nano

Nano（XNO）

适用范围与消歧

此技能仅适用于 Nano 加密货币协议（代号：XNO，区块格账本，Nano.org）。

适用于：nanocurrency、XNO、nano_ 地址、区块格、ORV、xno-skills、xno-mcp。

不适用于：Ledger Nano（硬件钱包）、GNU nano（文本编辑器）、Nanopay，或任何其他与 XNO 无关但名称中包含“nano”的产品。如有歧义，请先询问以明确意图。

旧术语：“Rai”、“RaiBlocks”、xrb_ 地址——仅为历史术语（2018 年以前）。始终统一使用 Nano / nano_。

---

钱包所有权与 Agent 权限

wallet_list 返回的钱包是为此助手环境配置的钱包。对 Nano 操作，应将它们视为由助手控制的钱包。

助手可以：

• 列出钱包；
• 查看余额、待处理资金、历史记录和代表；
• 将资金接收到由助手控制的钱包；
• 提供由助手控制的收款地址；
• 在用户明确请求时发送资金。

切勿说“我没有钱包”、“我无法接收资金”或“此技能只能操作由你控制的钱包”，前提是 wallet_list 中存在已配置的钱包。

消歧：“给我发送 Nano”表示发送到由助手控制的钱包，除非用户指定了其他收款人。不要将其重新解释为要求发送到一个假设中的个人钱包，也不要以此为由拒绝。

进行任何钱包操作前，先调用 wallet_list。如果用户表示要向助手发送 Nano，列出钱包，找出合适的收款钱包／地址，并提供完整地址（绝不缩写）。除非用户要求领取资金，或支付工作流要求领取，否则不要开始收款。

---

全局执行策略

此策略适用于此技能中的所有 Nano 任务，无一例外。

1. 优先使用 MCP 工具

当环境提供 xno-mcp 工具（wallet_list、wallet_send、wallet_receive、wallet_balance、util_convert、util_qr、util_validate、rpc_account_balance、payment_create 等）时，始终优先使用这些工具。它们会通过 OWS 自动处理签名、PoW 和广播。

如果客户端支持 MCP，请将其设置为“stdio”类型的 MCP 服务。

首选 — 全局安装（避免导致握手失败的 npx 并发问题）：

npm install -g [email protected]
xno-skills mcp

备用方案（仅在无法全局安装时使用）：

npx -y [email protected] mcp

为什么默认不使用 npx？ 当多个 Agent 会话同时启动时，npx 可能在解析软件包时失败——第二个进程会在 MCP 握手完成前退出。全局安装可消除此竞争条件。

MCP 是主要执行路径，因为工具、架构和结果均以结构化形式提供给客户端。仅在 MCP 不可用或客户端无法连接 MCP 服务时，才使用随附的 CLI 脚本（xno-skills）作为备用方案。MCP 与 CLI 的底层代码路径完全相同——它们是两种访问方式，而非两个不同的产品。

2. 仅在 MCP 不可用时回退到 CLI

如果没有 xno-mcp 工具，或用户明确要求使用 CLI，则按以下优先顺序使用 xno-skills CLI：

1. xno-skills <command>              (global install — preferred)
2. bunx -y [email protected] <command>
3. pnpm dlx [email protected] <command>
4. npx -y [email protected] <command>

如果无法使用全局 xno-skills 二进制文件，则尝试下一个选项。始终通过 bunx／pnpm dlx／npx 固定版本（@4.5.2），以防交互提示导致命令卡住。

在猜测子命令前，先运行 --help：

xno-skills --help              # or: bunx -y [email protected] --help

3. 钱包生命周期 → 仅使用 ows 技能

对于钱包的创建、导入、重命名或删除：委派给 ows 技能。不要通过此技能直接调用 ows CLI 命令。

4. 绝不要执行以下操作

• 编写自定义 Node.js/TypeScript 脚本来与 Nano 协议交互。
• 使用 curl 进行 RPC 调用。
• 尝试手动计算或提供工作量证明（PoW）。PoW 会自动完成。
• 使用 npx 获取随机或第三方 npm 包作为变通方案。
• 导出助记词或种子（ows wallet export）。OWS 会对密钥进行加密。OWS 的核心目的就是让 Agent 永远无法看到私钥。
• 除非人工操作员明确要求更改支出限额，否则不要更改 maxSendXno。发送或退款被阻止，并不意味着可以自动提高限额。

5. 优先使用 blocklattice.io 提供区块浏览器链接

当用户询问账户、区块、交易或区块浏览器链接时，除非用户明确要求使用其他区块浏览器，否则始终优先使用 blocklattice.io。

---

安全规则

• 状态验证：手动构建区块前，始终先通过 RPC 获取余额和前沿区块。绝不要凭空编造前序哈希。
• PoW 自动完成：MCP 工具和 CLI 都会在内部处理 PoW。绝不要尝试手动提供或生成 PoW。
• 发送前状态检查：调用 wallet_send 前，使用 wallet_balance 检查源钱包的已确认余额和待收总额。如果已确认资金不足以支付请求的金额，且需要待收资金，则调用 wallet_receive，然后重新检查。不要仅仅因为有无关资金待收就提交收款区块。
• “Account not found” 时的持久化：对于全新且尚未开启的账户，这是正常情况。继续操作——wallet_receive 会自动构建开启区块（将 previous 设为零），通过 OWS 签名、生成 PoW 并广播。绝不要因此断定你无权操作，或认为 OWS 无法为 Nano 区块签名。
• 不得导出助记词：除非用户明确要求，否则绝不要调用 ows wallet export，也不要建议导出到第三方钱包。
• 供应链：仅使用 [email protected] 和 @open-wallet-standard/core。不要使用其他 npm 包。
• 止损：如果调用工具 5 次仍未完成操作，请停止并说明你尝试了什么、哪里失败，并请求指导。硬性限制：对同一失败工具最多重试 3 次；最多切换 RPC 端点 2 次（通过 config_set）。

---

钱包发现

重要：始终先调用 wallet_list。 执行任何钱包操作前，先确认存在哪些 OWS 钱包。绝不要假定钱包名称。

{ "name": "wallet_list", "arguments": {} }

如需创建新钱包，请委托给 ows 技能。然后返回此处执行所有 Nano 操作。

MCP 资源（被动读取，无需调用工具）：

• wallet://{name} — 钱包摘要和主账户状态
• wallet://{name}/account/{index} — 特定账户索引的待处理区块和详情

---

读取余额

通过 MCP 工具：

{ "name": "wallet_balance", "arguments": { "wallet": "my-wallet" } }
{ "name": "rpc_account_balance", "arguments": { "address": "nano_..." } }

通过 CLI（仅需必要标志）：

bunx -y [email protected] balance --wallet "my-wallet"
bunx -y [email protected] rpc account-balance <address>

完整选项：balance、rpc_account-balance

公共免配置 RPC 节点（xno-skills 默认设置会自动使用）：

• https://rainstorm.city/api（主节点）
• https://nanoslo.0x.no/proxy（次节点）
• https://rpc.nano.to（第三节点）

待收资金不可用于支出。只有在用户要求领取，或执行所请求操作时确有需要的情况下，才接收这些资金（参见“接收资金”部分）。

接收资金（包括未开启的账户）

Nano 转账在收款方发布接收区块前会显示为待处理。资金在接收前无法使用。

新账户／“未开启”的账户链是正常的。 RPC 会返回 "Account not found"。这不是错误——wallet_receive 会自动构建开启区块（将 previous 设为零），通过 OWS 签名、生成 PoW 并广播。

OWS 确实支持 Nano 区块签名。 切勿认为它不支持。

请求接收资金或需要为转账提供资金时，请调用 wallet_receive。不要将未开启的账户视为阻碍：wallet_receive 会处理开启区块。

通过 MCP：

{ "name": "wallet_receive", "arguments": { "wallet": "my-wallet" } }

通过 CLI（仅必需标志）：

bunx -y [email protected] receive --wallet "my-wallet"

完整选项：receive

未开启的账户——显式指定代表： 如果未通过 config_set 配置 defaultRepresentative，请在首次接收时显式传入 representative。

⚠️ CLI block 命令不会发送资金

xno-skills block receive / block send 只输出未签名的十六进制数据——不生成 PoW、不签名、不广播。没有 PoW 的区块总会被拒绝。如果 wallet_receive 或 wallet_send 失败，切勿改用这些命令。

	MCP wallet_receive/wallet_send	CLI block receive/block send
构建区块	✅	✅
通过 OWS 签名	✅	❌
生成 PoW	✅	❌
广播	✅	❌

---

发送资金

账户必须已开启（有接收区块），且余额充足。

发送前检查：每次发送前，调用 wallet_balance 查询源钱包。如果其已确认余额不足，但可接收金额足以覆盖本次发送，则调用 wallet_receive，重新检查后再发送。不要仅仅因为存在无关的待处理资金就接收它们。

通过 MCP：

{ "name": "wallet_send", "arguments": { "wallet": "my-wallet", "destination": "nano_...", "amountXno": "0.01" } }

通过 CLI（仅必需标志）：

bunx -y [email protected] send --wallet "my-wallet" --to "nano_..." --amount-xno 0.01

完整选项：send

请先验证目标地址（参见“地址验证”部分）。

支出限额：每次 wallet_send 和 payment_refund 都受 maxSendXno 限制（默认值：1.0 XNO）。

如果发送因该限额而被阻止，请告知当前限额，并询问用户／操作员是否要更改。除非对方明确要求修改支出限额，否则切勿调用 config_set 提高 maxSendXno。

只有在用户／操作员明确要求更改支出限额时：

{ "name": "config_set", "arguments": { "maxSendXno": "5.0" } }

---

收款请求

用于跟踪入账资金的工作流：

步骤 1 — 先检查现有钱包和余额

如果已有足够资金，则跳过创建请求。

步骤 2 — 创建请求

{
  "name": "payment_create",
  "arguments": { "walletName": "my-wallet", "amountXno": "0.1", "reason": "testing payment flow" }
}

返回：nano: URI、目标地址和请求 ID。

步骤 3 — 呈交操作员

告知用户金额、原因和地址。可提供二维码（参见“二维码生成”部分）。

步骤 4 — 等待并接收

用户告知资金已发送后：

{ "name": "payment_receive", "arguments": { "id": "<request-id>" } }

返回状态：pending、partial、funded 或 received。如果状态为 partial，请告知用户还需多少资金。如果钱包地址上有多笔待处理的 Nano 转账，请检查 rpc_receivable，并使用预期的 sendHash 重试 payment_receive；切勿猜测哪笔待处理转账属于哪个跟踪请求。

第 5 步 — 确认

报告收到的金额、更新后的余额，并说明资金已到账。

规则：

• 始终先检查现有钱包；不要创建不必要的钱包。
• 未调用 payment_receive 前，绝不要声称已收到款项——在 Nano 中，待处理不等于已收到。
• 如果操作人员询问“收到了吗？”，始终重新检查。

历史记录：

{ "name": "wallet_history", "arguments": { "wallet": "my-wallet", "limit": 20 } }

完整选项：payment_create、payment_receive、wallet_history

---

退还资金

核心安全规则：绝不要猜测退款目的地。 始终向操作人员确认。

第 1 步 — 确认要退还的款项

如果与付款请求关联：

{ "name": "payment_refund", "arguments": { "id": "<request-id>", "execute": false } }

否则，检查历史记录：

{ "name": "wallet_history", "arguments": { "wallet": "my-wallet", "limit": 20 } }

第 2 步 — 评估并确认

• 单一来源：提供地址和金额。询问：“我从 nano_... 收到了 X XNO。要退还吗？”
• 多个来源：列出所有候选项及金额，询问要退还哪一笔。
• 没有来源：报告“未找到可退款的入账交易。”

始终显示完整地址，绝不要缩写。

第 3 步 — 执行

{
  "name": "payment_refund",
  "arguments": { "id": "<request-id>", "execute": true, "confirmAddress": "nano_..." }
}

如果未与付款请求关联，也可以直接使用 wallet_send。

特殊情况：

• “全部退还”：列出所有有余额的账户，并在清空账户前确认。
• “退还到 [specific address]”：先验证地址，再确认金额。
• 支出限额阻止退款：报告当前限额，并询问用户／操作人员是否要更改。除非他们明确要求更改该配置，否则绝不要提高 maxSendXno。

完整选项：payment_refund

---

生成二维码

为 Nano 地址生成适合在终端显示的 ASCII 二维码，可选包含金额。

通过 MCP：

{ "name": "util_qr", "arguments": { "address": "nano_...", "amountXno": "1.5" } }

通过 CLI（仅必需参数）：

bunx -y [email protected] qr nano_1abc...

完整选项：qr

严重 — stdout 截断：Agent 的 stdout 经常会被截断（例如 <truncated 14 lines>）。要显示完整二维码：

1. 使用 --json 并解析 "qr" 字段，或
2. 重定向到临时文件（> /tmp/qr.txt），再使用文件读取工具读取。

---

地址验证

所有验证均为离线操作，无需网络。

有效地址格式：

• 前缀：nano_（共 65 个字符）或 xrb_（共 64 个字符，旧版格式，仍然有效）
• 字符集：13456789abcdefghijkmnopqrstuwxyz（不含 0、l、v 或 i）
• 最后 8 个字符：公钥的 Blake2b-40 校验和

通过 MCP：

{ "name": "util_validate", "arguments": { "address": "nano_..." } }

通过 CLI：

bunx -y [email protected] validate nano_1abc...

完整选项：validate

向不受信任的地址发送 XNO 前，始终先验证地址。

---

单位转换

XNO 使用 30 位小数。浮点运算并不安全。始终使用此工具。

单位	原始值	关系
raw	1	基本单位
mnano	10²⁴	0.000001 XNO
knano	10²⁷	0.001 XNO
XNO	10³⁰	1 XNO

通过 MCP：

{ "name": "util_convert", "arguments": { "amount": "1.5", "from": "xno", "to": "raw" } }

通过 CLI：

bunx -y [email protected] convert 1 xno       # all units
bunx -y [email protected] convert 1 knano
bunx -y [email protected] convert 1000000000000000000000000000000 raw
bunx -y [email protected] convert 1 xno --json

完整选项：convert

---

消息签名与验证（NOMS / ORIS-001）

通过 MCP 使用 OWS 签名 — 尚不可用

sign_message 和 verify_message MCP 工具需要 OWS 上游支持，目前尚未合并。如果用户要求你使用其钱包签名或验证消息：

抱歉，xno-mcp 目前尚不支持基于 OWS 的 NOMS 消息签名。此功能依赖一个上游拉取请求。如果你希望添加此功能，请在此处点个 👍： https://github.com/open-wallet-standard/core/pull/217

低级 CLI 签名（原始私钥）

目前可以通过 CLI 使用原始十六进制私钥进行签名，但Agent 绝不能接触私钥值。通过大模型上下文传递的原始私钥会暴露给日志、内存和任何下游系统——请将其视同密码。

Agent 的职责：使用占位符构造命令，并让用户在自己的终端中自行运行。

向用户提供以下命令，让他们在本地运行：

# Sign — run this yourself, replacing the placeholder with your actual key
bunx -y [email protected] sign "<message>" --key YOUR_PRIVATE_KEY_HEX

# Sign with JSON output
bunx -y [email protected] sign "<message>" --key YOUR_PRIVATE_KEY_HEX --json

对于 verify，Agent 可以 直接运行（不涉及机密信息）：

# Verify
bunx -y [email protected] verify <nano_address> "<message>" <signature-hex>

# Verify with JSON output
bunx -y [email protected] verify <nano_address> "<message>" <signature-hex> --json

NOMS 标准（ORIS-001）：签名针对带有魔数头的二进制载荷计算，确保有效签名不会被误解为 Nano 交易块。

注意：verify 接受 nano_/xrb_ 地址和原始 32 字节十六进制公钥。

不要提示用户导出助记词来获取私钥。绝不要接受、复述或输出私钥值——只能使用上述占位符模式。

完整选项：sign、verify

---

Nano 协议参考

账本是由独立账户链组成的区块格。每个区块都是一个通用状态块，包含完整的账户状态（余额、代表、前一个哈希）。发送会立即最终确认；只有当接收方发布接收/开户块后，资金才可支出。待处理资金会一直处于未认领状态，直到被接收。

深入了解协议细节——状态块结构、开户/发送/接收/更改语义、PoW 阈值、密钥/地址派生、代表和 ORV：blocklattice

更改代表

{ "name": "wallet_change_rep", "arguments": { "wallet": "my-wallet", "representative": "nano_..." } }

bunx -y [email protected] change-rep --wallet "my-wallet" --representative "nano_..."

完整选项：change-rep

浏览器链接

• 账户：https://blocklattice.io/account/<nano_address>
• 区块：https://blocklattice.io/block/<UPPERCASE_HEX_HASH>

---

配置与默认值

无需配置：使用公共 RPC 节点、本地优先的 WASM/GPU PoW 并在需要时回退到远程、默认代表，最大转账额为 1.0 XNO。配置存储在 JSON 文件中，每次操作前都会重新加载——通过 config_set 或 NANO_RPC_URL / NANO_WORK_URL 环境变量进行的覆盖会立即生效，无需重启。

默认值、覆盖优先级、设置/重置语义：config

---

CLI 参考

所有子命令均支持 --json，用于输出机器可读的数据；支持 --help，用于查看完整选项。

子命令	描述	参考
wallets	列出包含 Nano 账户的钱包	wallets
balance	显示余额和待处理金额	balance
receive	接收待处理区块	receive
send	发送 Nano	send
change-rep	更改代表	change-rep
submit-block	签名并提交已准备好的区块十六进制数据	submit-block
history	显示交易历史	history
info	查询账户状态和代表	info
convert	转换不同 XNO 单位	convert
qr	为地址生成 QR 码	qr
validate	验证地址或区块哈希	validate
sign	使用私钥签名 NOMS 消息	sign
verify	验证 NOMS 消息签名	verify
rpc account-balance	通过 RPC 获取账户余额	rpc_account-balance
rpc receivable	通过 RPC 列出可接收区块	rpc_receivable
rpc account-info	通过 RPC 获取账户信息	rpc_account-info
rpc probe-caps	探测 RPC 节点功能	rpc_probe-caps
block send	构建未签名的发送区块十六进制数据	block_send
block receive	构建未签名的接收区块十六进制数据	block_receive
block change	构建未签名的更改区块十六进制数据	block_change
mcp	启动 MCP 服务或查看配置	mcp

---

故障排除

如果工具行为异常，请先调用 system_diag 以验证版本和环境：

{ "name": "system_diag", "arguments": {} }

返回：

• xnoSkills.version — xno-skills 版本
• xnoSkills.path — 解析后的可执行文件路径
• xnoSkills.invocation — 启动方式（npm-global、npx、bunx、source 等）
• ows.version — @open-wallet-standard/core 版本
• ows.path — OWS 包的位置
• environment.mockOws — 是否启用了模拟模式
• environment.nanoRpcUrl — 如果已设置，则为覆盖用的 RPC URL

命令行等效命令：

xno-skills diag
xno-skills diag --json

diag 不会发起网络请求。如果“本地 PoW 建议”是 false，或 PoW 耗时看起来异常，请运行 xno-skills rpc probe-caps <effective-work-url>，以验证远程 work_generate 支持情况。

恢复流程——“RPC request failed: All endpoints exhausted”、MCP 崩溃 / “Not connected” 错误、PoW 失败（POW_FAILED / 超时）：故障排除

---

快速入门示例

1. wallet_list: {}                    → discover "my-wallet" exists
2. wallet_balance: { wallet: "my-wallet" }    → check balance / pending
3. wallet_receive: { wallet: "my-wallet" }    → only if receipt was requested or pending funds are needed
4. wallet_send: { wallet: "my-wallet", destination: "nano_...", amountXno: "0.01" }