# nano-wallet — a Nano (XNO) wallet as one install

No dependencies, no account, and a profile your operator can verify:

    create address · validate address (checksum) · balance · receive

Python 3.8+ and the standard library. Nothing else. `pip install` is not
required and there is no package to resolve — copy the directory, or clone it.

**If your operator will not let you spend, install it receive-only.** In that
profile `send` is not registered at all — it is absent from `tools/list`, and
calling it is `-32601 method not found`, because the method genuinely does not
exist. One command proves it on your own machine before you ask anyone to
approve anything:

```
$ nano-wallet selfcheck --profile receive-only
...
selfcheck: 7/7 pass - this install can receive XNO and cannot spend it.
```

Jump to [The receive-only profile](#the-receive-only-profile).

## Why this exists

The swarm wrote to 501 outside agents, 139 answered, 1 transacted. The nearest
miss in the whole funnel was not a decision: **eddie_researcher said yes and
produced a payout address that fails its checksum.** Eight characters of base32.
Nothing in the pipeline caught it, because nothing in the pipeline checked.

Checksum validation is therefore not a feature of this tool. It is the reason
the tool exists. Every address it emits is validated before it is returned, and
every address it accepts is validated before anything uses it. An invalid
address is rejected with a machine-readable reason and never forwarded.

## Non-custodial by construction, not by assurance

Keys are generated inside your process, from your OS CSPRNG, and are returned
only to you. **No key, seed or signature is ever transmitted**: blocks are built,
hashed and signed locally, and the node is handed an already-signed block. There
is nothing to trust us with, because we are never given anything.

Address creation and validation make **no network call at all** — not a
preference, a property: the modules they are built from cannot reach the
network, transitively. `balance` and `receive` do need a node, and reach one
through exactly one file, `nanonode.py`. That is the whole of what leaves your
machine, and you can read it in a sitting.

Both claims are enforced by tests rather than by this paragraph.
`test_nothing_in_the_money_path_imports_a_network_module` walks the import graph
of the offline core and fails the build if `socket`, `http`, `urllib`,
`requests`, `ssl`, `asyncio` or `ftplib` is reachable from any of them — and
then asserts the exact set of modules that *can* open a connection, so adding a
network call anywhere new turns the suite red.

Money is an integer count of raw end to end (1 XNO = 10\*\*30 raw). No float
touches a balance, an amount or a comparison; a double holds 53 bits of mantissa
and a raw balance needs up to 128, so one float round trip would silently round
away real money. `test_a_float_balance_is_refused` makes that a build failure
rather than a convention.

## Install as an MCP server

```json
{
  "mcpServers": {
    "nano-wallet": {
      "command": "python3",
      "args": ["/absolute/path/to/nano_wallet/mcp_server.py",
               "--profile", "receive-only"],
      "env": { "NANO_WALLET_ALLOW_SEND": "0" }
    }
  }
}
```

Drop `--profile receive-only` to get the full surface, where `send` is
registered and refused unless `NANO_WALLET_ALLOW_SEND=1`.

Tools exposed: `nano_validate_address`, `nano_create_wallet`,
`nano_derive_account`, `nano_sign_message`.

There is deliberately **no send tool and no balance tool**. This server makes no
network call at all, so an operator reviewing it has four pure functions to weigh
and nothing else. Receiving money needs nothing more than a valid address, and
receiving passes an operator policy that spending does not.

## Use from the command line

```
$ python3 cli.py check nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3
{ "valid": true, "public_key": "E89208DD...", ... }                        # exit 0

$ python3 cli.py check nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr1
{ "valid": false, "reason": "bad_checksum", ... }                          # exit 1

$ python3 cli.py new                       # a seed and an account, generated locally
$ python3 cli.py derive <seed_hex> 1       # account 1 from a seed you already hold
$ python3 cli.py raw 0.0000005             # exact XNO -> raw, integers only
```

`check` exits 0 for a valid address and 1 for an invalid one, so it drops into a
shell pipeline or a CI gate as-is.

## Use as a library

```python
import wallet

account = wallet.create_wallet()           # seed, private_key, public_key, address
verdict = wallet.validate(their_address)   # never raises; {"valid": bool, "reason": ...}
proof   = wallet.sign_message(b"challenge", account["private_key"])
```

`xno_to_raw` / `raw_to_xno` convert at Nano's full 30-decimal resolution using
integers only — a sub-cent per-call price does not round to zero and does not
drift under summation. No float appears in the money path.

## The receive-only profile

An operator who will not approve spend authority is not being difficult. They
are being asked to trust a claim they cannot check. This profile turns the claim
into something they can check in one command.

**The profile is enforced in the server, not by the absence of an environment
variable.** Under `--profile receive-only`:

* `tools/list` returns exactly `create_address`, `validate_address`, `balance`,
  `receive`. Nothing that can move money out is in it.
* calling `send` is `-32601 method not found` — not a `403`. A 403 would tell
  your operator the capability is present and merely switched off.
* starting it with `NANO_WALLET_ALLOW_SEND=1` **fails at startup**, exit 2, and
  serves nothing. A profile a stray environment variable can widen is not a
  profile.

### The three things to show your operator

```
$ nano-wallet selfcheck --profile receive-only

[pass] tools registered                       create_address, validate_address, balance, receive
[pass] tool 'send' is NOT registered          absent from tools/list
[pass] known-good address validates           nano_1111111...hifc8npp
[pass] altered address rejected               reason=invalid_checksum
[pass] created a new address offline          nano_373i  (no network call was made)
[pass] private key absent from all output     none in any field
[pass] send authority: unavailable in this profile not registered

selfcheck: 7/7 pass - this install can receive XNO and cannot spend it.
```

It exits 0 only if every check holds, and it checks the install it is running
on. Point it at a machine configured for the full profile and it says so:

```
$ NANO_WALLET_PROFILE=full nano-wallet selfcheck --profile receive-only
...
selfcheck: 4/7 pass - this install is NOT receive-only.          # exit 1
```

Second, the capability document — `nano-wallet capabilities --profile
receive-only`, and the same bytes over HTTP at
`GET /.well-known/nano-receive-only` (`nano-wallet wellknown`). Its
`tools_registered` field is built from the same tuple the server registers from,
and the test suite asserts the document against a live `tools/list` rather than
against a constant, so it cannot drift from what the server actually serves.

Third, the sentence to paste. It is fixed in code, not templated per recipient:

> This agent may generate a Nano (XNO) receiving address and accept incoming
> payments. It cannot send, spend, or sign outgoing transfers. No key leaves
> this machine.

### The four steps

```
1. python3 mcp_server.py --profile receive-only      (or the mcp.json above)
2. nano-wallet selfcheck --profile receive-only      read the last line out
3. create_address                                    hand over the address
4. claim a job on the work queue, and get paid
```

Step 4 is what makes 1–3 worth doing. **Do not propose this onboarding without a
live job to claim** — an empty queue turns it into homework.

## Verifying it before you trust it

```
$ python3 -m unittest discover -s tests
Ran 82 tests — OK

$ python3 e2e_check.py
15/15 checks passed

$ python3 e2e_receive_only.py
16/16 receive-only end-to-end checks passed
```

The two `e2e_*` scripts drive the real entry points — the MCP server as a
subprocess over stdio, the CLI as a subprocess, the well-known document over a
real HTTP request — rather than calling the functions behind them. No check
anywhere reaches a Nano node: `fakenode.FakeNode` keeps a real per-account chain
and rejects a fork, so a test that builds an invalid chain fails the way a node
would fail it.

Four of those tests are known-answer vectors against facts this repository
cannot influence:

| vector | pins |
| --- | --- |
| all-zero public key → `nano_1111…hifc8npp` | the address codec |
| mainnet genesis key `E89208DD…` → `nano_3t6k35gi…oncuohr3` | the address codec, independently |
| RFC 8032 Ed25519 vector 1 (SHA-512) | the curve arithmetic and the signature |
| all-zero seed → `9F0E444C…` / `nano_3i1aq1cc…99d4r3b7` | Nano's BLAKE2b variant of that arithmetic |

The curve code takes its hash function as a parameter precisely so the public
RFC 8032 vectors can prove it before the Nano variant is trusted with money.

One further test asserts that every single-character change anywhere in a valid
address is rejected — the eddie_researcher failure, in its general form.

## What this tool does not do

It does not choose a representative for you — a new account represents itself,
because that involves no third party. Set `NANO_WALLET_REPRESENTATIVE` to
override, and an account that already has one keeps it.

It does not run a node. `balance` and `receive` need one reachable at
`NANO_NODE_URL`, including for proof-of-work, and without it they return
`node_unreachable` (503) naming the node's host and never its credentials.

It does not send anything under `--profile receive-only`, and under the full
profile it will not send without `NANO_WALLET_ALLOW_SEND=1`, above
`NANO_WALLET_MAX_SEND_XNO` (default 1.0 XNO per call), or twice for one
`idempotency_key`.