ckb-session-kit 0.0.0-stage → 2.0.0

package/dist/subscription.js

@@ -0,0 +1,959 @@
+import { ccc } from "@ckb-ccc/core";
+import { relativeBlocksSince, sessionLockCellDep, sessionLockScript, } from "./lock.js";
+import { addTopUp, assertPlainXudt, assertSigningLock, checkSigningLock, isAnyoneCanPay, keyCellFloor, ownerSweep, ownOrigin, plainXudtFault, randomPick, completeFeeOrNoFeeCell, rebuildOnDeadInputs, SessionBalanceError, signAndSend, tokenAmount, tokenData, withoutDeadCached, withinU128, } from "./onchain.js";
+import { assertCurrentDeployment } from "./deployment.js";
+import { SessionPolicyError } from "./session.js";
+const tokenOf = (sub) => sub.token && ccc.Script.from(sub.token.type);
+export function subscriptionLock(deployment, sub) {
+    const token = tokenOf(sub);
+    return sessionLockScript(deployment, {
+        ownerLockHash: sub.subscriberLockHash,
+        sessionLockHash: sub.chargerLockHash,
+        // In a token subscription no CKB may leave: the charger pays the fee from its own cell.
+        maxPerTx: token ? 0n : sub.price,
+        minInterval: sub.periodBlocks,
+        ...(token && { token: { typeHash: token.hash(), maxPerTx: sub.price } }),
+        recipientLockHash: sub.payToLockHash,
+    });
+}
+/** Throws unless the three roles and the numbers make a subscription the lock can enforce as meant. */
+function assertTerms(sub) {
+    if (sub.price <= 0n)
+        throw new SessionPolicyError("price must be positive");
+    // min_interval 0 means no rate limit at all: the charger could take the price every block.
+    if (sub.periodBlocks <= 0n)
+        throw new SessionPolicyError("periodBlocks must be positive");
+    relativeBlocksSince(sub.periodBlocks);
+    if (sub.payToLockHash === sub.chargerLockHash) {
+        // With a recipient set, outputs under the key's lock may not grow (error 17).
+        throw new SessionPolicyError("payTo must differ from the charger: a charge to the charger's own lock is refused (error 17)");
+    }
+    if (sub.chargerLockHash === sub.subscriberLockHash)
+        throw new SessionPolicyError("the charger must not be the subscriber");
+    if (sub.payToLockHash === sub.subscriberLockHash)
+        throw new SessionPolicyError("payTo must not be the subscriber");
+}
+/**
+ * The memo an opening commits to, binding the subscription to one account at the
+ * creator: a hash, so the account id never appears on-chain and can double as a
+ * secret the subscriber's browser presents to the creator.
+ */
+export function subscriptionMemo(account) {
+    return ccc.hashCkb(ccc.bytesFrom(`ckb-session-kit subscribe ${account}`, "utf8"));
+}
+/**
+ * Plain (untyped) cells under a subscription's lock, with or without data: the
+ * charger may write data into a change cell, and such a cell must still be found,
+ * charged and swept (review L2).
+ *
+ * In a token subscription, the cells typed with exactly its token and holding at
+ * least the 16-byte amount (the lock keeps a charge's change at exactly 16).
+ * Plain CKB sent to the same lock holds no tokens and cannot pay a price; it is
+ * left to `recoverSessions`. Cells whose tokens would overflow a u128 are left out
+ * (`withinU128`).
+ *
+ * The indexer filters by kind (`kindFilter`: no type script; or exactly the
+ * token's type script), so cells of any other kind are never listed and never
+ * count toward `cap`: anyone can create them, they cannot pay a price, and one
+ * with a type script that refuses to be spent could never be cleared (mentor
+ * review, 2 Nov). Only cells that are really of the kind count toward `cap`
+ * (review W6 M1), and the listing itself is read at most `RAW_READS * cap`
+ * deep, for an indexer that would list more than the filter asks.
+ */
+async function subscriptionCells(client, lock, token, 
+/** Refuse ("too-many-cells") once more than this many cells of this kind sit under the lock. */
+cap) {
+    const cells = [];
+    let read = 0;
+    for await (const cell of client.findCells({ script: lock, scriptType: "lock", scriptSearchMode: "exact", filter: kindFilter(token), withData: true })) {
+        if (cap !== undefined && ++read > RAW_READS * cap)
+            throw tooManyCells(cap);
+        if (!ofKind(cell, token))
+            continue;
+        if (cap !== undefined && cells.length >= cap)
+            throw tooManyCells(cap);
+        cells.push(cell);
+    }
+    // Cells only CCC's cache still lists, spent since by another client, would make a charge or a cancel fail.
+    const live = await withoutDeadCached(client, lock, cells);
+    // A planted cell of 2^128-1 free tokens would block charges and the cancel; the
+    // subscriber's and the charger's own cells are always kept.
+    return token ? withinU128(client, live) : live;
+}
+/**
+ * The indexer filter for a subscription's own kind of cell under its lock: no
+ * type script, or exactly its token. The indexer matches a filter script by args
+ * prefix, and xUDT with a zero flags word ignores bytes after it, so anyone can
+ * create zero-amount cells of `xUDT(token.args ++ anything)` (review W6 M1);
+ * the length range (33 bytes plus the args, as the indexer and CCC count a
+ * script) leaves only the token itself, as CCC's `completeInputsByUdt` does.
+ */
+const kindFilter = (token) => token
+    ? { script: token, scriptLenRange: [token.occupiedSize, token.occupiedSize + 1] }
+    : { scriptLenRange: [0, 1] };
+/** Whether `cell` is of the subscription's kind: untyped, or typed with exactly `token` and holding its amount. */
+const ofKind = (cell, token) => token ? cell.cellOutput.type?.eq(token) === true && ccc.bytesFrom(cell.outputData).length >= 16 : !cell.cellOutput.type;
+/** Listed cells read per cell a scan may keep: only an indexer that ignored the filter would list other ones. */
+const RAW_READS = 8;
+/**
+ * Look-alikes of a token subscription's token under its lock (review W6 M1):
+ * cells typed with the token's code and args that start with the token's args
+ * but are longer. The subscription never makes them, so every one was planted.
+ * Only those an owner sweep can spend are kept: a plain xUDT (zero flags, so no
+ * extension script that could refuse the spend) holding an amount. At most
+ * `budget` listed cells are read when given; `more` says some were left unread.
+ */
+async function lookalikeCells(client, lock, token, budget) {
+    const xudt = await client.getKnownScript(ccc.KnownScript.XUdt);
+    const cells = [];
+    let read = 0;
+    let more = false;
+    for await (const cell of client.findCells({ script: lock, scriptType: "lock", scriptSearchMode: "exact", filter: { script: token }, withData: true })) {
+        if (budget !== undefined && ++read > budget) {
+            more = true;
+            break;
+        }
+        const type = cell.cellOutput.type;
+        if (!type || type.eq(token) || !type.args.startsWith(token.args) || type.codeHash !== token.codeHash || type.hashType !== token.hashType)
+            continue;
+        if (plainXudtFault(type, xudt) !== undefined || ccc.bytesFrom(cell.outputData).length < 16)
+            continue;
+        cells.push(cell);
+    }
+    return { cells: await withinU128(client, await withoutDeadCached(client, lock, cells)), more };
+}
+/**
+ * The most cells under one subscription's lock that a status or a charge reads
+ * (security audit, 30 Oct). Anyone can create cells under any lock, and each
+ * cell read costs RPC calls (its creating transaction, and that transaction's
+ * inputs), so without a bound one request could be made to cost thousands. A
+ * subscription in use holds one cell, or a few after top-ups; 16 is far above that.
+ *
+ * Beyond it, a status or a charge is refused with a `SessionPolicyError` of
+ * reason "too-many-cells", never answered from part of the cells: the cells
+ * left unread could hold the newest charge (so access would be denied as
+ * unpaid, with a wrong balance) or a mature cell (so a charge would leave it free
+ * to pay a second price in the same period). Refusing grants nothing and charges
+ * nothing. Only cells of the subscription's own kind count (plain CKB, or its
+ * token). The subscriber clears cells planted among them with
+ * `clearPlantedCells`, which leaves the subscription's own cells as they are,
+ * or with `cancelSubscription`.
+ */
+export const MAX_SUBSCRIPTION_CELLS = 16;
+/**
+ * The most transactions that spent a cell under the lock that `lastCharge` reads
+ * in the recent history (each is fetched, with its inputs), on the same grounds.
+ * Only the subscriber and the charger can make those.
+ */
+const MAX_HISTORY = 4 * MAX_SUBSCRIPTION_CELLS;
+/**
+ * The most transactions that only created cells under the lock that `lastCharge`
+ * pages past in the recent history (review W6 M2). Anyone can make those, but
+ * they are skipped without a fetch, so only the indexer's pages cost anything
+ * (`HISTORY_PAGE` entries each). Past it, a status or a charge is refused
+ * rather than stopping short of the last charge: blocking one period this way
+ * takes over 1024 transactions within it, each locking up at least a cell's
+ * size (153 CKB) under the subscription's lock.
+ */
+export const MAX_CREATED_HISTORY = 64 * MAX_SUBSCRIPTION_CELLS;
+/** Entries per indexer page when reading a lock's history. */
+const HISTORY_PAGE = 128;
+/** The most inputs a creating transaction may have before its inputs are looked up (each is an RPC call). */
+const MAX_PAYMENT_INPUTS = 32;
+/** The charger's cells read when picking one to pay a charge's fee: any of them will do. */
+const FEE_CELL_SCAN = 4 * MAX_SUBSCRIPTION_CELLS;
+const tooManyTransactions = (cap) => new SessionPolicyError(`over ${cap} recent transactions under this subscription's lock: refused rather than read in part; ` +
+    "they leave the window a period after they committed, or the subscriber can cancel", "too-many-cells");
+const tooManyCells = (cap) => new SessionPolicyError(`over ${cap} cells or recent transactions under this subscription's lock: refused rather than read in part; ` +
+    "the subscriber can clear the planted cells (clearPlantedCells), or cancel", "too-many-cells");
+/** The token units in token cells (cells typed with `token`, with at least 16 data bytes). */
+function tokensIn(cells, token) {
+    return cells.reduce((s, c) => (c.type?.eq(token) && ccc.bytesFrom(c.data).length >= 16 ? s + tokenAmount(c.data) : s), 0n);
+}
+/**
+ * Whether transaction `txHash` (which spent a cell under a subscription's lock)
+ * is a charge: one of its inputs is under the charger's lock. Only the charger
+ * (session mode) and the subscriber (owner mode) can spend those cells. When it
+ * cannot be told (the transaction or an input not found, too many inputs), it
+ * counts as a charge: that can only delay the next charge, never allow a second
+ * one in a period. The last input is looked at first: a charge puts the
+ * charger's cell there.
+ */
+async function isCharge(client, txHash, chargerLockHash) {
+    const fetched = await client.getTransactionNoCache(txHash);
+    const inputs = fetched?.transaction.inputs ?? [];
+    if (!inputs.length || inputs.length > MAX_PAYMENT_INPUTS)
+        return { charge: true, fetched };
+    const byCharger = (c) => !c || c.cellOutput.lock.hash() === chargerLockHash;
+    const last = await client.getCell(inputs[inputs.length - 1].previousOutput);
+    if (byCharger(last))
+        return { charge: true, fetched };
+    const rest = await Promise.all(inputs.slice(0, -1).map((i) => client.getCell(i.previousOutput)));
+    return { charge: rest.some(byCharger), fetched, inputs: [...rest, last] };
+}
+/**
+ * The memo `clearPlantedCells` puts in the witness (`input_type`) of the
+ * subscriber's own input, under the subscriber's signature: a status tells its
+ * cleanup from a cancel by it, so a cleanup does not end a paid period (review
+ * W6 L2). Only the subscriber can sign it; a subscriber who marks a cancel
+ * with it keeps access only through a period already paid for.
+ */
+export const CLEAR_PLANTED_MEMO = ccc.hashCkb(ccc.bytesFrom("ckb-session-kit clear-planted", "utf8"));
+/** Whether a subscriber's spend `fetched` (with its `inputs`) is marked as a `clearPlantedCells` cleanup. */
+function isCleanup(fetched, inputs, subscriberLockHash) {
+    const tx = fetched?.transaction;
+    if (!tx || !inputs)
+        return false;
+    return inputs.some((c, i) => {
+        if (c?.cellOutput.lock.hash() !== subscriberLockHash)
+            return false;
+        try {
+            return tx.getWitnessArgsAt(i)?.inputType === CLEAR_PLANTED_MEMO;
+        }
+        catch {
+            return false; // not a WitnessArgs
+        }
+    });
+}
+/**
+ * The newest charge (a spend of a cell under `lock` by the charger), with its
+ * age in blocks, looking back under `window` blocks (undefined if none), from
+ * the indexer's history of the lock: a charge that took the whole balance leaves
+ * no change cell to tell it by (30 Oct). `ownerAfter`: the subscriber spent
+ * cells under the lock after it, other than in a cleanup marked with
+ * `CLEAR_PLANTED_MEMO` (a cancel, or any other owner-mode spend).
+ * Transactions that only created cells under the lock (anyone can) are skipped
+ * without being fetched, and counted under their own, larger budget
+ * (`MAX_CREATED_HISTORY`); only spends count toward `MAX_HISTORY`, and an
+ * entry older than the window is never counted (review W6 M2). Past either
+ * budget it refuses: stopping short could miss the last charge. A subscriber's
+ * spend does not date the last charge: a cleanup must not delay the next one
+ * (mentor review, 2 Nov).
+ */
+async function lastCharge(client, lock, sub, tip, window) {
+    let spends = 0;
+    let created = 0;
+    let ownerAfter = false;
+    for await (const t of client.findTransactionsByLock(lock, null, true, "desc", HISTORY_PAGE)) {
+        const born = ccc.numFrom(t.blockNumber);
+        const age = tip > born ? tip - born : 0n; // the indexer may be a block past the tip read
+        if (age >= window)
+            break;
+        // Stopping short could miss the last charge and let a second one into the period: refuse instead.
+        if (!t.cells.some((c) => c.isInput)) {
+            if (++created > MAX_CREATED_HISTORY)
+                throw tooManyTransactions(MAX_CREATED_HISTORY);
+            continue;
+        }
+        if (++spends > MAX_HISTORY)
+            throw tooManyTransactions(MAX_HISTORY);
+        const { charge, fetched, inputs } = await isCharge(client, t.txHash, sub.chargerLockHash);
+        if (charge)
+            return { charge: { txHash: t.txHash, age, fetched }, ownerAfter };
+        if (!isCleanup(fetched, inputs, sub.subscriberLockHash))
+            ownerAfter = true;
+    }
+    return { ownerAfter };
+}
+/** Whether `p` spends a cell under `lockHash`: who took part in the transaction. */
+const spends = (p, lockHash) => p.inputs.some((c) => c?.cellOutput.lock.hash() === lockHash);
+const NO_TOKEN_TARGET = "payTo has no cell of this token to top up: create one (any amount, even 0) first";
+/**
+ * The subscriber opens a subscription, in one transaction and one signature: the
+ * first period's price goes to `payTo` at once (a new cell cannot be charged for a
+ * whole period, so otherwise the first period would be free; review H1), and one
+ * cell holding `budget` shannons goes under the session lock. No key cell: the
+ * creator already owns cells under its charger key. `budget` of the cell's own
+ * size (153 CKB) plus n prices pays n more periods; what is left comes back on
+ * cancel. With a price of 153 CKB or more, the last 153 can be charged too.
+ *
+ * `account` (the subscriber's id at the creator) is committed in the witness of
+ * the subscriber's own input, which the subscriber's signature covers; the
+ * creator checks it with `verifySubscription`, so nobody else can present this
+ * subscription as theirs (review H3).
+ *
+ * `payTo` should be an anyone-can-pay address with a live cell, so a charge of
+ * any size tops it up; otherwise each charge creates a new cell and the price must
+ * be at least that cell's size (61 CKB for a plain address). Keep a plain cell in
+ * the wallet: cancelling needs one to prove ownership.
+ *
+ * With `token`, the subscription is paid in that plain xUDT and `price` is in
+ * token units: the cell holds `token.amount` units plus its own size in CKB
+ * (282 CKB; `budget` may add more, which stays until cancel), and the first price
+ * tops up `payTo`'s cell of the token. `payTo` must then be anyone-can-pay and
+ * already hold a cell of the token: no CKB may leave a token subscription, so a
+ * charge cannot pay for a new token cell.
+ */
+export async function openSubscription(subscriber, deployment, opts) {
+    const client = subscriber.client;
+    const token = opts.token && ccc.Script.from(opts.token.type);
+    if (token && opts.token) {
+        await assertPlainXudt(token, client);
+        if (opts.token.amount < 0n)
+            throw new SessionBalanceError("token amount must not be negative");
+    }
+    else if (opts.budget === undefined) {
+        throw new SessionBalanceError("budget is required: the shannons the subscription cell holds");
+    }
+    const subscriberLock = (await subscriber.getRecommendedAddressObj()).script;
+    await assertSigningLock(subscriberLock, client, opts);
+    const [chargerLock, payToLock] = await Promise.all([opts.charger, opts.payTo].map(async (a) => (await ccc.Address.fromString(a, client)).script));
+    // A charger lock that signs nothing would let anyone trigger charges (review M2). Its own
+    // opt-in: opting in for the subscriber's wallet does not waive review of the creator's lock (review W6 I1).
+    await checkSigningLock(chargerLock, client, !!opts.allowUnreviewedChargerLock, {
+        whose: "the charger's lock",
+        can: "charge a subscription",
+        optIn: "allowUnreviewedChargerLock",
+    });
+    const sub = {
+        subscriberLockHash: subscriberLock.hash(),
+        chargerLockHash: chargerLock.hash(),
+        payToLockHash: payToLock.hash(),
+        price: opts.price,
+        periodBlocks: opts.periodBlocks,
+        ...(token && { token: { type: { codeHash: token.codeHash, hashType: token.hashType, args: token.args } } }),
+    };
+    assertTerms(sub);
+    const acp = await isAnyoneCanPay(payToLock, client);
+    const newCell = ccc.CellOutput.from({ lock: payToLock }, "0x").capacity;
+    if (token && !acp) {
+        throw new SessionPolicyError("a token subscription pays into payTo's anyone-can-pay cell of the token: no CKB may leave it to make a new one");
+    }
+    if (!token && opts.price < newCell && !acp) {
+        throw new SessionPolicyError(`each charge creates a cell for payTo, which needs ${ccc.fixedPointToString(newCell)} CKB: ` +
+            "raise the price or use an anyone-can-pay address");
+    }
+    // Not a legacy lock (the 8 Oct code lacks errors 16-18, review M5), and its code
+    // is live on this network (audit round 2, 31 Oct).
+    await assertCurrentDeployment(client, deployment);
+    const lock = subscriptionLock(deployment, sub);
+    // Two live cells under the same lock are one group with two rate-limited cells:
+    // two charges per period (review M1).
+    if ((await subscriptionCells(client, lock, token)).length) {
+        throw new SessionPolicyError("a subscription with exactly these terms is already open: cancel it first");
+    }
+    const tx = ccc.Transaction.from({
+        outputs: [{ lock, capacity: opts.budget ?? 0n, ...(token && { type: token }) }],
+        outputsData: [token && opts.token ? tokenData(opts.token.amount) : "0x"],
+    });
+    // CCC raises an output to its occupied capacity; a budget below that is a mistake.
+    if (opts.budget !== undefined && tx.outputs[0].capacity !== opts.budget) {
+        throw new SessionBalanceError(`budget must be at least ${ccc.fixedPointToString(tx.outputs[0].capacity)} CKB`);
+    }
+    // The first period, paid now.
+    if (token) {
+        if (!(await addTopUp(tx, client, payToLock, { token, units: opts.price })))
+            throw new SessionBalanceError(NO_TOKEN_TARGET, "no-payout-cell");
+        await tx.completeInputsByUdt(subscriber, token);
+        const extra = (await tx.getInputsUdtBalance(client, token)) - tx.getOutputsUdtBalance(token);
+        if (extra > 0n)
+            tx.addOutput({ lock: subscriberLock, type: token }, tokenData(extra));
+    }
+    else {
+        // A random cell, so openings at once rarely compete for one (review, 28 Oct).
+        if (!acp || !(await addTopUp(tx, client, payToLock, { ckb: opts.price }))) {
+            tx.addOutput({ lock: payToLock, capacity: opts.price });
+            if (tx.outputs[1].capacity !== opts.price) {
+                throw new SessionBalanceError(`payTo has no cell to top up, and a new one needs ${ccc.fixedPointToString(newCell)} CKB`, "no-payout-cell");
+            }
+        }
+    }
+    await tx.completeInputsByCapacity(subscriber);
+    if (opts.account !== undefined) {
+        let mine = -1;
+        for (let i = 0; i < tx.inputs.length && mine < 0; i++) {
+            await tx.inputs[i].completeExtraInfos(client);
+            if (tx.inputs[i].cellOutput?.lock.eq(subscriberLock))
+                mine = i;
+        }
+        if (mine < 0)
+            throw new SessionBalanceError("no input of the subscriber to carry the account memo");
+        tx.setWitnessArgsAt(mine, { inputType: subscriptionMemo(opts.account) });
+    }
+    await tx.completeFeeBy(subscriber);
+    let funded = sub;
+    const txHash = await signAndSend(subscriber, tx, async (hash) => {
+        funded = { ...sub, openTx: hash };
+        await opts.beforeSend?.(funded);
+    });
+    return { txHash, subscription: funded };
+}
+/**
+ * The live cells of a subscription, their balance (shannons) and token balance
+ * (units; 0 without a token), and how many blocks until one can be charged: once
+ * a cell is a period old and the last charge (the newest transaction that spent
+ * a cell under the lock) is too. Throws a `SessionPolicyError` ("too-many-cells")
+ * with over `MAX_SUBSCRIPTION_CELLS` cells under the lock.
+ */
+export async function findSubscriptionCells(client, deployment, sub) {
+    const { lock, cells, balance, tokenBalance, nextChargeIn } = await subscriptionState(client, deployment, sub);
+    return { lock, cells, balance, tokenBalance, nextChargeIn };
+}
+/**
+ * `findSubscriptionCells`, plus what it looked up on the way: the tip, and each
+ * cell's creating transaction and age (undefined while not committed), so a
+ * charge or a status fetches each of them once (review, 28 Oct).
+ */
+async function subscriptionState(client, deployment, sub) {
+    const lock = subscriptionLock(deployment, sub);
+    const token = tokenOf(sub);
+    const cells = await subscriptionCells(client, lock, token, MAX_SUBSCRIPTION_CELLS);
+    const balance = cells.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    const tokenBalance = token ? tokensIn(cells.map((c) => ({ type: c.cellOutput.type, data: c.outputData })), token) : 0n;
+    // Cells made by one transaction share one lookup.
+    const byHash = new Map();
+    const creating = (h) => {
+        if (!byHash.has(h))
+            byHash.set(h, client.getTransactionNoCache(h)); // the node's answer, not the cache's
+        return byHash.get(h);
+    };
+    const [tip, created] = await Promise.all([client.getTip(), Promise.all(cells.map((c) => creating(c.outPoint.txHash)))]);
+    const ages = created.map((res) => {
+        const born = res?.blockNumber;
+        return born === undefined || born === null ? undefined : tip - ccc.numFrom(born);
+    });
+    let nextChargeIn;
+    for (const age of ages) {
+        if (age === undefined)
+            continue; // not committed yet
+        const wait = age >= sub.periodBlocks ? 0n : sub.periodBlocks - age;
+        if (nextChargeIn === undefined || wait < nextChargeIn)
+            nextChargeIn = wait;
+    }
+    // The rate limit is per cell, so a cell older than the last charge (a top-up)
+    // could pay a second price in the same period: wait out the newest charge as
+    // well (review, 28 Oct). It is read from the lock's history, not from its change
+    // cell, which a charge of the whole balance does not leave (30 Oct). Only the
+    // charger's spends count: the subscriber's own (clearing planted cells) leave
+    // the subscription's cells as they were (mentor review, 2 Nov), and a cancel
+    // takes every cell, so whatever comes after it is younger than it anyway.
+    // One block more than a period: a status counts the period's last block as paid.
+    const { charge: spent, ownerAfter } = await lastCharge(client, lock, sub, tip, sub.periodBlocks + 1n);
+    if (nextChargeIn !== undefined && spent && sub.periodBlocks - spent.age > nextChargeIn)
+        nextChargeIn = sub.periodBlocks - spent.age;
+    return { lock, cells, balance, tokenBalance, nextChargeIn, tip, created, ages, spent, ownerAfter };
+}
+/**
+ * The creator's charger key takes one price from the subscription and pays it to
+ * `payTo` (topping up its anyone-can-pay cell with `topUp`). The fee comes from
+ * one of the charger's own plain cells, which goes back to it smaller. Throws a
+ * `SessionBalanceError` while no cell is a full period old or the last charge is
+ * under one, or once what is left cannot cover a price and still leave a cell behind.
+ *
+ * In a token subscription the price is in token units and always tops up
+ * `payTo`'s cell of the token (`topUp` is implied). The change keeps every
+ * shannon that came in (no CKB may leave) and the tokens less one price, in
+ * exactly 16 data bytes.
+ *
+ * With `topUp` (or a token), `payTo`'s cell is a confirmed one that no
+ * transaction in the node's pool spends, where the node can tell
+ * (`pickPayoutCell`). A charge the node rejects for a spent or unknown input is
+ * built again after clearing the client's cache, with another payout cell,
+ * after a short wait: up to `retry.attempts` in all (default 3), waiting
+ * `retry.delayMs` (default 1000) doubling each time (`rebuildOnDeadInputs`).
+ * `beforeSend` runs again with each new hash. A send whose outcome is unknown
+ * is never retried.
+ */
+export async function chargeSubscription(charger, deployment, sub, opts) {
+    // Built on a cell another instance or payer spent since: rebuilt from live cells (audit, 31 Oct; review, 2 Nov).
+    return rebuildOnDeadInputs(charger.client, (avoid) => chargeOnce(charger, deployment, sub, opts, avoid), opts.retry);
+}
+async function chargeOnce(charger, deployment, sub, opts, avoid) {
+    const client = charger.client;
+    assertTerms(sub);
+    const token = tokenOf(sub);
+    const chargerLock = (await charger.getRecommendedAddressObj()).script;
+    if (chargerLock.hash() !== sub.chargerLockHash)
+        throw new SessionPolicyError("this signer is not the subscription's charger");
+    const { script: payToLock } = await ccc.Address.fromString(opts.payTo, client);
+    if (payToLock.hash() !== sub.payToLockHash)
+        throw new SessionPolicyError("payTo is not the subscription's payout address");
+    const state = await subscriptionState(client, deployment, sub);
+    if (!state.cells.length)
+        throw new SessionBalanceError("no subscription cell: cancelled, or not committed yet");
+    if (state.nextChargeIn !== 0n) {
+        throw new SessionBalanceError(state.nextChargeIn === undefined
+            ? "the subscription's cell is not committed yet"
+            : `not a full period yet: next charge in ${state.nextChargeIn} blocks`);
+    }
+    const tx = ccc.Transaction.from({ cellDeps: [sessionLockCellDep(deployment)] });
+    if (token) {
+        if (!(await isAnyoneCanPay(payToLock, client)))
+            throw new SessionPolicyError("a token subscription needs an anyone-can-pay payTo", "payto-not-anyone-can-pay");
+        if (!(await addTopUp(tx, client, payToLock, { token, units: sub.price }, avoid)))
+            throw new SessionBalanceError(NO_TOKEN_TARGET, "no-payout-cell");
+    }
+    else if (opts.topUp) {
+        if (!(await isAnyoneCanPay(payToLock, client)))
+            throw new SessionPolicyError("topUp needs an anyone-can-pay payTo", "payto-not-anyone-can-pay");
+        if (!(await addTopUp(tx, client, payToLock, { ckb: sub.price }, avoid))) {
+            throw new SessionBalanceError("payTo has no anyone-can-pay cell to top up", "no-payout-cell");
+        }
+    }
+    else {
+        tx.addOutput({ lock: payToLock, capacity: sub.price });
+        if (tx.outputs[0].capacity !== sub.price) {
+            throw new SessionBalanceError(`a charge to a new cell must be at least ${ccc.fixedPointToString(tx.outputs[0].capacity)} CKB`);
+        }
+    }
+    // Every mature cell, merged into one change: the rate limit is per cell, so
+    // leaving one out would let it pay another price in the same period (code review, 26 Oct).
+    const taken = state.cells.filter((_, i) => (state.ages[i] ?? -1n) >= sub.periodBlocks);
+    const ckbIn = taken.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    const since = relativeBlocksSince(sub.periodBlocks);
+    tx.inputs.unshift(...taken.map((c) => ccc.CellInput.from({ previousOutput: c.outPoint, since })));
+    if (token) {
+        const tokenIn = tokensIn(taken.map((c) => ({ type: c.cellOutput.type, data: c.outputData })), token);
+        if (tokenIn < sub.price) {
+            throw new SessionBalanceError(`the subscription holds ${tokenIn} token units: not enough for a price of ${sub.price}`);
+        }
+        // All the CKB back (max_per_tx is 0), the tokens less one price, in exactly 16 bytes.
+        tx.addOutput({ lock: state.lock, type: token, capacity: ckbIn }, tokenData(tokenIn - sub.price));
+    }
+    else {
+        const change = ckbIn - sub.price;
+        const cellSize = ccc.CellOutput.from({ lock: state.lock }, "0x").capacity;
+        if (change < 0n || (change > 0n && change < cellSize)) {
+            throw new SessionBalanceError(`the subscription holds ${ccc.fixedPointToString(ckbIn)} CKB: not enough for a price of ` +
+                `${ccc.fixedPointToString(sub.price)} CKB and a ${ccc.fixedPointToString(cellSize)} CKB cell left behind`);
+        }
+        if (change > 0n)
+            tx.addOutput({ lock: state.lock, capacity: change });
+    }
+    // The charger's own cell authorises the charge and pays the fee; it comes back last, smaller.
+    // A random one, so charges of many subscriptions at once rarely collide (review, 28 Oct).
+    const floor = keyCellFloor(chargerLock);
+    const keyCell = randomPick(await feeCells(client, chargerLock, floor));
+    if (!keyCell)
+        throw new SessionBalanceError(`the charger needs a plain cell of at least ${ccc.fixedPointToString(floor + FEE_CELL_MARGIN)} CKB for fees`, "no-fee-cell");
+    tx.inputs.push(ccc.CellInput.from({ previousOutput: keyCell.outPoint }));
+    tx.addOutput({ lock: chargerLock, capacity: 0n });
+    await completeFeeOrNoFeeCell(tx, charger, `the charger's cell cannot cover the fee; send it a plain cell above ${ccc.fixedPointToString(floor + FEE_CELL_MARGIN)} CKB`);
+    return signAndSend(charger, tx, opts.beforeSend);
+}
+/**
+ * What a charger's fee cell holds above the cell it comes back as, at least: far
+ * more than a charge's fee (about 0.00001 CKB at the minimum fee rate). A cell
+ * just above the floor would pass the filter and then fail inside CCC (round-2
+ * fuzz, 31 Oct).
+ */
+const FEE_CELL_MARGIN = 1000000n; // 0.01 CKB
+/**
+ * Plain cells of the charger of at least `floor` plus `FEE_CELL_MARGIN`: at most `MAX_SUBSCRIPTION_CELLS` of
+ * them, from the first `FEE_CELL_SCAN` cells under its lock. Any one of them pays
+ * a fee, so there is no need to read every cell someone may have sent to the
+ * charger's address (security audit, 30 Oct).
+ */
+async function feeCells(client, lock, floor) {
+    const cells = [];
+    let seen = 0;
+    for await (const cell of client.findCellsByLock(lock, null, true)) {
+        if (++seen > FEE_CELL_SCAN || cells.length >= MAX_SUBSCRIPTION_CELLS)
+            break;
+        if (!cell.cellOutput.type && cell.outputData === "0x" && cell.cellOutput.capacity >= floor + FEE_CELL_MARGIN)
+            cells.push(cell);
+    }
+    // The change of this client's last charge, spent since by another instance, must not pay this one's fee.
+    return withoutDeadCached(client, lock, cells);
+}
+/**
+ * The subscriber takes everything left back, in owner mode: no creator involved
+ * and no wait. `nothingFound` means no cell is left (already cancelled, or run dry).
+ * In a token subscription the tokens come back as one token cell (`refundedTokens`).
+ * Subscriptions are also found and swept by `recoverSessions`, since their args
+ * begin with the subscriber's lock hash like any session's.
+ */
+export async function cancelSubscription(subscriber, deployment, sub) {
+    const lock = (await subscriber.getRecommendedAddressObj()).script;
+    if (lock.hash() !== sub.subscriberLockHash)
+        throw new SessionPolicyError("this signer is not the subscriber");
+    // Every cell, without MAX_SUBSCRIPTION_CELLS: cancelling is how a subscriber
+    // clears cells planted under its lock, and the reads are its own.
+    const subLock = subscriptionLock(deployment, sub);
+    const token = tokenOf(sub);
+    const cells = await subscriptionCells(subscriber.client, subLock, token);
+    const balance = cells.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    const tokenBalance = token ? tokensIn(cells.map((c) => ({ type: c.cellOutput.type, data: c.outputData })), token) : 0n;
+    // A charger may leave a token subscription's last change untyped; its CKB is the subscriber's too (review, 27 Oct).
+    const untyped = token ? await subscriptionCells(subscriber.client, subLock) : [];
+    // Look-alikes of the token planted under the lock go back with the rest (review W6 M1).
+    const lookalikes = token ? (await lookalikeCells(subscriber.client, subLock, token)).cells : [];
+    const all = [...cells, ...untyped, ...lookalikes];
+    if (!all.length)
+        return { refunded: 0n, nothingFound: true };
+    const txHash = await ownerSweep(subscriber, deployment, all);
+    const refunded = all.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    return {
+        txHash,
+        refunded: token ? refunded : balance,
+        ...(token && { refundedTokens: tokenBalance }),
+    };
+}
+/** The most cells under a subscription's lock that one `clearPlantedCells` reads. */
+const CLEAR_SCAN = 4 * MAX_SUBSCRIPTION_CELLS;
+/**
+ * The most planted cells one `clearPlantedCells` transaction sweeps: with the
+ * subscriber's own input (and room for one more for the fee) it stays within
+ * `MAX_PAYMENT_INPUTS`, so a status can read it and never takes it for a
+ * charge, which would delay the next one (review W6 L3).
+ */
+const CLEAR_BATCH = MAX_PAYMENT_INPUTS - 2;
+/**
+ * The subscriber clears cells a third party created under the subscription's
+ * lock, without cancelling (mentor review, 2 Nov). Anyone can create cells under
+ * any lock; past `MAX_SUBSCRIPTION_CELLS` of the subscription's kind, a status or
+ * a charge is refused ("too-many-cells").
+ *
+ * A cell is the subscription's own when its creating transaction is the
+ * opening (`sub.openTx`), or had an input under the subscriber's or the
+ * charger's lock: an opening, a charge, a top-up by the subscriber. Nobody else
+ * can sign for those. Every other cell of the subscription's kind is planted:
+ * one owner-mode transaction (one signature) sweeps them to the subscriber,
+ * who keeps their CKB and tokens. The subscription's own cells are not touched,
+ * so their age and the payments that made them still count: access and the
+ * charge schedule go on as before.
+ *
+ * In a token subscription, look-alikes of the token (cells typed with the
+ * token's code and longer args that start with the token's, which xUDT accepts
+ * and anyone can create with 0 units) are planted too, and swept the same way
+ * when an owner sweep can spend them (plain xUDT, no flags; review W6 M1).
+ *
+ * Bounded: one call keeps at most `4 * MAX_SUBSCRIPTION_CELLS` cells of the
+ * kind, reads at most twice as many listed cells for each of the two scans,
+ * and looks each creating transaction up once. `more` says cells were left
+ * unread: call again once this sweep commits. Refused when none of the cells read is the
+ * subscription's own: cancel instead. `nothingFound` when nothing is planted.
+ */
+export async function clearPlantedCells(subscriber, deployment, sub) {
+    const client = subscriber.client;
+    const lock = (await subscriber.getRecommendedAddressObj()).script;
+    if (lock.hash() !== sub.subscriberLockHash)
+        throw new SessionPolicyError("this signer is not the subscriber");
+    const subLock = subscriptionLock(deployment, sub);
+    const token = tokenOf(sub);
+    // At most CLEAR_SCAN cells of the kind, from at most twice as many listed (review W6 M1).
+    let cells = [];
+    let more = false;
+    let read = 0;
+    for await (const cell of client.findCells({ script: subLock, scriptType: "lock", scriptSearchMode: "exact", filter: kindFilter(token), withData: true })) {
+        if (cells.length >= CLEAR_SCAN || ++read > 2 * CLEAR_SCAN) {
+            more = true;
+            break;
+        }
+        if (ofKind(cell, token))
+            cells.push(cell);
+    }
+    cells = await withoutDeadCached(client, subLock, cells);
+    if (token)
+        cells = await withinU128(client, cells);
+    // Look-alikes of the token are always planted; the scan reads past the token's own cells too.
+    const lookalikes = token ? await lookalikeCells(client, subLock, token, 2 * CLEAR_SCAN) : { cells: [], more: false };
+    if (lookalikes.more)
+        more = true;
+    // One look-up per creating transaction, however many cells it made.
+    const origin = new Map();
+    const own = (c) => {
+        const h = c.outPoint.txHash;
+        if (sub.openTx && h === ccc.hexFrom(sub.openTx))
+            return Promise.resolve(true);
+        if (!origin.has(h))
+            origin.set(h, ownOrigin(client, c));
+        return origin.get(h);
+    };
+    const mine = await Promise.all(cells.map(own));
+    const plantedOfKind = cells.filter((_, i) => !mine[i]);
+    const found = [...plantedOfKind, ...lookalikes.cells];
+    if (!found.length)
+        return { swept: 0, refunded: 0n, more, ...(!more && { nothingFound: true }) };
+    // Every cell read and none the subscription's own: it is gone (cancel instead). With
+    // cells left unread, its own may lie past them (review W6 L1), and sweeping planted ones is harmless.
+    if (!more && !mine.some(Boolean) && plantedOfKind.length) {
+        throw new SessionPolicyError("none of these cells is the subscription's own: cancel it instead (cancelSubscription)");
+    }
+    const planted = found.slice(0, CLEAR_BATCH);
+    if (found.length > planted.length)
+        more = true;
+    const txHash = await ownerSweep(subscriber, deployment, planted, { memo: CLEAR_PLANTED_MEMO });
+    return {
+        txHash,
+        swept: planted.length,
+        refunded: planted.reduce((s, c) => s + c.cellOutput.capacity, 0n),
+        ...(token && { refundedTokens: tokensIn(planted.map((c) => ({ type: c.cellOutput.type, data: c.outputData })), token) }),
+        more,
+    };
+}
+/** How many more prices a subscription's cells can pay. */
+function chargesLeftOf(sub, lock, balance, tokenBalance) {
+    if (sub.token)
+        return tokenBalance / sub.price;
+    const cellSize = ccc.CellOutput.from({ lock }, "0x").capacity;
+    return balance >= cellSize + sub.price ? (balance - cellSize) / sub.price : 0n;
+}
+/**
+ * The creator checks a subscription from the chain alone. Nothing in the request
+ * is trusted but the out point. The cell at `outPoint` must be live, under this
+ * deployment of the session lock (never an older one), untyped and without data,
+ * with 112-byte args holding exactly these terms, and at least `minBalance`.
+ *
+ * And the transaction that created the cell must have paid `payTo` at least one
+ * price: the opening pays the first period, every charge pays one. A cell the
+ * subscriber re-created in owner mode to reset its age paid nothing, and is
+ * refused (review H2). So access is granted up to `paidThroughBlock`; check the
+ * current cell again (`findSubscriptionCells`) once that block has passed.
+ *
+ * With `account`, the creating transaction must also carry `subscriptionMemo(account)`
+ * in the witness of an input under the subscriber's lock, which only the
+ * subscriber's signature covers: someone else's subscription cannot be claimed
+ * (review H3). The memo is in the opening only, so check `account` once, when a
+ * subscription is registered, then keep the subscription by its lock.
+ *
+ * With `token` (a token subscription), the cell must instead be typed with exactly
+ * that token and hold its amount, with 160-byte args (`max_per_tx` 0, the token's
+ * type hash, `price` in token units as `max_per_tx_token`); `minBalance` is in token
+ * units, and the payment counted is token units into `payTo`'s cells of the token.
+ * Without `token`, a 160-byte cell is refused, and the reverse.
+ */
+export async function verifySubscription(client, deployment, outPoint, expected) {
+    const cell = await client.getCellLive(outPoint, true, false);
+    if (!cell)
+        return { ok: false, reason: "no live cell at that out point" };
+    const lock = cell.cellOutput.lock;
+    if (lock.codeHash !== ccc.hexFrom(deployment.codeHash) || lock.hashType !== ccc.hashTypeFrom(deployment.hashType)) {
+        return { ok: false, reason: "not under this deployment of the session lock" };
+    }
+    const token = expected.token && ccc.Script.from(expected.token);
+    const args = ccc.bytesFrom(lock.args);
+    if (token) {
+        if (!cell.cellOutput.type?.eq(token) || ccc.bytesFrom(cell.outputData).length < 16) {
+            return { ok: false, reason: "a token subscription cell is typed with the token and holds its amount" };
+        }
+        if (args.length !== 160)
+            return { ok: false, reason: "not a token subscription: args must be 160 bytes (token, with a payout address)" };
+    }
+    else {
+        if (cell.cellOutput.type || cell.outputData !== "0x")
+            return { ok: false, reason: "a subscription cell carries no type and no data" };
+        if (args.length !== 112)
+            return { ok: false, reason: "not a subscription: args must be 112 bytes (CKB, with a payout address)" };
+    }
+    const [chargerLock, payToLock] = await Promise.all([expected.charger, expected.payTo].map(async (a) => (await ccc.Address.fromString(a, client)).script));
+    const sub = token
+        ? {
+            subscriberLockHash: ccc.hexFrom(args.slice(0, 32)),
+            chargerLockHash: ccc.hexFrom(args.slice(32, 64)),
+            price: ccc.numLeFromBytes(args.slice(112, 128)),
+            periodBlocks: ccc.numLeFromBytes(args.slice(72, 80)),
+            payToLockHash: ccc.hexFrom(args.slice(128, 160)),
+            token: { type: { codeHash: token.codeHash, hashType: token.hashType, args: token.args } },
+        }
+        : {
+            subscriberLockHash: ccc.hexFrom(args.slice(0, 32)),
+            chargerLockHash: ccc.hexFrom(args.slice(32, 64)),
+            price: ccc.numLeFromBytes(args.slice(64, 72)),
+            periodBlocks: ccc.numLeFromBytes(args.slice(72, 80)),
+            payToLockHash: ccc.hexFrom(args.slice(80, 112)),
+        };
+    if (token) {
+        if (ccc.hexFrom(args.slice(80, 112)) !== token.hash())
+            return { ok: false, reason: "a different token" };
+        if (ccc.numLeFromBytes(args.slice(64, 72)) !== 0n)
+            return { ok: false, reason: "a token subscription must let no CKB out (max_per_tx 0)" };
+    }
+    if (sub.chargerLockHash !== chargerLock.hash())
+        return { ok: false, reason: "a different charger" };
+    if (sub.payToLockHash !== payToLock.hash())
+        return { ok: false, reason: "a different payout address" };
+    if (sub.price !== expected.price)
+        return { ok: false, reason: "a different price" };
+    if (sub.periodBlocks !== expected.periodBlocks)
+        return { ok: false, reason: "a different period" };
+    try {
+        assertTerms(sub);
+        if (token)
+            await assertPlainXudt(token, client);
+    }
+    catch (e) {
+        return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+    }
+    const balance = cell.cellOutput.capacity;
+    const tokenBalance = token ? tokenAmount(cell.outputData) : 0n;
+    if (token) {
+        if (tokenBalance < (expected.minBalance ?? 0n))
+            return { ok: false, reason: `holds ${tokenBalance} token units, under the minimum` };
+    }
+    else if (balance < (expected.minBalance ?? ccc.CellOutput.from({ lock }, "0x").capacity)) {
+        return { ok: false, reason: `holds ${ccc.fixedPointToString(balance)} CKB, under the minimum` };
+    }
+    const created = await paymentOf(client, deployment, cell.outPoint.txHash, sub);
+    if (typeof created === "string")
+        return { ok: false, reason: created };
+    // An opening is signed by the subscriber, a charge by the charger. Any other
+    // payment to payTo (a paid read, say) must not count as a period too (review, 27 Oct).
+    if (!spends(created, sub.subscriberLockHash) && !spends(created, sub.chargerLockHash)) {
+        return { ok: false, reason: "the cell was created neither by the subscriber's opening nor by a charge" };
+    }
+    if (expected.account !== undefined && !commitsToAccount(created, sub, expected.account)) {
+        return { ok: false, reason: "the opening does not commit to this account" };
+    }
+    return {
+        ok: true,
+        subscription: sub,
+        balance,
+        ...(token && { tokenBalance }),
+        chargesLeft: chargesLeftOf(sub, lock, balance, tokenBalance),
+        paidThroughBlock: created.block + sub.periodBlocks,
+    };
+}
+/**
+ * The committed transaction `txHash`, if it paid `sub`'s payout address enough;
+ * otherwise why not. Enough is the sum of the prices of every subscription cell
+ * it creates for that payout address, not one price: otherwise one payment could
+ * open or renew many subscriptions at once (code review, 26 Oct). Only untyped
+ * cells count as paid, and an input that cannot be looked up fails the check.
+ *
+ * In a token subscription, the same in token units: the prices of every token
+ * subscription cell (160-byte args) for that payout address and token, against
+ * the units the payout address gained in cells typed with exactly that token
+ * and holding at least 16 data bytes. CKB and token payments never count for each other.
+ */
+async function paymentOf(client, deployment, txHash, sub, 
+/** `txHash`'s response, when already fetched. */
+fetched) {
+    // The node's answer, never CCC's cache: a cached "committed" outlives a reorg (audit, 31 Oct).
+    const created = fetched ?? (await client.getTransactionNoCache(txHash));
+    if (!created || created.status !== "committed" || created.blockNumber === undefined || created.blockNumber === null) {
+        return "the transaction that created the cell is not committed";
+    }
+    const tx = created.transaction;
+    if (tx.inputs.length > MAX_PAYMENT_INPUTS)
+        return `the transaction has over ${MAX_PAYMENT_INPUTS} inputs`;
+    const codeHash = ccc.hexFrom(deployment.codeHash);
+    const hashType = ccc.hashTypeFrom(deployment.hashType);
+    const token = tokenOf(sub);
+    const tokenHash = token?.hash();
+    let owed = 0n;
+    for (const o of tx.outputs) {
+        const args = ccc.bytesFrom(o.lock.args);
+        if (o.lock.codeHash !== codeHash || o.lock.hashType !== hashType)
+            continue;
+        if (!token && args.length === 112 && ccc.hexFrom(args.slice(80, 112)) === sub.payToLockHash) {
+            owed += ccc.numLeFromBytes(args.slice(64, 72));
+        }
+        if (token &&
+            args.length === 160 &&
+            ccc.hexFrom(args.slice(80, 112)) === tokenHash &&
+            ccc.hexFrom(args.slice(128, 160)) === sub.payToLockHash) {
+            owed += ccc.numLeFromBytes(args.slice(112, 128));
+        }
+    }
+    if (owed < sub.price)
+        owed = sub.price;
+    const toPayTo = (cells) => cells.filter((c) => c.cellOutput.lock.hash() === sub.payToLockHash);
+    const amount = (cells) => token
+        ? tokensIn(cells.map((c) => ({ type: c.cellOutput.type, data: c.data })), token)
+        : cells.reduce((s, c) => (!c.cellOutput.type ? s + c.cellOutput.capacity : s), 0n);
+    const out = amount(toPayTo(tx.outputs.map((cellOutput, i) => ({ cellOutput, data: tx.outputsData[i] ?? "0x" }))));
+    const notPaid = "the transaction that created the cell did not pay the price to payTo";
+    // What payTo gained is at most what its outputs hold: a transaction that falls
+    // short already is refused before its inputs are looked up (security audit, 30 Oct).
+    if (out < owed)
+        return notPaid;
+    const inputs = await Promise.all(tx.inputs.map((i) => client.getCell(i.previousOutput)));
+    if (inputs.some((c) => !c))
+        return "an input of the transaction could not be looked up";
+    const paid = out - amount(toPayTo(inputs.map((c) => ({ cellOutput: c.cellOutput, data: c.outputData }))));
+    if (paid < owed)
+        return notPaid;
+    return { tx, block: ccc.numFrom(created.blockNumber), inputs };
+}
+/** Whether `p` carries `subscriptionMemo(account)` in the witness of an input under the subscriber's lock. */
+function commitsToAccount(p, sub, account) {
+    const memo = subscriptionMemo(account);
+    return p.inputs.some((c, i) => c?.cellOutput.lock.hash() === sub.subscriberLockHash && p.tx.getWitnessArgsAt(i)?.inputType === memo);
+}
+/**
+ * Where a subscription stands, for a creator's server that keeps no database:
+ * the subscriber sends the terms' subscriber lock hash, the opening's hash and
+ * its account id on every request. The opening must have paid the first price
+ * into a cell under exactly this subscription's lock and committed to `account`
+ * under the subscriber's signature; then the live cells give the period paid for.
+ * Each must have been created by a payment, so a cell re-created by the
+ * subscriber to reset its age counts for nothing. Cancelling ends access at once.
+ * A token subscription (`sub.token`) counts payments in its token, as `verifySubscription` does.
+ *
+ * Throws a `SessionPolicyError` of reason "too-many-cells" when over
+ * `MAX_SUBSCRIPTION_CELLS` cells (or recent transactions) sit under the lock:
+ * not a verdict on the subscription, so not an `ok: false`. A server should
+ * answer it as a conflict the subscriber can clear by cancelling and opening again.
+ */
+export async function subscriptionStatus(client, deployment, sub, proof) {
+    try {
+        assertTerms(sub);
+        const token = tokenOf(sub);
+        if (token)
+            await assertPlainXudt(token, client);
+    }
+    catch (e) {
+        return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+    }
+    const lock = subscriptionLock(deployment, sub);
+    // One check per transaction, however many cells it made (security audit, 30 Oct).
+    const checked = new Map();
+    const payment = (txHash, fetched) => {
+        if (!checked.has(txHash))
+            checked.set(txHash, paymentOf(client, deployment, txHash, sub, fetched));
+        return checked.get(txHash);
+    };
+    const openHash = ccc.hexFrom(proof.openTx);
+    const opening = await payment(openHash);
+    if (typeof opening === "string")
+        return { ok: false, reason: `opening: ${opening}` };
+    if (!opening.tx.outputs.some((o) => o.lock.eq(lock)))
+        return { ok: false, reason: "the opening created no cell under this subscription's lock" };
+    if (!commitsToAccount(opening, sub, proof.account))
+        return { ok: false, reason: "the opening does not commit to this account" };
+    const { cells, balance, tokenBalance, nextChargeIn, tip, created, spent, ownerAfter } = await subscriptionState(client, deployment, sub);
+    let paidThroughBlock;
+    const renews = (p, txHash) => 
+    // Only the proven opening or a charge renews; another payment to payTo that
+    // also creates a cell here (a paid read, say) is not a period (review, 27 Oct).
+    typeof p !== "string" && (txHash === openHash || spends(p, sub.chargerLockHash));
+    const paying = cells.map((c, i) => ({ txHash: c.outPoint.txHash, fetched: created[i] }));
+    // A charge of the whole balance leaves no cell, but still paid for its period
+    // (30 Oct), unless the subscriber spent cells after it: a cancel ends access at once.
+    if (spent && !ownerAfter && !paying.some((c) => c.txHash === spent.txHash))
+        paying.push({ txHash: spent.txHash, fetched: spent.fetched });
+    const payments = await Promise.all(paying.map((c) => payment(c.txHash, c.fetched)));
+    for (const [i, { txHash }] of paying.entries()) {
+        const p = payments[i];
+        if (!renews(p, txHash))
+            continue;
+        const through = p.block + sub.periodBlocks;
+        if (paidThroughBlock === undefined || through > paidThroughBlock)
+            paidThroughBlock = through;
+    }
+    return {
+        ok: true,
+        status: {
+            paidThroughBlock,
+            tip,
+            active: paidThroughBlock !== undefined && tip <= paidThroughBlock,
+            balance,
+            ...(sub.token && { tokenBalance }),
+            chargesLeft: chargesLeftOf(sub, lock, balance, tokenBalance),
+            nextChargeIn,
+        },
+    };
+}
+/**
+ * About how many blocks `seconds` is, from the average block time over the last
+ * `sample` blocks. Block time varies; round up when a period means "no more often than".
+ */
+export async function blocksForSeconds(client, seconds, sample = 1000n) {
+    const tip = await client.getTipHeader();
+    const old = await client.getHeaderByNumber(tip.number > sample ? tip.number - sample : 0n);
+    if (!old || tip.number === old.number)
+        throw new Error("not enough blocks to estimate block time");
+    const msPerBlock = Number(tip.timestamp - old.timestamp) / Number(tip.number - old.number);
+    return BigInt(Math.ceil((seconds * 1000) / msPerBlock));
+}