@aastar/sdk 0.20.3 → 0.20.5

package/README.md

@@ -4,7 +4,7 @@ The ultimate TypeScript SDK for the AAstar Protocol - a decentralized, community
 AAstar 协议的终极 TypeScript SDK —— 构建去中心化、社区驱动的账户抽象生态系统。
 
 [![npm version](https://img.shields.io/npm/v/@aastar/sdk.svg)](https://www.npmjs.com/package/@aastar/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 ---
 
@@ -36,7 +36,10 @@ AAstar SDK 提供了一套完整的工具集用于交互 AAstar 协议。它采
 | `@aastar/sdk/x402` | x402 settlement (x402 结算) |
 | `@aastar/sdk/channel` | Micro-payment channels (微支付通道) |
 | `@aastar/sdk/enduser` · `/operator` · `/admin` | Role lifecycle workflows (角色生命周期) |
-| `@aastar/sdk/airaccount` | KMS WebAuthn passkeys, BLS aggregate signatures, tiered ERC-4337 accounts (Passkey + BLS + 分层签名) |
+| `@aastar/sdk/kms` | KMS WebAuthn passkeys, BLS aggregate signatures, tiered ERC-4337 accounts (Passkey + BLS + 分层签名) |
+
+> 🔄 The `@aastar/sdk/airaccount` subpath is **deprecated** — it still works as an alias of `@aastar/sdk/kms` for one release. Please migrate to `@aastar/sdk/kms`.
+> `@aastar/sdk/airaccount` 子路径已**废弃**，作为 `@aastar/sdk/kms` 的别名再保留一个版本，请尽快迁移到 `@aastar/sdk/kms`。
 
 > ⚠️ **`react` / `react-dom` are optional peer deps.** They're only needed for the `@aastar/sdk/dapp`
 > subpath. The root `import '@aastar/sdk'` and all non-UI subpaths work in Node/server with no React.
@@ -47,16 +50,16 @@ AAstar SDK 提供了一套完整的工具集用于交互 AAstar 协议。它采
 ## 📦 Installation | 安装
 
 ```bash
-pnpm add @aastar/sdk viem ethers
+pnpm add @aastar/sdk viem
 # or
-npm install @aastar/sdk viem ethers
+npm install @aastar/sdk viem
 
 # Only if you use the React UI subpath (@aastar/sdk/dapp):
 pnpm add react react-dom
 ```
 
-> AirAccount / KMS / BLS features are included — no separate install. Import them from `@aastar/sdk/airaccount`.
-> AirAccount / KMS / BLS 能力已内置，无需单独安装，从 `@aastar/sdk/airaccount` 导入即可。
+> You only need `@aastar/sdk` + `viem` — all transitive deps install automatically. KMS / WebAuthn / BLS features are bundled in — no separate install. Import them from `@aastar/sdk/kms`.
+> 只需安装 `@aastar/sdk` + `viem`，其余依赖自动带入。KMS / WebAuthn / BLS 能力已内置，无需单独安装，从 `@aastar/sdk/kms` 导入即可。
 
 ### Importing | 导入方式
 
@@ -66,7 +69,7 @@ import { createEndUserClient, createOperatorClient, CANONICAL_ADDRESSES } from '
 
 // …or cherry-pick from a subpath to keep bundles lean:
 import { registryActions } from '@aastar/sdk/core';
-import { KmsManager, P256PasskeySigner } from '@aastar/sdk/airaccount';
+import { KmsManager, P256PasskeySigner } from '@aastar/sdk/kms';
 import { useGasless } from '@aastar/sdk/dapp'; // requires react
 ```
 
@@ -74,37 +77,43 @@ import { useGasless } from '@aastar/sdk/dapp'; // requires react
 
 ## 🌐 Multi-chain | 多链配置
 
-Contract addresses are keyed by **chainId** in `CANONICAL_ADDRESSES`, so switching chains means
-switching the viem `chain` + `transport` and passing the matching address set.
-合约地址在 `CANONICAL_ADDRESSES` 中按 **chainId** 分组，切链 = 切换 viem `chain` + `transport` 并传入对应链的地址集。
+**Switching chains is seamless — just pass a viem `chain`.** Contract addresses are auto-resolved
+from `chain.id`, so you never hardcode addresses or memorize chainIds. Use the exact chain objects
+from `viem/chains`.
+切链是无感的——**只需传入一个 viem `chain`**，合约地址会根据 `chain.id` 自动解析，无需手写地址、无需记 chainId。直接用 `viem/chains` 里的链对象即可。
 
-| Network | chainId | Status |
-|---|---|---|
-| Optimism (mainnet) | `10` | ✅ deployed |
-| Sepolia (testnet) | `11155111` | ✅ deployed (primary test target) |
-| OP Sepolia (testnet) | `11155420` | ✅ deployed |
-| Ethereum mainnet | `1` | ⏳ not yet deployed |
+| Network | viem chain | chainId | Status |
+|---|---|---|---|
+| Optimism (mainnet) | `optimism` | `10` | ✅ deployed |
+| Sepolia (testnet) | `sepolia` | `11155111` | ✅ deployed (primary test target) |
+| OP Sepolia (testnet) | `optimismSepolia` | `11155420` | ✅ deployed |
+| Ethereum mainnet | `mainnet` | `1` | ⏳ not yet deployed |
 
 ```typescript
-import { createEndUserClient, CANONICAL_ADDRESSES } from '@aastar/sdk';
+import { createEndUserClient } from '@aastar/sdk';
 import { sepolia, optimism } from 'viem/chains';
 import { http } from 'viem';
 
-// Sepolia testnet
+// Sepolia testnet — addresses auto-resolved from sepolia.id
 const test = createEndUserClient({
   chain: sepolia,
   transport: http(process.env.SEPOLIA_RPC_URL),
-  addresses: CANONICAL_ADDRESSES[11155111],
 });
 
-// Optimism mainnet — same code, just swap chain + transport + address set
+// Optimism mainnet — same code, just swap chain + transport
 const prod = createEndUserClient({
   chain: optimism,
   transport: http('https://mainnet.optimism.io'),
-  addresses: CANONICAL_ADDRESSES[10],
 });
 ```
 
+- **Unsupported chain?** If you pass a chain that has no deployment yet (e.g. `mainnet`) and no
+  explicit `addresses`, the factory throws a clear error naming the supported chains — no silent
+  misconfiguration.
+- **Custom / private deployment?** Override per-call with `addresses: { ... }` (or `CANONICAL_ADDRESSES[chainId]`
+  to start from a known set); the explicit value always wins over auto-resolution.
+- 未部署的链（如 `mainnet`）且未显式传 `addresses` 时，工厂会抛出列明受支持链的清晰报错；自定义部署可通过 `addresses` 覆盖，显式值优先。
+
 Helpers for RPC URLs and explorer links live in `@aastar/sdk` too:
 `getNetwork(name)`, `getRpcUrl(name)`, `getChainId(name)`, `getTxUrl(name, hash)`, `getAddressUrl(name, addr)`.
 
@@ -131,23 +140,22 @@ Helpers for RPC URLs and explorer links live in `@aastar/sdk` too:
 import { http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { sepolia } from 'viem/chains';
-import { createEndUserClient, createOperatorClient, CANONICAL_ADDRESSES } from '@aastar/sdk';
+import { createEndUserClient, createOperatorClient } from '@aastar/sdk';
 
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 
 // Role-based clients compose viem action factories under the hood.
+// Addresses auto-resolve from chain.id — no `addresses` needed for supported chains.
 const enduser = createEndUserClient({
   chain: sepolia,
   transport: http(process.env.SEPOLIA_RPC_URL),
   account,
-  addresses: CANONICAL_ADDRESSES[11155111],
 });
 
 const operator = createOperatorClient({
   chain: sepolia,
   transport: http(process.env.SEPOLIA_RPC_URL),
   account,
-  addresses: CANONICAL_ADDRESSES[11155111],
 });
 ```
 
@@ -237,7 +245,7 @@ All capabilities are bundled into `@aastar/sdk`; the table below maps each forme
 | `@aastar/sdk/identity` | Reputation, Credit limits, ZK Proofs |
 | `@aastar/sdk/paymaster` | EntryPoint & Paymaster low-level API |
 | `@aastar/sdk/dapp` | React Components & Integration Hooks (needs `react`) |
-| `@aastar/sdk/airaccount` | KMS WebAuthn, BLS Signatures, ERC-4337 Tiered Accounts |
+| `@aastar/sdk/kms` | KMS WebAuthn, BLS Signatures, ERC-4337 Tiered Accounts (`/airaccount` = deprecated alias) |
 
 ---
 

package/dist/UserClient-UYIHF6UJ.js

@@ -0,0 +1,6 @@
+export { UserClient } from './chunk-FIS3RUGL.js';
+import './chunk-TIH7D4FQ.js';
+import './chunk-NRH56SAJ.js';
+import './chunk-PZ5AY32C.js';
+//# sourceMappingURL=UserClient-UYIHF6UJ.js.map
+//# sourceMappingURL=UserClient-UYIHF6UJ.js.map

package/dist/{UserClient-JMNNZT4P.js.map → UserClient-UYIHF6UJ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"UserClient-JMNNZT4P.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"UserClient-UYIHF6UJ.js"}

package/dist/account.js

@@ -1,6 +1,6 @@
-export { UserOpClient, createEOAWalletClient, getUserOpHash, packUserOpLimits, toSimpleSmartAccount } from './chunk-YSDWB6DO.js';
-import './chunk-TBDMSJVL.js';
-import './chunk-ZJLIKMCA.js';
+export { UserOpClient, createEOAWalletClient, getUserOpHash, packUserOpLimits, toSimpleSmartAccount } from './chunk-FBDMID2J.js';
+import './chunk-TIH7D4FQ.js';
+import './chunk-NRH56SAJ.js';
 import './chunk-PZ5AY32C.js';
 //# sourceMappingURL=account.js.map
 //# sourceMappingURL=account.js.map

package/dist/admin.js

@@ -1,6 +1,6 @@
-export { ProtocolGovernance } from './chunk-5TDDS3T5.js';
-import './chunk-TBDMSJVL.js';
-import './chunk-ZJLIKMCA.js';
+export { ProtocolGovernance } from './chunk-ZFIKBDBT.js';
+import './chunk-TIH7D4FQ.js';
+import './chunk-NRH56SAJ.js';
 import './chunk-PZ5AY32C.js';
 //# sourceMappingURL=admin.js.map
 //# sourceMappingURL=admin.js.map