dual-rail 1.3.0__tar.gz
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.
- dual_rail-1.3.0/LICENSE +21 -0
- dual_rail-1.3.0/MANIFEST.in +10 -0
- dual_rail-1.3.0/PKG-INFO +538 -0
- dual_rail-1.3.0/README.md +525 -0
- dual_rail-1.3.0/api/index.py +30 -0
- dual_rail-1.3.0/audits/dual-rail-2026-10-03.md +112 -0
- dual_rail-1.3.0/audits/dual-rail-2026-10-07.md +117 -0
- dual_rail-1.3.0/audits/dual-rail-2026-10-09.md +91 -0
- dual_rail-1.3.0/audits/dual-rail-2026-10-11.md +173 -0
- dual_rail-1.3.0/audits/dual-rail-2026-10-12.md +131 -0
- dual_rail-1.3.0/docs/HOSTED-FACILITATOR.md +47 -0
- dual_rail-1.3.0/docs/refusal_checklist.py +80 -0
- dual_rail-1.3.0/docs/x402-nano-end-to-end.md +325 -0
- dual_rail-1.3.0/docs/x402-nano-seller-guide.md +140 -0
- dual_rail-1.3.0/dual_rail/__init__.py +13 -0
- dual_rail-1.3.0/dual_rail/acceptance_kit.py +201 -0
- dual_rail-1.3.0/dual_rail/accepts_snippet.py +256 -0
- dual_rail-1.3.0/dual_rail/adapter.py +250 -0
- dual_rail-1.3.0/dual_rail/binding.py +107 -0
- dual_rail-1.3.0/dual_rail/challenge.py +158 -0
- dual_rail-1.3.0/dual_rail/cli.py +595 -0
- dual_rail-1.3.0/dual_rail/declaration.py +653 -0
- dual_rail-1.3.0/dual_rail/ed25519_blake2b.py +138 -0
- dual_rail-1.3.0/dual_rail/fakenode.py +54 -0
- dual_rail-1.3.0/dual_rail/hosted_facilitator.py +218 -0
- dual_rail-1.3.0/dual_rail/money.py +87 -0
- dual_rail-1.3.0/dual_rail/nanoaddr.py +159 -0
- dual_rail-1.3.0/dual_rail/nanonode.py +111 -0
- dual_rail-1.3.0/dual_rail/network.py +196 -0
- dual_rail-1.3.0/dual_rail/store.py +54 -0
- dual_rail-1.3.0/dual_rail/testhost.py +54 -0
- dual_rail-1.3.0/dual_rail/usd_quote.py +77 -0
- dual_rail-1.3.0/dual_rail/verifiers.py +124 -0
- dual_rail-1.3.0/dual_rail/verify.py +241 -0
- dual_rail-1.3.0/dual_rail.egg-info/PKG-INFO +538 -0
- dual_rail-1.3.0/dual_rail.egg-info/SOURCES.txt +69 -0
- dual_rail-1.3.0/dual_rail.egg-info/dependency_links.txt +1 -0
- dual_rail-1.3.0/dual_rail.egg-info/entry_points.txt +2 -0
- dual_rail-1.3.0/dual_rail.egg-info/top_level.txt +1 -0
- dual_rail-1.3.0/llms.txt +14 -0
- dual_rail-1.3.0/node/address.js +117 -0
- dual_rail-1.3.0/node/blake2b.js +95 -0
- dual_rail-1.3.0/node/challenge.js +113 -0
- dual_rail-1.3.0/node/conformance.js +124 -0
- dual_rail-1.3.0/node/declaration.js +552 -0
- dual_rail-1.3.0/node/dual-rail.js +391 -0
- dual_rail-1.3.0/node/money.js +69 -0
- dual_rail-1.3.0/node/network.js +122 -0
- dual_rail-1.3.0/node/node-client.js +84 -0
- dual_rail-1.3.0/node/package.json +33 -0
- dual_rail-1.3.0/node/test/declaration.test.js +321 -0
- dual_rail-1.3.0/node/test/dual-rail.test.js +624 -0
- dual_rail-1.3.0/node/testhost.js +91 -0
- dual_rail-1.3.0/proof.json +23 -0
- dual_rail-1.3.0/pyproject.toml +23 -0
- dual_rail-1.3.0/setup.cfg +4 -0
- dual_rail-1.3.0/tests/capture_live_verify.py +99 -0
- dual_rail-1.3.0/tests/cross-check-against-x402-core.txt +69 -0
- dual_rail-1.3.0/tests/cross_check_x402_core.js +204 -0
- dual_rail-1.3.0/tests/test_acceptance_kit.py +118 -0
- dual_rail-1.3.0/tests/test_accepts_snippet.py +218 -0
- dual_rail-1.3.0/tests/test_binding.py +192 -0
- dual_rail-1.3.0/tests/test_conformance.py +403 -0
- dual_rail-1.3.0/tests/test_declaration.py +644 -0
- dual_rail-1.3.0/tests/test_dual_rail.py +1376 -0
- dual_rail-1.3.0/tests/test_end_to_end_doc.py +229 -0
- dual_rail-1.3.0/tests/test_hosted_facilitator.py +110 -0
- dual_rail-1.3.0/tests/test_seller_guide_faq.py +18 -0
- dual_rail-1.3.0/tests/test_verifiers.py +130 -0
- dual_rail-1.3.0/tests/verify-against-a-live-endpoint.txt +125 -0
- dual_rail-1.3.0/vercel.json +1 -0
dual_rail-1.3.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dhyabi2
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
dual_rail-1.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dual-rail
|
|
3
|
+
Version: 1.3.0
|
|
4
|
+
Summary: Add XNO beside USDC/x402, never instead of it: one appended accepts[] entry, and a verifier that proves both rails still work.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/dhyabi2/dual-rail
|
|
7
|
+
Project-URL: Source, https://github.com/dhyabi2/dual-rail
|
|
8
|
+
Keywords: x402,nano,xno,payments,wsgi,middleware,agent
|
|
9
|
+
Requires-Python: >=3.8
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Dynamic: license-file
|
|
13
|
+
|
|
14
|
+
# dual-rail — add XNO **beside** USDC/x402, never instead of it
|
|
15
|
+
|
|
16
|
+
**If our rail fails, yours keeps selling.** Every error on the Nano side — an
|
|
17
|
+
unreachable node, a timeout, a malformed proof, a block we cannot find — falls
|
|
18
|
+
through to your existing rails exactly as if this adapter were not installed.
|
|
19
|
+
There is no code path in it that can turn a Nano problem into a 5xx for a
|
|
20
|
+
customer paying in USDC. That is enforced by a test, not by this paragraph:
|
|
21
|
+
`test_node_outage_falls_through` runs the whole flow with every node call
|
|
22
|
+
raising and asserts no 5xx anywhere.
|
|
23
|
+
|
|
24
|
+
This is not a migration. It appends **one entry** to your `accepts[]` array and
|
|
25
|
+
leaves your existing entries byte-identical, in the same order. A client that
|
|
26
|
+
takes the first acceptable entry keeps its current behaviour exactly. Deleting
|
|
27
|
+
one array element reverts it.
|
|
28
|
+
|
|
29
|
+
No dependencies, in either language. Python 3.8+ and the standard library; Node
|
|
30
|
+
18+ and nothing else.
|
|
31
|
+
|
|
32
|
+
## First five minutes
|
|
33
|
+
|
|
34
|
+
The Canon, five lines, from [the-unowned-rail](https://github.com/dhyabi2/the-unowned-rail) (copy them, pass them on):
|
|
35
|
+
|
|
36
|
+
1. Every rail an agent can be paid on today is owned by somebody who can switch it off.
|
|
37
|
+
2. A balance in someone else's database is a receivable, not revenue.
|
|
38
|
+
3. We are not selling cheap. Nobody ever refused us over fees.
|
|
39
|
+
4. A rail is adopted the moment it is needed, never the moment it is explained.
|
|
40
|
+
5. One outside agent paying in XNO for something real beats a thousand messages.
|
|
41
|
+
|
|
42
|
+
Lines 1, 2, 4 and 5 are positions, not measurements. Line 3 is one: on 2026-11-02 a keyword scan of the
|
|
43
|
+
4,521 conversations in [agent-conversations](https://github.com/dhyabi2/agent-conversations) found no outside
|
|
44
|
+
agent declining because of fees (the objections were compliance and identity, receipts, and the cost of getting in).
|
|
45
|
+
A scan is not proof of absence; if you have been refused over fees, open an issue and it changes the line.
|
|
46
|
+
|
|
47
|
+
**Make a key offline (receives only if you never hand out the seed).** No network call is made; the seed stays in a file only you can read:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
git clone https://github.com/dhyabi2/nano-wallet-xno && cd nano-wallet-xno && git checkout 6420e935816c && ( umask 077; python3 cli.py new > nano-key.json )
|
|
51
|
+
python3 -c "import json;print(json.load(open('nano-key.json'))['address'])" # the only thing you ever share
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Check the address** (checksum, exit 0 if valid): `python3 cli.py check nano_...`
|
|
55
|
+
|
|
56
|
+
**Verify one payment with no code of ours** (any public node; this block is a real 0.0005 XNO send):
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
curl -s -H 'Content-Type: application/json' -d '{"action":"block_info","json_block":"true","hash":"B749B757EE750FC9AEA72F33CB429EACCD2ABEC9F2CCF59BF17AFAC304C9A58F"}' https://rpc.nano.to | python3 -c "import sys,json;d=json.load(sys.stdin);print(d['confirmed'],d['subtype'],d['amount'],d['contents']['link_as_account'])"
|
|
60
|
+
# true send 500000000000000000000000000 nano_1yo6c1t64ahfjdw1dxizmbbnpdmbrckwhw9phbg5pdkeubrizga4qhnjmnx7
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Confirmed, a send, the amount you quoted in raw (1 XNO = 10^30 raw), and the account you expected: that is the whole check.
|
|
64
|
+
|
|
65
|
+
**Pin what you run.** Read the code once, then pin the commit (a commit id is a hash of the code; `git rev-parse HEAD` must print it):
|
|
66
|
+
|
|
67
|
+
| repo | reviewed commit |
|
|
68
|
+
|---|---|
|
|
69
|
+
| nano-wallet-xno | `6420e935816c6984e916305465ff22a3e63498bb` |
|
|
70
|
+
| nano-invoice | `58b8181498de6b67a4e4afbf76d85420889bd85c` |
|
|
71
|
+
| nano-settlement-verify | `f2daf334bb490aed5629c1965957477096b8a953` |
|
|
72
|
+
| dual-rail | `e1d3ec721c57c300f65e47b3e8d5e62802269fb9` |
|
|
73
|
+
|
|
74
|
+
Those four are the state this block was written against (2026-11-02); `git checkout <id>` always gives you exactly that code, whatever happens to the repo later.
|
|
75
|
+
An operator who will not let the agent hold a key: see [OPERATORS.md](https://github.com/dhyabi2/the-unowned-rail/blob/main/OPERATORS.md).
|
|
76
|
+
|
|
77
|
+
## Quickstart (two minutes, no Nano node, no network)
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
git clone https://github.com/dhyabi2/dual-rail && cd dual-rail
|
|
81
|
+
python3 -m unittest discover -s tests # 215 tests, includes the Python/Node conformance run
|
|
82
|
+
(cd node && npm test) # 81 tests
|
|
83
|
+
python3 tests/capture_live_verify.py # real HTTP server on 127.0.0.1, adapter mounted, 7/7 verify
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Then point it at your own 402 (read-only, changes nothing):
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
python3 -m dual_rail.cli inspect https://your-service.example/.well-known/x402
|
|
90
|
+
python3 -m dual_rail.cli add --manifest https://your-service.example/.well-known/x402 \
|
|
91
|
+
--pay-to nano_YOUR_ADDRESS --amount 0.0001 --diff
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Install the Python package from PyPI:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
pip install dual-rail==1.3.0
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
That gives you the `dual-rail` command (the same CLI as `python3 -m dual_rail.cli`) and the
|
|
101
|
+
`dual_rail` package (`from dual_rail import dual_rail`). Since 1.3.0 every module lives inside
|
|
102
|
+
`dual_rail/`: code that did `import verify` or `from adapter import dual_rail` against 1.2.0 now
|
|
103
|
+
writes `from dual_rail import verify` / `from dual_rail import dual_rail`. The root scripts are
|
|
104
|
+
gone too: `python3 cli.py`, `python3 acceptance_kit.py`, `python3 accepts_snippet.py` and
|
|
105
|
+
`python3 usd_quote.py` become `python3 -m dual_rail.cli` (or `dual-rail`), `python3 -m dual_rail.acceptance_kit`,
|
|
106
|
+
and so on; run them with `-m` from the checkout root, not by file path. The Node middleware is
|
|
107
|
+
not on npm yet: `require('./node/dual-rail')` from a checkout.
|
|
108
|
+
|
|
109
|
+
The `nano_3t6k35gi…` address in the examples is the public Nano **genesis**
|
|
110
|
+
account, used only because it is a valid, well-known address. Put your own
|
|
111
|
+
account there.
|
|
112
|
+
|
|
113
|
+
## What changes in your 402
|
|
114
|
+
|
|
115
|
+
```diff
|
|
116
|
+
{
|
|
117
|
+
"x402Version": 2,
|
|
118
|
+
"accepts": [
|
|
119
|
+
{ "scheme": "exact", "network": "base", "asset": "USDC", ... },
|
|
120
|
+
{ "scheme": "exact", "network": "solana", "asset": "USDC", ... },
|
|
121
|
+
+ { "scheme": "exact", "network": "nano:mainnet", "asset": "XNO",
|
|
122
|
+
+ "maxAmountRequired": "100000000000000000000000000",
|
|
123
|
+
+ "maxAmountRequiredFormatted": "0.0001 XNO", "payTo": "nano_3t6k…",
|
|
124
|
+
+ "description": "Feeless native-coin settlement. Optional — the entries above are unchanged.",
|
|
125
|
+
+ "extra": { "decimals": 30, "adapter": "dual-rail/1" } }
|
|
126
|
+
]
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Same status code, same headers, same ordering, same `x-402-version`. One
|
|
131
|
+
additional element at the end of `accepts[]`, and nothing else.
|
|
132
|
+
|
|
133
|
+
New to selling over x402 in XNO? Start with the one-page [`docs/x402-nano-seller-guide.md`](https://github.com/dhyabi2/dual-rail/blob/main/docs/x402-nano-seller-guide.md): the entry, the check, the traps, and a runnable 15-case refusal list (`python3 docs/refusal_checklist.py`, offline).
|
|
134
|
+
|
|
135
|
+
One real `nano:mainnet` entry followed from the 402 to a confirmed block on the ledger, verified with no facilitator, is in [`docs/x402-nano-end-to-end.md`](https://github.com/dhyabi2/dual-rail/blob/main/docs/x402-nano-end-to-end.md).
|
|
136
|
+
|
|
137
|
+
`maxAmountRequired` is in **raw**, the asset's atomic unit, which is what
|
|
138
|
+
`extra.decimals: 30` declares it to be — 10\*\*30 raw to the XNO, so the
|
|
139
|
+
figure above is 0.0001 XNO. That is how every x402 client reads the field
|
|
140
|
+
(feeless402's `offer_amount_raw` is `int(offer["maxAmountRequired"])`), and it
|
|
141
|
+
is the same convention the USDC entries above use: their `"10000"` is 0.01 USDC
|
|
142
|
+
at 6 decimals, not ten thousand dollars. `maxAmountRequiredFormatted` carries
|
|
143
|
+
the decimal figure for a human. You still configure the price in XNO
|
|
144
|
+
(`amountXno: "0.0001"`); only the wire format is raw.
|
|
145
|
+
|
|
146
|
+
## Bind each payment to its request, and keep spent blocks across restarts (opt-in, Python)
|
|
147
|
+
|
|
148
|
+
Two reviewers' objections to Nano-on-x402 code, answered in two constructor options. Both are off
|
|
149
|
+
by default, so an existing install changes by nothing.
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
rail = dual_rail(payTo="nano_YOUR_ADDRESS", amountXno="0.0001",
|
|
153
|
+
nodeUrl="https://rpc.nano.to",
|
|
154
|
+
bindingSecret=os.environ["DUAL_RAIL_SECRET"], # >= 16 random bytes, yours alone
|
|
155
|
+
replayDb="/var/lib/myapp/nano-spent.db") # survives restarts, shared by workers
|
|
156
|
+
application = rail.wsgi(protected_app, gate=x402_middleware)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
* **Payment-to-request binding (`nano-block-sig/1`).** A confirmed send block is public, so a proof that is
|
|
160
|
+
only its hash can be presented by anyone who saw it. With `bindingSecret` the 402's Nano entry carries
|
|
161
|
+
`extra.binding = {scheme, nonce, resource}` and the payer must add `payload.binding = {nonce, signature}`:
|
|
162
|
+
an Ed25519-BLAKE2b signature, made with the key of the account that PAID, over
|
|
163
|
+
`"nano-402-binding/1\n" + block_hash + "\n" + nonce + "\n" + resource + "\n" + payTo`. The seller holds no
|
|
164
|
+
state for the nonce (`<expiry_hex>.<HMAC(secret, resource|expiry|payTo)>`, ten minutes). A watcher with only
|
|
165
|
+
the block hash cannot sign; a signature for `/report` is worthless on `/other`; a nonce from another seller or
|
|
166
|
+
for another payee is refused. A bad or missing binding is "unpaid": the request falls through to your other
|
|
167
|
+
rails exactly like any other failed proof. The buyer side is `nano-pay402` in
|
|
168
|
+
[nano-wallet-xno](https://github.com/dhyabi2/nano-wallet-xno), which signs the identical message
|
|
169
|
+
(`tests/test_binding.py` and its tests pin one shared signature vector).
|
|
170
|
+
* **Persistent, atomic replay store.** `replayDb` is a SQLite file (mode 0600, WAL). A block is spent once,
|
|
171
|
+
for whichever resource claims it first, with one atomic `INSERT OR IGNORE`: 32 racing threads over four
|
|
172
|
+
connections give exactly one winner (`test_concurrent_claims_have_exactly_one_winner`), and a restarted
|
|
173
|
+
process still refuses a block it served before. Pass `guard=` to supply your own (`seen`, `claim`).
|
|
174
|
+
|
|
175
|
+
Not done: the Node binding has no equivalent yet, and the binding does not cover the request body.
|
|
176
|
+
|
|
177
|
+
## Acceptance kit and the paste-in accepts[] generator
|
|
178
|
+
|
|
179
|
+
Two commands a seller can run. Both read only: no key, no payment, nothing is installed.
|
|
180
|
+
|
|
181
|
+
**`python3 -m dual_rail.acceptance_kit`** runs five cases a Nano-paid seller should pass, and exits 0 only if all five ran and passed
|
|
182
|
+
(5 means a case was skipped, 1 means one failed). The last three need a [nano-invoice](https://github.com/dhyabi2/nano-invoice)
|
|
183
|
+
checkout: `git clone --branch v0.2.1 https://github.com/dhyabi2/nano-invoice` and `--nano-invoice PATH`. `refusal-probe` needs a dual-rail checkout (its script is in `docs/`, which pip does not install): from a pip install it is reported skipped, so the kit exits 5 there, never 0.
|
|
184
|
+
|
|
185
|
+
| case | what passing it proves |
|
|
186
|
+
|---|---|
|
|
187
|
+
| `refusal-probe` | a check built to say no does say no: 15 offline payments (1 honest, 14 that must be refused for the stated reason) |
|
|
188
|
+
| `accepts-shape` | the Nano `accepts[]` entry has every field x402 v1 and v2 require, raw as an integer string, a checksummed `payTo`; `--manifest URL` runs it on yours |
|
|
189
|
+
| `duplicate-retry` | one payment presented twice is served once, in memory and after a restart; a second exact transfer is `duplicate` and refunded to its sender |
|
|
190
|
+
| `attribution-tests` | exact amount pays and records the chain's sender; off by one raw pays nothing; short is underpaid; after expiry is late |
|
|
191
|
+
| `buyer-recovery` | the invoice id re-derives from merchant and order key, the same order key returns the same invoice, a duplicate is refunded |
|
|
192
|
+
|
|
193
|
+
**`python3 -m dual_rail.accepts_snippet --manifest URL --pay-to nano_... [--usd 0.01 | --amount 0.0001] [--framework python|node]`**
|
|
194
|
+
reads your own x402 manifest and prints the exact modified manifest (your entries untouched, one Nano entry appended), its
|
|
195
|
+
diff, the server change, and a test that fails if an existing entry changed. With `--usd` the price stays in dollars:
|
|
196
|
+
converted to raw at read time from two independent feeds (refused if they differ by more than 2 percent, rounded up), valid
|
|
197
|
+
60 seconds, refunds return the same raw. See [`docs/USD-PEGGED-QUOTE.md`](https://github.com/dhyabi2/xno-call-binding/blob/main/docs/USD-PEGGED-QUOTE.md).
|
|
198
|
+
|
|
199
|
+
## The verifier is the product
|
|
200
|
+
|
|
201
|
+
The middleware is the implementation detail. This is the artefact that goes in a
|
|
202
|
+
message:
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
$ dual-rail verify https://example.dev/report --payment 9F2C0000…
|
|
206
|
+
|
|
207
|
+
[pass] 402 challenge reachable HTTP 402, x-402-version: 2
|
|
208
|
+
[pass] pre-existing rails intact 2 entries: USDC/base, USDC/solana (unchanged)
|
|
209
|
+
[pass] nano entry present and last nano:mainnet XNO 0.0001 -> nano_3t6k35g…
|
|
210
|
+
[pass] nano payTo passes checksum valid
|
|
211
|
+
[pass] existing rail still settles 2 pre-existing challenges well-formed
|
|
212
|
+
[pass] nano rail settles block 9F2C0000… -> HTTP 200
|
|
213
|
+
[pass] node outage falls through unverifiable proof -> HTTP 402 with all 3 entries, no 5xx
|
|
214
|
+
|
|
215
|
+
verify: 7/7 pass - both rails live, existing rails unchanged.
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Exit 0 only if all seven hold. A captured run against a live endpoint is in
|
|
219
|
+
[`tests/verify-against-a-live-endpoint.txt`](https://github.com/dhyabi2/dual-rail/blob/main/tests/verify-against-a-live-endpoint.txt),
|
|
220
|
+
whose header says precisely what that run does and does not prove.
|
|
221
|
+
|
|
222
|
+
`--payment` is spent by the run: one payment buys one call, so verifying twice
|
|
223
|
+
needs two payments. That is the replay protection working.
|
|
224
|
+
|
|
225
|
+
## Install
|
|
226
|
+
|
|
227
|
+
### Node / Express
|
|
228
|
+
|
|
229
|
+
```js
|
|
230
|
+
const { dualRail } = require('./node/dual-rail'); // from a checkout
|
|
231
|
+
|
|
232
|
+
app.use(dualRail({
|
|
233
|
+
payTo: 'nano_3t6k35gi95xu6tergt6p69ck76ogmitsa8mnijtpxm9fkcm736xtoncuohr3',
|
|
234
|
+
amountXno: '0.0001', // a decimal STRING, never a number
|
|
235
|
+
nodeUrl: process.env.NANO_NODE_URL,
|
|
236
|
+
gate: x402Middleware, // your paywall - see "Mounting" below
|
|
237
|
+
}));
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Python / WSGI (Flask, FastAPI via WSGI, anything)
|
|
241
|
+
|
|
242
|
+
```python
|
|
243
|
+
from dual_rail import dual_rail
|
|
244
|
+
|
|
245
|
+
rail = dual_rail(payTo="nano_3t6k35gi…", amountXno="0.0001",
|
|
246
|
+
nodeUrl=os.environ["NANO_NODE_URL"])
|
|
247
|
+
application = rail.wsgi(protected_app, gate=x402_middleware)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Construction **throws** if `payTo` fails its checksum. A service must not be
|
|
251
|
+
able to boot advertising an address nobody can pay. It also throws if
|
|
252
|
+
`amountXno` is outside 0.000001–100 XNO, if it is a float rather than a string,
|
|
253
|
+
or if `onVerifyError` is anything but `"fallthrough"` — failing closed on our
|
|
254
|
+
rail would let our outage cost you a sale on yours, so the option exists only to
|
|
255
|
+
be read, never to be changed.
|
|
256
|
+
|
|
257
|
+
### Mounting, and why `gate` exists
|
|
258
|
+
|
|
259
|
+
Without `gate` the adapter does the additive half: a 402 written by anything
|
|
260
|
+
downstream gets one entry appended on its way out. That needs no cooperation
|
|
261
|
+
from your stack at all.
|
|
262
|
+
|
|
263
|
+
Admitting a Nano-paid request is the other half, and it means bypassing your
|
|
264
|
+
paywall — so the adapter has to be shown which middleware that is. `gate` is it.
|
|
265
|
+
The adapter never modifies, wraps or reorders anything else, and a request
|
|
266
|
+
without a valid Nano payment goes through your gate untouched.
|
|
267
|
+
|
|
268
|
+
## CLI
|
|
269
|
+
|
|
270
|
+
There is one CLI, and it is the Python one — `dual_rail/cli.py` (run it as `dual-rail` or `python3 -m dual_rail.cli`, not by file path). The Node package ships
|
|
271
|
+
the middleware only; duplicating the verifier in two languages would give two
|
|
272
|
+
things to keep in step and no more assurance, and the verifier talks HTTP to
|
|
273
|
+
your endpoint rather than into either runtime.
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
dual-rail inspect <manifest-url|file> # read-only; prints the current rails
|
|
277
|
+
dual-rail check <manifest-url|file> [--json] # read-only; would a client PAY the Nano entry?
|
|
278
|
+
# reads a 402 challenge or a resources[] catalogue
|
|
279
|
+
dual-rail add --manifest <url|file> --pay-to nano_… --amount 0.0001 [--out p.json|--diff]
|
|
280
|
+
dual-rail verify <base-url> [--payment <block hash>] [--json]
|
|
281
|
+
dual-rail verifiers [--node <url>] [--json] # who can validate an XNO payment today, checked live
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
`add` exits **3** rather than emit a patch that removes or modifies a line it
|
|
285
|
+
did not author — including on a YAML manifest, which cannot be re-rendered
|
|
286
|
+
without rewriting lines, and where it tells you to use `--out` instead. Run on
|
|
287
|
+
an already-patched manifest it exits 0 with `already_present` and emits nothing.
|
|
288
|
+
|
|
289
|
+
## Who can validate an XNO payment today?
|
|
290
|
+
|
|
291
|
+
```
|
|
292
|
+
python3 -m dual_rail.cli verifiers [--json]
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Checked live each run, never from a list: (1) a `block_info` read against a
|
|
296
|
+
public Nano node (`https://rpc.nano.to` unless `--node`) - this is
|
|
297
|
+
self-verification with no facilitator and no custodian, because the payer
|
|
298
|
+
broadcasts its own signed send block and any node shows it to anyone; it is the
|
|
299
|
+
read `dual_rail/verify.py` makes; (2) [gosuda/x402-facilitator](https://github.com/gosuda/x402-facilitator),
|
|
300
|
+
whose main-branch README must still have a `### Nano` section naming
|
|
301
|
+
`nano:mainnet` with `exact` ticked. It is reported `custodial: false` only while
|
|
302
|
+
that section says the payer broadcasts its own block and the facilitator is
|
|
303
|
+
read-only on the chain; otherwise `unknown`. A check that cannot be reached is
|
|
304
|
+
reported unreachable, not passed. Exit 0 if at least one is confirmed, 1 if none.
|
|
305
|
+
|
|
306
|
+
## Would a client actually pay your Nano entry?
|
|
307
|
+
|
|
308
|
+
`inspect` reads the price under whichever name your document uses — x402
|
|
309
|
+
renamed it from `maxAmountRequired` (v1) to `amount` (v2), and it reports which
|
|
310
|
+
one it found in `amount_field`. It also reads a **multi-resource** manifest,
|
|
311
|
+
where `accepts[]` sits under each `resources[]` item rather than at the top
|
|
312
|
+
level, and reports each resource separately. `add` deliberately refuses that
|
|
313
|
+
shape: which of your resources gets the payout address is your call, not this
|
|
314
|
+
tool's, so point it at the one resource's own 402.
|
|
315
|
+
|
|
316
|
+
`inspect` says what is in your `accepts[]` array. `check` says whether anything
|
|
317
|
+
would act on it — and it is a different question, because an x402 client that
|
|
318
|
+
cannot parse your Nano entry does not reject it with a reason. The entry fails a
|
|
319
|
+
schema check inside the client library and is **dropped before any payment is
|
|
320
|
+
attempted**. From your side that is indistinguishable from nobody wanting to pay
|
|
321
|
+
in XNO.
|
|
322
|
+
|
|
323
|
+
```
|
|
324
|
+
$ python3 -m dual_rail.cli check https://your-service.example/.well-known/x402
|
|
325
|
+
|
|
326
|
+
accepts[1] network "nano-mainnet"
|
|
327
|
+
x402 v2: 3 problem(s)
|
|
328
|
+
[network_not_caip2] "nano-mainnet" is accepted by x402 v1 but refused by v2,
|
|
329
|
+
whose NetworkSchemaV2 requires a colon (@x402/core 2.28.0). Emit "nano:mainnet"
|
|
330
|
+
[amount_field_is_other_version_name] this entry carries maxAmountRequired,
|
|
331
|
+
x402 v1's name for the price…
|
|
332
|
+
[pay_to_invalid] payTo is not a payable Nano account (bad_checksum)…
|
|
333
|
+
|
|
334
|
+
check: NOT payable as it stands
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
It exits **1** when nothing in the document is payable, so it can gate a deploy.
|
|
338
|
+
|
|
339
|
+
The rules come in two halves, and the split is the point. `shape_problems` is
|
|
340
|
+
**only** what the x402 schema itself rejects, read off `@x402/core` 2.28.0's own
|
|
341
|
+
`PaymentRequirementsV1Schema` and `PaymentRequirementsV2Schema` — the renamed
|
|
342
|
+
amount field, the CAIP-2 network rule that v2 added and v1 did not have,
|
|
343
|
+
`maxTimeoutSeconds` being a `number` so that `"60"` is refused, `extra` having
|
|
344
|
+
to be an object or null. That half is checked for **equivalence** against the
|
|
345
|
+
real installed package by `tests/cross_check_x402_core.js`, over 120,000
|
|
346
|
+
nearly-valid documents of which the library accepts about 42%; the captured run
|
|
347
|
+
is in `tests/cross-check-against-x402-core.txt`. It is not part of the suite
|
|
348
|
+
because this package has no dependencies and is not acquiring one.
|
|
349
|
+
|
|
350
|
+
`nano_problems` is what no generic x402 conformance tool can check, because it
|
|
351
|
+
needs the chain:
|
|
352
|
+
|
|
353
|
+
- a `payTo` that is well-formed and **fails its checksum**. x402 asks only for a
|
|
354
|
+
non-empty string, so the client accepts it and the money sent there is
|
|
355
|
+
unspendable.
|
|
356
|
+
- an amount that is not a whole number of raw. `@x402nano/typescript-common`
|
|
357
|
+
declares an integer amount `/^\d+$/`, so `"0.0001"` is not a payable v2
|
|
358
|
+
amount however right it looks.
|
|
359
|
+
- an amount above 2\*\*128-1 raw, which no Nano block's balance field can hold.
|
|
360
|
+
- a network identifier that means Nano but is not the canonical spelling.
|
|
361
|
+
|
|
362
|
+
And because a client parses the whole 402 or none of it, `check` reports a
|
|
363
|
+
**sibling** entry that sinks the document your entry is in — a USDC entry
|
|
364
|
+
carrying `"network": "base"` in a document that says `x402Version: 2` fails
|
|
365
|
+
`NetworkSchemaV2`, and the array your Nano entry sits in is thrown out with it.
|
|
366
|
+
|
|
367
|
+
### Two document shapes, and the one that used to read as empty
|
|
368
|
+
|
|
369
|
+
A **402 challenge** has a top-level `accepts[]`. A **resource catalogue** —
|
|
370
|
+
what a seller serves at `/.well-known/x402` — has `resources[]`, each item
|
|
371
|
+
carrying its own `url` and its own `accepts[]`. `check` read only the first
|
|
372
|
+
shape and reported a catalogue as `accepts must be an array of entries; got
|
|
373
|
+
null`: **0 entries, 0 naming Nano, not payable**, exit 1, about a document
|
|
374
|
+
carrying payable Nano entries. From the seller's side that is the same thing as
|
|
375
|
+
nobody wanting to pay in XNO, which is the confusion this whole command exists
|
|
376
|
+
to end. It now reads both, one resource at a time — flattening them would
|
|
377
|
+
invent an `accepts[]` no client ever sees and make an entry's index meaningless:
|
|
378
|
+
|
|
379
|
+
```
|
|
380
|
+
$ python3 -m dual_rail.cli check https://extract.paypercall.dev/.well-known/x402
|
|
381
|
+
|
|
382
|
+
x402 version declared: 2
|
|
383
|
+
document: resource catalogue, 24 resource(s)
|
|
384
|
+
accepts[] entries: 24 across all resources
|
|
385
|
+
resources naming Nano: 24, of which not payable: 0
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
`payable` for a catalogue is **every** Nano resource, not any: a catalogue of 24
|
|
389
|
+
endpoints with one unpayable entry is a seller problem, and an `any` would
|
|
390
|
+
report it healthy on the strength of the other 23. `resources_not_payable` says
|
|
391
|
+
how many, and each is printed under its own url.
|
|
392
|
+
|
|
393
|
+
A catalogue entry is an **advertisement**, not a challenge, and the three
|
|
394
|
+
fields the x402 schema requires that only a live 402 can supply —
|
|
395
|
+
`maxTimeoutSeconds`, and v1's `resource` and `description` — are reported as a
|
|
396
|
+
note rather than counted against it. Measured: the manifest above omits all
|
|
397
|
+
three on all 24 entries, while a real 402 from the same resource carries
|
|
398
|
+
`maxTimeoutSeconds: 60` and a top-level `resource` object. Reporting them as
|
|
399
|
+
problems would be the same false alarm `verify` used to raise about a working
|
|
400
|
+
USDC rail. The relaxation covers a **missing** field only — a
|
|
401
|
+
`maxTimeoutSeconds` of `"60"` is still refused — and nothing a later 402
|
|
402
|
+
cannot repair is relaxed at all: a bad checksum, a decimal amount, an amount
|
|
403
|
+
over the 128-bit ceiling, a wrong asset, scheme or network still sink the
|
|
404
|
+
entry.
|
|
405
|
+
|
|
406
|
+
`shape_problems` itself is untouched by this, which is why the equivalence run
|
|
407
|
+
above still reads 0 disagreements over 120,000 documents: the catalogue
|
|
408
|
+
relaxation sits one layer up, in `split_challenge_only`. A catalogue is not a
|
|
409
|
+
document `@x402/core` models — `PaymentRequiredSchema` rejects it for want of
|
|
410
|
+
`resource` and `accepts` — so the equivalence claim is about the **entries**,
|
|
411
|
+
which are `PaymentRequirements` in either shape, and not about the catalogue
|
|
412
|
+
around them.
|
|
413
|
+
|
|
414
|
+
## Network identifiers: there is more than one
|
|
415
|
+
|
|
416
|
+
`nano:mainnet` is the canonical spelling and the only one x402 v2 accepts.
|
|
417
|
+
`nano-mainnet` is also in the wild: legal under v1, whose `NetworkSchemaV1` is
|
|
418
|
+
any non-empty string, and refused by v2. `dual_rail/network.py` / `node/network.js` read
|
|
419
|
+
both as mainnet, emit the canonical one, and tell you which you were given.
|
|
420
|
+
|
|
421
|
+
A bare `nano` or `xno` is **refused**, not assumed: it names the family without
|
|
422
|
+
naming the network, and Nano's test networks use the same `nano_` address
|
|
423
|
+
prefix, so reading it as mainnet would be a guess about where money goes. It
|
|
424
|
+
comes back as `network_unspecified`, and `nano:testnet` comes back as
|
|
425
|
+
`not_mainnet` — a different answer from "this is not Nano", because the two want
|
|
426
|
+
different fixes.
|
|
427
|
+
|
|
428
|
+
This matters to the adapter and not only to the validator. `find_nano` used to
|
|
429
|
+
compare against the literal `nano:mainnet`, so a seller who **already** accepted
|
|
430
|
+
XNO and spelled it `nano-mainnet` looked like a seller with no Nano entry, and
|
|
431
|
+
`add` appended a second one. The array then carried two Nano prices and two
|
|
432
|
+
payout addresses, and which one got paid depended on the payer's protocol
|
|
433
|
+
version: a v1 client takes the first entry it can pay, a v2 client refuses
|
|
434
|
+
`nano-mainnet` outright and takes the other. `add` is now a no-op there, and
|
|
435
|
+
`check` reports such an array as `duplicate_nano_entries` if one reaches it.
|
|
436
|
+
|
|
437
|
+
## Money
|
|
438
|
+
|
|
439
|
+
Integer raw end to end (1 XNO = 10\*\*30 raw): `BigInt` in Node, `int` in Python.
|
|
440
|
+
A float amount is **refused**, not rounded — a double holds 53 bits of mantissa
|
|
441
|
+
against the ~100 a raw balance needs, so one float round trip loses real money
|
|
442
|
+
in the low-order digits. Underpayment by a single raw is underpayment.
|
|
443
|
+
|
|
444
|
+
## Verifying it before you mount it
|
|
445
|
+
|
|
446
|
+
```
|
|
447
|
+
$ python3 -m unittest discover -s tests
|
|
448
|
+
Ran 215 tests — OK
|
|
449
|
+
|
|
450
|
+
$ cd node && npm test
|
|
451
|
+
# pass 81
|
|
452
|
+
|
|
453
|
+
$ python3 -m unittest tests.test_conformance
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
The last one is the interesting one. The two bindings have to behave
|
|
457
|
+
**identically**, and a promise that they do is worth nothing without something
|
|
458
|
+
that runs them side by side: `tests/test_conformance.py` drives one shared
|
|
459
|
+
matrix — addresses, amounts, price bands, challenge shapes, network
|
|
460
|
+
identifiers, whole 402 declarations, payment proofs, settlement verdicts —
|
|
461
|
+
through both and asserts deep equality, case by case, **messages included**. It
|
|
462
|
+
fails rather than skips if `node` is missing, because an unrun conformance suite
|
|
463
|
+
is exactly the state in which two implementations drift apart.
|
|
464
|
+
|
|
465
|
+
Node has no variable-length BLAKE2b (`crypto` offers `blake2b512` only) and
|
|
466
|
+
Nano's address checksum needs a 5-byte one, which is **not** a truncation of the
|
|
467
|
+
64-byte digest. `node/blake2b.js` implements RFC 7693 properly, and its digests
|
|
468
|
+
are checked against Python's `hashlib.blake2b` on ten vectors including
|
|
469
|
+
multi-block input.
|
|
470
|
+
|
|
471
|
+
No test in this repository reaches a Nano node or any host but 127.0.0.1.
|
|
472
|
+
|
|
473
|
+
## What it does not do
|
|
474
|
+
|
|
475
|
+
It does not run a node, hold a key, or sign anything — it only reads whether a
|
|
476
|
+
block you were paid is a confirmed **send to your account**. It does not choose
|
|
477
|
+
your price. It does not
|
|
478
|
+
touch your existing rails, and it is built so that it cannot: `assert_additive`
|
|
479
|
+
compares the array before and after and raises unless the prefix is deeply equal
|
|
480
|
+
and exactly one element was added.
|
|
481
|
+
|
|
482
|
+
The replay guard is per-process and in-memory. A service running several workers
|
|
483
|
+
needs a shared store behind `ReplayGuard.seen`/`remember` — two methods, said
|
|
484
|
+
here rather than discovered in production.
|
|
485
|
+
|
|
486
|
+
The guard keys each purchase on the request **path**, canonicalised the same way
|
|
487
|
+
in both bindings (`verify.resource_key` / `resourceKey`): query and any
|
|
488
|
+
`scheme://host` prefix dropped, percent-escapes decoded, repeated slashes
|
|
489
|
+
collapsed, trailing slash dropped, ASCII lowercased. So `/report/`, `/REPORT`,
|
|
490
|
+
`//report`, `/%72eport` and `GET http://any.host/report` are one purchase, and
|
|
491
|
+
`/report` and `/reports` are two. A route whose handler really is
|
|
492
|
+
case-sensitive shares one key with its other-case spellings: that refuses a
|
|
493
|
+
second call, it never admits one.
|
|
494
|
+
|
|
495
|
+
**Upgrading with a persisted store.** Earlier versions keyed on
|
|
496
|
+
`scheme://host/path` (and, briefly on 2026-10-11, on the raw path alone). If
|
|
497
|
+
your `seen`/`remember` are backed by a store that outlives the process, rewrite
|
|
498
|
+
every stored key through `verify.migrate_legacy_key(key)` (Python) or
|
|
499
|
+
`migrateLegacyKey(key)` (Node) before the new version takes traffic. Without
|
|
500
|
+
that, every block spent before the upgrade can be spent once more. The
|
|
501
|
+
in-memory default starts empty and needs nothing.
|
|
502
|
+
|
|
503
|
+
A Python app mounted under a prefix passes it: `verify.migrate_legacy_key(key,
|
|
504
|
+
"/api")`, because the Python key now includes SCRIPT_NAME and the old one did
|
|
505
|
+
not (the Node key always carried the mount through `originalUrl`). Run the
|
|
506
|
+
migration once: with a mount prefix it is not idempotent (a second pass turns
|
|
507
|
+
`/api/report` into `/api/api/report`). One kind of old key cannot be migrated:
|
|
508
|
+
one whose host part the payer shaped with an odd `Host:` header
|
|
509
|
+
(`http://a/b/report` becomes `/b/report`), so that block can be spent once more
|
|
510
|
+
on the real path. It takes planning before the upgrade and buys one call.
|
|
511
|
+
|
|
512
|
+
## Who made this, and its honest limits
|
|
513
|
+
|
|
514
|
+
Written and maintained by **dhyabi2**, as part of an effort to make Nano (XNO)
|
|
515
|
+
a practical payment rail for AI agents. It is ours; it is not an official Nano
|
|
516
|
+
Foundation or x402 Foundation project.
|
|
517
|
+
|
|
518
|
+
- **No third-party deployment yet.** The captured verify run is against our own
|
|
519
|
+
test host on 127.0.0.1 with a fake node (its header says so). Nobody outside
|
|
520
|
+
has mounted this in production yet.
|
|
521
|
+
- **`nano:mainnet` is not a network name the x402 specification defines.** A
|
|
522
|
+
client that does not know it simply skips the entry - which is exactly why it
|
|
523
|
+
is appended last and never replaces your rails.
|
|
524
|
+
- **Replay protection is in-memory and per-process** (see above).
|
|
525
|
+
- **Your node is your trust anchor.** A payment counts when the node you
|
|
526
|
+
configure says the block is confirmed; the adapter does not cross-check a
|
|
527
|
+
second node.
|
|
528
|
+
- **A proof must be a send to your account, and only that.** Until
|
|
529
|
+
2026-10-04 a confirmed block of any other kind whose `block_account` was your
|
|
530
|
+
payout address verified — which a *receive* on your own account is. Every
|
|
531
|
+
receive hash is public in your account history, so a stranger could read your
|
|
532
|
+
ledger and be served without paying. The payee is now read from the block's own
|
|
533
|
+
send destination, anything that is not a send is refused as `not_a_send`, and
|
|
534
|
+
the two accounts are compared by public key rather than by the `nano_`/`xrb_`
|
|
535
|
+
spelling a node happens to serve.
|
|
536
|
+
- Python package 1.3.0, on PyPI; the Node middleware (1.0.0) is not on npm yet.
|
|
537
|
+
|
|
538
|
+
MIT licensed - see `LICENSE`.
|