ckb-session-kit 1.0.0 → 2.1.0

package/dist/subscription.js

@@ -1,6 +1,7 @@
 import { ccc } from "@ckb-ccc/core";
-import { relativeBlocksSince, TESTNET_LEGACY_DEPLOYMENTS, sessionLockCellDep, sessionLockScript, } from "./lock.js";
-import { assertPlainXudt, assertSigningLock, collect, keyCellFloor, matureCells, ownerSweep, SessionBalanceError, signAndSend, tokenAmount, tokenData, } from "./onchain.js";
+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) {
@@ -32,10 +33,6 @@ function assertTerms(sub) {
     if (sub.payToLockHash === sub.subscriberLockHash)
         throw new SessionPolicyError("payTo must not be the subscriber");
 }
-async function isAnyoneCanPay(lock, client) {
-    const acp = await client.getKnownScript(ccc.KnownScript.AnyoneCanPay);
-    return lock.codeHash === acp.codeHash && lock.hashType === acp.hashType;
-}
 /**
  * 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
@@ -52,54 +49,215 @@ export function subscriptionMemo(account) {
  * 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`.
+ * 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) {
+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 = [];
-    for await (const cell of client.findCellsByLock(lock, null, true)) {
+    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 (token ? type?.eq(token) && ccc.bytesFrom(cell.outputData).length >= 16 : !type)
-            cells.push(cell);
+        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;
+    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);
 }
-const U128_MAX = (1n << 128n) - 1n;
 /**
- * Cells whose token amounts add up without overflowing a u128, in order; the rest
- * are left out. Anyone can plant a cell holding 2^128-1 units of a free token
- * under a subscription's lock, and xUDT refuses a transaction whose inputs
- * overflow, so taking every cell at once would block charges and the cancel
- * (review, 27 Oct). Only the planter's own tokens are left behind.
+ * 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.
  */
-function fitting(cells, token) {
-    if (!token)
-        return cells;
-    const kept = [];
-    let sum = 0n;
-    for (const c of cells) {
-        const units = c.cellOutput.type?.eq(token) && ccc.bytesFrom(c.outputData).length >= 16 ? tokenAmount(c.outputData) : 0n;
-        if (sum + units > U128_MAX)
+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;
-        sum += units;
-        kept.push(c);
-    }
-    return kept;
+        }
+        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);
-/** A cell of `token` under `payTo`'s anyone-can-pay lock to top up; random, so payers at once rarely collide. */
-async function tokenTarget(client, payToLock, token) {
-    const targets = (await collect(client, payToLock, token)).filter((c) => !!c.cellOutput.type);
-    const target = targets[Math.floor(Math.random() * targets.length)];
-    if (!target) {
-        throw new SessionBalanceError("payTo has no cell of this token to top up: create one (any amount, even 0) first");
-    }
-    return target;
-}
+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
@@ -128,10 +286,6 @@ async function tokenTarget(client, payToLock, token) {
  */
 export async function openSubscription(subscriber, deployment, opts) {
     const client = subscriber.client;
-    if (TESTNET_LEGACY_DEPLOYMENTS.some((d) => ccc.hexFrom(d.codeHash) === ccc.hexFrom(deployment.codeHash))) {
-        // The 8 Oct code lacks errors 16-18 (review M5); no new subscription goes under an old lock.
-        throw new SessionPolicyError("this is an old deployment of the session lock: open subscriptions under the current one");
-    }
     const token = opts.token && ccc.Script.from(opts.token.type);
     if (token && opts.token) {
         await assertPlainXudt(token, client);
@@ -142,10 +296,15 @@ export async function openSubscription(subscriber, deployment, opts) {
         throw new SessionBalanceError("budget is required: the shannons the subscription cell holds");
     }
     const subscriberLock = (await subscriber.getRecommendedAddressObj()).script;
-    await assertSigningLock(subscriberLock, client);
+    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).
-    await assertSigningLock(chargerLock, client);
+    // 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(),
@@ -164,6 +323,9 @@ export async function openSubscription(subscriber, deployment, opts) {
         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).
@@ -180,26 +342,19 @@ export async function openSubscription(subscriber, deployment, opts) {
     }
     // The first period, paid now.
     if (token) {
-        const target = await tokenTarget(client, payToLock, token);
-        tx.inputs.push(ccc.CellInput.from({ previousOutput: target.outPoint }));
-        tx.addOutput({ lock: payToLock, type: token, capacity: target.cellOutput.capacity }, tokenData(tokenAmount(target.outputData) + opts.price));
-        await tx.addCellDepsOfKnownScripts(client, ccc.KnownScript.AnyoneCanPay, ccc.KnownScript.XUdt);
+        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 {
-        const target = acp ? (await collect(client, payToLock))[0] : undefined;
-        if (target) {
-            tx.inputs.push(ccc.CellInput.from({ previousOutput: target.outPoint }));
-            tx.addOutput({ lock: payToLock, capacity: target.cellOutput.capacity + opts.price });
-            await tx.addCellDepsOfKnownScripts(client, ccc.KnownScript.AnyoneCanPay);
-        }
-        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`);
+                throw new SessionBalanceError(`payTo has no cell to top up, and a new one needs ${ccc.fixedPointToString(newCell)} CKB`, "no-payout-cell");
             }
         }
     }
@@ -225,42 +380,85 @@ export async function openSubscription(subscriber, deployment, opts) {
 }
 /**
  * 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.
+ * (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);
+    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;
-    if (!cells.length)
-        return { lock, cells, balance, tokenBalance, nextChargeIn: undefined };
-    const tip = await client.getTip();
+    // 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 c of cells) {
-        const born = (await client.getTransaction(c.outPoint.txHash))?.blockNumber;
-        if (born === undefined || born === null)
+    for (const age of ages) {
+        if (age === undefined)
             continue; // not committed yet
-        const age = tip - ccc.numFrom(born);
         const wait = age >= sub.periodBlocks ? 0n : sub.periodBlocks - age;
         if (nextChargeIn === undefined || wait < nextChargeIn)
             nextChargeIn = wait;
     }
-    return { lock, cells, balance, tokenBalance, nextChargeIn };
+    // 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 once what is left
- * cannot cover a price and still leave a cell behind.
+ * `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);
@@ -270,7 +468,7 @@ export async function chargeSubscription(charger, deployment, sub, opts) {
     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 findSubscriptionCells(client, deployment, sub);
+    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) {
@@ -281,22 +479,16 @@ export async function chargeSubscription(charger, deployment, sub, opts) {
     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");
-        const target = await tokenTarget(client, payToLock, token);
-        tx.inputs.push(ccc.CellInput.from({ previousOutput: target.outPoint }));
-        tx.addOutput({ lock: payToLock, type: token, capacity: target.cellOutput.capacity }, tokenData(tokenAmount(target.outputData) + sub.price));
-        await tx.addCellDepsOfKnownScripts(client, ccc.KnownScript.AnyoneCanPay, ccc.KnownScript.XUdt);
+            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");
-        const targets = await collect(client, payToLock);
-        const target = targets[Math.floor(Math.random() * targets.length)];
-        if (!target)
-            throw new SessionBalanceError("payTo has no anyone-can-pay cell to top up");
-        tx.inputs.push(ccc.CellInput.from({ previousOutput: target.outPoint }));
-        tx.addOutput({ lock: payToLock, capacity: target.cellOutput.capacity + sub.price });
-        await tx.addCellDepsOfKnownScripts(client, ccc.KnownScript.AnyoneCanPay);
+            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 });
@@ -306,7 +498,7 @@ export async function chargeSubscription(charger, deployment, sub, opts) {
     }
     // 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 = fitting(await matureCells(client, state.cells, sub.periodBlocks), token);
+    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 })));
@@ -329,15 +521,41 @@ export async function chargeSubscription(charger, deployment, sub, opts) {
             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 = (await collect(client, chargerLock)).find((c) => c.cellOutput.capacity > floor);
+    const keyCell = randomPick(await feeCells(client, chargerLock, floor));
     if (!keyCell)
-        throw new SessionBalanceError(`the charger needs a plain cell above ${ccc.fixedPointToString(floor)} CKB for fees`);
+        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 tx.completeFeeChangeToOutput(charger, tx.outputs.length - 1);
+    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).
@@ -349,20 +567,119 @@ 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");
-    const { cells, balance, tokenBalance, lock: subLock } = await findSubscriptionCells(subscriber.client, deployment, sub);
+    // 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) : [];
-    const all = [...cells, ...untyped];
+    // 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 sweep = fitting(all, token);
-    const txHash = await ownerSweep(subscriber, deployment, sweep);
-    const refunded = sweep.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    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: tokensIn(sweep.map((c) => ({ type: c.cellOutput.type, data: c.outputData })), token) }),
+        ...(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. */
@@ -487,8 +804,6 @@ export async function verifySubscription(client, deployment, outPoint, expected)
         paidThroughBlock: created.block + sub.periodBlocks,
     };
 }
-/** 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 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
@@ -501,8 +816,11 @@ const MAX_PAYMENT_INPUTS = 32;
  * 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) {
-    const created = await client.getTransaction(txHash);
+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";
     }
@@ -530,20 +848,22 @@ async function paymentOf(client, deployment, txHash, sub) {
     }
     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 toPayTo = (cells) => cells.filter((c) => c.cellOutput.lock.hash() === sub.payToLockHash);
-    const outs = toPayTo(tx.outputs.map((cellOutput, i) => ({ cellOutput, data: tx.outputsData[i] ?? "0x" })));
-    const ins = toPayTo(inputs.map((c) => ({ cellOutput: c.cellOutput, data: c.outputData })));
-    const paid = token
-        ? tokensIn(outs.map((c) => ({ type: c.cellOutput.type, data: c.data })), token) -
-            tokensIn(ins.map((c) => ({ type: c.cellOutput.type, data: c.data })), token)
-        : [outs, ins]
-            .map((cells) => cells.reduce((s, c) => (!c.cellOutput.type ? s + c.cellOutput.capacity : s), 0n))
-            .reduce((o, i) => o - i);
+    const paid = out - amount(toPayTo(inputs.map((c) => ({ cellOutput: c.cellOutput, data: c.outputData }))));
     if (paid < owed)
-        return "the transaction that created the cell did not pay the price to payTo";
+        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. */
@@ -560,6 +880,11 @@ function commitsToAccount(p, sub, account) {
  * 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 {
@@ -572,24 +897,36 @@ export async function subscriptionStatus(client, deployment, sub, proof) {
         return { ok: false, reason: e instanceof Error ? e.message : String(e) };
     }
     const lock = subscriptionLock(deployment, sub);
-    const opening = await paymentOf(client, deployment, proof.openTx, 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 } = await findSubscriptionCells(client, deployment, sub);
-    const tip = await client.getTip();
+    const { cells, balance, tokenBalance, nextChargeIn, tip, created, spent, ownerAfter } = await subscriptionState(client, deployment, sub);
     let paidThroughBlock;
-    const openHash = ccc.hexFrom(proof.openTx);
-    for (const c of cells) {
-        const p = await paymentOf(client, deployment, c.outPoint.txHash, sub);
-        if (typeof p === "string")
-            continue;
-        // 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).
-        if (c.outPoint.txHash !== openHash && !spends(p, sub.chargerLockHash))
+    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)