ckb-session-kit 0.0.0-stage → 2.0.0

package/dist/paywall.d.ts

@@ -0,0 +1,60 @@
+import { ccc } from "@ckb-ccc/core";
+import type { Session } from "./session.js";
+/** The memo for a payment: a short UTF-8 label, e.g. `read:article-1`. */
+export declare function paymentMemo(label: string): ccc.Hex;
+/** Whether `lock` runs the standard secp256k1-blake160 sighash_all code (`code`: that script on this network). */
+export declare const isSecp256k1Lock: (lock: ccc.Script, code?: {
+    codeHash: ccc.Hex;
+    hashType: ccc.HashType;
+}) => boolean;
+/**
+ * Which witnesses of `tx` a signature covers, given the locks of its inputs in
+ * order: the first witness of each input lock group whose lock signs (`signs`),
+ * and every witness past the inputs, which a sighash_all signature also covers.
+ *
+ * Any other witness can be changed by whoever relays the transaction without
+ * changing its hash: a session cell's (the session lock reads no witness) or an
+ * anyone-can-pay cell's taking a top-up (audit, 30 Oct). A memo there is nobody's.
+ */
+export declare function signedWitnesses(tx: ccc.Transaction, inputLocks: ccc.ScriptLike[], signs: (lock: ccc.Script) => boolean): (index: number) => boolean;
+/** Every witness carrying a memo (an `inputType`), with its index. */
+export declare function memoWitnesses(tx: ccc.Transaction): {
+    index: number;
+    memo: ccc.Hex;
+}[];
+/**
+ * The one witness carrying a memo and its index; undefined with none or several.
+ * Only witnesses `counts` accepts are looked at (`signedWitnesses`: those a
+ * signature covers); by default, all of them.
+ */
+export declare function soleMemo(tx: ccc.Transaction, counts?: (index: number) => boolean): {
+    index: number;
+    memo: ccc.Hex;
+} | undefined;
+export interface AccessProof {
+    txHash: ccc.Hex;
+    memo: ccc.Hex;
+    /** The session key's public key. */
+    publicKey: ccc.Hex;
+    signature: ccc.Hex;
+}
+/** The payer's side: prove that the key which paid `txHash` is asking. */
+export declare function signAccess(session: Session, txHash: ccc.HexLike, memo: ccc.HexLike): Promise<AccessProof>;
+export type AccessCheck = {
+    ok: true;
+    paid: bigint;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The server's side. `to` is the recipient that must have been paid, as a lock
+ * script; `minAmount` in shannons. With `token` (an xUDT type script), the
+ * payment is counted in that token's units instead, and `minAmount` is in units.
+ */
+export declare function verifyAccess(client: ccc.Client, proof: AccessProof, expect: {
+    to: ccc.ScriptLike;
+    minAmount: bigint;
+    memo: ccc.HexLike;
+    token?: ccc.ScriptLike;
+}): Promise<AccessCheck>;

package/dist/paywall.js

@@ -0,0 +1,175 @@
+import { ccc } from "@ckb-ccc/core";
+import { tokenAmount } from "./onchain.js";
+import { sessionSigner } from "./transfer.js";
+/**
+ * Paid access, checked against the chain with no database.
+ *
+ * The payer pays with `spendInSession(…, { memo })`. The memo goes into the
+ * witness of the session key's own input, which that key's signature covers, so
+ * the payment commits to what it pays for: it cannot be reused for something else.
+ *
+ * To claim the access, the payer signs a request with the same session key
+ * (`signAccess`). A server checks both with `verifyAccess`: the payment is
+ * committed, the recipient gained enough, the memo matches, and the request is
+ * signed by the key that paid. Anyone can see the payment on-chain; only the
+ * payer can use it.
+ *
+ * One payment, one claim: a payment transaction may carry exactly one memo in
+ * the witnesses a signature covers. Otherwise one transaction could pay the
+ * creator once and carry memos from several keys, each claiming the full amount
+ * for a different article or reader. A memo in a witness nobody signed (the
+ * session cell's) does not count: whoever relays the payment could add one.
+ */
+/** A session payment has a handful of inputs; more is not one, and costs RPC calls to check. */
+const MAX_PAYMENT_INPUTS = 16;
+/** The memo for a payment: a short UTF-8 label, e.g. `read:article-1`. */
+export function paymentMemo(label) {
+    return ccc.hexFrom(ccc.bytesFrom(label, "utf8"));
+}
+/**
+ * The standard secp256k1-blake160 sighash_all lock, the session key's own lock: the
+ * same code on mainnet and testnet. Its signature covers the first witness of its
+ * lock group (and the rest of the group, and every witness past the inputs).
+ */
+const SECP256K1_BLAKE160 = {
+    codeHash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
+    hashType: "type",
+};
+/** Whether `lock` runs the standard secp256k1-blake160 sighash_all code (`code`: that script on this network). */
+export const isSecp256k1Lock = (lock, code = SECP256K1_BLAKE160) => lock.codeHash === code.codeHash && lock.hashType === code.hashType;
+/**
+ * Which witnesses of `tx` a signature covers, given the locks of its inputs in
+ * order: the first witness of each input lock group whose lock signs (`signs`),
+ * and every witness past the inputs, which a sighash_all signature also covers.
+ *
+ * Any other witness can be changed by whoever relays the transaction without
+ * changing its hash: a session cell's (the session lock reads no witness) or an
+ * anyone-can-pay cell's taking a top-up (audit, 30 Oct). A memo there is nobody's.
+ */
+export function signedWitnesses(tx, inputLocks, signs) {
+    const locks = inputLocks.map((l) => ccc.Script.from(l));
+    return (i) => i >= tx.inputs.length || (i < locks.length && signs(locks[i]) && !locks.slice(0, i).some((l) => l.eq(locks[i])));
+}
+/** Every witness carrying a memo (an `inputType`), with its index. */
+export function memoWitnesses(tx) {
+    const found = [];
+    for (let i = 0; i < tx.witnesses.length; i++) {
+        let inputType;
+        try {
+            inputType = tx.getWitnessArgsAt(i)?.inputType;
+        }
+        catch {
+            continue; // not WitnessArgs: carries no memo
+        }
+        if (inputType !== undefined)
+            found.push({ index: i, memo: inputType });
+    }
+    return found;
+}
+/**
+ * The one witness carrying a memo and its index; undefined with none or several.
+ * Only witnesses `counts` accepts are looked at (`signedWitnesses`: those a
+ * signature covers); by default, all of them.
+ */
+export function soleMemo(tx, counts = () => true) {
+    const found = memoWitnesses(tx).filter((m) => counts(m.index));
+    return found.length === 1 ? found[0] : undefined;
+}
+function accessMessage(txHash, memo) {
+    return `ckb-session-kit access ${ccc.hexFrom(txHash)} ${ccc.hexFrom(memo)}`;
+}
+/** The payer's side: prove that the key which paid `txHash` is asking. */
+export async function signAccess(session, txHash, memo) {
+    const signer = sessionSigner(session, new ccc.ClientPublicTestnet());
+    const { signature } = await signer.signMessage(accessMessage(txHash, memo));
+    return { txHash: ccc.hexFrom(txHash), memo: ccc.hexFrom(memo), publicKey: signer.publicKey, signature: ccc.hexFrom(signature) };
+}
+/**
+ * The server's side. `to` is the recipient that must have been paid, as a lock
+ * script; `minAmount` in shannons. With `token` (an xUDT type script), the
+ * payment is counted in that token's units instead, and `minAmount` is in units.
+ */
+export async function verifyAccess(client, proof, expect) {
+    if (ccc.hexFrom(proof.memo) !== ccc.hexFrom(expect.memo))
+        return { ok: false, reason: "memo does not match" };
+    // Always the CKB secp256k1 scheme: a sign type chosen by the caller is not trusted.
+    let signed = false;
+    try {
+        signed = ccc.verifyMessageCkbSecp256k1(accessMessage(proof.txHash, proof.memo), proof.signature, proof.publicKey);
+    }
+    catch {
+        signed = false;
+    }
+    if (!signed)
+        return { ok: false, reason: "request not signed by the given key" };
+    // Not getTransaction: when the node no longer knows a transaction (reorged out,
+    // replaced by a conflicting spend), it answers from CCC's cache, where a payment
+    // once seen committed stays committed (audit, 31 Oct).
+    const res = await client.getTransactionNoCache(proof.txHash);
+    if (!res)
+        return { ok: false, reason: "payment not found" };
+    if (res.status !== "committed")
+        return { ok: false, reason: `payment is ${res.status}, not committed` };
+    const tx = res.transaction;
+    // Cheap checks first, before resolving any input over RPC.
+    if (tx.inputs.length > MAX_PAYMENT_INPUTS)
+        return { ok: false, reason: "not a session payment: too many inputs" };
+    const memos = memoWitnesses(tx);
+    if (!memos.length)
+        return { ok: false, reason: "a payment must carry exactly one memo" };
+    // The payer's lock: the standard secp256k1 lock of the key that signed the request.
+    const payerLock = (await new ccc.SignerCkbPublicKey(client, proof.publicKey).getAddressObjSecp256k1()).script;
+    // Before all of them, only the inputs whose witness carries a memo, until one is
+    // the payer's (usually the first): anyone can sign a request for someone else's
+    // public payment, and must not get to make the server resolve every input.
+    const known = new Map();
+    let paidByKey = false;
+    for (const { index } of memos) {
+        if (index >= tx.inputs.length)
+            continue;
+        const cell = await client.getCell(tx.inputs[index].previousOutput);
+        known.set(index, cell);
+        if (cell?.cellOutput.lock.eq(payerLock)) {
+            paidByKey = true;
+            break;
+        }
+    }
+    if (!paidByKey)
+        return { ok: false, reason: "the signing key did not pay this transaction" };
+    const to = ccc.Script.from(expect.to);
+    const token = expect.token && ccc.Script.from(expect.token);
+    // What a cell gives the recipient: its capacity, or with a token its units of that exact token
+    // (a committed xUDT cell always holds the 16-byte amount).
+    const value = (o, data) => !o.lock.eq(to) ? 0n : !token ? o.capacity : o.type?.eq(token) ? tokenAmount(data) : 0n;
+    // The rest at once, reusing those already looked up.
+    const inputs = await Promise.all(tx.inputs.map((input, i) => (known.has(i) ? known.get(i) : client.getCell(input.previousOutput))));
+    let payerInput = -1;
+    let toIn = 0n;
+    for (const [i, cell] of inputs.entries()) {
+        if (!cell)
+            return { ok: false, reason: "an input of the payment cannot be resolved" };
+        if (payerInput < 0 && cell.cellOutput.lock.eq(payerLock))
+            payerInput = i;
+        toIn += value(cell.cellOutput, cell.outputData);
+    }
+    if (payerInput < 0)
+        return { ok: false, reason: "the signing key did not pay this transaction" };
+    // One memo among the witnesses a signature covers. A memo in a witness nobody
+    // signed (the session cell's, say) was not put there by the payer and cannot
+    // void the payment; several signed ones could each claim it (audit, 30 Oct).
+    const covered = signedWitnesses(tx, inputs.map((c) => c.cellOutput.lock), (lock) => isSecp256k1Lock(lock, payerLock));
+    if (!soleMemo(tx, covered))
+        return { ok: false, reason: "a payment must carry exactly one memo" };
+    // The witness the payer's lock verified (the first of its group) must carry the memo.
+    const witness = tx.getWitnessArgsAt(payerInput);
+    if (!witness?.inputType || ccc.hexFrom(witness.inputType) !== ccc.hexFrom(expect.memo)) {
+        return { ok: false, reason: "the payment does not carry this memo" };
+    }
+    const toOut = tx.outputs.reduce((sum, o, i) => sum + value(o, tx.outputsData[i] ?? "0x"), 0n);
+    const paid = toOut - toIn;
+    if (paid < expect.minAmount) {
+        const shown = token ? `${paid} units` : `${ccc.fixedPointToString(paid)} CKB`;
+        return { ok: false, reason: `paid ${shown}, below the price` };
+    }
+    return { ok: true, paid };
+}

package/dist/place.d.ts

@@ -0,0 +1,113 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * CKB Place: a shared pixel board kept on-chain, with no database.
+ *
+ * A player pays the board's anyone-can-pay address with
+ * `spendInSession(…, { to: board, amount: price × pixels, topUp: true, memo })`,
+ * where `memo` (from `encodePlacement`) lists the pixels. Anyone can rebuild the
+ * board from the chain: take the transactions that touch the board's lock, keep
+ * those that paid enough for their memo (`checkPlacement`), and apply them in
+ * chain order (`applyPlacements`). Last write wins.
+ *
+ * This module is the pure part: no network. Finding and resolving the
+ * transactions is the caller's.
+ *
+ * Memo format, version 1 (bytes):
+ *
+ *     "px1" (0x70 0x78 0x31) | x u8 | y u8 | colour u8 | x | y | colour | …
+ *
+ * One to `maxPixels` pixels; each must lie on the board and use a palette index
+ * below `colours`. Anything else (wrong magic, a partial triple, a pixel off the
+ * board, too many pixels) makes the whole memo invalid: memos come from anyone,
+ * and a payment is never half-applied. A pixel may appear twice; each entry is
+ * paid for and the later one wins.
+ */
+export interface PlaceBoard {
+    /** Columns, 1–256 (x is one byte). */
+    width: number;
+    /** Rows, 1–256 (y is one byte). */
+    height: number;
+    /** Palette size, 1–256; a colour is an index below it. */
+    colours: number;
+    /** Shannons per pixel. */
+    price: bigint;
+    /** Most pixels one memo may carry; bounds the memo at 3 + 3 × maxPixels bytes. */
+    maxPixels: number;
+}
+/** The demo's board: 32×32, 16 colours, 0.1 CKB a pixel, up to 32 pixels a payment. */
+export declare const PLACE_BOARD: PlaceBoard;
+export interface Pixel {
+    x: number;
+    y: number;
+    colour: number;
+}
+export declare class PlaceMemoError extends Error {
+    constructor(message: string);
+}
+/** The memo for a placement. Throws `PlaceMemoError` for an empty, oversized or off-board list. */
+export declare function encodePlacement(pixels: Pixel[], board?: PlaceBoard): ccc.Hex;
+/** The pixels in a memo, or `undefined` if it is not a valid version-1 memo for this board. Never throws. */
+export declare function decodePlacement(memo: ccc.HexLike, board?: PlaceBoard): Pixel[] | undefined;
+/** What a placement costs, in shannons. */
+export declare function placementPrice(pixels: number, board?: PlaceBoard): bigint;
+/**
+ * The placement memo of `tx` and where it sits (the witness index), or `undefined`.
+ *
+ * With `inputs` (the cells `tx` spends, resolved, in input order) this is exact:
+ * exactly one memo among the witnesses a signature covers (`signedWitnesses`: the
+ * first witness of a secp256k1 lock group, as the session key's key cell has, or
+ * one past the inputs), at an input's index, and a valid placement. A memo in a
+ * witness nobody signed (the session cell's, the board's) is ignored: whoever
+ * relays the transaction could have put it there (audit, 30 Oct).
+ *
+ * Without `inputs` it is the cheap check, before resolving any input: `undefined`
+ * means `tx` is certainly no placement; otherwise the first witness at an input's
+ * index holding a valid placement, which `checkPlacement` then settles.
+ */
+export declare function placementMemo(tx: ccc.TransactionLike, board?: PlaceBoard, inputs?: ccc.CellOutputLike[]): {
+    index: number;
+    pixels: Pixel[];
+} | undefined;
+export type PlacementCheck = {
+    ok: true;
+    pixels: Pixel[];
+    paid: bigint;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
+ * the cells `tx` spends, resolved, in input order.
+ *
+ * - exactly one memo among the witnesses a signature covers, and a valid one,
+ *   in the first witness of a secp256k1 lock group that is not the board's
+ *   (`placementMemo` with `inputs`): the witness the payer's lock signs (the
+ *   session key's key cell), so the payment commits to these pixels and no relay
+ *   can swap them, nor add a memo of its own that counts;
+ * - the board's lock gained at least `price × pixels` (outputs minus inputs).
+ */
+export declare function checkPlacement(tx: ccc.TransactionLike, inputs: ccc.CellOutputLike[], boardLock: ccc.ScriptLike, board?: PlaceBoard): PlacementCheck;
+/** A checked placement and where it sits in the chain. */
+export interface Placement {
+    txHash: ccc.Hex;
+    blockNumber: bigint;
+    /** Position of the transaction in its block. */
+    txIndex: number;
+    pixels: Pixel[];
+}
+/** One square of the board: its colour and the transaction that set it last. */
+export interface PlacedPixel {
+    colour: number;
+    txHash: ccc.Hex;
+    blockNumber: bigint;
+}
+/** Row-major, `width × height` long; `undefined` where nothing has been placed. */
+export type BoardState = (PlacedPixel | undefined)[];
+/**
+ * The board after `placements`, applied in chain order (block number, then
+ * position in the block) whatever order they are given in; within one
+ * placement, in memo order. Last write wins. A transaction listed twice counts
+ * once, and a pixel off the board is skipped.
+ */
+export declare function applyPlacements(placements: Placement[], board?: PlaceBoard): BoardState;

package/dist/place.js

@@ -0,0 +1,155 @@
+import { ccc } from "@ckb-ccc/core";
+import { isSecp256k1Lock, memoWitnesses, signedWitnesses, soleMemo } from "./paywall.js";
+/** The demo's board: 32×32, 16 colours, 0.1 CKB a pixel, up to 32 pixels a payment. */
+export const PLACE_BOARD = { width: 32, height: 32, colours: 16, price: 10000000n, maxPixels: 32 };
+export class PlaceMemoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlaceMemoError";
+    }
+}
+const MAGIC = [0x70, 0x78, 0x31]; // "px1"
+const byteSized = (n) => Number.isInteger(n) && n >= 1 && n <= 256;
+function checkBoard(board) {
+    if (!byteSized(board.width) || !byteSized(board.height) || !byteSized(board.colours)) {
+        throw new PlaceMemoError("board width, height and colours must be 1–256");
+    }
+    if (!Number.isInteger(board.maxPixels) || board.maxPixels < 1)
+        throw new PlaceMemoError("maxPixels must be at least 1");
+    if (board.price <= 0n)
+        throw new PlaceMemoError("price must be positive");
+}
+function onBoard(p, board) {
+    const ok = (v, max) => Number.isInteger(v) && v >= 0 && v < max;
+    return ok(p.x, board.width) && ok(p.y, board.height) && ok(p.colour, board.colours);
+}
+/** The memo for a placement. Throws `PlaceMemoError` for an empty, oversized or off-board list. */
+export function encodePlacement(pixels, board = PLACE_BOARD) {
+    checkBoard(board);
+    if (!pixels.length)
+        throw new PlaceMemoError("no pixels to place");
+    if (pixels.length > board.maxPixels)
+        throw new PlaceMemoError(`at most ${board.maxPixels} pixels per placement`);
+    const bytes = [...MAGIC];
+    for (const p of pixels) {
+        if (!onBoard(p, board))
+            throw new PlaceMemoError(`pixel (${p.x}, ${p.y}) colour ${p.colour} is not on the board`);
+        bytes.push(p.x, p.y, p.colour);
+    }
+    return ccc.hexFrom(new Uint8Array(bytes));
+}
+/** The pixels in a memo, or `undefined` if it is not a valid version-1 memo for this board. Never throws. */
+export function decodePlacement(memo, board = PLACE_BOARD) {
+    let bytes;
+    try {
+        checkBoard(board);
+        bytes = ccc.bytesFrom(memo);
+    }
+    catch {
+        return undefined;
+    }
+    // Length first: an oversized memo is refused before it is read.
+    const n = (bytes.length - MAGIC.length) / 3;
+    if (!Number.isInteger(n) || n < 1 || n > board.maxPixels)
+        return undefined;
+    if (MAGIC.some((b, i) => bytes[i] !== b))
+        return undefined;
+    const pixels = [];
+    for (let i = MAGIC.length; i < bytes.length; i += 3) {
+        const p = { x: bytes[i], y: bytes[i + 1], colour: bytes[i + 2] };
+        if (!onBoard(p, board))
+            return undefined;
+        pixels.push(p);
+    }
+    return pixels;
+}
+/** What a placement costs, in shannons. */
+export function placementPrice(pixels, board = PLACE_BOARD) {
+    return board.price * BigInt(pixels);
+}
+/**
+ * The placement memo of `tx` and where it sits (the witness index), or `undefined`.
+ *
+ * With `inputs` (the cells `tx` spends, resolved, in input order) this is exact:
+ * exactly one memo among the witnesses a signature covers (`signedWitnesses`: the
+ * first witness of a secp256k1 lock group, as the session key's key cell has, or
+ * one past the inputs), at an input's index, and a valid placement. A memo in a
+ * witness nobody signed (the session cell's, the board's) is ignored: whoever
+ * relays the transaction could have put it there (audit, 30 Oct).
+ *
+ * Without `inputs` it is the cheap check, before resolving any input: `undefined`
+ * means `tx` is certainly no placement; otherwise the first witness at an input's
+ * index holding a valid placement, which `checkPlacement` then settles.
+ */
+export function placementMemo(tx, board = PLACE_BOARD, inputs) {
+    const t = ccc.Transaction.from(tx);
+    if (!inputs) {
+        for (const m of memoWitnesses(t)) {
+            const pixels = m.index < t.inputs.length ? decodePlacement(m.memo, board) : undefined;
+            if (pixels)
+                return { index: m.index, pixels };
+        }
+        return undefined;
+    }
+    if (inputs.length !== t.inputs.length)
+        return undefined;
+    const locks = inputs.map((c) => ccc.CellOutput.from(c).lock);
+    // Two signed memos: which one was paid for is ambiguous.
+    const found = soleMemo(t, signedWitnesses(t, locks, (lock) => isSecp256k1Lock(lock)));
+    if (!found || found.index >= t.inputs.length)
+        return undefined;
+    const pixels = decodePlacement(found.memo, board);
+    return pixels && { index: found.index, pixels };
+}
+/**
+ * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
+ * the cells `tx` spends, resolved, in input order.
+ *
+ * - exactly one memo among the witnesses a signature covers, and a valid one,
+ *   in the first witness of a secp256k1 lock group that is not the board's
+ *   (`placementMemo` with `inputs`): the witness the payer's lock signs (the
+ *   session key's key cell), so the payment commits to these pixels and no relay
+ *   can swap them, nor add a memo of its own that counts;
+ * - the board's lock gained at least `price × pixels` (outputs minus inputs).
+ */
+export function checkPlacement(tx, inputs, boardLock, board = PLACE_BOARD) {
+    const t = ccc.Transaction.from(tx);
+    if (inputs.length !== t.inputs.length)
+        return { ok: false, reason: "inputs not resolved" };
+    const memo = placementMemo(t, board, inputs);
+    if (!memo)
+        return { ok: false, reason: "no valid placement memo" };
+    const lock = ccc.Script.from(boardLock);
+    const cells = inputs.map((c) => ccc.CellOutput.from(c));
+    if (cells[memo.index].lock.eq(lock))
+        return { ok: false, reason: "the memo is in the board's own witness" };
+    const sum = (cs) => cs.reduce((s, c) => (c.lock.eq(lock) ? s + c.capacity : s), 0n);
+    const paid = sum(t.outputs) - sum(cells);
+    const price = placementPrice(memo.pixels.length, board);
+    if (paid < price) {
+        return { ok: false, reason: `paid ${ccc.fixedPointToString(paid)} CKB for ${memo.pixels.length} pixel(s), below ${ccc.fixedPointToString(price)}` };
+    }
+    return { ok: true, pixels: memo.pixels, paid };
+}
+/**
+ * The board after `placements`, applied in chain order (block number, then
+ * position in the block) whatever order they are given in; within one
+ * placement, in memo order. Last write wins. A transaction listed twice counts
+ * once, and a pixel off the board is skipped.
+ */
+export function applyPlacements(placements, board = PLACE_BOARD) {
+    const state = new Array(board.width * board.height).fill(undefined);
+    const seen = new Set();
+    const ordered = [...placements].sort((a, b) => a.blockNumber !== b.blockNumber ? (a.blockNumber < b.blockNumber ? -1 : 1) : a.txIndex - b.txIndex);
+    for (const p of ordered) {
+        if (seen.has(p.txHash))
+            continue;
+        seen.add(p.txHash);
+        for (const px of p.pixels) {
+            if (!onBoard(px, board))
+                continue;
+            state[px.y * board.width + px.x] = { colour: px.colour, txHash: p.txHash, blockNumber: p.blockNumber };
+        }
+    }
+    return state;
+}

package/dist/session.d.ts

@@ -0,0 +1,71 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * What a session key may do. This is the off-chain mirror of what the session
+ * lock script will enforce on-chain (Week 4): the browser refuses out-of-scope
+ * requests early, and the chain refuses them regardless.
+ */
+export interface SessionScope {
+    /** Largest amount one transaction may move, in shannons. */
+    maxPerTx: bigint;
+    /** Recipient addresses allowed. Omitted means any recipient. */
+    recipients?: string[];
+}
+export interface SessionPolicy {
+    expiresAt: Date;
+    scope: SessionScope;
+}
+export interface Session {
+    /** Never leaves the browser. */
+    privateKey: ccc.Hex;
+    publicKey: ccc.Hex;
+    policy: SessionPolicy;
+    /** Set once the owner has funded the session under the on-chain session lock. */
+    onchain?: {
+        ownerLock: {
+            codeHash: ccc.Hex;
+            hashType: ccc.HashType;
+            args: ccc.Hex;
+        };
+        minInterval: bigint;
+        recipientLockHash?: ccc.Hex;
+        /** A token session: the xUDT type its cells hold, and the most units one spend may move. */
+        token?: {
+            type: {
+                codeHash: ccc.Hex;
+                hashType: ccc.HashType;
+                args: ccc.Hex;
+            };
+            maxPerTx: bigint;
+        };
+        /** The funding transaction, so a key is not forgotten while its funds are still on the way. */
+        openTx?: ccc.Hex;
+    };
+}
+export interface CreateOptions {
+    now?: Date;
+    /** Injectable for tests; defaults to the platform CSPRNG. */
+    randomBytes?: (n: number) => Uint8Array;
+}
+/**
+ * Why a policy error is not about the request itself: "payto-not-anyone-can-pay",
+ * the payer's own setup (a charge can never top such a `payTo` up); or
+ * "too-many-cells", more cells under a subscription's lock than a status or a
+ * charge reads (`MAX_SUBSCRIPTION_CELLS`).
+ */
+export type SessionPolicyReason = "payto-not-anyone-can-pay" | "too-many-cells" | "owner-lock-unsafe" | "owner-lock-unreviewed";
+export declare class SessionPolicyError extends Error {
+    readonly reason?: SessionPolicyReason;
+    constructor(message: string, reason?: SessionPolicyReason);
+}
+export declare function createSession(policy: SessionPolicy, options?: CreateOptions): Session;
+export declare function isActive(session: Session, now?: Date): boolean;
+export type ScopeCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkRequest(session: Session, request: {
+    to: string;
+    amount: bigint;
+}, now?: Date): ScopeCheck;

package/dist/session.js

@@ -0,0 +1,57 @@
+import { ccc } from "@ckb-ccc/core";
+export class SessionPolicyError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.name = "SessionPolicyError";
+        if (reason)
+            this.reason = reason;
+    }
+}
+const SECP256K1_N = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
+export function createSession(policy, options = {}) {
+    const now = options.now ?? new Date();
+    if (!Number.isFinite(policy.expiresAt.getTime())) {
+        throw new SessionPolicyError("expiresAt is not a valid date");
+    }
+    if (policy.expiresAt.getTime() <= now.getTime()) {
+        throw new SessionPolicyError("expiresAt must be in the future");
+    }
+    if (policy.scope.maxPerTx <= 0n) {
+        throw new SessionPolicyError("scope.maxPerTx must be positive");
+    }
+    if (policy.scope.recipients?.length === 0) {
+        throw new SessionPolicyError("scope.recipients must be omitted or non-empty");
+    }
+    const random = options.randomBytes ?? ((n) => crypto.getRandomValues(new Uint8Array(n)));
+    let privateKey;
+    // Rejection-sample until the key is a valid secp256k1 scalar (1..n-1).
+    for (;;) {
+        const candidate = ccc.hexFrom(random(32));
+        const k = BigInt(candidate);
+        if (k > 0n && k < SECP256K1_N) {
+            privateKey = candidate;
+            break;
+        }
+    }
+    // The signer only derives the public key here; no network call is made.
+    const signer = new ccc.SignerCkbPrivateKey(new ccc.ClientPublicTestnet(), privateKey);
+    return { privateKey, publicKey: signer.publicKey, policy };
+}
+export function isActive(session, now = new Date()) {
+    return now.getTime() < session.policy.expiresAt.getTime();
+}
+export function checkRequest(session, request, now = new Date()) {
+    if (!isActive(session, now))
+        return { ok: false, reason: "session expired" };
+    const { scope } = session.policy;
+    if (request.amount <= 0n)
+        return { ok: false, reason: "amount must be positive" };
+    if (request.amount > scope.maxPerTx) {
+        return { ok: false, reason: `amount exceeds maxPerTx (${ccc.fixedPointToString(scope.maxPerTx)} CKB)` };
+    }
+    if (scope.recipients && !scope.recipients.includes(request.to)) {
+        return { ok: false, reason: "recipient not in scope" };
+    }
+    return { ok: true };
+}

package/dist/store.d.ts

@@ -0,0 +1,27 @@
+import type { Session } from "./session.js";
+/**
+ * Where a session lives between page loads. The key never leaves the device:
+ * the browser store writes to IndexedDB, which is per-origin and local.
+ */
+export interface SessionStore {
+    load(): Promise<Session | undefined>;
+    /**
+     * Stores `session`. Refuses (SessionStoreConflict) to replace a *different*
+     * session: its key may hold funds, and another tab may have just saved it. Also
+     * refuses to replace the same session's on-chain binding with none.
+     */
+    save(session: Session): Promise<void>;
+    /** Forgets `session`, only if it is still the stored one; another tab may have replaced it. */
+    clear(session: Session): Promise<void>;
+}
+export declare class SessionStoreConflict extends Error {
+    constructor();
+}
+export declare function serializeSession(s: Session): string;
+export declare function deserializeSession(json: string): Session;
+export declare function memoryStore(): SessionStore;
+/**
+ * One session per `key`. Pages on the same origin that each run their own
+ * session (a wallet page and a reader page, say) pass different keys.
+ */
+export declare function indexedDbStore(idb?: IDBFactory, key?: string): SessionStore;