TypeScript client modules

The browser pages in web/ are built from a handful of DOM-free modules in web/src/. They are the reference client for ZOL: session keys, deposits through the gateway page API, and Solana / MagicBlock rollup transactions for the ledger and the zol-coinflip program.

Using the modules

They are not a published npm package. They live in the zol-coinflip-web app (web/package.json, "private": true). Two options:

1. Import from the repo. Scripts in the repo already do this, e.g. web/scripts/testnet-smoke.ts imports ../src/gateway, ../src/deposit, ../src/session, ../src/chain and runs with cd web && npx vite-node scripts/testnet-smoke.ts.
2. Copy the files into your project. Copy with symlinks dereferenced: web/src/wire.ts is a symlink to crates/zol-wire/ts/wire.ts (cp -L web/src/{chain,session,passkey,deposit,gateway,memo,ua,wire}.ts your/src/). wire.ts is checked against crates/zol-wire/vectors/v0.3.json.

Requirements:

• Dependencies (versions from web/package.json): @noble/curves@^1.6, @noble/hashes@^1.5 (v1 import paths such as @noble/hashes/sha256), @scure/base@^1.1, @solana/web3.js@^1.95 (v1 API), and buffer@^6 in browsers.
• chain.ts builds instructions with Buffer.from. In a browser, install a global first, as the pages do:

  import { Buffer } from "buffer";
  (globalThis as any).Buffer ??= Buffer;

• ESM, TypeScript 5, moduleResolution: "Bundler" (web/tsconfig.json). With Vite, allow the symlinked file: server: { fs: { allow: [".."] } } (web/vite.config.ts).
• passkey.ts needs a browser (WebAuthn, localStorage, location). Everything else also runs in Node ≥ 20 / Bun (creditDigest uses globalThis.crypto.subtle).

Tests: web/test/ (npm test in web/).

Testnet values

From docs/ops/testnet-deploy.md and web/scripts/testnet-smoke.ts (testnet beta; may change):

The pages read these from VITE_GATEWAY (comma-separated), VITE_BASE_RPC, VITE_ER_RPC, VITE_LEDGER, VITE_APP, VITE_VALIDATOR, VITE_VRF_QUEUE; their built-in defaults are local devnet values.

session.ts

Source: web/src/session.ts

A session key is an Ed25519 key, one per app program. It signs the deposit memo and every Solana and rollup action of the player; the ledger knows the player only by it. Its public key is the {session} of the gateway API and the player's Solana signer.

Storage keys (app = program ID base58):

Backup string format:

zolsess1:<app program id>:<seed hex, 64 chars>:<checksum>
checksum = hex(sha256("zolsess1:<app>:<seed hex>")[0..4])

parseSessionBackup rejects a wrong prefix or part count, a checksum mismatch, a backup for a different app, and a malformed seed.

import { loadOrCreateSession, exportSession, hex, type KV } from "./session";

const APP = "7G2o74qyLh477EuWUFdgumeB13kTCK1cuHgKoRqM1yUo";
const s = loadOrCreateSession(APP, localStorage);       // browser

// Node / Bun: any KV works.
const m = new Map<string, string>();
const kv: KV = { getItem: (k) => m.get(k) ?? null, setItem: (k, v) => void m.set(k, v) };
const s2 = loadOrCreateSession(APP, kv);

console.log(hex(s.publicKey));          // the {session} for the gateway API
const backup = exportSession(APP, s);   // show to the player once

passkey.ts

Source: web/src/passkey.ts

Passkeys sign with P-256, but the ledger and rollup need Ed25519 from the session key. So the passkey derives the seed through the WebAuthn PRF extension:

salt = sha256("zol/session/v1/" ‖ app)                       // PRF input, fixed per app
seed = sha256("ZOL passkey session v1" ‖ app ‖ prf_output)   // session seed

The same passkey gives the same session on every device it syncs to. Without PRF support the pages fall back to a random session with a backup string.

Both functions store the credential ID (base64) in localStorage under zol:passkey:<app>. The RP name is hard-coded to "ZOL coin flip". A passkey is bound to the page's hostname, so the derived session depends on serving the page from the same host.

import { createPasskeySeed, seedFromPasskey, prfSupported } from "./passkey";
import { storeSession } from "./session";

if ((await prfSupported()) !== false) {
  const seed = await createPasskeySeed(APP);          // new player
  // or: const seed = await seedFromPasskey(APP);     // returning player, new device
  const s = storeSession(APP, seed, localStorage, "passkey");
}

ua.ts

Source: web/src/ua.ts

Payout address parsing: a ZIP 316 unified address (bech32m + F4Jumble + TLV items), or a raw 43-byte Orchard-format receiver as 86 hex chars. The memo carries the Orchard receiver (typecode 0x03); Ironwood uses the same receivers.

import { parsePayoutAddress } from "./ua";
const payout = parsePayoutAddress("utest1…", "testnet"); // Uint8Array(43)

gateway.ts

Source: web/src/gateway.ts. Endpoint semantics: gateway-api.md.

Network failures surface as the fetch error, not GatewayError. denominations and value are JS numbers (safe: zatoshi amounts are far below 2^53).

import { Gateway } from "./gateway";
import { hex } from "./session";

const gw = new Gateway("https://zol.cash/op0");
const info = await gw.app(APP);
const all = (info.operators ?? [gw.base]).map((u) => new Gateway(u));
const deposits = await gw.deposits(APP, hex(s.publicKey));

memo.ts

Source: web/src/memo.ts. Format: gateway-api.md § Deposit memo.

wire.ts

Source: crates/zol-wire/ts/wire.ts (symlinked at web/src/wire.ts). TypeScript twin of zol-wire; no imports.

deposit.ts

Source: web/src/deposit.ts

prepareDeposit:

1. GET app info from the first gateway; throws unless state === "active" and amountZat is one of denominations.
2. Parses payoutInput (parsePayoutAddress, network-checked).
3. Builds and signs the memo with expiry tip + EXPIRY_BLOCKS.
4. Registers the canonical memo (hex) with every gateway passed, in parallel. Throws if none accepted; throws if two operators return different session uas.
5. Returns the ZIP 321 link to the session's UA.

It does not call the payout check. On a device where the session may already have a balance, call Gateway#payoutCheck first (as house-page.ts does), since a different payout address voids the deposit.

import { Gateway } from "./gateway";
import { prepareDeposit } from "./deposit";
import { hex } from "./session";
import { parsePayoutAddress } from "./ua";

const first = new Gateway("https://zol.cash/op0");
const gws = ((await first.app(APP)).operators ?? [first.base]).map((u) => new Gateway(u));

const c = await first.payoutCheck(APP, hex(s.publicKey), hex(parsePayoutAddress(payoutUa, "testnet")));
if (c.bound && !c.matches) throw new Error("use the payout address bound to this session");

const d = await prepareDeposit(gws, APP, s, payoutUa, 1_000_000n /* 0.01 TAZ */);
console.log(d.link, d.registered, d.failed);   // show d.link as a QR code
// then poll first.deposits(APP, hex(s.publicKey)) until state === "credited"

chain.ts

Source: web/src/chain.ts. Account orders follow idl/zol_coinflip.json and idl/zol_ledger.json. Instruction data is the 8-byte Anchor discriminator sha256("global:<name>")[0..8] plus little-endian args.

Two connections are involved: base (Solana) and ER (the MagicBlock ephemeral rollup). Tables, pots and auctions are delegated to the rollup while a game runs; read them there when the base account's owner is DLP (the pages' readLive pattern). Rollup transactions cost no SOL: the session key can be the fee payer. Solana transactions need a funded fee payer.

Constants

Helpers

Pdas

new Pdas({ ledger, app }: Programs); Programs = { ledger: PublicKey; app: PublicKey } (app is the zol-coinflip program).

potId is 32 random bytes chosen by the table creator.

Coinflip

new Coinflip(p: Programs); .pdas: Pdas. Each method returns a TransactionInstruction. "Where" is where the pages send it.

Auctions

new Auctions(cf: Coinflip). Sealed-bid auction instructions.

Decoders

Each checks the 8-byte account discriminator (sha256("account:<Name>")[0..8]) and throws not a <Name> account otherwise.

Sending

sendSigned is for transactions signed by several parties, e.g. a server that is fee payer partially signs after the player signs (see web/house/auction.ts).

Examples

import { Buffer } from "buffer";
(globalThis as any).Buffer ??= Buffer;
import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import { Coinflip, DLP, decodeBalance, decodeApp, decodeTable, sendTx } from "./chain";

const base = new Connection("https://api.devnet.solana.com", "confirmed");
const er = new Connection("https://devnet-as.magicblock.app", "confirmed");
const cf = new Coinflip({
  ledger: new PublicKey("3qh6GRqjmVSeVctB6R7oYYsdG68oFyRDwnXGvKamib3Y"),
  app: new PublicKey("7G2o74qyLh477EuWUFdgumeB13kTCK1cuHgKoRqM1yUo"),
});
const me = s.keypair.publicKey;          // s: Session from session.ts
const feePayer: Keypair = s.keypair;     // or a funded relayer key

// Read the session's ledger balance (zatoshi).
const acc = await base.getAccountInfo(cf.pdas.balance(me));
const bal = acc ? decodeBalance(acc.data) : null;

// Read a table where it lives (base, or the rollup while delegated).
async function readLive(key: PublicKey) {
  const b = await base.getAccountInfo(key);
  return b && b.owner.equals(DLP) ? (await er.getAccountInfo(key)) ?? b : b;
}
const t = decodeTable((await readLive(cf.pdas.table(potId)))!.data);

// Solana: take a seat (fee payer pays SOL, the session key signs).
await sendTx(base, [cf.join(me, potId)], feePayer, [s.keypair]);

// Rollup: flip once the table is delegated (free; the session key pays).
const queue = new PublicKey("5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc");
await sendTx(er, [cf.flip(me, potId, queue, crypto.getRandomValues(new Uint8Array(32)))], s.keypair);

// Exit: mark the balance for exit and settle it in one Solana transaction.
const app = decodeApp((await base.getAccountInfo(cf.pdas.app()))!.data);
await sendTx(base, [cf.requestExit(me), cf.settle(feePayer.publicKey, app.nextSettlement, [me])], feePayer, [s.keypair]);

Notes and open points

• Balances below the ledger's minExit (decodeLedgerParams) cannot be withdrawn. The house page disables withdrawal below it; main.ts does not check it before requestExit.
• The decoders use fixed byte offsets matching the current program layouts; they are not generated from the IDL, so a program layout change needs a matching update here.