Tests, not an audit. The repository says of its own fuzz and property tests: “A property that holds for every generated case is not a proof, and none of this is an audit.” No independent security audit or cryptographic review of the code has been done.
Tools in the repository. Everything on this page is run from a checkout, against generated input, fixtures or a local network. Nothing on this page is a result from the devnet.
Fuzz targets for the decoders
The native-payments crate decodes bytes that arrive from outside the node and keeps the state every payment changes. protocol/payments/tests/decoder_fuzz.rs holds one fuzz target for each decoder. Each target takes bytes and requires three things:
- the decoder does not panic;
- it accepts exactly the inputs that a reference statement of the format accepts, size bounds included;
- whatever it accepts encodes back to the same bytes.
The reference is in tests/support/reference.rs. It is written from the format, field by field, and shares no code with the decoders.
The targets, the decoder each one drives, and what else each one checks:
payment_decoderdriveswire::decodewith the three tags. A wrong size is always refused as a length error; another network is refused.payment_encoder_agrees_with_decoderdriveswire::encode. The encoder refuses every context the decoder refuses; an accepted context comes back unchanged.envelope_decoderdrivesenvelope::decodeandenvelope::encode. The identity is the digest of the inner payment; expiry lies inside the window of the executing slot.anchor_history_decoderdrivesAnchorHistory::decode. The eligible roots of a decoded history are those the slot rules give.pool_state_decoderdrivesPoolState::decodeforNPOOL003andNPOOL004. The decoded roots and checkpoints belong to the decoded tree; a decoded slot-anchored state completes a slot; a note equal to the empty leaf is refused; a payment and a completed slot leave a state that decodes.staged_payload_and_buffer_decoderdrivesStagedPayloadandnative_accounts::Buffer. The in-memory assembler and the account buffer accept the same chunks; the account decodes after every instruction.unstructured_bytes_reach_no_panicdrives all of the above with bytes that have a known tag and an exact size, and nothing else valid.
Inputs are valid encodings with one to three mutations, most of them aligned to fields; encodings assembled from parts that break one rule; and unstructured bytes.
The targets are ordinary integration tests on the pinned stable toolchain, with no dependency that the crate did not already have. The generator is a small fixed algorithm, so a seed gives the same cases on every machine. No coverage-guided engine drives them.
Property tests for the pool state
protocol/payments/tests/pool_properties.rs holds property tests for the pool state transition. The test pool_transition_keeps_its_invariants runs random sequences of payments, completed slots, anchor queries and encode-decode reloads against a model, from fresh pools and from pools assembled a few payments below the tree limit or the backing limit. After every step it requires:
- Backing is conserved. It moves by exactly the public value of an accepted payment and by nothing else, equals deposits less withdrawals, and stays between zero and the largest signed amount.
- The note count is monotonic. It never decreases and grows by two per accepted payment. The tree root equals that of an independent incremental Merkle tree.
- Anchors come only from completed slots. The roots a slot accepts are the roots recorded by slots completed before it and inside the window, plus the empty tree during the first window. The tree of the slot still executing is not among them.
- A payment leaves a tree that a slot can record. A note equal to the empty leaf is refused. After every accepted payment into a slot-anchored pool, the slot it executed in and later slots complete.
- Capacity fails closed. A full tree or a full backing refuses the payment. Every refused step leaves the state byte for byte unchanged.
Two tests do not depend on the random sequences: capacity_fails_closed_at_every_limit walks each limit, and long_runs_rotate_the_recent_roots_and_the_slot_window makes more payments than a legacy pool keeps roots and completes more slots than the window holds.
Run the fuzz targets and property tests
The workspace tests run every target at its built-in case count. To run the two files on their own:
sh tools/dev.sh test --locked -p native-payments --test decoder_fuzz --test pool_properties -- --nocapture
Three environment variables change the run:
PROTOCOL_FUZZ_SCALE=4: four times the built-in case count of every target.PROTOCOL_FUZZ_SECONDS=60: run every target for that long instead of counting cases.PROTOCOL_FUZZ_SEED=7: a different sequence of cases; the default seed is fixed.
With --nocapture each target prints its case count, how many inputs were accepted, the time taken and the seed. tools/check.sh and the pull-request workflow run the two files a second time with PROTOCOL_FUZZ_SCALE=4. The seed stays fixed there, so those runs repeat the same cases; use a new seed to explore.
A decoder target that fails prints the reason, the bytes that differ from the valid encoding the input was derived from, and the whole input in hexadecimal. Before printing, it puts bytes back to their valid value for as long as the failure remains, so what is left is the part that matters. A failing target also names the case and the seed.
What the first runs found
The repository records the result in docs/protocol-fuzzing.md. The first runs of these targets found two ways to reach a slot-anchored pool state on which complete_slot returned InvalidEncoding. Neither was a panic in the crate or an encoding that did not round-trip, and each refusal left the state unchanged. Both had one cause, and both are now refused earlier, by two rules in protocol/payments/src/state.rs:
PoolState::with_paymentrefuses a payment if either note is the empty leaf, withInvalidEncoding, for both pool formats. A refused payment leaves the pool as it was.PoolState::decoderefuses anNPOOL004state whose tree the next completed slot could not record.NPOOL003states complete no slots and decode as before.
What the two rules do not reach, as the same document states it: a written-down state may hold a checkpoint that claims the root the next payment will produce. The payment is accepted and the slot is then refused, as before. The transition never writes such a state. A caller of complete_slot still has to handle a refusal; decision 0041 is a draft of what the validator should do with one, and nothing in it is implemented.
The rules are in the workspace crate. The validator candidate carries its own copy of state.rs; the same two rules are prepared for that copy as a patch that is not yet part of the candidate’s reconstruction plan. Until it is, the candidate’s copy has the earlier behaviour.
What the fuzzing does not cover
- Proof and signature verification is not fuzzed. Decoded payments carry random proofs and signatures that are never verified in these tests.
- Only the
native-paymentscrate of the workspace is exercised: not the native program’s instruction decoding, and not any other copy of these formats. - The reference statements were written for the formats as they are. A deliberate format change needs the same change there.
- A property that holds for every generated case is not a proof.
Protocol test vectors
The repository also holds test vectors for the protocol, a test that regenerates them from the code on every run, and a second reader written in Python from the specification alone. Both are described, with their commands, on Protocol specification.
Protocol copy guard
The repository holds the payment protocol and the native program twice. The workspace builds and tests protocol/payments/src and node/adapter/src. The candidate’s base patch adds its own copy of both to the patched tree, and the validator built from the candidate runs that copy. A change made to one copy only is a difference between tested and deployed rules.
tools/protocol_copy_guard.py fails when the two drift:
python3 -B tools/protocol_copy_guard.py check
python3 -B -m unittest discover -s tools -p 'protocol_copy_guard_test.py' -v
- What
checkdoes. It takes the candidate’s copies from the pinned patch chain with Git patch application, compares them with the workspace file by file, and fails on any difference that is not recorded intools/protocol_copy_allowlist.json. - Records are pinned. Every record pins both files by SHA-256. A change to either side of a recorded difference fails until the same change is made on the other side or the difference is reviewed again, and a record must be deleted once its files are identical.
- The proof system must match. The check requires the same exact
orchardrelease on both sides. - What is recorded now. Four files are byte-identical in both places:
anchors.rs,staging.rsandverification.rsof the protocol, andinstructions.rsof the program. Proof verification is one of the identical files. The other files differ, each with a written review. Two records are marked as differences of behaviour:processor/runtime_features.rs, the one file through which the workspace’s program reaches its runtime, andstate.rs, which has the two rules above in the workspace only.
The check compares source text. It does not compile either copy and is not a proof that two different texts behave alike. It builds nothing; it needs Python 3.11 or newer and Git.
The background is in node/candidate/README.md and in decision 0043, a draft that sets out the options for keeping one copy.
Supply and pool-backing monitor
Shielded amounts are hidden by design, so nobody can add up the notes. What stays public is the boundary of the pool: the pool account’s balance, the backing the payment program records in that account, and the chain’s total supply. tools/supply_monitor.py watches that boundary.
It reads one validator RPC endpoint and answers two questions: is every unit the shielded pool records as backing actually in the pool account, and has the total supply stayed within what the chain is scheduled to issue? It sends no transaction, holds no wallet capability and creates no key. It is one file that needs Python 3.9 or newer and /usr/bin/openssl, so a reader can fetch and review it on its own.
A tool in the repository, not a published feed. The monitor is a file in the repository, with its tests and a runbook. These docs do not present it as running against the devnet, and this site publishes no result from it. The runs the repository describes are against a loopback stand-in for a validator’s RPC and against a local two-validator network.
What it checks
Amounts are whole base units. Each check is true, false, or null when it could not be evaluated.
pool_account: the account exists, is owned by the payment program, is not executable, and its data is a pool header in a known format.pool_backing:lamports >= rent_floor + backing. This is the rule the payment program applies before every payment.pool_rent_floor:rent_floor >= rent_exempt_minimum(data_bytes)as the endpoint reports it.supply_identity:total == circulating + non_circulating.pool_within_supply:lamports <= total.supply_ceiling:total <= --supply-ceiling;nullwhen no ceiling is given.continuity, against the baseline: format, network domain and rent floor unchanged; note count not lower; and backing unchanged when the note count is unchanged.supply_issuance, against the baseline:total - baseline.total <= allowance, where the allowance is the most the chain may have issued since the baseline.
The result is green, red or unknown. The baseline is the last green result: the monitor replaces it only when the new result is green, so a red result stays red for as long as its cause remains. If the reads never name one slot, the result is unknown, not red. The default commitment level is finalized.
The monitor writes a result document that an operator can sign and publish, and a verify command checks such a document. A valid signature means the key holder’s monitor reported these numbers from its endpoint. It is not a proof of chain state.
Run it
Unsigned, to the terminal, against the default RPC address of a local network:
python3 -B tools/supply_monitor.py check --rpc http://127.0.0.1:18899
The unit tests need no network. They run the monitor against a loopback stand-in for the validator’s RPC whose pool account bytes are written by the real encoder:
python3 -B -m unittest discover -s tools -p 'supply_monitor_test.py'
On a real local network, with a fresh pool:
sh tools/build_localnet.sh
python3 -B tools/localnet.py init --root .data/supply
python3 -B tools/localnet.py start --root .data/supply
python3 -B tools/supply_monitor_localnet.py --root .data/supply
python3 -B tools/localnet.py stop --root .data/supply
That harness runs the monitor against both validators while a deposit, a private send and a withdrawal are made and the network crosses epoch boundaries, and requires every result to be green. It then puts a loopback relay in front of the first validator that alters the answers about the pool account or the supply, and requires each alteration to be reported red under the expected check. The signed form, the baseline and the exit codes are in docs/supply-monitor-runbook.md.
What a green result establishes
For the node that was read, and at the slot named:
- every unit of recorded backing, and the rent reserve, is in the pool account;
- the pool account is the payment program’s, in a known format, and has not changed except through payments since the baseline;
- the supply the node reports is consistent with itself, covers the pool, respects a declared ceiling, and has not grown since the baseline by more than the pending rewards and the scheduled inflation of the epochs crossed.
What it does not establish
- That no note was forged. A forged note inside the pool changes neither backing nor balance, so no public reading shows it. What the boundary gives is a limit on the damage: forged notes could at worst take backing that belongs to honest notes; they cannot raise the total supply.
- That account balances add up to the total.
totalis the node’s own running count. No RPC method lists every account at one slot, so the monitor cannot sum them. - An exact reconciliation of supply.
supply_issuanceis an upper bound. Fees burned since the baseline are not measured. - Anything the endpoint did not tell truthfully. The monitor trusts its endpoint.
Where the checks run
The repository has two places that run checks: tools/check.sh, run by hand, and one workflow that runs on pull requests. The workflow covers the packages that build without the vendored validator.
| Check | tools/check.sh | Pull-request workflow |
|---|---|---|
| Fuzz targets and property tests | With the workspace tests, then again with four times the cases | With the Rust tests, then again with four times the cases |
| Vector test in Rust | With the workspace tests | With the Rust tests of native-payments |
| Second reader of the vectors, in Python | With the Python suites | Not run |
| Protocol copy guard | Its tests, with the Python suites | Its tests and check |
| Supply monitor unit tests | With the Python suites | Not run |
| SDK JavaScript tests, cookbook included | Yes | Yes |
The workflow’s own description: the validator, the native program, the command-line wallet and the Python suites are not covered there, except the copy guard. The local-network harness of the supply monitor is in neither; it is run by hand. How to run tools/check.sh is on Build and run the code.