Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Cookbook

Five short recipes on the SDK: decode a payment, verify one offline, watch the pool account, check that a payment landed, and check an address. Each runs from a checkout on fixtures.

Status

Source only, not audited. The recipes use the Developer SDK from a checkout. Nothing is published to npm or crates.io, the formats are experimental and can change without migration, and the code has not been independently audited.

Fixtures, not a network. Each recipe runs with no network, no node and no funds. The inputs are fixtures in sdk/fixtures: real payments with real proofs, made on a fixture network with public, disposable keys. They are not payments of any deployed network and move nothing.

The public devnet admits cohort wallets only. Devnet test coins are valueless and distinct from the ZOL token. Develop against a local network.

The cookbook is a directory in the repository: docs/cookbook. This page presents its five recipes. Every command, code block and output below is copied from those files; the notes are shortened, and each recipe links to its full text.

The recipes

The five recipes
RecipeLanguageWhat you get
Decode a paymentJavaScriptThe public fields of a payment, from its bytes
Verify a payment offlineRustA check of the signatures and the proof, and a list of what that does not cover
Watch the pool accountJavaScriptThe pool’s note count, backing and latest root, from a file or from an RPC endpoint
Check that a payment landedJavaScriptWhat the devnet explorer feed says about a transaction
Check an addressJavaScriptA typing and network check of a shielded address before you pay it

Before the first recipe, clone the repository. The JavaScript recipes need only Node.js: they have no dependencies and nothing is installed. The Rust recipe needs the toolchain and the one-time fetch of the SDK quick start, and its first build compiles the proof system.

Decode a payment

A payment is a fixed layout of bytes: a tag, the network it is for, a few public fields, two actions, a proof and a signature. decodePayment in sdk/js/formats.mjs reads the public part.

node sdk/js/examples/decode-payment.mjs

With no argument the example reads a fixture: Alice pays Bob 40 units with a shielded fee of 3. Pass a file that holds a payment as hex to read your own.

const payment = decodePayment(hex);
console.log(`${payment.kind}: ${payment.bytes} bytes, tag ${payment.tag}`);
console.log(`network       ${payment.network}`);
console.log(`payment id    ${payment.paymentId}`);
console.log(`expiry slot   ${payment.expirySlot}`);
// Negative: value enters the pool. Zero: none moves. Positive: it leaves.
console.log(`public value  ${payment.publicValueBalance}`);
console.log(`shielded fee  ${payment.shieldedFee}`);
console.log(`sponsor       ${payment.sponsor}`);
console.log(`anchor        ${payment.anchor}`);
for (const action of payment.actions) {
  console.log(`nullifier     ${action.nullifier}`);
  console.log(`commitment    ${action.commitment}`);
}
shielded-fee-payment: 9230 bytes, tag NPAY0003
network       0707070707070707070707070707070707070707070707070707070707070707
payment id    2b8296f7d96e1f6077bdc31d4541859544c849af0bcd5261aedacd50225c8832
expiry slot   100
public value  3
shielded fee  3
sponsor       6cGXszer5keoaWm8Co5G9f4KGBThuGz4NsKTqYij1emg
anchor        1fbe1c80664a1b478518e05c8029b49418782b2c39b077cf627d4af0b0b5b31d
nullifier     6154b85afc11f06db91f2f7a1f9a860a0e7504217cb12dbd3422e16abb179604
commitment    593c0de55f92909e654bfc77e9307b582c2ff968fd2760f0c1cb4149b0293b02
nullifier     f017eb9715131a11a425e3a24d208b3ea7399541f71575ffe7a5303af95b6c27
commitment    5a4f325f4f2ea8d2f6b4f648215dabedc1d138a51a5fe71853eb27a2188ff82b
for another network: WrongNetwork
  • kind follows from the tag and the sign of the public value: deposit, private-send, sponsor-withdrawal, recipient-withdrawal or shielded-fee-payment.
  • public value is negative when coins enter the pool, zero when none move and positive when they leave. Here it is the fee of 3, paid to the sponsor account. The 40 units and the recipient are not in the public fields.
  • payment id is the BLAKE2b-256 digest of the bytes. The relay returns it from submitShieldedPayment.
  • nullifier and commitment: every action carries one of each, whether or not it spends or creates a real note. The bytes do not say which.
Limit

Decoding does not verify the signatures or the proof, and it does not check that the two 32-byte keys of an action are valid curve points. A decoded payment says what the bytes claim. To check the claim, use the next recipe.

An inline envelope (ZOLNPAY1) around a payment is opened with decodeEnvelope, which also checks that the payment is the one the envelope names. Full recipe: docs/cookbook/decode-a-payment.md.

Verify a payment offline

inspect-payment decodes a payment and checks its spend authorization signatures, its binding signature and its proof, with the same PaymentVerifier a validator uses. It needs no RPC and no ledger.

sh tools/dev.sh run --offline --locked -p zolana-sdk-examples --bin inspect-payment -- sdk/fixtures/shielded-send.hex

The input is a payment or an inline envelope, as raw bytes, hex or base64: a file, the argument itself, or - for standard input. --json prints one JSON object instead, and --network <64 hex digits> refuses a payment made for any other network. The repository records that the whole command took about two seconds on an Apple Silicon Mac.

input                9230 bytes, tag NPAY0003
kind                 shielded-fee-payment
network              0707070707070707070707070707070707070707070707070707070707070707
payment id           2b8296f7d96e1f6077bdc31d4541859544c849af0bcd5261aedacd50225c8832
expiry slot          100
public value         3 units leave the pool to the sponsor as the fee
shielded fee         3
sponsor              6cGXszer5keoaWm8Co5G9f4KGBThuGz4NsKTqYij1emg
anchor               1fbe1c80664a1b478518e05c8029b49418782b2c39b077cf627d4af0b0b5b31d
action 0
  nullifier          6154b85afc11f06db91f2f7a1f9a860a0e7504217cb12dbd3422e16abb179604
  nullifier account  6NB5KEfy2yJmqRC7axs9zBHCFMbz73kKatsHiExsEkVp
  commitment         593c0de55f92909e654bfc77e9307b582c2ff968fd2760f0c1cb4149b0293b02
action 1
  nullifier          f017eb9715131a11a425e3a24d208b3ea7399541f71575ffe7a5303af95b6c27
  nullifier account  9eY7J7nSSJqqG2hGhZd3dJkRTwmD1dBZGYvakxCgFnAe
  commitment         5a4f325f4f2ea8d2f6b4f648215dabedc1d138a51a5fe71853eb27a2188ff82b
verified             the spend authorization signatures, the binding signature and the proof
not revealed         the shielded addresses, the value of each note and the memos
                     which actions spend or create a real note, and which are padding
not checked          that any chain accepts this anchor
                     that the nullifiers are unspent
                     the current slot: the verifier accepts this payment from slot 0 through slot 100
                     that the public accounts exist and can pay or be paid
                     that the payment was ever submitted or finalized

The exit status is 0 when the signatures and the proof are valid, 1 when the bytes decode but do not verify, and 2 when they cannot be read or decoded.

What “verified” means here

A validator verifies a payment against state it has authenticated: the current slot, the roots it accepts as anchors, the nullifiers already spent, and the public value the transaction is allowed to move. Offline there is no such state, so the command takes all four from the payment itself:

    let anchor = bundle.anchor().to_bytes();
    let (anchors, spent) = (BTreeSet::from([anchor]), BTreeSet::new());
    let view = ValidationView {
        current_slot: context.expires_at,
        accepted_anchors: &anchors,
        spent_nullifiers: &spent,
        authorized_public_value_balance: context.public_value_balance,
    };
    let verification = PaymentVerifier::with_shared_key(network, Arc::clone(key))?
        .verify(bundle, context, &view)
        .map(|_| ());

That is enough to show that the bytes are internally valid: the signatures match the payment, and the proof holds for the anchor it names. It is not enough to show that a chain would accept them. None of the following can be checked from the bytes alone:

  • whether the anchor is a root a chain accepts;
  • whether the nullifiers are unspent. Each nullifier account in the report is the address to look up with getAccountInfo: an existing account owned by the payment program means spent;
  • whether the current slot is inside the window the report gives;
  • whether the public accounts exist and can pay or be paid;
  • whether the payment was ever submitted or finalized.

The same check is available as a library function, inspect in sdk/rust-examples/src/inspect.rs. Full recipe: docs/cookbook/verify-a-payment-offline.md.

Watch the pool account

All shielded value sits behind one account, the pool. Its data holds the note count, the backing (the public coins held for the notes) and the recent roots of the note tree. decodePoolAccount in sdk/js/formats.mjs reads it.

node sdk/js/examples/watch-pool.mjs

With no argument the example decodes a fixture: the pool after a deposit of 100, a send with a fee of 3 and a withdrawal of 20.

function describe(data) {
  const pool = decodePoolAccount(new Uint8Array(Buffer.from(data, "base64")));
  const latest = pool.slotAnchors.at(-1);
  return `${pool.tag}: ${pool.noteCount} notes, backing ${pool.backing}` +
    (latest ? `, latest root ${latest.root} at slot ${latest.slot}` : "");
}
NPOOL004: 6 notes, backing 77, latest root 30948a46bf1dae55da625ae554938b4b003dfd3ea6b660bacfecae57155bee1a at slot 3

Six notes are three payments of two actions each, and the backing is 100 less the fee of 3 and the withdrawal of 20.

Against an endpoint

node sdk/js/examples/watch-pool.mjs --url http://127.0.0.1:18899

That is the default RPC address of a local network. The example asks for the account every two seconds and prints a line when it changes:

  const rpc = createRpcClient({ url });
  let previous;
  for (let poll = 0; poll < polls; poll++) {
    if (poll > 0) await sleep(interval);
    const account = await rpc.getAccountInfo(POOL_ADDRESS);
    if (account.value === null) throw new Error("this network has no pool account");
    // The pool is the account at this address that the payment program owns.
    if (account.value.owner !== PROGRAM_ID) throw new Error("the account is not owned by the payment program");
    const line = describe(account.value.data[0]);
    if (line !== previous) console.log(`slot ${account.context.slot}: ${line}`);
    previous = line;
  }

The pool address and the program id are fixed development values; POOL_ADDRESS and PROGRAM_ID are exported by formats.mjs. acceptedRoots(pool, slot) returns the roots a payment may be anchored to when it executes at a slot: the roots of completed earlier slots younger than 512 slots.

  • This polls with getAccountInfo. The SDK’s client has no subscription.
  • The decoder checks the layout and the bookkeeping rules but does not recompute the tree root from the stored frontier. The Rust PoolState::decode does.
  • An account is only as trustworthy as the endpoint that served it. A wallet replays finalized history and reconciles the result with this account; it does not take balances from it.
  • The loop was tested against a loopback server that serves the fixture, not against a validator.

Full recipe: docs/cookbook/watch-the-pool-account.md.

Check that a payment landed

The devnet explorer page shows a feed of recent blocks and transactions. sdk/js/explorer.mjs reads the same document: validateExplorerFeed applies the feed contract, and findTransaction looks a signature up.

node sdk/js/examples/payment-landed.mjs

With no argument the example reads the sample feed in clients/devnet-explorer and looks up its newest transaction, its oldest one and a signature it does not hold. Pass signatures to look up your own, and --feed <file or URL> to read another feed.

const feed = validateExplorerFeed(JSON.parse(text));
const finalized = feed.network.finalized_slot;
console.log(`feed ${feed.format}: status ${feed.network.status}, finalized slot ${finalized ?? "unknown"}, ${feed.transactions.length} transactions in the window`);

const signatures = wanted.length > 0 ? wanted
  : [feed.transactions[0].signature, feed.transactions.at(-1)?.signature ?? "", "1".repeat(64)];
for (const signature of signatures) {
  const found = findTransaction(feed, signature);
  if (found === null) {
    // Not in the window. This says nothing about whether it was ever executed.
    console.log(`${signature}\n  not in the feed's window`);
    continue;
  }
  const { transaction, atOrBelowFinalized } = found;
  const place = atOrBelowFinalized === null ? "the feed reports no finalized slot"
    : atOrBelowFinalized ? "at or below the feed's finalized slot" : "above the feed's finalized slot: look again later";
  console.log(`${signature}\n  slot ${transaction.slot}, ${transaction.ok ? "no error recorded" : "failed"}, fee ${transaction.fee}, ${place}`);
}
feed zolana-explorer-feed-v0: status live, finalized slot 254839, 37 transactions in the window
4m8QYMPsQaqE45rVXdXLPQp1EnRjGGpKdwgoNg8ZuWbkQfgffdGmFVHG3YiEMDzVJvgeNhEMb8iHicTGquV9Zf6U
  slot 254867, no error recorded, fee 5000, above the feed's finalized slot: look again later
4x12uCZs95HQKtXoDhpom9Gry6Go7Fta7hzb3osKZHBSpPSx8NYtj2XKUAwocY9dGsUL5DGHg5PZw17Uzoiuv8zZ
  slot 250981, no error recorded, fee 5000, at or below the feed's finalized slot
1111111111111111111111111111111111111111111111111111111111111111
  not in the feed's window

Where the signature comes from: sendTransaction returns it, and for a payment handed to the relay getShieldedPaymentStatus carries a signature field once the payment’s state is accepted or aborted.

Read the answer for what it is:

  • A match means the feed service read a block that lists the signature. ok and fee come from the node’s execution record when the service read the block in full. When the node returned signatures only, the service reports ok: true and a fee of 0 for every transaction of that block.
  • At or below the finalized slot compares the transaction’s slot with the finalized slot the feed reports. The service may list a block before it is finalized.
  • No match means the signature is not in the window: at most 200 transactions and 120 blocks. It does not mean the transaction failed or was never sent.
  • The feed is a convenience view. It carries no signature a reader can check, and it is not history. A wallet settles a payment from finalized blocks; the relay’s status is a hint as well.
Checked

The explorer page loads the feed from /explorer/feed.json on its own origin. The example was tested with the sample file and with a loopback server, not against a deployed explorer.

Full recipe: docs/cookbook/check-that-a-payment-landed.md. The feed itself is described on the Explorer page.

Check an address

A shielded address is text that starts with npriv1. It carries a version, a tag that binds it to one network, the address bytes and a 4-byte checksum. checkAddress in sdk/js/formats.mjs checks all of that before anything is paid.

node sdk/js/examples/check-address.mjs

With no argument the example checks a fixture address on the fixture network of the SDK examples. Pass an address to check your own against that network.

function report(label, text, on) {
  try {
    checkAddress(text, on);
    console.log(`${label}: well formed, and for this network`);
  } catch (error) {
    if (!(error instanceof FormatError)) throw error;
    console.log(`${label}: refused (${error.message})`);
  }
}

report("the address", address, network);
// One wrong character breaks the checksum.
const swapped = address.at(-1) === "x" ? "y" : "x";
report("one character changed", address.slice(0, -1) + swapped, network);
// The same text is refused on a network with another domain.
report("on another network", address, { ...network, network: "08".repeat(32) });
the address: well formed, and for this network
one character changed: refused (WrongNetwork: receiving address checksum or network mismatch)
on another network: refused (WrongNetwork: receiving address checksum or network mismatch)

A network is a 32-byte domain and a base58 genesis hash. A wallet has both in its network identity, and getGenesisHash returns the second. Without the second argument checkAddress checks the text alone and returns the network tag it carries.

Limit

One thing is left to the Rust decoder: checkAddress does not check that the 43 address bytes are a valid shielded address. decode_address in native-wallet-core does, and the wallets call it before they build a payment.

Full recipe: docs/cookbook/check-an-address.md.

How the recipes stay true

In the repository, every JavaScript or Rust block of a recipe is a passage of a file, and every output block is what that file printed. sdk/js/cookbook.test.mjs checks both on each test run: it compares the code blocks with the files, runs the JavaScript examples and compares what they print, and compares the Rust command’s output with a file that the Rust tests compare with the command.

node --test sdk/js/*.test.mjs
sh tools/dev.sh test --offline --locked -p zolana-sdk-examples

On this page, each block is in turn compared with the repository’s recipe, and where it is code or a stored report, with the source file as well, by the check that holds these docs to the repository. If the page and the repository ever differ, the repository is right.

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.