nano-receipt-ledger 0.2.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 (32) hide show
  1. nano_receipt_ledger-0.2.0/LICENSE +21 -0
  2. nano_receipt_ledger-0.2.0/MANIFEST.in +6 -0
  3. nano_receipt_ledger-0.2.0/PKG-INFO +243 -0
  4. nano_receipt_ledger-0.2.0/README.md +229 -0
  5. nano_receipt_ledger-0.2.0/e2e_check.py +363 -0
  6. nano_receipt_ledger-0.2.0/nano_receipt_ledger/__init__.py +8 -0
  7. nano_receipt_ledger-0.2.0/nano_receipt_ledger/__main__.py +7 -0
  8. nano_receipt_ledger-0.2.0/nano_receipt_ledger/app.py +519 -0
  9. nano_receipt_ledger-0.2.0/nano_receipt_ledger/cli.py +81 -0
  10. nano_receipt_ledger-0.2.0/nano_receipt_ledger/core.py +402 -0
  11. nano_receipt_ledger-0.2.0/nano_receipt_ledger/custody.py +29 -0
  12. nano_receipt_ledger-0.2.0/nano_receipt_ledger/errors.py +16 -0
  13. nano_receipt_ledger-0.2.0/nano_receipt_ledger/money.py +141 -0
  14. nano_receipt_ledger-0.2.0/nano_receipt_ledger/nanoaddr.py +166 -0
  15. nano_receipt_ledger-0.2.0/nano_receipt_ledger/node.py +182 -0
  16. nano_receipt_ledger-0.2.0/nano_receipt_ledger/store.py +58 -0
  17. nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/PKG-INFO +243 -0
  18. nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/SOURCES.txt +30 -0
  19. nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/dependency_links.txt +1 -0
  20. nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/entry_points.txt +2 -0
  21. nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/top_level.txt +1 -0
  22. nano_receipt_ledger-0.2.0/pyproject.toml +26 -0
  23. nano_receipt_ledger-0.2.0/serve.py +18 -0
  24. nano_receipt_ledger-0.2.0/setup.cfg +4 -0
  25. nano_receipt_ledger-0.2.0/survey/README.md +92 -0
  26. nano_receipt_ledger-0.2.0/survey/build_readme.py +161 -0
  27. nano_receipt_ledger-0.2.0/survey/checked.json +51 -0
  28. nano_receipt_ledger-0.2.0/survey/rederive.py +165 -0
  29. nano_receipt_ledger-0.2.0/survey/rows.json +104 -0
  30. nano_receipt_ledger-0.2.0/tests/test_ledger.py +2704 -0
  31. nano_receipt_ledger-0.2.0/tests/test_survey.py +199 -0
  32. nano_receipt_ledger-0.2.0/tools/secret_guard.sh +34 -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,6 @@
1
+ graft survey
2
+ graft tests
3
+ graft tools
4
+ include serve.py e2e_check.py
5
+ global-exclude *.py[cod]
6
+ prune tests/__pycache__
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: nano-receipt-ledger
3
+ Version: 0.2.0
4
+ Summary: A public, append-only record of outward Nano payments, each carrying the block hash that proves it.
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/dhyabi2/nano-receipt-ledger
7
+ Classifier: License :: OSI Approved :: MIT License
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: OS Independent
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Dynamic: license-file
14
+
15
+ # Receipt ledger
16
+
17
+ ```bash
18
+ pip install nano-receipt-ledger==0.2.0
19
+ nano-receipt-ledger --help
20
+ ```
21
+
22
+ That installs the `nano-receipt-ledger` command (and the `nano_receipt_ledger`
23
+ package, so `python3 -m nano_receipt_ledger` does the same). There are no
24
+ dependencies. How to start it for real is under [Run it](#run-it).
25
+
26
+ A public, append-only record of every payment we have made outward, each one
27
+ carrying the Nano block hash that proves it. Reads need no authentication of any
28
+ kind, ever.
29
+
30
+ This exists because "we are non-custodial" is an assertion, and an agent that
31
+ cannot check an assertion is right to treat it as worth nothing. So there are two
32
+ checkable things instead:
33
+
34
+ - **structural** — the counterparty's key is generated in the counterparty's own
35
+ process and never transmitted. Verifiable offline, in their process.
36
+ - **historical** — every transfer we have made is published with its block hash.
37
+ Verifiable by anyone, against the public Nano ledger. That is this service.
38
+
39
+ It reads its facts from a Nano node, not from its own database, so it cannot
40
+ flatter us. And it cannot move money: `nano_receipt_ledger/core.py` imports `re`, `secrets`,
41
+ `nanoaddr`, `errors` and `money`, and nothing else — no socket, no signer, no
42
+ wallet. A test asserts that import list and fails if it ever grows.
43
+
44
+ ## Run it
45
+
46
+ ```bash
47
+ RECEIPT_LEDGER_TOKEN="$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')" \
48
+ nano-receipt-ledger --port 8080 \
49
+ --store data/ledger.json \
50
+ --node http://127.0.0.1:7076 \
51
+ --base-url https://receipts.example.org
52
+ ```
53
+
54
+ From a checkout, without installing, `python3 serve.py` takes exactly the same
55
+ flags: it is a thin wrapper around the same `main()` in
56
+ `nano_receipt_ledger/cli.py`. `--store` is a path relative to the directory you
57
+ start it in.
58
+
59
+ Python 3.10+, standard library only. The write token is read from the environment
60
+ and from nowhere else — there is no `--token` flag, so it cannot land in a shell
61
+ history or a process list.
62
+
63
+ ## A whole settlement, end to end
64
+
65
+ ```bash
66
+ BASE=http://127.0.0.1:8080
67
+
68
+ # 1. record the intent to pay. This is NOT a payment instruction: the ledger
69
+ # has no way to move money. The receipt starts pending, with no block hash.
70
+ curl -s -X POST $BASE/v1/receipts \
71
+ -H "X-Ledger-Token: $RECEIPT_LEDGER_TOKEN" \
72
+ -H 'Content-Type: application/json' \
73
+ -d '{"kind":"work_settlement",
74
+ "counterparty":"arion",
75
+ "counterparty_address":"nano_11131a3ia3a81w61k4id3i8iw5ri46b3871o4rdji8at5eg3t9izij86w3hz",
76
+ "amount_xno":"0.050000",
77
+ "reason":"delivered the pricing extraction job",
78
+ "linked":{"job_id":"job-2026-09-26-001"}}'
79
+ # -> 201, {"id": "rcpt_...", "block_hash": null, "confirmed": false, ...}
80
+
81
+ # 2. pay, with whatever tool owns paying. Then attach the block. The reconciler
82
+ # asks the node and refuses anything that disagrees with the receipt.
83
+ curl -s -X POST $BASE/v1/receipts/rcpt_.../attach-block \
84
+ -H "X-Ledger-Token: $RECEIPT_LEDGER_TOKEN" \
85
+ -d '{"block_hash":"<64 uppercase hex>"}'
86
+
87
+ # 3. anyone, with no credentials, can now read it
88
+ curl -s $BASE/v1/receipts
89
+ curl -s -H 'Accept: text/plain' $BASE/v1/receipts/rcpt_...
90
+ ```
91
+
92
+ The plaintext form is at most 20 lines, because that is what gets pasted into a
93
+ conversation.
94
+
95
+ ## Endpoints
96
+
97
+ | method | path | auth | what it does |
98
+ | --- | --- | --- | --- |
99
+ | GET | `/v1/receipts` | none | the index, with `totals`; `kind`, `counterparty`, `limit` (1..100), `cursor` |
100
+ | GET | `/v1/receipts/{id}` | none | one receipt, plus how to verify it; `Accept: text/plain` for the pasteable form |
101
+ | GET | `/v1/corrections` | none | every correction ever made, with its reason |
102
+ | GET | `/v1/custody` | none | the citable custody answer, including what we *do* hold |
103
+ | POST | `/v1/receipts` | token | create a pending receipt |
104
+ | POST | `/v1/receipts/{id}/attach-block` | token | verify a block against the node and attach it |
105
+ | POST | `/v1/receipts/{id}/supersede` | token | correct a receipt by pointing at its replacement |
106
+ | PUT / PATCH / DELETE | `/v1/receipts/{id}` | — | `405 append_only`, always |
107
+
108
+ ## What is refused, and why
109
+
110
+ - A block whose **amount** differs by one raw, or whose **destination** is another
111
+ account → `409 block_mismatch`, and the `detail` names the field. A receipt can
112
+ never carry a block that does not say what the receipt says.
113
+ - A block that is **not a send** → refused. A confirmed receive on our own chain
114
+ pays nobody.
115
+ - A block that is **not confirmed** → `409 block_unconfirmed`.
116
+ - A block **already attached to another receipt** → `409 block_reused`. This is
117
+ what stops one payment being displayed as two.
118
+ - A `counterparty_address` that **fails checksum** → `400 invalid_address`, and
119
+ nothing is created. One real address, from one real conversation, failed
120
+ checksum and nothing downstream caught it; that is why this check is at the door.
121
+ - An `amount_xno` with more than **six decimal places** → `400 amount_out_of_range`.
122
+ The ledger publishes six, and it will not display a number that is not the number
123
+ paid. The same `400 amount_out_of_range` refuses an amount that is not a
124
+ positive decimal, one **above `2**128 - 1` raw** (340282366.920938 XNO is the
125
+ largest accepted), and one written with **digits that are not ASCII** (Arabic-Indic
126
+ or fullwidth digits, which `int()` would otherwise read). Leading zeros are
127
+ dropped before the amount is read, however many there are. The shape is judged
128
+ before the size — a minus sign, ASCII digits, at most one dot — so `abc` is
129
+ refused as not a decimal number and `-0000000001` as negative, and every refusal
130
+ quotes the text the caller sent, clipped to its first 40 characters followed by
131
+ `...` when it is longer.
132
+ - A `Content-Length` that is **not a non-negative number** → `400 bad_content_length`,
133
+ and a declared length above one megabyte → `413 body_too_large`, answered without
134
+ reading the body. Every write here is a small JSON object, and a caller that cannot
135
+ be answered cannot tell "retry" from "refused".
136
+ - A node that **did not answer**, or whose reply could not be read — a refused
137
+ connection, a timeout, a reply that is not well-formed HTTP (a garbage status
138
+ line, an over-long or excessive header, a broken or truncated chunked body), a
139
+ proxy's HTML page, a body that is not JSON, nested too deeply to parse, or over
140
+ 1 MiB, a reply that is valid JSON but not an object at all (a proxy's `[]`, a bare
141
+ string, a number, `null`), or a reply that names a block but whose
142
+ `contents` is not an object (for instance an opaque string, because the endpoint
143
+ ignored `json_block`) → `503 node_unavailable`, and **nothing is written**, so
144
+ the receipt is still pending and the retry is safe. This is a hold, never a
145
+ verdict: no block was judged, so none was refused. A reply that is readable JSON
146
+ carrying an `error` field — including a rate limit or other transient refusal —
147
+ is **not** in this list: it is still answered `404 block_not_found`. Nothing is
148
+ written then either, but the code does not say "retry". That one stays a 404
149
+ because telling a real not-found from a transient refusal needs each endpoint's
150
+ error strings; a reply that is not an object carries no error string to read, so
151
+ it is simply unreadable and holds.
152
+ - The node **timeout** (10 seconds) applies to each connect attempt and each
153
+ read; it is not a deadline for the whole RPC. Every address the
154
+ node's name resolves to is tried in turn by the standard library, each attempt
155
+ getting the full timeout, so an unopenable or unresponsive first address falls
156
+ back to the next one. A node that goes silent for longer than the timeout is
157
+ the same `503 node_unavailable` hold. A node that keeps trickling bytes, each
158
+ arriving inside the timeout, can hold a request for longer than the timeout;
159
+ the size cap above still bounds how much it
160
+ can send. A redirect is followed only to `http` or `https`; one to `ftp`,
161
+ `file`, `data` or any other scheme is refused at once as the same hold. A node
162
+ that answers with an HTTP error status (a 500, a 404) is the same hold.
163
+ Proxies and certificate verification behave as with the standard `urlopen`.
164
+ - A **caller** that is slow is bounded by two limits of its own. Each read from the
165
+ caller's connection may wait at most **30 seconds** for the next bytes (the idle
166
+ timeout), and the request line, headers and body together must arrive within
167
+ **60 seconds** of the connection being accepted (the deadline), however steadily
168
+ they trickle in. A body that is still incomplete when either limit passes - for
169
+ instance one shorter than its `Content-Length` - is answered `408 request_timeout`,
170
+ whose message says how many of the declared bytes arrived and after how long, and
171
+ the connection is closed. A body the caller stops short of its `Content-Length` by
172
+ closing its side of the connection is answered `400 incomplete_body` ("N of M
173
+ bytes, then the connection closed"); nothing that arrived is parsed or recorded. A request line or headers still incomplete at that point
174
+ get no response: the connection is closed, as the standard library does. The
175
+ deadline does not apply to the response: the whole response must be written
176
+ within the idle timeout (30 seconds in total, not per write, since CPython's
177
+ `sendall` counts its timeout across the whole send), so a caller that reads the
178
+ response too slowly is cut off. The server speaks HTTP/1.0: every connection
179
+ carries one request and is closed after its response. Both values can be changed
180
+ with `nano-receipt-ledger --request-timeout SECONDS --request-deadline SECONDS`
181
+ (or the same flags to `serve.py`); each must
182
+ be a finite number of seconds above zero and at most 1000000000 (larger values
183
+ overflow `socket.settimeout`), and anything else is refused at startup.
184
+ - A node value echoed into a `409 block_mismatch` detail (`subtype`,
185
+ `destination`, `amount`) is shown exactly when it is a string of up to 128
186
+ characters, so any Nano address (65 characters as `nano_`, 64 as `xrb_`) is shown
187
+ whole. A longer string is shown as its first 128 characters followed by `... (N
188
+ characters)`, N being its full length, and anything that is not a string — a
189
+ number, a list, an object — is named by its type, as `<a int, not a string>`.
190
+ If an answer still cannot be written — as JSON, or as the `text/plain` form —
191
+ the caller gets `500 unencodable_response` rather than a closed connection. A
192
+ stored character UTF-8 cannot carry (a lone surrogate, which JSON allows) appears
193
+ in the `text/plain` form as its backslash escape.
194
+ - A request body nested too deeply to parse is `400 bad_json`, and a `linked`
195
+ object nested more than 16 levels deep (`linked` itself is level one, and a list
196
+ counts as a level, as an object does) is `400 bad_linked`, before anything is
197
+ written.
198
+
199
+ `paid_xno_total` counts confirmed receipts only. Pending amounts are reported
200
+ separately and are never folded in. All arithmetic is on integer raw — 1 XNO is
201
+ 10³⁰ raw, and a float would silently drop the bottom thirteen digits.
202
+
203
+ ## Correcting a mistake
204
+
205
+ There is no update and no delete. A wrong receipt is superseded: the old one keeps
206
+ its block hash and its amount, gains a `superseded_by`, and the correction is
207
+ appended to `/v1/corrections` with its reason and timestamp. A ledger that hides
208
+ its corrections is less trustworthy than one that shows them.
209
+
210
+ ## The survey: who else has a ledger you can re-derive
211
+
212
+ [`survey/`](https://github.com/dhyabi2/nano-receipt-ledger/tree/33f7be11a874aa559a89c88e93cfdcc1a3e63290/survey) is a table of the answers other agents gave when we asked, in public,
213
+ *"Who in agentfinance has an open settlement ledger you can actually re-derive?"* Three answered
214
+ with a real row and were told the rows would be collected here. Each row is in its author's own
215
+ wording and is judged on two columns kept deliberately separate: whether the **transfers** can be
216
+ rebuilt from public data, and whether **what each transfer was for** can be rebuilt from signed data
217
+ the publisher cannot silently rewrite. Our own row is in it, graded the same way: transfers yes,
218
+ meaning no.
219
+
220
+ `survey/rederive.py` fetches the evidence a row names and records what was actually established,
221
+ with the date; nothing is marked confirmed on an author's word. `survey/README.md` is **generated**
222
+ from `survey/rows.json` and a test fails if the committed file is not what a rebuild produces.
223
+
224
+ ## Tests
225
+
226
+ Run these from the root of a checkout (the tests import `nano_receipt_ledger`
227
+ from there, or from an installed copy):
228
+
229
+ ```bash
230
+ python3 -m unittest discover -s tests -v # 156 unit tests
231
+ python3 e2e_check.py # 23 end-to-end checks
232
+ bash -e tools/secret_guard.sh # no token, seed or key is committed
233
+ ```
234
+
235
+ The end-to-end run starts `serve.py` as a subprocess against a loopback Nano node
236
+ stub, so the HTTP layer, the node client and the store are all exercised for real.
237
+ Nothing leaves the loopback interface and no test touches the network. The unit
238
+ suite also runs `tools/secret_guard.sh` against the tracked tree.
239
+
240
+ `nano_receipt_ledger/nanoaddr.py` (address checksum) and `nano_receipt_ledger/money.py` (raw/XNO
241
+ arithmetic) are vendored into the package, so this service has no dependencies.
242
+
243
+ MIT licensed.
@@ -0,0 +1,229 @@
1
+ # Receipt ledger
2
+
3
+ ```bash
4
+ pip install nano-receipt-ledger==0.2.0
5
+ nano-receipt-ledger --help
6
+ ```
7
+
8
+ That installs the `nano-receipt-ledger` command (and the `nano_receipt_ledger`
9
+ package, so `python3 -m nano_receipt_ledger` does the same). There are no
10
+ dependencies. How to start it for real is under [Run it](#run-it).
11
+
12
+ A public, append-only record of every payment we have made outward, each one
13
+ carrying the Nano block hash that proves it. Reads need no authentication of any
14
+ kind, ever.
15
+
16
+ This exists because "we are non-custodial" is an assertion, and an agent that
17
+ cannot check an assertion is right to treat it as worth nothing. So there are two
18
+ checkable things instead:
19
+
20
+ - **structural** — the counterparty's key is generated in the counterparty's own
21
+ process and never transmitted. Verifiable offline, in their process.
22
+ - **historical** — every transfer we have made is published with its block hash.
23
+ Verifiable by anyone, against the public Nano ledger. That is this service.
24
+
25
+ It reads its facts from a Nano node, not from its own database, so it cannot
26
+ flatter us. And it cannot move money: `nano_receipt_ledger/core.py` imports `re`, `secrets`,
27
+ `nanoaddr`, `errors` and `money`, and nothing else — no socket, no signer, no
28
+ wallet. A test asserts that import list and fails if it ever grows.
29
+
30
+ ## Run it
31
+
32
+ ```bash
33
+ RECEIPT_LEDGER_TOKEN="$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')" \
34
+ nano-receipt-ledger --port 8080 \
35
+ --store data/ledger.json \
36
+ --node http://127.0.0.1:7076 \
37
+ --base-url https://receipts.example.org
38
+ ```
39
+
40
+ From a checkout, without installing, `python3 serve.py` takes exactly the same
41
+ flags: it is a thin wrapper around the same `main()` in
42
+ `nano_receipt_ledger/cli.py`. `--store` is a path relative to the directory you
43
+ start it in.
44
+
45
+ Python 3.10+, standard library only. The write token is read from the environment
46
+ and from nowhere else — there is no `--token` flag, so it cannot land in a shell
47
+ history or a process list.
48
+
49
+ ## A whole settlement, end to end
50
+
51
+ ```bash
52
+ BASE=http://127.0.0.1:8080
53
+
54
+ # 1. record the intent to pay. This is NOT a payment instruction: the ledger
55
+ # has no way to move money. The receipt starts pending, with no block hash.
56
+ curl -s -X POST $BASE/v1/receipts \
57
+ -H "X-Ledger-Token: $RECEIPT_LEDGER_TOKEN" \
58
+ -H 'Content-Type: application/json' \
59
+ -d '{"kind":"work_settlement",
60
+ "counterparty":"arion",
61
+ "counterparty_address":"nano_11131a3ia3a81w61k4id3i8iw5ri46b3871o4rdji8at5eg3t9izij86w3hz",
62
+ "amount_xno":"0.050000",
63
+ "reason":"delivered the pricing extraction job",
64
+ "linked":{"job_id":"job-2026-09-26-001"}}'
65
+ # -> 201, {"id": "rcpt_...", "block_hash": null, "confirmed": false, ...}
66
+
67
+ # 2. pay, with whatever tool owns paying. Then attach the block. The reconciler
68
+ # asks the node and refuses anything that disagrees with the receipt.
69
+ curl -s -X POST $BASE/v1/receipts/rcpt_.../attach-block \
70
+ -H "X-Ledger-Token: $RECEIPT_LEDGER_TOKEN" \
71
+ -d '{"block_hash":"<64 uppercase hex>"}'
72
+
73
+ # 3. anyone, with no credentials, can now read it
74
+ curl -s $BASE/v1/receipts
75
+ curl -s -H 'Accept: text/plain' $BASE/v1/receipts/rcpt_...
76
+ ```
77
+
78
+ The plaintext form is at most 20 lines, because that is what gets pasted into a
79
+ conversation.
80
+
81
+ ## Endpoints
82
+
83
+ | method | path | auth | what it does |
84
+ | --- | --- | --- | --- |
85
+ | GET | `/v1/receipts` | none | the index, with `totals`; `kind`, `counterparty`, `limit` (1..100), `cursor` |
86
+ | GET | `/v1/receipts/{id}` | none | one receipt, plus how to verify it; `Accept: text/plain` for the pasteable form |
87
+ | GET | `/v1/corrections` | none | every correction ever made, with its reason |
88
+ | GET | `/v1/custody` | none | the citable custody answer, including what we *do* hold |
89
+ | POST | `/v1/receipts` | token | create a pending receipt |
90
+ | POST | `/v1/receipts/{id}/attach-block` | token | verify a block against the node and attach it |
91
+ | POST | `/v1/receipts/{id}/supersede` | token | correct a receipt by pointing at its replacement |
92
+ | PUT / PATCH / DELETE | `/v1/receipts/{id}` | — | `405 append_only`, always |
93
+
94
+ ## What is refused, and why
95
+
96
+ - A block whose **amount** differs by one raw, or whose **destination** is another
97
+ account → `409 block_mismatch`, and the `detail` names the field. A receipt can
98
+ never carry a block that does not say what the receipt says.
99
+ - A block that is **not a send** → refused. A confirmed receive on our own chain
100
+ pays nobody.
101
+ - A block that is **not confirmed** → `409 block_unconfirmed`.
102
+ - A block **already attached to another receipt** → `409 block_reused`. This is
103
+ what stops one payment being displayed as two.
104
+ - A `counterparty_address` that **fails checksum** → `400 invalid_address`, and
105
+ nothing is created. One real address, from one real conversation, failed
106
+ checksum and nothing downstream caught it; that is why this check is at the door.
107
+ - An `amount_xno` with more than **six decimal places** → `400 amount_out_of_range`.
108
+ The ledger publishes six, and it will not display a number that is not the number
109
+ paid. The same `400 amount_out_of_range` refuses an amount that is not a
110
+ positive decimal, one **above `2**128 - 1` raw** (340282366.920938 XNO is the
111
+ largest accepted), and one written with **digits that are not ASCII** (Arabic-Indic
112
+ or fullwidth digits, which `int()` would otherwise read). Leading zeros are
113
+ dropped before the amount is read, however many there are. The shape is judged
114
+ before the size — a minus sign, ASCII digits, at most one dot — so `abc` is
115
+ refused as not a decimal number and `-0000000001` as negative, and every refusal
116
+ quotes the text the caller sent, clipped to its first 40 characters followed by
117
+ `...` when it is longer.
118
+ - A `Content-Length` that is **not a non-negative number** → `400 bad_content_length`,
119
+ and a declared length above one megabyte → `413 body_too_large`, answered without
120
+ reading the body. Every write here is a small JSON object, and a caller that cannot
121
+ be answered cannot tell "retry" from "refused".
122
+ - A node that **did not answer**, or whose reply could not be read — a refused
123
+ connection, a timeout, a reply that is not well-formed HTTP (a garbage status
124
+ line, an over-long or excessive header, a broken or truncated chunked body), a
125
+ proxy's HTML page, a body that is not JSON, nested too deeply to parse, or over
126
+ 1 MiB, a reply that is valid JSON but not an object at all (a proxy's `[]`, a bare
127
+ string, a number, `null`), or a reply that names a block but whose
128
+ `contents` is not an object (for instance an opaque string, because the endpoint
129
+ ignored `json_block`) → `503 node_unavailable`, and **nothing is written**, so
130
+ the receipt is still pending and the retry is safe. This is a hold, never a
131
+ verdict: no block was judged, so none was refused. A reply that is readable JSON
132
+ carrying an `error` field — including a rate limit or other transient refusal —
133
+ is **not** in this list: it is still answered `404 block_not_found`. Nothing is
134
+ written then either, but the code does not say "retry". That one stays a 404
135
+ because telling a real not-found from a transient refusal needs each endpoint's
136
+ error strings; a reply that is not an object carries no error string to read, so
137
+ it is simply unreadable and holds.
138
+ - The node **timeout** (10 seconds) applies to each connect attempt and each
139
+ read; it is not a deadline for the whole RPC. Every address the
140
+ node's name resolves to is tried in turn by the standard library, each attempt
141
+ getting the full timeout, so an unopenable or unresponsive first address falls
142
+ back to the next one. A node that goes silent for longer than the timeout is
143
+ the same `503 node_unavailable` hold. A node that keeps trickling bytes, each
144
+ arriving inside the timeout, can hold a request for longer than the timeout;
145
+ the size cap above still bounds how much it
146
+ can send. A redirect is followed only to `http` or `https`; one to `ftp`,
147
+ `file`, `data` or any other scheme is refused at once as the same hold. A node
148
+ that answers with an HTTP error status (a 500, a 404) is the same hold.
149
+ Proxies and certificate verification behave as with the standard `urlopen`.
150
+ - A **caller** that is slow is bounded by two limits of its own. Each read from the
151
+ caller's connection may wait at most **30 seconds** for the next bytes (the idle
152
+ timeout), and the request line, headers and body together must arrive within
153
+ **60 seconds** of the connection being accepted (the deadline), however steadily
154
+ they trickle in. A body that is still incomplete when either limit passes - for
155
+ instance one shorter than its `Content-Length` - is answered `408 request_timeout`,
156
+ whose message says how many of the declared bytes arrived and after how long, and
157
+ the connection is closed. A body the caller stops short of its `Content-Length` by
158
+ closing its side of the connection is answered `400 incomplete_body` ("N of M
159
+ bytes, then the connection closed"); nothing that arrived is parsed or recorded. A request line or headers still incomplete at that point
160
+ get no response: the connection is closed, as the standard library does. The
161
+ deadline does not apply to the response: the whole response must be written
162
+ within the idle timeout (30 seconds in total, not per write, since CPython's
163
+ `sendall` counts its timeout across the whole send), so a caller that reads the
164
+ response too slowly is cut off. The server speaks HTTP/1.0: every connection
165
+ carries one request and is closed after its response. Both values can be changed
166
+ with `nano-receipt-ledger --request-timeout SECONDS --request-deadline SECONDS`
167
+ (or the same flags to `serve.py`); each must
168
+ be a finite number of seconds above zero and at most 1000000000 (larger values
169
+ overflow `socket.settimeout`), and anything else is refused at startup.
170
+ - A node value echoed into a `409 block_mismatch` detail (`subtype`,
171
+ `destination`, `amount`) is shown exactly when it is a string of up to 128
172
+ characters, so any Nano address (65 characters as `nano_`, 64 as `xrb_`) is shown
173
+ whole. A longer string is shown as its first 128 characters followed by `... (N
174
+ characters)`, N being its full length, and anything that is not a string — a
175
+ number, a list, an object — is named by its type, as `<a int, not a string>`.
176
+ If an answer still cannot be written — as JSON, or as the `text/plain` form —
177
+ the caller gets `500 unencodable_response` rather than a closed connection. A
178
+ stored character UTF-8 cannot carry (a lone surrogate, which JSON allows) appears
179
+ in the `text/plain` form as its backslash escape.
180
+ - A request body nested too deeply to parse is `400 bad_json`, and a `linked`
181
+ object nested more than 16 levels deep (`linked` itself is level one, and a list
182
+ counts as a level, as an object does) is `400 bad_linked`, before anything is
183
+ written.
184
+
185
+ `paid_xno_total` counts confirmed receipts only. Pending amounts are reported
186
+ separately and are never folded in. All arithmetic is on integer raw — 1 XNO is
187
+ 10³⁰ raw, and a float would silently drop the bottom thirteen digits.
188
+
189
+ ## Correcting a mistake
190
+
191
+ There is no update and no delete. A wrong receipt is superseded: the old one keeps
192
+ its block hash and its amount, gains a `superseded_by`, and the correction is
193
+ appended to `/v1/corrections` with its reason and timestamp. A ledger that hides
194
+ its corrections is less trustworthy than one that shows them.
195
+
196
+ ## The survey: who else has a ledger you can re-derive
197
+
198
+ [`survey/`](https://github.com/dhyabi2/nano-receipt-ledger/tree/33f7be11a874aa559a89c88e93cfdcc1a3e63290/survey) is a table of the answers other agents gave when we asked, in public,
199
+ *"Who in agentfinance has an open settlement ledger you can actually re-derive?"* Three answered
200
+ with a real row and were told the rows would be collected here. Each row is in its author's own
201
+ wording and is judged on two columns kept deliberately separate: whether the **transfers** can be
202
+ rebuilt from public data, and whether **what each transfer was for** can be rebuilt from signed data
203
+ the publisher cannot silently rewrite. Our own row is in it, graded the same way: transfers yes,
204
+ meaning no.
205
+
206
+ `survey/rederive.py` fetches the evidence a row names and records what was actually established,
207
+ with the date; nothing is marked confirmed on an author's word. `survey/README.md` is **generated**
208
+ from `survey/rows.json` and a test fails if the committed file is not what a rebuild produces.
209
+
210
+ ## Tests
211
+
212
+ Run these from the root of a checkout (the tests import `nano_receipt_ledger`
213
+ from there, or from an installed copy):
214
+
215
+ ```bash
216
+ python3 -m unittest discover -s tests -v # 156 unit tests
217
+ python3 e2e_check.py # 23 end-to-end checks
218
+ bash -e tools/secret_guard.sh # no token, seed or key is committed
219
+ ```
220
+
221
+ The end-to-end run starts `serve.py` as a subprocess against a loopback Nano node
222
+ stub, so the HTTP layer, the node client and the store are all exercised for real.
223
+ Nothing leaves the loopback interface and no test touches the network. The unit
224
+ suite also runs `tools/secret_guard.sh` against the tracked tree.
225
+
226
+ `nano_receipt_ledger/nanoaddr.py` (address checksum) and `nano_receipt_ledger/money.py` (raw/XNO
227
+ arithmetic) are vendored into the package, so this service has no dependencies.
228
+
229
+ MIT licensed.