Zolana
ExplorerDocsGitHubOpen wallet

Docs · Build on Zolana

Your first shielded payment

A guided path from a clean machine to a shielded payment that your own program builds, proves and verifies. Everything runs on your computer. Nothing is sent to a network.

Result

What you will have at the end. A Rust program of your own, 210 lines long, that creates a wallet, builds a deposit and a private send with a shielded fee, verifies both with the function the validator’s payment program calls, and shows a second spend of the same note being refused. Every payment in it carries a real proof. The program runs offline.

Limit

What you will not have. Nothing is sent to the devnet and no coins move. The amounts are numbers inside one program on your computer.

Why. The three crates used here build and verify payment bytes. The code that wraps those bytes in transactions, signs them and sends them is in native-payment-program and native-wallet. Both depend on the vendored validator source and build only inside the repository’s workspace, so a program that depends on these three crates alone cannot send a payment to a chain. The public devnet also admits cohort wallets only.

Status. Zolana’s blockchain is currently in devnet. Devnet test coins are valueless and distinct from the ZOL token issued on Solana. The blockchain code has not yet been independently audited. Zolana mainnet and the planned bridge are not yet live.

The steps were run on Apple Silicon macOS. The build and run times quoted below are from that machine.

1. Prerequisites

  • Git.
  • Rust 1.92 with Cargo. The repository pins that version in rust-toolchain.toml.
  • A C/C++ toolchain. On macOS that is the Xcode command-line tools.
  • Network access for the clone and the fetch in step 2 and for the first build in step 4. Nothing else needs it.

Build and run the code lists the packages for Ubuntu.

2. Clone and build the repository

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

tools/dev.sh runs Cargo with a dependency cache and a build directory inside the repository. fetch downloads the dependencies of the whole workspace, including the validator’s. The last command compiles only what one of the SDK’s examples needs, runs it, and prints:

recovery file: format native-wallet-seed-v1, 1246 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

An npriv1 address means the toolchain works. The size of the recovery file varies by a few bytes from run to run. Your own program will print the same address in step 4.

3. Create your crate

Your program lives outside the repository, in a directory next to it.

cd ..
cargo new first-payment
cd first-payment
cp ../zolana/Cargo.lock ../zolana/rust-toolchain.toml .

The two copied files start your crate from the state the repository is tested in: Cargo.lock holds the dependency versions, and rust-toolchain.toml selects the same compiler. Now replace the contents of Cargo.toml with:

[package]
name = "first-payment"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
native-payments = { git = "https://github.com/zolanacom/zolana", rev = "d4bc065a22bda67cad4c06a35284d2cae2563d16" }
native-wallet-core = { git = "https://github.com/zolanacom/zolana", rev = "d4bc065a22bda67cad4c06a35284d2cae2563d16" }
native-wallet-seed = { git = "https://github.com/zolanacom/zolana", rev = "d4bc065a22bda67cad4c06a35284d2cae2563d16" }
# 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
  • The three native-* crates are the ones that do not depend on the vendored validator: native-payments (wire format, verifier, pool state), native-wallet-core (addresses, payment construction with proofs, replay of history) and native-wallet-seed (the encrypted recovery file). The Developer SDK page describes them.
  • rev is the commit this page was checked against. There is no compatibility promise between commits.
  • Cargo clones the whole repository, but compiles only what the three crates need.

4. A wallet

Replace the contents of src/main.rs with:

use native_wallet_core::{encode_address, Result, WalletKeys};
use native_wallet_seed::{decrypt, encrypt, Network, FORMAT};
use orchard::keys::{Scope, SpendingKey};

// A network is a 32-byte domain plus the base58 hash of its genesis block.
// These are the fixture values of the SDK examples. They name no real network.
const NETWORK: [u8; 32] = [7; 32];
const GENESIS: &str = "11111111111111111111111111111111";

/// A wallet is one 32-byte seed. Everything else is derived from it.
struct Wallet {
    seed: [u8; 32],
}

impl Wallet {
    /// The private receiving address: external scope, index 0.
    fn address(&self) -> Result<String> {
        let address = self.viewing_key()?.address_at(0u32, Scope::External);
        Ok(encode_address(NETWORK, GENESIS, &address))
    }
}

// The one trait the library needs from a wallet.
impl WalletKeys for Wallet {
    fn network_domain(&self) -> [u8; 32] {
        NETWORK
    }
    fn genesis_hash(&self) -> &str {
        GENESIS
    }
    fn spending_key(&self) -> Result<SpendingKey> {
        // Not every 32-byte string is a valid spending key.
        Option::from(SpendingKey::from_bytes(self.seed)).ok_or_else(|| "invalid seed".into())
    }
}

fn main() -> Result<()> {
    // Public example values. A real wallet draws its seed from the operating
    // system's random source and asks the user for the password.
    let seed = [7u8; 32];
    let password = b"disposable example password";
    let network = Network {
        network: NETWORK,
        genesis_hash: GENESIS.to_owned(),
    };

    // The recovery file is the seed, encrypted under the password.
    let backup = encrypt(&seed, password, &network)?;
    println!("recovery file: format {FORMAT}, {} bytes", backup.len());

    // Open it again, as a wallet does at start-up.
    let alice = Wallet {
        seed: *decrypt(&backup, password, &network)?,
    };
    let bob = Wallet { seed: [8; 32] };
    println!("alice: {}", alice.address()?);
    println!("bob:   {}", bob.address()?);

    Ok(())
}
cargo run

The first build fetches the repository and compiles the dependencies. In the check that was 148 packages, your own included and none of them from node/agave, in about half a minute. Cargo also adjusts the copied Cargo.lock to your crate. The program prints:

recovery file: format native-wallet-seed-v1, 1256 bytes
alice: npriv1gZWMfgeB9UAafpZyPa5Pf92AdWqYpJKVgDuHNf7Z7JGnpxQSqAYXtCgvrYcFkwfzSUDXFBDx5gtWuSQnRnGCDr6fVn3Ba7NwiuLA386Xd2dV
bob:   npriv1gZWMfgeB9UAafpZyPa5Pf92AdWqYpJKVgDuHNf7Z7JGokPzEsbMzPasz2AuBbLMTEoubaxsDPoGMYEpFdp93VDk2FPKAE66uqFfvtHe7ySoD

What happened. A wallet is one 32-byte seed, and the seed is the Orchard spending key. The viewing key and the receiving address are derived from it. Alice’s address is the one the SDK example printed in step 2, because both use the same public seed and the same example network.

The address is bound to its network. The 32-byte network identifier and the genesis hash go into the encoding, and the same text does not decode on another network. The recovery file is the seed encrypted under a key derived from the password. The devnet wallet saves a file in the same format.

5. A deposit

This step has two edits. First, add the following at the end of src/main.rs. It is a small stand-in for the chain, the step a wallet performs for every payment it reads from history, and two helpers that print.

use native_payments::{
    state::PoolState,
    verification::{PaymentVerifier, ValidationView},
    wire,
};
use native_wallet_core::{
    history::WalletState,
    payments::{Payment, PaymentProver},
};
use std::{collections::BTreeSet, sync::Arc};

/// The part a validator plays: the pool, the spent nullifiers and the verifier.
struct Chain {
    verifier: PaymentVerifier,
    pool: PoolState,
    spent: BTreeSet<[u8; 32]>,
}

impl Chain {
    /// Check one payment in `slot`. Nothing changes unless every check passes.
    fn execute(&mut self, slot: u64, bytes: &[u8]) -> Result<()> {
        let payment = wire::decode(NETWORK, bytes)?;
        let anchors = self.pool.accepted_roots(slot)?;
        let view = ValidationView {
            current_slot: slot,
            accepted_anchors: &anchors,
            spent_nullifiers: &self.spent,
            // The public amount the payment declares. A validator moves exactly
            // this amount between public accounts in the same transaction.
            authorized_public_value_balance: payment.context.public_value_balance,
        };
        let effects = self
            .verifier
            .verify(&payment.bundle, &payment.context, &view)?;
        // Valid: append the commitments, record the nullifiers, close the slot.
        self.pool = self.pool.with_payment(&effects)?;
        self.spent.extend(effects.nullifiers);
        self.pool.complete_slot(slot)?;
        Ok(())
    }

    fn summary(&self) -> String {
        let (notes, backing) = (self.pool.note_count(), self.pool.backing);
        format!("{notes} notes, backing {backing}")
    }
}

/// What a wallet does with a payment from history: verify it, keep the notes
/// it can decrypt, and close the slot.
fn replay(wallet: &mut WalletState, slot: u64, bytes: &[u8]) -> Result<()> {
    let payment = wire::decode(NETWORK, bytes)?;
    wallet.accept(&payment.bundle, &payment.context, slot)?;
    wallet.finish_slot(slot)
}

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
}

/// Print what a payment makes public. Reading it needs no key.
fn describe(name: &str, bytes: &[u8]) -> Result<()> {
    let payment = wire::decode(NETWORK, bytes)?;
    let tag = std::str::from_utf8(&bytes[..8])?;
    println!("{name}: {} bytes, tag {tag}", bytes.len());
    println!("  value balance {}", payment.context.public_value_balance);
    let anchor = hex(&payment.bundle.anchor().to_bytes());
    println!("  anchor        {anchor}");
    for action in payment.bundle.actions() {
        println!("  nullifier     {}", hex(&action.nullifier().to_bytes()));
        println!("  commitment    {}", hex(&action.cmx().to_bytes()));
    }
    let proof = payment.bundle.authorization().proof().as_ref().len();
    println!("  proof         {proof} bytes");
    Ok(())
}

Chain::execute is the part to read closely. verify is the function the validator’s payment program calls, in node/adapter/src/processor/finalization.rs. It checks a payment against a ValidationView: the current slot, the accepted anchors and the nullifiers already spent. A validator takes all three from its own state, never from the sender.

Second, add this inside main, directly above its last line Ok(()):

    // The prover holds the circuit's proving key. Build it once per process.
    let prover = PaymentProver::new();
    let key = prover.verifying_key();

    // An empty pool. Slot 0 is its first completed slot.
    let mut chain = Chain {
        verifier: PaymentVerifier::with_shared_key(NETWORK, Arc::clone(&key))?,
        pool: PoolState::new_slot_anchored(NETWORK, 1)?,
        spent: BTreeSet::new(),
    };
    chain.pool.complete_slot(0)?;

    // Each wallet keeps its own view of the pool, built by replaying history.
    let mut alice_view = WalletState::with_key_for_pool(&alice, &chain.pool, Arc::clone(&key))?;
    let mut bob_view = WalletState::with_key_for_pool(&bob, &chain.pool, Arc::clone(&key))?;

    // The public account that funds the deposit. Later it receives the fee.
    let relay = [0x53; 32];
    // The last slot in which these payments are valid.
    let expiry = 100;

    // Slot 1: 100 units enter the pool as a note for Alice.
    let request = Payment::Deposit {
        amount: 100,
        recipient: &alice.address()?,
    };
    let deposit = prover.build(&alice, &alice_view, relay, expiry, request)?;
    describe("deposit", &deposit)?;
    chain.execute(1, &deposit)?;
    println!("verified in slot 1: pool has {}", chain.summary());
    for wallet in [&mut alice_view, &mut bob_view] {
        replay(wallet, 1, &deposit)?;
    }
    let (a, b) = (alice_view.balance()?, bob_view.balance()?);
    println!("balances: alice {a}, bob {b}");
cargo run

After the three lines from step 4 it now prints:

deposit: 9222 bytes, tag NPAY0001
  value balance -100
  anchor        ae2935f1dfd8a24aed7c70df7de3a668eb7a49b1319880dde2bbd9031ae5d82f
  nullifier     4b12f47a803f2328fd3be8f3ed131ada9ff1338a720a6ef7d286340dbee7fd11
  commitment    ddedf12eac5b4570be84b5b2bc93db2ddf12da310793575dad6cffa0bd50050d
  nullifier     74b91181c9f948e16cc64b7996ef82850bbed20b61ec35b9883de242bf246517
  commitment    5cb2fc124e458dba4885aabac1a822bad4719634de11d773d6c57f8b9636f916
  proof         7264 bytes
verified in slot 1: pool has 2 notes, backing 100
balances: alice 100, bob 0

The hexadecimal values differ on every run, because proofs and note encryption are randomized. The sizes, the tag and the anchor do not.

What happened. The deposit created a note of 100 for Alice. The chain never sees the note. It sees a 32-byte commitment to it and an encrypted copy, and it appends the commitment to a Merkle tree. Every payment has exactly two actions, so it publishes two nullifiers and two commitments whatever it does. That is why the pool counts 2 notes after one deposit.

The anchor is the tree root the payment was built against. Here it is the root of the empty tree. The proof is 7,264 bytes and was created by PaymentProver, on the wallet’s side. The verifier checked the signatures and the proof, and only then did the pool change. What a validator verifies lists the checks in order.

The value balance of −100 is public. It says that 100 units cross into the pool, and the pool’s backing rises by the same amount. Alice’s wallet found her note by decrypting the payment’s outputs with her viewing keys. Bob’s wallet replayed the same payment and could decrypt nothing, so his balance is 0. Notes and commitments has the full description.

6. A private send with a shielded fee

Add this above Ok(()):

    // Slot 2: Alice pays Bob 40. A fee of 3 leaves the pool for the relay.
    let request = Payment::ShieldedSend {
        amount: 40,
        recipient: &bob.address()?,
        fee: 3,
    };
    let send = prover.build(&alice, &alice_view, relay, expiry, request)?;
    describe("send", &send)?;
    chain.execute(2, &send)?;
    println!("verified in slot 2: pool has {}", chain.summary());
    for wallet in [&mut alice_view, &mut bob_view] {
        replay(wallet, 2, &send)?;
    }
    let (a, b) = (alice_view.balance()?, bob_view.balance()?);
    println!("balances: alice {a}, bob {b}");
    // Each wallet's view must equal the pool the chain holds.
    alice_view.reconcile(&chain.pool)?;
    bob_view.reconcile(&chain.pool)?;
cargo run

The new lines:

send: 9230 bytes, tag NPAY0003
  value balance 3
  anchor        d2e6167d86d94354acb22eb6ab32508166a0a7b84c6b542ad0179fe9ace73b2b
  nullifier     173de506838ce405ab7df5d3681a88e82cd3d78b89f6ed5aed7c097a9ecb5218
  commitment    baeac1c1e71cfecaea91470c71984ab10528a126cb9ff064fca0a93897c83d33
  nullifier     5152657a03e2106ebbf37acfcf4353abe6d15864ffcfc6461bde90a2f2cafe19
  commitment    5fc39ef1c8da3fb0e2a0b4e296ac5762c4d8ae334ecdc8552656b2c41520843d
  proof         7264 bytes
verified in slot 2: pool has 4 notes, backing 97
balances: alice 57, bob 40

What happened. Alice spent her 100-unit note. On the chain, spending a note means publishing its nullifier. The chain records both nullifiers of the payment. The two new commitments are a note of 40 for Bob and a change note of 57 for Alice: 100 less 40 less the fee of 3. Neither amount is among the public fields printed above, and neither is Bob’s address. They are inside the encrypted notes.

The anchor is no longer the root of the empty tree. It is the root recorded when slot 1 was completed, the first one that contains Alice’s note. The program uses the slot-anchored pool format, in which a wallet can only build against the root of a completed slot. That is why it closes each slot on the chain and in every wallet. The validator accepts an anchor for a limited number of slots: see Which anchors are accepted.

The fee is the public part. A shielded-fee payment has the tag NPAY0003, is 8 bytes longer than the deposit, and its value balance equals the fee: 3 units leave the pool, and the backing falls to 97. On a chain the validator pays them to the relay’s public account. Fees for private transfers explains the three fee modes, and Privacy boundary lists what stays public.

The two reconcile calls pass, so each wallet’s replayed pool is identical to the pool the chain holds.

7. The same note twice

Add this above Ok(()):

    // A second copy of Alice's wallet that has seen the deposit but not the
    // send. It still holds the 100-unit note and spends it again.
    let mut stale = WalletState::with_key_for_pool(&alice, &chain.pool, key)?;
    replay(&mut stale, 1, &deposit)?;
    let request = Payment::ShieldedSend {
        amount: 90,
        recipient: &bob.address()?,
        fee: 3,
    };
    let second = prover.build(&alice, &stale, relay, expiry, request)?;
    describe("second spend", &second)?;
    let refused = chain.execute(3, &second).unwrap_err();
    println!("refused in slot 3: {refused}");

    // The first send, submitted again unchanged, is refused the same way.
    let refused = chain.execute(3, &send).unwrap_err();
    println!("the first send again: {refused}");
    println!("pool still has {}", chain.summary());
cargo run

The output from the send to the end:

send: 9230 bytes, tag NPAY0003
  value balance 3
  anchor        873e734f2b17d879441dc4c555b8a395b7148c4e9905172fb29b1881e5e91603
  nullifier     3e54ff59f8d9ff4c24ddd218cc7371e0abdcfa5bf0c81cdf7f9c883ba45b3918
  commitment    753612dac1fced205750fe9d602c7eba7bdbd847014a294201d9710263376f28
  nullifier     03c3d236952cdcfa34a53a4dcdec3bd0e5f66eb051200fa5df6764977b47d628
  commitment    7f00448e10c8061e439a590fb2c45dd7146abebbc1541d71735d995e0534261b
  proof         7264 bytes
verified in slot 2: pool has 4 notes, backing 97
balances: alice 57, bob 40
second spend: 9230 bytes, tag NPAY0003
  value balance 3
  anchor        873e734f2b17d879441dc4c555b8a395b7148c4e9905172fb29b1881e5e91603
  nullifier     57eee283fd0b234bc56a05d784cb53dd8ec6b0a6edb5f738ee0b809df9302e3e
  commitment    b1f136cf494b1ac56fdc9fb4320e070cc55f39617af4e311aee1d06034f9ee27
  nullifier     03c3d236952cdcfa34a53a4dcdec3bd0e5f66eb051200fa5df6764977b47d628
  commitment    f34039926b47f5f3144a4da4b5489b8865f250a9ebc75305489dab71c3bf032a
  proof         7264 bytes
refused in slot 3: SpentNullifier
the first send again: SpentNullifier
pool still has 4 notes, backing 97

What happened. The second copy of Alice’s wallet never saw the send, so it still counted the 100-unit note as unspent and built a new payment with it. That payment is well formed and names an anchor the chain still accepts. But a note has one nullifier. In the run above it is 03c3d236952cdcfa34a53a4dcdec3bd0e5f66eb051200fa5df6764977b47d628, and it appears in the send and in the second spend. The other nullifier of each payment is different.

The verifier found that nullifier in the spent set and refused the payment with SpentNullifier, before it looked at the signatures or the proof. The first send, submitted again unchanged, fails in the same way, and the pool is unchanged. On Zolana every spent nullifier is a small permanent account, and the validator checks those accounts instead of a set in memory: see Nullifiers, and why they are permanent.

The finished program builds three proofs. In the check it ran in 11 to 14 seconds.

What the program leaves out

  • It sends nothing. There is no transaction, no public signature and no RPC call. The three crates cannot send a payment to a chain. On a local network the command-line wallet does that.
  • There are no public accounts. The 100 units of the deposit come from nowhere and the fee goes nowhere. A validator moves the public amount between real accounts in the same transaction as the payment, and requires that the sponsor named in the payment signed that transaction.
  • The program plays the chain. It hands each payment to the wallets as if it were final. A real client takes payments from finalized history, checks that the history is continuous, and reconciles the result with the on-chain pool account. Even then it trusts its RPC endpoint for consensus.
  • The slots are invented, with one payment in each.
  • The seeds and the password are public. Never reuse them. A real wallet draws its seed from the operating system’s random source.
  • The formats are experimental. The wire module calls itself “not a released protocol”, and a later commit can change any of this.
  • The code has not been independently audited.
Checked

The Rust and the manifest on this page were compiled and run step by step, and every output block is copied from one of those runs, on Apple Silicon macOS with Rust 1.92.0.

Downloading from github.com and crates.io was not part of the check. The clone and the Git dependency were served from a local copy of the pinned commit, with the other dependencies already on disk, so the fetch command in step 2 was not exercised.

Where to go next

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.