These formats are experimental. The wire module begins: “Fixed-shape experimental encoding. This format is not a released protocol.” Identifiers are “fixed public development identifiers”. Pool formats have been replaced before without migration.
Sources: protocol/payments/src and node/adapter/src. All integers are little-endian.
Identifiers
| Item | Value |
|---|---|
| Program id | A fixed 32-byte array, PROGRAM_ID in native_accounts.rs, beginning 91, 34, 9, 203. It has no associated private key. The source stores bytes, not a base58 string. |
| Pool address | Program-derived from the single seed native-payment-pool-v1. |
| Nullifier address | Program-derived from the seeds native-payment-spent-v1, the pool address and the 32-byte nullifier. |
| Feature gates | native_private_payments, native_recipient_withdrawals, native_shielded_fees, native_inline_payments. Their ids are fixed byte arrays that differ in the first byte (192 to 195). |
The program is registered in the validator’s builtin table under the name native_private_payments and enabled by the first feature gate. Genesis must activate the feature and provision the pool account; no instruction creates or replaces the pool.
Instructions
The first byte of the instruction data is the opcode. The program must be invoked as a top-level instruction; it rejects calls from other programs.
| Op | Name | Data after the opcode | Accounts |
|---|---|---|---|
| 0 | initialize | length u32, digest (32 bytes), expiry u64 | staging buffer (writable, signer); sponsor (signer) |
| 1 | write | offset u32, then the chunk | staging buffer (writable); sponsor (signer) |
| 2 | seal | none | staging buffer (writable); sponsor (signer) |
| 3 | finalize | none | pool (writable); sealed buffer (writable); sponsor (writable, signer); System Program; two nullifier accounts (writable, in action order); for a recipient-bound withdrawal, the recipient (writable) |
| 4 | close | none | staging buffer (writable); sponsor (writable, signer) |
| 5 | inline finalize | the whole envelope frame | pool (writable); sponsor (writable, signer); System Program; two nullifier accounts (writable) |
- write is sequential: the offset must equal the bytes received so far, and a chunk is 1 to 768 bytes.
- seal requires every byte and a matching digest. A sealed buffer is immutable.
- close returns the buffer’s balance to its sponsor. Only the recorded sponsor may close, and closing is allowed after expiry. The pool cannot be closed this way.
- inline finalize is refused unless the
native_inline_paymentsfeature is active. The source calls it an “execution candidate only: ordinary Agave ingress still enforces its MTU”. - The instruction builders are in
node/adapter/src/instructions.rs.finalize_and_closereturns the pair[payment, close]so that “the runtime commits the payment and its rent refund together, or neither”.
Compute charges: opcodes 3 and 5 consume 1,100,000 units (FINALIZE_COMPUTE_UNITS); every other opcode consumes 10,000. The wallets request a limit of 1,400,000.
Staging account
Size: a 96-byte header plus 16,384 payload bytes.
| Bytes | Field |
|---|---|
| 0..8 | tag NBUF0001 |
| 8..40 | sponsor |
| 40..44 | payload length, u32 |
| 44..48 | bytes received, u32 |
| 48..80 | payload digest |
| 80..88 | expiry slot, u64 |
| 88 | status: 0 writing, 1 sealed, 3 consumed |
| 89..96 | zero |
The digest is BLAKE2b with a 32-byte output and the personalization NativeStageV1!!!. The expiry must be no more than 1,024 slots ahead when the buffer is initialised; after it, every operation except close fails.
Pool account
There are two formats. A validator accepts the one its code line implements.
NPOOL003 | NPOOL004 | |
|---|---|---|
| Used by | The workspace validator (Agave 3.0.14 snapshot) | The Agave 4.3.2 candidate; the format the browser wallet requires |
| Layout | tag, network (32), rent floor, backing, commitment count (u64 each), root count (u8), 32 frontier nodes, up to 64 roots | tag, network (32), rent floor, backing, commitment count, 32 frontier nodes, history length (u32), slot anchor history |
| Size | 3,137 bytes | 25,728 bytes |
| Accepted anchors | The 64 most recent roots (MAX_ROOTS) | One root per completed slot, valid for 512 slots (ANCHOR_WINDOW_SLOTS) |
- Backing is the amount of native coin the notes are worth in total. The pool account must hold at least its rent floor plus its backing. A deposit raises backing; a withdrawal or a shielded fee lowers it.
- Commitment count is always even, because every payment appends two. The limit is
MAX_COMMITMENTS = (1 << 32) - 2. - Slot anchors (
NPOOL004): each entry is a slot, a note count and a root. The rule is in the source: “A slot root of age 511 is valid; age 512 is expired.” The current slot’s root is never accepted.
Nullifier account
40 bytes: the tag NSPENT01 followed by the 32-byte nullifier. The finalizer creates it with a rent-exempt balance taken from the sponsor, then allocates and assigns it to the program. An existing program-owned account at the derived address makes the payment fail. No instruction closes it.
Payment wire format
Three variants share one layout and differ in the tag and two optional fields.
| Tag | Variant | Size |
|---|---|---|
NPAY0001 | Deposit, private send, or withdrawal credited to the sponsor | 9,222 bytes |
NPAY0002 | Recipient-bound withdrawal | 9,254 bytes |
NPAY0003 | Shielded-fee send | 9,230 bytes |
Field order:
- tag, 8 bytes
- network identifier, 32 bytes
- expiry slot,
u64 - public value balance,
i64 - sponsor, 32 bytes
- shielded fee,
u64(NPAY0003only) - withdrawal recipient, 32 bytes (
NPAY0002only) - anchor, 32 bytes
- flag byte, then the action count, which must be 2
- two actions of 884 bytes each: nullifier (32), randomized key (32), commitment (32), ephemeral key (32), encrypted note, outgoing ciphertext, value commitment (32), spend authorization signature (64)
- proof length
u32, then the proof - binding signature, 64 bytes
The decoder rejects unknown tags, another network identifier, non-default flags, any action count other than 2, a proof of unexpected size and any length mismatch. A payment may not exceed 16,384 bytes.
Rules on the public fields:
- With a shielded fee: the fee is non-zero, the public value balance equals the fee, and there is no withdrawal recipient.
- With a withdrawal recipient: the public value balance is positive and the recipient is not all zero. On chain the recipient must be an ordinary, non-executable, System-owned account without data, on the curve, and different from the sponsor.
- The expiry must not be in the past and not more than 1,024 slots ahead (
MAX_EXPIRY_WINDOW).
Authorization digest
All signatures in a payment sign one BLAKE2b-256 digest over: the network identifier, PROTOCOL_VERSION (1), the Orchard bundle commitment, the expiry, the public value balance and the sponsor, then the fee if present and the recipient if present. The personalization is NativePayAuthV1!, NativePayAuthV2! with a withdrawal recipient, or NativePayAuthV3! with a shielded fee.
Inline envelope
An inline payment wraps the payment bytes in a frame: tag ZOLNPAY1, version 1, the domain ZolanaNativePay!, the network identifier, the expiry, a payment id (the payload digest) and the payload length. The frame is at most 16,384 bytes and carries only NPAY0003 payments. The source warns: “A successfully decoded envelope is NOT a verified payment.”
Verification
The order of checks is listed in How shielded payments work. The verifier is PaymentVerifier::verify in protocol/payments/src/verification.rs; the on-chain sequence around it is in node/adapter/src/processor/finalization.rs.
Constants
| Constant | Value | Meaning |
|---|---|---|
ACTION_COUNT | 2 | Actions per payment |
PROTOCOL_VERSION | 1 | Bound into the authorization digest |
MAX_EXPIRY_WINDOW | 1,024 slots | Furthest allowed expiry |
MAX_PAYLOAD_BYTES | 16,384 | Largest staged payment |
MAX_CHUNK_BYTES | 768 | Largest staging write |
MAX_ROOTS | 64 | Recent roots in NPOOL003 |
ANCHOR_WINDOW_SLOTS | 512 | Anchor lifetime in NPOOL004 |
MAX_COMMITMENTS | 4,294,967,294 | Capacity of the note tree |
MARKER_BYTES | 40 | Size of a nullifier account |
FINALIZE_COMPUTE_UNITS | 1,100,000 | Charged before proof verification |
Errors
The protocol crate defines these errors:
InvalidContext UnsupportedVersion InvalidShape Expired WrongValueBalance UnknownAnchor
DuplicateNullifier SpentNullifier InvalidSpendAuthorization InvalidBindingSignature
InvalidProof InvalidLength InvalidChunk IncompletePayload DigestMismatch SealedPayload
UnsealedPayload InvalidEncoding WrongNetwork CapacityExceeded InsufficientBacking
They are useful when you call the crate directly. On chain they are not distinguishable: the processor maps every decoding, verification and state error of a payment to the runtime’s InvalidInstructionData. A client learns that a finalization failed, not which check failed, so it has to run the same checks before it submits.
Units
Amounts in the protocol and in the command-line wallet are unsigned integers of the smallest unit (“native units”). The explorer and the browser wallet display ZOL with nine decimal places: 1 ZOL is 1,000,000,000 units. The explorer source names the unit lamports.