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
getGenesisHashwith 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:
- Refuse if a pending payment is saved. Resolve it first.
- Sync again, so the proof is built against current state.
- Call
getShieldedFeeQuoteand 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. - Check that amount plus fee is no more than the balance and no more than the two largest unspent notes together.
- Read the current slot and set the expiry to that slot plus 512.
- 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
- 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”.
- Submit that packet once.
- 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:
| Outcome | Condition | Then |
|---|---|---|
accepted | The exact payment is in finalized canonical history. | Save the new checkpoint and a receipt together; clear the pending record. |
expired-absent | Complete 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. |
unknown | Neither 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
| Situation | What the reference wallets do |
|---|---|
| A pending payment is saved | Refuse to quote or send. The command-line wallet says “an unresolved payment exists; run resolve before sending again”. |
| Crash during a staged upload | Do 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 confirmation | Resolve the original: look up its signature and, if needed, rescan canonical history. Only accepted, failed or expired-without-execution clears the record. |
| Lost acknowledgement | The 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 upload | Stop with “payment anchor is no longer available; sync and prepare a new payment”. Nothing was recorded. |
| The payment expired without executing | The 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 device | Balances 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
| Stays on the device | May leave |
|---|---|
| The 32-byte seed and the spending key | The private receiving address (npriv1…) |
| Viewing keys | The public address and the fee address |
| Decrypted notes, witnesses and randomness | The encrypted recovery file, to wherever the user saves it |
| The password | Signed access proofs and admission requests |
| Unencrypted checkpoints and pending payments | The 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.
| Core code | Public code | Message |
|---|---|---|
authentication | authentication | Password could not open this wallet. Check it and try again. |
password | password | Use a password between 12 and 1024 UTF-8 bytes. |
backup | backup | This recovery file is invalid or unsupported. Choose your original encrypted Zolana recovery file. |
network | network | This recovery file’s format or network does not match this wallet. Use the original file for the selected Zolana network. |
configuration | configuration | The wallet’s network configuration is invalid. No saved wallet was changed. |
locked | locked | Your wallet is locked. Unlock it to continue. |
recovery | recovery | Saved wallet or payment recovery data could not be verified. Keep your recovery file; no state was reset or replacement payment sent. |
history | sync | Network history could not be fully verified. Your last saved checkpoint and original payments were preserved. Try syncing again. |
sync_required | sync | Sync and save verified wallet history before reviewing or recovering this payment. |
review | review | The recipient, fee or expiry does not match the payment’s bounds. Sync and review the payment again. |
internal | wallet_error | Wallet operation failed; saved data was not reset. |
Transport and gateway codes a client must handle
| Code | Cause | Handling |
|---|---|---|
connection | Timeout or network failure | Safe to repeat a read. After a submit, go to recovery. |
rate_limit | HTTP 429 | Wait, then repeat the same request. |
access | HTTP 403, or the wallet has not joined | Do not retry. The wallet needs admission. |
transport | Any other gateway failure, including HTTP 409 on join (cohort full) | The outcome may be unknown; check state before repeating. |
member_payment_limit, network_payment_limit | JSON-RPC -32040 with scope member or network | No new payment can be sent. A payment already saved still has to be resolved. |
rollback | The endpoint is behind the saved wallet | Refuse and wait. |
pending, pending_unknown | An original payment is unresolved | Recover it. Do not build another. |
conflict, review, expiry, fee, balance | The review no longer matches the wallet, the slot, the quote or the spendable amount | Nothing 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
busybeyond 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.