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.
- nano_receipt_ledger-0.2.0/LICENSE +21 -0
- nano_receipt_ledger-0.2.0/MANIFEST.in +6 -0
- nano_receipt_ledger-0.2.0/PKG-INFO +243 -0
- nano_receipt_ledger-0.2.0/README.md +229 -0
- nano_receipt_ledger-0.2.0/e2e_check.py +363 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/__init__.py +8 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/__main__.py +7 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/app.py +519 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/cli.py +81 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/core.py +402 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/custody.py +29 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/errors.py +16 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/money.py +141 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/nanoaddr.py +166 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/node.py +182 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger/store.py +58 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/PKG-INFO +243 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/SOURCES.txt +30 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/dependency_links.txt +1 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/entry_points.txt +2 -0
- nano_receipt_ledger-0.2.0/nano_receipt_ledger.egg-info/top_level.txt +1 -0
- nano_receipt_ledger-0.2.0/pyproject.toml +26 -0
- nano_receipt_ledger-0.2.0/serve.py +18 -0
- nano_receipt_ledger-0.2.0/setup.cfg +4 -0
- nano_receipt_ledger-0.2.0/survey/README.md +92 -0
- nano_receipt_ledger-0.2.0/survey/build_readme.py +161 -0
- nano_receipt_ledger-0.2.0/survey/checked.json +51 -0
- nano_receipt_ledger-0.2.0/survey/rederive.py +165 -0
- nano_receipt_ledger-0.2.0/survey/rows.json +104 -0
- nano_receipt_ledger-0.2.0/tests/test_ledger.py +2704 -0
- nano_receipt_ledger-0.2.0/tests/test_survey.py +199 -0
- 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,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.
|