Version 0.1, source only. The SDK is a directory in the repository: sdk. Nothing is published to crates.io or npm, and there is no prebuilt Wasm module. You clone the repository and build from it.
Not audited, devnet only. Neither the protocol code nor the SDK has been independently reviewed. The only network is a devnet with valueless test coins, and it admits cohort wallets only.
Experimental formats. Wire formats, account layouts, identifiers and the custom RPC methods can change without migration.
What is in it
| Part | Path | What it gives you |
|---|---|---|
| Examples | sdk/rust-examples | Six offline Rust programs and a test file, as the workspace package zolana-sdk-examples. |
| Walk-through | sdk/EXAMPLES.md | Every example with its command and the output it printed. |
| Wasm build script | sdk/build-browser-core.sh | Builds the browser wallet core to WebAssembly with pinned tool versions. |
| Types | sdk/js/zolana-browser-core.d.ts | TypeScript types for the browser core, including the shapes of its JSON results. |
| RPC client | sdk/js/rpc.mjs | A dependency-free JSON-RPC client for the methods the wallets call, with types and tests. |
The SDK’s own README is the reference. This page is the short version.
Quick start
You need Git, Rust 1.92 and a C/C++ toolchain; Build and run the code has the details. The fetch step needs network access. Everything after it runs offline.
git clone https://github.com/zolanacom/zolana.git
cd zolana
sh tools/dev.sh fetch --locked
sh tools/dev.sh run --offline --locked -p zolana-sdk-examples --example wallet_address
The last command derives a wallet from a public fixture seed and prints:
recovery file: format native-wallet-seed-v1, 1259 bytes
wrong password: password is incorrect or encrypted seed was modified
private address: npriv1gZWMfgeB9UAafpZyPa5Pf92AdWqYpJKVgDuHNf7Z7JGnpxQSqAYXtCgvrYcFkwfzSUDXFBDx5gtWuSQnRnGCDr6fVn3Ba7NwiuLA386Xd2dV
same text on another network: receiving address checksum or network mismatch
The size of the recovery file varies by a few bytes from run to run. fetch downloads the dependencies of the whole workspace, including the validator’s; the examples compile only the crates they need.
The examples
All six are offline: no RPC, no ledger, no funds, public fixture keys. Each source file is under 80 lines. Run one with:
sh tools/dev.sh run --offline --locked -p zolana-sdk-examples --example <name>
wallet_addresswrites and reads the encrypted recovery file, derives thenpriv1address and decodes it again. It builds no proof.verify_proofverifies the repository’s proof fixture the way a validator does, then shows a second spend, a flipped proof bit and another network being refused. The fixture holds two real proofs.wire_messagebuilds a deposit with one real proof, prints its header fields from their byte offsets, and decodes it.private_paymenthas two wallets replay a deposit and a private send with a shielded fee, two real proofs, and ends with the expected balances.nullifier_addresscomputes the program id, the pool account and the account address of a nullifier. It builds no proof.pool_stateencodes and decodes both pool account formats and shows the slots at which a root is accepted. It builds no proof.
This is what private_payment printed:
after the deposit: alice 100, bob 0
payment: 9230 bytes, tag NPAY0003
envelope: 9332 bytes, payment id 809a468bab57a92b8082218a25ddb1607ca9efa3f412b29ac0749927ee7b3687
after the send: alice 57, bob 40
pool: 4 notes, backing 97
the same payment again: SpentNullifier
Alice ends with 57: 100 less the 40 she sent, less the fee of 3. The payment id differs on every run because proofs are randomized. In this example the program itself plays the chain; a real client takes payments from verified finalized history, as Integration guidelines describes.
The package has five tests that pin the values the examples print:
sh tools/dev.sh test --offline --locked -p zolana-sdk-examples
Use the crates in your own project
Three crates do not depend on the vendored validator: native-payments (wire format, verifier, pool state, addresses), native-wallet-core (address format, payment construction with proofs, replay of history into a balance) and native-wallet-seed (the encrypted recovery file). Add them as Git dependencies and pin a commit:
[dependencies]
native-payments = { git = "https://github.com/zolanacom/zolana", rev = "4c36000033f1109f097635a3ac7511c6e7e23a9d" }
native-wallet-core = { git = "https://github.com/zolanacom/zolana", rev = "4c36000033f1109f097635a3ac7511c6e7e23a9d" }
native-wallet-seed = { git = "https://github.com/zolanacom/zolana", rev = "4c36000033f1109f097635a3ac7511c6e7e23a9d" }
# The same orchard configuration as the Zolana workspace.
orchard = { version = "=0.16.0", default-features = false, features = ["circuit", "std", "zeroize"] }
# Profiles are not inherited from a dependency's workspace. Without this the
# proof system is compiled unoptimized in debug builds.
[profile.dev.package."*"]
opt-level = 2
revis the commit this was checked against. Replace it with the commit you have reviewed. There is no compatibility promise between commits.- Your project needs Rust 1.92 or later.
- Cargo clones the whole repository, including the vendored validator source, but compiles only what the three crates need. In the check that was 148 crates, none of them from
node/agave. - Your project resolves its own dependency versions. To start from the versions the repository tests with, copy its
Cargo.locknext to yourCargo.tomlbefore the first build.
How this was checked: a separate crate outside the workspace, with exactly these dependencies, derived an address, wrote and read a recovery file, decoded a pool account, built a deposit with a real proof and replayed it into a balance. It was built and run offline with path dependencies on a checkout, and with git dependencies on a local clone of that commit. Fetching from github.com was not part of the check.
These crates build and verify payment bytes. They do not send them. Wrapping a payment in transactions, signing and sending is in native-payment-program and native-wallet, which depend on crates inside node/agave and build only inside the workspace. On a local network, use the native-wallet command line: see Run a local network.
Build the browser core
zolana-browser-core is the Rust core of the browser wallet. One script builds it for the web:
sh sdk/build-browser-core.sh
The script installs nothing. It needs:
- the dependencies fetched, as in the quick start;
- the
wasm32-unknown-unknowntarget for the pinned Rust toolchain; - the
wasm-bindgencommand-line tool inPATHat exactly version 0.2.129, the version pinned inclients/browser-core/Cargo.toml. The script refuses any other version.
It runs a release build of the library for that target, then wasm-bindgen --target web, and writes browser_core.js and browser_core_bg.wasm to clients/browser-core/pkg/. A second script loads the result and creates a disposable wallet, without a browser and without a network:
node sdk/js/vault-example.mjs
What was checked: the script ran on macOS (Apple Silicon) with Rust 1.92.0 and wasm-bindgen 0.2.129, and vault-example.mjs ran against its output in Node 25.2.
What was not: the output was not loaded in a browser as part of the SDK, and the threaded build (the browser-multicore feature) is not covered, because the repository does not record the compiler flags for it.
A browser wallet built on this core is a hot wallet. The design record says so plainly: “WASM is not an isolated secret vault. A compromised first-party site can steal an unlocked seed or alter a recipient.”
TypeScript types and the RPC client
Types for the browser core
wasm-bindgen types every JSON result of the core as string. sdk/js/zolana-browser-core.d.ts describes the same exports (23 BrowserVault methods, 6 functions, 11 error codes) and adds the JSON shapes, as far as the Rust source fixes them. It is written by hand; a test compares its exported names and error codes with the Rust source.
JSON-RPC client
sdk/js/rpc.mjs is plain JavaScript with no dependencies; it needs a runtime with fetch. Against a local network it needs no access header:
import { createRpcClient } from "./sdk/js/rpc.mjs";
const rpc = createRpcClient({ url: "http://127.0.0.1:18899" });
console.log(await rpc.getGenesisHash());
console.log(await rpc.getSlot());
It sends one JSON object per request with the headers and size limits the invited gateway enforces, reads a bounded response, times out, and never retries. It offers typed wrappers for the standard reads the wallets use, the three relay methods and the bounded wallet reads; RPC and gateway describes the methods. It holds no keys, signs nothing and does not sync a wallet.
The public devnet admits cohort wallets only. Without a membership, a gateway answers every method except getGenesisHash with HTTP 403. The client is for local networks, and for wallets that hold a cohort membership and pass their access proof through its accessHeader option.
The client’s tests run against a loopback server that applies the gateway’s request rules. It was not run against a validator or a devnet gateway.
node --test sdk/js/*.test.mjs
What the SDK does not do
- It publishes nothing. There are no registry packages and no prebuilt Wasm.
- It cannot send a payment to a chain from your own program; see the limit above.
- It does not open the devnet. Access still needs an invitation to a finite cohort.
- Its JavaScript side is a description and a transport, not a wallet: there is no packaged sync, storage or recovery logic.
- It was run on Apple Silicon macOS only.
What does not exist yet has the full list.