Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Integration guidelines

How a client should build, quote, submit and recover a private payment, and what it must handle.

These rules are drawn from what the project’s own wallets do and from its design records. The browser wallet’s worker (clients/browser-wallet/product-worker.js) and the command-line wallet (clients/wallet/src) are the reference implementations. Nothing here has been independently reviewed.

The shape of a client

A client has four parts: keys that stay on the device, the wallet core that builds proofs and replays history, durable local storage, and a transport to an RPC endpoint or gateway. The core is deliberately free of RPC, files and clocks; the host supplies them and is responsible for them.

One rule runs through everything below: a client writes down what it is about to do before it does it, and never replaces a payment whose outcome it does not know.

1. Sync before anything else

  • Check the network first. Compare getGenesisHash with the configured network and stop on a mismatch.
  • Replay full finalized history. Download finalized blocks, check that each block’s parent slot and hash continue the previous one, and replay the payment transactions through the wallet core. A gap or discontinuity is a hard error, never a partial balance.
  • Reconcile with the pool. After replay, the reconstructed tree must match the finalized on-chain pool account at the same slot.
  • Never go backwards. If the endpoint shows a state older than the saved checkpoint, refuse. The browser wallet’s message is “Finalized RPC state is behind your saved wallet. Recovery will not roll it back.”
  • Show only a verified balance. Do not display a balance, and do not enable sending, until a sync has completed and its checkpoint is saved.

What this does and does not verify: proofs, signatures and continuity of the history supplied by the endpoint. It is not a light client. “RPC consensus is trusted.”

2. Quote

For a shielded-fee send, the browser wallet does this, in this order:

  1. Refuse if a pending payment is saved. Resolve it first.
  2. Sync again, so the proof is built against current state.
  3. Call getShieldedFeeQuote and validate the answer: the expected format, this network, a fee above zero and at most 100,000,000 units, the expected transport and pool format. Reject anything else.
  4. Check that amount plus fee is no more than the balance and no more than the two largest unspent notes together.
  5. Read the current slot and set the expiry to that slot plus 512.
  6. Show the user the recipient, the amount, the maximum fee and the total, and keep the review bound to the exact wallet state it was made from.

The fee the user approved is a cap. The core refuses to build a payment whose quoted fee exceeds it.

3. Build

Build the proof on the device. The payment binds the recipient, the amount, the fee, the relay account and the expiry; none of them can be changed afterwards without invalidating it.

Before sending, compare what the core returned with what the user reviewed (amount, fee, expiry). If the wallet state changed since the review, or the expiry slot has passed, stop and ask for a new review. Nothing has been broadcast at this point.

4. Save, then submit once

  1. Save the exact payment durably before any network call. The browser wallet reserves it in storage and only then reads the packet back out; its comment says a crash before or after leaves “one durable immutable reservation, never a replacement send”.
  2. Submit that packet once.
  3. Treat every failure of the submit call as “unknown”. A timeout, a dropped connection, an error reply or a capacity error does not tell you the payment failed. In the words of the design record: “a lost response is not authorization for another payment.”

Resending the same packet is safe: the relay derives the job id from the packet and returns the same id. Building a new payment for the same intent is not safe until the first one is resolved.

5. Confirm from finalized history only

A payment is done when the client has found that exact payment in finalized canonical history, not before.

  • The relay’s status (pending, accepted, aborted) is a hint that decides when to look. It never settles the saved payment. “Relay status alone cannot clear an intent.”
  • Retained (compact) history can rebuild a balance but cannot prove that a payment was included or that it was not. Only canonical blocks can.
  • “Pending display, zero-confirmation acceptance and a relay’s acknowledgement do not count as finality.”

There are exactly three outcomes:

Payment outcomes
OutcomeConditionThen
acceptedThe exact payment is in finalized canonical history.Save the new checkpoint and a receipt together; clear the pending record.
expired-absentComplete canonical history from before the payment was created shows no execution, and the chain is past the payment’s expiry.Clear the pending record. The notes are unspent; a new payment may be built.
unknownNeither can be shown yet.Keep the pending record. Block new sends. Try again later.

A payment that was aborted or withheld “remains potentially executable until its signed slot expiry”. That is why absence is only accepted after expiry and with complete coverage.

6. Recovery rules

Recovery rules
SituationWhat the reference wallets do
A pending payment is savedRefuse to quote or send. The command-line wallet says “an unresolved payment exists; run resolve before sending again”.
Crash during a staged uploadDo not resume the upload. Close the staging account (reclaim) after verifying it is the recorded one, then build a new payment. Finalization was never sent, so no note was spent.
Crash after submit, before confirmationResolve the original: look up its signature and, if needed, rescan canonical history. Only accepted, failed or expired-without-execution clears the record.
Lost acknowledgementThe same as above. For relay transports, resend the identical packet; never a new proof and never a higher fee.
The anchor is no longer accepted before uploadStop with “payment anchor is no longer available; sync and prepare a new payment”. Nothing was recorded.
The payment expired without executingThe record is cleared and a new payment is built from a fresh sync. The old proof is never re-signed.
Restore from seed on another deviceBalances and nullifiers come back from history. Unfinished journals do not. Keep one active operation per seed.

Two prohibitions appear throughout the runbooks: never delete a journal to get unstuck, and never treat a quota reset, a wallet recreation or a re-run as a retry.

Fees

  • Shielded fee. The relay quotes a flat fee. The client enforces the user’s cap and the hard ceiling of 100,000,000 units. The fee and the relay account become public. A failed submission costs the relay, not the user.
  • User-paid public fee. The payer is a public key derived from the wallet seed and must be funded in advance. The wallet quotes a maximum gross debit made of refundable staging rent, permanent rent for two nullifier accounts, transaction fees, a repair reserve and a cleanup reserve. The user authorises that maximum with --max-fee-debit, and the amount charged is recorded durably and never reset by a refund or an uncertain outcome.
  • Sponsor. For local fixtures only. Tester profiles reject it.

Whichever mode is used, the recipient receives the full private amount. A withdrawal cannot be combined with a shielded fee.

What must never leave the device

What may leave the device
Stays on the deviceMay leave
The 32-byte seed and the spending keyThe private receiving address (npriv1…)
Viewing keysThe public address and the fee address
Decrypted notes, witnesses and randomnessThe encrypted recovery file, to wherever the user saves it
The passwordSigned access proofs and admission requests
Unencrypted checkpoints and pending paymentsThe finished payment packet: proof, ciphertexts and public fields

The reference wallets have no command or function that exports a seed, a viewing key or a decrypted note. Passwords are read from a private file or standard input, never from a command-line argument or environment variable. The recovery file is the seed encrypted with XChaCha20-Poly1305 under a key from PBKDF2-HMAC-SHA256 with 600,000 rounds, in the format native-wallet-seed-v1.

A browser client should be honest about its limit: “WASM is not an isolated secret vault. A compromised first-party site can steal an unlocked seed or alter a recipient.”

Nullifiers and note discovery

  • Finding notes. Try to decrypt every payment output with both of the wallet’s incoming viewing keys: the external one for received payments and the internal one for change.
  • Spent or unspent. A note is spent when its nullifier appears in replayed history. Compute this from history; do not keep a separate “spent” flag that can drift.
  • Selection. A payment spends at most two notes. Offer the user the largest amount payable from two notes, not the total balance.
  • Anchors age out. Build the proof right after a sync and submit it promptly. “Wallets must synchronize before proving and cannot indefinitely queue proofs.”
  • History is needed from the start. A wallet’s notes are recovered from the encrypted outputs in history. Validator snapshots keep the pool and the nullifier accounts but not old ciphertexts, so a client depends on an endpoint that retains history.

What your service will learn

If you operate a gateway or relay for users, you cannot avoid learning the following, and you should say so to your users:

  • each member’s stable identity (the fee address) and, from admission, the private receiving address tied to it;
  • the network address and timing of every request;
  • which member submitted which payment packet.

You do not learn spending or viewing keys, and you cannot read amounts or recipients from a packet. Everyone, not only you, can see fees, timing, nullifiers and any deposit or withdrawal. The privacy boundary page is the full statement; do not describe an integration as anonymous.

Error codes

Versioned core codes

The wallet core reports errors as zolana-wallet-error-v1:<code>. The worker maps each to a public code and message; unrecognised text becomes wallet_error with “Wallet operation failed; saved data was not reset.” The mapping is pinned by product-worker-errors.test.mjs.

Versioned core error codes
Core codePublic codeMessage
authenticationauthenticationPassword could not open this wallet. Check it and try again.
passwordpasswordUse a password between 12 and 1024 UTF-8 bytes.
backupbackupThis recovery file is invalid or unsupported. Choose your original encrypted Zolana recovery file.
networknetworkThis recovery file’s format or network does not match this wallet. Use the original file for the selected Zolana network.
configurationconfigurationThe wallet’s network configuration is invalid. No saved wallet was changed.
lockedlockedYour wallet is locked. Unlock it to continue.
recoveryrecoverySaved wallet or payment recovery data could not be verified. Keep your recovery file; no state was reset or replacement payment sent.
historysyncNetwork history could not be fully verified. Your last saved checkpoint and original payments were preserved. Try syncing again.
sync_requiredsyncSync and save verified wallet history before reviewing or recovering this payment.
reviewreviewThe recipient, fee or expiry does not match the payment’s bounds. Sync and review the payment again.
internalwallet_errorWallet operation failed; saved data was not reset.

Transport and gateway codes a client must handle

Transport and gateway codes
CodeCauseHandling
connectionTimeout or network failureSafe to repeat a read. After a submit, go to recovery.
rate_limitHTTP 429Wait, then repeat the same request.
accessHTTP 403, or the wallet has not joinedDo not retry. The wallet needs admission.
transportAny other gateway failure, including HTTP 409 on join (cohort full)The outcome may be unknown; check state before repeating.
member_payment_limit, network_payment_limitJSON-RPC -32040 with scope member or networkNo new payment can be sent. A payment already saved still has to be resolved.
rollbackThe endpoint is behind the saved walletRefuse and wait.
pending, pending_unknownAn original payment is unresolvedRecover it. Do not build another.
conflict, review, expiry, fee, balanceThe review no longer matches the wallet, the slot, the quote or the spendable amountNothing was broadcast. Sync and review again.

The worker marks only a few read operations as automatically retryable (retryableRead), and never a submit.

On-chain errors

A failed finalization surfaces as the runtime’s InvalidInstructionData whatever the cause. The command-line wallet therefore reports a finalized failure only as failed. Run the checks from the protocol reference on the client before submitting.

Concurrency

  • One operation per wallet at a time. The command-line wallet takes an exclusive lock file; the worker queues requests and answers busy beyond four.
  • One active operation per seed across devices. Independently restored copies do not share a lock.
  • All payments write the one shared pool account, so the chain processes them one after another.

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.