Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Crates and command-line tools

Every crate and binary in the workspace that a developer can use, with its commands.

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

Workspace crates
PackagePathWhat it is
native-paymentsprotocol/paymentsIn-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-programnode/adapterThe native program’s entrypoint and instruction builders. “Metered native payment entrypoint for the local development network.”
native-wallet-coreclients/wallet-coreProof construction and checked note replay shared by the native and browser wallets. “No RPC, filesystem, thread management or host clock belongs here.”
native-wallet-seedclients/wallet-seedCodec for the encrypted seed file (native-wallet-seed-v1). No filesystem, Orchard or RPC.
native-walletclients/walletThe command-line wallet library and its binaries. “Experimental local wallet. RPC consensus is trusted; keys never leave this process.”
zolana-browser-coreclients/browser-coreThe browser wallet’s Rust core, built as a Wasm library (cdylib) and as an ordinary Rust library for native tests.
payment-labclients/cliPublic synthetic fixtures and the proof-smoke command.
native-validator-checknode/validator-checkSigned-transaction checks against the modified Agave Bank. Tests only.
native-localnetnode/localnetDisposable local-network tooling. “Fixture spending keys are intentionally public.”
native-rpc-accessnode/rpc-accessOperator 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_address and decode_address: the npriv1 address format.
  • enum Payment: Deposit, Send, ShieldedSend, Withdraw and WithdrawTo.
  • payments::validate and PaymentProver::build: check a payment against wallet state and build its proof bytes.
  • WalletState and Replay: 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
native-wallet commands
CommandWhat it does
init, restoreCreate a wallet with a new random seed, or restore one from an encrypted backup. Both take --backup.
addressPrint the wallet’s addresses. Needs no RPC.
balanceSync and print the verified finalized balance, the unspent-note count and the largest amount payable from two notes.
feesShow the user fee address, refundable rent, a gross-debit quote and any funding shortfall. --payment send|withdraw selects the payment shape.
deposit, send, withdrawMake a payment. --amount is in native units; --to is an npriv1 address for deposits and sends, a public address for withdrawals.
resolveDetermine the outcome of a recorded pending payment.
reclaimClose a recorded interrupted upload after any pending payment is resolved.
archiveCollect retained public history into a directory. Needs no wallet or password.
check, profilecheck 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-statusTester-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.

BrowserVault methods
GroupMethods
Create and openBrowserVault.create(network_json, password), BrowserVault.restore(network_json, encrypted, password), unlock(password), lock(), is_locked()
Identity and backupidentity() returns the private address, public address and fee address as JSON; encrypted_backup() returns the encrypted recovery bytes
Synccheckpoint_info, begin_sync, apply_history_page, apply_compact_history_page, apply_canonical_blocks, apply_archival_page, finish_sync, payment_status
Paymentsbuild_payment, pending_packet, validate_pending_checkpoint, pending_outcome
Gateway accessadmission_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.

Limit

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.

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.