zingolabs · ala-mode · Aug 13, 2025 · Aug 14, 2025 · Aug 14, 2025 · Aug 14, 2025
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
@@ -1,3 +1,4 @@
 [toolchain]
-channel = "stable"
+#channel = "stable"
+channel = "1.88.0"
 components = ["rustfmt", "clippy"]
diff --git a/zaino-fetch/src/jsonrpsee/connector.rs b/zaino-fetch/src/jsonrpsee/connector.rs
@@ -26,11 +26,11 @@ use crate::jsonrpsee::{
     error::{JsonRpcError, TransportError},
     response::{
         block_subsidy::GetBlockSubsidy, peer_info::GetPeerInfo, GetBalanceError,
-        GetBalanceResponse, GetBlockCountResponse, GetBlockError, GetBlockHash, GetBlockResponse,
-        GetBlockchainInfoResponse, GetInfoResponse, GetMempoolInfoResponse, GetSubtreesError,
-        GetSubtreesResponse, GetTransactionResponse, GetTreestateError, GetTreestateResponse,
-        GetUtxosError, GetUtxosResponse, SendTransactionError, SendTransactionResponse, TxidsError,
-        TxidsResponse,
+        GetBalanceResponse, GetBlockCountResponse, GetBlockError, GetBlockHash,
+        GetBlockHeaderResponse, GetBlockResponse, GetBlockchainInfoResponse, GetInfoResponse,
+        GetMempoolInfoResponse, GetSubtreesError, GetSubtreesResponse, GetTransactionResponse,
+        GetTreestateError, GetTreestateResponse, GetUtxosError, GetUtxosResponse,
+        SendTransactionError, SendTransactionResponse, TxidsError, TxidsResponse,
     },
 };
 
@@ -420,6 +420,18 @@ impl JsonRpSeeConnector {
             .await
     }
 
+    /// from online zcashd RPC reference docs:
+    /// getblockheader 'hash' ( verbose )
+    ///
+    /// If verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.
+    /// If verbose is true, returns an Object with information about blockheader <hash>.
+    pub async fn get_block_header(
+        &self,
+    ) -> Result<GetBlockHeaderResponse, RpcRequestError<Infallible>> {
+        // do something
+        unreachable!("so far");
+    }
+
     /// Returns details on the active state of the TX memory pool.
     ///
     /// online zcash rpc reference: [`getmempoolinfo`](https://zcash.github.io/rpc/getmempoolinfo.html)

diff --git a/zaino-fetch/src/jsonrpsee/response.rs b/zaino-fetch/src/jsonrpsee/response.rs
@@ -1526,3 +1526,140 @@ pub struct GetMempoolInfoResponse {
 impl ResponseToError for GetMempoolInfoResponse {
     type RpcError = Infallible;
 }
+
+/// The Zcash source code is considered canonical:
+///
+/// block.cpp and block.h define the core data structures for blocks and their serialization, validation, and header logic
+/// within `class CBlockHeader` the first two lines are enums and do not represent fields:
+/// https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/primitives/block.h#L30
+/// The HEADER_SIZE enum defines the constant byte size of a block header,
+/// while CURRENT_VERSION specifies the default version number used for newly created blocks.
+/// The fields begin on this line:
+/// https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/primitives/block.h#L32
+///   int32_t nVersion;
+///   uint256 hashPrevBlock;
+///   uint256 hashMerkleRoot;
+///   uint256 hashBlockCommitments;
+///   uint32_t nTime;
+///   uint32_t nBits;
+///   uint256 nNonce;
+///   std::vector<unsigned char> nSolution;
+///
+/// SetNull() is used to clear field values:
+/// https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/primitives/block.h#L60
+/// Cblock represents a full block, and inherits from CBlockHeader:
+/// <https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/primitives/block.h#L121>
+///
+/// chain.cpp and .h represent the state of the blockchain: structure, indexing, and chain selection
+/// The function does not modify the state of the object: it is called on `const`,
+/// with a return type defined as CBlockHeader in chain.h file:
+/// <https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/chain.h#L449>
+/// <https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/chain.h#L643>
+/// CBlockHeader GetBlockHeader() const
+///    {
+///        CBlockHeader header;
+///        header.nVersion             = nVersion;
+///        header.hashPrevBlock        = hashPrev;
+///        header.hashMerkleRoot       = hashMerkleRoot;
+///        header.hashBlockCommitments = hashBlockCommitments;
+///        header.nTime                = nTime;
+///        header.nBits                = nBits;
+///        header.nNonce               = nNonce;
+///        header.nSolution            = nSolution;
+///        return header;
+///    }
+/// matching what's above.
+/// see also
+/// [chain.cpp link](https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/chain.cpp#L82)
+///
+// TODO: compare Chain.cpp, Block.cpp and the online RPC docs.
+/// https://zcash.github.io/rpc/getblockheader.html <verbose=true>:
+/// --has these return fields documented that overlap with the C++ code:
+/// version.
+/// merkleroot.
+/// time.
+/// bits.
+/// nonce.
+/// prev. block hash.
+/// --and these that do not:
+/// hash (same as provided RPC argument)
+/// confirmations (confirmations but only on best-chain, else -1)
+/// height
+/// finalsaplingroot (The root of the Sapling commitment tree after applying this block): see comment on hashBlockCommitments below.
+/// difficulty ("x.xxx" - floating point)
+/// next block hash
+/// --leaving these in the C++ code unreported in the online docs:
+/// nSolution
+/// hashBlockCommitments (thought to be an aggregate including the merkleroot, and finalsapling root )
+///
+/// hashBlockCommitments = Merkle roots of transaction commitments, including transparent and shielded ones — into a single value that is effectively committed to by the block.
+/// maybe kind of hashsum for all tx in block.
+///
+/// A real return using `zcash-cli` from zcashd 6.3.0 running on mainnet:
+/// getblockheader 000003f9071a74cd0a1f7dba0614cd3dbd38b8afa401849c41a624c6a7b919a3
+/// {
+///   "hash": "000003f9071a74cd0a1f7dba0614cd3dbd38b8afa401849c41a624c6a7b919a3",
+///   "confirmations": 1151,
+///   "height": 304,
+///   "version": 4,
+///   "merkleroot": "670da2a6b2b7bcfce573b21edf8432863f5bf33eb904b0450ae4023a38ef8f70",
+///   "finalsaplingroot": "0000000000000000000000000000000000000000000000000000000000000000",
+///   "time": 1477673429,
+///   "nonce": "0000cf5e461e3ed275a3dffecca8ace6c147bd6bcaa6692ad87d29f5aa1d0000",
+///   "solution": "00c886a0b5c5853129ec616a66f0686d1656f9e7e02efa3ff27814cea191134a213b5774629c8e7ae3491eab5bee00f5f5b7d726027974c0edd91de72ac07f2d795feea493070b8b46d6e223f15596f402f87ebe056d6934c7037beaef55219d9c3e770a90913f4cf3187cf606c68bc1e1fb0b030c846e63e90d6a8a74e11a12e32667985829267d61f61fa3c49cb6edbc841e2f54eeaa069fd135eee6e3a256bdc0915b2e9b5e92025954d35a89f2cf8ef1637161ddd719c8d3bb6cd14a014ce3f9345925edf705593c35a4530d553c6cb814eb940a0f874de5da31c2d566b10675a2ac7337981c921355aecbae62abee979458724485eeb850b2530365dc2ca08ac2f8a7ac13e33fd7f82a55fcd4d842175e649848869e250a70c630f5604492216cdb366a10e717201957153f21df41bc97be7538d9e2da1f33172b33b9ee8a6704f21b03c0c0a0da11040f690f6600dc0fec2bc0d55ddf54e5c4b673414d854411fba40f805d4ac4ac88cf99d7c2b017b194eba7bc9dfa4f0e8a0e267e6424534133e240194d9f254b32d9c7e51b3a838981e89779b58185bab0def9c2e50ab8f38e024f25adefaebd5b944e854a07d48a6201ce34cff5125aa09784a404e1b3be66a5916bf4adafe4560aa6260bde0d8a560b5f7e3f82a1616f39497b34924179482f8afcde1cf343160ba74182e645de969d15becb0701f7ef0a54070afd74c64c63d655e9f52b5432cf33295ce70b0e5c7935202539b87ede4b4ad89b56bd23e62476649ef9b10b2bd92baa63d62a57e7b5b472300ccb5e0bdf731fb9e0e8ca1fd919fe67001d0abc115d593476cb7424f1a283bced761c20f393493ef0376324f752a7eb6b871125e04378344d84e74cef562e4c45b098cf5c8f68f5c3d857affa5bbd591e78cd318d29f3af1afbc7788f23ae8164cf39ff04748ff600d525ff32084c14fd817b89cc79d7379cf3fdb2a00228a1b8bb2df2e7e277c357feba972566ba2cdc971329aba7132054b5168ee132b131633af3e079f1514115d719f163ab9d3b7db58a993db1f995d1f10f990195a396b612210d8e0bf15424af0a74bcc9cd367a0ee2df0d6f7f6419fe8ca1e86f7451f95bb3f3676526bfd1a802570aa8d85e177d013cca82fc3579244a39e0b425bc96f0ebdbe0b59a65428a4db0cdf8f05b04180d39fb2bc95bdacf3207362048b66d74f93f60079778e2ffaf6dcbb53c880abd4648c28e7857e06c0f89b10d63adc5a9bbace110ae71d6ce746a1dc5c31b219b2cfd19ed88fa69238e4ba4cae6787c749e85046d8d3a04387d65e927c25dd5160b29774b96d8bd25d542221e0c8fdb38f062a3913abc8165e1eb96c405be5d2d4594ab2bcbe6725af82fe3f9f8adbd3f5d5caf33d5939e19ef2a0526f8ccb9c8fe1cfb5652a404f8f04682ce5a4334af2bef30f247978702dc38ae206db5c783e76d53bb85343bd925315d81382e18f11d5479b5254d818b6bf8f6c68fb9879a9b63fcbfb042711b4c372a8e23fd62d87cfee662fa51f0dce80d0ddc91503fdb029334c1b66929d5525a84f534700c38c00e14aad4949f687687aff2feab223712b6f002153967f0281ae9f5a40ce2b55b458b6aac65fd88702c70f4b070b01bc996d2b43a09d4a6466a7234cba405387387e25c4027e9aa409868d2ed627b429e70ff06020198ea5c5bcd61a8010784d49314f60d9fac24086c8c8b6824cdc7e433b9121cffc7fe80ac1d82331491de5cab0f8178ef76140ddaba6fc98a35b5bcaf0c8bfdab520fb807ea6377b1f8edfada6163f95e7714a078e1fe4d11d8e922c17cfa5bd219ecbc392e131bb4158b6c2a0ff16bb462fdf3f576116bc8f335f939d2ae0ca4ad72d39e4c5a93a97920db264f7e67fd",
+///   "bits": "1e085354",
+///   "difficulty": 245.990748139731,
+///   "chainwork": "0000000000000000000000000000000000000000000000000000000006659ef3",
+///   "previousblockhash": "000001b5ad3057566497fa4cf1ad5519fa6a39acb0cd249aa23ca7d3b2ebd8f5",
+///   "nextblockhash": "0000064be84052d3a4cda52592db6a61cd4cb127e34cd42404bba18d870b1aaa"
+/// }
+///
+/// this includes all the fields in the online RPC docs, as well as:
+/// solution (visble to me in C++ code)
+/// chainwork (not seen yet)
+/// ... according to https://zcash.github.io/rpc/getblockchaininfo.html
+///  "chainwork": "xxxx"     (string) total amount of work in active chain, in hexadecimal
+/// this number does increment during chain sync with `getblockchaininfo`,
+/// also present in getblockdeltas documentation - but I can confirm the zcash-cli RPC call is not functioning, at least in the same way.
+///  but is a set amount when using getblockheader <hash>
+/// therefore I think it is likely to be able to be found in the block, somehow.
+/// https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/rpc/blockchain.cpp#L126
+/// https://github.com/zcash/zcash/blob/b65b008a7b334a2f7c2eaae1b028e011f2e21dd1/src/rpc/blockchain.cpp#L268 :
+///  result.pushKV("chainwork", blockindex->nChainWork.GetHex());
+///
+/// however, zcash-cli when backed by zebrad 2.5.0 does NOT return chainwork and DOES return blockcommitments
+/// (though my example with unsynced zebra was all 000s):
+/// getblockheader 000003f9071a74cd0a1f7dba0614cd3dbd38b8afa401849c41a624c6a7b919a3
+/// {
+///   "hash": "000003f9071a74cd0a1f7dba0614cd3dbd38b8afa401849c41a624c6a7b919a3",
+///   "confirmations": 1848585,
+///   "height": 304,
+///   "version": 4,
+///   "merkleroot": "670da2a6b2b7bcfce573b21edf8432863f5bf33eb904b0450ae4023a38ef8f70",
+///   "blockcommitments": "0000000000000000000000000000000000000000000000000000000000000000",
+///   "finalsaplingroot": "0000000000000000000000000000000000000000000000000000000000000000",
+///   "time": 1477673429,
+///   "nonce": "0000cf5e461e3ed275a3dffecca8ace6c147bd6bcaa6692ad87d29f5aa1d0000",
+///   "solution": "00c886a0b5c5853129ec616a66f0686d1656f9e7e02efa3ff27814cea191134a213b5774629c8e7ae3491eab5bee00f5f5b7d726027974c0edd91de72ac07f2d795feea493070b8b46d6e223f15596f402f87ebe056d6934c7037beaef55219d9c3e770a90913f4cf3187cf606c68bc1e1fb0b030c846e63e90d6a8a74e11a12e32667985829267d61f61fa3c49cb6edbc841e2f54eeaa069fd135eee6e3a256bdc0915b2e9b5e92025954d35a89f2cf8ef1637161ddd719c8d3bb6cd14a014ce3f9345925edf705593c35a4530d553c6cb814eb940a0f874de5da31c2d566b10675a2ac7337981c921355aecbae62abee979458724485eeb850b2530365dc2ca08ac2f8a7ac13e33fd7f82a55fcd4d842175e649848869e250a70c630f5604492216cdb366a10e717201957153f21df41bc97be7538d9e2da1f33172b33b9ee8a6704f21b03c0c0a0da11040f690f6600dc0fec2bc0d55ddf54e5c4b673414d854411fba40f805d4ac4ac88cf99d7c2b017b194eba7bc9dfa4f0e8a0e267e6424534133e240194d9f254b32d9c7e51b3a838981e89779b58185bab0def9c2e50ab8f38e024f25adefaebd5b944e854a07d48a6201ce34cff5125aa09784a404e1b3be66a5916bf4adafe4560aa6260bde0d8a560b5f7e3f82a1616f39497b34924179482f8afcde1cf343160ba74182e645de969d15becb0701f7ef0a54070afd74c64c63d655e9f52b5432cf33295ce70b0e5c7935202539b87ede4b4ad89b56bd23e62476649ef9b10b2bd92baa63d62a57e7b5b472300ccb5e0bdf731fb9e0e8ca1fd919fe67001d0abc115d593476cb7424f1a283bced761c20f393493ef0376324f752a7eb6b871125e04378344d84e74cef562e4c45b098cf5c8f68f5c3d857affa5bbd591e78cd318d29f3af1afbc7788f23ae8164cf39ff04748ff600d525ff32084c14fd817b89cc79d7379cf3fdb2a00228a1b8bb2df2e7e277c357feba972566ba2cdc971329aba7132054b5168ee132b131633af3e079f1514115d719f163ab9d3b7db58a993db1f995d1f10f990195a396b612210d8e0bf15424af0a74bcc9cd367a0ee2df0d6f7f6419fe8ca1e86f7451f95bb3f3676526bfd1a802570aa8d85e177d013cca82fc3579244a39e0b425bc96f0ebdbe0b59a65428a4db0cdf8f05b04180d39fb2bc95bdacf3207362048b66d74f93f60079778e2ffaf6dcbb53c880abd4648c28e7857e06c0f89b10d63adc5a9bbace110ae71d6ce746a1dc5c31b219b2cfd19ed88fa69238e4ba4cae6787c749e85046d8d3a04387d65e927c25dd5160b29774b96d8bd25d542221e0c8fdb38f062a3913abc8165e1eb96c405be5d2d4594ab2bcbe6725af82fe3f9f8adbd3f5d5caf33d5939e19ef2a0526f8ccb9c8fe1cfb5652a404f8f04682ce5a4334af2bef30f247978702dc38ae206db5c783e76d53bb85343bd925315d81382e18f11d5479b5254d818b6bf8f6c68fb9879a9b63fcbfb042711b4c372a8e23fd62d87cfee662fa51f0dce80d0ddc91503fdb029334c1b66929d5525a84f534700c38c00e14aad4949f687687aff2feab223712b6f002153967f0281ae9f5a40ce2b55b458b6aac65fd88702c70f4b070b01bc996d2b43a09d4a6466a7234cba405387387e25c4027e9aa409868d2ed627b429e70ff06020198ea5c5bcd61a8010784d49314f60d9fac24086c8c8b6824cdc7e433b9121cffc7fe80ac1d82331491de5cab0f8178ef76140ddaba6fc98a35b5bcaf0c8bfdab520fb807ea6377b1f8edfada6163f95e7714a078e1fe4d11d8e922c17cfa5bd219ecbc392e131bb4158b6c2a0ff16bb462fdf3f576116bc8f335f939d2ae0ca4ad72d39e4c5a93a97920db264f7e67fd",
+///   "bits": "1e085354",
+///   "difficulty": 245.99074813973095,
+///   "previousblockhash": "000001b5ad3057566497fa4cf1ad5519fa6a39acb0cd249aa23ca7d3b2ebd8f5",
+///   "nextblockhash": "0000064be84052d3a4cda52592db6a61cd4cb127e34cd42404bba18d870b1aaa"
+/// }
+
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct GetBlockHeaderResponse {
+    // fields taken from zcashd source code pasted above
+    version: (),                // int32_t number
+    hash_previous_block: (),    // uint256 hash
+    hash_merkle_root: (),       // uint256 hash
+    hash_block_commitments: (), // uint256 hash
+    time: (),                   // uint32_t number
+    bits: (),                   // uint32_t number
+    nonce: (),                  // uint256 number
+    solution: (), // vec<unsigned char> (char in C++ often represents raw bytes, and nSolution appears to mean 'number used once' or a misapplied convention.)
+}
+
+impl ResponseToError for GetBlockHeaderResponse {
+    type RpcError = Infallible;
+}
diff --git a/zaino-state/src/backends/fetch.rs b/zaino-state/src/backends/fetch.rs
@@ -23,9 +23,8 @@
     jsonrpsee::{
         connector::{JsonRpSeeConnector, RpcError},
         response::{
-            block_subsidy::GetBlockSubsidy,
-            peer_info::GetPeerInfo,
-            {GetMempoolInfoResponse, GetNetworkSolPsResponse},
+            block_subsidy::GetBlockSubsidy, peer_info::GetPeerInfo, GetBlockHeaderResponse,
+            GetMempoolInfoResponse, GetNetworkSolPsResponse,
         },
     },
 };
@@ -197,8 +196,8 @@
    }
 }

 #[async_trait]
 impl ZcashIndexer for FetchServiceSubscriber {
    type Error = FetchServiceError;

    /// Returns software information from the RPC server, as a [`GetInfo`] JSON struct.
@@ -216,6 +215,42 @@
         Ok(self.fetcher.get_info().await?.into())
     }
 
+    /// getblockheader 'hash' ( verbose )
+    /// If verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.
+    /// If verbose is true, returns an Object with information about blockheader 'hash'.
+    ///
+    /// online zcashd reference: [`getblockheader`](https://zcash.github.io/rpc/getblockheader.html)
+    /// method: post
+    /// tags: blockchain
+    // TODO params are only demos
+    async fn get_block_header(
+        &self,
+        _hash_or_height_demo: HashOrHeight,
+        _verbose: Option<bool>,
+    ) -> Result<GetBlockHeaderResponse, Self::Error> {
+        Ok(self.fetcher.get_block_header().await?)
+    }
+
+    /// getblockheader 'hash' ( verbose )
+    /// If verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.
+    /// If verbose is true, returns an Object with information about blockheader 'hash'.
+    ///
+    /// online zcashd reference: [`getblockheader`](https://zcash.github.io/rpc/getblockheader.html)
+    /// method: post
+    /// tags: blockchain
+    // TODO params are only demos
+    /*
+    async fn get_block_header_static(
+        _: _,
+        _: _,
+        _hash_or_height_demo: HashOrHeight,
+        _verbose: Option<bool>,
+    ) -> Result<GetBlockHeaderResponse, Self::Error> {
+        unreachable!("so far");
+        //Ok(self.fetcher.get_block_header().await?)
+    }
+    */
+
     /// Returns blockchain state information, as a [`GetBlockchainInfoResponse`] JSON struct.
     ///
     /// zcashd reference: [`getblockchaininfo`](https://zcash.github.io/rpc/getblockchaininfo.html)