> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/wallet.md).

# 钱包

一个刻意设计得 **基础的**, **非托管的** 由 Rust core 拥有的多链加密货币钱包。它为每条受支持的链管理一个账户，这些账户由同一个恢复短语派生，读取余额，并运行严格的 **准备 → 确认 → 执行** 流程，用于原生转账和少量代币转账。

它被有意设计得极简：密钥/账户管理，以及基本的链上操作。更高层级的 DeFi（兑换、跨链桥、通用合约/dapp 调用）位于单独的 `web3` 模块中，且 **不会** 属于钱包的 agent 或 RPC 接口范围。

最重要的一点是： **签名和广播完全在 core 内部、从解密后的恢复短语中完成。没有任何私钥会离开设备或经过网络。** 这是你的钱，所以钱包在设计上是保守的。

***

## 支持的链和代币标准

设置会派生 **每条链恰好一个账户**。EVM 是一个在六个网络间复用的单账户。仅支持下方列出的转账标准。其他任何操作（兑换、任意合约调用）都不在钱包的职责范围内。

| 链       | 网络                                                | 原生资产          | 代币标准                        | 说明                                                                 |
| ------- | ------------------------------------------------- | ------------- | --------------------------- | ------------------------------------------------------------------ |
| EVM     | Ethereum、Base、Arbitrum、Optimism、Polygon、BNB Chain | ETH / BNB / 等 | ERC-20（BNB Chain 上为 BEP-20） | 一个 `EVM` 在这六个网络上共用一个账户；按请求选择网络，默认是 Ethereum 主网。EIP-1559 / 结构化交易签名。 |
| Bitcoin | 主网                                                | BTC           | None                        | P2WPKH（原生 SegWit）。 **拒绝代币转账。** 用于余额/广播的 Esplora REST。              |
| Solana  | 主网 / devnet（按 RPC）                                | SOL           | SPL                         | ed25519 签名；原生资产 + SPL 代币转账。                                        |
| Tron    | 主网                                                | TRX           | TRC-20                      | 用于原生资产 + TRC-20 转账的 TronGrid REST。                                 |

内置资产目录包含原生资产，以及每条链常见的稳定币（例如：ERC-20/BEP-20 形式的 USDC/USDT，Solana 上的 SPL 形式 USDC，Tron 上的 TRC-20 形式 USDT）。

***

## 入门与恢复短语

设置是一个单次、不可撤销的操作：它会保存同意标志、助记词词数、设置来源、每个受支持链恰好一个派生账户，以及加密后的恢复短语。有效的 BIP-39 助记词词数为 **12、15、18、21 或 24**.

恢复短语是唯一的秘密。钱包会将每条链的账户 **地址** （可以安全展示）与秘密材料分开存储，而只有加密后的短语才能重建私钥。

***

## 密钥托管与安全

钱包是 **非托管且本地的**。不存在服务器端的密钥托管。

* **恢复短语在静态存储时始终处于加密状态。** 它在持久化到任何位置之前，会通过 core `加密` 域进行加密。
* **首选位置：操作系统密钥串。** 加密后的短语保存在操作系统密钥串中，键名为 `wallet.mnemonic`，并按工作区派生的用户 ID 进行作用域隔离。访问受 keyring 同意策略控制。
* **备用位置：工作区 JSON。** 当密钥串不可用时（例如无界面环境），加密后的短语会回退到 `{workspace_dir}/state/wallet-state.json`。在加载时，任何存放在 JSON 中的密钥都会透明地 **迁移到密钥串中** ，一旦密钥串可用，并从 JSON 中移除。
* **原子、受保护的写入。** `wallet-state.json` 会在进程级锁保护下以原子方式写入（临时文件 + fsync + 持久化）。损坏或无效的状态文件会被隔离，而不会被信任。
* **仅在签名时解密。** 链签名器只在派生密钥以签署已确认交易时才会在 core 内部解密短语。明文密钥永远不会被持久化，也永远不会通过网络序列化。

参见 [操作系统密钥环与秘密存储](/openhuman/zh/gong-neng/privacy-and-security/os-keyring-and-secret-storage.md) ，了解秘密如何在各平台上存储，以及 [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md) ，了解更广泛的模型。

***

## 读取余额与链信息

只读接口不需要确认：

* **状态**：入门状态以及安全的各链账户地址。
* **余额**：每个账户的原生资产余额。注意：目前只有 **EVM 余额会实时读取** （Ethereum 主网）；BTC、Solana 和 Tron 会调用各自的提供方，但在出错时会回退为零余额并显示“provider missing”状态。
* **网络默认值 / 支持的资产**：每条链的 RPC 和浏览器 URL、能力标志以及内置资产目录。
* **链状态**：每条链的就绪状态和当前活跃的 RPC URL。

可通过以下方式按链/网络覆盖 RPC 端点： `OPENHUMAN_WALLET_RPC_*` 环境变量。日志中 URL 会被脱敏为仅保留协议和主机。

***

## 发送转账：准备 → 确认 → 执行

每次写入都是一个两步、显式的流程。钱包绝不会一步直接发送。

1. **准备** (`prepare_transfer`）：校验金额、收款地址，以及（对于代币）calldata，估算手续费，并返回一个 **已准备的报价** ，带有 `quoteId`。报价保存在内存存储中， **有效期 5 分钟**，上限为 64，并且会 **不会** 跨重启持久保留。
2. **确认 + 执行** (`execute_prepared`）：需要 `confirmed: true` 以及一个有效的 `quoteId`。在广播之前，会以原子方式消耗该报价，因此并发确认不会造成重复提交；若失败，则会以刷新后的 TTL 恢复，使其仍可重试。

**报价所有者绑定。** 每个报价都绑定到准备它的聊天线程。一个报价只能由创建它的同一所有者执行；若 `quoteId` 泄漏到共享频道中，返回的将是无法区分的“未找到”错误，而不会让另一个会话劫持它。

转账仅限于 **原生发送以及上表中的代币标准**。Bitcoin 拒绝代币转账。这里不提供兑换、跨链桥和通用合约调用。

***

## 交易状态跟踪

广播后，有三个只读检查器可让 agent 通过哈希跟踪交易：

* **`tx_status`**：生命周期状态（pending / confirmed / failed / not found）。
* **`tx_receipt`**：回执详情（success、fee、block）。
* **`lookup_tx`**：原始交易载荷。

***

## Agent 工具与批准安全

agent 通过六个工具访问钱包：

| 工具                        | 用途                   |
| ------------------------- | -------------------- |
| `wallet_status`           | 入门状态 + 账户地址。         |
| `wallet_chain_status`     | 每条链的就绪状态 + 当前活跃 RPC。 |
| `wallet_prepare_transfer` | 构建已验证、已估算费用的报价。      |
| `wallet_tx_status`        | 按哈希查询交易生命周期状态。       |
| `wallet_tx_receipt`       | 按哈希查询交易回执。           |
| `wallet_lookup_tx`        | 按哈希查询原始交易。           |

请注意， **没有任何 agent 工具可以执行转账。** agent 可以准备报价，但真正转移资金（`execute_prepared`）要经过 RPC 接口，必须显式确认并通过所有者绑定检查。结合先准备后确认的流程以及按线程绑定的报价，这可以防止 agent 悄无声息地花费资金。

由于这些是金融操作，它们应通过 [批准门控](/openhuman/zh/gong-neng/approval-gate.md) 来呈现，以便在人类确认后再移动资金。请将每一次转账都视为高风险操作。

***

## 另见

* [审批门控](/openhuman/zh/gong-neng/approval-gate.md)
* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)
* [操作系统密钥环与秘密存储](/openhuman/zh/gong-neng/privacy-and-security/os-keyring-and-secret-storage.md)