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.
Files changed (71) hide show
  1. dual_rail-1.3.0/LICENSE +21 -0
  2. dual_rail-1.3.0/MANIFEST.in +10 -0
  3. dual_rail-1.3.0/PKG-INFO +538 -0
  4. dual_rail-1.3.0/README.md +525 -0
  5. dual_rail-1.3.0/api/index.py +30 -0
  6. dual_rail-1.3.0/audits/dual-rail-2026-10-03.md +112 -0
  7. dual_rail-1.3.0/audits/dual-rail-2026-10-07.md +117 -0
  8. dual_rail-1.3.0/audits/dual-rail-2026-10-09.md +91 -0
  9. dual_rail-1.3.0/audits/dual-rail-2026-10-11.md +173 -0
  10. dual_rail-1.3.0/audits/dual-rail-2026-10-12.md +131 -0
  11. dual_rail-1.3.0/docs/HOSTED-FACILITATOR.md +47 -0
  12. dual_rail-1.3.0/docs/refusal_checklist.py +80 -0
  13. dual_rail-1.3.0/docs/x402-nano-end-to-end.md +325 -0
  14. dual_rail-1.3.0/docs/x402-nano-seller-guide.md +140 -0
  15. dual_rail-1.3.0/dual_rail/__init__.py +13 -0
  16. dual_rail-1.3.0/dual_rail/acceptance_kit.py +201 -0
  17. dual_rail-1.3.0/dual_rail/accepts_snippet.py +256 -0
  18. dual_rail-1.3.0/dual_rail/adapter.py +250 -0
  19. dual_rail-1.3.0/dual_rail/binding.py +107 -0
  20. dual_rail-1.3.0/dual_rail/challenge.py +158 -0
  21. dual_rail-1.3.0/dual_rail/cli.py +595 -0
  22. dual_rail-1.3.0/dual_rail/declaration.py +653 -0
  23. dual_rail-1.3.0/dual_rail/ed25519_blake2b.py +138 -0
  24. dual_rail-1.3.0/dual_rail/fakenode.py +54 -0
  25. dual_rail-1.3.0/dual_rail/hosted_facilitator.py +218 -0
  26. dual_rail-1.3.0/dual_rail/money.py +87 -0
  27. dual_rail-1.3.0/dual_rail/nanoaddr.py +159 -0
  28. dual_rail-1.3.0/dual_rail/nanonode.py +111 -0
  29. dual_rail-1.3.0/dual_rail/network.py +196 -0
  30. dual_rail-1.3.0/dual_rail/store.py +54 -0
  31. dual_rail-1.3.0/dual_rail/testhost.py +54 -0
  32. dual_rail-1.3.0/dual_rail/usd_quote.py +77 -0
  33. dual_rail-1.3.0/dual_rail/verifiers.py +124 -0
  34. dual_rail-1.3.0/dual_rail/verify.py +241 -0
  35. dual_rail-1.3.0/dual_rail.egg-info/PKG-INFO +538 -0
  36. dual_rail-1.3.0/dual_rail.egg-info/SOURCES.txt +69 -0
  37. dual_rail-1.3.0/dual_rail.egg-info/dependency_links.txt +1 -0
  38. dual_rail-1.3.0/dual_rail.egg-info/entry_points.txt +2 -0
  39. dual_rail-1.3.0/dual_rail.egg-info/top_level.txt +1 -0
  40. dual_rail-1.3.0/llms.txt +14 -0
  41. dual_rail-1.3.0/node/address.js +117 -0
  42. dual_rail-1.3.0/node/blake2b.js +95 -0
  43. dual_rail-1.3.0/node/challenge.js +113 -0
  44. dual_rail-1.3.0/node/conformance.js +124 -0
  45. dual_rail-1.3.0/node/declaration.js +552 -0
  46. dual_rail-1.3.0/node/dual-rail.js +391 -0
  47. dual_rail-1.3.0/node/money.js +69 -0
  48. dual_rail-1.3.0/node/network.js +122 -0
  49. dual_rail-1.3.0/node/node-client.js +84 -0
  50. dual_rail-1.3.0/node/package.json +33 -0
  51. dual_rail-1.3.0/node/test/declaration.test.js +321 -0
  52. dual_rail-1.3.0/node/test/dual-rail.test.js +624 -0
  53. dual_rail-1.3.0/node/testhost.js +91 -0
  54. dual_rail-1.3.0/proof.json +23 -0
  55. dual_rail-1.3.0/pyproject.toml +23 -0
  56. dual_rail-1.3.0/setup.cfg +4 -0
  57. dual_rail-1.3.0/tests/capture_live_verify.py +99 -0
  58. dual_rail-1.3.0/tests/cross-check-against-x402-core.txt +69 -0
  59. dual_rail-1.3.0/tests/cross_check_x402_core.js +204 -0
  60. dual_rail-1.3.0/tests/test_acceptance_kit.py +118 -0
  61. dual_rail-1.3.0/tests/test_accepts_snippet.py +218 -0
  62. dual_rail-1.3.0/tests/test_binding.py +192 -0
  63. dual_rail-1.3.0/tests/test_conformance.py +403 -0
  64. dual_rail-1.3.0/tests/test_declaration.py +644 -0
  65. dual_rail-1.3.0/tests/test_dual_rail.py +1376 -0
  66. dual_rail-1.3.0/tests/test_end_to_end_doc.py +229 -0
  67. dual_rail-1.3.0/tests/test_hosted_facilitator.py +110 -0
  68. dual_rail-1.3.0/tests/test_seller_guide_faq.py +18 -0
  69. dual_rail-1.3.0/tests/test_verifiers.py +130 -0
  70. dual_rail-1.3.0/tests/verify-against-a-live-endpoint.txt +125 -0
  71. dual_rail-1.3.0/vercel.json +1 -0
@@ -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.
@@ -0,0 +1,10 @@
1
+ include README.md LICENSE llms.txt proof.json vercel.json
2
+ graft dual_rail
3
+ graft tests
4
+ graft docs
5
+ graft node
6
+ graft api
7
+ graft audits
8
+ prune node/node_modules
9
+ global-exclude *.py[cod]
10
+ exclude tests/conformance-matrix.json
@@ -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`.