@zan_team/cli 0.0.5 → 0.0.6-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zan_team/cli",
-  "version": "0.0.5",
+  "version": "0.0.6-beta.0",
   "description": "Unified ZAN command-line interface for developers, automation, and AI agents",
   "type": "module",
   "bin": {
@@ -35,8 +35,15 @@
     "release:beta": "tsx scripts/release.ts --kind=beta"
   },
   "dependencies": {
+    "@scure/bip39": "^2.4.0",
+    "@solana-program/address-lookup-table": "^0.15.0",
+    "@solana-program/compute-budget": "^0.19.0",
+    "@solana-program/system": "^0.15.0",
+    "@solana/kit": "^8.4.0",
     "commander": "^14.0.3",
     "cross-keychain": "^1.1.0",
+    "lossless-json": "^4.3.1",
+    "micro-key-producer": "^0.10.2",
     "qrcode-terminal": "^0.12.0",
     "viem": "^2.56.3",
     "yaml": "^2.9.0",

package/skills/zan-cli/SKILL.md

@@ -43,7 +43,7 @@ zan --json --no-interactive --project <project-id> --network <network-id> evm rp
 
 用户选择创建时确定名称，执行 `project create --name <name>`，使用返回的 ID。不要未经选择自动创建项目。创建不会自动切换 Project。
 
-确定后执行 `project use <project-id>`，验证项目并建立加密 Endpoint 缓存；再执行 `--project <project-id> evm networks` 获取可用 Network。按用户指定的链、主网/测试网匹配实际 Network ID；有歧义再询问，不猜 ID。后续命令显式带所选 `--project`，链上调用同时带 `--network`，避免残留环境变量切换上下文。只有用户需要持久默认 Network 时才执行 `settings set network <id>`。
+确定后执行 `project use <project-id>`，验证项目并建立加密 Endpoint 缓存；再按链执行 `--project <project-id> evm networks` 或 `--project <project-id> solana networks` 获取 Network。按用户指定的链、主网/测试网匹配实际 Network ID；有歧义再询问，不猜 ID。后续命令显式带所选 `--project`，链上调用同时带 `--network`，避免残留环境变量切换上下文。只有用户需要持久默认 Network 时才执行 `settings set network <id>`。
 
 凭据存储由 CLI 管理：包含服务端 API Key 的 Endpoint 数据保存在本地加密缓存中，缓存加密密钥保存在系统凭据库（macOS Keychain）。不要把这理解为必须先将 API Key 导出到文件，Agent 也不需要读取这些凭据。
 
@@ -68,7 +68,11 @@ Key 累计用量当作共享套餐周期用量。无 Key 限额不代表套餐
 
 调用 RPC 前先读 [文档到 CLI 的映射](references/rpc-workflow.md)，再检索并打开 [ZAN 官方文档](https://docs.zan.top) 中对应链和方法的页面。核对方法名、参数顺序与类型、单位、Network 支持情况和返回字段；当前会话已核对同一方法时可复用。CLI 的语法以当前 manifest / 帮助为准。不要把文档中的 curl 命令或完整 JSON-RPC 请求体直接当作 CLI 参数。
 
-如果工作需要消息或交易签名，先按 [钱包与签名](references/signing.md) 让用户选择 ZAN CLI 钱包模块或其他密钥/签名方式，再完成相应配置。普通只读查询不需要钱包。API Key 用于 ZAN API 访问，不是钱包私钥。
+Solana 查询使用 `zan --json --no-interactive inspect --family solana` 检查本链默认配置；`solana networks` 列出 mainnet/testnet，不包含 devnet。目录表示已配置路由，实际 Key 权限和额度由请求结果决定。设置 Solana 默认网络不会更改 EVM 默认网络。普通查询使用 `solana data balance`、`solana data tokens`、`solana account`、`solana tx`、`solana tx status`、`solana block`、`solana fees` 或 `solana rpc`，无需配置钱包。
+
+如果工作需要消息或交易签名，先按 [钱包与签名](references/signing.md) 让用户选择 ZAN CLI 钱包模块或其他密钥/签名方式，再完成相应配置。普通只读查询不需要钱包。助记词导入不指定链，存入系统凭据库供后续派生；不要让用户在聊天中提供助记词、passphrase 或私钥。Solana 本地消息签名使用 solana sign，EVM 保留 zan sign。API Key 用于 ZAN API 访问，不是钱包私钥。
+
+Solana 交易、通用指令、Tips/Points 与超时恢复按 [Solana transactions](references/solana-transactions.md) 执行。签名与广播授权分别确认；只读数据获取不进入付费发送流程。
 
 ## 4. 执行与排错
 

package/skills/zan-cli/references/rpc-workflow.md

@@ -31,3 +31,18 @@ Hyperliquid 选择实际返回的 `ecosystem: hyperliquid` Network。JSON-RPC /
 本节仅适用于项目应用代码直接调用 ZAN API。代码若只是通过 CLI 获取数据，继续使用 CLI 的凭据管理，不需要导出 Key。直接调用 API 的代码按对应文档组装接口及请求，在运行时从目标项目 `.env` 的 `ZAN_API_KEY` 读取认证值。Agent 不需要知道真实 Key：只编写读取变量的代码，由 CLI 的 `project rpc-key pull` 完成写入。不要为了复现文档示例把实际 Key 拼进 Agent 执行的 curl 参数或粘贴到文档网站的在线调试器。
 
 所选 Network 与文档的主网/测试网、生态和接口路径必须对应；URL 路径中的生态标识不一定等于 CLI Network ID。结果按文档解释单位、编码和不存在时的语义，不能把 RPC 调用成功当作业务结果符合预期。
+
+## Solana 查询
+
+根据当前 manifest 选择 Solana 命令，显式携带用户确定的项目与网络，例如：
+
+```sh
+zan --json --no-interactive --project <project-id> --network solana-testnet solana data balance <address>
+zan --json --no-interactive --project <project-id> --network solana-mainnet solana rpc getBalance '"11111111111111111111111111111111"' '{"commitment":"confirmed"}'
+```
+
+Base58 地址不是 EVM 地址；区块查询使用十进制 slot，不是 block height。默认 commitment 为 confirmed，交易详情和区块只接受 confirmed/finalized。Token 查询分别获取 SPL Token、Token-2022 账户，不承诺支持所有 token 转账扩展。
+
+输出整数为十进制字符串，lamports 与 SOL 由 CLI 精确转换；不要转成 JavaScript Number 再运算。原始 RPC 位置参数各为 JSON 值，stdin 为一个 JSON 数组，支持大整数数值 token。Solana 策略使用 ~/.zan-cli/config.yaml 的 allowedSolanaRpcMethods；旧配置缺该列表时使用只读默认值，空列表拒绝全部 raw 方法。
+
+sendTransaction、requestAirdrop 和 simulateTransaction 不能通过修改 raw allowlist 开启；本版本只通过 manifest 实际列出的交易命令提供相关能力，不能用 EVM raw RPC 绕过确认。交易详情 null 或状态 not-found 表示未查到，不表示交易从未执行；状态查询会搜索历史。

package/skills/zan-cli/references/signing.md

@@ -28,3 +28,19 @@
 执行签名前确定用户授权的账户、消息内容，或链、收款地址、金额及 calldata；信息已明确时无需重复确认。读取余额不授权签名，签名请求也不授权广播。只在用户明确要求广播且实际命令和策略支持时另行执行；不要为广播绕过方法允许列表。
 
 已签名交易可直接用于广播，按用户请求交付结果，避免额外记录或上传。区分“已编码”“已签名”“已广播”“已确认”，不能把生成的交易哈希当作上链证明。
+
+## 多链助记词与 Solana
+
+`wallet add <alias> --mnemonic` 由用户在本地隐藏输入 BIP39 助记词，不指定链，预览 EVM、Solana 两个地址和派生路径后保存。助记词直接保存在系统凭据库；可选 `--passphrase-prompt` 从控制终端隐藏读取 passphrase，并作为同一秘密来源保存。不要在聊天、命令参数、环境变量或应用 `.env` 中传入这些秘密；仅当用户已有安全输入来源时使用 `--mnemonic --stdin`，stdin 只读一行且不再从该流读取交互选择。
+
+后续执行 `zan settings wallet derive main`，选择 Account 2、填写新别名并确认公开地址；这会从同一来源添加本地账户，不转移资产。脚本明确指定 `derive main --index 1 --alias trading`；index 从 0 开始，1 对应 Account 2。高级 `--evm-path` / `--solana-path` 与 --index 互斥，Solana 路径全部 hardened。源钱包必须由助记词导入；同一来源和路径不能重复创建。
+
+单链导入保留 `wallet add <alias> --stdin` 的 EVM 私钥语义；Solana 用 `--chain solana` 隐藏读取 Base58 64-byte secret，或 `--chain solana --keypair-file <path>` 读取用户选择的 keypair JSON。不能把任意 32-byte seed 当作支持的外部私钥格式；公钥部分不匹配会拒绝。
+
+`wallet list` 展示各链地址及 active 状态；`wallet use <alias>` 设置别名包含的各链默认账户，`--chain solana` 只修改 Solana 默认项。默认值按环境保存，钱包及秘密来源在同一 ZAN_HOME 内共享。删除别名会删除其全部链账户；其他派生别名仍能使用共享助记词，最后一个引用删除才清理秘密。凭据清理失败会明确报错，下次钱包命令重试，不把失败当作完全删除成功。
+
+`zan solana sign <message> --account <alias>` 在本地签 Ed25519 消息字节；默认 UTF-8，--hex 为偶数长度的 0x 字节。它无需项目、网络或 RPC，也不会广播。既有 `zan sign` 保持 EVM EIP-191 语义。
+
+旧 EVM 钱包索引首次使用时原位迁移，签名前核对地址与密钥，未知索引版本拒绝。迁移后使用新 CLI；旧版不能读取 v2 索引，避免混用版本。没有助记词/私钥导出命令，--reveal 也不会返回秘密。
+
+Solana 交易文件的构建、模拟、本地签名和广播见 [Solana transactions](solana-transactions.md)。签名不广播，已有完整签名文件可直接提交而无需本地钱包。

package/skills/zan-cli/references/solana-transactions.md

@@ -0,0 +1,92 @@
+# Solana transactions and Trading Boost
+
+Use the current `agent manifest` and command help for exact syntax. Agent commands include `--json --no-interactive`. Online preparation uses an explicitly selected Project and `solana-mainnet` or `solana-testnet`; a read-only readiness probe is `zan inspect --family solana`. Offline transaction signing and basic inspection require no login or RPC.
+
+## Authorization and inputs
+
+First establish the signing method using [wallet and signing](signing.md). A local mnemonic import is chain-independent and retains the phrase in the system credential store for later derivation. Never request wallet secrets in chat or arguments. Existing externally signed transactions can be sent without any local wallet.
+
+A request to sign does not authorize broadcast. Before broadcasting, establish the network, payer, recipient/amount or full instruction document, and any paid mode. Reuse explicit authorization already given in the conversation. Agents may use `--yes` only within that authorized scope. Without `--yes`, non-interactive submissions are rejected.
+
+## Two transaction entry points
+
+For a simple SOL transfer:
+
+```sh
+zan --json --no-interactive --project <id> --network solana-testnet solana transfer \
+  --to <recipient> --amount 0.01 --account <alias> --yes --wait
+```
+
+SOL amounts use exact decimal notation with at most nine fractional digits; scientific notation and excess precision are rejected. Transfer prepares the message, simulates, quotes fees, confirms, rechecks validity, signs locally, verifies signatures, and submits once. Cancellation signs and sends nothing.
+
+For general instructions or an external transaction:
+
+```sh
+zan solana tx build --instructions-file instructions.json --account <alias> --out unsigned.base64
+zan solana tx inspect --file unsigned.base64
+zan solana tx inspect --file unsigned.base64 --online
+zan solana tx simulate --file unsigned.base64
+zan solana tx sign --file unsigned.base64 --account <alias> --out signed.base64
+zan solana tx send --file signed.base64 --yes --wait
+```
+
+Add explicit Project/Network and automation flags to online commands. Build also accepts an explicit `--payer <address>` without a wallet. A document is strict JSON:
+
+```json
+{
+  "version": 0,
+  "instructions": [
+    {
+      "programAddress": "<program-address>",
+      "accounts": [
+        { "address": "<account-address>", "isSigner": false, "isWritable": true }
+      ],
+      "dataBase64": "<canonical-base64>"
+    }
+  ],
+  "lookupTableAddresses": []
+}
+```
+
+Supported versions are `"legacy"` and `0`; lookup tables require v0. Obtain program data from its documented interface or the user's existing client. Do not invent ABI/Anchor/SPL encoding. Unknown instructions retain program, accounts and data; an offline lookup-table inspection can be incomplete. `--online` resolves table accounts and validates their owners and indices.
+
+The file contains wire Base64. A public `<file>.metadata.json` sidecar binds network, blockhash and known valid height to the exact wire SHA-256. Bare external Base64 is accepted; it does not establish chain identity or last valid height. Keep matching sidecars when moving generated files. Existing outputs are never overwritten.
+
+`tx sign` adds only the selected required signer's signature, preserves message bytes and other signatures, and reports missing signers. It never refreshes an external blockhash or inserts instructions. `tx send` requires every signature to be valid. External durable nonce messages retain their first nonce instruction and use nonce-account validity rather than recent-blockhash expiry.
+
+## Explicit paid modes
+
+Ordinary RPC is the default. Boost works on mainnet only:
+
+```sh
+zan solana transfer --to <recipient> --amount 0.01 --account <alias> \
+  --boost tips --tip-sol 0.0003 --region sg --yes --wait
+zan solana transfer --to <recipient> --amount 0.01 --account <alias> \
+  --boost points --tier turbo --yes --wait
+zan solana tx send --file signed.base64 --boost points --tier prime --yes --wait
+zan solana boost status
+```
+
+Tips adds exactly one tip before local signing. The minimum/default is 300000 lamports (0.0003 SOL), using the current ZAN tip account. Regions are sg (default), global, hk, de and us. External signed transactions must already contain an adequate tip from the payer; missing or duplicate tips are rejected without rewriting bytes. Use `tx build --boost tips` to prepare it.
+
+Points uses the current Project Key, including an explicit Key override, and only the verified global route. Standard/Turbo/Prime cost 1/3/5 Points. Scripts must specify the tier; interactive users select it. Balance, expiry and permissions are unavailable/unknown under current CLI authentication. An explicit paid-mode confirmation permits the route request, and the gateway validates actual permission/quota. Points is service credit, not wallet SOL. Existing tips are preserved and displayed; Points does not remove or waive them.
+
+`--tip-sol` applies only to Tips, `--tier` only to Points. Reads, fees, simulation and confirmation always use ordinary RPC. `--anti-mev` adds the documented read-only Jito guard to a newly built message and enables the ZAN endpoint parameter; externally signed messages must already include the protection account. Do not claim guaranteed protection or acceleration.
+
+Network total fee already includes applicable priority fee. Display base/priority breakdown only when reliably available; do not add priority again. Unknown fees and Points balances are unavailable, not zero. For instruction documents, compute-budget instructions can be provided using the program's documented encoder.
+
+## Outcomes and recovery
+
+Simulation defaults to confirmed commitment. Existing signatures are verified locally; unsigned/partially signed simulation reports that full signature verification is skipped. Results identify `signatureVerificationScope: local`. RPC simulation receives a separate copy with every signature cleared and `sigVerify:false`, retaining the exact original message. The signed file stays unchanged; simulation does not release reusable signatures or authorize broadcast. `--skip-preflight` is an explicit opt-out of simulation and RPC preflight. `--commitment confirmed|finalized` applies throughout preparation and waiting.
+
+`--wait` enables confirmation waiting; `--wait-timeout <ms>` limits the total wait and global `--timeout` limits each HTTP request. Results distinguish submitted, confirmed, finalized, failed, expired and unknown. `accelerationStatus: unknown` can accompany a confirmed paid-mode transaction: chain confirmation is not a Boost receipt.
+
+Unknown exits 6, is not automatically retryable, and preserves the signature/recovery command in stdout JSON; stderr contains the structured error. Failed/expired exits 7. Search history with:
+
+```sh
+zan --json --no-interactive --project <id> --network <selected-network> solana tx status <signature>
+```
+
+Do not generate a second payment, replace the blockhash, increase the tip, switch routes or blindly resend after an unknown result. A history miss alone does not establish non-execution. Without known valid-height metadata, elapsed time does not prove expiry. Durable nonce changes with unknown history remain unknown.
+
+Submission results include the actual `projectId` and `network`; use the supplied recovery command, which pins both selections instead of relying on ambient defaults. A first Ctrl+C during confirmation keeps the known signature/outcome available while retaining the standard interrupt exit code 130. A second interrupt hard-stops the process.

package/skills/zan-cli/references/troubleshooting.md

@@ -40,3 +40,9 @@
 | `RATE_LIMITED` / `NETWORK_ERROR` / 临时服务错误 | 只对可安全重放且 `retryable: true` 的调用有限重试；遵守等待提示，持续失败则报告。 |
 
 CLI 已内置 Access Token 刷新及有限重放，不手动操作 Token。未知问题保留不含秘密的错误码、信息、hint 与执行上下文，给出有依据的下一步；不要把所有错误都归因于认证。只有实际成功获取数据后才报告结果。纯 CLI 查询不需要 `.env`，缺少该文件不是查询失败的原因；仅在任务需要应用代码直接调用 API 时，Key 写入失败才需要单独报告尚未完成应用配置。
+
+## Solana transaction recovery
+
+Submission exit 6 with `status: unknown` and `retryable: false` preserves a known signature. Query `solana tx status <signature>` on the same selected network; do not automatically create another payment or switch routes. Failed/expired exits 7. Read the stdout result as well as the stderr failure. A history miss alone does not prove a transaction never executed.
+
+Points balance, expiry and permission are unknown under current CLI authentication; this is not a zero balance. Explicit mode/tier plus confirmation authorizes one route request. Key override must apply consistently to reads and Boost; never query an unrelated account's Points to infer override permissions. `confirmed` on-chain with acceleration `unknown` is expected when no acceleration receipt exists.