This guide uses only scripts and binaries that are in the public repository. It runs the workspace’s validator (the Agave 3.0.14 snapshot), so payments go through staging accounts and a development sponsor pays the public costs. Everything binds to loopback, and the fixture keys are public: nothing here is a real wallet.
1. Build
sh tools/dev.sh fetch --locked
sh tools/build_localnet.sh
CARGO_BUILD_JOBS=2 sh tools/dev.sh build --offline --locked -p native-wallet
build_localnet.sh builds agave-validator and native-localnet from the workspace. It takes time and disk space; keep room for the build and two ledgers. The wallet build produces target/debug/native-wallet.
2. The scripted run
One script does the whole exercise on a new network:
python3 -B tools/wallet_localnet.py --root .data/wallet-example
It needs local ports 18899 and 19899 free and a root directory that does not exist yet. It initialises the network, starts both validators, creates two wallets with random keys, and then runs:
| Step | Expected private balances (alice, bob) |
|---|---|
| alice deposits 100 | 100, 0 |
| alice sends 40 to bob | 60, 40 |
| bob withdraws 15 | 60, 25 |
| bob sends 10 to alice | 70, 15 |
| alice withdraws 65, which needs two notes | 5, 15 |
Each payment prints a line such as Confirmed wallet deposit by alice. The script then checks the same balances on the second validator, resolves a pending payment as if the client had lost its final response, restores both wallets from their seed backups and restarts one validator. Receipts are written to wallet-result.json in the root, and secret material stays in private files under its wallets/ directory.
The validators are left running when the script ends. Stop them with:
python3 -B tools/localnet.py stop --root .data/wallet-example
3. The same thing by hand
Start a network of your own. The root must be a new directory under .data.
python3 -B tools/localnet.py init --root .data/v2
python3 -B tools/localnet.py start --root .data/v2
python3 -B tools/localnet.py status --root .data/v2
init writes network.json and sponsor.keypair.json into the root. start prints the RPC address of each validator (http://127.0.0.1:18899 and :19899). status prints the slot, the pool’s backing and the number of commitments. RPC can answer before startup has finished; new finalized blocks are the sign that the network is live.
Create a wallet
The password is read from a private file or from standard input, never from the command line. Create a private directory and a random password file:
mkdir -m 700 .data/my-wallet
python3 -c 'import os,secrets; f=os.open(".data/my-wallet/unlock.password",os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600); os.write(f,secrets.token_bytes(48)); os.close(f)'
target/debug/native-wallet init --network .data/v2/network.json \
--wallet .data/my-wallet/main.wallet.json \
--backup .data/my-wallet/main.seed-backup.json \
--password-file .data/my-wallet/unlock.password
init prints the wallet’s private address (it starts with npriv1), its public address and its fee address. Repeat with other file names for a second wallet.
The runbook writes these examples with the network root .data/wn2. The commands here are the same with the root from this guide.
Deposit, send, check
Chain operations add --rpc. On this fixture, deposits, sends and withdrawals also take --sponsor with the keypair that init wrote, and --amount in integer native units. These are the invocations the harness in step 2 runs.
W="--network .data/v2/network.json --wallet .data/my-wallet/main.wallet.json --password-file .data/my-wallet/unlock.password --rpc http://127.0.0.1:18899"
# Move 100 units from the sponsor's public account into the pool, as a note for this wallet.
target/debug/native-wallet deposit $W --sponsor .data/v2/sponsor.keypair.json --amount 100
# Send 40 units privately to another wallet's npriv1 address.
target/debug/native-wallet send $W --sponsor .data/v2/sponsor.keypair.json --amount 40 --to npriv1...
# The verified finalized balance, the unspent-note count and the largest amount payable from two notes.
target/debug/native-wallet balance $W
A payment uses at most the two largest unspent notes. Change goes to an internal address of the same wallet, which the scan also finds. If an amount exceeds the value in two notes the wallet rejects it even when the total balance is higher; send a supported amount to your own address to combine notes.
Withdraw
The harness withdraws with withdraw-legacy, which the wallet’s help describes as “disposable fixture compatibility only; credits the sponsor”:
target/debug/native-wallet withdraw-legacy $W --sponsor .data/v2/sponsor.keypair.json --amount 15
The ordinary withdraw command is the recipient-bound withdrawal to a public address of the wallet’s own. The repository’s runbook exercises it on a separately initialised rehearsal network with user-paid fees, not on this public-key fixture, so it is not shown here as a tested step.
If something is interrupted
The wallet records a payment before it broadcasts it. If a command is interrupted, the next send is refused until the original is dealt with:
resolvedetermines what happened to a recorded payment (journal file<wallet>.pending.json).reclaimcloses a recorded interrupted upload and recovers its temporary rent (journal file<wallet>.staging.json).
Never delete these journal files. Integration guidelines explains the rules behind them.
4. The network’s own check
python3 -B tools/localnet.py verify --root .data/v2
verify runs a fixed payment exercise from the Rust fixture and then stops one validator and recovers it from a snapshot. It can run only once per network; on a second run it answers “this network already completed recovery verification; use status or a fresh network”. If you want a clean network for wallet commands, skip it or use a separate root.
5. The other fee modes locally
The sponsor mode above is the only one that runs on a default local network with nothing else installed. For the other two, this is what the repository contains:
| Mode | Commands | What is missing from the repository |
|---|---|---|
| User-paid fees | native-wallet fees shows the fee address and a quote; send --fee-payer user --max-fee-debit <cap> pays from it. See docs/private-send-runbook.md. | The acceptance harnesses (tools/private_send_localnet.py, tools/userfees_localnet.py) require a Playwright runtime and a browser script that are kept outside the repository. No documented command funds a fee address on the public-key fixture. |
| Shielded fees | native-shielded send --max-shielded-fee <cap> and native-shielded resolve. The harness is python3 -B tools/shielded_fees_localnet.py --name f54a. See docs/shielded-fees-runbook.md. | Nothing, but the harness is Linux-only, refuses macOS and existing fixture roots, and starts its own gateway, faucet and relay on loopback. |
| Inline (single-transaction) payments | Not available on the workspace validator. | They need the Agave 4.3.2 candidate, which is reconstructed and built separately. The local scripts here use the staged path. |
6. Stop and clean up
python3 -B tools/localnet.py stop --root .data/v2
- There is no reset or delete command. To start again, choose a new root.
- Ports 18899 and 19899 must be free before another network starts.
- State lives in the root:
network.json, ledgers, validator logs and result files. Build caches are in.tools/andtarget/.
What this does not show
- It is a two-validator network on one machine with public fixture keys. It demonstrates the payment path, not a deployment.
- Recovery procedures have been exercised against process kills on test fixtures. Power loss, disk loss and host loss are not covered.
- The hosted devnet uses the candidate validator, a gateway and a relay with configuration that is not in the repository.
Sources: docs/local-validator-runbook.md, docs/local-wallet-runbook.md and tools/wallet_localnet.py.