ckb-session-kit 1.0.0 → 2.1.0

package/dist/paywall.d.ts

@@ -2,6 +2,35 @@ import { ccc } from "@ckb-ccc/core";
 import type { Session } from "./session.js";
 /** The memo for a payment: a short UTF-8 label, e.g. `read:article-1`. */
 export declare function paymentMemo(label: string): ccc.Hex;
+/** Whether `lock` runs the standard secp256k1-blake160 sighash_all code (`code`: that script on this network). */
+export declare const isSecp256k1Lock: (lock: ccc.Script, code?: {
+    codeHash: ccc.Hex;
+    hashType: ccc.HashType;
+}) => boolean;
+/**
+ * Which witnesses of `tx` a signature covers, given the locks of its inputs in
+ * order: the first witness of each input lock group whose lock signs (`signs`),
+ * and every witness past the inputs, which a sighash_all signature also covers.
+ *
+ * Any other witness can be changed by whoever relays the transaction without
+ * changing its hash: a session cell's (the session lock reads no witness) or an
+ * anyone-can-pay cell's taking a top-up (audit, 30 Oct). A memo there is nobody's.
+ */
+export declare function signedWitnesses(tx: ccc.Transaction, inputLocks: ccc.ScriptLike[], signs: (lock: ccc.Script) => boolean): (index: number) => boolean;
+/** Every witness carrying a memo (an `inputType`), with its index. */
+export declare function memoWitnesses(tx: ccc.Transaction): {
+    index: number;
+    memo: ccc.Hex;
+}[];
+/**
+ * The one witness carrying a memo and its index; undefined with none or several.
+ * Only witnesses `counts` accepts are looked at (`signedWitnesses`: those a
+ * signature covers); by default, all of them.
+ */
+export declare function soleMemo(tx: ccc.Transaction, counts?: (index: number) => boolean): {
+    index: number;
+    memo: ccc.Hex;
+} | undefined;
 export interface AccessProof {
     txHash: ccc.Hex;
     memo: ccc.Hex;

package/dist/paywall.js

@@ -14,9 +14,11 @@ import { sessionSigner } from "./transfer.js";
  * signed by the key that paid. Anyone can see the payment on-chain; only the
  * payer can use it.
  *
- * One payment, one claim: a payment transaction may carry exactly one memo.
- * Otherwise one transaction could pay the creator once and carry memos from
- * several keys, each claiming the full amount for a different article or reader.
+ * One payment, one claim: a payment transaction may carry exactly one memo in
+ * the witnesses a signature covers. Otherwise one transaction could pay the
+ * creator once and carry memos from several keys, each claiming the full amount
+ * for a different article or reader. A memo in a witness nobody signed (the
+ * session cell's) does not count: whoever relays the payment could add one.
  */
 /** A session payment has a handful of inputs; more is not one, and costs RPC calls to check. */
 const MAX_PAYMENT_INPUTS = 16;
@@ -24,6 +26,55 @@ const MAX_PAYMENT_INPUTS = 16;
 export function paymentMemo(label) {
     return ccc.hexFrom(ccc.bytesFrom(label, "utf8"));
 }
+/**
+ * The standard secp256k1-blake160 sighash_all lock, the session key's own lock: the
+ * same code on mainnet and testnet. Its signature covers the first witness of its
+ * lock group (and the rest of the group, and every witness past the inputs).
+ */
+const SECP256K1_BLAKE160 = {
+    codeHash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
+    hashType: "type",
+};
+/** Whether `lock` runs the standard secp256k1-blake160 sighash_all code (`code`: that script on this network). */
+export const isSecp256k1Lock = (lock, code = SECP256K1_BLAKE160) => lock.codeHash === code.codeHash && lock.hashType === code.hashType;
+/**
+ * Which witnesses of `tx` a signature covers, given the locks of its inputs in
+ * order: the first witness of each input lock group whose lock signs (`signs`),
+ * and every witness past the inputs, which a sighash_all signature also covers.
+ *
+ * Any other witness can be changed by whoever relays the transaction without
+ * changing its hash: a session cell's (the session lock reads no witness) or an
+ * anyone-can-pay cell's taking a top-up (audit, 30 Oct). A memo there is nobody's.
+ */
+export function signedWitnesses(tx, inputLocks, signs) {
+    const locks = inputLocks.map((l) => ccc.Script.from(l));
+    return (i) => i >= tx.inputs.length || (i < locks.length && signs(locks[i]) && !locks.slice(0, i).some((l) => l.eq(locks[i])));
+}
+/** Every witness carrying a memo (an `inputType`), with its index. */
+export function memoWitnesses(tx) {
+    const found = [];
+    for (let i = 0; i < tx.witnesses.length; i++) {
+        let inputType;
+        try {
+            inputType = tx.getWitnessArgsAt(i)?.inputType;
+        }
+        catch {
+            continue; // not WitnessArgs: carries no memo
+        }
+        if (inputType !== undefined)
+            found.push({ index: i, memo: inputType });
+    }
+    return found;
+}
+/**
+ * The one witness carrying a memo and its index; undefined with none or several.
+ * Only witnesses `counts` accepts are looked at (`signedWitnesses`: those a
+ * signature covers); by default, all of them.
+ */
+export function soleMemo(tx, counts = () => true) {
+    const found = memoWitnesses(tx).filter((m) => counts(m.index));
+    return found.length === 1 ? found[0] : undefined;
+}
 function accessMessage(txHash, memo) {
     return `ckb-session-kit access ${ccc.hexFrom(txHash)} ${ccc.hexFrom(memo)}`;
 }
@@ -51,7 +102,10 @@ export async function verifyAccess(client, proof, expect) {
     }
     if (!signed)
         return { ok: false, reason: "request not signed by the given key" };
-    const res = await client.getTransaction(proof.txHash);
+    // Not getTransaction: when the node no longer knows a transaction (reorged out,
+    // replaced by a conflicting spend), it answers from CCC's cache, where a payment
+    // once seen committed stays committed (audit, 31 Oct).
+    const res = await client.getTransactionNoCache(proof.txHash);
     if (!res)
         return { ok: false, reason: "payment not found" };
     if (res.status !== "committed")
@@ -60,39 +114,38 @@ export async function verifyAccess(client, proof, expect) {
     // Cheap checks first, before resolving any input over RPC.
     if (tx.inputs.length > MAX_PAYMENT_INPUTS)
         return { ok: false, reason: "not a session payment: too many inputs" };
-    let memos = 0;
-    let memoAt = -1;
-    for (let i = 0; i < tx.witnesses.length; i++) {
-        let inputType;
-        try {
-            inputType = tx.getWitnessArgsAt(i)?.inputType;
-        }
-        catch {
-            continue; // not WitnessArgs: carries no memo
-        }
-        if (inputType !== undefined) {
-            memos++;
-            memoAt = i;
-        }
-    }
-    if (memos !== 1)
+    const memos = memoWitnesses(tx);
+    if (!memos.length)
         return { ok: false, reason: "a payment must carry exactly one memo" };
     // The payer's lock: the standard secp256k1 lock of the key that signed the request.
     const payerLock = (await new ccc.SignerCkbPublicKey(client, proof.publicKey).getAddressObjSecp256k1()).script;
-    // One lookup before all of them: anyone can sign a request for someone else's
+    // Before all of them, only the inputs whose witness carries a memo, until one is
+    // the payer's (usually the first): anyone can sign a request for someone else's
     // public payment, and must not get to make the server resolve every input.
-    const memoCell = memoAt < tx.inputs.length ? await client.getCell(tx.inputs[memoAt].previousOutput) : undefined;
-    if (!memoCell?.cellOutput.lock.eq(payerLock))
+    const known = new Map();
+    let paidByKey = false;
+    for (const { index } of memos) {
+        if (index >= tx.inputs.length)
+            continue;
+        const cell = await client.getCell(tx.inputs[index].previousOutput);
+        known.set(index, cell);
+        if (cell?.cellOutput.lock.eq(payerLock)) {
+            paidByKey = true;
+            break;
+        }
+    }
+    if (!paidByKey)
         return { ok: false, reason: "the signing key did not pay this transaction" };
     const to = ccc.Script.from(expect.to);
     const token = expect.token && ccc.Script.from(expect.token);
     // What a cell gives the recipient: its capacity, or with a token its units of that exact token
     // (a committed xUDT cell always holds the 16-byte amount).
     const value = (o, data) => !o.lock.eq(to) ? 0n : !token ? o.capacity : o.type?.eq(token) ? tokenAmount(data) : 0n;
+    // The rest at once, reusing those already looked up.
+    const inputs = await Promise.all(tx.inputs.map((input, i) => (known.has(i) ? known.get(i) : client.getCell(input.previousOutput))));
     let payerInput = -1;
     let toIn = 0n;
-    for (let i = 0; i < tx.inputs.length; i++) {
-        const cell = await client.getCell(tx.inputs[i].previousOutput);
+    for (const [i, cell] of inputs.entries()) {
         if (!cell)
             return { ok: false, reason: "an input of the payment cannot be resolved" };
         if (payerInput < 0 && cell.cellOutput.lock.eq(payerLock))
@@ -101,6 +154,12 @@ export async function verifyAccess(client, proof, expect) {
     }
     if (payerInput < 0)
         return { ok: false, reason: "the signing key did not pay this transaction" };
+    // One memo among the witnesses a signature covers. A memo in a witness nobody
+    // signed (the session cell's, say) was not put there by the payer and cannot
+    // void the payment; several signed ones could each claim it (audit, 30 Oct).
+    const covered = signedWitnesses(tx, inputs.map((c) => c.cellOutput.lock), (lock) => isSecp256k1Lock(lock, payerLock));
+    if (!soleMemo(tx, covered))
+        return { ok: false, reason: "a payment must carry exactly one memo" };
     // The witness the payer's lock verified (the first of its group) must carry the memo.
     const witness = tx.getWitnessArgsAt(payerInput);
     if (!witness?.inputType || ccc.hexFrom(witness.inputType) !== ccc.hexFrom(expect.memo)) {

package/dist/place.d.ts

@@ -51,11 +51,20 @@ export declare function decodePlacement(memo: ccc.HexLike, board?: PlaceBoard):
 /** What a placement costs, in shannons. */
 export declare function placementPrice(pixels: number, board?: PlaceBoard): bigint;
 /**
- * The cheap part of the check, before resolving any input: the transaction
- * carries exactly one memo, it is a valid placement, and where it sits (the
- * witness index). `undefined` if not.
+ * The placement memo of `tx` and where it sits (the witness index), or `undefined`.
+ *
+ * With `inputs` (the cells `tx` spends, resolved, in input order) this is exact:
+ * exactly one memo among the witnesses a signature covers (`signedWitnesses`: the
+ * first witness of a secp256k1 lock group, as the session key's key cell has, or
+ * one past the inputs), at an input's index, and a valid placement. A memo in a
+ * witness nobody signed (the session cell's, the board's) is ignored: whoever
+ * relays the transaction could have put it there (audit, 30 Oct).
+ *
+ * Without `inputs` it is the cheap check, before resolving any input: `undefined`
+ * means `tx` is certainly no placement; otherwise the first witness at an input's
+ * index holding a valid placement, which `checkPlacement` then settles.
  */
-export declare function placementMemo(tx: ccc.TransactionLike, board?: PlaceBoard): {
+export declare function placementMemo(tx: ccc.TransactionLike, board?: PlaceBoard, inputs?: ccc.CellOutputLike[]): {
     index: number;
     pixels: Pixel[];
 } | undefined;
@@ -71,11 +80,11 @@ export type PlacementCheck = {
  * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
  * the cells `tx` spends, resolved, in input order.
  *
- * - exactly one memo, and a valid one (`placementMemo`);
- * - the memo sits in the first witness of an input's lock group, and that lock is
- *   not the board's: it is the witness the payer's lock verifies, so a lock that
- *   signs its witnesses (secp256k1: the session key's key cell) commits the
- *   payment to these pixels and no relay can swap them;
+ * - exactly one memo among the witnesses a signature covers, and a valid one,
+ *   in the first witness of a secp256k1 lock group that is not the board's
+ *   (`placementMemo` with `inputs`): the witness the payer's lock signs (the
+ *   session key's key cell), so the payment commits to these pixels and no relay
+ *   can swap them, nor add a memo of its own that counts;
  * - the board's lock gained at least `price × pixels` (outputs minus inputs).
  */
 export declare function checkPlacement(tx: ccc.TransactionLike, inputs: ccc.CellOutputLike[], boardLock: ccc.ScriptLike, board?: PlaceBoard): PlacementCheck;

package/dist/place.js

@@ -1,4 +1,5 @@
 import { ccc } from "@ckb-ccc/core";
+import { isSecp256k1Lock, memoWitnesses, signedWitnesses, soleMemo } from "./paywall.js";
 /** The demo's board: 32×32, 16 colours, 0.1 CKB a pixel, up to 32 pixels a payment. */
 export const PLACE_BOARD = { width: 32, height: 32, colours: 16, price: 10000000n, maxPixels: 32 };
 export class PlaceMemoError extends Error {
@@ -67,27 +68,34 @@ export function placementPrice(pixels, board = PLACE_BOARD) {
     return board.price * BigInt(pixels);
 }
 /**
- * The cheap part of the check, before resolving any input: the transaction
- * carries exactly one memo, it is a valid placement, and where it sits (the
- * witness index). `undefined` if not.
+ * The placement memo of `tx` and where it sits (the witness index), or `undefined`.
+ *
+ * With `inputs` (the cells `tx` spends, resolved, in input order) this is exact:
+ * exactly one memo among the witnesses a signature covers (`signedWitnesses`: the
+ * first witness of a secp256k1 lock group, as the session key's key cell has, or
+ * one past the inputs), at an input's index, and a valid placement. A memo in a
+ * witness nobody signed (the session cell's, the board's) is ignored: whoever
+ * relays the transaction could have put it there (audit, 30 Oct).
+ *
+ * Without `inputs` it is the cheap check, before resolving any input: `undefined`
+ * means `tx` is certainly no placement; otherwise the first witness at an input's
+ * index holding a valid placement, which `checkPlacement` then settles.
  */
-export function placementMemo(tx, board = PLACE_BOARD) {
+export function placementMemo(tx, board = PLACE_BOARD, inputs) {
     const t = ccc.Transaction.from(tx);
-    let found;
-    for (let i = 0; i < t.witnesses.length; i++) {
-        let inputType;
-        try {
-            inputType = t.getWitnessArgsAt(i)?.inputType;
+    if (!inputs) {
+        for (const m of memoWitnesses(t)) {
+            const pixels = m.index < t.inputs.length ? decodePlacement(m.memo, board) : undefined;
+            if (pixels)
+                return { index: m.index, pixels };
         }
-        catch {
-            continue; // not WitnessArgs: carries no memo
-        }
-        if (inputType === undefined)
-            continue;
-        if (found)
-            return undefined; // two memos: which one was paid for is ambiguous
-        found = { index: i, memo: inputType };
+        return undefined;
     }
+    if (inputs.length !== t.inputs.length)
+        return undefined;
+    const locks = inputs.map((c) => ccc.CellOutput.from(c).lock);
+    // Two signed memos: which one was paid for is ambiguous.
+    const found = soleMemo(t, signedWitnesses(t, locks, (lock) => isSecp256k1Lock(lock)));
     if (!found || found.index >= t.inputs.length)
         return undefined;
     const pixels = decodePlacement(found.memo, board);
@@ -97,28 +105,24 @@ export function placementMemo(tx, board = PLACE_BOARD) {
  * Whether `tx` is a valid placement on the board under `boardLock`. `inputs` are
  * the cells `tx` spends, resolved, in input order.
  *
- * - exactly one memo, and a valid one (`placementMemo`);
- * - the memo sits in the first witness of an input's lock group, and that lock is
- *   not the board's: it is the witness the payer's lock verifies, so a lock that
- *   signs its witnesses (secp256k1: the session key's key cell) commits the
- *   payment to these pixels and no relay can swap them;
+ * - exactly one memo among the witnesses a signature covers, and a valid one,
+ *   in the first witness of a secp256k1 lock group that is not the board's
+ *   (`placementMemo` with `inputs`): the witness the payer's lock signs (the
+ *   session key's key cell), so the payment commits to these pixels and no relay
+ *   can swap them, nor add a memo of its own that counts;
  * - the board's lock gained at least `price × pixels` (outputs minus inputs).
  */
 export function checkPlacement(tx, inputs, boardLock, board = PLACE_BOARD) {
     const t = ccc.Transaction.from(tx);
     if (inputs.length !== t.inputs.length)
         return { ok: false, reason: "inputs not resolved" };
-    const memo = placementMemo(t, board);
+    const memo = placementMemo(t, board, inputs);
     if (!memo)
         return { ok: false, reason: "no valid placement memo" };
     const lock = ccc.Script.from(boardLock);
     const cells = inputs.map((c) => ccc.CellOutput.from(c));
-    const memoLock = cells[memo.index].lock;
-    if (memoLock.eq(lock))
+    if (cells[memo.index].lock.eq(lock))
         return { ok: false, reason: "the memo is in the board's own witness" };
-    if (cells.slice(0, memo.index).some((c) => c.lock.eq(memoLock))) {
-        return { ok: false, reason: "the memo is not in the first witness of its lock group" };
-    }
     const sum = (cs) => cs.reduce((s, c) => (c.lock.eq(lock) ? s + c.capacity : s), 0n);
     const paid = sum(t.outputs) - sum(cells);
     const price = placementPrice(memo.pixels.length, board);

package/dist/session.d.ts

@@ -46,8 +46,21 @@ export interface CreateOptions {
     /** Injectable for tests; defaults to the platform CSPRNG. */
     randomBytes?: (n: number) => Uint8Array;
 }
+/**
+ * Why a policy error is not about the request itself: "payto-not-anyone-can-pay",
+ * the payer's own setup (a charge can never top such a `payTo` up); or
+ * "too-many-cells", more cells under a subscription's lock than a status or a
+ * charge reads (`MAX_SUBSCRIPTION_CELLS`). From `fundInSession`:
+ * "session-has-recipient", the session has an on-chain recipient, so it cannot
+ * fund outputs to other locks; "owner-lock-input", the app transaction spends a
+ * cell under the owner's lock, which would switch the session lock to owner
+ * mode; "app-tx-shape", the app transaction already holds cells only the kit
+ * may add (session or key cells), or its inputs exceed its outputs.
+ */
+export type SessionPolicyReason = "payto-not-anyone-can-pay" | "too-many-cells" | "owner-lock-unsafe" | "owner-lock-unreviewed" | "session-has-recipient" | "owner-lock-input" | "app-tx-shape";
 export declare class SessionPolicyError extends Error {
-    constructor(message: string);
+    readonly reason?: SessionPolicyReason;
+    constructor(message: string, reason?: SessionPolicyReason);
 }
 export declare function createSession(policy: SessionPolicy, options?: CreateOptions): Session;
 export declare function isActive(session: Session, now?: Date): boolean;

package/dist/session.js

@@ -1,8 +1,11 @@
 import { ccc } from "@ckb-ccc/core";
 export class SessionPolicyError extends Error {
-    constructor(message) {
+    reason;
+    constructor(message, reason) {
         super(message);
         this.name = "SessionPolicyError";
+        if (reason)
+            this.reason = reason;
     }
 }
 const SECP256K1_N = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");

package/dist/store.d.ts

@@ -7,7 +7,8 @@ export interface SessionStore {
     load(): Promise<Session | undefined>;
     /**
      * Stores `session`. Refuses (SessionStoreConflict) to replace a *different*
-     * session: its key may hold funds, and another tab may have just saved it.
+     * session: its key may hold funds, and another tab may have just saved it. Also
+     * refuses to replace the same session's on-chain binding with none.
      */
     save(session: Session): Promise<void>;
     /** Forgets `session`, only if it is still the stored one; another tab may have replaced it. */

package/dist/store.js

@@ -20,6 +20,21 @@ function storedKey(raw) {
         throw new Error(UNREADABLE);
     return key;
 }
+/**
+ * Throws SessionStoreConflict unless `session` may replace the stored value: a
+ * different key may hold funds, and a save of the same key without the on-chain
+ * binding (a stale tab that never saw the funding) would lose what finds them
+ * (review, 28 Oct).
+ */
+function assertReplaceable(raw, session) {
+    const held = storedKey(raw);
+    if (held === undefined)
+        return;
+    if (held !== session.publicKey)
+        throw new SessionStoreConflict();
+    if (!session.onchain && JSON.parse(raw).onchain)
+        throw new SessionStoreConflict();
+}
 export function serializeSession(s) {
     const stored = {
         v: 1,
@@ -91,9 +106,7 @@ export function memoryStore() {
     return {
         load: async () => (value === undefined ? undefined : deserializeSession(value)),
         save: async (s) => {
-            const held = storedKey(value);
-            if (held !== undefined && held !== s.publicKey)
-                throw new SessionStoreConflict();
+            assertReplaceable(value, s);
             value = serializeSession(s);
         },
         clear: async (s) => {
@@ -168,9 +181,7 @@ export function indexedDbStore(idb = globalThis.indexedDB, key = KEY) {
         save: async (session) => {
             const value = serializeSession(session);
             await update((raw) => {
-                const held = storedKey(raw);
-                if (held !== undefined && held !== session.publicKey)
-                    throw new SessionStoreConflict();
+                assertReplaceable(raw, session);
                 return "put";
             }, value);
         },

package/dist/subscription.d.ts

@@ -1,5 +1,6 @@
 import { ccc } from "@ckb-ccc/core";
 import { type SessionLockDeployment } from "./lock.js";
+import { type SigningLockOptions, type RetryOptions } from "./onchain.js";
 /**
  * Subscriptions (docs/design/subscriptions.md): the same session lock, with the
  * roles moved. The subscriber is the owner; the creator's charger key is the
@@ -47,6 +48,42 @@ export declare function subscriptionLock(deployment: SessionLockDeployment, sub:
  * secret the subscriber's browser presents to the creator.
  */
 export declare function subscriptionMemo(account: string): ccc.Hex;
+/**
+ * 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 declare const MAX_SUBSCRIPTION_CELLS = 16;
+/**
+ * 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 declare const MAX_CREATED_HISTORY: number;
+/**
+ * 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 declare const CLEAR_PLANTED_MEMO: `0x${string}`;
 /**
  * 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
@@ -87,13 +124,18 @@ export declare function openSubscription(subscriber: ccc.Signer, deployment: Ses
     };
     account?: string;
     beforeSend?: (sub: Subscription) => Promise<void>;
-}): Promise<{
+    /** Let an unreviewed charger lock through, with a warning (`allowUnreviewedOwnerLock` covers the subscriber's own lock only). */
+    allowUnreviewedChargerLock?: boolean;
+} & SigningLockOptions): Promise<{
     txHash: ccc.Hex;
     subscription: Subscription;
 }>;
 /**
  * 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 declare function findSubscriptionCells(client: ccc.Client, deployment: SessionLockDeployment, sub: Subscription): Promise<{
     lock: ccc.Script;
@@ -106,19 +148,30 @@ export declare function findSubscriptionCells(client: ccc.Client, deployment: Se
  * 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 declare function chargeSubscription(charger: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription, opts: {
+export declare function chargeSubscription(charger: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription, opts: ChargeOptions): Promise<ccc.Hex>;
+type ChargeOptions = {
     payTo: string;
     topUp?: boolean;
     beforeSend?: (txHash: ccc.Hex) => Promise<void>;
-}): Promise<ccc.Hex>;
+    retry?: RetryOptions;
+};
 /**
  * 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).
@@ -132,6 +185,40 @@ export declare function cancelSubscription(subscriber: ccc.Signer, deployment: S
     refundedTokens?: bigint;
     nothingFound?: true;
 }>;
+/**
+ * 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 declare function clearPlantedCells(subscriber: ccc.Signer, deployment: SessionLockDeployment, sub: Subscription): Promise<{
+    txHash?: ccc.Hex;
+    swept: number;
+    refunded: bigint;
+    refundedTokens?: bigint;
+    more: boolean;
+    nothingFound?: true;
+}>;
 export type SubscriptionCheck = {
     ok: true;
     subscription: Subscription;
@@ -181,7 +268,10 @@ export declare function verifySubscription(client: ccc.Client, deployment: Sessi
     token?: ccc.ScriptLike;
 }): Promise<SubscriptionCheck>;
 export interface SubscriptionStatus {
-    /** The block until which the subscriber has paid, from the newest paying cell; undefined when no cell is left. */
+    /**
+     * The block until which the subscriber has paid, from the newest paying cell or
+     * a charge that took the whole balance; undefined when neither is left.
+     */
     paidThroughBlock: bigint | undefined;
     tip: bigint;
     /** Whether the tip is within the paid period. */
@@ -203,6 +293,11 @@ export interface SubscriptionStatus {
  * 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 declare function subscriptionStatus(client: ccc.Client, deployment: SessionLockDeployment, sub: Subscription, proof: {
     openTx: ccc.HexLike;
@@ -219,3 +314,4 @@ export declare function subscriptionStatus(client: ccc.Client, deployment: Sessi
  * `sample` blocks. Block time varies; round up when a period means "no more often than".
  */
 export declare function blocksForSeconds(client: ccc.Client, seconds: number, sample?: bigint): Promise<bigint>;
+export {};