Zolana
ExplorerDocsGitHubOpen wallet

Docs · Concepts

How shielded payments work

Notes, commitments and nullifiers, what a validator checks while it executes a block, where proofs are made, and how fees are paid.

This page describes what the Zolana code does around a shielded payment. The proof system itself is the Orchard circuit from the orchard crate, version 0.16.0, used unchanged. What that circuit proves is defined by the crate, not by this project.

Notes and commitments

A shielded balance is not a number stored in an account. It is a set of notes. Each note records an amount for one receiving address, and the wallet that owns it keeps the details.

The chain does not store notes in the clear. For every new note a payment publishes a 32-byte commitment and an encrypted copy of the note. The validator appends the commitment to a Merkle tree kept in the shielded pool account. The pool keeps the tree’s frontier (32 levels) and a count instead of every commitment, so the account does not grow with every payment.

A wallet finds its own notes by trying to decrypt the encrypted outputs of each payment with its viewing keys. Outputs that do not decrypt belong to someone else.

The root of the tree after a payment is called an anchor. A later payment that spends a note names an anchor, and the validator accepts the payment only if that anchor is one of the recent roots it has recorded.

Nullifiers, and why they are permanent

Each action of a payment publishes a 32-byte nullifier. The chain refuses any payment whose nullifier has been published before. That is the rule that stops a note from being spent twice.

On Zolana every nullifier becomes its own small account:

  • It is 40 bytes and owned by the payment program. Its data is the tag NSPENT01 followed by the nullifier.
  • Its address is derived from the seeds native-payment-spent-v1, the pool address and the full nullifier, so anyone can compute where a given nullifier would live.
  • If an account owned by the program already exists at that address, the payment is rejected, even if its data is malformed.
  • There is no operation to close, overwrite or reset one.

They are permanent for two reasons recorded in the design notes. An earlier design kept spent nullifiers in an array inside the pool account; it stopped after 128 payments, and enlarging the array would have made every payment read and rewrite a growing set. And because the markers are ordinary accounts, replay, snapshots and fork choice use the validator’s existing account machinery instead of a side database or a spent set maintained over RPC.

Permanence has a cost. Each marker has to hold a rent-exempt balance that is never returned. At the current development rent schedule that is 1,169,280 units per marker, 2,338,560 for the two markers of one payment. The design notes say this needs economic calibration before any public release.

What one payment keeps private and what it publishes Two columns. Left: the two input notes stay private; the payment publishes two nullifiers, which become two permanent accounts, so a second spend of the same note is rejected. Right: the two output notes stay private; the payment publishes two commitments and the encrypted notes, which are appended to the note tree, and the new root becomes an anchor for later spends. The fee, relay account, expiry, proof and signatures are also public. SPENT BY THIS PAYMENT CREATED BY THIS PAYMENT 2 input notes amounts, owner 2 output notes amounts, recipient 2 nullifiers 32 bytes each 2 commitments plus encrypted notes 2 permanent accounts Never closed. A second spend of the same note is rejected. Added to the note tree The new root becomes an anchor for later spends. Private: known to the wallets involved Public: stored on chain Also public: fee, relay account, expiry, proof, signatures.
Every payment has exactly two actions, so it always publishes two nullifiers and two commitments.

What a payment contains

Every payment has exactly two actions. The wire format is fixed-shape, and the code calls it experimental: “This format is not a released protocol.” A payment carries:

  • the network identifier, an expiry slot and the public value balance;
  • the sponsor, which is the public account that signs and pays for the outer transaction;
  • for a shielded-fee payment, the exact fee; for a recipient-bound withdrawal, the public recipient;
  • the anchor;
  • for each of the two actions: a nullifier, a randomized authorization key, a commitment, the encrypted note, and a spend authorization signature;
  • the proof and a binding signature.

A payment without a fee field is 9,222 bytes. With a shielded fee it is 9,230 bytes, and a recipient-bound withdrawal is 9,254 bytes.

The public value balance says how much native coin crosses the boundary of the pool. Negative means a deposit, positive means coins leave the pool (a withdrawal, or the fee of a shielded-fee send), and zero means the value stays inside.

Where proofs are created

Proofs are created on the wallet’s device. In the browser wallet the proof is built by a Rust core compiled to WebAssembly and run in a web worker; the core’s own description is that it keeps “seeds, note decryption and proof construction inside Rust”. The command-line wallet does the same in its local process.

Validators only verify. Neither the gateway nor the relay builds proofs, and the client flows in the repository do not send spending or viewing keys to them.

A proof is roughly 9 KiB, more than fits in one ordinary 1,232-byte transaction packet. The repository has two ways to deliver it:

  • Staged. The payment is uploaded in chunks of at most 768 bytes into a temporary staging account (at most 16 KiB, valid for at most 1,024 slots), sealed against a content digest, and then finalized by a small instruction. This is what the workspace’s validator (the Agave 3.0.14 snapshot) supports.
  • Inline. The whole payment travels in a single transaction. This needs the Agave 4.3.2 candidate, which is a patch series built separately. The browser wallet only accepts fee quotes for this transport.

What a validator verifies

The payment program runs inside block execution, on every validator. Before anything is written it checks, in this order:

  1. The payment uses the supported Orchard bundle version. The historical v1 circuit is rejected.
  2. The shape is exact: two actions, the expected proof size and the default flags.
  3. The payment has not expired, and its expiry is no more than 1,024 slots ahead.
  4. The value balance inside the proof equals the public value balance the payment declares.
  5. The anchor is one of the accepted recent roots.
  6. The two nullifiers differ from each other, and neither has been spent.
  7. Each action’s spend authorization signature is valid.
  8. The binding signature is valid.
  9. The proof verifies.

The signatures cover a digest that commits to the network identifier, the protocol version, the full Orchard bundle, the expiry, the public value balance and the sponsor, plus the fee and the withdrawal recipient where present. Changing any of them invalidates the payment.

Around these checks, the program also requires that it was called as a top-level instruction, that the sponsor named in the payment is the account that signed the transaction, that both nullifier accounts are at their derived addresses and unused, and that the pool account holds enough coins for its rent floor plus its recorded backing.

The code comment on the finalization step states the ordering: “Account-role and spend-marker checks and proof verification precede writes. The Bank commits public transfers, permanent nullifiers, pool state and staged-payload consumption together.” If a later instruction in the same transaction fails, all of it rolls back.

Finalizing a payment is charged 1,100,000 compute units before the proof is verified; the other operations are charged 10,000. The design notes call these “conservative local development charges, not calibrated production throughput claims”.

A private payment from wallet to chain Three stages from top to bottom. First, your device selects up to two unspent notes, builds the proof, signs the payment and encrypts the two new notes; keys and note contents do not leave it. Second, the gateway checks membership and limits, and the relay signs the transaction and pays its public fee. Third, every validator checks shape, expiry and value balance, that the anchor is an accepted tree root, that both nullifiers are unused, the spend and binding signatures, and the proof. If all pass, the same transaction creates two permanent nullifier accounts, appends two note commitments and moves the fee from the pool to the relay. 1 · YOUR DEVICE Selects up to two unspent notes Builds the proof and signs the payment Encrypts the two new notes Keys and note contents do not leave it payment packet proof, ciphertexts, public fields 2 · GATEWAY AND RELAY Gateway checks membership and limits Relay signs the transaction, pays its fee one transaction 3 · EVERY VALIDATOR, IN EXECUTION Shape, expiry and value balance Anchor is an accepted tree root Both nullifiers are unused Spend and binding signatures Proof If all pass, in the same transaction: + 2 nullifier accounts (permanent) + 2 note commitments, new tree root Fee moves from the pool to the relay
A private send on the devnet path. The fee comes out of the notes being spent.

Which anchors are accepted

A wallet must build its proof against a root the validator still remembers, so a proof cannot be kept for long before it is submitted.

  • In the pool format used by the workspace’s validator (NPOOL003), the pool keeps the 64 most recent roots.
  • In the slot-anchored format used by the Agave 4.3.2 candidate (NPOOL004), the pool records one root per completed slot and accepts roots for 512 slots. The code states it exactly: “A slot root of age 511 is valid; age 512 is expired.” The root of the current slot is never eligible.

The browser wallet sets a payment’s expiry to the current slot plus 512 and asks for a new review if that slot has passed before sending.

Fees for private transfers

Something has to pay the public costs of the outer transaction: the transaction fee and the rent of the two nullifier accounts. The protocol has one field for this, the sponsor, and three ways to fill it.

Three ways to pay fees
ModeWho paysWhat it makes public
Development sponsorAn operator account pays for everything. Used on local fixtures; tester profiles forbid it.The sponsor account, the fees and the timing.
User’s public fee accountA separate public key derived from the wallet’s seed. It has to be funded publicly in advance.The fee account, its funding source, the fees and the timing.
Shielded feeA relay pays the public costs. The payment itself pays the relay an exact fee out of the notes being spent.The relay account, the exact fee and the timing.

The devnet browser wallet uses the third mode. The wallet asks the gateway for a quote, shows the fee, and refuses a quote above its own maximum. It then builds a payment whose public value balance equals the fee and whose sponsor is the relay’s account. The validator pays the relay out of the pool in the same transaction that records the payment. A shielded-fee payment cannot also withdraw to a public recipient.

The user needs no public coins for this. A submission that fails or is aborted costs the relay, not the user’s shielded balance; only a successful payment reimburses it.

The cohort tooling in the repository fixes the relay fee at 3,000,000 units (0.003 ZOL). The runbook describes such values as “development units, not final fee policy”.

Deposits and withdrawals

A deposit moves native coins from a public account into the pool account, and the pool’s recorded backing rises by the same amount. A withdrawal does the reverse. Both are visible: the amount and the public account are public.

A recipient-bound withdrawal names its public recipient inside the signed digest, so the recipient cannot be swapped by whoever submits the transaction. The recipient must be an ordinary public account that is different from the sponsor.

Limits of the design

  • Two actions, two inputs. A payment can spend at most two notes. If an amount exceeds the value of the two largest unspent notes, the wallet rejects it even when the total balance is higher.
  • One asset. The pool holds only the native coin.
  • One shared pool account. Every payment writes to it, so payments are serialised. No throughput figure is claimed.
  • A fixed-depth tree. The pool refuses new payments at 4,294,967,294 commitments. Tree rollover is future work.
  • Experimental formats. Account formats, wire formats and identifiers are development values and have changed between pool versions without migration.
  • No independent review. No independent cryptographic review or security audit has been completed.

The byte-level details are in the protocol reference. What all of this hides and does not hide is on the privacy boundary page.

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.