ckb-session-kit 0.0.0-stage → 2.0.0

package/dist/deployment.d.ts

@@ -0,0 +1,21 @@
+import { ccc } from "@ckb-ccc/core";
+import { type SessionLockDeployment } from "./lock.js";
+/**
+ * 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 declare function assertCurrentDeployment(client: ccc.Client, deployment: SessionLockDeployment): Promise<void>;

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

@@ -0,0 +1,16 @@
+export { checkRequest, createSession, isActive, SessionPolicyError } 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 { 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";
+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

@@ -0,0 +1,9 @@
+export { checkRequest, createSession, isActive, SessionPolicyError } from "./session.js";
+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 { 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/lock.d.ts

@@ -0,0 +1,70 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * Client side of the on-chain session lock (contracts/session-lock).
+ *
+ * Args layout, 80 or 112 bytes:
+ * owner_lock_hash 32 | session_lock_hash 32 | max_per_tx u64 LE | min_interval u64 LE | [recipient_lock_hash 32]
+ *
+ * A token session (128 or 160 bytes) puts the token before the recipient:
+ * ... | min_interval | token_type_hash 32 | max_per_tx_token u128 LE | [recipient_lock_hash 32]
+ */
+export interface SessionLockParams {
+    /** Lock hash whose presence in a transaction's inputs grants owner mode. */
+    ownerLockHash: ccc.HexLike;
+    /** Lock hash of the session key's own lock (its key cell); grants session mode. */
+    sessionLockHash: ccc.HexLike;
+    /** Most shannons one session-mode transaction may move out, fees included. */
+    maxPerTx: bigint;
+    /** Blocks each session-locked input must have aged (relative since); 0 = no rate limit. */
+    minInterval?: bigint;
+    /** If set, the only lock session-mode spends may pay (besides change, key cell, owner). */
+    recipientLockHash?: ccc.HexLike;
+    /** A token session: the one xUDT type its cells may hold, and the most units one spend may move. */
+    token?: {
+        typeHash: ccc.HexLike;
+        maxPerTx: bigint;
+    };
+}
+/** Where the session lock code lives on a network. */
+export interface SessionLockDeployment {
+    codeHash: ccc.HexLike;
+    hashType: ccc.HashTypeLike;
+    cellDep: {
+        outPoint: {
+            txHash: ccc.HexLike;
+            index: ccc.NumLike;
+        };
+        depType: ccc.DepTypeLike;
+    };
+}
+/**
+ * The session lock deployed on CKB public testnet. Kept identical to
+ * deployment/testnet.json by a test.
+ */
+export declare const TESTNET_DEPLOYMENT: SessionLockDeployment;
+/**
+ * Earlier testnet deployments, newest first. Their code is immutable, so sessions
+ * opened under them keep their old rules; pass these to `recoverSessions` too so
+ * those sessions can still be swept. 13 Oct 2026: before token sessions (errors
+ * 19, 20) and untyped-only payments. 8 Oct 2026: before errors 16, 17 and 18.
+ */
+export declare const TESTNET_LEGACY_DEPLOYMENTS: SessionLockDeployment[];
+/** Error codes returned by the session lock, for reading node rejections. */
+export declare const SESSION_LOCK_ERRORS: Record<number, string>;
+export declare function sessionLockArgs(p: SessionLockParams): ccc.Hex;
+export declare function sessionLockScript(d: SessionLockDeployment, p: SessionLockParams): ccc.Script;
+export declare function sessionLockCellDep(d: SessionLockDeployment): ccc.CellDep;
+/** A relative `since` of `blocks` block numbers (RFC 0017), as the rate limit requires. */
+export declare function relativeBlocksSince(blocks: bigint): bigint;
+/**
+ * Pulls a session-lock error code out of a node's rejection message, if there is
+ * one. The session lock only ever runs as an input's lock: a code from a type
+ * script (xUDT on a token payment, say) is not one, and gives undefined. An
+ * input lock can still be another lock in the same transaction (the recipient's
+ * anyone-can-pay cell on a top-up); pass `sessionInputs`, the indexes of the
+ * session cells, to rule that out too.
+ */
+export declare function sessionLockErrorFrom(message: string, sessionInputs?: number[]): {
+    code: number;
+    meaning: string;
+} | undefined;

package/dist/lock.js

@@ -0,0 +1,106 @@
+import { ccc } from "@ckb-ccc/core";
+/**
+ * The session lock deployed on CKB public testnet. Kept identical to
+ * deployment/testnet.json by a test.
+ */
+export const TESTNET_DEPLOYMENT = {
+    codeHash: "0xab419466529ea479590d4be7b23580ce2ddc640ba902735c9ad9a22dc64c08ce",
+    hashType: "data2",
+    cellDep: {
+        outPoint: { txHash: "0xf3098bdb9a7bb1c500990be0f1159b7e66f507fef6b7a4f904046024284877f2", index: "0x0" },
+        depType: "code",
+    },
+};
+/**
+ * Earlier testnet deployments, newest first. Their code is immutable, so sessions
+ * opened under them keep their old rules; pass these to `recoverSessions` too so
+ * those sessions can still be swept. 13 Oct 2026: before token sessions (errors
+ * 19, 20) and untyped-only payments. 8 Oct 2026: before errors 16, 17 and 18.
+ */
+export const TESTNET_LEGACY_DEPLOYMENTS = [
+    {
+        codeHash: "0x1cb7724269e2e86359b5b47cad6b1860ccd6da254c25c651056c8431d11590cd",
+        hashType: "data2",
+        cellDep: {
+            outPoint: { txHash: "0x37cfe04f64fd4dbec3803a972a51b7080f9ca1a3042535e97b7a756d0e03b071", index: "0x0" },
+            depType: "code",
+        },
+    },
+    {
+        codeHash: "0x1ae8b8f71ed1846e2823ecccd8c3f80527be2895689f5dae54a53bd42526bc20",
+        hashType: "data2",
+        cellDep: {
+            outPoint: { txHash: "0xab2e69b8b97c15bddeb80954edd6d33befcd2fe9e4243377a46f14a3e1c343d2", index: "0x0" },
+            depType: "code",
+        },
+    },
+];
+/** Error codes returned by the session lock, for reading node rejections. */
+export const SESSION_LOCK_ERRORS = {
+    10: "bad args",
+    11: "not authorised: neither owner nor session key present",
+    12: "outflow exceeds max_per_tx",
+    13: "recipient not allowed",
+    14: "rate limited: input too young",
+    15: "overflow (capacity or token amounts)",
+    16: "too many change cells: a session spend may not split the session cell",
+    17: "the key cell may not grow in a session spend",
+    18: "session cells and their change may not carry a type script (in a token session: none but the token)",
+    19: "malformed token data: under 16 bytes, or token change not exactly 16",
+    20: "token outflow exceeds max_per_tx_token",
+};
+const U64_MAX = (1n << 64n) - 1n;
+function u64le(v) {
+    if (v < 0n || v > U64_MAX)
+        throw new RangeError(`not a u64: ${v}`);
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, v, true);
+    return b;
+}
+const U128_MAX = (1n << 128n) - 1n;
+function u128le(v) {
+    if (v < 0n || v > U128_MAX)
+        throw new RangeError(`not a u128: ${v}`);
+    return ccc.numLeToBytes(v, 16);
+}
+function hash32(h, name) {
+    const b = ccc.bytesFrom(h);
+    if (b.length !== 32)
+        throw new RangeError(`${name} must be 32 bytes`);
+    return b;
+}
+export function sessionLockArgs(p) {
+    return ccc.hexFrom(ccc.bytesConcat(hash32(p.ownerLockHash, "ownerLockHash"), hash32(p.sessionLockHash, "sessionLockHash"), u64le(p.maxPerTx), u64le(p.minInterval ?? 0n), ...(p.token === undefined ? [] : [hash32(p.token.typeHash, "token.typeHash"), u128le(p.token.maxPerTx)]), ...(p.recipientLockHash === undefined ? [] : [hash32(p.recipientLockHash, "recipientLockHash")])));
+}
+export function sessionLockScript(d, p) {
+    return ccc.Script.from({ codeHash: d.codeHash, hashType: d.hashType, args: sessionLockArgs(p) });
+}
+export function sessionLockCellDep(d) {
+    return ccc.CellDep.from(d.cellDep);
+}
+/** A relative `since` of `blocks` block numbers (RFC 0017), as the rate limit requires. */
+export function relativeBlocksSince(blocks) {
+    if (blocks < 0n || blocks >= 1n << 56n)
+        throw new RangeError(`blocks out of range: ${blocks}`);
+    return (1n << 63n) | blocks;
+}
+/**
+ * Pulls a session-lock error code out of a node's rejection message, if there is
+ * one. The session lock only ever runs as an input's lock: a code from a type
+ * script (xUDT on a token payment, say) is not one, and gives undefined. An
+ * input lock can still be another lock in the same transaction (the recipient's
+ * anyone-can-pay cell on a top-up); pass `sessionInputs`, the indexes of the
+ * session cells, to rule that out too.
+ */
+export function sessionLockErrorFrom(message, sessionInputs) {
+    const m = message.match(/error code (-?\d+)/i) ?? message.match(/ValidationFailure\D+(-?\d+)/);
+    if (!m)
+        return undefined;
+    const source = message.match(/source: (Inputs|Outputs)\[(\d+)\]\.(Lock|Type)/);
+    if (source && (source[1] !== "Inputs" || source[3] !== "Lock"))
+        return undefined;
+    if (source && sessionInputs && !sessionInputs.includes(Number(source[2])))
+        return undefined;
+    const code = Number(m[1]);
+    return { code, meaning: SESSION_LOCK_ERRORS[code] ?? "unknown" };
+}