@zan_team/cli 0.0.5 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # ZAN CLI
 
-ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、动态多链发现、EVM 与 Hyperliquid 查询、钱包管理与本地签名，以及稳定的机器可读输出。
+ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入口，提供安全认证、ZAN Project 管理与套餐用量查询、EVM / Solana / Hyperliquid 查询、助记词与钱包管理、本地签名、Solana 交易与 Trading Boost 加速，以及稳定的机器可读输出。
 
 ## 快速开始
 
@@ -9,6 +9,8 @@ ZAN CLI 是面向开发者、自动化脚本和 AI Agent 的统一命令行入
 - Node.js 22 或更高版本。
 - 可用的系统凭据库：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。
 
+macOS / Windows 需要安装 CLI 的可选原生凭据库依赖，安装时请保留 optional dependencies。通过命令行子进程传递秘密的备用凭据库实现已禁用；Linux 支持原生或通过 stdin 传入秘密的 Secret Service 实现。
+
 ### 安装
 
 使用 npm 全局安装：
@@ -19,6 +21,7 @@ zan --help
 ```
 
 CLI 默认连接 ZAN 服务，无需配置服务地址。
+下文命令中的 `<project-id>`、`<solana-address>` 等是占位符，执行前请替换为实际值并去掉尖括号。
 
 ### 登录
 
@@ -68,7 +71,14 @@ zan settings set network <network-id>
 zan settings show
 ```
 
-将 `<network-id>` 替换为 `evm networks` 返回的 Network ID。
+将 `<network-id>` 替换为 `evm networks` 返回的 Network ID。使用 Solana 时：
+
+```sh
+zan solana networks
+zan settings set network solana-testnet
+```
+
+Solana 支持 `solana-testnet` 和 `solana-mainnet`。EVM 与 Solana 的默认 Network 分开保存。
 
 ### 第一次查询
 
@@ -84,6 +94,15 @@ zan evm data balance 0x0000000000000000000000000000000000000000
 zan evm rpc eth_blockNumber
 ```
 
+Solana 查询示例：
+
+```sh
+zan solana rpc getSlot
+zan solana data balance <solana-address>
+```
+
+余额查询无需导入钱包。导入助记词、转账及加速的完整流程见[钱包与签名](#钱包与签名)和[Solana 交易与加速](#solana-交易与加速)。
+
 ### 脚本和 AI Agent
 
 自动化调用应显式关闭交互并使用 JSON 输出：
@@ -97,7 +116,7 @@ zan \
   evm rpc eth_blockNumber
 ```
 
-成功结果写入 stdout，失败结果写入 stderr。脚本还应检查进程退出码。
+成功结果写入 stdout，失败结果写入 stderr。Solana 交易提交遇到失败或结果不确定时，还会在 stdout 保留交易结果；脚本应同时检查退出码，见[自动化与 JSON 输出](#自动化与-json-输出)。
 
 ## 完整使用指南
 
@@ -244,8 +263,13 @@ JSON 直接返回 `{ project, keyUsage, plan }`，额度字段为十进制整数
 zan evm networks
 zan evm networks --search base
 zan evm networks --refresh
+zan solana networks
+zan solana networks --search testnet
 ```
 
+Solana 查询、交易与加速使用当前 Project 的 RPC Key；配置了 Key 覆盖值时使用该覆盖值。
+无需另建 Solana Project 或导出 Key 才能使用 CLI。
+
 网络列表中的币种显示为 `-` 时，仍可使用 `evm rpc` 查询。
 `evm data balance` 需要币种信息；信息缺失时可用 `evm rpc eth_getBalance`
 查询以最小单位表示的余额。
@@ -295,13 +319,19 @@ zan project rpc-key clear
 ```sh
 zan settings get project
 zan settings get network
+zan settings get solanaNetwork
 zan settings show
 zan settings set project <project-id>
 zan settings set network <network-id>
 zan settings clear network
+zan settings clear solanaNetwork
 zan settings clear
 ```
 
+`network` 表示 EVM 默认 Network，`solanaNetwork` 表示 Solana 默认 Network。
+`settings set network solana-testnet` 会自动更新 Solana 默认值；设置 EVM Network 不会覆盖它。
+显式传入的 `--network` 或 `ZAN_NETWORK` 必须与命令所属链匹配。
+
 Project 和 Network 的选择优先级：
 
 ```text
@@ -364,7 +394,7 @@ printf '["0x0000000000000000000000000000000000000000","latest"]' \
 
 该文件位于当前用户的主目录，对所有项目生效；`ZAN_HOME` 不改变此路径。
 
-YAML schema 支持两个顶层属性，分别控制 Raw JSON-RPC 和 Hyperliquid Info 方法：
+YAML schema 支持三个顶层属性，分别控制 EVM Raw JSON-RPC、Hyperliquid Info 和 Solana Raw JSON-RPC 方法：
 
 ```yaml
 allowedRpcMethods:
@@ -377,13 +407,18 @@ allowedHyperliquidInfoMethods:
   - meta
   - activeAssetData
   - userFills
+allowedSolanaRpcMethods:
+  - getSlot
+  - getBalance
+  - getAccountInfo
+  - getTransaction
 ```
 
-条目是精确且大小写敏感的方法名（1–128 字符，匹配 `^[A-Za-z][A-Za-z0-9_.-]*$`），不允许重复，最多 256 条。不支持通配、前缀或正则。空列表会拒绝所有 Raw RPC 方法。文件必须是单个 YAML 文档且不超过 64 KiB；注释允许，重复键、别名、自定义标签和合并键会被拒绝。
+条目是精确且大小写敏感的方法名（1–128 字符，匹配 `^[A-Za-z][A-Za-z0-9_.-]*$`），不允许重复，最多 256 条。不支持通配、前缀或正则。空列表会拒绝对应类别的所有 Raw 方法。文件必须是单个 YAML 文档且不超过 64 KiB；注释允许，重复键、别名、自定义标签和合并键会被拒绝。
 
-首次调用 `zan evm rpc` 或 `zan hyperliquid info` 时，若配置文件不存在，CLI 会创建默认查询方法列表。已有文件不会被升级覆盖；修改后在下一次调用生效。
+首次调用 `zan evm rpc`、`zan hyperliquid info` 或 `zan solana rpc` 时，若配置文件不存在，CLI 会创建默认查询方法列表。已有文件不会被升级覆盖；修改后在下一次调用生效。
 
-旧版本生成、只有 `allowedRpcMethods` 的配置文件继续兼容：Hyperliquid Info 使用默认允许列表，不会自动改写用户文件。若要限制 Info 调用，请显式加入 `allowedHyperliquidInfoMethods`；空列表会拒绝所有 Info 方法。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
+旧版本配置继续兼容：缺少 `allowedHyperliquidInfoMethods` 或 `allowedSolanaRpcMethods` 时，对应命令使用默认允许列表，不会自动改写用户文件。可显式加入对应属性限制方法；空列表拒绝该类 Raw 调用。已有配置不会自动补入新增加的 `hl_*` JSON-RPC 方法，需要使用时请手动加入 `allowedRpcMethods`。
 
 允许列表不保证所选 Network 或套餐支持某个方法；RPC 错误仍然是最终依据。诊断和跟踪类读取可能消耗更多额度。
 
@@ -469,23 +504,97 @@ zan evm logs \
 
 当前版本返回原始日志，不执行 ABI 解码或分页。
 
+### Solana 查询
+
+登录并选择 Project 后，设置 Solana Network：
+
+```sh
+zan settings set network solana-testnet
+zan inspect --family solana
+```
+
+常用查询无需本地钱包：
+
+```sh
+zan solana data balance <solana-address>
+zan solana data tokens <owner-address>
+zan solana account <solana-address>
+zan solana tx <transaction-signature>
+zan solana tx status <transaction-signature>
+zan solana block <slot>
+zan solana fees
+```
+
+`data tokens` 同时查询 SPL Token 和 Token-2022 账户。余额中的 lamports 和代币原始数量使用精确十进制字符串，避免大整数精度丢失。`fees` 返回近期优先费采样，单位为 micro-lamports / CU，不能直接当作整笔交易费用。
+
+余额、代币和账户查询支持 `--commitment processed|confirmed|finalized`，默认 `confirmed`；交易和区块查询支持 `confirmed|finalized`。
+
+Raw JSON-RPC 的位置参数同样必须是合法 JSON：
+
+```sh
+zan solana rpc getSlot
+zan solana rpc getBalance '"<solana-address>"' '{"commitment":"confirmed"}'
+```
+
+也可通过 `--stdin` 读取一个 JSON 参数数组，不能同时传位置参数。
+`allowedSolanaRpcMethods` 控制 Raw 查询；即使加入允许列表，`sendTransaction`、`requestAirdrop` 和 `simulateTransaction` 仍不能通过 `solana rpc` 执行。交易模拟使用 `solana tx simulate`，提交使用下面的交易命令。内置查询命令使用固定只读方法，不受允许列表影响。
+
 ### 钱包与签名
 
-添加钱包时通过终端隐藏输入私钥，私钥保存在系统凭据库中：
+钱包操作在本地完成，无需登录或选择 Project / Network。交互提示使用英文，秘密通过终端隐藏输入，保存在系统凭据库中。
+
+#### 导入助记词与派生账户
+
+导入 BIP39 助记词无需指定链，同一来源可派生 EVM 和 Solana 账户：
 
 ```sh
-zan settings wallet add my-wallet
+zan settings wallet add main --mnemonic
 zan settings wallet list
-zan settings wallet use my-wallet
+zan settings wallet use main
 ```
 
-使用当前钱包签署消息（EIP-191）：
+在隐藏输入提示中一次性输入完整助记词，所有单词放在同一行，单词之间用空格分隔，全部输入完成后按 Enter。使用 `--mnemonic --stdin` 时也使用同样的单行格式。
+CLI 检查单词数量（12、15、18、21 或 24）、BIP39 词表和校验和。交互输入无效时显示英文错误原因并让用户重新输入，可按 Ctrl+C 取消；stdin 输入无效时返回错误，不进入交互重试。错误不会回显助记词。
+默认导入第一个账户（Account 1，index 0），不显示账户选择。CLI 会预览两条链的公开地址和派生路径，确认后保存助记词；后续需要新增账户时使用 `wallet derive`。
+如原钱包使用了 BIP39 passphrase，导入时增加 `--passphrase-prompt`，在隐藏提示中输入。
+
+从已保存助记词添加第二个账户：
+
+```sh
+zan settings wallet derive main --index 1 --alias trading
+zan settings wallet use trading --chain solana
+```
+
+`--index` 从 0 开始，`1` 表示 Account 2。默认派生路径为 EVM 的 `m/44'/60'/0'/0/<index>` 和 Solana 的 `m/44'/501'/<index>'/0'`。
+已有钱包地址使用其他路径时，可通过 `--evm-path` / `--solana-path` 指定；自定义路径不能与 `--index` 同用，Solana 路径每一级须使用带 `'` 的加固派生。导入后请核对地址与原钱包一致。
+
+`wallet use <alias>` 为别名包含的链设置默认账户，`--chain solana` 或 `--chain evm` 只修改一条链。默认账户分别保存。
+
+#### 导入单链私钥
+
+也可运行 `zan settings wallet add <alias>`，按英文提示选择导入方式，或显式指定：
+
+```sh
+zan settings wallet add evm-wallet --chain evm
+zan settings wallet add solana-wallet --chain solana
+zan settings wallet add solana-file --keypair-file /path/to/keypair.json
+```
+
+Solana 私钥支持 Base58 编码的 64 字节 secret key，或包含 64 个字节整数的 JSON keypair 文件。
+`--stdin` 从标准输入读取秘密；使用 `--stdin` 时省略 `--mnemonic` 和 `--chain` 会沿用 EVM 私钥格式。不要将真实助记词、passphrase 或私钥放入命令参数、聊天或日志。
+
+#### 消息与 EVM 交易签名
+
+使用默认账户或指定别名签署消息：
 
 ```sh
 zan sign "Hello ZAN"
-zan sign "Hello ZAN" --account my-wallet
+zan sign "Hello ZAN" --account main
+zan solana sign "Hello ZAN" --account main
 ```
 
+`zan sign` 使用 EVM EIP-191，`zan solana sign` 使用 Solana Ed25519。消息默认按 UTF-8 编码；`--hex` 按十六进制字节解释。消息签名无需网络连接，也不会广播交易。
+
 签署交易前需选择 Project 和 Network。以下命令仅生成已签名交易，不广播：
 
 ```sh
@@ -506,9 +615,122 @@ zan evm contract encode --method 'balanceOf(address)' \
 删除已保存的钱包：
 
 ```sh
-zan settings wallet remove my-wallet
+zan settings wallet remove trading
+```
+
+删除一个派生账户不会删除其他账户仍引用的助记词来源。
+
+### Solana 交易与加速
+
+#### SOL 转账
+
+先导入钱包、登录并选择 Project，再在测试网尝试转账。发送方需要测试网 SOL 支付金额和网络费用：
+
+```sh
+zan --network solana-testnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main --wait
+```
+
+CLI 准备交易、模拟并预览收款方、金额、指令和费用，确认后才本地签名并提交。取消确认不会签名或发送。
+金额使用 SOL 十进制表示，最多 9 位小数，不接受科学计数法。
+默认使用普通 RPC；加速需要显式选择付费模式。
+
+`--wait` 等待 `confirmed`，可用 `--commitment finalized` 等待最终确认；不加 `--wait` 时提交后返回。
+`--wait-timeout <ms>` 控制总等待时间，默认 60000；全局 `--timeout` 控制单次请求超时。
+默认执行模拟和 RPC preflight，`--skip-preflight` 显式跳过两者。
+
+#### 通用交易：构建、检查、模拟、签名和提交
+
+选择目标 Solana Network 后，可从指令文件构建交易，或使用外部生成的 Base64 交易文件：
+
+```sh
+zan settings set network solana-testnet
+zan solana tx build --instructions-file instructions.json --account main --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 main --out signed.base64
+zan solana tx send --file signed.base64 --wait
+```
+
+`instructions.json` 的格式如下；将占位符替换为程序文档或 SDK 生成的地址与指令数据：
+
+```json
+{
+  "version": 0,
+  "instructions": [
+    {
+      "programAddress": "<program-address>",
+      "accounts": [
+        { "address": "<account-address>", "isSigner": false, "isWritable": true }
+      ],
+      "dataBase64": "<canonical-base64>"
+    }
+  ],
+  "lookupTableAddresses": []
+}
+```
+
+支持 `"legacy"` 和 `0` 两种版本；地址查找表使用 v0。CLI 不内置 SPL 转账、Swap 或 Anchor 指令编码，应使用对应程序的 SDK 生成数据。
+构建时也可用 `--payer <address>` 替代 `--account`，无需本地钱包。
+
+基本检查和 `tx sign` 离线完成，无需登录或 RPC。使用地址查找表时，`inspect --online` 可解析完整账户；离线检查可能不完整。
+签名只添加当前账户的签名，保留原消息、已有签名和 blockhash；多签交易需逐个签署必需账户。
+`tx send` 要求全部签名有效，可提交外部已签名交易，无需本地钱包。
+模拟成功仅表示本次模拟通过。已有签名在本地校验，结果标记 `signatureVerificationScope: local`；未签名或部分签名交易会标记未完成全部签名验证。发送给 RPC 的模拟副本会清除全部签名，保留原消息，原交易文件保持不变，避免模拟时披露可广播的交易。
+
+生成的 Base64 文件附带公开的 `<file>.metadata.json`，记录关联网络和交易有效期信息；移动文件时请一起保留。输出文件已存在时不会覆盖。
+外部交易文件不会被自动改写、补指令或刷新 blockhash。
+
+#### Trading Boost：Tips 与 Points
+
+加速仅支持 `solana-mainnet`。先查看当前 Project 和 Network 的能力说明：
+
+```sh
+zan --network solana-mainnet solana boost status
+```
+
+| 模式 | 选择参数 | 额外费用 |
+| --- | --- | --- |
+| 普通 RPC（默认） | `--boost rpc` 或省略 | 无加速费用，仍支付网络费用 |
+| Tips | `--boost tips --tip-sol 0.0003` | 钱包支付 SOL tip，最低及默认值为 0.0003 SOL |
+| Points | `--boost points --tier standard\|turbo\|prime` | 每次提交对应 1 / 3 / 5 Points，仍支付网络费用 |
+
+选择一种模式发送：
+
+```sh
+# Tips
+zan --network solana-mainnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main \
+  --boost tips --tip-sol 0.0003 --region sg --wait
+
+# Points
+zan --network solana-mainnet solana transfer \
+  --to <recipient-address> --amount 0.01 --account main \
+  --boost points --tier turbo --wait
 ```
 
+Tips 的区域可选 `sg`（默认）、`global`、`hk`、`de`、`us`；Points 使用 `global` 路由。
+Points 未指定 tier 时，交互模式提示选择；非交互模式必须显式指定。
+当前 CLI 不提供 Points 余额、过期时间和权限的确定查询，`boost status` 中的 unknown / unavailable 不表示余额为零，实际权限和额度由服务校验。
+
+已有交易也可通过 `tx send --boost points --tier turbo` 提交。
+使用 Tips 时须在签名前准备 tip，例如 `tx build --boost tips`；外部已签名交易必须已包含足额 tip，否则拒绝发送。Points 不会删除交易中已有的 SOL tip。
+`--anti-mev` 可在构建或转账签名前加入保护账户；外部已签名交易须预先包含该账户才能使用此选项。
+模拟、费用查询和确认查询仍使用普通 RPC。付费提交不保证加速或 Anti-MEV 效果，链上确认也不代表已取得加速回执。
+
+#### 交易结果与恢复
+
+结果区分 `submitted`、`confirmed`、`finalized`、`failed`、`expired`、`unknown`。
+等待超时或网络中断时，按结果中的 `recoveryCommand` 查询；它固定本次 Project、Network 和签名：
+
+```sh
+zan --project <project-id> --network <original-network-id> solana tx status <transaction-signature>
+```
+
+示例中的网络应与原交易一致。`unknown` 表示执行结果尚未确定，不能据此重新转账；历史查询暂未找到也不能证明未执行。
+CLI 不会自动重签、切换加速模式或发送替代交易。确认期间第一次 Ctrl+C 会保留已知签名和结果，退出码仍为 130。
+
 ### 自动化与 JSON 输出
 
 推荐的自动化调用形式：
@@ -525,9 +747,19 @@ zan --json --no-interactive --project <project-id> usage
 
 - 成功时，stdout 只包含一个完整 JSON 值；部分命令可能同时向 stderr 输出风险警告。
 - 失败时，stderr 只包含一个完整 JSON 错误。
+- Solana 交易提交返回 `failed` / `expired` / `unknown` 时，stdout 还保留交易结果和恢复命令。前两者退出码为 7，`unknown` 为 6 且不可自动重试；不要仅凭 stdout 有结果判断成功。
 - JSON 模式不输出进度提示。
 - 非交互模式不读取交互输入、不打开浏览器。
-- 显式的 `evm rpc --stdin` 仍会读取作为命令数据的 stdin。
+- 显式的 `evm rpc --stdin`、`solana rpc --stdin` 和钱包导入 `--stdin` 仍会读取作为命令数据的 stdin。
+
+自动化提交 Solana 交易必须使用 `--yes` 明确授权本次广播。例如，已确认网络、收款方、金额和账户后：
+
+```sh
+zan --json --no-interactive --project <project-id> --network solana-testnet \
+  solana transfer --to <recipient-address> --amount 0.01 --account main --yes --wait
+```
+
+签名授权不等于广播授权。Agent 应在用户授权的范围内使用 `--yes`；Points 模式还必须指定 `--tier`。
 
 错误示例：
 
@@ -549,6 +781,7 @@ zan --json --no-interactive --project <project-id> usage
 ```sh
 zan inspect
 zan --json --no-interactive inspect
+zan inspect --family solana
 ```
 
 获取 Agent 可读取的命令说明：
@@ -560,11 +793,12 @@ zan --json --no-interactive agent manifest
 
 Agent 可用 `inspect` 检查本地状态；`ready: false` 需结合实际命令判断。
 例如缺少 Network 不影响已登录且已选择 Project 的 `usage` 查询。
+`inspect --family solana` 检查 Solana 的就绪状态；余额查询无需钱包，本地消息签名和离线交易签名无需登录或 Network。
 
 ### Agent Skill
 
 CLI 随附 zan-cli Skill，包含命令使用说明、
-Project/Network 选择、套餐与 Key 用量、EVM/Hyperliquid 查询、RPC Key 拉取及钱包签名指引。
+Project/Network 选择、套餐与 Key 用量、EVM / Solana / Hyperliquid 查询、RPC Key 拉取、助记词派生、钱包签名及 Solana 交易与 Trading Boost 指引。
 安装 CLI 后，使用以下命令将 Skill 安装到 Agent 可发现的位置。
 
 选择 Agent 和安装范围：
@@ -632,22 +866,22 @@ zan completions fish
 |    `3` | 认证、凭据库或必要设置缺失                 |
 |    `4` | Project、Network、ENS 名称或查询资源不存在 |
 |    `5` | 限流                                       |
-|    `6` | 网络错误                                   |
-|    `7` | JSON-RPC 错误                              |
+|    `6` | 网络错误或 Solana 提交结果不确定            |
+|    `7` | JSON-RPC 错误或 Solana 交易失败、过期        |
 |    `8` | ZAN CLI API 错误                           |
 |  `130` | 用户中断                                   |
 
-只有限流、临时网络错误和服务端明确标记的临时错误适合自动重试。参数错误、认证拒绝和资源不存在不应自动重试。
+读取请求遇到限流、临时网络错误或服务端明确标记的临时错误时，可结合 `retryable` 重试。参数错误、认证拒绝和资源不存在不应自动重试。Solana 提交结果不确定时先查询原签名，不自动重试广播或重新支付。
 
 创建 Project 时若提示名称重复，可更换名称，或执行 `zan project list` 查找已有项目。
 套餐不可用或项目数量达到上限时，请根据错误提示检查账号套餐及项目状态。
 
 ### 安全注意事项
 
-- 不要在聊天、问题反馈、日志或版本控制中包含私钥、API Key、登录凭据及含凭据的 RPC 地址。
+- 不要在聊天、问题反馈、日志或版本控制中包含助记词、passphrase、私钥、API Key、登录凭据及含凭据的 RPC 地址。
 - 仅在应用直接调用 ZAN API 时使用 `project rpc-key pull`，并妥善保管生成的 `.env`。
-- 私钥和 API Key 使用隐藏输入或 stdin 传入，不要将真实值写在命令参数中。
-- 自定义 RPC 允许列表可能开放写操作；执行前确认方法及参数的影响。
+- 助记词、私钥和 API Key 使用隐藏输入或 stdin 传入；passphrase 使用隐藏提示，不要将真实值写在命令参数中。
+- 自定义 EVM RPC 允许列表可能开放写操作；执行前确认方法及参数的影响。
 - 分享签名、已签名交易或查询结果前，确认其用途及接收方。
 - 自动化调用使用 `--json --no-interactive`，同时检查退出码和风险警告。