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
| Recipe | Language | What you get |
|---|---|---|
| Decode a payment | JavaScript | The public fields of a payment, from its bytes |
| Verify a payment offline | Rust | A check of the signatures and the proof, and a list of what that does not cover |
| Watch the pool account | JavaScript | The pool’s note count, backing and latest root, from a file or from an RPC endpoint |
| Check that a payment landed | JavaScript | What the devnet explorer feed says about a transaction |
| Check an address | JavaScript | A 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-withdrawalorshielded-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.
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 accountin the report is the address to look up withgetAccountInfo: 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::decodedoes. - 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.
okandfeecome from the node’s execution record when the service read the block in full. When the node returned signatures only, the service reportsok: trueand 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.
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.
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.