Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Protocol reference

Instructions, account layouts, the payment wire format, constants and errors of the native payment program.

Stability

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

Identifiers
ItemValue
Program idA 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 addressProgram-derived from the single seed native-payment-pool-v1.
Nullifier addressProgram-derived from the seeds native-payment-spent-v1, the pool address and the 32-byte nullifier.
Feature gatesnative_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.

Instructions
OpNameData after the opcodeAccounts
0initializelength u32, digest (32 bytes), expiry u64staging buffer (writable, signer); sponsor (signer)
1writeoffset u32, then the chunkstaging buffer (writable); sponsor (signer)
2sealnonestaging buffer (writable); sponsor (signer)
3finalizenonepool (writable); sealed buffer (writable); sponsor (writable, signer); System Program; two nullifier accounts (writable, in action order); for a recipient-bound withdrawal, the recipient (writable)
4closenonestaging buffer (writable); sponsor (writable, signer)
5inline finalizethe whole envelope framepool (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_payments feature 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_close returns 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.

Staging account header
BytesField
0..8tag NBUF0001
8..40sponsor
40..44payload length, u32
44..48bytes received, u32
48..80payload digest
80..88expiry slot, u64
88status: 0 writing, 1 sealed, 3 consumed
89..96zero

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.

Pool account formats
NPOOL003NPOOL004
Used byThe workspace validator (Agave 3.0.14 snapshot)The Agave 4.3.2 candidate; the format the browser wallet requires
Layouttag, network (32), rent floor, backing, commitment count (u64 each), root count (u8), 32 frontier nodes, up to 64 rootstag, network (32), rent floor, backing, commitment count, 32 frontier nodes, history length (u32), slot anchor history
Size3,137 bytes25,728 bytes
Accepted anchorsThe 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.

Payment variants
TagVariantSize
NPAY0001Deposit, private send, or withdrawal credited to the sponsor9,222 bytes
NPAY0002Recipient-bound withdrawal9,254 bytes
NPAY0003Shielded-fee send9,230 bytes

Field order:

  1. tag, 8 bytes
  2. network identifier, 32 bytes
  3. expiry slot, u64
  4. public value balance, i64
  5. sponsor, 32 bytes
  6. shielded fee, u64 (NPAY0003 only)
  7. withdrawal recipient, 32 bytes (NPAY0002 only)
  8. anchor, 32 bytes
  9. flag byte, then the action count, which must be 2
  10. 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)
  11. proof length u32, then the proof
  12. 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

Constants
ConstantValueMeaning
ACTION_COUNT2Actions per payment
PROTOCOL_VERSION1Bound into the authorization digest
MAX_EXPIRY_WINDOW1,024 slotsFurthest allowed expiry
MAX_PAYLOAD_BYTES16,384Largest staged payment
MAX_CHUNK_BYTES768Largest staging write
MAX_ROOTS64Recent roots in NPOOL003
ANCHOR_WINDOW_SLOTS512Anchor lifetime in NPOOL004
MAX_COMMITMENTS4,294,967,294Capacity of the note tree
MARKER_BYTES40Size of a nullifier account
FINALIZE_COMPUTE_UNITS1,100,000Charged 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.

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.