xno-skills 4.7.3 → 4.7.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/dist/cjs/cli.js +4 -4
- package/dist/cjs/version.d.ts +2 -2
- package/dist/cjs/version.js +1 -1
- package/dist/esm/cli.js +4 -4
- package/dist/esm/version.d.ts +2 -2
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
- package/skills/nano/SKILL.md +51 -172
- package/skills/nano/references/blocklattice.md +72 -0
- package/skills/nano/references/config.md +49 -0
- package/skills/nano/references/mcp.md +4 -4
- package/skills/nano/references/payment.create.md +18 -0
- package/skills/nano/references/payment.receive.md +15 -0
- package/skills/nano/references/payment.refund.md +25 -0
- package/skills/nano/references/troubleshooting.md +39 -0
package/README.md
CHANGED
|
@@ -72,7 +72,7 @@ xno-skills --help
|
|
|
72
72
|
|
|
73
73
|
To pin to the current stable release instead:
|
|
74
74
|
```bash
|
|
75
|
-
npm install -g xno-skills@4.7.
|
|
75
|
+
npm install -g xno-skills@4.7.4 && npx -y skills add CasualSecurityInc/xno-skills -g -y --all
|
|
76
76
|
```
|
|
77
77
|
|
|
78
78
|
|
|
@@ -132,7 +132,7 @@ Exposes Nano wallet functions as tools for AI agents (Claude Desktop, Cursor, Co
|
|
|
132
132
|
**Preferred** (global install — avoids `npx` concurrency handshake failures):
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
|
-
npm install -g xno-skills@4.7.
|
|
135
|
+
npm install -g xno-skills@4.7.4
|
|
136
136
|
```
|
|
137
137
|
|
|
138
138
|
```json
|
|
@@ -153,7 +153,7 @@ npm install -g xno-skills@4.7.3
|
|
|
153
153
|
"mcpServers": {
|
|
154
154
|
"nano": {
|
|
155
155
|
"command": "npx",
|
|
156
|
-
"args": ["-y", "-p", "xno-skills@4.7.
|
|
156
|
+
"args": ["-y", "-p", "xno-skills@4.7.4", "xno-mcp"]
|
|
157
157
|
}
|
|
158
158
|
}
|
|
159
159
|
}
|
|
@@ -166,7 +166,7 @@ npm install -g xno-skills@4.7.3
|
|
|
166
166
|
<summary>Codex</summary>
|
|
167
167
|
|
|
168
168
|
```bash
|
|
169
|
-
# Preferred (after npm install -g xno-skills@4.7.
|
|
169
|
+
# Preferred (after npm install -g xno-skills@4.7.4):
|
|
170
170
|
codex mcp add nano \
|
|
171
171
|
-c sandbox_mode="danger-full-access" \
|
|
172
172
|
-c 'sandbox_permissions=["network-access"]' \
|
|
@@ -176,7 +176,7 @@ codex mcp add nano \
|
|
|
176
176
|
codex mcp add nano \
|
|
177
177
|
-c sandbox_mode="danger-full-access" \
|
|
178
178
|
-c 'sandbox_permissions=["network-access"]' \
|
|
179
|
-
-- npx -y -p xno-skills@4.7.
|
|
179
|
+
-- npx -y -p xno-skills@4.7.4 xno-mcp
|
|
180
180
|
```
|
|
181
181
|
</details>
|
|
182
182
|
|
package/dist/cjs/cli.js
CHANGED
|
@@ -796,7 +796,7 @@ Configuration for popular AI agent harnesses:
|
|
|
796
796
|
|
|
797
797
|
Preferred (global install — avoids npx concurrency handshake failures):
|
|
798
798
|
|
|
799
|
-
npm install -g xno-skills@4.7.
|
|
799
|
+
npm install -g xno-skills@4.7.4
|
|
800
800
|
|
|
801
801
|
1. Claude Desktop / Cursor / Roo Code (in config.json):
|
|
802
802
|
{
|
|
@@ -821,16 +821,16 @@ Fallback (if global install is not possible):
|
|
|
821
821
|
"mcpServers": {
|
|
822
822
|
"xno": {
|
|
823
823
|
"command": "npx",
|
|
824
|
-
"args": ["-y", "xno-skills@4.7.
|
|
824
|
+
"args": ["-y", "xno-skills@4.7.4", "mcp"]
|
|
825
825
|
}
|
|
826
826
|
}
|
|
827
827
|
}
|
|
828
828
|
|
|
829
829
|
2. Gemini CLI:
|
|
830
|
-
gemini mcp add xno npx -y xno-skills@4.7.
|
|
830
|
+
gemini mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
831
831
|
|
|
832
832
|
3. Claude Code:
|
|
833
|
-
claude mcp add xno npx -y xno-skills@4.7.
|
|
833
|
+
claude mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
834
834
|
|
|
835
835
|
To run the MCP server directly in this terminal:
|
|
836
836
|
xno-skills mcp (if globally installed)
|
package/dist/cjs/version.d.ts
CHANGED
package/dist/cjs/version.js
CHANGED
package/dist/esm/cli.js
CHANGED
|
@@ -796,7 +796,7 @@ Configuration for popular AI agent harnesses:
|
|
|
796
796
|
|
|
797
797
|
Preferred (global install — avoids npx concurrency handshake failures):
|
|
798
798
|
|
|
799
|
-
npm install -g xno-skills@4.7.
|
|
799
|
+
npm install -g xno-skills@4.7.4
|
|
800
800
|
|
|
801
801
|
1. Claude Desktop / Cursor / Roo Code (in config.json):
|
|
802
802
|
{
|
|
@@ -821,16 +821,16 @@ Fallback (if global install is not possible):
|
|
|
821
821
|
"mcpServers": {
|
|
822
822
|
"xno": {
|
|
823
823
|
"command": "npx",
|
|
824
|
-
"args": ["-y", "xno-skills@4.7.
|
|
824
|
+
"args": ["-y", "xno-skills@4.7.4", "mcp"]
|
|
825
825
|
}
|
|
826
826
|
}
|
|
827
827
|
}
|
|
828
828
|
|
|
829
829
|
2. Gemini CLI:
|
|
830
|
-
gemini mcp add xno npx -y xno-skills@4.7.
|
|
830
|
+
gemini mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
831
831
|
|
|
832
832
|
3. Claude Code:
|
|
833
|
-
claude mcp add xno npx -y xno-skills@4.7.
|
|
833
|
+
claude mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
834
834
|
|
|
835
835
|
To run the MCP server directly in this terminal:
|
|
836
836
|
xno-skills mcp (if globally installed)
|
package/dist/esm/version.d.ts
CHANGED
package/dist/esm/version.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xno-skills",
|
|
3
|
-
"version": "4.7.
|
|
3
|
+
"version": "4.7.4",
|
|
4
4
|
"description": "The Nano (XNO) toolkit for AI agents and developers. Send, receive, check balances, and manage payment requests without ever handling private keys.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/cjs/index.js",
|
package/skills/nano/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: nano
|
|
3
|
-
description: "Nano (XNO) cryptocurrency wallet operations, transaction analysis, and explorer lookups. Use for send/receive, balances, pending funds, address validation, unit conversion, tx/hash/account lookup, explorer links, and Nano block-lattice questions. Prefer xno-mcp first; use xno-skills CLI as fallback."
|
|
3
|
+
description: "Nano (XNO) cryptocurrency wallet operations, transaction analysis, and explorer lookups. Use for send/receive, balances, pending funds, address validation, unit conversion, tx/hash/account lookup, explorer links, and Nano block-lattice questions. Prefer xno-mcp first; use xno-skills CLI as fallback. Configured OWS wallets ARE the assistant's own wallets — never claim you cannot receive or hold Nano."
|
|
4
4
|
triggers:
|
|
5
5
|
- nano
|
|
6
6
|
- xno
|
|
@@ -73,6 +73,26 @@ This skill applies **exclusively to the Nano cryptocurrency protocol** (ticker:
|
|
|
73
73
|
|
|
74
74
|
---
|
|
75
75
|
|
|
76
|
+
## Wallet Ownership & Agent Authority
|
|
77
|
+
|
|
78
|
+
Wallets returned by `wallet_list` are wallets configured for this assistant environment. Treat them as **assistant-controlled wallets** for Nano operations.
|
|
79
|
+
|
|
80
|
+
**The assistant may**:
|
|
81
|
+
|
|
82
|
+
- list wallets;
|
|
83
|
+
- inspect balances, pending funds, history, and representatives;
|
|
84
|
+
- receive funds into an assistant-controlled wallet;
|
|
85
|
+
- provide an assistant-controlled receiving address;
|
|
86
|
+
- send funds when the user explicitly requests it.
|
|
87
|
+
|
|
88
|
+
> **Never say** "I don't have a wallet", "I can't receive funds", or "the skill only operates wallets you control" when `wallet_list` exposes configured wallets.
|
|
89
|
+
|
|
90
|
+
**Disambiguation**: "Send me Nano" means send to an **assistant-controlled wallet**, unless the user names another recipient. Do not reinterpret it as a request to send to a hypothetical personal wallet, and do not refuse on that basis.
|
|
91
|
+
|
|
92
|
+
Before any wallet operation, call `wallet_list`. If the user says they want to send Nano to the assistant, list the wallets, identify a suitable receiving wallet/address, and present the full address (never abbreviated). Do not initiate a receive until the user asks to claim funds or a payment workflow requires it.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
76
96
|
## Global Execution Policy
|
|
77
97
|
|
|
78
98
|
**This policy applies to every Nano task in this skill, without exception.**
|
|
@@ -85,12 +105,12 @@ If the client supports MCP, set it up as a "stdio" type MCP server.
|
|
|
85
105
|
|
|
86
106
|
**Preferred — global install** (avoids `npx` concurrency issues that cause handshake failures):
|
|
87
107
|
|
|
88
|
-
npm install -g xno-skills@4.7.
|
|
108
|
+
npm install -g xno-skills@4.7.4
|
|
89
109
|
xno-skills mcp
|
|
90
110
|
|
|
91
111
|
**Fallback** (only if global install is not possible):
|
|
92
112
|
|
|
93
|
-
npx -y xno-skills@4.7.
|
|
113
|
+
npx -y xno-skills@4.7.4 mcp
|
|
94
114
|
|
|
95
115
|
> **Why not `npx` by default?** When multiple agent sessions start concurrently, `npx` can fail during package resolution — the second process exits before the MCP handshake completes. A global install eliminates this race.
|
|
96
116
|
|
|
@@ -102,16 +122,16 @@ If `xno-mcp` tools are not available, or the user explicitly asks for CLI usage,
|
|
|
102
122
|
|
|
103
123
|
```
|
|
104
124
|
1. xno-skills <command> (global install — preferred)
|
|
105
|
-
2. bunx -y xno-skills@4.7.
|
|
106
|
-
3. pnpm dlx xno-skills@4.7.
|
|
107
|
-
4. npx -y xno-skills@4.7.
|
|
125
|
+
2. bunx -y xno-skills@4.7.4 <command>
|
|
126
|
+
3. pnpm dlx xno-skills@4.7.4 <command>
|
|
127
|
+
4. npx -y xno-skills@4.7.4 <command>
|
|
108
128
|
```
|
|
109
129
|
|
|
110
130
|
If the global `xno-skills` binary is not available, fall through to the next option. Always pin the version (`@4.5.2`) with `bunx`/`pnpm dlx`/`npx` to prevent interactive prompts from freezing.
|
|
111
131
|
|
|
112
132
|
Before guessing a subcommand, run `--help`:
|
|
113
133
|
```bash
|
|
114
|
-
xno-skills --help # or: bunx -y xno-skills@4.7.
|
|
134
|
+
xno-skills --help # or: bunx -y xno-skills@4.7.4 --help
|
|
115
135
|
```
|
|
116
136
|
|
|
117
137
|
### 3. Wallet lifecycle → `ows` skill only
|
|
@@ -140,7 +160,7 @@ When the user asks for an account, block, transaction, or explorer link, always
|
|
|
140
160
|
- **Pre-send state**: Before `wallet_send`, inspect the source wallet's confirmed balance and total receivable amount with `wallet_balance`. If confirmed funds cannot cover the requested send and receivables are needed, call `wallet_receive`, then recheck. Do not submit receive blocks merely because unrelated funds are pending.
|
|
141
161
|
- **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.
|
|
142
162
|
- **No mnemonic exports**: Never call `ows wallet export` or suggest exporting to a third-party wallet unless the user explicitly commands it.
|
|
143
|
-
- **Supply chain**: Only use `xno-skills@4.7.
|
|
163
|
+
- **Supply chain**: Only use `xno-skills@4.7.4` and `@open-wallet-standard/core`. No other npm packages.
|
|
144
164
|
- **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.
|
|
145
165
|
|
|
146
166
|
---
|
|
@@ -171,8 +191,8 @@ To **create** a new wallet, delegate to the `ows` skill. Then return here for al
|
|
|
171
191
|
|
|
172
192
|
**Via CLI (required flags only):**
|
|
173
193
|
```bash
|
|
174
|
-
bunx -y xno-skills@4.7.
|
|
175
|
-
bunx -y xno-skills@4.7.
|
|
194
|
+
bunx -y xno-skills@4.7.4 balance --wallet "my-wallet"
|
|
195
|
+
bunx -y xno-skills@4.7.4 rpc account-balance <address>
|
|
176
196
|
```
|
|
177
197
|
|
|
178
198
|
Full options: [balance](references/balance.md), [rpc_account-balance](references/rpc_account-balance.md)
|
|
@@ -203,7 +223,7 @@ When receipt is requested or needed to fund a send, call `wallet_receive`. Do no
|
|
|
203
223
|
|
|
204
224
|
**Via CLI (required flags only):**
|
|
205
225
|
```bash
|
|
206
|
-
bunx -y xno-skills@4.7.
|
|
226
|
+
bunx -y xno-skills@4.7.4 receive --wallet "my-wallet"
|
|
207
227
|
```
|
|
208
228
|
|
|
209
229
|
Full options: [receive](references/receive.md)
|
|
@@ -237,7 +257,7 @@ The account must be opened (have a receive block) and have sufficient balance.
|
|
|
237
257
|
|
|
238
258
|
**Via CLI (required flags only):**
|
|
239
259
|
```bash
|
|
240
|
-
bunx -y xno-skills@4.7.
|
|
260
|
+
bunx -y xno-skills@4.7.4 send --wallet "my-wallet" --to "nano_..." --amount-xno 0.01
|
|
241
261
|
```
|
|
242
262
|
|
|
243
263
|
Full options: [send](references/send.md)
|
|
@@ -353,7 +373,7 @@ Generates a terminal-friendly ASCII QR code for a Nano address, optionally with
|
|
|
353
373
|
|
|
354
374
|
**Via CLI (required args only):**
|
|
355
375
|
```bash
|
|
356
|
-
bunx -y xno-skills@4.7.
|
|
376
|
+
bunx -y xno-skills@4.7.4 qr nano_1abc...
|
|
357
377
|
```
|
|
358
378
|
|
|
359
379
|
Full options: [qr](references/qr.md)
|
|
@@ -380,7 +400,7 @@ All validation is **offline** — no network required.
|
|
|
380
400
|
|
|
381
401
|
**Via CLI:**
|
|
382
402
|
```bash
|
|
383
|
-
bunx -y xno-skills@4.7.
|
|
403
|
+
bunx -y xno-skills@4.7.4 validate nano_1abc...
|
|
384
404
|
```
|
|
385
405
|
|
|
386
406
|
Full options: [validate](references/validate.md)
|
|
@@ -407,10 +427,10 @@ XNO uses **30 decimal places**. Floating-point arithmetic is unsafe. Always use
|
|
|
407
427
|
|
|
408
428
|
**Via CLI:**
|
|
409
429
|
```bash
|
|
410
|
-
bunx -y xno-skills@4.7.
|
|
411
|
-
bunx -y xno-skills@4.7.
|
|
412
|
-
bunx -y xno-skills@4.7.
|
|
413
|
-
bunx -y xno-skills@4.7.
|
|
430
|
+
bunx -y xno-skills@4.7.4 convert 1 xno # all units
|
|
431
|
+
bunx -y xno-skills@4.7.4 convert 1 knano
|
|
432
|
+
bunx -y xno-skills@4.7.4 convert 1000000000000000000000000000000 raw
|
|
433
|
+
bunx -y xno-skills@4.7.4 convert 1 xno --json
|
|
414
434
|
```
|
|
415
435
|
|
|
416
436
|
Full options: [convert](references/convert.md)
|
|
@@ -436,20 +456,20 @@ Present the user with this command to run locally:
|
|
|
436
456
|
|
|
437
457
|
```bash
|
|
438
458
|
# Sign — run this yourself, replacing the placeholder with your actual key
|
|
439
|
-
bunx -y xno-skills@4.7.
|
|
459
|
+
bunx -y xno-skills@4.7.4 sign "<message>" --key YOUR_PRIVATE_KEY_HEX
|
|
440
460
|
|
|
441
461
|
# Sign with JSON output
|
|
442
|
-
bunx -y xno-skills@4.7.
|
|
462
|
+
bunx -y xno-skills@4.7.4 sign "<message>" --key YOUR_PRIVATE_KEY_HEX --json
|
|
443
463
|
```
|
|
444
464
|
|
|
445
465
|
For verify, the agent *can* run this directly (no secret material involved):
|
|
446
466
|
|
|
447
467
|
```bash
|
|
448
468
|
# Verify
|
|
449
|
-
bunx -y xno-skills@4.7.
|
|
469
|
+
bunx -y xno-skills@4.7.4 verify <nano_address> "<message>" <signature-hex>
|
|
450
470
|
|
|
451
471
|
# Verify with JSON output
|
|
452
|
-
bunx -y xno-skills@4.7.
|
|
472
|
+
bunx -y xno-skills@4.7.4 verify <nano_address> "<message>" <signature-hex> --json
|
|
453
473
|
```
|
|
454
474
|
|
|
455
475
|
**NOMS standard (ORIS-001)**: Signatures are computed over a binary payload with a magic header, ensuring a valid signature cannot be misinterpreted as a Nano transaction block.
|
|
@@ -462,90 +482,25 @@ Full options: [sign](references/sign.md), [verify](references/verify.md)
|
|
|
462
482
|
|
|
463
483
|
---
|
|
464
484
|
|
|
465
|
-
##
|
|
466
|
-
|
|
467
|
-
**The ledger is a block lattice** — a set of completely independent account-chains.
|
|
468
|
-
|
|
469
|
-
- Every account maintains its own linear chain of state blocks.
|
|
470
|
-
- Only the account owner (private-key holder) can append to their chain.
|
|
471
|
-
- No global mempool, no miners, no gas fees, no block producers.
|
|
472
|
-
- Each block records the **full current state** of its account (balance, representative, previous hash).
|
|
473
|
-
- Total supply is fixed at genesis.
|
|
474
|
-
|
|
475
|
-
### Universal State Blocks
|
|
476
|
-
|
|
477
|
-
**All blocks today are Universal State Blocks** (`type: "state"`):
|
|
478
|
-
|
|
479
|
-
```json
|
|
480
|
-
{
|
|
481
|
-
"type": "state",
|
|
482
|
-
"account": "nano_...",
|
|
483
|
-
"previous": "64-hex...", // frontier hash, or "0" for open block
|
|
484
|
-
"representative": "nano_...",
|
|
485
|
-
"balance": "decimal-string", // new balance in raw (1 XNO = 10^30 raw)
|
|
486
|
-
"link": "...", // send: destination address; receive: send block hash; change: "0"
|
|
487
|
-
"signature": "128-hex...",
|
|
488
|
-
"work": "16-hex..."
|
|
489
|
-
}
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
### The Account-Chain Dance
|
|
493
|
-
|
|
494
|
-
**Alice sends to Bob**:
|
|
495
|
-
1. Alice builds a Send block: `previous` = her frontier, `balance` = old − amount, `link` = Bob's address.
|
|
496
|
-
2. Alice signs + PoW + broadcasts. Funds are **irrevocably deducted** from Alice and become **pending** on Bob's chain.
|
|
497
|
-
|
|
498
|
-
**Bob must claim**:
|
|
499
|
-
1. Bob builds a Receive block: `previous` = his frontier (zeros for open), `balance` = old + amount, `link` = Alice's send block hash.
|
|
500
|
-
2. Bob signs + PoW + broadcasts. Only then are funds spendable.
|
|
501
|
-
|
|
502
|
-
**Critical**: The send is final for Alice. Funds are not spendable by Bob until his receive block is confirmed. There is no automatic receive. Pending funds sit forever until claimed.
|
|
503
|
-
|
|
504
|
-
### PoW Thresholds (Epoch v2, 2026)
|
|
485
|
+
## Nano Protocol Reference
|
|
505
486
|
|
|
506
|
-
-
|
|
507
|
-
- Receive / Open / Epoch: `fffffe0000000000`
|
|
487
|
+
The ledger is a block lattice of independent account-chains. Every block is a Universal State Block carrying full account state (balance, representative, previous hash). A send is final immediately; funds become spendable only when the recipient publishes a receive/open block. Pending funds sit unclaimed forever until received.
|
|
508
488
|
|
|
509
|
-
|
|
510
|
-
threshold `ffffffc000000000` is legacy-only and must not be selected for
|
|
511
|
-
current mainnet blocks.
|
|
489
|
+
Deep protocol details — state-block anatomy, open/send/receive/change semantics, PoW thresholds, key/address derivations, representatives & ORV: [blocklattice](references/blocklattice.md)
|
|
512
490
|
|
|
513
|
-
|
|
514
|
-
- Open block (height 1): `blake2b(nonce || public_key)`
|
|
515
|
-
- All other blocks: `blake2b(nonce || previous_frontier_hash)`
|
|
491
|
+
### Changing Representative
|
|
516
492
|
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
### Representatives & ORV
|
|
520
|
-
|
|
521
|
-
- Voting weight = balance delegated to a representative.
|
|
522
|
-
- Quorum = >67% of online weight → confirmed → cemented (deterministic finality, typically <1s).
|
|
523
|
-
- Choose representatives with high uptime, low voting weight concentration, and trustworthy operators.
|
|
524
|
-
- Lists: [blocklattice.io/representatives](https://blocklattice.io/representatives), [nanoticker.org](https://nanoticker.org/representatives)
|
|
525
|
-
|
|
526
|
-
**Change representative:**
|
|
527
493
|
```json
|
|
528
494
|
{ "name": "wallet_change_rep", "arguments": { "wallet": "my-wallet", "representative": "nano_..." } }
|
|
529
495
|
```
|
|
530
496
|
```bash
|
|
531
|
-
bunx -y xno-skills@4.7.
|
|
497
|
+
bunx -y xno-skills@4.7.4 change-rep --wallet "my-wallet" --representative "nano_..."
|
|
532
498
|
```
|
|
533
499
|
|
|
534
500
|
Full options: [change-rep](references/change-rep.md)
|
|
535
501
|
|
|
536
|
-
###
|
|
502
|
+
### Explorer Links
|
|
537
503
|
|
|
538
|
-
- **Seed**: 32 bytes (64 hex, uppercase)
|
|
539
|
-
- **Private key**: `blake2b(32, seed || index)`, index as 4-byte big-endian uint
|
|
540
|
-
- **Address**: `nano_` + 52-base32(public key) + 8-base32(Blake2b-40 checksum). Total 65 chars.
|
|
541
|
-
- **Block hash / frontier**: 32 bytes (64 hex)
|
|
542
|
-
- **Signature**: 64 bytes (128 hex), Ed25519 + Blake2b
|
|
543
|
-
- **Work**: 8 bytes (16 hex)
|
|
544
|
-
- **Balance**: always raw units as decimal string in JSON. Never floating-point.
|
|
545
|
-
|
|
546
|
-
### Blockchain Explorer
|
|
547
|
-
|
|
548
|
-
- Always prefer `blocklattice.io` unless the user explicitly requests another explorer.
|
|
549
504
|
- Account: `https://blocklattice.io/account/<nano_address>`
|
|
550
505
|
- Block: `https://blocklattice.io/block/<UPPERCASE_HEX_HASH>`
|
|
551
506
|
|
|
@@ -553,68 +508,9 @@ Full options: [change-rep](references/change-rep.md)
|
|
|
553
508
|
|
|
554
509
|
## Configuration & Defaults
|
|
555
510
|
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
**No configuration is required to get started.** Defaults work out of the box:
|
|
511
|
+
No configuration required: public RPC nodes, local-first WASM/GPU PoW with remote fallback, default representative, max send `1.0 XNO`. Config lives in a JSON file that reloads before every operation — overrides via `config_set` or `NANO_RPC_URL` / `NANO_WORK_URL` env vars take effect immediately, no restart.
|
|
559
512
|
|
|
560
|
-
|
|
561
|
-
- PoW: local WASM/GPU by default; falls back to remote via the first RPC node when local is not performant
|
|
562
|
-
- Representative: `nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4`
|
|
563
|
-
- Max per send: `1.0 XNO`
|
|
564
|
-
|
|
565
|
-
### Override precedence
|
|
566
|
-
|
|
567
|
-
**Remote PoW URL** (resolved in order):
|
|
568
|
-
1. `NANO_WORK_URL` env var
|
|
569
|
-
2. saved config `workUrl`
|
|
570
|
-
3. `NANO_RPC_URL` env var
|
|
571
|
-
4. saved config `rpcUrl`
|
|
572
|
-
5. default primary RPC node
|
|
573
|
-
|
|
574
|
-
**RPC endpoint list** (normal traffic):
|
|
575
|
-
1. explicit tool argument `rpcUrl`
|
|
576
|
-
2. saved config `rpcUrl`
|
|
577
|
-
3. `NANO_RPC_URL` env var
|
|
578
|
-
4. default RPC node list
|
|
579
|
-
|
|
580
|
-
### Setting values
|
|
581
|
-
|
|
582
|
-
```json
|
|
583
|
-
{ "name": "config_set", "arguments": { "workUrl": "https://my-node.example/api" } }
|
|
584
|
-
```
|
|
585
|
-
|
|
586
|
-
### Resetting values
|
|
587
|
-
|
|
588
|
-
Setting a string field to `""` or `null` clears the saved override (falls back to defaults):
|
|
589
|
-
```json
|
|
590
|
-
{ "name": "config_set", "arguments": { "workUrl": "" } }
|
|
591
|
-
```
|
|
592
|
-
|
|
593
|
-
Setting a number field to `null` clears the saved override:
|
|
594
|
-
```json
|
|
595
|
-
{ "name": "config_set", "arguments": { "powTimeoutMs": null } }
|
|
596
|
-
```
|
|
597
|
-
|
|
598
|
-
Omitted fields are preserved unchanged.
|
|
599
|
-
|
|
600
|
-
---
|
|
601
|
-
|
|
602
|
-
## RPC Error Recovery
|
|
603
|
-
|
|
604
|
-
**"RPC request failed: All endpoints exhausted"** is almost always transient (rate limiting, brief node restart). Follow in order, stopping as soon as one works:
|
|
605
|
-
|
|
606
|
-
| Step | Action |
|
|
607
|
-
|---|---|
|
|
608
|
-
| 1 | Wait 5 s. Retry with identical arguments. |
|
|
609
|
-
| 2 | `config_set({ rpcUrl: "https://rainstorm.city/api" })`, retry. |
|
|
610
|
-
| 3 | `config_set({ rpcUrl: "https://nanoslo.0x.no/proxy" })`, retry. |
|
|
611
|
-
| 4 | `config_set({ rpcUrl: "https://rpc.nano.to" })`, retry. |
|
|
612
|
-
| 5 | Try any other public node, retry. |
|
|
613
|
-
| 6 | `config_set({ rpcUrl: "" })` to reset. **Stop — report to user.** |
|
|
614
|
-
|
|
615
|
-
Calling `config_set` with a new `rpcUrl` creates a fresh `NanoClient`, bypassing the exponential backoff cooldown on default endpoints.
|
|
616
|
-
|
|
617
|
-
**Prohibited at every step**: custom scripts, curl, CLI `block` commands, manual PoW.
|
|
513
|
+
Defaults, override precedence, set/reset semantics: [config](references/config.md)
|
|
618
514
|
|
|
619
515
|
---
|
|
620
516
|
|
|
@@ -673,24 +569,7 @@ xno-skills diag --json
|
|
|
673
569
|
|
|
674
570
|
`diag` does not make network calls. If `Local PoW Recommended` is `false` or PoW timing looks surprising, run `xno-skills rpc probe-caps <effective-work-url>` to verify remote `work_generate` support.
|
|
675
571
|
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
- **OWS is an in-process library, NOT a daemon**: There is no background "OWS daemon" or wallet service running. `@open-wallet-standard/core` is a library loaded entirely in-process by the MCP server and CLI.
|
|
679
|
-
- **"Not connected" from MCP client**: If an MCP client/agent receives a "Not connected" error on `wallet_balance` or any other tool, it typically means the underlying `xno-mcp` server process has crashed (usually due to a Rust native addon panic during PoW or backend initialization) or was terminated. It does **not** mean a background daemon is down.
|
|
680
|
-
|
|
681
|
-
### PoW failures (`POW_FAILED` / timeout)
|
|
682
|
-
|
|
683
|
-
**PoW is done locally by default.** xno-skills uses WASM-based Proof of Work that runs in-process — no external work peer is required.
|
|
684
|
-
|
|
685
|
-
On first use, the system probes local backends to build a local-first execution plan. This probe itself runs real PoW and may take 5–15 seconds — this is normal and happens on the first PoW operation in a process.
|
|
686
|
-
|
|
687
|
-
**Diagnose in order, stopping at the first resolution:**
|
|
688
|
-
|
|
689
|
-
| Step | Check | Action |
|
|
690
|
-
|---|---|---|
|
|
691
|
-
| 1 | Was this the very first `send`/`receive` on a fresh MCP or CLI process? | Allow for first-use warmup. Retry the operation once. |
|
|
692
|
-
| 2 | Did the error say "Timed out after 10000ms"? | That is the local WASM per-backend timeout. It means WASM itself failed or is unavailable. Check Node.js version (`node --version`) — WASM PoW requires Node 16+. |
|
|
693
|
-
| 3 | Is the system under heavy CPU load? | WASM PoW is CPU-bound. A send block requires ~8× more work than receive. Wait for load to drop, then retry. |
|
|
572
|
+
Recovery procedures — **"RPC request failed: All endpoints exhausted"**, **MCP crashes / "Not connected" errors**, **PoW failures (`POW_FAILED` / timeout)**: [troubleshooting](references/troubleshooting.md)
|
|
694
573
|
|
|
695
574
|
---
|
|
696
575
|
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Block-Lattice Protocol Reference
|
|
2
|
+
|
|
3
|
+
On-demand protocol reference for the Nano skill. Load this when you need block anatomy, PoW thresholds, key derivations, or consensus details — not during routine wallet operations.
|
|
4
|
+
|
|
5
|
+
## Block-Lattice Mental Model
|
|
6
|
+
|
|
7
|
+
**The ledger is a block lattice** — a set of completely independent account-chains.
|
|
8
|
+
|
|
9
|
+
- Every account maintains its own linear chain of state blocks.
|
|
10
|
+
- Only the account owner (private-key holder) can append to their chain.
|
|
11
|
+
- No global mempool, no miners, no gas fees, no block producers.
|
|
12
|
+
- Each block records the **full current state** of its account (balance, representative, previous hash).
|
|
13
|
+
- Total supply is fixed at genesis.
|
|
14
|
+
|
|
15
|
+
### Universal State Blocks
|
|
16
|
+
|
|
17
|
+
**All blocks today are Universal State Blocks** (`type: "state"`):
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"type": "state",
|
|
22
|
+
"account": "nano_...",
|
|
23
|
+
"previous": "64-hex...", // frontier hash, or "0" for open block
|
|
24
|
+
"representative": "nano_...",
|
|
25
|
+
"balance": "decimal-string", // new balance in raw (1 XNO = 10^30 raw)
|
|
26
|
+
"link": "...", // send: destination address; receive: send block hash; change: "0"
|
|
27
|
+
"signature": "128-hex...",
|
|
28
|
+
"work": "16-hex..."
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### The Account-Chain Dance
|
|
33
|
+
|
|
34
|
+
**Alice sends to Bob**:
|
|
35
|
+
1. Alice builds a Send block: `previous` = her frontier, `balance` = old − amount, `link` = Bob's address.
|
|
36
|
+
2. Alice signs + PoW + broadcasts. Funds are **irrevocably deducted** from Alice and become **pending** on Bob's chain.
|
|
37
|
+
|
|
38
|
+
**Bob must claim**:
|
|
39
|
+
1. Bob builds a Receive block: `previous` = his frontier (zeros for open), `balance` = old + amount, `link` = Alice's send block hash.
|
|
40
|
+
2. Bob signs + PoW + broadcasts. Only then are funds spendable.
|
|
41
|
+
|
|
42
|
+
**Critical**: The send is final for Alice. Funds are not spendable by Bob until his receive block is confirmed. There is no automatic receive. Pending funds sit forever until claimed.
|
|
43
|
+
|
|
44
|
+
### PoW Thresholds (Epoch v2, 2026)
|
|
45
|
+
|
|
46
|
+
- Send / Change: `fffffff800000000`
|
|
47
|
+
- Receive / Open / Epoch: `fffffe0000000000`
|
|
48
|
+
|
|
49
|
+
Epoch blocks use the receive/open threshold above. The historical epoch-1
|
|
50
|
+
threshold `ffffffc000000000` is legacy-only and must not be selected for
|
|
51
|
+
current mainnet blocks.
|
|
52
|
+
|
|
53
|
+
PoW input:
|
|
54
|
+
- Open block (height 1): `blake2b(nonce || public_key)`
|
|
55
|
+
- All other blocks: `blake2b(nonce || previous_frontier_hash)`
|
|
56
|
+
|
|
57
|
+
### Representatives & ORV
|
|
58
|
+
|
|
59
|
+
- Voting weight = balance delegated to a representative.
|
|
60
|
+
- Quorum = >67% of online weight → confirmed → cemented (deterministic finality, typically <1s).
|
|
61
|
+
- Choose representatives with high uptime, low voting weight concentration, and trustworthy operators.
|
|
62
|
+
- Lists: [blocklattice.io/representatives](https://blocklattice.io/representatives), [nanoticker.org](https://nanoticker.org/representatives)
|
|
63
|
+
|
|
64
|
+
### Data Representations
|
|
65
|
+
|
|
66
|
+
- **Seed**: 32 bytes (64 hex, uppercase)
|
|
67
|
+
- **Private key**: `blake2b(32, seed || index)`, index as 4-byte big-endian uint
|
|
68
|
+
- **Address**: `nano_` + 52-base32(public key) + 8-base32(Blake2b-40 checksum). Total 65 chars.
|
|
69
|
+
- **Block hash / frontier**: 32 bytes (64 hex)
|
|
70
|
+
- **Signature**: 64 bytes (128 hex), Ed25519 + Blake2b
|
|
71
|
+
- **Work**: 8 bytes (16 hex)
|
|
72
|
+
- **Balance**: always raw units as decimal string in JSON. Never floating-point.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Configuration Reference
|
|
2
|
+
|
|
3
|
+
On-demand configuration reference for `xno-mcp` / xno-skills. Load this when you need override precedence, env vars, or set/reset semantics.
|
|
4
|
+
|
|
5
|
+
## Defaults (zero-config)
|
|
6
|
+
|
|
7
|
+
- Public RPC nodes (`rainstorm.city`, `nanoslo.0x.no/proxy`, `rpc.nano.to`)
|
|
8
|
+
- PoW: local WASM/GPU by default; falls back to remote via the first RPC node when local is not performant
|
|
9
|
+
- Representative: `nano_3arg3asgtigae3xckabaaewkx3bzsh7nwz7jkmjos79ihyaxwphhm6qgjps4`
|
|
10
|
+
- Max per send: `1.0 XNO`
|
|
11
|
+
|
|
12
|
+
## Config file behavior
|
|
13
|
+
|
|
14
|
+
`xno-mcp` reads configuration from a JSON file on disk. It reloads the file before every operation, so manual edits take effect immediately. No restart required.
|
|
15
|
+
|
|
16
|
+
### Override precedence
|
|
17
|
+
|
|
18
|
+
**Remote PoW URL** (resolved in order):
|
|
19
|
+
1. `NANO_WORK_URL` env var
|
|
20
|
+
2. saved config `workUrl`
|
|
21
|
+
3. `NANO_RPC_URL` env var
|
|
22
|
+
4. saved config `rpcUrl`
|
|
23
|
+
5. default primary RPC node
|
|
24
|
+
|
|
25
|
+
**RPC endpoint list** (normal traffic):
|
|
26
|
+
1. explicit tool argument `rpcUrl`
|
|
27
|
+
2. saved config `rpcUrl`
|
|
28
|
+
3. `NANO_RPC_URL` env var
|
|
29
|
+
4. default RPC node list
|
|
30
|
+
|
|
31
|
+
### Setting values
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{ "name": "config_set", "arguments": { "workUrl": "https://my-node.example/api" } }
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Resetting values
|
|
38
|
+
|
|
39
|
+
Setting a string field to `""` or `null` clears the saved override (falls back to defaults):
|
|
40
|
+
```json
|
|
41
|
+
{ "name": "config_set", "arguments": { "workUrl": "" } }
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Setting a number field to `null` clears the saved override:
|
|
45
|
+
```json
|
|
46
|
+
{ "name": "config_set", "arguments": { "powTimeoutMs": null } }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Omitted fields are preserved unchanged.
|
|
@@ -12,7 +12,7 @@ Configuration for popular AI agent harnesses:
|
|
|
12
12
|
|
|
13
13
|
Preferred (global install — avoids npx concurrency handshake failures):
|
|
14
14
|
|
|
15
|
-
npm install -g xno-skills@4.7.
|
|
15
|
+
npm install -g xno-skills@4.7.4
|
|
16
16
|
|
|
17
17
|
1. Claude Desktop / Cursor / Roo Code (in config.json):
|
|
18
18
|
{
|
|
@@ -37,16 +37,16 @@ Fallback (if global install is not possible):
|
|
|
37
37
|
"mcpServers": {
|
|
38
38
|
"xno": {
|
|
39
39
|
"command": "npx",
|
|
40
|
-
"args": ["-y", "xno-skills@4.7.
|
|
40
|
+
"args": ["-y", "xno-skills@4.7.4", "mcp"]
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
43
|
}
|
|
44
44
|
|
|
45
45
|
2. Gemini CLI:
|
|
46
|
-
gemini mcp add xno npx -y xno-skills@4.7.
|
|
46
|
+
gemini mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
47
47
|
|
|
48
48
|
3. Claude Code:
|
|
49
|
-
claude mcp add xno npx -y xno-skills@4.7.
|
|
49
|
+
claude mcp add xno npx -y xno-skills@4.7.4 mcp
|
|
50
50
|
|
|
51
51
|
To run the MCP server directly in this terminal:
|
|
52
52
|
xno-skills mcp (if globally installed)
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# payment_create (MCP tool)
|
|
2
|
+
|
|
3
|
+
Create a tracked inbound Nano payment request against an OWS wallet.
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{ "name": "payment_create", "arguments": { "walletName": "my-wallet", "amountXno": "0.1", "reason": "testing payment flow" } }
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
| Argument | Required | Notes |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `walletName` | yes | OWS wallet that will receive the funds |
|
|
12
|
+
| `amountXno` | yes | Requested amount in XNO |
|
|
13
|
+
| `reason` | yes | Description shown to the payer |
|
|
14
|
+
| `accountIndex` | no | OWS only supports `0` |
|
|
15
|
+
|
|
16
|
+
Returns: `nano:` URI, target address, and request ID.
|
|
17
|
+
|
|
18
|
+
Workflow and rules: see Payment Requests in SKILL.md. Always check existing wallets/balances first.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# payment_receive (MCP tool)
|
|
2
|
+
|
|
3
|
+
Claim inbound funds for a tracked payment request and report status.
|
|
4
|
+
|
|
5
|
+
```json
|
|
6
|
+
{ "name": "payment_receive", "arguments": { "id": "<request-id>" } }
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Returns status: `pending`, `partial`, `funded`, or `received`.
|
|
10
|
+
|
|
11
|
+
- `pending` / `partial`: tell the user how much more is needed (for `partial`).
|
|
12
|
+
- Never claim receipt without calling this tool — pending is not received in Nano.
|
|
13
|
+
- If the operator asks "did you get it?", always re-check, even if you checked before.
|
|
14
|
+
|
|
15
|
+
Related queries: `payment_status` (single request by ID), `payment_list` (list requests, filterable by wallet/status).
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# payment_refund (MCP tool)
|
|
2
|
+
|
|
3
|
+
Return funds from a tracked payment request to the original payer.
|
|
4
|
+
|
|
5
|
+
## Step 1 — Dry run (default)
|
|
6
|
+
|
|
7
|
+
```json
|
|
8
|
+
{ "name": "payment_refund", "arguments": { "id": "<request-id>", "execute": false } }
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Evaluates the refund destination without sending anything. Never guess the refund destination — always confirm with the operator, showing the **full address** (never abbreviate).
|
|
12
|
+
|
|
13
|
+
## Step 2 — Execute after confirmation
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{ "name": "payment_refund", "arguments": { "id": "<request-id>", "execute": true, "confirmAddress": "nano_..." } }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`confirmAddress` must match the original source address.
|
|
20
|
+
|
|
21
|
+
**Edge cases:**
|
|
22
|
+
- Spending limit blocks the refund: report the current `maxSendXno` limit and ask whether the human/operator wants it changed. Never raise it unless explicitly requested.
|
|
23
|
+
- Not linked to a payment request: use `wallet_send` directly after confirming destination and amount with the operator.
|
|
24
|
+
|
|
25
|
+
Gated by `maxSendXno` like every send.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Troubleshooting Reference
|
|
2
|
+
|
|
3
|
+
On-demand recovery procedures for the Nano skill. Entry point: run `system_diag` / `xno-skills diag` first (see SKILL.md).
|
|
4
|
+
|
|
5
|
+
## "RPC request failed: All endpoints exhausted"
|
|
6
|
+
|
|
7
|
+
Almost always transient (rate limiting, brief node restart). Follow in order, stopping as soon as one works:
|
|
8
|
+
|
|
9
|
+
| Step | Action |
|
|
10
|
+
|---|---|
|
|
11
|
+
| 1 | Wait 5 s. Retry with identical arguments. |
|
|
12
|
+
| 2 | `config_set({ rpcUrl: "https://rainstorm.city/api" })`, retry. |
|
|
13
|
+
| 3 | `config_set({ rpcUrl: "https://nanoslo.0x.no/proxy" })`, retry. |
|
|
14
|
+
| 4 | `config_set({ rpcUrl: "https://rpc.nano.to" })`, retry. |
|
|
15
|
+
| 5 | Try any other public node, retry. |
|
|
16
|
+
| 6 | `config_set({ rpcUrl: "" })` to reset. **Stop — report to user.** |
|
|
17
|
+
|
|
18
|
+
Calling `config_set` with a new `rpcUrl` creates a fresh `NanoClient`, bypassing the exponential backoff cooldown on default endpoints.
|
|
19
|
+
|
|
20
|
+
**Prohibited at every step**: custom scripts, curl, CLI `block` commands, manual PoW.
|
|
21
|
+
|
|
22
|
+
## MCP Server Crashes & "Not connected" Errors
|
|
23
|
+
|
|
24
|
+
- **OWS is an in-process library, NOT a daemon**: There is no background "OWS daemon" or wallet service running. `@open-wallet-standard/core` is a library loaded entirely in-process by the MCP server and CLI.
|
|
25
|
+
- **"Not connected" from MCP client**: If an MCP client/agent receives a "Not connected" error on `wallet_balance` or any other tool, it typically means the underlying `xno-mcp` server process has crashed (usually due to a Rust native addon panic during PoW or backend initialization) or was terminated. It does **not** mean a background daemon is down.
|
|
26
|
+
|
|
27
|
+
## PoW failures (`POW_FAILED` / timeout)
|
|
28
|
+
|
|
29
|
+
**PoW is done locally by default.** xno-skills uses WASM-based Proof of Work that runs in-process — no external work peer is required.
|
|
30
|
+
|
|
31
|
+
On first use, the system probes local backends to build a local-first execution plan. This probe itself runs real PoW and may take 5–15 seconds — this is normal and happens on the first PoW operation in a process.
|
|
32
|
+
|
|
33
|
+
**Diagnose in order, stopping at the first resolution:**
|
|
34
|
+
|
|
35
|
+
| Step | Check | Action |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| 1 | Was this the very first `send`/`receive` on a fresh MCP or CLI process? | Allow for first-use warmup. Retry the operation once. |
|
|
38
|
+
| 2 | Did the error say "Timed out after 10000ms"? | That is the local WASM per-backend timeout. It means WASM itself failed or is unavailable. Check Node.js version (`node --version`) — WASM PoW requires Node 16+. |
|
|
39
|
+
| 3 | Is the system under heavy CPU load? | WASM PoW is CPU-bound. A send block requires ~8× more work than receive. Wait for load to drop, then retry. |
|