It describes what exists. The specification makes no statement about what the protocol will become. The encodings are experimental, and every amount and limit is a development parameter.
Not reviewed outside the project. In the document’s own words, nothing in it “has been reviewed by anyone outside the project”. It is a statement to check the code against, not an audit of the code.
The specification is one file: docs/protocol-spec.md. It describes the shielded-payment protocol as the code in the repository implements it: every byte of every encoding, the state the validator keeps, the rules that change that state, and the limits. It is written so that a reviewer can check the code against a statement, and so that a second implementation can be written from it and checked against the test vectors.
This page introduces the document. It does not repeat it. For a short summary of the formats, see the Protocol reference.
What it covers
| Sections | Subject |
|---|---|
| 1 and 2 | Scope, sources and conventions |
| 3 | Overview: the objects, the kinds of payment, the two ways a payment reaches the program, and what a payment shows and does not contain |
| 4 | Cryptographic components |
| 5 to 7 | Payment encoding, the authorization digest and payment verification |
| 8 and 9 | The pool account in both formats, the note commitment tree and anchors |
| 10 to 12 | Nullifier markers, staging and the inline envelope |
| 13 | The native program: entry rules, feature gates, instructions, finalization and who pays what |
| 14 | Test vectors |
| 15 | Open questions and observations |
| 16 | Statements elsewhere that differ from the code |
| 17 | What the document does not cover |
| Appendices | A: constants and limits. B: domain separation. C: errors |
What it is written from
The specification is taken from two crates of the workspace: native-payments in protocol/payments (encodings, the authorization digest, verification, pool state, anchors, staging and the envelope) and native-payment-program in node/adapter (the native program that executes payments inside the validator). Its references have the form file:line.
The repository contains a second copy of both crates inside the patch file that the Agave 4.3.2 candidate builds. The document specifies the workspace crates and marks what exists only in the candidate. One consequence is stated in its section 15: the program built from the workspace accepts no payment against an NPOOL004 pool, so that format, as a rule a validator executes, still exists only in a build of the patch file. The protocol copy guard compares the two copies.
The formats carry their own version tags: NPAY0001, NPAY0002 and NPAY0003 for payments, NPOOL003 and NPOOL004 for the pool, ZOLANCH1 for the checkpoint history, NBUF0001 for the staging account, NSPENT01 for the nullifier marker and ZOLNPAY1 for the envelope.
How it treats doubt
Where the code is ambiguous, surprising or inconsistent, the document says what the code does and lists the point in section 15 instead of choosing an interpretation. That section has 31 numbered items. Each states what the code does and where; none is resolved there.
Section 16 lists the places where a decision record or a comment in the two crates says something the present code does not do. Decision records are kept as written when later work changes the facts.
The test vectors
The vectors are in protocol/payments/tests/vectors; the README there lists the files and the conventions of the JSON.
| File | Contents |
|---|---|
payloads/*.hex | Four payments with real proofs: a deposit, a private send, a payment with a shielded fee and a withdrawal to a bound recipient. Each spends notes created by the ones before it. |
payments.json | The four payments field by field, their authorization digests with every intermediate value, what the test wallets can decrypt, decoder cases and verification cases. |
envelope.json | The frame around the fee payment, the slots in which it decodes, and decoder cases. |
staging.json | Payload digests, a staging account through initialization, every write, sealing and consumption, and stored accounts the decoder accepts or refuses. |
anchors.json | Slot checkpoint histories: records accepted and refused, the roots a slot may use, the largest history, and decoder cases. |
pool.json | Empty-tree constants, tree hash samples, the four payments applied to an NPOOL003 pool and to an NPOOL004 pool slot by slot, root rotation, capacity limits, and decoder cases. |
accounts.json | The program address, the pool address and the marker address of every nullifier in the four payments, with seeds and bump. |
Every key in these files is public test material, and the network domain is synthetic. Nothing in them describes a running network.
How the vectors are checked
By the code
protocol/payments/tests/protocol_vectors.rs builds every JSON file from the crate’s own functions: it encodes with the crate’s encoders and records what the crate’s decoders, verifier and state transition return.
The test committed_vectors_are_what_the_code_produces runs with the workspace tests. It reads the four payments, requires the verifier to accept each of them, regenerates every JSON file and requires it to equal the committed copy byte for byte. Each decoder case and each verification case also carries the result the specification states for it, and the test fails if the code returns another. A change of a format, a limit, a rule or an error name therefore fails the test until the vectors, and with them the document, are changed.
To run that test file on its own:
sh tools/dev.sh test --offline --locked -p native-payments --test protocol_vectors
The repository gives this command with a variable in front. With WRITE_PROTOCOL_VECTORS=1 it rewrites the JSON files, which is the step after an intended change of a format, a rule or an error; review the difference afterwards.
WRITE_PROTOCOL_VECTORS=1 sh tools/dev.sh test --offline --locked -p native-payments --test protocol_vectors
On an ordinary run the four payments are read from payloads/, not rebuilt. An ignored test rebuilds them, proofs included, from fixed keys and a fixed byte stream and compares the result with the files; with PROTOCOL_VECTORS_PROVE=1 it rewrites them:
PROTOCOL_VECTORS_PROVE=1 sh tools/dev.sh test --offline --locked -p native-payments --test protocol_vectors -- --ignored
Rebuilding gives the same bytes when repeated on one machine. It has not been compared across platforms, which is why the ordinary test verifies the committed payments instead of rebuilding them.
By a second reader
tools/protocol_vectors_test.py is written from the document in another language, Python, and shares no code with the crates. It decodes payments, envelopes, checkpoint histories, pool accounts and staging accounts by the rules of the specification, computes the digests and the derived addresses, applies the pre-signature checks of verification and replays the recorded sequences. Every result must equal what the vectors record from the code.
It does not implement the tree hash, signature verification or proof verification. For those it takes the recorded roots and results, and it names the five decoder cases whose refusal rests on the tree hash.
It runs with the Python suites of tools/check.sh:
python3 -B -m unittest discover -s tools -p '*_test.py'
To run that one file, give its name as the pattern: -p 'protocol_vectors_test.py'. It needs Python and nothing else: no build and no network.
What the vectors do not cover
The native program of section 13 is not exercised by the vectors. Its account rules, instruction data, error codes, compute charge, feature gates and marker data are specified from the source and are tested by the program’s own tests and by node/validator-check. Nor do the vectors cover what exists only in the candidate.
What the document does not cover
- The Orchard Action statement, key derivation, note encryption and address formats. They are the
orchardcrate’s, used unchanged. - An argument that the integration is sound: that value is conserved, that each binding is sufficient, or that the hidden values stay hidden. The document states what is bound, not what follows.
- The wallets: note selection, scanning, witness maintenance, journals, recovery and fee quotes.
- The gateway, relay, faucet and other services, and what their operators observe. For that, see Privacy boundary.
- Consensus, block production, snapshots, replay and the validator outside the native program.
- Economics: no fee, rent or supply schedule is specified, because none is chosen.
This page and the Protocol reference
The Protocol reference on this site is a short summary: opcodes, layouts, sizes and constants on one page. The specification is the full statement, with the reasons, the open points and the vectors. If the two differ, the specification and the code are right. Other checks of the same code are on Testing and verification.