ZOL ledger program reference

zol-ledger is the Anchor program on Solana that records who is owed what for the ZEC held in each app's Zcash vault. Players deposit shielded ZEC into a per-app vault held by 2-of-3 operators. An attested credit then adds the deposit to a Balance on Solana, keyed by the player's session key. Apps are separate Anchor programs that call the ledger by CPI. They move balances into pots, delegate a pot to a MagicBlock rollup, move value between its seats there, and bring the pot back. The pot is then paid out to the players' balances. Players leave through exit requests, which become settlement records that the operators pay on Zcash. The ledger never calls app code. Value enters only through attested credits and leaves only through settlement records.

Source: programs/zol-ledger/src/. IDL: idl/zol_ledger.json. The Rust code is the source of truth; this page follows ledger version 0.3.0.

Contents

1. Program ID and calling the ledger from an app
2. Accounts
3. Instructions
   • Admin and guardians
   • App registration and activation
   • Deposits
   • Pots
   • Exits and settlements
   • SDK-generated: process_undelegation
4. Events
5. Errors
6. Invariants the ledger guarantees

1. Program ID and calling the ledger from an app

The ID is set with declare_id! in lib.rs and is zol_ledger::ID in Rust.

The app authority

Each app acts through one address: the PDA with seed ["zol-app"] under the app's own program ID. The constant is zol_ledger::state::seeds::APP_AUTHORITY. Only the app program can sign for this address, through invoke_signed. The ledger stores it as App.authority at registration, and copies it into every pot as Pot.app_authority.

These instructions require the app authority as a signer: register_app, open_pot, buy_in, delegate_pot, move_seat, close_pot. An app can therefore only call them by CPI from its own program.

Depending on the crate

Add the ledger as a dependency with the cpi feature. This enables no-entrypoint and generates zol_ledger::cpi::* (one function per instruction) and zol_ledger::cpi::accounts::* (one struct per accounts list). From programs/zol-coinflip/Cargo.toml:

[features]
idl-build = ["anchor-lang/idl-build", "zol-ledger/idl-build"]

[dependencies]
zol-ledger = { path = "../zol-ledger", features = ["cpi"] }

Account types, seeds and helpers are public in zol_ledger::state (Config, Params, App, Balance, Pot, PotReceipt, SeatStake, PotAction, ActionAccount, seeds, limits, bps). Apps can deserialize ledger accounts with them, for example to read Pot.amounts in the rollup.

CPI example

From zol-coinflip:

pub const APP_AUTHORITY_SEED: &[u8] = b"zol-app";

zol_ledger::cpi::move_seat(
    CpiContext::new_with_signer(
        zol_ledger::ID,
        zol_ledger::cpi::accounts::MoveSeat {
            authority: a.app_authority.to_account_info(),
            pot: a.pot.to_account_info(),
            app_authority: a.app_authority.to_account_info(),
        },
        &[&[APP_AUTHORITY_SEED, &[bump]]],
    ),
    loser,
    winner,
    amount,
)?;

Instructions that take a variable list of accounts (cash_out, refund_pot, settle, set_guardians, unfreeze_app) read them from the remaining accounts. Over CPI, pass them with CpiContext::with_remaining_accounts.

Where instructions run

Most instructions run on Solana. move_seat and close_pot run in the MagicBlock rollup, where the pot is delegated. The program is built with #[ephemeral], which also adds the SDK's process_undelegation instruction (see 3.6).

2. Accounts

All amounts are in zatoshi (1 ZEC = 100,000,000 zatoshi). "App PDA" below means the App account address, not the app's program ID.

PDA seeds

Notes:

• Deposit seeds hold only the deposit ID, not the app. Deposit IDs are global across apps.
• Pot is the only account that is ever delegated. While delegated it is owned by the delegation program DELeGGvXpWV2fqJUhqcF5ZSYMS4JTLjteaAMARRSaeSh.
• No ledger instruction closes an account. Rent stays in Deposit, Balance, Pot, PotReceipt and Settlement accounts.

Config

One per deployment. Created by initialize.

Params

Set at initialize and replaceable by set_config. Params::validate enforces the rules in the last column.

bps(amount, bps) is floor(amount * bps / 10_000), computed in u128.

limits constants

From zol_ledger::state::limits. The admin can only set parameters within these bounds.

A dev-timings build refuses to initialize for Zcash mainnet.

App

One per app program. Created by register_app.

AppState:

The move from Activating to Active is lazy. App::refresh applies it at the start of credit_deposit, open_pot, buy_in, delegate_pot, settle and freeze_app. A stored Activating with activates_at <= now is effectively Active. Off-chain readers should treat it so.

Deposit

One per deposit ID. Created by either credit_deposit or void_deposit, so each ID is credited or voided at most once.

Balance

One per (app, session key). Created by the first credit_deposit for that session key.

Pot

The part of a pot that goes to the rollup. Holds amounts per seat, never player keys. Created by open_pot.

Delegable: yes. delegate_pot delegates it to the named validator; close_pot commits and undelegates it.

PotReceipt

The Solana-side record of a pot: who sits where and what they paid. Never delegated. Created by open_pot.

PotState transitions:

open_pot ──> Open ──delegate_pot──> Delegated ──cash_out──> CashedOut
              │                        │
              └──refund_pot──> Refunded <──refund_pot──┘

A receipt is "live" in Open and Delegated.

Settlement

One per settle call, numbered per app from 0. Created by settle.

Plain structs

PayoutEntry:

SeatStake (argument of delegate_pot):

PotAction (argument of close_pot): an instruction the delegation program runs on Solana right after the pot returns, signed only by the app's escrow (its fee payer). It may call only the pot's own app program. The ledger never signs for it.

ActionAccount:

Instruction argument structs (InitializeArgs, SetConfigArgs, CreditArgs) are described with their instructions.

3. Instructions

Account tables list accounts in the order of the IDL. W = writable, S = signer. Anchor's own account checks (wrong PDA, wrong owner, failed deserialization, account already initialized) fail with Anchor or System Program errors, not with the ledger errors listed per instruction.

Which instructions an app's state blocks

App::require_active fails with Paused if Config.paused, AppFrozen if the app is Frozen, and AppNotActive otherwise unless Active. It is called by:

So players can always leave an open pot, pots in the rollup can always come home and be paid out or refunded, and exits can be requested. Settling needs the app active again.

Attestations

credit_deposit, void_deposit and mark_paid require that the instruction immediately before them in the transaction is an Ed25519 precompile (Ed25519SigVerify111111111111111111111111111) instruction that:

• verifies exactly one signature (num_signatures == 1);
• takes its signature, public key and message from its own data (all three instruction indexes are u16::MAX);
• has public key Config.attestor;
• has a 32-byte message equal to the expected digest.

Otherwise the instruction fails with BadAttestation. The digests are defined in crates/zol-wire/src/digest.rs. Each is a SHA-256 over a 16-byte domain tag and the network byte, then:

3.1 Admin and guardians

initialize

Runs on Solana. Creates Config. Only the program's upgrade authority can call it, once.

Args: args: InitializeArgs

Checks: params pass Params::validate. Guardians are 1 to 7, distinct, none the default key, and 1 <= threshold <= len. network is a known value. A dev-timings build rejects mainnet.

Effect: writes all fields; paused = false.

Errors: NotUpgradeAuthority, FeeTooHigh, BadParams, BadGuardians.

set_config

Runs on Solana. Signer: admin. The admin can change parameters within the program's caps, rotate the attestor key, pause, and hand over the admin role. It cannot change guardians and cannot unfreeze an app.

Args: args: SetConfigArgs. Each None field is left unchanged.

Emits ConfigChanged. Errors: FeeTooHigh, BadParams; has_one = admin failure is an Anchor error.

set_guardians

Runs on Solana. Replaces the guardian set. Signers: at least guardian_threshold distinct current guardians.

Args: guardians: Vec<Pubkey>, threshold: u8. Same rules as at initialize.

Errors: GuardianThreshold, BadGuardians. No event.

set_cap

Runs on Solana. Signer: admin. Sets App.deposit_cap to any value. Works in any app state.

Args: cap: u64. No checks beyond the admin. No event.

A new app's cap is 0, so it accepts no credits until the admin sets a cap.

freeze_app

Runs on Solana. Signer: any one guardian.

Args: none.

Effect, after App::refresh:

• Activating (still within its delay): cancels the activation. State back to Pending; vault_address, genesis_head and activates_at zeroed. Emits ActivationCancelled.
• Active: state becomes Frozen. Emits AppFrozen.
• Any other state: fails.

Errors: NotGuardian, BadAppState.

unfreeze_app

Runs on Solana. Returns a frozen app to Active. Signers: at least guardian_threshold distinct guardians. The admin cannot do this.

Args: none. Emits AppUnfrozen. Errors: GuardianThreshold, BadAppState (app not Frozen).

3.2 App registration and activation

register_app

Runs on Solana. Creates the App account in state Pending. The app must call it by CPI, signing for its ["zol-app"] PDA; this is the app's consent. Anyone may pay.

Args: none.

Effect: if registration_bond > 0, transfers that many lamports from payer to the App account. Sets program_id, authority, registrant, state = Pending, bond. All counters and deposit_cap start at 0. Emits AppRegistered.

Errors: NotAProgram, BadAppAuthority.

activate_app

Runs on Solana. Signer: admin. Records the vault and starts the activation delay. The vault address and genesis head never change once the app is active. Only a guardian cancel during the delay clears them.

Args: vault_address: [u8; 43], genesis_head: [u8; 32].

Checks: app is Pending; neither argument is all zeros.

Effect: state Activating; activates_at = now + activation_delay_secs. Emits AppActivating.

Errors: BadAppState, BadParams, Overflow.

3.3 Deposits

credit_deposit

Runs on Solana. Credits an attested deposit to the player's balance. Any account may relay it; the attestation is the authorization.

Args: args: CreditArgs

Checks, in order: app active and ledger unpaused; amount > 0; amount is a permitted denomination; no unknown flag bits; app_data within the limit; the preceding instruction attests the credit digest; liability + unpaid_total + net <= deposit_cap; for an existing balance, the same payout_commitment.

Effect:

• fee = bps(amount, entry_fee_bps), net = amount - fee.
• App: deposit_count += 1, credited_total += amount, liability += net, fee_pool += fee.
• Deposit: state Credited, index = previous deposit_count, and the arguments.
• Balance: created on first use with this payout_commitment; amount += net; auto_exit set from flags.
• Emits DepositCredited.

A second credit or void of the same deposit_id fails because the Deposit account already exists.

Errors: Paused, AppFrozen, AppNotActive, ZeroAmount, BadDenomination, BadFlags, AppDataTooLong, BadAttestation, OverCap, PayoutCommitmentMismatch, Overflow.

void_deposit

Runs on Solana. Records an attested void, so the deposit can never be credited, and the operators can refund it on Zcash. Works in any app state, including frozen, paused or cancelled. Credits nothing.

Args: deposit_id: [u8; 32].

Effect: creates the Deposit with state Voided, app, id and digest. Emits DepositVoided.

Errors: BadAttestation.

3.4 Pots

A pot's life:

1. open_pot (app) creates Pot and PotReceipt in state Open.
2. buy_in (app and player) moves balance into a seat. leave_pot (player alone) moves it back.
3. delegate_pot (app) checks the seats, fixes session_deadline and the validator, and delegates Pot to the rollup.
4. move_seat (app, in the rollup) moves value between seats.
5. close_pot (app, in the rollup) commits the pot and returns it to Solana, optionally with a return action.
6. cash_out (anyone) pays the returned seat amounts to the players' balances.

refund_pot (anyone) returns every buy-in if the pot never started in time, or never validly returned.

open_pot

Runs on Solana. Signer: app authority.

Args: pot_id: [u8; 32], open_deadline: i64.

Checks: app active and ledger unpaused; now < open_deadline <= now + max_open_secs. pot_id must be unused for this app.

Effect: Pot with app, app_authority, pot_id, no seats. PotReceipt in state Open with open_deadline. Emits PotOpened.

Errors: BadAppAuthority, Paused, AppFrozen, AppNotActive, BadDeadline, Overflow.

buy_in

Runs on Solana. Signers: app authority and the player's session key. Nobody enters a pot except through the app.

Args: amount: u64.

Checks: app active and ledger unpaused; receipt Open; now < open_deadline; amount > 0; balance not exiting; balance.amount >= amount. A new player needs a free seat: seat_count < max_seats.

Effect: balance.amount -= amount. A player already seated adds to their seat; a new player takes the next seat. receipt.buy_ins[seat] and receipt.total grow by amount. pot.amounts[seat] is set to the seat's buy-in and pot.seat_count to the receipt's. Emits BoughtIn.

Errors: BadAppAuthority, Paused, AppFrozen, AppNotActive, BadPotState, OpenDeadlinePassed, ZeroAmount, BalanceExiting, InsufficientBalance, PotFull, Overflow.

leave_pot

Runs on Solana. Signer: the player's session key alone. While the pot is Open, a player can always take their whole buy-in back, so an app cannot trap anyone in a pot that has not started. Works in any app state and while paused.

Args: none.

Checks: receipt Open; the player has a seat.

Effect: removes the seat and shifts later seats down by one in both receipt and pot, so they stay aligned and ordered. receipt.total and seat_count decrease. The buy-in returns to balance.amount. Emits LeftPot.

Because seats shift, an app must not assume a player's seat index is fixed before delegation. delegate_pot takes the expected seating for this reason.

Errors: BadPotState, NoSeat, Overflow.

delegate_pot

Runs on Solana. Signer: app authority. Starts the pot: fixes the seating, the session deadline and the rollup validator, then delegates Pot to the MagicBlock delegation program.

Accounts 5–7 and 9–11 are added by the ephemeral-rollups SDK's #[delegate] macro.

Args:

Checks: validator non-default; app active and ledger unpaused; receipt Open; now < open_deadline; seat_count > 0; expected matches players and buy_ins seat by seat and has the same length; now + min_session_secs <= session_deadline <= now + max_session_secs; pot owned by the ledger with the receipt's seat_count.

Effect: receipt state Delegated, session_deadline and validator recorded; pot.delegated = true; pot delegated to validator. Emits PotDelegated.

Errors: BadParams, BadAppAuthority, BadAccount, Paused, AppFrozen, AppNotActive, BadPotState, OpenDeadlinePassed, ReceiptMismatch, BadDeadline, PotInvalid, Overflow.

move_seat

Runs in the rollup. Signer: app authority. Moves value between two seats of one delegated pot. It cannot create value, add a player or touch another pot. It reads no Config or App, so app freezes and the ledger pause do not stop it.

Args: from: u8, to: u8, amount: u64.

Checks: pot.delegated; from < seat_count, to < seat_count, from != to; amounts[from] >= amount. A zero amount is not rejected.

Effect: amounts[from] -= amount, amounts[to] += amount. No event.

Errors: BadAppAuthority, BadPotState, BadSeat, InsufficientBalance, Overflow.

close_pot

Runs in the rollup. Signer: app authority (and the payer). Commits the pot and returns it to Solana. With action, the delegation program then runs that instruction on Solana right after the pot is back, paid from the app's escrow. An app can use this to pay its players out without a keeper. close_pot checks no deadline; the app decides when to close.

Accounts 5–6 are added by the SDK's #[commit] macro. In Anchor, omit an optional account by passing the program ID in its place; zol_ledger::cpi::accounts::ClosePot takes Option<AccountInfo> for both.

Args: action: Option<PotAction>.

Checks: pot owned by the ledger and at the right address; authority == pot.app_authority; pot.delegated. With an action:

• find_program_address(["zol-app"], action.program) equals authority, so the action can only call the pot's own app;
• action.accounts.len() <= 16;
• action.data.len() <= 256;
• 0 < action.compute_units <= 400_000;
• escrow_authority is present and a signer.

The ledger does not check the address of escrow_authority. Action accounts carry no signer flag; the action runs signed only by the escrow.

Effect: pot.delegated = false is written, then a MagicBlock intent bundle commits and undelegates the pot, with magic_fee_vault if given. With an action, the bundle adds it as a post-undelegate action (CallHandler) with destination_program = action.program, the action's accounts, data and compute units, and escrow_authority. The return to Solana is asynchronous. Until it lands, cash_out fails with PotNotReturned. An app's action handler should expect the pot may not be back yet; zol-coinflip's cash_out_table then does nothing. zol-coinflip also notes that the action receives extra trailing accounts (the escrow), which its handler ignores. No event.

Errors: BadAccount, BadAppAuthority, BadPotState, BadAction.

cash_out

Runs on Solana. Anyone may call it, including an app's return action. Pays the returned seat amounts to the players' balances. Works in any app state and while paused, so pots in the rollup can still come home.

Args: none.

Checks: receipt Delegated; pot owned by the ledger again (otherwise PotNotReturned). The pot must have validly returned: seat_count, app and pot_id match the receipt, the seat amounts sum to receipt.total, and unused seats are zero (otherwise PotInvalid). Exactly seat_count balances, no duplicates, each with app == app and session_key == players[i].

Effect: balances[i].amount += pot.amounts[i]. If a balance has auto_exit and now holds at least min_exit, it is marked exiting. Receipt state CashedOut. Emits PotCashedOut. App.liability does not change (value moves from a live receipt to balances).

Errors: BadAccount, BadPotState, PotNotReturned, PotInvalid, DuplicateAccount, Overflow.

refund_pot

Runs on Solana. Anyone. Returns every buy-in from the receipt. Works in any app state and while paused. Same accounts as cash_out.

Args: none.

Allowed when:

• receipt Open and now >= open_deadline (the pot never started in time); or
• receipt Delegated, now >= session_deadline + refund_grace_secs, and the pot has not validly returned (same test as cash_out). A pot that returned and passes the checks can only be cashed out.

Effect: balances[i].amount += receipt.buy_ins[i]; auto_exit is not applied. Receipt state Refunded. Emits PotRefunded.

Errors: BadAccount, RefundNotAllowed, DuplicateAccount, Overflow.

3.5 Exits and settlements

request_exit

Runs on Solana. Signer: the player's session key. Marks the balance for payout. The whole balance at settle time is paid, and buy-ins are refused while it is marked. Works in any app state and while paused. There is no instruction to unmark.

Args: none. Checks: balance.amount >= min_exit. Effect: exiting = true. Emits ExitRequested.

Errors: BelowMinExit.

settle

Runs on Solana. Anyone. Turns 1 to 16 exiting balances into the app's next settlement record, which the operators pay on Zcash.

Args: none.

Checks: app active and ledger unpaused; 1 to 16 balances; no duplicates; each belongs to app, is exiting, and holds at least min_exit.

Effect, per balance: fee = bps(amount, exit_fee_bps) + network_fee_allowance; payouts[i] = { commitment: payout_commitment, amount: amount - fee }; App.liability -= amount; App.fee_pool += fee; the balance's amount = 0 and exiting = false. Then Settlement is written as Unpaid with sequence = next_settlement, count and total; next_settlement += 1; unpaid_total += total. Emits Settled.

Errors: Paused, AppFrozen, AppNotActive, BadPayoutCount, DuplicateAccount, BadAccount, NotExiting, BelowMinExit, Overflow.

mark_paid

Runs on Solana. Any relayer, with an attestation. A public record for auditors, posted after the payout reaches depth on Zcash. The code notes that signers never rely on it. Works in any app state and while paused.

Args: none.

Checks: settlement Unpaid; settlement.sequence == app.paid_count (settlements are marked paid in order); the preceding instruction attests the paid digest.

Effect: settlement Paid; paid_count += 1; unpaid_total -= total. Emits SettlementPaid.

Errors: AlreadyPaid, OutOfOrder, BadAttestation, Overflow.

3.6 SDK-generated: process_undelegation

Added by the ephemeral-rollups SDK's #[ephemeral] attribute. The delegation program calls it to hand an undelegated account (the pot) back to the ledger. Apps do not call it. Accounts in IDL order: base_account (W), buffer (PDA ["undelegate-buffer", base_account] under the delegation program), payer (W), system_program. Args: account_seeds: Vec<Vec<u8>>. Its behavior is defined by the SDK, not by ledger code.

4. Events

Emitted with Anchor emit! (program log). In most events app is the app's program ID. In ExitRequested it is the App PDA, because that event takes Balance.app.

initialize, set_guardians, set_cap, move_seat and close_pot emit no event.

5. Errors

From error.rs, enum ZolError. Code is 6000 + index.

6. Invariants the ledger guarantees

These follow from the code and its doc comments. They hold for any app program, since apps are untrusted callers.

Value

• Value enters only through credit_deposit, which needs an attestor signature over the exact deposit, a permitted denomination, and room under the app's deposit_cap. A deposit ID is credited or voided at most once, never both.
• Value leaves only through settle, into a numbered settlement record that the operators pay on Zcash. The exit fee and network fee allowance go to fee_pool.
• No pot instruction creates value. buy_in and leave_pot move value between a balance and a seat. move_seat moves value between two seats of one pot. cash_out pays out only a pot whose seat amounts sum to the receipt's total. refund_pot pays back exactly the recorded buy-ins.
• App.liability equals the sum of the app's balances plus the totals of its live receipts. Credits add the net amount; settlements subtract the settled balances; pot instructions leave it unchanged.
• Credits are refused once liability + unpaid_total would exceed deposit_cap. A new app's cap is 0.

Who can move what

• Only an app's program can act as that app: its authority is its own ["zol-app"] PDA, and registration needs that PDA's signature.
• An app touches only its own pots. open_pot, buy_in and delegate_pot require App.authority; move_seat and close_pot require the pot's app_authority.
• Nobody enters a pot without both the app's and the player's signatures (buy_in).
• A player can leave an Open pot alone, in any app state.
• Payouts go only to the receipt's players. cash_out and refund_pot credit seat i to the balance whose session key is players[i], in the same app. Player keys live only in the receipt, which never leaves Solana.
• A return action from close_pot may call only the pot's own app, within fixed size and compute limits, signed only by the app's escrow. The ledger never signs for it.
• An exiting balance cannot buy in. A balance's payout commitment is fixed by its first credit; settlement pays to it.

Liveness and deadlines

• An Open pot that did not start by its open_deadline can be refunded by anyone.
• A delegated pot that has not validly returned by session_deadline + refund_grace_secs can be refunded by anyone. refund_grace_secs is at least 3,900 s in release builds, longer than a forced undelegation (about 60 minutes). A pot that did validly return can only be cashed out.
• leave_pot, move_seat, close_pot, cash_out, refund_pot, request_exit, void_deposit and mark_paid work when the app is frozen or the ledger is paused, so pots in the rollup can still come home and players are not trapped.
• The pot's rollup validator is fixed at delegation and recorded in the receipt. The delegation program accepts commits only from it.

Governance limits

• The admin can set parameters only within the program's caps: each fee at most 1%, network fee allowance at most 0.001 ZEC, at most 16 seats, and the activation-delay and refund-grace floors.
• The admin cannot change guardians or unfreeze an app.
• An app's vault address and genesis head take effect only after the activation delay (at least 1 hour in release builds). Any one guardian can cancel during the delay. No instruction changes them once the app is active.
• Any one guardian can freeze an active app. Unfreezing and replacing the guardian set need a threshold of guardians.
• Settlements are numbered per app and marked paid strictly in order, each with an attestation.