Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Build and run the code

Prerequisites, the commands that work, the repository layout, how to run the tests, and where the candidate patch series lives.

Prerequisites

  • Rust 1.92, pinned in rust-toolchain.toml, and a C/C++ toolchain.
  • Python 3. The tools use the standard library. A few tests and acceptance runners use optional extras (the cryptography package, an installed Playwright runtime).
  • Node.js for the JavaScript test suites, and Git.

On macOS the C/C++ toolchain is the Xcode command-line tools. For Ubuntu, the Linux runbook lists the packages a builder needs: Git, Python 3, build-essential, pkg-config, libssl-dev, libudev-dev, zlib1g-dev, llvm, clang, libclang-dev, cmake, libprotobuf-dev and protobuf-compiler.

Development has been on Apple Silicon macOS, with Linux x86-64 builds described in the Linux pilot runbook. Other platforms are untested.

Fetch once, then build offline

tools/dev.sh wraps Cargo with a project-local dependency cache (.tools/cargo) and target directory. Fetch dependencies once; everything after that builds offline against the lockfile.

git clone https://github.com/zolanacom/zolana.git
cd zolana
sh tools/dev.sh fetch --locked

Verify a proof, run the runtime tests

# Build and verify a real shielded-payment proof fixture. No chain, no funds.
sh tools/dev.sh run --offline --locked -p payment-lab -- proof-smoke

# Execute synthetic native payments in the runtime and through the Agave Bank.
CARGO_BUILD_JOBS=2 sh tools/dev.sh test --offline --locked -p native-payment-program --test runtime
CARGO_BUILD_JOBS=2 sh tools/dev.sh test --offline --locked -p native-validator-check --test bank

Both test targets depend on crates from the vendored Agave snapshot, so they compile part of the validator.

Start a local network

This builds the validator from node/agave, which takes time and disk space.

sh tools/build_localnet.sh
python3 -B tools/localnet.py init --root .data/v2
python3 -B tools/localnet.py start --root .data/v2
python3 -B tools/localnet.py verify --root .data/v2
python3 -B tools/localnet.py stop --root .data/v2

To exercise the command-line wallet end to end on a fresh local network (stop any other local network first):

CARGO_BUILD_JOBS=2 sh tools/dev.sh build --offline --locked -p native-wallet
python3 -B tools/wallet_localnet.py --root .data/wallet-example

Run a local network walks through both, including what each step prints.

Run the portal without a network

python3 -B tools/network_portal.py --port 8780

It shows a disconnected-history state.

Run the tests

sh tools/check.sh --development-only

This runs, in order: a formatting check, Clippy with warnings as errors, the workspace’s Rust tests, a build of every binary, the local validator build, the Python unit tests under tools/, the Node test suites for the browser wallet, the portal and the wallet UI, and git diff --check.

Note

Use the --development-only flag. Without it the script also runs tools/check_publication.py, which is not part of the public repository, so the last step fails.

Individual suites can be run on their own:

# Rust, whole workspace
CARGO_BUILD_JOBS=2 sh tools/dev.sh test --offline --locked --workspace -- --nocapture

# Python tools
python3 -B -m unittest discover -s tools -p '*_test.py'

# Browser wallet and portal (Node's built-in test runner)
node --test clients/browser-wallet/*.test.mjs clients/network-portal/*.test.mjs

# Wallet UI
node clients/wallet-ui/ui-state.test.cjs
node tools/wallet_ui_contract_test.cjs

Where a document in the repository says a test passed, it refers to the project’s own runs. The underlying logs are not part of the repository.

Repository layout

Repository layout
PathContents
protocol/payments/native-payments: payment validation, wire formats, pool state, anchors and envelopes
node/adapter/native-payment-program: the native program (metered execution, staging, nullifier accounts, coin accounting)
node/agave/Upstream Agave v3.0.14 source snapshot with local modifications; Apache-2.0
node/validator-check/Integration tests that run signed transactions through the Agave Bank
node/localnet/native-localnet and native-validator binaries for local test networks
node/rpc-access/Authenticated private RPC transport used by the validator and operator tools
node/candidate/Patch series and reconstruction plan that port the payment code to Agave 4.3.2; not built by the workspace
clients/cli/payment-lab: proof fixture and development commands
clients/wallet/native-wallet, native-faucet and native-shielded binaries, plus the synthetic native-fast-cash fixture
clients/wallet-core/, clients/wallet-seed/Shared proof construction and history replay; the encrypted seed format
clients/browser-core/Rust/Wasm core of the browser wallet
clients/browser-wallet/Browser wallet page, workers, storage adapter and Node test suites
clients/browser-lab/Loopback page that measures synthetic proofs in a browser
clients/wallet-ui/Device-local wallet UI, served by tools/wallet_ui.py
clients/network-portal/Network portal and read-only explorer, served by tools/network_portal.py
clients/devnet-explorer/The static explorer page used on this site
tools/Build wrappers, local-network runners, operator services and their tests
docs/decisions/Architecture decisions
docs/Runbooks, design notes and the tester quick-start

The local tools bind to loopback and use disposable test keys and test units. They keep their state in git-ignored directories: .data/ for networks and wallets, .local/ for operator scratch files, .tools/ and target/ for build caches.

The candidate patch series

There are two validator code lines.

  • The workspace builds against the Agave 3.0.14 snapshot in node/agave. Payments are delivered through staging accounts.
  • The candidate in node/candidate ports the payment code to Agave 4.3.2. Single-transaction (“inline”) shielded payments and slot-anchored pool state need it. It is a patch series, reconstructed and built separately, and requires Rust 1.97.1.

The candidate is rebuilt from an exact upstream archive that you supply and a pinned plan. Source preparation is offline:

python3 -B tools/reconstruct_native_candidate.py verify-plan \
  --plan-sha256 f7e49b5c08901b0c868b826f8f828215f025cf4b42499a7707b1d3763b8075b0

python3 -B tools/reconstruct_native_candidate.py prepare \
  --plan-sha256 f7e49b5c08901b0c868b826f8f828215f025cf4b42499a7707b1d3763b8075b0 \
  --archive /absolute/path/agave-a203300.tar.gz \
  --output /absolute/path/new-current-candidate

Compiling the result requires its pinned toolchain, dependencies and a Linux build environment. The candidate README is explicit that build, runtime acceptance and installation are separate steps, and that source preparation “establishes reproducible source, not a build, cryptographic audit or deployment”.

The ledger compression change from release v0.2.0 is kept under node/candidate/drafts/ledger-lz4; it is not yet part of the reconstruction plan.

What you cannot rebuild from the repository

The hosted devnet is not reproducible from the repository alone. The deployment, enrollment and backup automation used to host it is not included.

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.