All crates are version 0.1.0, edition 2021, Rust 1.92, MIT. None is published to a registry. The Developer SDK shows how to depend on three of them from your own project.
Crates
| Package | Path | What it is |
|---|---|---|
native-payments | protocol/payments | In-process verification primitives: wire encoding, the verifier, pool state, anchors, staging and the inline envelope. Its own description: “This library does not mutate a ledger, authorize a deposit debit, or constitute a deployed chain.” |
native-payment-program | node/adapter | The native program’s entrypoint and instruction builders. “Metered native payment entrypoint for the local development network.” |
native-wallet-core | clients/wallet-core | Proof construction and checked note replay shared by the native and browser wallets. “No RPC, filesystem, thread management or host clock belongs here.” |
native-wallet-seed | clients/wallet-seed | Codec for the encrypted seed file (native-wallet-seed-v1). No filesystem, Orchard or RPC. |
native-wallet | clients/wallet | The command-line wallet library and its binaries. “Experimental local wallet. RPC consensus is trusted; keys never leave this process.” |
zolana-browser-core | clients/browser-core | The browser wallet’s Rust core, built as a Wasm library (cdylib) and as an ordinary Rust library for native tests. |
payment-lab | clients/cli | Public synthetic fixtures and the proof-smoke command. |
native-validator-check | node/validator-check | Signed-transaction checks against the modified Agave Bank. Tests only. |
native-localnet | node/localnet | Disposable local-network tooling. “Fixture spending keys are intentionally public.” |
native-rpc-access | node/rpc-access | Operator capability for loopback raw RPC. Not for wallets. |
The verification API in one example
This is Fixture::check from clients/cli/src/proof_smoke.rs, the code behind proof-smoke. It encodes a payment, stages it in 768-byte chunks as the chain would receive it, decodes it and verifies it:
pub fn check(&self) -> Result<Report, Error> {
let bytes = wire::encode(self.network, &self.context, &self.bundle)?;
let size = bytes.len();
let mut staged = StagedPayload::new(size, payload_digest(&bytes))?;
for (i, chunk) in bytes.chunks(MAX_CHUNK_BYTES).enumerate() {
staged.append(i * MAX_CHUNK_BYTES, chunk)?;
}
staged.seal()?;
let decoded = wire::decode(self.network, &staged.into_payload()?)?;
let empty = BTreeSet::new();
let started = Instant::now();
self.verifier
.verify(&decoded.bundle, &decoded.context, &self.view(&empty))?;
// ...
}
The verifier is built with PaymentVerifier::new(genesis, verifying_key) and is read-only. The ValidationView it takes (current slot, accepted anchors, spent nullifiers, authorised public value balance) must come from authenticated node state; the crate’s doc comment says “never values asserted by an untrusted RPC caller”.
The wallet core
native-wallet-core is the part a wallet integration is built on. Its main entry points:
trait WalletKeys: the host supplies the network domain, the genesis hash and the spending key.encode_addressanddecode_address: thenpriv1address format.enum Payment:Deposit,Send,ShieldedSend,WithdrawandWithdrawTo.payments::validateandPaymentProver::build: check a payment against wallet state and build its proof bytes.WalletStateandReplay: replay verified history into notes, a balance and witnesses.
The crate states that “nothing in this crate is directly exported as a WASM ABI”; the browser reaches it through zolana-browser-core.
Binaries
payment-lab
Usage: payment-lab proof-smoke
Runs an offline cryptographic fixture, not a deployed-chain payment.
native-wallet
The first line of its help lists the commands:
native-wallet init|restore|address|balance|fees|deposit|send|withdraw|resolve|reclaim|archive|check|profile|test-coins|join|access-status
| Command | What it does |
|---|---|
init, restore | Create a wallet with a new random seed, or restore one from an encrypted backup. Both take --backup. |
address | Print the wallet’s addresses. Needs no RPC. |
balance | Sync and print the verified finalized balance, the unspent-note count and the largest amount payable from two notes. |
fees | Show the user fee address, refundable rent, a gross-debit quote and any funding shortfall. --payment send|withdraw selects the payment shape. |
deposit, send, withdraw | Make a payment. --amount is in native units; --to is an npriv1 address for deposits and sends, a public address for withdrawals. |
resolve | Determine the outcome of a recorded pending payment. |
reclaim | Close a recorded interrupted upload after any pending payment is resolved. |
archive | Collect retained public history into a directory. Needs no wallet or password. |
check, profile | check validates the RPC against the network configuration and needs no wallet or password. profile prints a tester profile’s public configuration. |
test-coins, join, access-status | Tester-profile commands: request the one-time grant, join with an invitation file, check admission. |
Options every wallet command takes:
--network <network.json> --wallet <encrypted-seed.json> --password-file <private-file|->
Fee options select who pays: --sponsor <keypair.json> on local fixtures, --fee-payer user --max-fee-debit <native-units> for the wallet’s own public fee account, or --fee-payer shielded --max-shielded-fee <cap> on native-inline profiles. User-paid and shielded fees cannot be combined with sponsor options. On failure the wallet prints Wallet error: … to standard error and exits with status 1. Setting NATIVE_WALLET_PROGRESS=1 makes it print progress phases as JSON lines.
native-shielded
A separate entrypoint for shielded-fee sends: send, resolve and the operator-only relay.
native-shielded send --network tester-profile.json --wallet wallet.enc.json \
--password-file - --amount <native-units> --to <private-address> \
--max-shielded-fee <maximum-native-units>
native-shielded resolve --network tester-profile.json --wallet wallet.enc.json \
--password-file -
native-faucet
Operator tooling for test grants and admission: init, init-native, accept, tick, and the access commands (access-init, invite-issue, invite-revoke and others). It has no help text. See docs/test-faucet-runbook.md and docs/invited-testnet-runbook.md.
native-localnet and native-validator
native-localnet prepares and exercises disposable networks (init, exercise, recovery-check and a set of fault and restart commands). It is normally driven through tools/localnet.py. native-validator reuses the upstream validator command line with this workspace’s payment program linked in.
Checkers
browser-core-check verifies a public synthetic browser proof packet read from standard input, without a network. browser-vault-check prints a disposable creation and recovery reference. native-fast-cash is, in its own words, an “isolated synthetic fixture CLI, not an update to an existing wallet app”.
The browser core
zolana-browser-core compiles to WebAssembly with wasm-bindgen 0.2.129. Its JavaScript-facing surface is one class and a few functions.
| Group | Methods |
|---|---|
| Create and open | BrowserVault.create(network_json, password), BrowserVault.restore(network_json, encrypted, password), unlock(password), lock(), is_locked() |
| Identity and backup | identity() returns the private address, public address and fee address as JSON; encrypted_backup() returns the encrypted recovery bytes |
| Sync | checkpoint_info, begin_sync, apply_history_page, apply_compact_history_page, apply_canonical_blocks, apply_archival_page, finish_sync, payment_status |
| Payments | build_payment, pending_packet, validate_pending_checkpoint, pending_outcome |
| Gateway access | admission_claim_id, rpc_header, admission_request, admission_status |
Free functions: prepare_wallet_prover(), vault_acceptance(), and the synthetic fixture functions version(), prepare_prover(), synthetic_fixture() and decrypt_fixture(). A threaded build is behind the browser-multicore feature, which needs shared Wasm memory, cross-origin isolation and an initialised thread pool.
The shapes of the JSON these methods take and return are typed in sdk/js/zolana-browser-core.d.ts.
The division of labour is fixed by the core: seeds, note decryption and proof construction stay inside Rust; JavaScript owns durable encrypted storage and bounded transport. Errors cross the boundary as versioned strings of the form zolana-wallet-error-v1:<code>; the codes are listed in Integration guidelines.
There is no prebuilt Wasm artifact. You build it with sdk/build-browser-core.sh, which covers the single-threaded package; the Developer SDK page lists what it needs. The repository does not record the compiler flags for the threaded package. The wallet page expects the output as browser_core.js and browser_core_bg.wasm under /wasm/ or /wasm-parallel/.
The browser wallet’s worker
The wallet page talks to one module worker, clients/browser-wallet/product-worker.js. The page posts { id, action, ...params } and receives { id, ok: true, result } or { id, ok: false, code, error }, plus progress events.
The accepted actions are:
initialize create restore unlock lock backup status check_access join
sync payment_hint automatic_sync cancel_review quote_payment send recover_pending
Nothing in the repository presents the worker as a library for third parties. It is one packaged asset of the wallet page: it fetches /transport.json, /rpc, /admission/join and /admission/status from its own origin and imports the Wasm core from a fixed path. Read it as the reference implementation of a client, which is how Integration guidelines uses it. Its behaviour is pinned by the Node test suites next to it (product-worker-*.test.mjs), which run without a browser.