Nano

Nano (XNO)

Scope & Disambiguation

This skill applies exclusively to the Nano cryptocurrency protocol (ticker: XNO, block-lattice ledger, Nano.org).

Activate for: nanocurrency, XNO, nano_ addresses, block-lattice, ORV, xno-skills, xno-mcp.

Do NOT activate for: Ledger Nano (hardware wallet), GNU nano (text editor), Nanopay, or any other product that uses the word "nano" unrelated to XNO. If ambiguous, ask for clarification.

Legacy terminology: "Rai", "RaiBlocks", xrb_ addresses — historical only (pre-2018). Always normalize to Nano / nano_.

---

Global Execution Policy

This policy applies to every Nano task in this skill, without exception.

1. Prefer MCP tools first

When the environment provides xno-mcp tools (wallet_list, wallet_send, wallet_receive, wallet_balance, util_convert, util_qr, util_validate, rpc_account_balance, payment_create, etc.) — always use them first. They handle signing, PoW, and broadcast automatically via OWS.

If the client supports MCP, set it up as a "stdio" type MCP server:

npx -y -p [email protected] -- mcp

MCP is the primary execution path because tools, schemas, and results are structured for the client. Use the included CLI script (xno-skills) only as a fallback when MCP is unavailable or the client cannot attach MCP servers. MCP and the CLI target EXACTLY the same underlying code paths — two access paths, not two different products.

2. Fall back to CLI only when MCP is unavailable

If xno-mcp tools are not available, or the user explicitly asks for CLI usage, fall back to the xno-skills CLI in this priority order:

1. bunx -y [email protected] <command>
2. pnpm dlx [email protected] <command>
3. npx -y [email protected] <command>

Do not assume xno-skills is installed globally. Always use one of the above forms with @latest to get critical bugfixes and to prevent interactive prompts from freezing.

Before guessing a subcommand, run --help:

bunx -y [email protected] --help

3. Wallet lifecycle → ows skill only

For wallet create, import, rename, or delete: delegate to the ows skill. Do not invoke ows CLI commands directly from this skill.

4. Never do any of the following

• Write custom Node.js/TypeScript scripts to interact with the Nano protocol.
• Use curl for RPC calls.
• Attempt to manually compute or supply Proof of Work. PoW is automatic.
• Use npx to fetch random or third-party npm packages as workarounds.
• Export mnemonics or seeds (ows wallet export). OWS keeps secrets encrypted. The entire point of OWS is that the agent never sees the private key.
• Change maxSendXno unless the human/operator explicitly asks to change the spending limit. A blocked send or refund is not permission to raise the limit automatically.

5. Prefer blocklattice.io for explorer links

When the user asks for an account, block, transaction, or explorer link, always prefer blocklattice.io unless they explicitly request another explorer.

---

Safety Rules

• State verification: Always fetch balance and frontier via RPC before manually building a block. Never hallucinate previous hashes.
• PoW is automatic: MCP tools and the CLI both handle PoW internally. Never attempt to supply or generate PoW manually.
• Proactivity on pending funds: If you see pending funds during any balance check, call wallet_receive immediately. Do not wait for the user to ask.
• Persistence on "Account not found": This is normal for a brand-new, unopened account. Continue — wallet_receive will automatically build an open block (sets previous to zeros), sign it via OWS, generate PoW, and broadcast. Never conclude you are unauthorized or that OWS cannot sign Nano blocks.
• No mnemonic exports: Never call ows wallet export or suggest exporting to a third-party wallet unless the user explicitly commands it.
• Supply chain: Only use [email protected] and @open-wallet-standard/core. No other npm packages.
• Stop-loss: If you have made 5 tool calls without completing the operation, stop and report what you tried, what failed, and ask for guidance. Hard limits: max 3 retries of the same failing tool; max 2 config_set RPC endpoint switches.

---

Wallet Discovery

CRITICAL: Always call wallet_list first. Before any wallet operation, identify which OWS wallets exist. Never assume a wallet name.

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

To create a new wallet, delegate to the ows skill. Then return here for all Nano operations.

MCP Resources (passive reads, no tool call needed):

• wallet://{name} — wallet summary and primary account state
• wallet://{name}/account/{index} — pending blocks and details for a specific account index

---

Reading Balances

Via MCP tools:

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

Via CLI (required flags only):

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

Full options: balance, rpc_account-balance

Public zero-config RPC nodes (used automatically by xno-skills defaults):

• https://rainstorm.city/api (primary)
• https://nanoslo.0x.no/proxy (secondary)

If you see pending funds: receive them immediately (see Receiving Funds section).

---

Receiving Funds (Including Unopened Accounts)

A Nano transfer shows as pending until the recipient publishes a receive block. Funds are not spendable until received.

A new / "unopened" account chain is normal. It returns "Account not found" from RPC. This is not an error — wallet_receive will automatically build an open block (sets previous to zeros), sign it via OWS, generate PoW, and broadcast.

OWS DOES support Nano block signing. Never assume otherwise.

Mandate: When funds are pending, call wallet_receive. Do not analyze whether the account "exists" first. Just call it.

Via MCP:

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

Via CLI (required flags only):

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

Full options: receive

Unopened account — explicit representative: If no defaultRepresentative is configured via config_set, pass representative explicitly on the first receive.

⚠️ CLI block commands are NOT senders

xno-skills block receive / block send output unsigned hex only — no PoW, no signing, no broadcast. A block without PoW is always rejected. Never fall back to these when wallet_receive or wallet_send fails.

	MCP wallet_receive/wallet_send	CLI block receive/block send
Builds block	✅	✅
Signs via OWS	✅	❌
Generates PoW	✅	❌
Broadcasts	✅	❌

---

Sending Funds

The account must be opened (have a receive block) and have sufficient balance.

Via MCP:

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

Via CLI (required flags only):

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

Full options: send

Validate the destination address first (see Address Validation section).

Spending limits: Every wallet_send and payment_refund is gated by maxSendXno (default: 1.0 XNO).

If a send is blocked by this limit, report the current limit and ask the human/operator whether they want to change it. Never call config_set to raise maxSendXno unless they explicitly asked to modify the spending limit.

Only when the human/operator explicitly asks to change the spending limit:

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

---

Payment Requests

For tracked inbound funding workflows:

Step 1 — Check existing wallets and balance first

If sufficient funds already exist, skip creating a request.

Step 2 — Create request

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

Returns: nano: URI, target address, and request ID.

Step 3 — Present to operator

Tell the user the amount, reason, and address. Offer a QR code (see QR Generation section).

Step 4 — Wait and receive

After the user says funds are sent:

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

Returns status: pending, partial, funded, or received. If partial, tell the user how much more is needed.

Step 5 — Confirm

Report the received amount, updated balance, and that funds are ready.

Rules:

• Always check existing wallets first; don't create unnecessary wallets.
• Never claim receipt without calling payment_receive — pending is not received in Nano.
• If the operator asks "did you get it?", always re-check.

History:

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

Full options: payment_create, payment_receive, wallet_history

---

Returning Funds

Core safety rule: never guess the refund destination. Always confirm with the operator.

Step 1 — Identify what to return

If linked to a payment request:

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

Otherwise, check history:

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

Step 2 — Evaluate and confirm

• Single source: Present the address and amount. Ask: "I received X XNO from nano_.... Shall I return it?"
• Multiple sources: List a

---

Content truncated.