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
cryptographypackage, 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.
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
| Path | Contents |
|---|---|
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/candidateports 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.