feat(rpc): add verifyutxochaintipinclusionproof RPC method #819

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?

tests/floresta-cli/verifyutxochaintipinclusionproof.py

tests/test_framework/rpc/floresta.py

doc/rpc/verifyutxochaintipinclusionproof.md

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!

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

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.

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

tests/floresta-cli/verifyutxochaintipinclusionproof.py

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

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

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.

tests/floresta-cli/verifyutxochaintipinclusionproof.py

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

tests/floresta-cli/verifyutxochaintipinclusionproof.py

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

thanks! @moisesPompilio

sugestions applied

tests/floresta-cli/verifyutxochaintipinclusionproof.py

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

updated commit descriptions

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

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

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.

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.

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

verbosity added

thanks! @jaoleal

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

moisesPompilio reviewed Jan 30, 2026

View reviewed changes

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

tests/test_framework/rpc/floresta.py Outdated Show resolved Hide resolved

doc/rpc/verifyutxochaintipinclusionproof.md Outdated Show resolved Hide resolved

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 suggested changes Feb 1, 2026

View reviewed changes

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

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 suggested changes Feb 2, 2026

View reviewed changes

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

moisesPompilio reviewed Feb 2, 2026

View reviewed changes

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

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

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

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

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

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

tests/floresta-cli/verifyutxochaintipinclusionproof.py Outdated Show resolved Hide resolved

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

crates/floresta-node/src/json_rpc/blockchain.rs Outdated Show resolved Hide resolved

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 from 7fc11ea to 139aaa5 Compare February 11, 2026 03:26

bc1cindy added 2 commits February 11, 2026 00:35

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

feat(rpc): add verifyutxochaintipinclusionproof RPC method #819

Are you sure you want to change the base?

feat(rpc): add verifyutxochaintipinclusionproof RPC method #819

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants