@keelcodes/sdk 2.3.1 → 2.3.2

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

@@ -9,6 +9,10 @@ export declare const KEEL_SESSION_VALIDATOR: Address;
 export declare const KEEL_SESSION_HOOK: Address;
 /** KeelTokenPaymaster（三链同址；gas 垫付 + 稳定币结算） */
 export declare const KEEL_TOKEN_PAYMASTER: Address;
+/** Kernel v3 factory（三链同址；首笔 createAccount） */
+export declare const KEEL_KERNEL_FACTORY: Address;
+/** Kernel v3 root validator（ECDSA，三链同址；账户 owner 验签） */
+export declare const KEEL_ROOT_VALIDATOR: Address;
 export declare const KEEL_CHAIN_IDS: Record<KeelChain, number>;
 /** 各链 USDC（BSC 为 Binance-Peg USDC，18 位） */
 export declare const KEEL_USDC: Record<KeelChain, Address>;

package/dist/aa/chain-defaults.js

@@ -10,7 +10,7 @@
 // ⚠️ 均为不可变部署；链上重部署须同步本表。
 // ---------------------------------------------------------------------------
 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.KEEL_BUNDLER_URL = exports.KEEL_USDC_DECIMALS = exports.KEEL_USDC = exports.KEEL_CHAIN_IDS = exports.KEEL_ROOT_VALIDATOR = exports.KEEL_KERNEL_FACTORY = 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");
@@ -23,6 +23,10 @@ exports.KEEL_SESSION_VALIDATOR = '0x8BCB3F5d855F5b2a1f1398690Daaa7866992bDE7';
 exports.KEEL_SESSION_HOOK = '0x466b5DC3796D44b0B63FdF2d3bC7a8Ea371a891F';
 /** KeelTokenPaymaster（三链同址；gas 垫付 + 稳定币结算） */
 exports.KEEL_TOKEN_PAYMASTER = '0x4500A1FbAe335F5E20Fa85C70Daa98a89faD6415';
+/** Kernel v3 factory（三链同址；首笔 createAccount） */
+exports.KEEL_KERNEL_FACTORY = '0xaac5D4240AF87249B3f71BC8E4A2cae074A3E419';
+/** Kernel v3 root validator（ECDSA，三链同址；账户 owner 验签） */
+exports.KEEL_ROOT_VALIDATOR = '0x845ADb2C711129d4f3966735eD98a9F09fC4cE57';
 exports.KEEL_CHAIN_IDS = { base: 8453, bsc: 56, ethereum: 1 };
 /** 各链 USDC（BSC 为 Binance-Peg USDC，18 位） */
 exports.KEEL_USDC = {
@@ -45,6 +49,8 @@ function keelChainConfig(chain, opts = {}) {
         entryPoint: exports.KEEL_ENTRYPOINT_V07,
         rpcUrl: opts.rpcUrl,
         kernelVersion: '0.3.1',
+        kernelFactory: exports.KEEL_KERNEL_FACTORY,
+        rootValidator: exports.KEEL_ROOT_VALIDATOR,
         sessionValidatorCopies: [opts.sessionValidator ?? exports.KEEL_SESSION_VALIDATOR],
         sessionHookCopies: [opts.sessionHook ?? exports.KEEL_SESSION_HOOK],
         bundlers: [

package/dist/aa/index.d.ts

@@ -4,6 +4,7 @@ export * from './nonce';
 export * from './token-paymaster';
 export * from './signer';
 export * from './userop';
+export * from './kernel-account';
 export * from './keel-session';
 export * from './x402';
 export * from './x402-session';

package/dist/aa/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./nonce"), exports);
 __exportStar(require("./token-paymaster"), exports);
 __exportStar(require("./signer"), exports);
 __exportStar(require("./userop"), exports);
+__exportStar(require("./kernel-account"), exports);
 __exportStar(require("./keel-session"), exports);
 __exportStar(require("./x402"), exports);
 __exportStar(require("./x402-session"), exports);

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

@@ -24,6 +24,52 @@ export interface KeelTokenLimit {
 export declare function toKeelRules(policy: SessionPolicy): KeelRule[];
 /** `policyData = abi.encode(version, validAfter, validUntil, Rule[])` */
 export declare function encodeKeelPolicyData(policy: SessionPolicy): Hex;
+/** Kernel.execute selector（安装期的 selectorData，必须恰好 4 字节） */
+export declare const KEEL_SELECTOR_DATA: Hex;
+/** hookData flag：仅未初始化时调 onInstall */
+export declare const KEEL_HOOK_FLAG_IF_UNINITIALIZED: Hex;
+/** hookData flag：强制调 onInstall（同账户轮换/换 key 必须用） */
+export declare const KEEL_HOOK_FLAG_FORCE: Hex;
+/** `enableSession(sessionId, sessionKey, policyData)` 完整 calldata（安装期 validatorData） */
+export declare function encodeKeelEnableData(policy: SessionPolicy): Hex;
+/** hookData = flag(1B) ‖ abi.encode(sessionId, policyData)（Kernel 剥掉首字节后交给 hook） */
+export declare function encodeKeelHookData(policy: SessionPolicy, flag?: Hex): Hex;
+/** 解析 slot 对应的 hook 副本；未配置返回 address(1)（= 不挂 hook）。 */
+export declare function resolveKeelHook(chainConfig: ChainAAConfig, slot: number): Address;
+/** 组装 installModule 的 initData（Kernel v3.1 紧凑布局） */
+export declare function encodeKeelValidatorInstallData(params: {
+    enableData: Hex;
+    hook: Address;
+    hookData: Hex;
+    selectorData?: Hex;
+}): Hex;
+export interface EncodeKeelEnableSessionCallParams {
+    accountAddress: Address;
+    policy: SessionPolicy;
+    chainConfig: ChainAAConfig;
+    /** slot 序号（= validator 副本下标；一 key 一副本） */
+    slot: number;
+    /** 同账户换 key / 轮换必须传 {@link KEEL_HOOK_FLAG_FORCE} */
+    hookFlag?: Hex;
+}
+/**
+ * owner 侧「安装/授权」callData：
+ *   execute( installModule(VALIDATOR, validatorCopy, initData) )
+ * 作为 UserOp.callData 由 owner 签名后提交（root nonce；账户未部署时同笔带 factory）。
+ */
+export declare function encodeKeelEnableSessionCall(p: EncodeKeelEnableSessionCallParams): Hex;
+export interface EncodeKeelUninstallCallParams {
+    accountAddress: Address;
+    chainConfig: ChainAAConfig;
+    slot: number;
+    /** 该 slot 的 sessionId（hook 段 onUninstall 必需） */
+    sessionId: string;
+}
+/**
+ * owner 侧「撤销」callData（validator + hook 两段批量；无 hook 时单段）。
+ * 走 root nonce，owner 裸签 getUserOpHash；**不需要** invalidateNonce。
+ */
+export declare function encodeKeelUninstallCall(p: EncodeKeelUninstallCallParams): Hex;
 /** 解析 slot 对应的 validator 副本地址（缺配置直接抛错，不回退旧模块）。 */
 export declare function resolveKeelValidator(chainConfig: ChainAAConfig, slot: number): Address;
 /** agent 侧签名对象：digest = keccak256(userOpHash ‖ keccak256(policyData)) */
@@ -68,3 +114,60 @@ export interface BuildKeelSessionUserOpParams {
  * 与 aa-sdk 的 `buildKeelSessionUserOp` 逐字节一致（同输入同输出）。
  */
 export declare function buildKeelSessionUserOp(p: BuildKeelSessionUserOpParams): Promise<UserOperationV7>;
+export type UserOpGasOverrides = Partial<Pick<UserOperationV7, 'callGasLimit' | 'verificationGasLimit' | 'preVerificationGas' | 'maxFeePerGas' | 'maxPriorityFeePerGas'>>;
+/** owner 侧草稿：op 未签名；owner 对 `userOpHash` 签名后填入 `op.signature`。 */
+export interface OwnerUserOpDraft {
+    account: Address;
+    op: UserOperationV7;
+    /** owner 需签名的摘要（= EntryPoint.getUserOpHash） */
+    userOpHash: Hex;
+}
+export interface BuildOwnerEnableUserOpParams {
+    /** 未传 nonce（且 deploy 需派生地址）时必须提供 */
+    client?: PublicClient;
+    chainConfig: ChainAAConfig;
+    /** owner EOA（root validator 的 owner） */
+    owner: Address;
+    /** 账户地址；`deploy` 时可省略（用 factory.getAddress 反事实派生） */
+    account?: Address;
+    /** relay `POST /v1/wallet/session` 返回的 enableCallData（优先） */
+    enableCallData?: Hex;
+    /** 或本地由 policy 编码（与 enableCallData 二选一） */
+    policy?: SessionPolicy;
+    /** validator 副本下标 */
+    slot: number;
+    /** 同账户换 key / 轮换传 {@link KEEL_HOOK_FLAG_FORCE} */
+    hookFlag?: Hex;
+    /** 账户未部署时传 true（salt=0）或 `{ salt }`：自动带 factory + factoryData */
+    deploy?: boolean | {
+        salt?: bigint;
+    };
+    nonce?: bigint;
+    gas?: UserOpGasOverrides;
+}
+/**
+ * 首笔 / 后续 owner 授权（enable session）UserOp 构造（未签名）：
+ *   callData = enableCallData ?? execute(installModule(KeelSessionValidator, ...))
+ *   factory  = 仅在 `deploy` 时携带（relay **不会**代部署）
+ *   nonce    = root `getNonce(account, 0)`
+ *   digest   = getUserOpHash(op) → owner 裸签
+ */
+export declare function buildOwnerEnableUserOp(p: BuildOwnerEnableUserOpParams): Promise<OwnerUserOpDraft>;
+export interface BuildOwnerRevokeUserOpParams {
+    /** 未传 nonce 时必须提供 */
+    client?: PublicClient;
+    chainConfig: ChainAAConfig;
+    account: Address;
+    slot: number;
+    sessionId: string;
+    nonce?: bigint;
+    gas?: UserOpGasOverrides;
+}
+/**
+ * owner 撤销（revoke）UserOp 构造（未签名）：
+ *   callData = executeBatch[uninstallModule(VALIDATOR), uninstallModule(HOOK, sessionId)]
+ *   nonce    = root `getNonce(account, 0)`
+ *   digest   = getUserOpHash(op) → owner 裸签
+ * 上链成功后 policy 随 hook.onUninstall 一并清除，**不需要** invalidateNonce。
+ */
+export declare function buildOwnerRevokeUserOp(p: BuildOwnerRevokeUserOpParams): Promise<OwnerUserOpDraft>;

package/dist/aa/keel-session.js

@@ -9,17 +9,26 @@
 // 链上只存 keccak256(policyData) 作为 commitment，因此这里必须逐字节一致。
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KEEL_POLICY_VERSION = void 0;
+exports.KEEL_HOOK_FLAG_FORCE = exports.KEEL_HOOK_FLAG_IF_UNINITIALIZED = exports.KEEL_SELECTOR_DATA = exports.KEEL_POLICY_VERSION = void 0;
 exports.toBytes32 = toBytes32;
 exports.toKeelRules = toKeelRules;
 exports.encodeKeelPolicyData = encodeKeelPolicyData;
+exports.encodeKeelEnableData = encodeKeelEnableData;
+exports.encodeKeelHookData = encodeKeelHookData;
+exports.resolveKeelHook = resolveKeelHook;
+exports.encodeKeelValidatorInstallData = encodeKeelValidatorInstallData;
+exports.encodeKeelEnableSessionCall = encodeKeelEnableSessionCall;
+exports.encodeKeelUninstallCall = encodeKeelUninstallCall;
 exports.resolveKeelValidator = resolveKeelValidator;
 exports.keelSessionDigest = keelSessionDigest;
 exports.encodeKeelSessionSignature = encodeKeelSessionSignature;
 exports.buildKeelSessionUserOp = buildKeelSessionUserOp;
+exports.buildOwnerEnableUserOp = buildOwnerEnableUserOp;
+exports.buildOwnerRevokeUserOp = buildOwnerRevokeUserOp;
 const viem_1 = require("viem");
 const userop_1 = require("./userop");
 const nonce_1 = require("./nonce");
+const kernel_account_1 = require("./kernel-account");
 exports.KEEL_POLICY_VERSION = 1n;
 /** bytes32 归一化（已是 0x+64 hex 直接用，否则左对齐补零） */
 function toBytes32(id) {
@@ -73,6 +82,140 @@ function encodeKeelPolicyData(policy) {
         { type: 'tuple[]', components: KeelRuleTuple },
     ], [exports.KEEL_POLICY_VERSION, policy.validAfter, policy.validUntil, toKeelRules(policy)]);
 }
+// ---------------------------------------------------------------------------
+// owner 侧编码（session 授权安装 / 撤销卸载）
+//
+// 安装 initData（Kernel v3.1 紧凑布局）：
+//   initData = hook(20B) ‖ abi.encode(bytes validatorData, bytes hookData, bytes selectorData)
+//   validatorData = enableSession(sessionId, sessionKey, policyData) 完整 calldata
+//   hookData      = flag(1B) ‖ abi.encode(bytes32 sessionId, bytes policyData)
+//   selectorData  = 0xe9ae5c53（Kernel.execute，恰好 4 字节；长度≠4 时内核静默不 set）
+// ⚠️ flag：0x00 = 仅未初始化时调 onInstall；0xff = 强制（同账户换 key 必须用 0xff）。
+//
+// 撤销 = 一次批量 execute：
+//   ① uninstallModule(VALIDATOR=1, validatorCopy, '0x')
+//   ② uninstallModule(HOOK=4, hookCopy, abi.encode(bytes32 sessionId))
+// 只发①不发②会在 hook 残留 session（union 语义 ⇒ 旧更宽策略仍参与准入）。
+// ---------------------------------------------------------------------------
+/** Kernel.execute selector（安装期的 selectorData，必须恰好 4 字节） */
+exports.KEEL_SELECTOR_DATA = '0xe9ae5c53';
+/** hookData flag：仅未初始化时调 onInstall */
+exports.KEEL_HOOK_FLAG_IF_UNINITIALIZED = '0x00';
+/** hookData flag：强制调 onInstall（同账户轮换/换 key 必须用） */
+exports.KEEL_HOOK_FLAG_FORCE = '0xff';
+const MODULE_TYPE_VALIDATOR = 1n;
+const MODULE_TYPE_HOOK = 4n;
+/** address(1) = Kernel 约定「不挂 hook」 */
+const HOOK_NONE = '0x0000000000000000000000000000000000000001';
+/** KeelSessionValidator.enableSession(bytes32,address,bytes) */
+const KeelSessionValidatorAbi = [
+    {
+        type: 'function',
+        name: 'enableSession',
+        inputs: [
+            { name: 'sessionId', type: 'bytes32' },
+            { name: 'sessionKey', type: 'address' },
+            { name: 'policyData', type: 'bytes' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+];
+/** Kernel 账户自身的 ERC-7579 模块管理方法 */
+const KeelModuleManagerAbi = [
+    {
+        type: 'function',
+        name: 'installModule',
+        inputs: [
+            { name: 'moduleTypeId', type: 'uint256' },
+            { name: 'module', type: 'address' },
+            { name: 'initData', type: 'bytes' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+    {
+        type: 'function',
+        name: 'uninstallModule',
+        inputs: [
+            { name: 'moduleTypeId', type: 'uint256' },
+            { name: 'module', type: 'address' },
+            { name: 'deInitData', type: 'bytes' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+];
+/** `enableSession(sessionId, sessionKey, policyData)` 完整 calldata（安装期 validatorData） */
+function encodeKeelEnableData(policy) {
+    return (0, viem_1.encodeFunctionData)({
+        abi: KeelSessionValidatorAbi,
+        functionName: 'enableSession',
+        args: [toBytes32(policy.sessionId), policy.signer, encodeKeelPolicyData(policy)],
+    });
+}
+/** hookData = flag(1B) ‖ abi.encode(sessionId, policyData)（Kernel 剥掉首字节后交给 hook） */
+function encodeKeelHookData(policy, flag = exports.KEEL_HOOK_FLAG_IF_UNINITIALIZED) {
+    return (0, viem_1.concatHex)([
+        flag,
+        (0, viem_1.encodeAbiParameters)([{ type: 'bytes32' }, { type: 'bytes' }], [toBytes32(policy.sessionId), encodeKeelPolicyData(policy)]),
+    ]);
+}
+/** 解析 slot 对应的 hook 副本；未配置返回 address(1)（= 不挂 hook）。 */
+function resolveKeelHook(chainConfig, slot) {
+    return chainConfig.sessionHookCopies?.[slot] ?? HOOK_NONE;
+}
+/** 组装 installModule 的 initData（Kernel v3.1 紧凑布局） */
+function encodeKeelValidatorInstallData(params) {
+    return (0, viem_1.concatHex)([
+        params.hook,
+        (0, viem_1.encodeAbiParameters)([{ type: 'bytes' }, { type: 'bytes' }, { type: 'bytes' }], [params.enableData, params.hookData, params.selectorData ?? exports.KEEL_SELECTOR_DATA]),
+    ]);
+}
+/**
+ * owner 侧「安装/授权」callData：
+ *   execute( installModule(VALIDATOR, validatorCopy, initData) )
+ * 作为 UserOp.callData 由 owner 签名后提交（root nonce；账户未部署时同笔带 factory）。
+ */
+function encodeKeelEnableSessionCall(p) {
+    const validator = resolveKeelValidator(p.chainConfig, p.slot);
+    const hook = resolveKeelHook(p.chainConfig, p.slot);
+    const initData = encodeKeelValidatorInstallData({
+        enableData: encodeKeelEnableData(p.policy),
+        hook,
+        hookData: encodeKeelHookData(p.policy, p.hookFlag),
+    });
+    return (0, userop_1.encodeExecute)(p.accountAddress, 0n, (0, viem_1.encodeFunctionData)({
+        abi: KeelModuleManagerAbi,
+        functionName: 'installModule',
+        args: [MODULE_TYPE_VALIDATOR, validator, initData],
+    }));
+}
+/**
+ * owner 侧「撤销」callData（validator + hook 两段批量；无 hook 时单段）。
+ * 走 root nonce，owner 裸签 getUserOpHash；**不需要** invalidateNonce。
+ */
+function encodeKeelUninstallCall(p) {
+    const validator = resolveKeelValidator(p.chainConfig, p.slot);
+    const hook = resolveKeelHook(p.chainConfig, p.slot);
+    const uninstallValidator = (0, viem_1.encodeFunctionData)({
+        abi: KeelModuleManagerAbi,
+        functionName: 'uninstallModule',
+        args: [MODULE_TYPE_VALIDATOR, validator, '0x'],
+    });
+    if (hook === HOOK_NONE) {
+        return (0, userop_1.encodeExecute)(p.accountAddress, 0n, uninstallValidator);
+    }
+    const uninstallHook = (0, viem_1.encodeFunctionData)({
+        abi: KeelModuleManagerAbi,
+        functionName: 'uninstallModule',
+        args: [MODULE_TYPE_HOOK, hook, (0, viem_1.encodeAbiParameters)([{ type: 'bytes32' }], [toBytes32(p.sessionId)])],
+    });
+    return (0, userop_1.encodeExecuteBatch)([
+        { target: p.accountAddress, data: uninstallValidator },
+        { target: p.accountAddress, data: uninstallHook },
+    ]);
+}
 /** 解析 slot 对应的 validator 副本地址（缺配置直接抛错，不回退旧模块）。 */
 function resolveKeelValidator(chainConfig, slot) {
     if (!Number.isInteger(slot) || slot < 0) {
@@ -130,3 +273,103 @@ async function buildKeelSessionUserOp(p) {
     const sig = await p.agentSigner.signUserOp(keelSessionDigest(userOpHash, policyData));
     return { ...op, signature: encodeKeelSessionSignature({ sessionId: p.policy.sessionId, policyData, sig }) };
 }
+/** root 通道 nonce：key=0 ⇒ mode=DEFAULT / vType=ROOT。 */
+async function readRootNonce(client, entryPoint, account) {
+    return (await client.readContract({
+        address: entryPoint,
+        abi: ENTRYPOINT_GETNONCE_ABI,
+        functionName: 'getNonce',
+        args: [account, 0n],
+    }));
+}
+/**
+ * 首笔 / 后续 owner 授权（enable session）UserOp 构造（未签名）：
+ *   callData = enableCallData ?? execute(installModule(KeelSessionValidator, ...))
+ *   factory  = 仅在 `deploy` 时携带（relay **不会**代部署）
+ *   nonce    = root `getNonce(account, 0)`
+ *   digest   = getUserOpHash(op) → owner 裸签
+ */
+async function buildOwnerEnableUserOp(p) {
+    if (!p.enableCallData && !p.policy) {
+        throw new Error('[keel-sdk] buildOwnerEnableUserOp: enableCallData 与 policy 至少提供一个');
+    }
+    const deploy = p.deploy === true ? {} : p.deploy;
+    let factory;
+    let factoryData;
+    let account = p.account;
+    if (deploy) {
+        const built = (0, kernel_account_1.encodeKernelFactoryData)(p.chainConfig, p.owner, deploy.salt ?? 0n);
+        factory = built.factory;
+        factoryData = built.factoryData;
+        if (!account) {
+            if (!p.client) {
+                throw new Error('[keel-sdk] buildOwnerEnableUserOp: deploy 且未传 account 时必须提供 client（用于反事实地址预测）');
+            }
+            account = await (0, kernel_account_1.predictAccountAddress)({
+                client: p.client,
+                chainConfig: p.chainConfig,
+                owner: p.owner,
+                salt: deploy.salt ?? 0n,
+            });
+        }
+    }
+    if (!account) {
+        throw new Error('[keel-sdk] buildOwnerEnableUserOp: account 必填（首笔部署请传 deploy: true）');
+    }
+    const callData = p.enableCallData ??
+        encodeKeelEnableSessionCall({
+            accountAddress: account,
+            policy: p.policy,
+            chainConfig: p.chainConfig,
+            slot: p.slot,
+            hookFlag: p.hookFlag,
+        });
+    let nonce = p.nonce;
+    if (nonce === undefined) {
+        if (!p.client) {
+            throw new Error('[keel-sdk] buildOwnerEnableUserOp: 未传 nonce 时必须提供 client');
+        }
+        nonce = await readRootNonce(p.client, p.chainConfig.entryPoint, account);
+    }
+    const op = (0, userop_1.buildUserOpWithCallData)({
+        sender: account,
+        nonce,
+        callData,
+        factory,
+        factoryData,
+        gas: p.gas,
+    });
+    return {
+        account,
+        op,
+        userOpHash: (0, userop_1.getUserOpHash)(op, p.chainConfig.entryPoint, p.chainConfig.chainId),
+    };
+}
+/**
+ * owner 撤销（revoke）UserOp 构造（未签名）：
+ *   callData = executeBatch[uninstallModule(VALIDATOR), uninstallModule(HOOK, sessionId)]
+ *   nonce    = root `getNonce(account, 0)`
+ *   digest   = getUserOpHash(op) → owner 裸签
+ * 上链成功后 policy 随 hook.onUninstall 一并清除，**不需要** invalidateNonce。
+ */
+async function buildOwnerRevokeUserOp(p) {
+    const callData = encodeKeelUninstallCall({
+        accountAddress: p.account,
+        chainConfig: p.chainConfig,
+        slot: p.slot,
+        sessionId: p.sessionId,
+    });
+    let nonce = p.nonce;
+    if (nonce === undefined) {
+        if (!p.client) {
+            throw new Error('[keel-sdk] buildOwnerRevokeUserOp: 未传 nonce 时必须提供 client');
+        }
+        nonce = await readRootNonce(p.client, p.chainConfig.entryPoint, p.account);
+    }
+    const op = (0, userop_1.buildUserOpWithCallData)({ sender: p.account, nonce, callData, gas: p.gas });
+    return {
+        account: p.account,
+        op,
+        userOpHash: (0, userop_1.getUserOpHash)(op, p.chainConfig.entryPoint, p.chainConfig.chainId),
+    };
+}

package/dist/aa/kernel-account.d.ts

@@ -0,0 +1,30 @@
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { ChainAAConfig } from './types';
+/**
+ * 编码 Kernel v3.1 `initialize(...)` calldata。
+ * rootValidator = 0x01 ‖ rootValidator 地址（21B）；validatorData = owner（20B）。
+ */
+export declare function encodeKernelInitialize(chainConfig: ChainAAConfig, owner: Address, rootValidator?: Address): Hex;
+/**
+ * 首笔部署参数：`factory` + `factoryData = createAccount(initializeData, salt)`。
+ * salt 缺省 0（与 relay 的账户派生一致）。
+ */
+export declare function encodeKernelFactoryData(chainConfig: ChainAAConfig, owner: Address, salt?: bigint): {
+    factory: Address;
+    factoryData: Hex;
+};
+/** 从 createAccount 编码中解包 (data, salt) —— 供 factory.getAddress 预测复用。 */
+export declare function unpackFactoryData(factoryData: Hex): {
+    data: Hex;
+    salt: Hex;
+};
+/**
+ * 反事实地址预测：`factory.getAddress(data, salt)` view（纯 CREATE2，无合约创建）。
+ * 不依赖 `EntryPoint.getSenderAddress`（部分 RPC 拒绝 eth_call 内的 CREATE2 模拟）。
+ */
+export declare function predictAccountAddress(params: {
+    client: PublicClient;
+    chainConfig: ChainAAConfig;
+    owner: Address;
+    salt?: bigint;
+}): Promise<Address>;

package/dist/aa/kernel-account.js

@@ -0,0 +1,122 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Kernel v3 账户：factory initData 编码 / 反事实地址预测
+//
+// 首笔 owner 操作（enable session）之前账户通常尚未部署，UserOp 必须携带
+// factory + factoryData，由 EntryPoint 在验证阶段 CREATE2 部署。
+//
+//   initializeData = initialize(
+//     rootValidator,            // bytes21 = 0x01 ‖ ECDSA validator(20B)
+//     hook,                     // address(0) → Kernel 内部归一为 address(1)（不挂 hook）
+//     validatorData,            // owner EOA（20B）
+//     hookData,                 // '0x'
+//     initConfig                // []
+//   )                            // Kernel v3.1+，selector 0x3c3b752b
+//   factoryData    = KernelFactory.createAccount(initializeData, bytes32 salt)
+//
+// ⚠️ 仅支持 Kernel v3.1+（0.3.0-beta 的 initialize 为 4 参数，Keel session 路径不支持）。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeKernelInitialize = encodeKernelInitialize;
+exports.encodeKernelFactoryData = encodeKernelFactoryData;
+exports.unpackFactoryData = unpackFactoryData;
+exports.predictAccountAddress = predictAccountAddress;
+const viem_1 = require("viem");
+const chain_defaults_1 = require("./chain-defaults");
+/** ValidationId 前缀：VALIDATOR 类型（0x01） */
+const VALIDATOR_TYPE_VALIDATOR = '0x01';
+/** Kernel v3.1+：initialize(bytes21, address, bytes, bytes, bytes[]) */
+const KernelV3Init5Abi = [
+    {
+        type: 'function',
+        name: 'initialize',
+        inputs: [
+            { name: '_rootValidator', type: 'bytes21', internalType: 'ValidationId' },
+            { name: 'hook', type: 'address', internalType: 'contract IHook' },
+            { name: 'validatorData', type: 'bytes', internalType: 'bytes' },
+            { name: 'hookData', type: 'bytes', internalType: 'bytes' },
+            { name: 'initConfig', type: 'bytes[]', internalType: 'bytes[]' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+];
+/** KernelFactory.createAccount(bytes data, bytes32 salt) */
+const KernelFactoryAbi = [
+    {
+        type: 'function',
+        name: 'createAccount',
+        inputs: [
+            { name: 'data', type: 'bytes' },
+            { name: 'salt', type: 'bytes32' },
+        ],
+        outputs: [{ name: '', type: 'address' }],
+        stateMutability: 'payable',
+    },
+];
+/** KernelFactory.getAddress(bytes data, bytes32 salt)（纯 CREATE2 计算） */
+const KernelFactoryGetAddressAbi = [
+    {
+        type: 'function',
+        name: 'getAddress',
+        inputs: [
+            { name: 'data', type: 'bytes' },
+            { name: 'salt', type: 'bytes32' },
+        ],
+        outputs: [{ name: '', type: 'address' }],
+        stateMutability: 'view',
+    },
+];
+/**
+ * 编码 Kernel v3.1 `initialize(...)` calldata。
+ * rootValidator = 0x01 ‖ rootValidator 地址（21B）；validatorData = owner（20B）。
+ */
+function encodeKernelInitialize(chainConfig, owner, rootValidator = chainConfig.rootValidator ?? chain_defaults_1.KEEL_ROOT_VALIDATOR) {
+    if (chainConfig.kernelVersion && chainConfig.kernelVersion !== '0.3.1') {
+        throw new Error(`[keel-sdk] encodeKernelInitialize 仅支持 Kernel 0.3.1+，got ${chainConfig.kernelVersion}`);
+    }
+    return (0, viem_1.encodeFunctionData)({
+        abi: KernelV3Init5Abi,
+        functionName: 'initialize',
+        args: [(0, viem_1.concatHex)([VALIDATOR_TYPE_VALIDATOR, rootValidator]), viem_1.zeroAddress, owner, '0x', []],
+    });
+}
+/**
+ * 首笔部署参数：`factory` + `factoryData = createAccount(initializeData, salt)`。
+ * salt 缺省 0（与 relay 的账户派生一致）。
+ */
+function encodeKernelFactoryData(chainConfig, owner, salt = 0n) {
+    const factory = chainConfig.kernelFactory;
+    if (!factory) {
+        throw new Error(`[keel-sdk] missing kernelFactory for chain ${chainConfig.chainId}`);
+    }
+    return {
+        factory,
+        factoryData: (0, viem_1.encodeFunctionData)({
+            abi: KernelFactoryAbi,
+            functionName: 'createAccount',
+            args: [encodeKernelInitialize(chainConfig, owner), (0, viem_1.toHex)(salt, { size: 32 })],
+        }),
+    };
+}
+/** 从 createAccount 编码中解包 (data, salt) —— 供 factory.getAddress 预测复用。 */
+function unpackFactoryData(factoryData) {
+    const body = factoryData.slice(10);
+    const salt = ('0x' + body.slice(64, 128));
+    const dataLen = parseInt(body.slice(128, 192), 16);
+    return { data: ('0x' + body.slice(192, 192 + dataLen * 2)), salt };
+}
+/**
+ * 反事实地址预测：`factory.getAddress(data, salt)` view（纯 CREATE2，无合约创建）。
+ * 不依赖 `EntryPoint.getSenderAddress`（部分 RPC 拒绝 eth_call 内的 CREATE2 模拟）。
+ */
+async function predictAccountAddress(params) {
+    const { factory, factoryData } = encodeKernelFactoryData(params.chainConfig, params.owner, params.salt ?? 0n);
+    const { data, salt } = unpackFactoryData(factoryData);
+    return (await params.client.readContract({
+        address: factory,
+        abi: KernelFactoryGetAddressAbi,
+        functionName: 'getAddress',
+        args: [data, salt],
+    }));
+}

package/dist/aa/types.d.ts

@@ -15,6 +15,10 @@ export interface ChainAAConfig {
     rpcUrl?: string;
     /** Kernel 版本（缺省 '0.3.1'） */
     kernelVersion?: string;
+    /** Kernel v3 factory（首笔部署用；缺省取内置三链默认） */
+    kernelFactory?: Address;
+    /** Kernel v3 root validator（ECDSA；缺省取内置三链默认） */
+    rootValidator?: Address;
     /** Keel(v1) session validator 副本（slot i → 第 i 个；append-only） */
     sessionValidatorCopies?: Address[];
     /** Keel(v1) policy hook 副本（与 validator 成对） */

package/dist/aa/userop.d.ts

@@ -7,6 +7,19 @@ export declare function encodeExecute(target: Address, value: bigint, data: Hex)
  * 挂 KeelPolicyHook 的 session 配置下，Kernel 在验证期强制 callData 以它开头。
  */
 export declare const EXECUTE_USER_OP_SELECTOR: Hex;
+/** 批量执行单条（ERC-7579 Execution = (target, value, data)） */
+export interface Execution {
+    target: Address;
+    value?: bigint;
+    data: Hex;
+}
+/**
+ * BATCH execMode：CALLTYPE_BATCH(0x01) | EXECTYPE_DEFAULT(0x00) → 高 2 字节 0x0100。
+ * 用于 owner 侧撤销（validator + hook 两段一次上链）。
+ */
+export declare const BATCH_EXEC_MODE: Hex;
+/** 编码 Kernel v3 批量调用：execute(BATCH_EXEC_MODE, abi.encode(Execution[])) */
+export declare function encodeExecuteBatch(executions: Execution[]): Hex;
 /** 外层包装：executeUserOp.selector ‖ execute(...)（Route C / 挂真 hook 时必需） */
 export declare function encodeExecuteUserOp(executeCallData: Hex): Hex;
 export interface BuildUserOpWithCallDataParams {

package/dist/aa/userop.js

@@ -6,8 +6,9 @@
 // userOpHash = viem getUserOperationHash（v0.7 EIP-712，含 chainId 防跨链重放）
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXECUTE_USER_OP_SELECTOR = void 0;
+exports.BATCH_EXEC_MODE = exports.EXECUTE_USER_OP_SELECTOR = void 0;
 exports.encodeExecute = encodeExecute;
+exports.encodeExecuteBatch = encodeExecuteBatch;
 exports.encodeExecuteUserOp = encodeExecuteUserOp;
 exports.buildUserOpWithCallData = buildUserOpWithCallData;
 exports.getUserOpHash = getUserOpHash;
@@ -42,6 +43,27 @@ function encodeExecute(target, value, data) {
  * 挂 KeelPolicyHook 的 session 配置下，Kernel 在验证期强制 callData 以它开头。
  */
 exports.EXECUTE_USER_OP_SELECTOR = '0x8dd7712f';
+/**
+ * BATCH execMode：CALLTYPE_BATCH(0x01) | EXECTYPE_DEFAULT(0x00) → 高 2 字节 0x0100。
+ * 用于 owner 侧撤销（validator + hook 两段一次上链）。
+ */
+exports.BATCH_EXEC_MODE = '0x0100000000000000000000000000000000000000000000000000000000000000';
+const ExecutionTuple = [
+    { name: 'target', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'data', type: 'bytes' },
+];
+/** 编码 Kernel v3 批量调用：execute(BATCH_EXEC_MODE, abi.encode(Execution[])) */
+function encodeExecuteBatch(executions) {
+    return (0, viem_1.encodeFunctionData)({
+        abi: KernelV3ExecuteAbi,
+        functionName: 'execute',
+        args: [
+            exports.BATCH_EXEC_MODE,
+            (0, viem_1.encodeAbiParameters)([{ name: 'executions', type: 'tuple[]', components: ExecutionTuple }], [executions.map((e) => ({ target: e.target, value: e.value ?? 0n, data: e.data }))]),
+        ],
+    });
+}
 /** 外层包装：executeUserOp.selector ‖ execute(...)（Route C / 挂真 hook 时必需） */
 function encodeExecuteUserOp(executeCallData) {
     return (0, viem_1.concatHex)([exports.EXECUTE_USER_OP_SELECTOR, executeCallData]);

package/dist/http.d.ts

@@ -1,6 +1,6 @@
 import type { KeelConfig } from './types';
 /** SDK 版本（契约 §5，随包版本同步）。 */
-export declare const SDK_VERSION = "2.3.1";
+export declare const SDK_VERSION = "2.3.2";
 export declare class HttpClient {
     private baseUrl;
     private headers;

package/dist/http.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = exports.SDK_VERSION = void 0;
 const errors_1 = require("./errors");
 /** SDK 版本（契约 §5，随包版本同步）。 */
-exports.SDK_VERSION = '2.3.1';
+exports.SDK_VERSION = '2.3.2';
 /**
  * 钱包签名的复用时长（ms）：首次签名后在该窗口内复用，避免每个请求都触发钱包弹窗。
  * 服务端会话 TTL 为 24h，此处取 1h 留足余量。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelcodes/sdk",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "Keel SDK — unified access to payment / wallet / data / account modules over https://keel.codes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",