0.2.1

@0xinfrax/aa-sdk

InfraX 共享 ERC-4337 智能账户 SDK（白标自 InfraX @0xinfrax/aa-sdk）——Kernel v3 + UserOp v0.7 + Bundler + Paymaster + Session Key。

• npm: @0xinfrax/aa-sdk@0.2.0（0.2.0 新增内置多链 AA 栈地址常量 src/chain-defaults.ts + aaChainSupported()——外部消费方（如 Actora 网关）无需再手工维护地址表，未配置的地址类 env 由内置默认补齐；同版把 AA_<CHAIN>_BUNDLERS 由「配置点必填」改为「使用点必填」——缺该 env 时 getChainConfig 返回 bundlers: [] 不抛错，仅在 BundlerClient 发直连 UserOp / 估 gas 时报错，经 aa-relay 提交的调用方无需配置；0.1.3 新增 src/escrow.ts InfraXEscrow 充值构建 helper——depositFor 等编码 + UserOp（REQ-1/REQ-5，AgentX 自动续订资金）；0.1.2 发布三段批量 disable 等 session 新导出；0.1.1 补 PaymasterClient/BundlerClient 自定义 headers——relay 模式注入 X-API-Key；@infrax scope 私有发布需付费订阅，故用 @0xinfrax scope + --access public）
• 文档: docs/AA_SDK_TECH_DESIGN.md（技术方案）、docs/PAYMASTER_PROVISION_REQUEST.md §八（InfraX 对接与公网入口）
• 关联包: @0xinfrax/session-key-core（Aa 命名空间导出同源能力，v0.2.1 已发布）——两通道并存，按需选用

安装

npm install @0xinfrax/aa-sdk
# peerDependencies: viem >=2.0.0、permissionless >=0.2.0（需一并安装）
npm install viem@^2 permissionless@^0.2

type: module，产物 dist/（43 files），含类型声明。

快速开始

import { createKernelAccount, createAAClient, getChainConfig, MpcSigner } from '@0xinfrax/aa-sdk';

const cfg = getChainConfig('oxachain', process.env); // 从 AA_OXACHAIN_* env 加载
const signer = new MpcSigner(address, 'https://.../api/v2/mpc', { email }); // 或 token 模式
const account = await createKernelAccount({ owner: signer, chainConfig: cfg });
const client = createAAClient({ account, chainConfig: cfg });

环境变量（链配置，内置默认 + env 覆盖）

链别名 → chainId：oxachain:19505、base-sepolia:84532、base:8453、arbitrum:42161、optimism:10、polygon:137、ethereum:1、bsc:56。

内置多链默认地址表（0.2.0+，src/chain-defaults.ts）

bsc(56) / ethereum(1) / base(8453) / oxachain(19505) 的 AA 栈地址已内置，外部消费方无需再手工维护地址表：

• 优先级：env > 内置默认 > 既有全局兜底（如 AA_ENTRYPOINT_V07 → DEFAULT_ENTRYPOINT_V07）。env 存在时行为与旧版本完全一致；env 缺失时用内置默认补齐。
• AA_<CHAIN>_RPC_URL 仍为必填（链上读写通用依赖，getChainConfig 阶段抛错）。
• AA_<CHAIN>_BUNDLERS 为「使用点必填」（0.2.0 起）：getChainConfig 缺该 env 时给 bundlers: [] 不抛错，由真正发直连 UserOp 的使用点报错 —— BundlerClient.sendUserOperation() / estimateUserOperationGas() 抛 BundlerError: no bundler endpoints configured (chain <id>)。这样「显式传自建 chainConfig、只做地址预测 / 构建 UserOp / 算 hash」的消费方无需配置 bundler；而「本该直连」的路径缺配置时明确报错，不会静默退化到 relay。（JSON 非法且非纯 URL 仍在 getChainConfig 抛错。）
• provenance：entryPoint/implementation/factory/ecdsaValidator 为 ZeroDev 官方确定性部署（bsc/ethereum/base 三链同址）；sessionModule 为 infraX 自研自部署（四链异址）。均为不可变部署，链上重部署须同步本表。
• ⚠️ sessionSigMode 随地址一并内置：bsc/ethereum/base = payload（自研模块仅存 permissionsHash，缺省 onchain 会静默 AA24）；oxachain = onchain。env 显式设置时仍以 env 为准（非法值报错）。

aaChainSupported()：链支持预检（不抛错）

import { aaChainSupported } from '@0xinfrax/aa-sdk';

aaChainSupported('base');      // true（有内置默认）
aaChainSupported('polygon');   // false（已知别名，但无内置地址且 env 未提供）
aaChainSupported('unknown');   // false（不抛错）

返回 true 当且仅当「链别名已知 且 该链的 sessionModule 与 validatorAddress 可解析（内置或 env 提供）」。⚠️ 不检查 RPC / BUNDLERS：缺 RPC 在 getChainConfig 抛错；缺 BUNDLERS 则在发直连 UserOp 时由 BundlerClient 抛错（见上）。

Paymaster（代付，可选）

平台默认"用户自充"；开启 sponsor 时经 aa-relay 代理（服务端持有 apikey）：

import { PaymasterClient } from '@0xinfrax/aa-sdk';

const pm = new PaymasterClient(
  { type: 'verifying', url: 'https://rpc-gw.0xainet.top/aa-relay/v1/paymaster' },
  'https://rpc-gw.0xainet.top/aa-relay',   // relay 代理模式：{chain, method, params}
  { 'X-API-Key': AA_RELAY_KEY },          // v0.1.1：自定义 headers（relay 鉴权必需）
);
const stub = await pm.getPaymasterStubData(op, { chain: 'oxachain', entryPoint, chainId: 19505 });
const data  = await pm.getPaymasterData(op, { chain: 'oxachain', entryPoint, chainId: 19505 });

自定义 headers 支持（v0.1.1，InfraX 联调反馈 ⑤）：

• PaymasterClient：构造第三参数 headers，或 PaymasterConfig.headers（config 优先）；relay 模式下注入 X-API-Key 过 aa-relay 鉴权
• BundlerClient：构造第二参数 headers，或 BundlerConfig[].headers（端点级优先）；注入到所有 RPC 请求（send/estimate/receipt 轮询）
• env 形态：AA_{CHAIN}_PAYMASTER_URL 支持 JSON {"url":"...","headers":{"X-API-Key":"..."}}；AA_{CHAIN}_BUNDLERS 数组项支持 "headers" 字段

关键导出（barrel dist/index.d.ts）

• 配置：getChainConfig / getEnabledChains / getAllChainConfigs / parseBundlers / parsePaymaster / entryPointAbi（EntryPoint v0.7 getNonce(address,uint192)）
• 账户：createKernelAccount / createAAClient / activateSmartAccount
• 交易：buildUserOp / signUserOp / estimateUserOpGas / userOpToRpc / PackedUserOperationV7
• 充值（0.1.3，InfraXEscrow，REQ-1/REQ-5）：InfraXEscrowAbi / encodeDepositFor / encodeDepositForBatch / encodeDepositForERC20 / encodeDepositForERC20Batch / buildDepositForUserOp / buildDepositForBatchUserOp / buildDepositForERC20UserOp / buildDepositForERC20BatchUserOp
• 客户端：BundlerClient / PaymasterClient
• 签名器：MpcSigner（email/token 双模式）/ PrivateKeySigner / ExternalWalletSigner / SessionKeySigner
• Session（enable）：encodeEnableSessionCall / buildEnableSessionUserOp / signEnableUserOp / buildSessionUserOp / validateSessionCall / SessionPolicy / SessionPermission
• Session（disable/轮换，0.1.2）：buildDisableSessionUserOp（三段批量 draft：disableSession@module + uninstallModule + invalidateNonce）/ encodeDisableSessionBatch / encodeValidatorInstallData / KernelV3SessionDataBuilder / MODULE_TYPE_VALIDATOR / isSessionModuleInstalled / verifyDisableSignature
• 类型：ChainAAConfig / BundlerConfig / PaymasterConfig / UserOperationV7 / Signer / AAError / isAAError

⚠️ 遗留单调用 encodeDisableSessionCall 已于 2026-08-20 移除：仅 uninstallModule 不删 session 记录（onUninstall 空实现），旧 key 可复用。撤销/轮换一律用 encodeDisableSessionBatch（三段批量）。

aa-relay 公网入口

https://rpc-gw.0xainet.top/aa-relay/（nginx → aa-relay :9131；上游强制 X-API-Key 鉴权）

端口说明：9131 = aa-relay 网关（对外入口）；9134 = 内部 signer（aa-paymaster 签名服务，仅内网不可直连，由 aa-relay 代理）。

测试

npm test        # vitest（149/149 绿）
npm run build   # tsc → dist/