Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Testing and verification

What the fuzz targets, the property tests, the protocol copy guard and the supply monitor in the repository check, how to run each, and what none of them shows.

Status

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:

  1. the decoder does not panic;
  2. it accepts exactly the inputs that a reference statement of the format accepts, size bounds included;
  3. 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_decoder drives wire::decode with the three tags. A wrong size is always refused as a length error; another network is refused.
  • payment_encoder_agrees_with_decoder drives wire::encode. The encoder refuses every context the decoder refuses; an accepted context comes back unchanged.
  • envelope_decoder drives envelope::decode and envelope::encode. The identity is the digest of the inner payment; expiry lies inside the window of the executing slot.
  • anchor_history_decoder drives AnchorHistory::decode. The eligible roots of a decoded history are those the slot rules give.
  • pool_state_decoder drives PoolState::decode for NPOOL003 and NPOOL004. 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_decoder drives StagedPayload and native_accounts::Buffer. The in-memory assembler and the account buffer accept the same chunks; the account decodes after every instruction.
  • unstructured_bytes_reach_no_panic drives 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:

  1. PoolState::with_payment refuses a payment if either note is the empty leaf, with InvalidEncoding, for both pool formats. A refused payment leaves the pool as it was.
  2. PoolState::decode refuses an NPOOL004 state whose tree the next completed slot could not record. NPOOL003 states 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-payments crate 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 check does. 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 in tools/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 orchard release on both sides.
  • What is recorded now. Four files are byte-identical in both places: anchors.rs, staging.rs and verification.rs of the protocol, and instructions.rs of 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, and state.rs, which has the two rules above in the workspace only.
Limit

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.

Limit

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; null when 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. total is 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_issuance is 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.

Where each check runs
Checktools/check.shPull-request workflow
Fuzz targets and property testsWith the workspace tests, then again with four times the casesWith the Rust tests, then again with four times the cases
Vector test in RustWith the workspace testsWith the Rust tests of native-payments
Second reader of the vectors, in PythonWith the Python suitesNot run
Protocol copy guardIts tests, with the Python suitesIts tests and check
Supply monitor unit testsWith the Python suitesNot run
SDK JavaScript tests, cookbook includedYesYes

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.

Your privacy
has a boundary.

Zolana is an independent blockchain for native shielded deposits, private transfers and withdrawals. The browser wallet creates proofs and decrypts its own notes locally.

Shielded details

Payment amounts and receiving addresses are protected by proofs. Your spending and viewing keys stay on your device.

Public evidence

Blocks, timing, fees, nullifiers and public deposit or withdrawal accounts and amounts remain visible.

The invited gateway knows your membership and receiving address. It sees your IP address and request timing and can link your submissions. This is not a claim of complete anonymity.

Valueless test coins. No Solana bridge, SOL/USDC deposits, post-quantum protection or audited-security claim.