> 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 核心拥有的多链加密钱包。它从同一个恢复短语派生出每条受支持链上的一个账户，读取余额，并运行严格的 **准备 → 确认 → 执行** 流程，用于原生转账和少量代币转账。

它刻意保持极简：只有密钥/账户管理以及基础链上操作。更高级的 DeFi（兑换、桥接、通用合约/dapp 调用）位于单独的 `web3` 模块中，并且 **不** 不属于钱包的 agent 或 RPC 接口。

最重要的一个特性是： **签名和广播完全在核心内部基于解密后的恢复短语完成。任何私钥都不会离开设备或通过网络传输。** 这是你的钱，因此钱包在设计上偏保守。

***

## 受支持的链和代币标准

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

| 链      | 网络                                                | 原生            | 代币标准                        | 备注                                                                 |
| ------ | ------------------------------------------------- | ------------- | --------------------------- | ------------------------------------------------------------------ |
| EVM    | Ethereum、Base、Arbitrum、Optimism、Polygon、BNB Chain | ETH / BNB / 等 | ERC-20（BNB Chain 上为 BEP-20） | 一个 `EVM` 在全部六个网络中共用一个账户；每次请求按需选择网络，默认为以太坊主网。支持 EIP-1559 / 结构化交易签名。 |
| 比特币    | 主网                                                | BTC           | None                        | P2WPKH（原生 SegWit）。 **拒绝代币转账。** 用于余额/广播的 Esplora REST 接口。           |
| Solana | 主网 / 测试网（按 RPC）                                   | SOL           | SPL                         | ed25519 签名；原生和 SPL 代币转账。                                           |
| 波场     | 主网                                                | TRX           | TRC-20                      | 用于原生和 TRC-20 转账的 TronGrid REST 接口。                                 |

内置资产目录包括原生资产以及各链常见的稳定币（例如，USDC/USDT 作为 ERC-20/BEP-20，Solana 上的 USDC 作为 SPL，Tron 上的 USDT 作为 TRC-20）。

***

## 入门与恢复短语

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

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

***

## 密钥托管与安全

钱包是 **非托管且本地化的**。没有服务端密钥托管。

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

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

***

## 读取余额和链信息

只读接口无需确认：

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

每条链/网络的 RPC 端点都可通过 `OPENHUMAN_WALLET_RPC_*` 环境变量覆盖。日志中 URL 会被脱敏为协议 + 主机。

***

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

每次写入都是有意设计的两步流程。钱包绝不会一步直接发送。

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

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

转账仅限于 **原生转账以及上表中的代币标准**。比特币拒绝代币转账。此处不提供兑换、桥接和通用合约调用。

***

## 交易状态跟踪

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

* **`tx_status`**：生命周期状态（pending / confirmed / failed / not found）。
* **`tx_receipt`**：回执详情（成功、手续费、区块）。
* **`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)