@keelcodes/sdk 2.2.0 → 2.3.1

package/dist/aa/bundler.d.ts

@@ -0,0 +1,28 @@
+import type { Address, Hex } from 'viem';
+import type { BundlerLike, UserOpReceipt, UserOpResult, UserOperationV7 } from './types';
+export interface BundlerClientOptions {
+    url: string;
+    entryPoint: Address;
+    headers?: Record<string, string>;
+    /** 单次 HTTP 超时（ms），默认 30s */
+    timeoutMs?: number;
+    /** 收据轮询间隔（ms），默认 1s */
+    pollIntervalMs?: number;
+    /** 等收据总超时（ms），默认 120s */
+    waitTimeoutMs?: number;
+}
+export declare class BundlerClient implements BundlerLike {
+    private readonly url;
+    private readonly entryPoint;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly pollIntervalMs;
+    private readonly waitTimeoutMs;
+    private nextId;
+    constructor(opts: BundlerClientOptions);
+    estimateUserOperationGas(op: UserOperationV7): Promise<Partial<Pick<UserOperationV7, 'callGasLimit' | 'verificationGasLimit' | 'preVerificationGas'>>>;
+    sendUserOperation(op: UserOperationV7): Promise<UserOpResult>;
+    /** 轮询 `eth_getUserOperationReceipt`；超时抛错（不静默返回未确认）。 */
+    waitForReceipt(userOpHash: Hex): Promise<UserOpReceipt>;
+    private rpc;
+}

package/dist/aa/bundler.js

@@ -0,0 +1,95 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// 最小 ERC-4337 bundler 客户端（JSON-RPC over HTTP）
+//
+// 只覆盖 session 付款需要的三件事：
+//   eth_estimateUserOperationGas / eth_sendUserOperation / eth_getUserOperationReceipt
+// Keel 托管端点：`https://keel.codes/v1/bundler/{chain}`（可自定义 headers 带鉴权）。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BundlerClient = void 0;
+const userop_1 = require("./userop");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class BundlerClient {
+    url;
+    entryPoint;
+    headers;
+    timeoutMs;
+    pollIntervalMs;
+    waitTimeoutMs;
+    nextId = 1;
+    constructor(opts) {
+        this.url = opts.url;
+        this.entryPoint = opts.entryPoint;
+        this.headers = { 'Content-Type': 'application/json', ...(opts.headers ?? {}) };
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.pollIntervalMs = opts.pollIntervalMs ?? 1_000;
+        this.waitTimeoutMs = opts.waitTimeoutMs ?? 120_000;
+    }
+    async estimateUserOperationGas(op) {
+        const r = await this.rpc('eth_estimateUserOperationGas', [(0, userop_1.userOpToRpc)(op), this.entryPoint]);
+        return {
+            callGasLimit: BigInt(r.callGasLimit),
+            verificationGasLimit: BigInt(r.verificationGasLimit),
+            preVerificationGas: BigInt(r.preVerificationGas),
+        };
+    }
+    async sendUserOperation(op) {
+        const userOpHash = await this.rpc('eth_sendUserOperation', [
+            (0, userop_1.userOpToRpc)(op),
+            this.entryPoint,
+        ]);
+        const receipt = await this.waitForReceipt(userOpHash);
+        return { userOpHash, bundlerUrl: this.url, receipt };
+    }
+    /** 轮询 `eth_getUserOperationReceipt`；超时抛错（不静默返回未确认）。 */
+    async waitForReceipt(userOpHash) {
+        const deadline = Date.now() + this.waitTimeoutMs;
+        let lastErr;
+        while (Date.now() < deadline) {
+            try {
+                const r = await this.rpc('eth_getUserOperationReceipt', [userOpHash]);
+                if (r) {
+                    return {
+                        txHash: r.transactionHash ?? r.receipt?.transactionHash,
+                        success: r.success,
+                        actualGasCost: BigInt(r.actualGasCost),
+                        actualGasUsed: BigInt(r.actualGasUsed),
+                        logs: r.logs ?? [],
+                    };
+                }
+            }
+            catch (e) {
+                // 轮询期 RPC 抖动不致命
+                lastErr = e;
+            }
+            await sleep(this.pollIntervalMs);
+        }
+        throw new Error(`[keel-sdk] userOp receipt timeout after ${this.waitTimeoutMs}ms (${userOpHash})` +
+            (lastErr instanceof Error ? `: ${lastErr.message}` : ''));
+    }
+    async rpc(method, params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({ jsonrpc: '2.0', id: this.nextId++, method, params }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.error) {
+            const msg = json?.error?.message ?? `HTTP ${res.status}`;
+            const data = json?.error?.data ? ` ${JSON.stringify(json.error.data).slice(0, 300)}` : '';
+            throw new Error(`[keel-sdk] bundler ${method} failed: ${msg}${data}`);
+        }
+        return json.result;
+    }
+}
+exports.BundlerClient = BundlerClient;

package/dist/aa/chain-defaults.d.ts

@@ -0,0 +1,30 @@
+import { type Address, type PublicClient } from 'viem';
+import type { ChainAAConfig } from './types';
+export type KeelChain = 'base' | 'bsc' | 'ethereum';
+/** EntryPoint v0.7（三链同址） */
+export declare const KEEL_ENTRYPOINT_V07: Address;
+/** KeelSessionValidator 副本（slot 0，三链同址） */
+export declare const KEEL_SESSION_VALIDATOR: Address;
+/** KeelPolicyHook 副本（slot 0，与 validator 成对，三链同址） */
+export declare const KEEL_SESSION_HOOK: Address;
+/** KeelTokenPaymaster（三链同址；gas 垫付 + 稳定币结算） */
+export declare const KEEL_TOKEN_PAYMASTER: Address;
+export declare const KEEL_CHAIN_IDS: Record<KeelChain, number>;
+/** 各链 USDC（BSC 为 Binance-Peg USDC，18 位） */
+export declare const KEEL_USDC: Record<KeelChain, Address>;
+export declare const KEEL_USDC_DECIMALS: Record<KeelChain, number>;
+/** Keel 托管 bundler（ERC-4337 JSON-RPC，路径即链别名） */
+export declare const KEEL_BUNDLER_URL: Record<KeelChain, string>;
+export interface KeelChainOptions {
+    rpcUrl?: string;
+    /** 覆盖 bundler（缺省 `KEEL_BUNDLER_URL[chain]`） */
+    bundlerUrl?: string;
+    bundlerHeaders?: Record<string, string>;
+    /** 覆盖 validator/hook 副本（仅重部署后需要） */
+    sessionValidator?: Address;
+    sessionHook?: Address;
+}
+/** 取某条链的 ChainAAConfig（内置默认 + 可选覆盖）。 */
+export declare function keelChainConfig(chain: KeelChain, opts?: KeelChainOptions): ChainAAConfig;
+/** 便捷：创建该链的只读 PublicClient（用于读 EntryPoint nonce 等）。 */
+export declare function keelPublicClient(chain: KeelChain, rpcUrl?: string): PublicClient;

package/dist/aa/chain-defaults.js

@@ -0,0 +1,63 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — 内置三链 AA 栈地址（B 端零配置起步）
+//
+// 来源：infraX 生产部署（2026-10 三链同址核验）。
+//  - EntryPoint v0.7 / Kernel 官方栈：三链同址（ZeroDev 确定性部署）
+//  - KeelSessionValidator 副本 / KeelPolicyHook / KeelTokenPaymaster：三链同址
+//  - USDC：三链异址，且 **BSC 为 18 位精度**（其余 6 位）
+//
+// ⚠️ 均为不可变部署；链上重部署须同步本表。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEEL_BUNDLER_URL = exports.KEEL_USDC_DECIMALS = exports.KEEL_USDC = exports.KEEL_CHAIN_IDS = exports.KEEL_TOKEN_PAYMASTER = exports.KEEL_SESSION_HOOK = exports.KEEL_SESSION_VALIDATOR = exports.KEEL_ENTRYPOINT_V07 = void 0;
+exports.keelChainConfig = keelChainConfig;
+exports.keelPublicClient = keelPublicClient;
+const viem_1 = require("viem");
+const chains_1 = require("viem/chains");
+/** EntryPoint v0.7（三链同址） */
+exports.KEEL_ENTRYPOINT_V07 = '0x0000000071727De22E5E9d8BAf0edAc6f37da032';
+/** KeelSessionValidator 副本（slot 0，三链同址） */
+exports.KEEL_SESSION_VALIDATOR = '0x8BCB3F5d855F5b2a1f1398690Daaa7866992bDE7';
+/** KeelPolicyHook 副本（slot 0，与 validator 成对，三链同址） */
+exports.KEEL_SESSION_HOOK = '0x466b5DC3796D44b0B63FdF2d3bC7a8Ea371a891F';
+/** KeelTokenPaymaster（三链同址；gas 垫付 + 稳定币结算） */
+exports.KEEL_TOKEN_PAYMASTER = '0x4500A1FbAe335F5E20Fa85C70Daa98a89faD6415';
+exports.KEEL_CHAIN_IDS = { base: 8453, bsc: 56, ethereum: 1 };
+/** 各链 USDC（BSC 为 Binance-Peg USDC，18 位） */
+exports.KEEL_USDC = {
+    base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    bsc: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
+    ethereum: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+};
+exports.KEEL_USDC_DECIMALS = { base: 6, bsc: 18, ethereum: 6 };
+/** Keel 托管 bundler（ERC-4337 JSON-RPC，路径即链别名） */
+exports.KEEL_BUNDLER_URL = {
+    base: 'https://keel.codes/v1/bundler/base',
+    bsc: 'https://keel.codes/v1/bundler/bsc',
+    ethereum: 'https://keel.codes/v1/bundler/ethereum',
+};
+const VIEM_CHAIN = { base: chains_1.base, bsc: chains_1.bsc, ethereum: chains_1.mainnet };
+/** 取某条链的 ChainAAConfig（内置默认 + 可选覆盖）。 */
+function keelChainConfig(chain, opts = {}) {
+    return {
+        chainId: exports.KEEL_CHAIN_IDS[chain],
+        entryPoint: exports.KEEL_ENTRYPOINT_V07,
+        rpcUrl: opts.rpcUrl,
+        kernelVersion: '0.3.1',
+        sessionValidatorCopies: [opts.sessionValidator ?? exports.KEEL_SESSION_VALIDATOR],
+        sessionHookCopies: [opts.sessionHook ?? exports.KEEL_SESSION_HOOK],
+        bundlers: [
+            {
+                url: opts.bundlerUrl ?? exports.KEEL_BUNDLER_URL[chain],
+                priority: 0,
+                ...(opts.bundlerHeaders ? { headers: opts.bundlerHeaders } : {}),
+            },
+        ],
+    };
+}
+/** 便捷：创建该链的只读 PublicClient（用于读 EntryPoint nonce 等）。 */
+function keelPublicClient(chain, rpcUrl) {
+    const transport = rpcUrl ? (0, viem_1.http)(rpcUrl) : (0, viem_1.http)();
+    return (0, viem_1.createPublicClient)({ chain: VIEM_CHAIN[chain], transport });
+}

package/dist/aa/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './chain-defaults';
+export * from './nonce';
+export * from './token-paymaster';
+export * from './signer';
+export * from './userop';
+export * from './keel-session';
+export * from './x402';
+export * from './x402-session';
+export * from './bundler';

package/dist/aa/index.js

@@ -0,0 +1,29 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — AA / x402 客户端入口
+// ---------------------------------------------------------------------------
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./chain-defaults"), exports);
+__exportStar(require("./nonce"), exports);
+__exportStar(require("./token-paymaster"), exports);
+__exportStar(require("./signer"), exports);
+__exportStar(require("./userop"), exports);
+__exportStar(require("./keel-session"), exports);
+__exportStar(require("./x402"), exports);
+__exportStar(require("./x402-session"), exports);
+__exportStar(require("./bundler"), exports);

package/dist/aa/keel-session.d.ts

@@ -0,0 +1,70 @@
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { ChainAAConfig, SessionPolicy, Signer, UserOperationV7 } from './types';
+export declare const KEEL_POLICY_VERSION = 1n;
+/** bytes32 归一化（已是 0x+64 hex 直接用，否则左对齐补零） */
+export declare function toBytes32(id: string): Hex;
+/** 链上 Rule（字段顺序即 ABI 顺序，不可调换） */
+export interface KeelRule {
+    target: Address;
+    selectors: Hex[];
+    maxPerTx: bigint;
+    maxDaily: bigint;
+    maxCalls: bigint;
+    tokenLimits: KeelTokenLimit[];
+}
+export interface KeelTokenLimit {
+    token: Address;
+    maxPerTx: bigint;
+    maxDaily: bigint;
+}
+/**
+ * SessionPermission[] → 链上 Rule[]（每条 target 一个 Rule）。
+ * tokenLimits 只挂到 `token == target` 的那条 Rule（链上强制同址）。
+ */
+export declare function toKeelRules(policy: SessionPolicy): KeelRule[];
+/** `policyData = abi.encode(version, validAfter, validUntil, Rule[])` */
+export declare function encodeKeelPolicyData(policy: SessionPolicy): Hex;
+/** 解析 slot 对应的 validator 副本地址（缺配置直接抛错，不回退旧模块）。 */
+export declare function resolveKeelValidator(chainConfig: ChainAAConfig, slot: number): Address;
+/** agent 侧签名对象：digest = keccak256(userOpHash ‖ keccak256(policyData)) */
+export declare function keelSessionDigest(userOpHash: Hex, policyData: Hex): Hex;
+/** agent 侧 userOp.signature 组装：sessionId(32B) ‖ policyData ‖ sessionKeySig(65B)。 */
+export declare function encodeKeelSessionSignature(p: {
+    sessionId: string;
+    policyData: Hex;
+    sig: Hex;
+}): Hex;
+export interface BuildKeelSessionUserOpParams {
+    /** 未传 nonce 时用于读链上 getNonce；传 nonce（relay 预分配）时可不给 */
+    client?: PublicClient;
+    chainConfig: ChainAAConfig;
+    account: Address;
+    /** session 策略（复算 policyData = 链上 commitment，须与 enable 时逐字节一致） */
+    policy: SessionPolicy;
+    /** slot 序号（= validator 副本下标；一 key 一副本） */
+    slot: number;
+    /** 该 key 的 agent 通道号（nonceKey 隔离多 agent 并发）；缺省 0 */
+    agentIndex?: number | bigint;
+    /**
+     * nonce 整值（= `nonceKey<<64 | sequence`），由 relay `POST /v1/wallet/session/nonce/allocate`
+     * 预分配后回传。缺省则读链上当前 getNonce（单 agent 串行场景）。
+     */
+    nonce?: bigint;
+    call: {
+        target: Address;
+        value?: bigint;
+        data: Hex;
+    };
+    /** agent（session key）签名者 */
+    agentSigner: Signer;
+    gas?: Partial<Pick<UserOperationV7, 'callGasLimit' | 'verificationGasLimit' | 'preVerificationGas' | 'maxFeePerGas' | 'maxPriorityFeePerGas'>>;
+}
+/**
+ * v1（Keel）agent 侧调用 UserOp 构造（已签名）：
+ *   nonce    = 预分配整值，或 `EntryPoint.getNonce(account, validatorNonceKey(validator, agentIndex))`
+ *   callData = `executeUserOp( execute(target,value,data) )` —— 挂真 hook 时必需
+ *   signature= sessionId ‖ policyData ‖ agentSig(keccak256(userOpHash ‖ keccak256(policyData)))
+ *
+ * 与 aa-sdk 的 `buildKeelSessionUserOp` 逐字节一致（同输入同输出）。
+ */
+export declare function buildKeelSessionUserOp(p: BuildKeelSessionUserOpParams): Promise<UserOperationV7>;

package/dist/aa/keel-session.js

@@ -0,0 +1,132 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Keel(v1) session 编码：policyData / 摘要 / 签名布局
+//
+// 链上契约（KeelSessionValidator + KeelPolicyHook 共用同一份 policyData）：
+//   policyData   = abi.encode(version=1, validAfter, validUntil, Rule[])
+//   UserOp 摘要  = keccak256(userOpHash ‖ keccak256(policyData))
+//   signature    = sessionId(32B) ‖ policyData ‖ sessionKeySig(65B)
+// 链上只存 keccak256(policyData) 作为 commitment，因此这里必须逐字节一致。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEEL_POLICY_VERSION = void 0;
+exports.toBytes32 = toBytes32;
+exports.toKeelRules = toKeelRules;
+exports.encodeKeelPolicyData = encodeKeelPolicyData;
+exports.resolveKeelValidator = resolveKeelValidator;
+exports.keelSessionDigest = keelSessionDigest;
+exports.encodeKeelSessionSignature = encodeKeelSessionSignature;
+exports.buildKeelSessionUserOp = buildKeelSessionUserOp;
+const viem_1 = require("viem");
+const userop_1 = require("./userop");
+const nonce_1 = require("./nonce");
+exports.KEEL_POLICY_VERSION = 1n;
+/** bytes32 归一化（已是 0x+64 hex 直接用，否则左对齐补零） */
+function toBytes32(id) {
+    return ((0, viem_1.isHex)(id) && id.length === 66 ? id : (0, viem_1.toHex)(id, { size: 32 }));
+}
+const KeelTokenLimitTuple = [
+    { name: 'token', type: 'address' },
+    { name: 'maxPerTx', type: 'uint256' },
+    { name: 'maxDaily', type: 'uint256' },
+];
+const KeelRuleTuple = [
+    { name: 'target', type: 'address' },
+    { name: 'selectors', type: 'bytes4[]' },
+    { name: 'maxPerTx', type: 'uint256' },
+    { name: 'maxDaily', type: 'uint256' },
+    { name: 'maxCalls', type: 'uint256' },
+    { name: 'tokenLimits', type: 'tuple[]', components: KeelTokenLimitTuple },
+];
+/**
+ * SessionPermission[] → 链上 Rule[]（每条 target 一个 Rule）。
+ * tokenLimits 只挂到 `token == target` 的那条 Rule（链上强制同址）。
+ */
+function toKeelRules(policy) {
+    const rules = [];
+    for (const p of policy.permissions) {
+        const limits = p.tokenLimits ?? [];
+        for (const target of p.targets) {
+            rules.push({
+                target,
+                selectors: [...(p.selectors ?? [])],
+                maxPerTx: p.valueLimit ?? 0n,
+                maxDaily: p.dailyLimit ?? 0n,
+                maxCalls: BigInt(p.countLimit ?? 0),
+                tokenLimits: limits
+                    .filter((t) => t.token.toLowerCase() === target.toLowerCase())
+                    .map((t) => ({ token: t.token, maxPerTx: t.maxPerTx, maxDaily: t.maxDaily })),
+            });
+        }
+    }
+    if (rules.length === 0) {
+        throw new Error('[keel-sdk] session policy needs at least one target');
+    }
+    return rules;
+}
+/** `policyData = abi.encode(version, validAfter, validUntil, Rule[])` */
+function encodeKeelPolicyData(policy) {
+    return (0, viem_1.encodeAbiParameters)([
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'uint256' },
+        { type: 'tuple[]', components: KeelRuleTuple },
+    ], [exports.KEEL_POLICY_VERSION, policy.validAfter, policy.validUntil, toKeelRules(policy)]);
+}
+/** 解析 slot 对应的 validator 副本地址（缺配置直接抛错，不回退旧模块）。 */
+function resolveKeelValidator(chainConfig, slot) {
+    if (!Number.isInteger(slot) || slot < 0) {
+        throw new Error(`[keel-sdk] invalid slot: ${slot}`);
+    }
+    const copy = chainConfig.sessionValidatorCopies?.[slot];
+    if (copy)
+        return copy;
+    throw new Error(`[keel-sdk] no keel session validator for slot ${slot}`);
+}
+/** agent 侧签名对象：digest = keccak256(userOpHash ‖ keccak256(policyData)) */
+function keelSessionDigest(userOpHash, policyData) {
+    return (0, viem_1.keccak256)((0, viem_1.concatHex)([userOpHash, (0, viem_1.keccak256)(policyData)]));
+}
+/** agent 侧 userOp.signature 组装：sessionId(32B) ‖ policyData ‖ sessionKeySig(65B)。 */
+function encodeKeelSessionSignature(p) {
+    return (0, viem_1.concatHex)([toBytes32(p.sessionId), p.policyData, p.sig]);
+}
+/** EntryPoint v0.7 getNonce(address,uint192) */
+const ENTRYPOINT_GETNONCE_ABI = (0, viem_1.parseAbi)([
+    'function getNonce(address sender, uint192 key) view returns (uint256)',
+]);
+/**
+ * v1（Keel）agent 侧调用 UserOp 构造（已签名）：
+ *   nonce    = 预分配整值，或 `EntryPoint.getNonce(account, validatorNonceKey(validator, agentIndex))`
+ *   callData = `executeUserOp( execute(target,value,data) )` —— 挂真 hook 时必需
+ *   signature= sessionId ‖ policyData ‖ agentSig(keccak256(userOpHash ‖ keccak256(policyData)))
+ *
+ * 与 aa-sdk 的 `buildKeelSessionUserOp` 逐字节一致（同输入同输出）。
+ */
+async function buildKeelSessionUserOp(p) {
+    const validator = resolveKeelValidator(p.chainConfig, p.slot);
+    // agentIndex（通道号）落在 nonceKey 低 16 位（uint16）⇒ 合法 0..65535；
+    // 超界会被 ValidatorLib 静默截断到别的通道，故在 SDK 边界显式拒绝。
+    const agentIndex = p.agentIndex ?? 0;
+    if (BigInt(agentIndex) < 0n || BigInt(agentIndex) > 65535n) {
+        throw new Error(`[keel-sdk] buildKeelSessionUserOp: agentIndex 必须在 0..65535（uint16 通道号），got ${agentIndex}`);
+    }
+    let nonce = p.nonce;
+    if (nonce === undefined) {
+        if (!p.client) {
+            throw new Error('[keel-sdk] buildKeelSessionUserOp: 未传 nonce 时必须提供 client（用于读链上 getNonce）');
+        }
+        nonce = (await p.client.readContract({
+            address: p.chainConfig.entryPoint,
+            abi: ENTRYPOINT_GETNONCE_ABI,
+            functionName: 'getNonce',
+            args: [p.account, (0, nonce_1.validatorNonceKey)(validator, agentIndex)],
+        }));
+    }
+    const callData = (0, userop_1.encodeExecuteUserOp)((0, userop_1.encodeExecute)(p.call.target, p.call.value ?? 0n, p.call.data));
+    const op = (0, userop_1.buildUserOpWithCallData)({ sender: p.account, nonce, callData, gas: p.gas });
+    const userOpHash = (0, userop_1.getUserOpHash)(op, p.chainConfig.entryPoint, p.chainConfig.chainId);
+    const policyData = encodeKeelPolicyData(p.policy);
+    const sig = await p.agentSigner.signUserOp(keelSessionDigest(userOpHash, policyData));
+    return { ...op, signature: encodeKeelSessionSignature({ sessionId: p.policy.sessionId, policyData, sig }) };
+}

package/dist/aa/nonce.d.ts

@@ -0,0 +1,8 @@
+import type { Address } from 'viem';
+export declare const VALIDATION_MODE_DEFAULT = 0;
+export declare const VALIDATION_MODE_ENABLE = 1;
+export declare const VALIDATION_TYPE_ROOT = 0;
+export declare const VALIDATION_TYPE_VALIDATOR = 1;
+export declare function encodeAsNonceKey(mode: number, vType: number, validator: Address, nonceKey?: number | bigint): bigint;
+/** 已安装 validator 的常规 UserOp（agent session key 走此通道）。 */
+export declare function validatorNonceKey(validator: Address, nonceKey?: number | bigint): bigint;

package/dist/aa/nonce.js

@@ -0,0 +1,22 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Kernel v3 nonce key 编码（ValidatorLib.encodeAsNonceKey）
+//
+// EntryPoint nonce = nonceKey << 64 | sequence；Kernel 用 nonceKey 路由到
+// 具体 validator：key = (mode << 184) | (vType << 176) | (validator << 16) | nonceKey
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALIDATION_TYPE_VALIDATOR = exports.VALIDATION_TYPE_ROOT = exports.VALIDATION_MODE_ENABLE = exports.VALIDATION_MODE_DEFAULT = void 0;
+exports.encodeAsNonceKey = encodeAsNonceKey;
+exports.validatorNonceKey = validatorNonceKey;
+exports.VALIDATION_MODE_DEFAULT = 0;
+exports.VALIDATION_MODE_ENABLE = 1;
+exports.VALIDATION_TYPE_ROOT = 0;
+exports.VALIDATION_TYPE_VALIDATOR = 1;
+function encodeAsNonceKey(mode, vType, validator, nonceKey = 0) {
+    return (BigInt(mode) << 184n) | (BigInt(vType) << 176n) | (BigInt(validator) << 16n) | BigInt(nonceKey);
+}
+/** 已安装 validator 的常规 UserOp（agent session key 走此通道）。 */
+function validatorNonceKey(validator, nonceKey = 0) {
+    return encodeAsNonceKey(exports.VALIDATION_MODE_DEFAULT, exports.VALIDATION_TYPE_VALIDATOR, validator, nonceKey);
+}

package/dist/aa/signer.d.ts

@@ -0,0 +1,3 @@
+import type { Hex } from 'viem';
+import type { Signer } from './types';
+export declare function privateKeySigner(privateKey: Hex): Signer;

package/dist/aa/signer.js

@@ -0,0 +1,16 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// 自持私钥签名器（最简单接入形态；MPC / 外部钱包请自行实现 Signer）
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.privateKeySigner = privateKeySigner;
+const accounts_1 = require("viem/accounts");
+function privateKeySigner(privateKey) {
+    const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+    return {
+        type: 'private-key',
+        address: account.address,
+        signUserOp: (hash) => account.sign({ hash }),
+        signMessage: (message) => account.signMessage({ message: { raw: message } }),
+    };
+}

package/dist/aa/token-paymaster.d.ts

@@ -0,0 +1,9 @@
+import { type Address, type Hex } from 'viem';
+/**
+ * token 计费分支的 `paymasterData`：`tokenAddress`（可选再追 32B 客户端报价）。
+ * 客户端报价只有比链上价更保守时才会被采用（不会多扣）。
+ */
+export declare function buildTokenPaymasterData(args: {
+    token: Address;
+    clientPrice?: bigint;
+}): Hex;

package/dist/aa/token-paymaster.js

@@ -0,0 +1,18 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// KeelTokenPaymaster 客户端数据编码
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTokenPaymasterData = buildTokenPaymasterData;
+const viem_1 = require("viem");
+/**
+ * token 计费分支的 `paymasterData`：`tokenAddress`（可选再追 32B 客户端报价）。
+ * 客户端报价只有比链上价更保守时才会被采用（不会多扣）。
+ */
+function buildTokenPaymasterData(args) {
+    if (args.clientPrice == null)
+        return args.token;
+    if (args.clientPrice <= 0n)
+        throw new Error('[keel-sdk] clientPrice must be > 0');
+    return (0, viem_1.concatHex)([args.token, (0, viem_1.toHex)(args.clientPrice, { size: 32 })]);
+}

package/dist/aa/types.d.ts

@@ -0,0 +1,92 @@
+import type { Address, Hex } from 'viem';
+export type EvmNetwork = 'evm';
+export interface BundlerConfig {
+    url: string;
+    /** 0 = 主端点（缺省） */
+    priority?: number;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** 链配置：B 端可用 `keelChainConfig()` 取内置三链默认，再按需覆盖。 */
+export interface ChainAAConfig {
+    chainId: number;
+    /** EntryPoint v0.7 */
+    entryPoint: Address;
+    rpcUrl?: string;
+    /** Kernel 版本（缺省 '0.3.1'） */
+    kernelVersion?: string;
+    /** Keel(v1) session validator 副本（slot i → 第 i 个；append-only） */
+    sessionValidatorCopies?: Address[];
+    /** Keel(v1) policy hook 副本（与 validator 成对） */
+    sessionHookCopies?: Address[];
+    bundlers?: BundlerConfig[];
+}
+/** 统一签名器（自持私钥 / MPC / 外部钱包）。 */
+export interface Signer {
+    readonly type: 'private-key' | 'mpc' | 'external-wallet';
+    readonly address: Address;
+    /** 对 UserOp hash（或等价的 EIP-712 摘要）签名，返回 65 字节 ECDSA */
+    signUserOp(hash: Hex): Promise<Hex>;
+    /** 对任意消息签名（EIP-191） */
+    signMessage(message: Hex): Promise<Hex>;
+}
+/** ERC-20 金额级限额（单笔 / 日累计；0 = 不限） */
+export interface TokenLimit {
+    token: Address;
+    maxPerTx: bigint;
+    maxDaily: bigint;
+}
+/** 单条策略（target 维度） */
+export interface SessionPermission {
+    targets: Address[];
+    selectors?: Hex[];
+    valueLimit?: bigint;
+    countLimit?: number;
+    dailyLimit?: bigint;
+    tokenLimits?: TokenLimit[];
+}
+/** session 策略：链上 `policyData` 的唯一来源（须与 enable 时逐字节一致）。 */
+export interface SessionPolicy {
+    network?: EvmNetwork;
+    sessionId: string;
+    signer: Address;
+    validUntil: bigint;
+    validAfter: bigint;
+    permissions: SessionPermission[];
+}
+/** ERC-4337 v0.7 UserOperation（非打包形态，bundler RPC 字段） */
+export interface UserOperationV7 {
+    sender: Address;
+    nonce: bigint;
+    factory?: Address;
+    factoryData?: Hex;
+    callData: Hex;
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    paymaster?: Address;
+    paymasterVerificationGasLimit?: bigint;
+    paymasterPostOpGasLimit?: bigint;
+    paymasterData?: Hex;
+    signature: Hex;
+}
+export interface UserOpReceipt {
+    txHash?: Hex;
+    success: boolean;
+    actualGasCost: bigint;
+    actualGasUsed: bigint;
+    logs: unknown[];
+}
+export interface UserOpResult {
+    userOpHash: Hex;
+    bundlerUrl: string;
+    /** 轮询到的收据（可能为 null = 未确认） */
+    receipt?: UserOpReceipt;
+}
+/** payX402WithSession 所需的最小 bundler 能力（HTTP 实现见 ./bundler）。 */
+export interface BundlerLike {
+    estimateUserOperationGas(op: UserOperationV7): Promise<Partial<Pick<UserOperationV7, 'callGasLimit' | 'verificationGasLimit' | 'preVerificationGas'>>>;
+    sendUserOperation(op: UserOperationV7): Promise<UserOpResult>;
+}

package/dist/aa/types.js

@@ -0,0 +1,8 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// @keelcodes/sdk — AA 客户端共享类型（EVM / Kernel v3 / ERC-4337 v0.7）
+//
+// 这里只保留「客户端自己签 UserOp + 自己组 x402 凭证」所需的最小形状，
+// 与 @0xinfrax/aa-sdk 的 ChainAAConfig / SessionPolicy 逐字节兼容。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });