ckb-session-kit 1.0.0 → 2.0.0

package/dist/deployment.js

@@ -0,0 +1,92 @@
+import { ccc } from "@ckb-ccc/core";
+import { TESTNET_LEGACY_DEPLOYMENTS } from "./lock.js";
+import { SessionPolicyError } from "./session.js";
+/**
+ * Checks run before any new cell goes under the session lock (audit round 2, 31 Oct).
+ *
+ * Only paths that CREATE cells under a deployment call this: `openSession`,
+ * `openSubscription`. Spending, closing, recovering, charging and cancelling
+ * still accept any deployment, legacy ones included, so funds already under an
+ * old lock can always come back.
+ */
+/** Successful checks, per client and deployment: one lookup per process, not per call. */
+const verified = new WeakMap();
+const keyOf = (d) => {
+    const op = ccc.OutPoint.from(d.cellDep.outPoint);
+    return [ccc.hexFrom(d.codeHash), ccc.hashTypeFrom(d.hashType), op.txHash, op.index, ccc.depTypeFrom(d.cellDep.depType)].join(":");
+};
+/**
+ * Throws a `SessionPolicyError` unless new cells may go under `deployment` on
+ * `client`'s network:
+ *
+ * - it is not one of `TESTNET_LEGACY_DEPLOYMENTS` (older code with fewer rules;
+ *   the 13 Oct one cannot even spend a token session's 128/160-byte args);
+ * - its `hashType` is not `data`: under CKB-VM version 0 the lock faults on
+ *   load, owner mode included, so such cells could never be spent;
+ * - its cell dep is live on this network and holds the code: the code cell's
+ *   data hashes to `codeHash` (`data1`, `data2`) or its type script hashes to
+ *   it (`type`). A `depGroup` cell dep is resolved and any member may match.
+ *   This catches a testnet deployment on a mainnet client, a typo in
+ *   `codeHash` and a wrong out point, any of which would leave funds under a
+ *   lock no code can run.
+ *
+ * A passing check is remembered for that client and deployment; a failing one
+ * is not, so the next call looks again.
+ */
+export async function assertCurrentDeployment(client, deployment) {
+    const codeHash = ccc.hexFrom(deployment.codeHash);
+    if (TESTNET_LEGACY_DEPLOYMENTS.some((d) => ccc.hexFrom(d.codeHash) === codeHash)) {
+        throw new SessionPolicyError("this is an old deployment of the session lock: new sessions and subscriptions go under the current one " +
+            "(old deployments are still accepted to spend, close, recover and cancel)");
+    }
+    if (ccc.hashTypeFrom(deployment.hashType) === "data") {
+        throw new SessionPolicyError("the session lock cannot run under hash_type data (CKB-VM version 0): use data1 or data2 (or type)");
+    }
+    let byKey = verified.get(client);
+    if (!byKey)
+        verified.set(client, (byKey = new Map()));
+    const key = keyOf(deployment);
+    let check = byKey.get(key);
+    if (!check) {
+        check = checkCode(client, deployment);
+        byKey.set(key, check);
+        check.catch(() => byKey.delete(key));
+    }
+    await check;
+}
+async function checkCode(client, d) {
+    const codeHash = ccc.hexFrom(d.codeHash);
+    const byType = ccc.hashTypeFrom(d.hashType) === "type";
+    const outPoint = ccc.OutPoint.from(d.cellDep.outPoint);
+    const where = `${outPoint.txHash}:${Number(outPoint.index)}`;
+    const dep = await client.getCellLive(outPoint, true);
+    if (!dep) {
+        throw new SessionPolicyError(`the session lock's cell dep ${where} is not a live cell on this network: a deployment for another ` +
+            "network (TESTNET_DEPLOYMENT on mainnet?) or a wrong out point; no funds go under a lock with no code");
+    }
+    let candidates = [dep];
+    if (ccc.depTypeFrom(d.cellDep.depType) === "depGroup") {
+        const members = depGroupMembers(dep.outputData);
+        if (!members)
+            throw new SessionPolicyError(`the session lock's dep group ${where} does not hold a list of out points`);
+        candidates = (await Promise.all(members.map((m) => client.getCellLive(m, true)))).filter((c) => !!c);
+    }
+    const holds = (c) => (byType ? c.cellOutput.type?.hash() === codeHash : ccc.hashCkb(c.outputData) === codeHash);
+    if (!candidates.some(holds)) {
+        throw new SessionPolicyError(`the session lock's cell dep ${where} does not hold code whose ${byType ? "type hash" : "data hash"} is ` +
+            `${codeHash}: a typo in codeHash or a wrong out point; no funds go under a lock with no code`);
+    }
+}
+/** A dep group cell's data: a molecule OutPointVec (u32 LE count, then 36-byte out points). */
+function depGroupMembers(data) {
+    const b = ccc.bytesFrom(data);
+    if (b.length < 4)
+        return undefined;
+    const n = Number(ccc.numLeFromBytes(b.slice(0, 4)));
+    if (b.length !== 4 + 36 * n)
+        return undefined;
+    return Array.from({ length: n }, (_, i) => {
+        const at = 4 + 36 * i;
+        return ccc.OutPoint.from({ txHash: b.slice(at, at + 32), index: ccc.numLeFromBytes(b.slice(at + 32, at + 36)) });
+    });
+}

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export { checkRequest, createSession, isActive, SessionPolicyError } from "./session.js";
-export type { CreateOptions, ScopeCheck, Session, SessionPolicy, SessionScope } from "./session.js";
+export type { CreateOptions, ScopeCheck, Session, SessionPolicy, SessionPolicyReason, SessionScope } from "./session.js";
 export { deserializeSession, indexedDbStore, memoryStore, serializeSession, SessionStoreConflict } from "./store.js";
 export type { SessionStore } from "./store.js";
 export { ScopeError, sendInScope, sessionAddress, sessionSigner } from "./transfer.js";
 export { relativeBlocksSince, SESSION_LOCK_ERRORS, sessionLockArgs, sessionLockCellDep, sessionLockErrorFrom, sessionLockScript, TESTNET_DEPLOYMENT, TESTNET_LEGACY_DEPLOYMENTS, } from "./lock.js";
 export type { SessionLockDeployment, SessionLockParams } from "./lock.js";
-export { assertPlainXudt, assertSigningLock, closeSession, findOwnedSessionCells, findSessionCells, keyLockOf, matureCells, onchainRecipient, openSession, recoverSessions, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
-export type { OnChainBinding, SessionCells } from "./onchain.js";
-export { blocksForSeconds, cancelSubscription, chargeSubscription, findSubscriptionCells, openSubscription, subscriptionLock, subscriptionMemo, subscriptionStatus, verifySubscription, } from "./subscription.js";
+export { assertCurrentDeployment } from "./deployment.js";
+export { assertPlainXudt, assertSigningLock, closeSession, createPayoutCells, DEFAULT_RETRY, findOwnedSessionCells, findSessionCells, keyLockOf, matureCells, MAX_PAYOUT_CELLS, MAX_POOL_CHECKS, onchainRecipient, openSession, pickPayoutCell, poolConflict, recoverSessions, SendOutcomeUnknownError, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
+export type { OnChainBinding, RetryOptions, SessionBalanceReason, SessionCells, SessionWarning, SigningLockOptions, } from "./onchain.js";
+export { blocksForSeconds, cancelSubscription, chargeSubscription, clearPlantedCells, findSubscriptionCells, MAX_SUBSCRIPTION_CELLS, openSubscription, subscriptionLock, subscriptionMemo, subscriptionStatus, verifySubscription, } from "./subscription.js";
 export type { Subscription, SubscriptionCheck, SubscriptionStatus } from "./subscription.js";
 export { paymentMemo, signAccess, verifyAccess } from "./paywall.js";
 export type { AccessCheck, AccessProof } from "./paywall.js";

package/dist/index.js

@@ -2,7 +2,8 @@ export { checkRequest, createSession, isActive, SessionPolicyError } from "./ses
 export { deserializeSession, indexedDbStore, memoryStore, serializeSession, SessionStoreConflict } from "./store.js";
 export { ScopeError, sendInScope, sessionAddress, sessionSigner } from "./transfer.js";
 export { relativeBlocksSince, SESSION_LOCK_ERRORS, sessionLockArgs, sessionLockCellDep, sessionLockErrorFrom, sessionLockScript, TESTNET_DEPLOYMENT, TESTNET_LEGACY_DEPLOYMENTS, } from "./lock.js";
-export { assertPlainXudt, assertSigningLock, closeSession, findOwnedSessionCells, findSessionCells, keyLockOf, matureCells, onchainRecipient, openSession, recoverSessions, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
-export { blocksForSeconds, cancelSubscription, chargeSubscription, findSubscriptionCells, openSubscription, subscriptionLock, subscriptionMemo, subscriptionStatus, verifySubscription, } from "./subscription.js";
+export { assertCurrentDeployment } from "./deployment.js";
+export { assertPlainXudt, assertSigningLock, closeSession, createPayoutCells, DEFAULT_RETRY, findOwnedSessionCells, findSessionCells, keyLockOf, matureCells, MAX_PAYOUT_CELLS, MAX_POOL_CHECKS, onchainRecipient, openSession, pickPayoutCell, poolConflict, recoverSessions, SendOutcomeUnknownError, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
+export { blocksForSeconds, cancelSubscription, chargeSubscription, clearPlantedCells, findSubscriptionCells, MAX_SUBSCRIPTION_CELLS, openSubscription, subscriptionLock, subscriptionMemo, subscriptionStatus, verifySubscription, } from "./subscription.js";
 export { paymentMemo, signAccess, verifyAccess } from "./paywall.js";
 export { applyPlacements, checkPlacement, decodePlacement, encodePlacement, PLACE_BOARD, placementMemo, placementPrice, PlaceMemoError, } from "./place.js";

package/dist/onchain.d.ts

@@ -33,8 +33,37 @@ export interface SessionCells {
     /** Token units in the session cells (token sessions; 0 otherwise). */
     tokenBalance: bigint;
 }
+/**
+ * Why a `SessionBalanceError` was thrown, where a caller may need to tell it apart
+ * without matching the message (which may change):
+ * - `no-fee-cell`: the paying key (a session's key cell, a subscription's charger)
+ *   has no cell that can pay the fee.
+ * - `no-payout-cell`: the recipient (`payTo`) has no cell to top up.
+ * - `payout-busy`: every payout cell checked is being spent by a transaction in
+ *   the node's pool (other payers at the same moment). Nothing was sent; try
+ *   again after a block, or give the recipient more cells (`createPayoutCells`).
+ *
+ * Neither is about the session's or the subscription's own balance or timing: the
+ * missing cells belong to the key's holder or the recipient (in a subscription,
+ * both are the creator's). Other balance errors have no `reason`.
+ */
+export type SessionBalanceReason = "no-fee-cell" | "no-payout-cell" | "payout-busy";
 export declare class SessionBalanceError extends Error {
-    constructor(message: string);
+    readonly reason?: SessionBalanceReason;
+    constructor(message: string, reason?: SessionBalanceReason);
+}
+/**
+ * Something about a session's terms that the lock will enforce as written but that
+ * the owner may not have meant. `openSession` reports it before anything is signed
+ * (`opts.onWarning`, or `console.warn` without one).
+ * - `no-rate-limit`: `minInterval` is 0 (or 1, almost the same: review W6 I3). Each
+ *   spend is held to `maxPerTx`, but the change of one spend can be spent again in
+ *   the next block (with 1, a block later), so a leaked key can repeat spends until the
+ *   session is empty.
+ */
+export interface SessionWarning {
+    code: "no-rate-limit";
+    message: string;
 }
 /**
  * The smallest key cell that can still be returned to the owner: a cell under the
@@ -42,11 +71,24 @@ export declare class SessionBalanceError extends Error {
  * below a key cell's own 61 CKB.
  */
 export declare function keyCellFloor(ownerLock: ccc.ScriptLike): bigint;
+/**
+ * A send failed and the node could not then be asked whether it has the
+ * transaction (review W6 L4): it may have been taken and committed. Never
+ * retried; `txHash` is the transaction to look for, and `cause` the send's own
+ * error. Its message never repeats the cause's, so nothing reads it as a
+ * refusal for a spent input.
+ */
+export declare class SendOutcomeUnknownError extends Error {
+    readonly txHash: ccc.Hex;
+    constructor(txHash: ccc.Hex, cause: unknown);
+}
 /**
  * Signs `tx`, hands its final hash to `beforeSend`, then sends it. The hash is
  * known before anything leaves, so a caller can record the payment or the key
  * against it first. If the send throws but the node did take the transaction (a
- * timeout on the reply, say), the hash is returned all the same.
+ * timeout on the reply, say), the hash is returned all the same. If the send
+ * throws and the status lookup fails too, a `SendOutcomeUnknownError` is thrown
+ * instead of the send's error, which `rebuildOnDeadInputs` never retries.
  */
 export declare function signAndSend(signer: ccc.Signer, tx: ccc.Transaction, beforeSend?: (txHash: ccc.Hex) => Promise<void>): Promise<ccc.Hex>;
 export declare function keyLockOf(session: Session, client: ccc.Client): Promise<ccc.Script>;
@@ -56,8 +98,110 @@ export declare const tokenData: (amount: bigint, rest?: Uint8Array) => `0x${stri
 /** A cell's data is exactly a 16-byte amount: what the session lock accepts as token change. */
 export declare const plainTokenCell: (cell: ccc.Cell, type: ccc.Script) => boolean;
 export declare function sessionLockOf(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<ccc.Script>;
+/**
+ * Whether a session-lock cell was created by a transaction its owner or its
+ * session key took part in (an input under the lock hash in args bytes 0..32 or
+ * 32..64). Nobody else can sign for those, so a planted cell never passes.
+ */
+export declare function ownOrigin(client: ccc.Client, cell: ccc.Cell): Promise<boolean>;
+/**
+ * `cells` less those whose token amounts would overflow a u128, per token type.
+ * Anyone can plant a cell holding 2^128-1 units of a free token under a session
+ * lock, and xUDT refuses a transaction whose inputs overflow, so taking every
+ * cell would block spends, closes, recovery, charges and cancels (review, 27 and
+ * 28 Oct). Which cells stay does not depend on indexer order: cells of the
+ * owner's or the key's own making first, then the smallest amounts. Without an
+ * overflow nothing is looked up and every cell stays, in order.
+ */
+export declare function withinU128(client: ccc.Client, cells: ccc.Cell[]): Promise<ccc.Cell[]>;
+/** One of `cells` at random: payers or chargers at once then rarely compete for the same cell. */
+export declare const randomPick: <T>(cells: T[]) => T | undefined;
+/** Whether `lock` is this network's anyone-can-pay lock (RFC 0026). */
+export declare function isAnyoneCanPay(lock: ccc.Script, client: ccc.Client): Promise<boolean>;
+/** The most cells of a recipient read when picking one to top up: any of them will do. */
+export declare const MAX_PAYOUT_CELLS = 64;
+/** The most payout cells a pick asks the node about (`get_live_cell` with the pool), all at once. */
+export declare const MAX_POOL_CHECKS = 4;
+/**
+ * Which of `cells` (the recipient's anyone-can-pay cells) to top up, so payers at
+ * the same moment rarely take the same one (mentor review, 2 Nov):
+ *
+ * - confirmed cells first (listed by the indexer), then this client's own
+ *   outputs still pending (only CCC's cache lists them), each group shuffled;
+ * - `avoid` (out points a node rejection named as spent) left out;
+ * - the first `MAX_POOL_CHECKS` asked at once whether a transaction in the
+ *   node's pool spends them (`get_live_cell` with `include_tx_pool`: a cell a
+ *   pool transaction consumes is dead); the first free one is taken.
+ *
+ * If the node cannot be asked, an unchecked cell is taken (a rejected send is
+ * retried). If every cell checked is spent in the pool, an unchecked one is taken
+ * if any is left; otherwise a `SessionBalanceError` "payout-busy" is thrown and
+ * nothing is sent. Undefined when `cells` is empty.
+ */
+export declare function pickPayoutCell(client: ccc.Client, lock: ccc.Script, cells: ccc.Cell[], avoid?: ReadonlySet<string>): Promise<ccc.Cell | undefined>;
+/**
+ * Tops up one cell under the anyone-can-pay `lock` in `tx`: one input, and one
+ * output holding `ckb` shannons more, or with `token`, `units` more of it in a
+ * cell of that token. The cell is chosen by `pickPayoutCell`, never one in
+ * `avoid`. Returns the cell, or undefined when `lock` has none to add to.
+ */
+export declare function addTopUp(tx: ccc.Transaction, client: ccc.Client, lock: ccc.Script, add: {
+    ckb?: bigint;
+    token?: ccc.Script;
+    units?: bigint;
+}, avoid?: ReadonlySet<string>): Promise<ccc.Cell | undefined>;
 /** Plain cells under `lock`; with `token`, also cells holding exactly that token. */
 export declare function collect(client: ccc.Client, lock: ccc.Script, token?: ccc.Script): Promise<ccc.Cell[]>;
+/**
+ * `cells` (found under `lock`) less those only CCC's client cache vouches for
+ * that are gone. The cache lists the outputs of every transaction this client
+ * sent as live, ahead of the indexer's cells, and never drops them: once another
+ * tab, device or server instance spends them, every transaction built here on
+ * them would be rejected until a reload (audit, 31 Oct). A cached cell is kept
+ * while the transaction that made it is pending or proposed (a chain of
+ * payments faster than the indexer needs it), or once committed while the node
+ * says it is still live; it is dropped once the node no longer knows that
+ * transaction, or says the cell is spent. When the node cannot be asked, it is kept.
+ */
+export declare function withoutDeadCached(client: ccc.Client, lock: ccc.Script, cells: ccc.Cell[]): Promise<ccc.Cell[]>;
+/** Whether a send was rejected because an input is spent or unknown to the node. */
+export declare function deadInputs(e: unknown): boolean;
+/**
+ * Whether a send was rejected because an input is already spent by a
+ * transaction in the node's pool, on a node with replace-by-fee on: CKB then
+ * runs its RBF checks instead of answering `Dead`, and refuses the newcomer
+ * (`PoolRejectedRBF`, -1111) unless it pays enough more to replace the other.
+ */
+export declare function poolConflict(e: unknown): boolean;
+/** How often, and how patiently, a payment or a charge is built again after a refusal for a spent cell. */
+export interface RetryOptions {
+    /** Attempts in all, the first included (default 3; 1 never retries). */
+    attempts?: number;
+    /** The wait before the second attempt, in ms (default 1000); it doubles each time, with jitter of +-50%. */
+    delayMs?: number;
+}
+export declare const DEFAULT_RETRY: Readonly<Required<RetryOptions>>;
+/**
+ * Runs `build` (which builds and sends a transaction). If the node definitely
+ * refused it because an input was already spent (`Dead`, `Unknown`, or an RBF
+ * refusal for a conflict in its pool), or `build` sent nothing because every
+ * payout cell was busy ("payout-busy"), clears the client's cache, waits, and
+ * runs it again, up to `retry.attempts` in all (audit, 31 Oct; mentor review,
+ * 2 Nov). `build` is given the out points rejections named, so a payout cell
+ * the node called spent is not picked again. The wait is `retry.delayMs`,
+ * doubling each time, times a random 0.5 to 1.5, so payers that collided do
+ * not retry in step.
+ *
+ * Any other error is thrown at once. That includes a send whose outcome is
+ * unknown (a timeout, a lost reply): `signAndSend` returns the hash when the
+ * node did take the transaction, and otherwise throws the send's own error,
+ * which is never retried, so nothing is ever paid twice. When the node cannot
+ * be asked either, a refusal for a spent input may only mean the first send
+ * committed (CCC retries a send on a fallback node): `signAndSend` then throws
+ * `SendOutcomeUnknownError`, never retried (review W6 L4). A `beforeSend` inside
+ * runs again with each new transaction's hash: a refused one never commits.
+ */
+export declare function rebuildOnDeadInputs<T>(client: ccc.Client, build: (avoid: ReadonlySet<string>) => Promise<T>, retry?: RetryOptions): Promise<T>;
 export declare function findSessionCells(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<SessionCells>;
 /**
  * The recipient the session lock will enforce, taken from the session's own scope
@@ -65,24 +209,56 @@ export declare function findSessionCells(session: Session, client: ccc.Client, d
  * scope listing several cannot be enforced on-chain and is refused.
  */
 export declare function onchainRecipient(session: Session): string | undefined;
+/** Options for {@link assertSigningLock}. */
+export type SigningLockOptions = {
+    /**
+     * Let a lock this kit has not reviewed own a session, with a `console.warn`.
+     * Use it only after checking yourself that the lock cannot be unlocked without
+     * the owner's signature. A lock known to unlock without it is refused anyway
+     * (the deployed anyone-can-pay, PW-Lock and always-success code, under any
+     * hash_type; see `assertSigningLock`).
+     */
+    allowUnreviewedOwnerLock?: boolean;
+};
 /**
- * Throws unless `lock` is known to need a signature over the whole transaction:
- * the session lock grants owner mode to any transaction with an input under the
- * owner's lock, so that lock is the only thing standing between a stranger and
- * every session. An allowlist, not a blocklist (code review, 14 Oct):
+ * Throws `SessionPolicyError` unless `lock` is a reviewed configuration of a lock
+ * that needs the owner's signature over the whole transaction. The session lock
+ * grants owner mode to any transaction with an input under the owner's lock, so
+ * that lock is the only thing standing between a stranger and every session.
+ * An allowlist, not a blocklist (code review, 14 Oct; mentor review, 2 Nov):
+ *
+ * Reviewed, accepted:
+ * - secp256k1-blake160 (20-byte args); secp256k1 multisig, v1 and v2 (20 bytes,
+ *   or 28 with a since, which only delays);
+ * - Omnilock with a signature auth flag (0x00-0x06: CKB, Ethereum, EOS, Tron,
+ *   Bitcoin, Dogecoin, multisig; 0x12: Ethereum with the message displayed), and
+ *   no mode other than time-lock or supply;
+ * - Nostr lock in signing mode (args[0] = 0, 21-byte args);
+ * - JoyID (closed source: reviewed from its documentation only).
  *
- * - secp256k1-blake160 (single or multisig), JoyID, Nostr, PW lock;
- * - Omnilock with a signature auth flag (0x00-0x07: CKB, Ethereum, EOS, Tron,
- *   Bitcoin, Dogecoin, multisig; 0x12: Ethereum with the message displayed) and neither administrator (0x01) nor
- *   anyone-can-pay (0x02) mode. Auth flags 0xFC-0xFE hand the decision to
- *   another lock or to arbitrary code, and are refused.
+ * Known to unlock without the owner's signature, refused always (reason
+ * `"owner-lock-unsafe"`): anyone-can-pay, PW-Lock, always-success (by their
+ * type id, or by the data hash of their deployed binaries under any data
+ * hash_type), Omnilock in anyone-can-pay or administrator mode, Nostr lock in
+ * PoW mode (args[0] != 0). Another build of those locks (a binary with a
+ * different data hash) is not recognised: it is refused as unreviewed.
  *
- * Anyone-can-pay (RFC 0026) unlocks with no signature at all: anyone could spend
- * the owner's cell back to itself unchanged and sweep every session.
+ * Anything else (Omnilock auth 0xFC-0xFE, which hand the decision to another lock
+ * or to other code; the proxy locks; unknown locks; args the lock's code would
+ * not accept) is refused with reason `"owner-lock-unreviewed"`, unless
+ * `allowUnreviewedOwnerLock` is set: then it passes with a warning.
  *
  * The owner must also never sign a partial (open) transaction with this lock.
  */
-export declare function assertSigningLock(lock: ccc.Script, client: ccc.Client): Promise<void>;
+export declare function assertSigningLock(lock: ccc.Script, client: ccc.Client, opts?: SigningLockOptions): Promise<void>;
+/** Whose lock `checkSigningLock` checks, for its messages, and the opt-in that lets an unreviewed one through. */
+export type SigningRole = {
+    whose: string;
+    can: string;
+    optIn: string;
+};
+/** `assertSigningLock` for any role: a subscription's charger lock is checked the same way (review M2), with its own opt-in. */
+export declare function checkSigningLock(lock: ccc.Script, client: ccc.Client, allowUnreviewed: boolean, role: SigningRole): Promise<void>;
 /**
  * Owner funds the session: one transaction, one signature from `owner`.
  * The on-chain recipient comes from `session.policy.scope.recipients`.
@@ -107,7 +283,12 @@ export declare function openSession(owner: ccc.Signer, session: Session, deploym
         maxPerTx: bigint;
     };
     beforeSend?: (binding: OnChainBinding) => Promise<void>;
-}): Promise<{
+    /**
+     * Called before anything is signed, once per `SessionWarning`; throw to stop the
+     * opening. Without it, warnings go to `console.warn`.
+     */
+    onWarning?: (warning: SessionWarning) => void | Promise<void>;
+} & SigningLockOptions): Promise<{
     txHash: ccc.Hex;
     binding: OnChainBinding;
 }>;
@@ -118,6 +299,13 @@ export declare function openSession(owner: ccc.Signer, session: Session, deploym
  * widens who may mint (owner mode by input or output type, code review 14 Oct).
  */
 export declare function assertPlainXudt(type: ccc.Script, client: ccc.Client): Promise<void>;
+/** The network's xUDT code: what `client.getKnownScript(ccc.KnownScript.XUdt)` returns. */
+type XudtCode = {
+    codeHash: ccc.Hex;
+    hashType: ccc.HashType;
+};
+/** Why `type` is not a plain xUDT under the network's xUDT script `xudt`, or undefined if it is. */
+export declare function plainXudtFault(type: ccc.Script, xudt: XudtCode): string | undefined;
 /**
  * The session key pays `to`: `amount` shannons, or in a token session `token`
  * units of its xUDT. The scope is checked here first, then the network checks it
@@ -135,22 +323,40 @@ export declare function assertPlainXudt(type: ccc.Script, client: ccc.Client): P
  *
  * `memo` is recorded in the witness of the session key's own input, which that
  * key's signature covers: the payment commits to it (see `verifyAccess`).
+ *
+ * With `topUp`, the recipient's cell is a confirmed one that no transaction in
+ * the node's pool spends, where the node can tell (`pickPayoutCell`): readers
+ * paying at the same moment compete for those cells.
+ *
+ * If the node rejects the payment because an input is already spent (another
+ * tab, device or payer took it first) or unknown, the client's cache is cleared
+ * and the payment is built again from the live cells, with another payout
+ * cell, after a short wait: up to `retry.attempts` in all (default 3), waiting
+ * `retry.delayMs` (default 1000) doubling each time. `beforeSend` runs again
+ * with each new hash (`rebuildOnDeadInputs`). A send whose outcome is unknown
+ * is never retried.
  */
-export declare function spendInSession(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding, request: {
+export declare function spendInSession(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding, request: SpendRequest, now?: Date): Promise<ccc.Hex>;
+type SpendCommon = {
     to: string;
-    amount: bigint;
-    token?: undefined;
     topUp?: boolean;
     memo?: ccc.HexLike;
     beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+    retry?: RetryOptions;
+};
+type SpendRequest = SpendCommon & ({
+    amount: bigint;
+    token?: undefined;
 } | {
-    to: string;
     token: bigint;
     amount?: undefined;
-    topUp?: boolean;
-    memo?: ccc.HexLike;
-    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
-}, now?: Date): Promise<ccc.Hex>;
+});
+/**
+ * `completeFeeChangeToOutput` into the last output, with CCC's "Insufficient CKB"
+ * (the paying cell holds its floor but not the fee too) as a
+ * `SessionBalanceError` with reason `no-fee-cell` (audit round 2, 31 Oct).
+ */
+export declare function completeFeeOrNoFeeCell(tx: ccc.Transaction, signer: ccc.Signer, message: string): Promise<void>;
 /** The cells created at least `blocks` blocks before the tip: those a relative `since` of `blocks` can spend. */
 export declare function matureCells(client: ccc.Client, cells: ccc.Cell[], blocks: bigint): Promise<ccc.Cell[]>;
 /**
@@ -162,9 +368,16 @@ export declare function matureCells(client: ccc.Client, cells: ccc.Cell[], block
  * it. A key-cell failure is reported in `keyError`; the key stays usable for a retry.
  *
  * `nothingFound` means no cell is left under the session or the key: the key can
- * be forgotten. If the funding transaction (`binding.openTx`) is still in flight
- * or not yet indexed, this throws instead, so the key is never forgotten before
- * the funds it controls arrive.
+ * be forgotten. If the funding transaction (`binding.openTx`) is still in flight,
+ * or committed with an output under the session or the key the node still holds
+ * live (not indexed yet), this throws instead, so the key is never forgotten
+ * before the funds it controls arrive. Once the funding is committed and every
+ * one of those outputs is spent (a close whose reply was lost, another tab's
+ * close), it is `nothingFound` (audit, 31 Oct).
+ *
+ * `owner` must be the wallet that opened the session (its lock is
+ * `binding.ownerLock`): any other is refused with a `SessionPolicyError` before
+ * it is asked to sign anything.
  */
 export declare function closeSession(owner: ccc.Signer, session: Session, deployment: SessionLockDeployment, binding: OnChainBinding): Promise<{
     keyTx?: ccc.Hex;
@@ -180,7 +393,9 @@ export declare function closeSession(owner: ccc.Signer, session: Session, deploy
  * for a token session) are kept: a cell with malformed args would fail the lock
  * even in owner mode, and anyone can create one with this owner's hash as a prefix
  * to block a sweep. Likewise a typed cell is kept only if it holds the session's
- * own token in well-formed data; anything else could make the sweep fail.
+ * own token, a plain xUDT, in exactly 16 bytes of data; anything else could make
+ * the sweep fail. Cells
+ * whose tokens would overflow a u128 together are left out (`withinU128`).
  *
  * Pass several deployments (`[TESTNET_DEPLOYMENT, ...TESTNET_LEGACY_DEPLOYMENTS]`)
  * to find sessions opened under earlier versions of the lock as well.
@@ -192,9 +407,10 @@ export declare function findOwnedSessionCells(owner: ccc.Signer, deployments: Se
  *
  * Anyone can create a cell under a session lock carrying this owner's hash and
  * their own key, and spend it before the sweep lands, which would make a single
- * sweep fail. So if the one transaction is refused, each session (cells sharing a
- * session key) is swept on its own, one signature each: a cell someone else can
- * spend fails alone, and `failed` counts the sessions not recovered.
+ * sweep fail. So if the one transaction is refused, each session (cells under one
+ * session lock) is swept on its own, one signature each: a cell someone else can
+ * spend fails alone, and `failed` counts the sessions not recovered. A fault no
+ * retry can fix (the owner holds no plain cell to prove ownership) is thrown.
  *
  * The key cell (the fee budget) is under the session key's own lock and cannot be
  * recovered without that key; keep it small.
@@ -208,5 +424,28 @@ export declare function recoverSessions(owner: ccc.Signer, deployments: SessionL
 /**
  * Spends `cells` in owner mode: everything returns to the owner. Tokens go back
  * in one cell per token type (xUDT would let a sweep burn them otherwise).
+ * `memo` goes in the witness (`input_type`) of the owner's own input, which the
+ * owner's signature covers: what the sweep is for (`CLEAR_PLANTED_MEMO`).
  */
-export declare function ownerSweep(owner: ccc.Signer, deployments: SessionLockDeployment | SessionLockDeployment[], cells: ccc.Cell[]): Promise<ccc.Hex>;
+export declare function ownerSweep(owner: ccc.Signer, deployments: SessionLockDeployment | SessionLockDeployment[], cells: ccc.Cell[], opts?: {
+    memo?: ccc.Hex;
+}): Promise<ccc.Hex>;
+/**
+ * Gives an anyone-can-pay address (a creator's `payTo`) `count` more cells to be
+ * topped up, paid by `funder`, in one transaction. Each top-up consumes one of
+ * these cells, so readers paying at the same moment compete for them; with more
+ * cells they rarely pick the same one (mentor review, 2 Nov). Anyone can be the
+ * funder: the anyone-can-pay lock needs no signature to receive a new cell.
+ *
+ * Each cell is as small as a cell under `payTo` can be (61 CKB for a 20-byte
+ * args address) unless `capacity` is given. With `token`, each is a cell of that
+ * token holding 0 units (about 142 CKB), for token payments. `count` is 1 to
+ * `MAX_PAYOUT_CELLS`: a payment reads no more than that many.
+ */
+export declare function createPayoutCells(funder: ccc.Signer, payTo: string, opts: {
+    count: number;
+    capacity?: bigint;
+    token?: ccc.ScriptLike;
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+}): Promise<ccc.Hex>;
+export {};