@keelcodes/sdk 2.3.1 → 2.4.0

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,7 +4,9 @@ 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-solana';
 export * from './x402-session';
 export * from './bundler';

package/dist/aa/index.js

@@ -23,7 +23,9 @@ __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-solana"), exports);
 __exportStar(require("./x402-session"), exports);
 __exportStar(require("./bundler"), 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/aa/x402-solana.d.ts

@@ -0,0 +1,99 @@
+import type { X402Accept, X402PaymentRequired, X402ResourceInfo } from './x402';
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+export declare const SOLANA_NETWORK_PREFIX = "solana:";
+/** Solana x402 签名域分隔标签。 */
+export declare const SOLANA_X402_DOMAIN = "x402-solana-v2";
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+export declare const SOLANA_X402_ASSET = "sol";
+export interface X402SolanaPaymentPayload {
+    x402Version: 2;
+    resource?: X402ResourceInfo;
+    accepted: X402Accept;
+    payload: {
+        method: string;
+        url: string;
+        /** 重放保护随机串（字符串即可；缺省由 txHash + 时间派生） */
+        salt: string;
+        /** 链上付款交易签名（base58） */
+        txHash: string;
+        /** 付款人公钥（base58） */
+        payer: string;
+    };
+    extensions?: Record<string, unknown>;
+    /** base58(ed25519 signature, 64B) */
+    signature: string;
+}
+/** 链上付款参数：向 `to` 转 `lamports`，原生 SOL。 */
+export interface X402SolanaPayment {
+    to: string;
+    lamports: bigint;
+    asset: typeof SOLANA_X402_ASSET;
+}
+/**
+ * Solana 会话签名器：只需公钥 + 对原始消息签名。
+ * 私钥始终留在客户端（session key / 智能账户），SDK 不接触。
+ */
+export interface X402SolanaSigner {
+    /** base58 公钥（= payload.payer） */
+    publicKey: string;
+    /** 返回 64B 签名：Uint8Array 或 base58 字符串 */
+    signMessage(message: Uint8Array): Promise<Uint8Array | string>;
+}
+export interface PayX402WithSolanaParams {
+    challenge: X402PaymentRequired;
+    /** 不传则自动选第一个 Solana accept */
+    accept?: X402Accept;
+    /** 发起链上转账并返回交易签名（base58） */
+    sendPayment: (payment: X402SolanaPayment) => Promise<{
+        signature: string;
+        payer?: string;
+    }>;
+    signer: X402SolanaSigner;
+    /** 等交易确认（建议传入，避免服务端校验时还查不到） */
+    waitForConfirmation?: (signature: string) => Promise<unknown>;
+    method?: string;
+    url?: string;
+    salt?: string;
+}
+export interface PayX402WithSolanaResult {
+    /** 可直接写入 `PAYMENT-SIGNATURE` 头 */
+    header: string;
+    payload: X402SolanaPaymentPayload;
+    /** 链上付款交易签名（= payload.payload.txHash） */
+    txHash: string;
+    payment: X402SolanaPayment;
+    accept: X402Accept;
+}
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+export declare function encodeBase58(bytes: Uint8Array): string;
+export declare function isSolanaAccept(accept: X402Accept): boolean;
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+export declare function selectSolanaAccept(challenge: X402PaymentRequired, opts?: {
+    network?: string;
+}): X402Accept;
+/** 按 accept 组装转账参数（原生 SOL）。 */
+export declare function buildSolanaX402Payment(accept: X402Accept): X402SolanaPayment;
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+export declare function buildSolanaX402Message(payload: X402SolanaPaymentPayload): Uint8Array;
+/** 由链上付款结果构造未签名的 payload。 */
+export declare function buildSolanaX402Payload(args: {
+    challenge: X402PaymentRequired;
+    accepted: X402Accept;
+    txHash: string;
+    payer: string;
+    method?: string;
+    url?: string;
+    salt?: string;
+}): X402SolanaPaymentPayload;
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+export declare function signX402WithSolanaSession(payload: X402SolanaPaymentPayload, signer: X402SolanaSigner): Promise<string>;
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+export declare function encodeSolanaPaymentSignature(payload: X402SolanaPaymentPayload): string;
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+export declare function payX402WithSolana(params: PayX402WithSolanaParams): Promise<PayX402WithSolanaResult>;

package/dist/aa/x402-solana.js

@@ -0,0 +1,171 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// x402 v2 · Solana（verifyOnly）客户端
+//
+// 结算模型与 EVM 一致：客户端自己广播 SOL 转账，服务端只做「验签 + 链上校验 +
+// 入账」，没有 facilitator `/settle`。
+//
+// 与 payments 服务端（`protocol/x402-v2.ts`）逐字节对齐：
+//   message = ["x402-solana-v2", scheme, network, amount, asset, payTo,
+//              method, url, salt, txHash].join("\n")
+//   header  = base64(JSON({ x402Version, resource, accepted,
+//                 payload:{method,url,salt,txHash,payer}, signature }))
+//
+// EVM 用 EIP-712 把「accepted + payload」绑定到付款人；SVM 没有等价的结构化
+// 签名，改用 ed25519 对上面这条确定性消息签名，payer 由 `payload.payer` 显式给出
+// （ed25519 无法从签名恢复公钥），服务端再用该公钥验签 + 校验链上同址。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOLANA_X402_ASSET = exports.SOLANA_X402_DOMAIN = exports.SOLANA_NETWORK_PREFIX = void 0;
+exports.encodeBase58 = encodeBase58;
+exports.isSolanaAccept = isSolanaAccept;
+exports.selectSolanaAccept = selectSolanaAccept;
+exports.buildSolanaX402Payment = buildSolanaX402Payment;
+exports.buildSolanaX402Message = buildSolanaX402Message;
+exports.buildSolanaX402Payload = buildSolanaX402Payload;
+exports.signX402WithSolanaSession = signX402WithSolanaSession;
+exports.encodeSolanaPaymentSignature = encodeSolanaPaymentSignature;
+exports.payX402WithSolana = payX402WithSolana;
+const x402_1 = require("./x402");
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+exports.SOLANA_NETWORK_PREFIX = 'solana:';
+/** Solana x402 签名域分隔标签。 */
+exports.SOLANA_X402_DOMAIN = 'x402-solana-v2';
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+exports.SOLANA_X402_ASSET = 'sol';
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+function encodeBase58(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = '1'.repeat(zeros);
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += BASE58_ALPHABET[digits[i]];
+    return out;
+}
+function isSolanaAccept(accept) {
+    return (String(accept.network ?? '').startsWith(exports.SOLANA_NETWORK_PREFIX) &&
+        String(accept.asset ?? '').toLowerCase() === exports.SOLANA_X402_ASSET);
+}
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+function selectSolanaAccept(challenge, opts = {}) {
+    const matches = challenge.accepts.filter((a) => isSolanaAccept(a) && (opts.network === undefined || a.network === opts.network));
+    const pick = matches.find((a) => a.scheme === 'exact') ?? matches[0];
+    if (!pick)
+        throw new Error('[keel-sdk] no Solana accept in this x402 challenge');
+    return pick;
+}
+/** 按 accept 组装转账参数（原生 SOL）。 */
+function buildSolanaX402Payment(accept) {
+    if (!isSolanaAccept(accept)) {
+        throw new Error(`[keel-sdk] accept is not Solana native: ${accept.network}/${accept.asset}`);
+    }
+    const lamports = BigInt(accept.amount);
+    if (lamports <= 0n)
+        throw new Error('[keel-sdk] x402 amount must be > 0');
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(accept.payTo)) {
+        throw new Error(`[keel-sdk] invalid Solana payTo: ${accept.payTo}`);
+    }
+    return { to: accept.payTo, lamports, asset: exports.SOLANA_X402_ASSET };
+}
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+function buildSolanaX402Message(payload) {
+    const { accepted } = payload;
+    return new TextEncoder().encode([
+        exports.SOLANA_X402_DOMAIN,
+        accepted.scheme,
+        accepted.network,
+        accepted.amount,
+        accepted.asset,
+        accepted.payTo,
+        payload.payload.method,
+        payload.payload.url,
+        payload.payload.salt,
+        payload.payload.txHash,
+    ].join('\n'));
+}
+/** 由链上付款结果构造未签名的 payload。 */
+function buildSolanaX402Payload(args) {
+    return {
+        x402Version: 2,
+        resource: args.challenge.resource,
+        accepted: args.accepted,
+        payload: {
+            method: args.method ?? 'GET',
+            url: args.url ?? args.challenge.resource?.url ?? '',
+            salt: args.salt ?? `${args.txHash}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+            txHash: args.txHash,
+            payer: args.payer,
+        },
+        signature: '',
+    };
+}
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+async function signX402WithSolanaSession(payload, signer) {
+    if (payload.payload.payer !== signer.publicKey) {
+        throw new Error('[keel-sdk] payload.payer does not match the signing publicKey');
+    }
+    const raw = await signer.signMessage(buildSolanaX402Message(payload));
+    const sig = typeof raw === 'string' ? raw : encodeBase58(raw);
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(sig)) {
+        throw new Error('[keel-sdk] signMessage must return a 64-byte ed25519 signature');
+    }
+    return sig;
+}
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+function encodeSolanaPaymentSignature(payload) {
+    return (0, x402_1.toBase64)(JSON.stringify(payload));
+}
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+async function payX402WithSolana(params) {
+    const accept = params.accept ?? selectSolanaAccept(params.challenge);
+    const payment = buildSolanaX402Payment(accept);
+    const sent = await params.sendPayment(payment);
+    const txHash = String(sent?.signature ?? '').trim();
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(txHash)) {
+        throw new Error(`[keel-sdk] sendPayment must return a base58 tx signature, got ${txHash}`);
+    }
+    const payer = String(sent.payer ?? params.signer.publicKey);
+    if (payer !== params.signer.publicKey) {
+        throw new Error('[keel-sdk] sendPayment payer differs from the x402 signing key');
+    }
+    if (params.waitForConfirmation)
+        await params.waitForConfirmation(txHash);
+    const unsigned = buildSolanaX402Payload({
+        challenge: params.challenge,
+        accepted: accept,
+        txHash,
+        payer,
+        method: params.method,
+        url: params.url,
+        salt: params.salt,
+    });
+    unsigned.signature = await signX402WithSolanaSession(unsigned, params.signer);
+    return {
+        header: encodeSolanaPaymentSignature(unsigned),
+        payload: unsigned,
+        txHash,
+        payment,
+        accept,
+    };
+}

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.4.0";
 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.4.0';
 /**
  * 钱包签名的复用时长（ms）：首次签名后在该窗口内复用，避免每个请求都触发钱包弹窗。
  * 服务端会话 TTL 为 24h，此处取 1h 留足余量。
@@ -88,7 +88,7 @@ class HttpClient {
             return { ...this.headers, ...this.walletToken.headers };
         }
         const timestamp = String(now);
-        const signature = await this.wallet.sign(`InfraX auth: ${timestamp}`);
+        const signature = await this.wallet.sign(`Keel auth: ${timestamp}`);
         const headers = {
             'x-wallet-address': this.wallet.address.toLowerCase(),
             'x-wallet-timestamp': timestamp,

package/dist/wallet/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types';
 export * from './solana-account-types';
 export * from './solana-execution-types';
+export * from './solana-dex-types';
 export * from './mpc-types';
 export * from './wallet-api';
 export * from '../aa';

package/dist/wallet/index.js

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./solana-account-types"), exports);
 __exportStar(require("./solana-execution-types"), exports);
+__exportStar(require("./solana-dex-types"), exports);
 __exportStar(require("./mpc-types"), exports);
 __exportStar(require("./wallet-api"), exports);
 __exportStar(require("../aa"), exports);

package/dist/wallet/solana-dex-types.d.ts

@@ -0,0 +1,136 @@
+import type { SolanaSubmitResult } from './solana-execution-types';
+/** DEX 报价（只读，不构建交易） */
+export interface SolanaDexQuoteParams {
+    chain: string;
+    inputMint: string;
+    outputMint: string;
+    /** base units（十进制整数） */
+    amount: string | number;
+    slippageBps?: number;
+}
+export interface SolanaDexQuoteResult {
+    chain: string;
+    /** Jupiter 原始报价（字段随聚合器版本变化，按需读取） */
+    quote: Record<string, unknown>;
+    inputMint: string;
+    inAmount: string;
+    outputMint: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+}
+/** `ProgramInteraction` policy 安装入参（`/dex/policy` 与 `/dex/install` 通用） */
+export interface SolanaDexPolicyParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    creator: string;
+    settingsPda: string;
+    transactionIndex: string | number;
+    /** policy PDA 的 u64 seed（= 调用前链上 `settings.policySeed + 1`） */
+    seed: string | number;
+    /** 作为 policy 唯一签名者的 session key 公钥 */
+    sessionKey: string;
+    rentPayer?: string;
+    accountIndex?: number;
+    /** 缺省 `[1,2,4]`（Initiate | Vote | Execute） */
+    permissions?: number[];
+    spendingLimits?: Array<{
+        mint: string;
+        /** base units（十进制整数） */
+        maxPerPeriod: string | number;
+        period?: number;
+        start?: string | number;
+        expiration?: string | number;
+    }>;
+    /** 缺省 = relay 配置里的 program 白名单（Jupiter + 直连 DEX + 辅助 program） */
+    constraints?: Array<{
+        programId: string;
+        accountConstraints?: Array<{
+            accountIndex: number;
+            pubkeys: string[];
+            owner?: string;
+        }>;
+        dataConstraints?: Array<{
+            offset: string | number;
+            value?: string;
+            operator?: number;
+        }>;
+    }>;
+    memo?: string;
+}
+/** 安装计划中的一步（未签名交易，按 `steps` 顺序签名广播） */
+export interface SolanaDexInstallStep {
+    step: 'createSettingsTransaction' | 'createProposal' | 'approveProposal' | 'executeSettingsTransaction';
+    /** 需要本地签名的公钥（base58） */
+    signers: string[];
+    instructionCount: number;
+    /** base64（v0） */
+    transaction: string;
+}
+export interface SolanaDexInstallResult {
+    chain: string;
+    policyPda: string;
+    /** 四步共用同一个 blockhash；过期未走完需重新调用 */
+    blockhash: string;
+    steps: SolanaDexInstallStep[];
+}
+export interface SolanaDexSwapParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    /** policy PDA */
+    policy: string;
+    /** smart account（vault）PDA */
+    vaultPda: string;
+    sessionKey: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string | number;
+    accountIndex?: number;
+    numSigners?: number;
+    slippageBps?: number;
+    wrapAndUnwrapSol?: boolean;
+    dynamicComputeUnitLimit?: boolean;
+    /**
+     * policy 创建时 `instructionsConstraints` 的顺序（programId 数组）。
+     * 缺省取 relay 配置白名单顺序；链上要求逐条指令都能映射到一条约束。
+     */
+    policyPrograms?: string[];
+}
+export interface SolanaDexSwapResult {
+    chain: string;
+    inAmount: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+    innerInstructionCount: number;
+    instructionConstraintIndices: number[];
+    addressLookupTables: number;
+    transactionBytes: number;
+    /** 未签名交易（base64 v0）；签名后经 `submit` 广播才会计费 */
+    transaction: string;
+    instructionCount?: number;
+    /** 计费提示：签名后发到该端点，relay 按 fee payer 收固定服务费 */
+    billing?: {
+        endpoint: string;
+        feePayer: string;
+        feeLamports: string;
+    };
+}
+/**
+ * 本地签名回调：入参为未签名交易（base64 v0）与需要签名的公钥，
+ * 返回已签名的 base64 交易。SDK 不内置 Solana 依赖，由调用方用
+ * `@solana/web3.js`（`VersionedTransaction.deserialize` → `sign`）实现。
+ */
+export type SolanaTransactionSigner = (transaction: string, signers: string[]) => Promise<string> | string;
+/** `dexSwapAndSubmit`：一次完成「取未签名交易 → 本地签名 → 经 relay 计费广播」。 */
+export interface SolanaDexSwapAndSubmitParams extends SolanaDexSwapParams {
+    sign: SolanaTransactionSigner;
+}
+export interface SolanaDexSwapAndSubmitResult extends SolanaDexSwapResult {
+    /** relay `/submit` 的广播回执（计费发生在这里） */
+    submit: SolanaSubmitResult;
+}

package/dist/wallet/solana-dex-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wallet/wallet-api.d.ts

@@ -3,6 +3,7 @@ import type { KeelEnvelope } from '../types';
 import type { CreateWalletParams, WalletCreated, ImportWalletParams, SignParams, SignResult, SendParams, SendResult, ChainParams, ChainResult, WalletBalanceParams, WalletBalanceResult, SessionCreateParams, SessionCreated, PaymasterInfo, PaymasterVoucherParams, PaymasterVoucher } from './types';
 import type { SolanaDeriveAccountParams, SolanaDerivedAccount, SolanaCreateAccountParams, SolanaInstallPolicyParams, SolanaCreatePolicyTransactionParams, SolanaCreateProposalParams, SolanaApproveProposalParams, SolanaExecutePolicyTransactionParams, SolanaRemovePolicyParams } from './solana-account-types';
 import type { SolanaExecutePolicyPayloadParams, SolanaCloseSettingsParams, SolanaCloseTransactionParams, SolanaExecutePolicyParams, SolanaExecuteParams, SolanaRemoveSignerParams, SolanaSubmitParams, SolanaUnsignedTransaction, SolanaSubmitResult } from './solana-execution-types';
+import type { SolanaDexQuoteParams, SolanaDexQuoteResult, SolanaDexPolicyParams, SolanaDexInstallResult, SolanaDexSwapParams, SolanaDexSwapResult, SolanaDexSwapAndSubmitParams, SolanaDexSwapAndSubmitResult } from './solana-dex-types';
 import type { MpcSendCodeParams, MpcVerifyParams, MpcBalanceParams, MpcSignMessageParams, MpcSignTypedDataParams, MpcSendTransactionParams, MpcContractCallParams, MpcContractWriteParams, MpcGasEstimateParams, MpcRegisterParams, MpcRegisterResult, MpcSolanaSignParams, MpcSolanaSignResult, MpcSolanaSendParams, MpcSolanaSendResult } from './mpc-types';
 export declare class WalletAPI {
     private http;
@@ -171,6 +172,18 @@ export declare class WalletAPI {
             execute: (p: SolanaExecuteParams) => Promise<SolanaUnsignedTransaction>;
             removeSigner: (p: SolanaRemoveSignerParams) => Promise<SolanaUnsignedTransaction>;
             submit: (p: SolanaSubmitParams) => Promise<SolanaSubmitResult>;
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p: SolanaDexQuoteParams) => Promise<SolanaDexQuoteResult>;
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p: SolanaDexPolicyParams) => Promise<SolanaDexInstallResult>;
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            dexSwap: (p: SolanaDexSwapParams) => Promise<SolanaDexSwapResult>;
+            /**
+             * DEX：一步完成 swap —— 取未签名交易 → `sign` 回调本地签名 → 经 `/submit` 广播。
+             * `sign` 由调用方提供（SDK 不内置 Solana 依赖），例如：
+             * `(b64) => { const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64')); tx.sign([kp]); return Buffer.from(tx.serialize()).toString('base64') }`
+             */
+            dexSwapAndSubmit: (p: SolanaDexSwapAndSubmitParams) => Promise<SolanaDexSwapAndSubmitResult>;
         };
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */

package/dist/wallet/wallet-api.js

@@ -153,6 +153,24 @@ class WalletAPI {
             execute: (p) => this.http.post('/v1/wallet/session/solana/session/execute', p),
             removeSigner: (p) => this.http.post('/v1/wallet/session/solana/session/remove-signer', p),
             submit: (p) => this.http.post('/v1/wallet/session/solana/submit', p),
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p) => this.http.post('/v1/wallet/session/solana/dex/quote', p),
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p) => this.http.post('/v1/wallet/session/solana/dex/install', p),
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            dexSwap: (p) => this.http.post('/v1/wallet/session/solana/dex/swap', p),
+            /**
+             * DEX：一步完成 swap —— 取未签名交易 → `sign` 回调本地签名 → 经 `/submit` 广播。
+             * `sign` 由调用方提供（SDK 不内置 Solana 依赖），例如：
+             * `(b64) => { const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64')); tx.sign([kp]); return Buffer.from(tx.serialize()).toString('base64') }`
+             */
+            dexSwapAndSubmit: async (p) => {
+                const { sign, ...swap } = p;
+                const built = await this.http.post('/v1/wallet/session/solana/dex/swap', swap);
+                const signed = await sign(built.transaction, [...new Set([swap.feePayer, swap.sessionKey])]);
+                const submit = await this.http.post('/v1/wallet/session/solana/submit', { chain: swap.chain, transaction: signed });
+                return { ...built, submit };
+            },
         },
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */

package/package.json

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