ckb-session-kit 2.0.0 → 2.2.0

package/dist/paywall.d.ts

@@ -1,5 +1,6 @@
 import { ccc } from "@ckb-ccc/core";
 import type { Session } from "./session.js";
+import { type ConfirmationFault } from "./confirmations.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). */
@@ -46,15 +47,24 @@ export type AccessCheck = {
 } | {
     ok: false;
     reason: string;
-};
+    code?: undefined;
+} | ConfirmationFault;
 /**
  * The server's side. `to` is the recipient that must have been paid, as a lock
  * script; `minAmount` in shannons. With `token` (an xUDT type script), the
  * payment is counted in that token's units instead, and `minAmount` is in units.
+ *
+ * With `minConfirmations` (default 0: committed is enough), a payment that is
+ * valid in every other way but fewer than that many blocks deep (counting its
+ * own block as 1) gives `code: "unconfirmed"` with its `confirmations`, and one
+ * whose block left the main chain `code: "reorged"` (src/confirmations.ts).
+ * Throws a `RangeError` for a `minConfirmations` that is not an integer from 0
+ * to `MAX_MIN_CONFIRMATIONS`.
  */
 export declare function verifyAccess(client: ccc.Client, proof: AccessProof, expect: {
     to: ccc.ScriptLike;
     minAmount: bigint;
     memo: ccc.HexLike;
     token?: ccc.ScriptLike;
+    minConfirmations?: number | bigint;
 }): Promise<AccessCheck>;

package/dist/paywall.js

@@ -1,6 +1,7 @@
 import { ccc } from "@ckb-ccc/core";
 import { tokenAmount } from "./onchain.js";
 import { sessionSigner } from "./transfer.js";
+import { confirmationFault, minConfirmationsFrom } from "./confirmations.js";
 /**
  * Paid access, checked against the chain with no database.
  *
@@ -88,8 +89,16 @@ export async function signAccess(session, txHash, memo) {
  * The server's side. `to` is the recipient that must have been paid, as a lock
  * script; `minAmount` in shannons. With `token` (an xUDT type script), the
  * payment is counted in that token's units instead, and `minAmount` is in units.
+ *
+ * With `minConfirmations` (default 0: committed is enough), a payment that is
+ * valid in every other way but fewer than that many blocks deep (counting its
+ * own block as 1) gives `code: "unconfirmed"` with its `confirmations`, and one
+ * whose block left the main chain `code: "reorged"` (src/confirmations.ts).
+ * Throws a `RangeError` for a `minConfirmations` that is not an integer from 0
+ * to `MAX_MIN_CONFIRMATIONS`.
  */
 export async function verifyAccess(client, proof, expect) {
+    const minConfirmations = minConfirmationsFrom(expect.minConfirmations);
     if (ccc.hexFrom(proof.memo) !== ccc.hexFrom(expect.memo))
         return { ok: false, reason: "memo does not match" };
     // Always the CKB secp256k1 scheme: a sign type chosen by the caller is not trusted.
@@ -171,5 +180,11 @@ export async function verifyAccess(client, proof, expect) {
         const shown = token ? `${paid} units` : `${ccc.fixedPointToString(paid)} CKB`;
         return { ok: false, reason: `paid ${shown}, below the price` };
     }
+    // Depth last: "unconfirmed" then means the payment is good, only too recent.
+    if (minConfirmations > 0n) {
+        const fault = await confirmationFault(client, await client.getTip(), res, minConfirmations, "payment");
+        if (fault)
+            return fault;
+    }
     return { ok: true, paid };
 }

package/dist/session.d.ts

@@ -50,9 +50,14 @@ export interface CreateOptions {
  * 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`).
+ * 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";
+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 {
     readonly reason?: SessionPolicyReason;
     constructor(message: string, reason?: SessionPolicyReason);

package/dist/subscription.d.ts

@@ -1,6 +1,7 @@
 import { ccc } from "@ckb-ccc/core";
 import { type SessionLockDeployment } from "./lock.js";
-import { type SigningLockOptions, type RetryOptions } from "./onchain.js";
+import { type SigningLockOptions, type SessionWarning, type RetryOptions } from "./onchain.js";
+import { type ConfirmationFault } from "./confirmations.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
@@ -126,6 +127,12 @@ export declare function openSubscription(subscriber: ccc.Signer, deployment: Ses
     beforeSend?: (sub: Subscription) => Promise<void>;
     /** Let an unreviewed charger lock through, with a warning (`allowUnreviewedOwnerLock` covers the subscriber's own lock only). */
     allowUnreviewedChargerLock?: boolean;
+    /**
+     * Called before anything is signed with a `SessionWarning` about the
+     * subscriber's lock (`"owner-lock-build-unreviewed"` or
+     * `"owner-lock-build-unresolved"`); throw to stop. Without it, `console.warn`.
+     */
+    onWarning?: (warning: SessionWarning) => void | Promise<void>;
 } & SigningLockOptions): Promise<{
     txHash: ccc.Hex;
     subscription: Subscription;
@@ -233,7 +240,8 @@ export type SubscriptionCheck = {
 } | {
     ok: false;
     reason: string;
-};
+    code?: undefined;
+} | ConfirmationFault;
 /**
  * The creator checks a subscription from the chain alone. Nothing in the request
  * is trusted but the out point. The cell at `outPoint` must be live, under this
@@ -257,6 +265,13 @@ export type SubscriptionCheck = {
  * type hash, `price` in token units as `max_per_tx_token`); `minBalance` is in token
  * units, and the payment counted is token units into `payTo`'s cells of the token.
  * Without `token`, a 160-byte cell is refused, and the reverse.
+ *
+ * With `minConfirmations` (default 0: committed is enough), the creating
+ * transaction must be that many blocks deep, its own block counting as 1: a cell
+ * valid in every other way gives `code: "unconfirmed"` until then, and
+ * `code: "reorged"` if that block left the main chain (src/confirmations.ts).
+ * Throws a `RangeError` for a `minConfirmations` that is not an integer from 0
+ * to `MAX_MIN_CONFIRMATIONS`.
  */
 export declare function verifySubscription(client: ccc.Client, deployment: SessionLockDeployment, outPoint: ccc.OutPointLike, expected: {
     charger: string;
@@ -266,6 +281,7 @@ export declare function verifySubscription(client: ccc.Client, deployment: Sessi
     minBalance?: bigint;
     account?: string;
     token?: ccc.ScriptLike;
+    minConfirmations?: number | bigint;
 }): Promise<SubscriptionCheck>;
 export interface SubscriptionStatus {
     /**
@@ -283,6 +299,11 @@ export interface SubscriptionStatus {
     chargesLeft: bigint;
     /** Blocks until the creator may charge again (0 = now). */
     nextChargeIn: bigint | undefined;
+    /**
+     * With `minConfirmations`: the block a charge still short of that depth will
+     * pay through once it has it, when that is past `paidThroughBlock`. Not access yet.
+     */
+    unconfirmedThroughBlock?: bigint;
 }
 /**
  * Where a subscription stands, for a creator's server that keeps no database:
@@ -298,17 +319,27 @@ export interface SubscriptionStatus {
  * `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.
+ *
+ * With `minConfirmations` (default 0: committed is enough), only payments that
+ * many blocks deep count, their own block counting as 1, and still on the main
+ * chain. An opening short of it gives `code: "unconfirmed"` (or `"reorged"`); a
+ * charge short of it does not extend `paidThroughBlock` yet, and shows in
+ * `unconfirmedThroughBlock`. The tip is read once. Throws a `RangeError` for a
+ * `minConfirmations` that is not an integer from 0 to `MAX_MIN_CONFIRMATIONS`.
  */
 export declare function subscriptionStatus(client: ccc.Client, deployment: SessionLockDeployment, sub: Subscription, proof: {
     openTx: ccc.HexLike;
     account: string;
+}, options?: {
+    minConfirmations?: number | bigint;
 }): Promise<{
     ok: true;
     status: SubscriptionStatus;
 } | {
     ok: false;
     reason: string;
-}>;
+    code?: undefined;
+} | ConfirmationFault>;
 /**
  * About how many blocks `seconds` is, from the average block time over the last
  * `sample` blocks. Block time varies; round up when a period means "no more often than".

package/dist/subscription.js

@@ -1,8 +1,9 @@
 import { ccc } from "@ckb-ccc/core";
 import { relativeBlocksSince, sessionLockCellDep, sessionLockScript, } from "./lock.js";
-import { addTopUp, assertPlainXudt, assertSigningLock, checkSigningLock, isAnyoneCanPay, keyCellFloor, ownerSweep, ownOrigin, plainXudtFault, randomPick, completeFeeOrNoFeeCell, rebuildOnDeadInputs, SessionBalanceError, signAndSend, tokenAmount, tokenData, withoutDeadCached, withinU128, } from "./onchain.js";
+import { addTopUp, assertPlainXudt, assertSigningLock, checkSigningLock, isAnyoneCanPay, keyCellFloor, ownerSweep, ownOrigin, plainXudtFault, randomPick, completeFeeOrNoFeeCell, rebuildOnDeadInputs, SessionBalanceError, signAndSend, tokenAmount, tokenData, warnOwnerLockBuild, withoutDeadCached, withinU128, } from "./onchain.js";
 import { assertCurrentDeployment } from "./deployment.js";
 import { SessionPolicyError } from "./session.js";
+import { confirmationFault, minConfirmationsFrom } from "./confirmations.js";
 const tokenOf = (sub) => sub.token && ccc.Script.from(sub.token.type);
 export function subscriptionLock(deployment, sub) {
     const token = tokenOf(sub);
@@ -297,6 +298,7 @@ export async function openSubscription(subscriber, deployment, opts) {
     }
     const subscriberLock = (await subscriber.getRecommendedAddressObj()).script;
     await assertSigningLock(subscriberLock, client, opts);
+    await warnOwnerLockBuild(subscriberLock, client, opts.onWarning);
     const [chargerLock, payToLock] = await Promise.all([opts.charger, opts.payTo].map(async (a) => (await ccc.Address.fromString(a, client)).script));
     // A charger lock that signs nothing would let anyone trigger charges (review M2). Its own
     // opt-in: opting in for the subscriber's wallet does not waive review of the creator's lock (review W6 I1).
@@ -394,7 +396,9 @@ export async function findSubscriptionCells(client, deployment, sub) {
  * cell's creating transaction and age (undefined while not committed), so a
  * charge or a status fetches each of them once (review, 28 Oct).
  */
-async function subscriptionState(client, deployment, sub) {
+async function subscriptionState(client, deployment, sub, 
+/** The tip, when the caller already read it (one tip per call). */
+knownTip) {
     const lock = subscriptionLock(deployment, sub);
     const token = tokenOf(sub);
     const cells = await subscriptionCells(client, lock, token, MAX_SUBSCRIPTION_CELLS);
@@ -407,7 +411,7 @@ async function subscriptionState(client, deployment, sub) {
             byHash.set(h, client.getTransactionNoCache(h)); // the node's answer, not the cache's
         return byHash.get(h);
     };
-    const [tip, created] = await Promise.all([client.getTip(), Promise.all(cells.map((c) => creating(c.outPoint.txHash)))]);
+    const [tip, created] = await Promise.all([knownTip ?? client.getTip(), Promise.all(cells.map((c) => creating(c.outPoint.txHash)))]);
     const ages = created.map((res) => {
         const born = res?.blockNumber;
         return born === undefined || born === null ? undefined : tip - ccc.numFrom(born);
@@ -712,8 +716,16 @@ function chargesLeftOf(sub, lock, balance, tokenBalance) {
  * type hash, `price` in token units as `max_per_tx_token`); `minBalance` is in token
  * units, and the payment counted is token units into `payTo`'s cells of the token.
  * Without `token`, a 160-byte cell is refused, and the reverse.
+ *
+ * With `minConfirmations` (default 0: committed is enough), the creating
+ * transaction must be that many blocks deep, its own block counting as 1: a cell
+ * valid in every other way gives `code: "unconfirmed"` until then, and
+ * `code: "reorged"` if that block left the main chain (src/confirmations.ts).
+ * Throws a `RangeError` for a `minConfirmations` that is not an integer from 0
+ * to `MAX_MIN_CONFIRMATIONS`.
  */
 export async function verifySubscription(client, deployment, outPoint, expected) {
+    const minConfirmations = minConfirmationsFrom(expected.minConfirmations);
     const cell = await client.getCellLive(outPoint, true, false);
     if (!cell)
         return { ok: false, reason: "no live cell at that out point" };
@@ -795,6 +807,12 @@ export async function verifySubscription(client, deployment, outPoint, expected)
     if (expected.account !== undefined && !commitsToAccount(created, sub, expected.account)) {
         return { ok: false, reason: "the opening does not commit to this account" };
     }
+    // Depth last: "unconfirmed" then means the cell is good, only too recent.
+    if (minConfirmations > 0n) {
+        const fault = await confirmationFault(client, await client.getTip(), { blockNumber: created.block, blockHash: created.blockHash }, minConfirmations, "the transaction that created the cell");
+        if (fault)
+            return fault;
+    }
     return {
         ok: true,
         subscription: sub,
@@ -864,7 +882,7 @@ fetched) {
     const paid = out - amount(toPayTo(inputs.map((c) => ({ cellOutput: c.cellOutput, data: c.outputData }))));
     if (paid < owed)
         return notPaid;
-    return { tx, block: ccc.numFrom(created.blockNumber), inputs };
+    return { tx, block: ccc.numFrom(created.blockNumber), blockHash: created.blockHash, inputs };
 }
 /** Whether `p` carries `subscriptionMemo(account)` in the witness of an input under the subscriber's lock. */
 function commitsToAccount(p, sub, account) {
@@ -885,8 +903,16 @@ function commitsToAccount(p, sub, account) {
  * `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.
+ *
+ * With `minConfirmations` (default 0: committed is enough), only payments that
+ * many blocks deep count, their own block counting as 1, and still on the main
+ * chain. An opening short of it gives `code: "unconfirmed"` (or `"reorged"`); a
+ * charge short of it does not extend `paidThroughBlock` yet, and shows in
+ * `unconfirmedThroughBlock`. The tip is read once. Throws a `RangeError` for a
+ * `minConfirmations` that is not an integer from 0 to `MAX_MIN_CONFIRMATIONS`.
  */
-export async function subscriptionStatus(client, deployment, sub, proof) {
+export async function subscriptionStatus(client, deployment, sub, proof, options = {}) {
+    const minConfirmations = minConfirmationsFrom(options.minConfirmations);
     try {
         assertTerms(sub);
         const token = tokenOf(sub);
@@ -912,7 +938,15 @@ export async function subscriptionStatus(client, deployment, sub, proof) {
         return { ok: false, reason: "the opening created no cell under this subscription's lock" };
     if (!commitsToAccount(opening, sub, proof.account))
         return { ok: false, reason: "the opening does not commit to this account" };
-    const { cells, balance, tokenBalance, nextChargeIn, tip, created, spent, ownerAfter } = await subscriptionState(client, deployment, sub);
+    // One tip for the whole call: the opening's depth, each charge's, and `active`.
+    const knownTip = minConfirmations > 0n ? await client.getTip() : undefined;
+    const depthFault = (p, what) => knownTip === undefined
+        ? Promise.resolve(undefined)
+        : confirmationFault(client, knownTip, { blockNumber: p.block, blockHash: p.blockHash }, minConfirmations, what);
+    const openingFault = await depthFault(opening, "the opening");
+    if (openingFault)
+        return openingFault;
+    const { cells, balance, tokenBalance, nextChargeIn, tip, created, spent, ownerAfter } = await subscriptionState(client, deployment, sub, knownTip);
     let paidThroughBlock;
     const renews = (p, txHash) => 
     // Only the proven opening or a charge renews; another payment to payTo that
@@ -924,14 +958,27 @@ export async function subscriptionStatus(client, deployment, sub, proof) {
     if (spent && !ownerAfter && !paying.some((c) => c.txHash === spent.txHash))
         paying.push({ txHash: spent.txHash, fetched: spent.fetched });
     const payments = await Promise.all(paying.map((c) => payment(c.txHash, c.fetched)));
+    let unconfirmedThroughBlock;
     for (const [i, { txHash }] of paying.entries()) {
         const p = payments[i];
         if (!renews(p, txHash))
             continue;
         const through = p.block + sub.periodBlocks;
+        // The opening's depth was checked above; a charge's is checked here.
+        const fault = txHash === openHash ? undefined : await depthFault(p, "a charge");
+        if (fault) {
+            // Too recent: it counts later. Reorged: it never does.
+            if (fault.code === "unconfirmed" && (unconfirmedThroughBlock === undefined || through > unconfirmedThroughBlock)) {
+                unconfirmedThroughBlock = through;
+            }
+            continue;
+        }
         if (paidThroughBlock === undefined || through > paidThroughBlock)
             paidThroughBlock = through;
     }
+    if (unconfirmedThroughBlock !== undefined && paidThroughBlock !== undefined && unconfirmedThroughBlock <= paidThroughBlock) {
+        unconfirmedThroughBlock = undefined;
+    }
     return {
         ok: true,
         status: {
@@ -942,6 +989,7 @@ export async function subscriptionStatus(client, deployment, sub, proof) {
             ...(sub.token && { tokenBalance }),
             chargesLeft: chargesLeftOf(sub, lock, balance, tokenBalance),
             nextChargeIn,
+            ...(unconfirmedThroughBlock !== undefined && { unconfirmedThroughBlock }),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckb-session-kit",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Browser-held self-custody sessions for CKB applications",
   "keywords": [
     "ckb",
@@ -57,6 +57,8 @@
     "smoke:contention": "tsx scripts/testnet-contention.ts",
     "smoke:clear-planted": "tsx scripts/testnet-clear-planted.ts",
     "smoke:owner-locks": "tsx scripts/testnet-owner-locks.ts",
+    "smoke:fund-pledge": "tsx scripts/testnet-fund-pledge.ts",
+    "smoke:pool-lag": "tsx scripts/testnet-pool-lag.ts",
     "matrix:wallets": "tsx scripts/wallet-matrix.ts",
     "prepack": "npm run build",
     "pack:check": "node scripts/pack-check.mjs"