feat(rpc): add verifyutxochaintipinclusionproof RPC method by bc1cindy · Pull Request #819 · getfloresta/Floresta

bc1cindy · 2026-01-30T20:11:45Z

Hey guys, I talked to Davidson and we agreed I'd implement this RPC.

This PR implements the verifyutxochaintipinclusionproof RPC method to verify utreexo accumulator proofs for chain tip UTXOs. It's based on the utreexod's reference implementation and allows clients to cryptographically verify UTXO inclusion without maintaining the full UTXO set.

Parses hex-encoded proofs from utreexod's proveutxochaintipinclusion RPC
Validates proof was generated at current chain tip (rejects stale proofs with clear error)
Creates a temporary pollard from the current accumulator roots using Pollard::from_roots()
Uses pollard.verify() to cryptographically verify inclusion by reconstructing the merkle path from proven hashes through the provided proof hashes up to the known roots
Returns true for valid proofs, false for invalid proofs and errors for malformed input.

Running:

RPC: ./target/release/floresta-cli --network regtest verifyutxochaintipinclusionproof <proof>

Test: uv run tests/test_runner.py -k verifyutxochaintipinclusionproof

Tested with proofs generated from utreexod proveutxochaintipinclusion RPC in regtest mode.

moisesPompilio

Can the name of this RPC be shorter, like verifyutxoproof?

Davidson-Souza · 2026-01-30T21:19:04Z

Can the name of this RPC be shorter, like verifyutxoproof?

This is the RPC's name on utreexod

bc1cindy · 2026-02-01T00:01:02Z

thanks for the review! @moisesPompilio

done!

bc1cindy · 2026-02-01T23:11:33Z

thanks for the review! @csgui

initially, I chose to remain faithful to the utreexod RPC implementation, but the validation of the proof size is important and it doesn't exist in utreexod, as well as explicit error handling, but all done now. Also added a test for the proof size.

furthermore, I realized that pollard::from_roots received 4 roots but internally only preserved 2, and this was causing errors in the verification of some proofs, so I switched to stump.verify, which is working well.

bc1cindy · 2026-02-03T15:08:40Z

thanks guys!

addressed all feedback : added InvalidProof error variant for stale/verification failures, bounds checking with read_bounded_len / MAX_INPUTS_PER_BLOCK/MAX_PROOF_HASHES, updated docs, trailing bytes check, and expanded tests with utreexod integration (utreexod running locally, it requires bdkwallet support)

ready for re-review! @moisesPompilio @csgui

moisesPompilio

For now we don't use simple assert statements in the integration tests; we have to use the asserts from FlorestaTestFramework. I marked some asserts and suggested how they should use the FlorestaTestFramework asserts, but check FlorestaTestFramework for which ones you need to use instead of the simple assert calls you added.

bc1cindy · 2026-02-06T16:11:30Z

hey @moisesPompilio

I improved the test as a full integration using the existing frameworks. Utreexod is instantiated via add_node() (no external dependency), coinbase txids are obtained via getblock/getblockhash (no bdkwallet), and shutil.rmtree cleans up data between runs. It runs on CI without manual setup.

bc1cindy · 2026-02-06T19:32:51Z

applied CI lint fix

bc1cindy · 2026-02-06T21:26:42Z

thanks! @moisesPompilio

sugestions applied

bc1cindy · 2026-02-06T23:03:45Z

updated commit descriptions

bc1cindy · 2026-02-11T00:33:40Z

extracted ChainTipInclusionProof struct with Decodable impl into block_proof.rs and added 3 unit tests

updated integration test bash tests/run.sh -k verifyutxochaintipinclusionproof

bc1cindy · 2026-02-11T03:46:26Z

verbosity added

thanks! @jaoleal

jaoleal

Just a few more suggestions but everything looks fine already

bc1cindy · 2026-02-13T01:50:50Z

I moved the struct to floresta-node/src/json_rpc/chain_tip_proof.rs, extracted a generic decode_hex_blob<T: Decodable> helper that also lives there, where the type is available and duplicated the decoding consts (MAX_INPUTS_PER_BLOCK, MAX_TREE_DEPTH, MAX_PROOF_HASHES) to avoid coupling with floresta-wire.

also created VerifyChainTipProofRes and VerifyChainTipProofVerbose in res.rs to replace the inline json!(), following the GetBlockRes pattern.

this matches how utreexod handlesverifyutxochaintipinclusionproof, that also takes a raw hex string.

bc1cindy · 2026-02-14T11:39:25Z

I moved the struct to floresta-node/src/json_rpc/chain_tip_proof.rs, extracted a generic decode_hex_blob<T: Decodable> helper that also lives there, where the type is available and duplicated the decoding consts (MAX_INPUTS_PER_BLOCK, MAX_TREE_DEPTH, MAX_PROOF_HASHES) to avoid coupling with floresta-wire.

also created VerifyChainTipProofRes and VerifyChainTipProofVerbose in res.rs to replace the inline json!(), following the GetBlockRes pattern.

this matches how utreexod handlesverifyutxochaintipinclusionproof, that also takes a raw hex string.

I chose floresta-node because floresta-rpc doesn't depend on rustreexo.

regarding JSON object parsing, to accept the proof as a JSON object, I'd need to add features = ["with-serde"] to rustreexo in floresta-node so Proof and BitcoinNodeHash can derive Deserialize, as both are gated behind #[cfg_attr(feature = "with-serde", derive(Serialize, Deserialize))].

not sure it's worth it since utreexod also just takes a raw hex string, and I don't know if that format would see much use.

happy to add, if you think it's the right direction though

jaoleal · 2026-02-14T14:43:13Z

IMHO its important to keep efforts to maintain the idiomaticity and strong structure of the project because of some rust 101 principles but I agree to skip this to not over complicate the PR.

WYT about opening a follow-up issue: "Strong typing for verifyutxoproof method" ?

not sure it's worth it since utreexod also just takes a raw hex string, and I don't know if that format would see much use.

I consider it to be worth some time exactly because its far more convenient and intuitive to understand the meaning of data when working on it, specially considering that ChainTipInclusionProof contains data thats really useful and probably will be used elsewhere too further in floresta. Besides, its an opportunity to improve another method UX.

Davidson-Souza · 2026-02-17T18:01:12Z

extracted a generic decode_hex_blob<T: Decodable> helper that also lives there

rust-bitcoin has a deserialize_hex method, won't they do the same?

not sure it's worth it since utreexod also just takes a raw hex string, and I don't know if that format would see much use.

Since that's what utreexod does, I think it's fine to do that. Accepting both would be too much IMO

Davidson-Souza · 2026-02-17T18:03:12Z

Also,

duplicated the decoding consts (MAX_INPUTS_PER_BLOCK, MAX_TREE_DEPTH, MAX_PROOF_HASHES) to avoid coupling with floresta-wire

floresta-node already depends on floresta-wire, so I don't think you would be "coupling" them

csgui

Left some comments about proper error handling on unwrap

Implements utreexo accumulator proof UTXO verification for chain tip, based on the utreexod's reference implementation. This allows clients to cryptographically verify UTXO inclusion without maintaining the full UTXO set. - Parses hex-encoded proofs from utreexod's proveutxochaintipinclusion - Validates proof was generated at current chain tip (rejects stale proofs) - Verifies cryptographic proof against the accumulator state - Makes MAX_INPUTS_PER_BLOCK and MAX_PROOF_HASHES public for DoS bounds - Adds InvalidProof error variant with appropriate HTTP/JSON-RPC codes Returns true for valid proofs, false for well-formed but invalid proofs. Malformed or stale proofs return specific error types.

bc1cindy · 2026-02-18T17:24:22Z

extracted a generic decode_hex_blob<T: Decodable> helper that also lives there

rust-bitcoin has a deserialize_hex method, won't they do the same?

nice, it's the same, I didn't know about it, thanks!

changes applied

Adds CLI command to verify utreexo proofs, making the RPC accessible via floresta-cli. Includes comprehensive documentation with usage examples showing both valid and invalid proof scenarios to help users understand expected behavior.

End-to-end test using florestad and utreexod that validates: - Input rejection: invalid hex, oversized proofs, empty input, truncated data - Valid proofs: generates and verifies proofs for all mined coinbase UTXOs - Invalid proofs: tampered data returns false, trailing bytes and wrong block hash return appropriate errors Also adds RPC bindings for both floresta (verifyutxochaintipinclusionproof) and utreexo (proveutxochaintipinclusion) in the test framework.

jaoleal · 2026-04-15T12:48:27Z

+/// Max hex-encoded proof size (DoS protection).
+/// 4MB based on MAX_INPUTS_PER_BLOCK (24,386) with safety margin.
+const MAX_PROOF_SIZE_BYTES: usize = 4 * 1024 * 1024;


Nit: is this the best place for this ?

jaoleal · 2026-04-15T12:49:41Z

+        let valid = match stump.verify(&tip_proof.proof, &tip_proof.hashes_proven) {
+            Ok(valid) => valid,
+            Err(e) => {
+                return Err(JsonRpcError::InvalidProof(format!(
+                    "Proof verification failed: {}",
+                    e
+                )))
+            }
+        };


This can be better written with a map_err

jaoleal · 2026-04-15T12:50:56Z

@@ -0,0 +1,126 @@
+//! Chain-tip inclusion proofs for the Utreexo accumulator.


Suggested change

//! Chain-tip inclusion proofs for the Utreexo accumulator.

// SPDX-License-Identifier: MIT OR Apache-2.0

//! Chain-tip inclusion proofs for the Utreexo accumulator.

jaoleal · 2026-04-15T13:12:14Z

+    /// The block hash at which this proof was generated.
+    pub proved_at_hash: BlockHash,
+    /// The Utreexo accumulator proof (targets + sibling hashes).
+    pub proof: Proof,
+    /// The raw leaf hashes that were proven.
+    pub hashes_proven: Vec<BitcoinNodeHash>,
+}


Suggested change

/// The block hash at which this proof was generated.

pub proved_at_hash: BlockHash,

/// The Utreexo accumulator proof (targets + sibling hashes).

pub proof: Proof,

/// The raw leaf hashes that were proven.

pub hashes_proven: Vec<BitcoinNodeHash>,

}

/// The block hash at which this proof was generated.

pub proved_at_hash: BlockHash,

/// The Utreexo accumulator proof (targets + sibling hashes).

pub proof: Proof,

/// The raw leaf hashes that were proven.

pub hashes_proven: Vec<BitcoinNodeHash>,

}

jaoleal · 2026-04-15T13:13:31Z

+#[derive(Debug, Serialize)]
+pub struct VerifyChainTipProofVerbose {
+    pub valid: bool,
+
+    pub proved_at_hash: String,
+
+    pub targets: Vec<u64>,
+
+    pub num_proof_hashes: usize,
+
+    pub proof_hashes: Vec<String>,
+
+    pub hashes_proven: Vec<String>,
+}
+


docs for this struct

jaoleal · 2026-04-15T13:20:21Z

+        params = [proof]
+        if verbosity is not None:
+            params.append(verbosity)
+        return self.perform_request("verifyutxochaintipinclusionproof", params)


Suggested change

params = [proof]

if verbosity is not None:

params.append(verbosity)

return self.perform_request("verifyutxochaintipinclusionproof", params)

return self.perform_request("verifyutxochaintipinclusionproof", [proof, verbosity])

jaoleal · 2026-04-15T13:20:29Z

        return self.perform_request("getmemoryinfo", params=[mode])
+
+    def verifyutxochaintipinclusionproof(
+        self, proof: str, verbosity: int = None


Suggested change

self, proof: str, verbosity: int = None

self, proof: str, verbosity: int = 0

jaoleal · 2026-04-15T13:24:35Z

+        match verbosity {
+            Some(v) => self.call(
+                "verifyutxochaintipinclusionproof",
+                &[Value::String(proof), Value::Number(Number::from(v))],
+            ),
+            None => self.call("verifyutxochaintipinclusionproof", &[Value::String(proof)]),
+        }


Suggested change

match verbosity {

Some(v) => self.call(

"verifyutxochaintipinclusionproof",

&[Value::String(proof), Value::Number(Number::from(v))],

),

None => self.call("verifyutxochaintipinclusionproof", &[Value::String(proof)]),

}

self.call(

"verifyutxochaintipinclusionproof",

&[Value::String(proof), Value::Number(Number::from(verbosity.unwrap_or(0)))],

)

jaoleal · 2026-04-15T13:30:27Z

+pub enum VerifyChainTipProofRes {
+    /// Verbosity 0: true/false
+    Bool(bool),
+
+    /// Verbosity 1: detailed proof info
+    Verbose(VerifyChainTipProofVerbose),
+}


Suggested change

pub enum VerifyChainTipProofRes {

/// Verbosity 0: true/false

Bool(bool),

/// Verbosity 1: detailed proof info

Verbose(VerifyChainTipProofVerbose),

}

/// Holds structured response for the verifychaintipproof rpc command by its verbosity level.

pub enum VerifyChainTipProofRes {

/// Verbosity 0: true/false

Zero(bool),

/// Verbosity 1: detailed proof info

One(VerifyChainTipProofVerbose),

}

bc1cindy marked this pull request as ready for review January 30, 2026 20:12

moisesPompilio reviewed Jan 30, 2026

View reviewed changes

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

Comment thread tests/test_framework/rpc/floresta.py Outdated

Comment thread doc/rpc/verifyutxochaintipinclusionproof.md Outdated

moisesPompilio assigned bc1cindy Jan 30, 2026

moisesPompilio added enhancement New feature or request new rpc This issue/PR implements a new json-rpc endpoint documentation Improvements or additions to documentation Integration Issues related to our integration tests labels Jan 30, 2026

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from 6c51864 to 04fbc6e Compare January 31, 2026 23:55

csgui requested changes Feb 1, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 04fbc6e to f977dbc Compare February 1, 2026 22:53

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from 04435ee to 882aec3 Compare February 1, 2026 23:43

csgui requested changes Feb 2, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

moisesPompilio reviewed Feb 2, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from 8e354d2 to 93274ab Compare February 3, 2026 14:56

csgui reviewed Feb 3, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 93274ab to 8e2deea Compare February 3, 2026 16:14

moisesPompilio reviewed Feb 3, 2026

View reviewed changes

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 3 times, most recently from 73ca04f to 79589d2 Compare February 6, 2026 16:06

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 79589d2 to 1a23b57 Compare February 6, 2026 19:28

moisesPompilio reviewed Feb 6, 2026

View reviewed changes

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 1a23b57 to f573885 Compare February 6, 2026 21:24

moisesPompilio reviewed Feb 6, 2026

View reviewed changes

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

Comment thread tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from ff1081d to 0fdd2e0 Compare February 6, 2026 23:02

Davidson-Souza reviewed Feb 7, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from 8d469cd to 7fc11ea Compare February 11, 2026 00:17

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch 2 times, most recently from 139aaa5 to e7f3f40 Compare February 11, 2026 03:39

jaoleal reviewed Feb 11, 2026

View reviewed changes

Comment thread crates/floresta-wire/src/p2p_wire/block_proof.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from e7f3f40 to e1ab794 Compare February 13, 2026 01:32

csgui reviewed Feb 17, 2026

View reviewed changes

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

Comment thread crates/floresta-node/src/json_rpc/blockchain.rs Outdated

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from e1ab794 to 15da2e1 Compare February 18, 2026 17:06

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 15da2e1 to 9d33279 Compare February 18, 2026 17:10

bc1cindy added 2 commits February 18, 2026 15:26

bc1cindy force-pushed the rpc/verifyutxochaintipinclusionproof branch from 9d33279 to 8ccc35f Compare February 18, 2026 18:32

jaoleal reviewed Apr 15, 2026

View reviewed changes

		@@ -0,0 +1,126 @@
		//! Chain-tip inclusion proofs for the Utreexo accumulator.

	self, proof: str, verbosity: int = None
	self, proof: str, verbosity: int = 0

Conversation

bc1cindy commented Jan 30, 2026

Uh oh!

moisesPompilio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Davidson-Souza commented Jan 30, 2026

Uh oh!

bc1cindy commented Feb 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 3, 2026

Uh oh!

Uh oh!

moisesPompilio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 6, 2026

Uh oh!

bc1cindy commented Feb 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 6, 2026

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 6, 2026

Uh oh!

Uh oh!

bc1cindy commented Feb 11, 2026

Uh oh!

bc1cindy commented Feb 11, 2026

Uh oh!

jaoleal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 13, 2026

Uh oh!

bc1cindy commented Feb 14, 2026

Uh oh!

jaoleal commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Davidson-Souza commented Feb 17, 2026

Uh oh!

Davidson-Souza commented Feb 17, 2026

Uh oh!

csgui left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bc1cindy commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jaoleal commented Feb 14, 2026 •

edited

Loading

bc1cindy commented Feb 18, 2026 •

edited

Loading