Transparent address history feature

integration-tests/Cargo.toml

@@ -10,6 +10,20 @@ edition = { workspace = true }
 license = { workspace = true }
 version = { workspace = true }
 
+[features]
+# **Experimental and alpha features**
+# Exposes the **complete** set of experimental / alpha features currently implemented in Zaino.
+experimental_features = ["transparent_address_history_experimental"]
+
+# Activates transparent address history capability in zaino
+#
+# NOTE: currently this is only implemented in the finalised state.
+transparent_address_history_experimental = [
+    "zaino-state/transparent_address_history_experimental",
+    "zainod/transparent_address_history_experimental",
+    "zaino-testutils/transparent_address_history_experimental"
+]
+
 [dev-dependencies]
 anyhow = { workspace = true }
 

zaino-serve/Cargo.toml

@@ -9,9 +9,18 @@ license = { workspace = true }
 version = { workspace = true }
 
 [features]
-state_service = []
+# Removes network restrictions.
 no_tls_use_unencrypted_traffic = ["tonic/tls-roots"]
 
+# **Experimental and alpha features**
+# Exposes the **complete** set of experimental / alpha features currently implemented in Zaino.
+experimental_features = ["transparent_address_history_experimental"]
+
+# Activates transparent address history capability in zaino
+#
+# NOTE: currently this is only implemented in the finalised state.
+transparent_address_history_experimental = ["zaino-state/transparent_address_history_experimental"]
+
 [dependencies]
 zaino-proto = { workspace = true }
 zaino-fetch = { workspace = true }

zaino-state/Cargo.toml

@@ -9,9 +9,20 @@ license = { workspace = true }
 version = { workspace = true }
 
 [features]
+default = []
+
 # test_dependencies - Exposes internal functionality for testing.
 test_dependencies = []
 
+# **Experimental and alpha features**
+# Exposes the **complete** set of experimental / alpha features currently implemented in Zaino.
+experimental_features = ["transparent_address_history_experimental"]
+
+# Activates transparent address history capability in zaino
+#
+# NOTE: currently this is only implemented in the finalised state.
+transparent_address_history_experimental = []
+
 [dependencies]
 zaino-common = { workspace = true }
 zaino-fetch = { workspace = true }

zaino-state/src/chain_index/finalised_state/CHANGELOG.md

@@ -102,8 +102,7 @@ Migration
 Bug Fixes / Optimisations
 - Complete DB rework
 --------------------------------------------------------------------------------
-DB VERSION v1.1.0 (from v1.0.0)
-Date: 2026-01-27
+DB VERSION v1.0.0 (RC Bug Fixes)
 --------------------------------------------------------------------------------
 
 Summary
@@ -141,15 +140,6 @@ API / capabilities
     - CompactBlockExt::get_compact_block(height, pool_types: PoolTypeFilter) signature updated.
     - Compact block contents are now filtered by PoolTypeFilter, and may include transparent transaction data (vin/vout) when selected.
 
-Migration
-- Strategy: In-place (metadata-only).
-- Backfill: None.
-- Completion criteria:
-  - DbMetadata.version updated from 1.0.0 to 1.1.0.
-  - DbMetadata.migration_status reset to Empty.
-- Failure handling:
-  - Idempotent: re-running re-writes the same metadata; no partial state beyond metadata.
-
 Bug Fixes / Optimisations
 - Added safety check for idempotent DB writes
 - Updated 'fix_addr_hist_records_by_addr_and_index_blocking' to take and reuse an lmdb ro transaction, improving initial sync performance.

zaino-state/src/chain_index/finalised_state/capability.rs

@@ -78,15 +78,16 @@
 use core::fmt;
 
 use crate::{
-    chain_index::types::{AddrEventBytes, TransactionHash},
-    error::FinalisedStateError,
-    read_fixed_le, read_u32_le, read_u8, version, write_fixed_le, write_u32_le, write_u8,
-    AddrScript, BlockHash, BlockHeaderData, CommitmentTreeData, CompactBlockStream,
-    FixedEncodedLen, Height, IndexedBlock, OrchardCompactTx, OrchardTxList, Outpoint,
-    SaplingCompactTx, SaplingTxList, StatusType, TransparentCompactTx, TransparentTxList,
-    TxLocation, TxidList, ZainoVersionedSerde,
+    chain_index::types::TransactionHash, error::FinalisedStateError, read_fixed_le, read_u32_le,
+    read_u8, version, write_fixed_le, write_u32_le, write_u8, BlockHash, BlockHeaderData,
+    CommitmentTreeData, CompactBlockStream, FixedEncodedLen, Height, IndexedBlock,
+    OrchardCompactTx, OrchardTxList, SaplingCompactTx, SaplingTxList, StatusType,
+    TransparentCompactTx, TransparentTxList, TxLocation, TxidList, ZainoVersionedSerde,
 };
 
+#[cfg(feature = "transparent_address_history_experimental")]
+use crate::{chain_index::types::AddrEventBytes, AddrScript, Outpoint};
+
 use async_trait::async_trait;
 use bitflags::bitflags;
 use core2::io::{self, Read, Write};
@@ -151,6 +152,7 @@ bitflags! {
         const CHAIN_BLOCK_EXT       = 0b0100_0000;
 
         /// Backend implements [`TransparentHistExt`] (transparent address history indices).
+        #[cfg(feature = "transparent_address_history_experimental")]
         const TRANSPARENT_HIST_EXT  = 0b1000_0000;
     }
 }
@@ -162,14 +164,24 @@ impl Capability {
     /// sync with:
     /// - the latest on-disk schema (`DbV1` today, `DbV2` in the future),
     /// - and [`DbVersion::capability`] for that schema.
-    pub(crate) const LATEST: Capability = Capability::READ_CORE
-        .union(Capability::WRITE_CORE)
-        .union(Capability::BLOCK_CORE_EXT)
-        .union(Capability::BLOCK_TRANSPARENT_EXT)
-        .union(Capability::BLOCK_SHIELDED_EXT)
-        .union(Capability::COMPACT_BLOCK_EXT)
-        .union(Capability::CHAIN_BLOCK_EXT)
-        .union(Capability::TRANSPARENT_HIST_EXT);
+    pub(crate) const LATEST: Capability = {
+        let base = Capability::READ_CORE
+            .union(Capability::WRITE_CORE)
+            .union(Capability::BLOCK_CORE_EXT)
+            .union(Capability::BLOCK_TRANSPARENT_EXT)
+            .union(Capability::BLOCK_SHIELDED_EXT)
+            .union(Capability::COMPACT_BLOCK_EXT)
+            .union(Capability::CHAIN_BLOCK_EXT);
+
+        #[cfg(feature = "transparent_address_history_experimental")]
+        {
+            base.union(Capability::TRANSPARENT_HIST_EXT)
+        }
+        #[cfg(not(feature = "transparent_address_history_experimental"))]
+        {
+            base
+        }
+    };
 
     /// Returns `true` if `self` includes **all** bits from `other`.
     ///
@@ -212,6 +224,7 @@ pub(crate) enum CapabilityRequest {
     IndexedBlockExt,
 
     /// Request the [`TransparentHistExt`] extension surface.
+    #[cfg(feature = "transparent_address_history_experimental")]
     TransparentHistExt,
 }
 
@@ -231,6 +244,7 @@ impl CapabilityRequest {
             CapabilityRequest::BlockShieldedExt => Capability::BLOCK_SHIELDED_EXT,
             CapabilityRequest::CompactBlockExt => Capability::COMPACT_BLOCK_EXT,
             CapabilityRequest::IndexedBlockExt => Capability::CHAIN_BLOCK_EXT,
+            #[cfg(feature = "transparent_address_history_experimental")]
             CapabilityRequest::TransparentHistExt => Capability::TRANSPARENT_HIST_EXT,
         }
     }
@@ -249,6 +263,7 @@ impl CapabilityRequest {
             CapabilityRequest::BlockShieldedExt => "BLOCK_SHIELDED_EXT",
             CapabilityRequest::CompactBlockExt => "COMPACT_BLOCK_EXT",
             CapabilityRequest::IndexedBlockExt => "CHAIN_BLOCK_EXT",
+            #[cfg(feature = "transparent_address_history_experimental")]
             CapabilityRequest::TransparentHistExt => "TRANSPARENT_HIST_EXT",
         }
     }
@@ -452,15 +467,23 @@ impl DbVersion {
             }
 
             // V1: Adds chainblockv1 and transparent transaction history data.
-            (1, 0) | (1, 1) => {
-                Capability::READ_CORE
+            (1, 0) => {
+                let base = Capability::READ_CORE
                     | Capability::WRITE_CORE
                     | Capability::BLOCK_CORE_EXT
                     | Capability::BLOCK_TRANSPARENT_EXT
                     | Capability::BLOCK_SHIELDED_EXT
                     | Capability::COMPACT_BLOCK_EXT
-                    | Capability::CHAIN_BLOCK_EXT
-                    | Capability::TRANSPARENT_HIST_EXT
+                    | Capability::CHAIN_BLOCK_EXT;
+
+                #[cfg(feature = "transparent_address_history_experimental")]
+                {
+                    base | Capability::TRANSPARENT_HIST_EXT
+                }
+                #[cfg(not(feature = "transparent_address_history_experimental"))]
+                {
+                    base
+                }
             }
 
             // Unknown / unsupported
@@ -893,7 +916,8 @@ pub trait IndexedBlockExt: Send + Sync {
 ///
 /// Range semantics:
 /// - Methods that accept `start_height` and `end_height` interpret the range as inclusive:
-///   `[start_height, end_height]`.
+///   `[start_height, end_height]`
+#[cfg(feature = "transparent_address_history_experimental")]
 #[async_trait]
 pub trait TransparentHistExt: Send + Sync {
     /// Fetch all address history records for a given transparent address.

zaino-state/src/chain_index/finalised_state/db.rs

@@ -64,17 +64,20 @@ use crate::{
     chain_index::{
         finalised_state::capability::{
             BlockCoreExt, BlockShieldedExt, BlockTransparentExt, CompactBlockExt, DbCore,
-            DbMetadata, DbRead, DbWrite, IndexedBlockExt, TransparentHistExt,
+            DbMetadata, DbRead, DbWrite, IndexedBlockExt,
         },
         types::TransactionHash,
     },
     config::BlockCacheConfig,
     error::FinalisedStateError,
-    AddrScript, BlockHash, BlockHeaderData, CommitmentTreeData, CompactBlockStream, Height,
-    IndexedBlock, OrchardCompactTx, OrchardTxList, Outpoint, SaplingCompactTx, SaplingTxList,
-    StatusType, TransparentCompactTx, TransparentTxList, TxLocation, TxidList,
+    BlockHash, BlockHeaderData, CommitmentTreeData, CompactBlockStream, Height, IndexedBlock,
+    OrchardCompactTx, OrchardTxList, SaplingCompactTx, SaplingTxList, StatusType,
+    TransparentCompactTx, TransparentTxList, TxLocation, TxidList,
 };
 
+#[cfg(feature = "transparent_address_history_experimental")]
+use crate::{chain_index::finalised_state::capability::TransparentHistExt, AddrScript, Outpoint};
+
 use async_trait::async_trait;
 use std::time::Duration;
 use tokio::time::{interval, MissedTickBehavior};
@@ -529,6 +532,7 @@ impl IndexedBlockExt for DbBackend {
     }
 }
 
+#[cfg(feature = "transparent_address_history_experimental")]
 #[async_trait]
 impl TransparentHistExt for DbBackend {
     async fn addr_records(