ckb-session-kit 2.0.0 → 2.2.0

package/dist/confirmations.d.ts

@@ -0,0 +1,46 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * Confirmation depth for the checks that accept a payment as proof of access
+ * (`verifyAccess`, `verifySubscription`, `subscriptionStatus`).
+ *
+ * Counting: a transaction in block `b` has `tip - b + 1` confirmations when the
+ * tip is block `tip`. The block that includes it is the first confirmation, as
+ * in the usual (Bitcoin) count; a payment in the tip block has 1.
+ * `minConfirmations` 0 (the default) checks no depth at all: committed is
+ * enough, exactly as before the option existed, and nothing more is fetched.
+ * 1 is the same depth as 0 plus the main-chain check below.
+ *
+ * A payment with enough confirmations must also still be on the main chain: the
+ * node's header at its block number must be the block the node said holds it
+ * (read without CCC's cache). Otherwise it is not counted (`"reorged"`).
+ */
+/** The largest `minConfirmations` accepted: about a day of CKB blocks. Anything past it is taken for a mistake. */
+export declare const MAX_MIN_CONFIRMATIONS = 10000;
+/** Why a payment that is otherwise valid does not count yet, or no longer counts. */
+export type ConfirmationFault = {
+    ok: false;
+    /** Committed, but not yet `minConfirmations` deep: ask again later. */
+    code: "unconfirmed";
+    reason: string;
+    /** `tip - block + 1`, or 0 when the node gave no block (or a block past the tip read). */
+    confirmations: bigint;
+    minConfirmations: bigint;
+} | {
+    ok: false;
+    /** Its block is no longer on the main chain: not counted. */
+    code: "reorged";
+    reason: string;
+};
+/** `minConfirmations` checked: a non-negative integer up to `MAX_MIN_CONFIRMATIONS`; undefined is 0. */
+export declare function minConfirmationsFrom(value: unknown): bigint;
+/** Confirmations of a transaction in block `block` with the tip at `tip`: `tip - block + 1`, never below 0. */
+export declare const confirmationsAt: (tip: bigint, block: bigint) => bigint;
+/**
+ * Why the committed transaction `res` (from `getTransactionNoCache`) does not
+ * count at `minConfirmations` with the tip at `tip`; undefined when it does.
+ * `what` names it in the reason ("payment", "the opening", …).
+ */
+export declare function confirmationFault(client: ccc.Client, tip: bigint, res: {
+    blockNumber?: ccc.NumLike | null;
+    blockHash?: ccc.HexLike | null;
+}, minConfirmations: bigint, what: string): Promise<ConfirmationFault | undefined>;

package/dist/confirmations.js

@@ -0,0 +1,58 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * Confirmation depth for the checks that accept a payment as proof of access
+ * (`verifyAccess`, `verifySubscription`, `subscriptionStatus`).
+ *
+ * Counting: a transaction in block `b` has `tip - b + 1` confirmations when the
+ * tip is block `tip`. The block that includes it is the first confirmation, as
+ * in the usual (Bitcoin) count; a payment in the tip block has 1.
+ * `minConfirmations` 0 (the default) checks no depth at all: committed is
+ * enough, exactly as before the option existed, and nothing more is fetched.
+ * 1 is the same depth as 0 plus the main-chain check below.
+ *
+ * A payment with enough confirmations must also still be on the main chain: the
+ * node's header at its block number must be the block the node said holds it
+ * (read without CCC's cache). Otherwise it is not counted (`"reorged"`).
+ */
+/** The largest `minConfirmations` accepted: about a day of CKB blocks. Anything past it is taken for a mistake. */
+export const MAX_MIN_CONFIRMATIONS = 10_000;
+/** `minConfirmations` checked: a non-negative integer up to `MAX_MIN_CONFIRMATIONS`; undefined is 0. */
+export function minConfirmationsFrom(value) {
+    if (value === undefined)
+        return 0n;
+    const ok = (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= MAX_MIN_CONFIRMATIONS) ||
+        (typeof value === "bigint" && value >= 0n && value <= BigInt(MAX_MIN_CONFIRMATIONS));
+    if (!ok) {
+        throw new RangeError(`minConfirmations must be an integer from 0 to ${MAX_MIN_CONFIRMATIONS}, got ${String(value)}`);
+    }
+    return BigInt(value);
+}
+/** Confirmations of a transaction in block `block` with the tip at `tip`: `tip - block + 1`, never below 0. */
+export const confirmationsAt = (tip, block) => (tip >= block ? tip - block + 1n : 0n);
+/**
+ * Why the committed transaction `res` (from `getTransactionNoCache`) does not
+ * count at `minConfirmations` with the tip at `tip`; undefined when it does.
+ * `what` names it in the reason ("payment", "the opening", …).
+ */
+export async function confirmationFault(client, tip, res, minConfirmations, what) {
+    if (minConfirmations === 0n)
+        return undefined;
+    const known = res.blockNumber !== undefined && res.blockNumber !== null && res.blockHash !== undefined && res.blockHash !== null;
+    const block = known ? ccc.numFrom(res.blockNumber) : undefined;
+    const confirmations = block === undefined ? 0n : confirmationsAt(tip, block);
+    if (confirmations < minConfirmations) {
+        return {
+            ok: false,
+            code: "unconfirmed",
+            reason: `${what} has ${confirmations} of ${minConfirmations} confirmations`,
+            confirmations,
+            minConfirmations,
+        };
+    }
+    // The node's main chain now, not CCC's header cache.
+    const header = await client.getHeaderByNumberNoCache(block);
+    if (!header || header.hash !== ccc.hexFrom(res.blockHash)) {
+        return { ok: false, code: "reorged", reason: `${what}'s block is no longer on the main chain` };
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -6,11 +6,13 @@ export { ScopeError, sendInScope, sessionAddress, sessionSigner } from "./transf
 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 { 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 { assertPlainXudt, assertSigningLock, checkOwnerLockBuild, closeSession, createPayoutCells, DEFAULT_FUND_FEE_RATE, DEFAULT_RETRY, deadInputs, findOwnedSessionCells, findSessionCells, fundInSession, keyLockOf, matureCells, MAX_PAYOUT_CELLS, MAX_POOL_CHECKS, onchainRecipient, openSession, pickPayoutCell, poolConflict, recoverSessions, REVIEWED_OWNER_LOCK_BUILDS, SendOutcomeUnknownError, sendWithSession, SessionBalanceError, sessionLockOf, spendInSession, tokenAmount, } from "./onchain.js";
+export type { FundedTransaction, FundOptions, OnChainBinding, OwnerLockBuild, RetryOptions, SendWithSessionOptions, 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";
+export { MAX_MIN_CONFIRMATIONS } from "./confirmations.js";
+export type { ConfirmationFault } from "./confirmations.js";
 export { applyPlacements, checkPlacement, decodePlacement, encodePlacement, PLACE_BOARD, placementMemo, placementPrice, PlaceMemoError, } from "./place.js";
 export type { BoardState, Pixel, PlaceBoard, PlacedPixel, Placement, PlacementCheck } from "./place.js";

package/dist/index.js

@@ -3,7 +3,8 @@ export { deserializeSession, indexedDbStore, memoryStore, serializeSession, Sess
 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 { 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 { assertPlainXudt, assertSigningLock, checkOwnerLockBuild, closeSession, createPayoutCells, DEFAULT_FUND_FEE_RATE, DEFAULT_RETRY, deadInputs, findOwnedSessionCells, findSessionCells, fundInSession, keyLockOf, matureCells, MAX_PAYOUT_CELLS, MAX_POOL_CHECKS, onchainRecipient, openSession, pickPayoutCell, poolConflict, recoverSessions, REVIEWED_OWNER_LOCK_BUILDS, SendOutcomeUnknownError, sendWithSession, 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 { MAX_MIN_CONFIRMATIONS } from "./confirmations.js";
 export { applyPlacements, checkPlacement, decodePlacement, encodePlacement, PLACE_BOARD, placementMemo, placementPrice, PlaceMemoError, } from "./place.js";

package/dist/onchain.d.ts

@@ -60,10 +60,18 @@ export declare class SessionBalanceError extends Error {
  *   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.
+ * - `owner-lock-build-unreviewed`: the owner's lock is Omnilock, JoyID or the
+ *   Nostr lock under its type id, and its live code cell is not a build listed
+ *   in `REVIEWED_OWNER_LOCK_BUILDS` (`dataHash` is what it runs now). The
+ *   deployer may have upgraded it; the opening is not refused.
+ * - `owner-lock-build-unresolved`: the same locks, but the code cell could not be
+ *   read, so the build was not checked.
  */
 export interface SessionWarning {
-    code: "no-rate-limit";
+    code: "no-rate-limit" | "owner-lock-build-unreviewed" | "owner-lock-build-unresolved";
     message: string;
+    /** With `"owner-lock-build-unreviewed"`: the data hash of the owner lock's live code cell. */
+    dataHash?: ccc.Hex;
 }
 /**
  * The smallest key cell that can still be returned to the owner: a cell under the
@@ -259,6 +267,40 @@ export type SigningRole = {
 };
 /** `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>;
+/** A build of a type-id owner lock: the data hash (ckb blake2b) of its code cell. */
+export type OwnerLockBuild = {
+    lock: "Omnilock" | "JoyID" | "Nostr lock";
+    network: "mainnet" | "testnet";
+    /** The type-id code hash owner locks reference (hash_type `type`). */
+    codeHash: ccc.Hex;
+    /** `ccc.hashCkb` of the code cell's data. */
+    dataHash: ccc.Hex;
+    /** What was checked, and when. */
+    review: string;
+};
+/**
+ * The builds of the type-id owner locks this kit has looked at. An owner lock
+ * hash binds the type id, not the binary, so the deployer can replace the code
+ * under every lock at once. `openSession` and `openSubscription` read the live
+ * code cell and warn (`"owner-lock-build-unreviewed"`) when its data hash is not
+ * listed here; they do not refuse. Data hashes read from the live code cells
+ * (resolved by type id, as CCC resolves them) on 7 Nov 2026.
+ */
+export declare const REVIEWED_OWNER_LOCK_BUILDS: readonly OwnerLockBuild[];
+/**
+ * For an owner lock that is Omnilock, JoyID or the Nostr lock referenced by type
+ * id: reads its live code cell and returns a warning unless the cell's data hash
+ * is in `reviewed` (default `REVIEWED_OWNER_LOCK_BUILDS`). `undefined` for every other lock (secp256k1,
+ * multisig, and any lock referenced by data hash, which already binds the binary).
+ *
+ * Never throws: if the code cell cannot be read (RPC error, or no live cell),
+ * the warning is `"owner-lock-build-unresolved"`. The pin is advisory, so a
+ * failed read cannot be stricter than an unknown build; and a client that cannot
+ * read cells will fail later in the opening anyway.
+ */
+export declare function checkOwnerLockBuild(lockLike: ccc.ScriptLike, client: ccc.Client, reviewed?: readonly OwnerLockBuild[]): Promise<SessionWarning | undefined>;
+/** Reports `checkOwnerLockBuild`'s warning, if any, to `onWarning` or `console.warn` (internal; not exported from the package). */
+export declare function warnOwnerLockBuild(lock: ccc.Script, client: ccc.Client, onWarning?: (warning: SessionWarning) => void | Promise<void>): Promise<void>;
 /**
  * Owner funds the session: one transaction, one signature from `owner`.
  * The on-chain recipient comes from `session.policy.scope.recipients`.
@@ -351,12 +393,99 @@ type SpendRequest = SpendCommon & ({
     token: bigint;
     amount?: undefined;
 });
+/**
+ * The fee rate `fundInSession` and `sendWithSession` use when none is given, in
+ * shannons per 1000 bytes (twice the usual testnet minimum). `sendWithSession` keeps the
+ * same rate on every attempt (see there).
+ */
+export declare const DEFAULT_FUND_FEE_RATE = 2000n;
+/** Options for {@link fundInSession}. */
+export interface FundOptions {
+    /** Shannons per 1000 bytes (default `DEFAULT_FUND_FEE_RATE`). The key cell pays it. */
+    feeRate?: ccc.NumLike;
+    /**
+     * The app's own policy on the finished transaction (which outputs it may hold),
+     * run last, before anything is signed: throw to refuse it. It guards against
+     * app bugs; a leaked key is bounded by the lock, not by this.
+     */
+    check?: (tx: ccc.Transaction) => void | Promise<void>;
+    now?: Date;
+    /** Out points (as `ccc.hexFrom(outPoint.toBytes())`) of session or key cells not to take. */
+    avoid?: ReadonlySet<string>;
+}
+/** What {@link fundInSession} returns. */
+export interface FundedTransaction {
+    /** The app's transaction with the session's inputs and outputs added, unsigned. */
+    tx: ccc.Transaction;
+    /** Shannons leaving the session cells (session inputs less change): what the lock holds to `maxPerTx`. */
+    outflow: bigint;
+    /** The inputs the kit added: session cells, then the key cell (and any key cell CCC added for the fee). */
+    sessionInputs: ccc.OutPoint[];
+}
+/**
+ * Funds a transaction the app built (its own inputs, typed outputs, cell deps
+ * and witnesses) from the session: adds session cells as inputs, at most one
+ * plain change cell under the session lock, and the key cell, which comes back
+ * as the last output and pays the fee. Signs nothing; `sendWithSession` signs
+ * and sends. The checks follow the order the session lock makes them, so a
+ * transaction this returns is one the lock accepts:
+ *
+ * 1. The session is active, and has no on-chain recipient: a recipient-scoped
+ *    session can only pay that recipient and the owner, never a typed output
+ *    (lock errors 13 and 18), so it is refused (`SessionPolicyError`,
+ *    "session-has-recipient").
+ * 2. No input of the app's is under the owner's lock: the lock would run in owner
+ *    mode, and the wallet would have to sign ("owner-lock-input"). None is under
+ *    the session lock or the key's lock, and no output is either: the kit adds
+ *    those ("app-tx-shape").
+ * 3. Need = the outputs' capacity less the app inputs'. Over `maxPerTx`, a
+ *    `ScopeError` before anything is looked up. Session cells are taken (plain
+ *    ones only, mature ones under a rate limit, with `since` set), and change
+ *    is either none or at least a session cell's size (121 CKB for 80-byte args).
+ * 4. The key cell: the largest, in last, out last; the fee (`feeRate`) comes out
+ *    of it, so the fee never counts as outflow.
+ * 5. outflow = session inputs less change, checked against `maxPerTx` again;
+ *    then `opts.check`.
+ *
+ * The app's inputs, witnesses and cell deps stay where they are; the kit's
+ * inputs go after them. `tx` itself is not changed.
+ */
+export declare function fundInSession(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding, txLike: ccc.TransactionLike, opts?: FundOptions): Promise<FundedTransaction>;
+/** Options for {@link sendWithSession}. */
+export interface SendWithSessionOptions extends Omit<FundOptions, "avoid"> {
+    /** Runs with the signed transaction's hash before it is sent, on every attempt (see `signAndSend`). */
+    beforeSend?: (txHash: ccc.Hex) => Promise<void>;
+    /** Attempts and backoff for a refusal naming one of the session's own cells (default `DEFAULT_RETRY`). */
+    retry?: RetryOptions;
+}
+/**
+ * Builds the app's transaction (`build`), funds it from the session
+ * (`fundInSession`), signs it with the session key alone and sends it. No
+ * wallet is involved: the key signs only its own cell, and the session lock
+ * checks no signature. Returns the transaction hash.
+ *
+ * Retries only when the node refuses the transaction for one of the session's
+ * own cells (`Dead` or `Unknown` naming a session or key cell this attempt
+ * added: another tab spent it). Then the client's cache is cleared, that cell
+ * is left out, and `build` runs again, with the backoff of `rebuildOnDeadInputs`.
+ *
+ * Any other refusal is thrown unchanged, for the app's own loop: a dead input of
+ * the app's (another user took the cell the app built on, such as a
+ * crowdfunding campaign cell; `deadInputs(e)` is true) or an RBF refusal
+ * (`poolConflict(e)`), which names no cell. The app waits for its cell to move
+ * and calls again. A send whose outcome is unknown is never retried.
+ *
+ * The fee rate is the same on every attempt (`feeRate`, default
+ * `DEFAULT_FUND_FEE_RATE`): a retry at a higher rate could replace (RBF)
+ * another user's pending transaction on the same app cell.
+ */
+export declare function sendWithSession(session: Session, client: ccc.Client, deployment: SessionLockDeployment, binding: OnChainBinding, build: () => Promise<ccc.TransactionLike>, opts?: SendWithSessionOptions): 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>;
+export declare function completeFeeOrNoFeeCell(tx: ccc.Transaction, signer: ccc.Signer, message: string, feeRate?: ccc.NumLike): 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[]>;
 /**

package/dist/onchain.js

@@ -569,6 +569,130 @@ export async function checkSigningLock(lock, client, allowUnreviewed, role) {
         return;
     return unreviewed("is not one this kit has reviewed: it may open without the owner's signature");
 }
+/**
+ * The builds of the type-id owner locks this kit has looked at. An owner lock
+ * hash binds the type id, not the binary, so the deployer can replace the code
+ * under every lock at once. `openSession` and `openSubscription` read the live
+ * code cell and warn (`"owner-lock-build-unreviewed"`) when its data hash is not
+ * listed here; they do not refuse. Data hashes read from the live code cells
+ * (resolved by type id, as CCC resolves them) on 7 Nov 2026.
+ */
+export const REVIEWED_OWNER_LOCK_BUILDS = Object.freeze([
+    {
+        lock: "Omnilock",
+        network: "mainnet",
+        codeHash: "0x9b819793a64463aed77c615d6cb226eea5487ccfc0783043a587254cda2b6f26",
+        dataHash: "0x768f306681da232ceb0b94f436c5f813377179762a831c5ad8797bd4fd2d118d",
+        review: "source: nervosnetwork/omnilock cd764d7, whose tests pin this hash; reviewed 5 Nov 2026",
+    },
+    {
+        lock: "JoyID",
+        network: "mainnet",
+        codeHash: "0xd00c84f0ec8fd441c38bc3f87a371f547190f2fcff88e642bc5bf54b9e318323",
+        dataHash: "0x4af7d832e7c328aa4ad6f2deb669743446aea7b9a2f0c25646897501ac4f1ebe",
+        review: "closed source: documentation and a string scan of this binary only; reviewed 5 Nov 2026",
+    },
+    {
+        lock: "Nostr lock",
+        network: "mainnet",
+        codeHash: "0x641a89ad2f77721b803cd50d01351c1f308444072d5fa20088567196c0574c68",
+        dataHash: "0x2effea19ff3024b5b0fb4c0c59c379e7610110e7e3fe7ae003247b1115e59795",
+        review: "source: cryptape/nostr-binding eef134e (strings consistent, not rebuilt); reviewed 5 Nov 2026",
+    },
+    {
+        lock: "Omnilock",
+        network: "testnet",
+        codeHash: "0xf329effd1c475a2978453c8600e1eaf0bc2087ee093c3ee64cc96ec6847752cb",
+        dataHash: "0x6b29b6f10346b43c540e53806ba88ba0fe3a0c3a29d7448ef555840c8f8318fa",
+        review: "the build live on testnet when read on 7 Nov 2026; its source is not identified (testnet funds only)",
+    },
+    {
+        lock: "JoyID",
+        network: "testnet",
+        codeHash: "0xd23761b364210735c19c60561d213fb3beae2fd6172743719eff6920e020baac",
+        dataHash: "0xd2c0f2f621a337007e046f0ed65f8fe29112c32a00ea1e43c2f8059fd42ca6d7",
+        review: "the build live on testnet when read on 7 Nov 2026, a different binary from mainnet; not examined, documentation review only",
+    },
+    {
+        lock: "Nostr lock",
+        network: "testnet",
+        codeHash: "0x6ae5ee0cb887b2df5a9a18137315b9bdc55be8d52637b2de0624092d5f0c91d5",
+        dataHash: "0x2effea19ff3024b5b0fb4c0c59c379e7610110e7e3fe7ae003247b1115e59795",
+        review: "the same binary as the mainnet Nostr lock",
+    },
+]);
+const BUILD_PINNED = [
+    [ccc.KnownScript.OmniLock, "Omnilock"],
+    [ccc.KnownScript.JoyId, "JoyID"],
+    [ccc.KnownScript.NostrLock, "Nostr lock"],
+];
+/**
+ * For an owner lock that is Omnilock, JoyID or the Nostr lock referenced by type
+ * id: reads its live code cell and returns a warning unless the cell's data hash
+ * is in `reviewed` (default `REVIEWED_OWNER_LOCK_BUILDS`). `undefined` for every other lock (secp256k1,
+ * multisig, and any lock referenced by data hash, which already binds the binary).
+ *
+ * Never throws: if the code cell cannot be read (RPC error, or no live cell),
+ * the warning is `"owner-lock-build-unresolved"`. The pin is advisory, so a
+ * failed read cannot be stricter than an unknown build; and a client that cannot
+ * read cells will fail later in the opening anyway.
+ */
+export async function checkOwnerLockBuild(lockLike, client, reviewed = REVIEWED_OWNER_LOCK_BUILDS) {
+    const lock = ccc.Script.from(lockLike);
+    if (lock.hashType !== "type")
+        return undefined;
+    let found;
+    for (const [known, name] of BUILD_PINNED) {
+        try {
+            const info = await client.getKnownScript(known);
+            if (info.codeHash === lock.codeHash && info.hashType === "type")
+                found = { info, name };
+        }
+        catch {
+            // not deployed on this network
+        }
+        if (found)
+            break;
+    }
+    if (!found)
+        return undefined;
+    const { info, name } = found;
+    const whose = `the owner's lock (${name}, type id ${lock.codeHash})`;
+    let dataHash;
+    try {
+        const type = info.cellDeps.map((d) => d.type).find((t) => t && t.hash() === lock.codeHash);
+        const cell = type && (await client.findSingletonCellByType(type, true));
+        if (cell && cell.cellOutput.type?.hash() === lock.codeHash)
+            dataHash = ccc.hashCkb(cell.outputData);
+    }
+    catch {
+        dataHash = undefined;
+    }
+    if (!dataHash) {
+        return {
+            code: "owner-lock-build-unresolved",
+            message: `${whose}: its live code cell could not be read, so its build was not checked against the reviewed builds`,
+        };
+    }
+    if (reviewed.some((b) => b.codeHash === lock.codeHash && b.dataHash === dataHash))
+        return undefined;
+    return {
+        code: "owner-lock-build-unreviewed",
+        dataHash,
+        message: `${whose} now runs code with data hash ${dataHash}, not a build this kit has reviewed: ` +
+            "the deployer may have upgraded it. Check that every way to unlock it still signs the whole transaction",
+    };
+}
+/** Reports `checkOwnerLockBuild`'s warning, if any, to `onWarning` or `console.warn` (internal; not exported from the package). */
+export async function warnOwnerLockBuild(lock, client, onWarning) {
+    const w = await checkOwnerLockBuild(lock, client);
+    if (!w)
+        return;
+    if (onWarning)
+        await onWarning(w);
+    else
+        console.warn(`ckb-session-kit: ${w.message}`);
+}
 /**
  * Owner funds the session: one transaction, one signature from `owner`.
  * The on-chain recipient comes from `session.policy.scope.recipients`.
@@ -595,6 +719,7 @@ export async function openSession(owner, session, deployment, opts) {
         relativeBlocksSince(opts.minInterval); // a spend must be able to meet it
     const ownerLock = (await owner.getRecommendedAddressObj()).script;
     await assertSigningLock(ownerLock, client, opts);
+    await warnOwnerLockBuild(ownerLock, client, opts.onWarning);
     const floor = keyCellFloor(ownerLock);
     const feeBudget = opts.feeBudget ?? floor + FEE_MARGIN;
     if (feeBudget <= floor) {
@@ -827,14 +952,194 @@ async function spendOnce(session, client, deployment, binding, request, now, avo
     }
     return signAndSend(sessionSigner(session, client), tx, request.beforeSend);
 }
+/**
+ * The fee rate `fundInSession` and `sendWithSession` use when none is given, in
+ * shannons per 1000 bytes (twice the usual testnet minimum). `sendWithSession` keeps the
+ * same rate on every attempt (see there).
+ */
+export const DEFAULT_FUND_FEE_RATE = 2000n;
+/**
+ * Funds a transaction the app built (its own inputs, typed outputs, cell deps
+ * and witnesses) from the session: adds session cells as inputs, at most one
+ * plain change cell under the session lock, and the key cell, which comes back
+ * as the last output and pays the fee. Signs nothing; `sendWithSession` signs
+ * and sends. The checks follow the order the session lock makes them, so a
+ * transaction this returns is one the lock accepts:
+ *
+ * 1. The session is active, and has no on-chain recipient: a recipient-scoped
+ *    session can only pay that recipient and the owner, never a typed output
+ *    (lock errors 13 and 18), so it is refused (`SessionPolicyError`,
+ *    "session-has-recipient").
+ * 2. No input of the app's is under the owner's lock: the lock would run in owner
+ *    mode, and the wallet would have to sign ("owner-lock-input"). None is under
+ *    the session lock or the key's lock, and no output is either: the kit adds
+ *    those ("app-tx-shape").
+ * 3. Need = the outputs' capacity less the app inputs'. Over `maxPerTx`, a
+ *    `ScopeError` before anything is looked up. Session cells are taken (plain
+ *    ones only, mature ones under a rate limit, with `since` set), and change
+ *    is either none or at least a session cell's size (121 CKB for 80-byte args).
+ * 4. The key cell: the largest, in last, out last; the fee (`feeRate`) comes out
+ *    of it, so the fee never counts as outflow.
+ * 5. outflow = session inputs less change, checked against `maxPerTx` again;
+ *    then `opts.check`.
+ *
+ * The app's inputs, witnesses and cell deps stay where they are; the kit's
+ * inputs go after them. `tx` itself is not changed.
+ */
+export async function fundInSession(session, client, deployment, binding, txLike, opts = {}) {
+    const now = opts.now ?? new Date();
+    if (!isActive(session, now))
+        throw new ScopeError("session expired");
+    if (binding.recipientLockHash) {
+        throw new SessionPolicyError("an app transaction with typed outputs to other locks needs a session without a recipient: " +
+            "this session's lock only lets it pay its recipient and the owner, in plain cells", "session-has-recipient");
+    }
+    const { maxPerTx } = session.policy.scope;
+    const tx = ccc.Transaction.from(txLike).clone();
+    const appInputs = tx.inputs.length;
+    const state = await findSessionCells(session, client, deployment, binding);
+    const ownerHash = ccc.Script.from(binding.ownerLock).hash();
+    const ownHashes = [state.lock.hash(), state.keyLock.hash()];
+    for (const [i, input] of tx.inputs.entries()) {
+        await input.completeExtraInfos(client);
+        const lockHash = input.cellOutput?.lock.hash();
+        if (lockHash === ownerHash) {
+            throw new SessionPolicyError(`input ${i} is under the session owner's lock: the session lock would run in owner mode and ` +
+                "the wallet would have to sign; fund this transaction from the wallet instead", "owner-lock-input");
+        }
+        if (lockHash && ownHashes.includes(lockHash)) {
+            throw new SessionPolicyError(`input ${i} is a session or key cell: fundInSession adds those itself`, "app-tx-shape");
+        }
+    }
+    for (const [i, output] of tx.outputs.entries()) {
+        if (ownHashes.includes(output.lock.hash())) {
+            throw new SessionPolicyError(`output ${i} is under the session lock or the key's lock: fundInSession adds the change and key cells itself`, "app-tx-shape");
+        }
+    }
+    const need = tx.getOutputsCapacity() - (await tx.getInputsCapacity(client));
+    if (need < 0n) {
+        throw new SessionPolicyError(`the app transaction's inputs exceed its outputs by ${ccc.fixedPointToString(-need)} CKB: ` +
+            "give the surplus an output, or it would go to the key cell", "app-tx-shape");
+    }
+    if (need > maxPerTx) {
+        throw new ScopeError(`the transaction needs ${ccc.fixedPointToString(need)} CKB from the session, over maxPerTx ` +
+            `(${ccc.fixedPointToString(maxPerTx)} CKB)`);
+    }
+    const avoid = opts.avoid ?? new Set();
+    const free = (c) => !avoid.has(outPointKey(c.outPoint));
+    const keyCells = state.keyCells.filter(free);
+    if (!keyCells.length)
+        throw new SessionBalanceError("no key cell left to pay fees", "no-fee-cell");
+    // Plain cells only: in a token session the tokens stay where they are.
+    const plain = state.sessionCells.filter((c) => !c.cellOutput.type && free(c));
+    const usable = need > 0n && binding.minInterval > 0n ? await matureCells(client, plain, binding.minInterval) : plain;
+    if (need > 0n && plain.length && !usable.length) {
+        throw new SessionBalanceError(`rate limited: no session cell is ${binding.minInterval} blocks old yet`);
+    }
+    // Change is none, or a whole session cell: take one more cell rather than leave a sliver.
+    const minChange = ccc.CellOutput.from({ lock: state.lock }, "0x").capacity;
+    const taken = [];
+    let ckbIn = 0n;
+    for (const cell of usable) {
+        if (ckbIn >= need && (ckbIn === need || ckbIn - need >= minChange))
+            break;
+        taken.push(cell);
+        ckbIn += cell.cellOutput.capacity;
+    }
+    const balance = plain.reduce((s, c) => s + c.cellOutput.capacity, 0n);
+    if (ckbIn < need) {
+        throw new SessionBalanceError(`session balance ${ccc.fixedPointToString(balance)} CKB is too low: the transaction needs ${ccc.fixedPointToString(need)} CKB`);
+    }
+    const change = ckbIn - need;
+    if (change > 0n && change < minChange) {
+        throw new SessionBalanceError(`the session would keep ${ccc.fixedPointToString(change)} CKB, below the ` +
+            `${ccc.fixedPointToString(minChange)} CKB a session cell needs; spend all of it or less`);
+    }
+    const since = binding.minInterval > 0n ? relativeBlocksSince(binding.minInterval) : 0n;
+    tx.inputs.push(...taken.map((c) => ccc.CellInput.from({ previousOutput: c.outPoint, since })));
+    if (taken.length)
+        tx.addCellDeps(sessionLockCellDep(deployment));
+    if (change > 0n)
+        tx.addOutput({ lock: state.lock, capacity: change }, "0x");
+    // The key cell authorises the spend, comes back last and pays the fee (as in spendOnce).
+    tx.inputs.push(ccc.CellInput.from({ previousOutput: largestCell(keyCells).outPoint }));
+    tx.addOutput({ lock: state.keyLock, capacity: 0n }, "0x");
+    await completeFeeOrNoFeeCell(tx, sessionSigner(session, client), "the key cell cannot cover the fee; top it up", opts.feeRate ?? DEFAULT_FUND_FEE_RATE);
+    if (tx.outputs[tx.outputs.length - 1].capacity < keyCellFloor(binding.ownerLock)) {
+        throw new SessionBalanceError("the key cell cannot cover another fee; top it up", "no-fee-cell");
+    }
+    // The lock's own rules on the result (1: outflow; 3 and 5: one plain change cell).
+    const outflow = taken.reduce((s, c) => s + c.cellOutput.capacity, 0n) - change;
+    if (outflow > maxPerTx) {
+        throw new ScopeError(`outflow ${ccc.fixedPointToString(outflow)} CKB exceeds maxPerTx (${ccc.fixedPointToString(maxPerTx)} CKB)`);
+    }
+    const changeCells = tx.outputs.filter((o) => o.lock.eq(state.lock));
+    if (changeCells.length > 1 || changeCells.some((o) => o.type)) {
+        throw new SessionPolicyError("the session lock allows one plain change cell", "app-tx-shape");
+    }
+    await opts.check?.(tx);
+    return { tx, outflow, sessionInputs: tx.inputs.slice(appInputs).map((i) => i.previousOutput) };
+}
+/**
+ * Builds the app's transaction (`build`), funds it from the session
+ * (`fundInSession`), signs it with the session key alone and sends it. No
+ * wallet is involved: the key signs only its own cell, and the session lock
+ * checks no signature. Returns the transaction hash.
+ *
+ * Retries only when the node refuses the transaction for one of the session's
+ * own cells (`Dead` or `Unknown` naming a session or key cell this attempt
+ * added: another tab spent it). Then the client's cache is cleared, that cell
+ * is left out, and `build` runs again, with the backoff of `rebuildOnDeadInputs`.
+ *
+ * Any other refusal is thrown unchanged, for the app's own loop: a dead input of
+ * the app's (another user took the cell the app built on, such as a
+ * crowdfunding campaign cell; `deadInputs(e)` is true) or an RBF refusal
+ * (`poolConflict(e)`), which names no cell. The app waits for its cell to move
+ * and calls again. A send whose outcome is unknown is never retried.
+ *
+ * The fee rate is the same on every attempt (`feeRate`, default
+ * `DEFAULT_FUND_FEE_RATE`): a retry at a higher rate could replace (RBF)
+ * another user's pending transaction on the same app cell.
+ */
+export async function sendWithSession(session, client, deployment, binding, build, opts = {}) {
+    const attempts = Math.max(1, Math.floor(opts.retry?.attempts ?? DEFAULT_RETRY.attempts));
+    const delay = Math.max(0, opts.retry?.delayMs ?? DEFAULT_RETRY.delayMs);
+    const feeRate = opts.feeRate ?? DEFAULT_FUND_FEE_RATE; // fixed for every attempt
+    const avoid = new Set();
+    for (let attempt = 1;; attempt++) {
+        let ours = new Set();
+        try {
+            const funded = await fundInSession(session, client, deployment, binding, await build(), {
+                feeRate,
+                check: opts.check,
+                now: opts.now,
+                avoid,
+            });
+            ours = new Set(funded.sessionInputs.map(outPointKey));
+            return await signAndSend(sessionSigner(session, client), funded.tx, opts.beforeSend);
+        }
+        catch (e) {
+            const named = e instanceof SendOutcomeUnknownError ? undefined : rejectedOutPoint(e);
+            if (!named || !ours.has(named) || attempt >= attempts)
+                throw e;
+            avoid.add(named);
+            await client.cache?.clear();
+            const wait = delay * 2 ** (attempt - 1) * (0.5 + Math.random());
+            if (wait > 0)
+                await sleep(wait);
+        }
+    }
+}
 /**
  * `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 async function completeFeeOrNoFeeCell(tx, signer, message) {
+export async function completeFeeOrNoFeeCell(tx, signer, message, feeRate) {
     try {
-        await tx.completeFeeChangeToOutput(signer, tx.outputs.length - 1);
+        await (feeRate === undefined
+            ? tx.completeFeeChangeToOutput(signer, tx.outputs.length - 1)
+            : tx.completeFeeChangeToOutput(signer, tx.outputs.length - 1, feeRate));
     }
     catch (e) {
         // By class, or by message where a second copy of CCC threw it (a bundler's CJS and ESM builds).