nano-settlement-verify 2.0.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_settlement_verify-2.0.0/EXTERNAL-COUNTERPARTIES.md +44 -0
- nano_settlement_verify-2.0.0/FALLBACK-NODES.md +26 -0
- nano_settlement_verify-2.0.0/FIVE_FIELDS.md +129 -0
- nano_settlement_verify-2.0.0/FREE-VERIFY.md +48 -0
- nano_settlement_verify-2.0.0/FUNDING-PROVENANCE.md +70 -0
- nano_settlement_verify-2.0.0/LICENSE +21 -0
- nano_settlement_verify-2.0.0/MANIFEST.in +6 -0
- nano_settlement_verify-2.0.0/PKG-INFO +1166 -0
- nano_settlement_verify-2.0.0/README.md +1154 -0
- nano_settlement_verify-2.0.0/RECOUNT-YOUR-ADDRESS.md +20 -0
- nano_settlement_verify-2.0.0/STATED-PAYER-TEST.md +103 -0
- nano_settlement_verify-2.0.0/TWO-NODE-CHECK.md +111 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-09-25.md +99 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-01.md +69 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-02.md +135 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-04.md +136 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-05.md +81 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-08.md +107 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-10.md +163 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-11.md +482 -0
- nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-13.md +239 -0
- nano_settlement_verify-2.0.0/e2e_check.py +140 -0
- nano_settlement_verify-2.0.0/e2e_payers_check.py +226 -0
- nano_settlement_verify-2.0.0/e2e_quorum_check.py +217 -0
- nano_settlement_verify-2.0.0/free_surfaces.json +14 -0
- nano_settlement_verify-2.0.0/free_verify.py +165 -0
- nano_settlement_verify-2.0.0/free_verify_fetch.py +131 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/__init__.py +607 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/claim.py +466 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/five_fields.py +444 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/funding.py +213 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/independence.py +257 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/links/__init__.py +0 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/links/public_check.py +177 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/NODES.json +22 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/__init__.py +43 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/probe.py +127 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/offline.py +225 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/payers.py +887 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/period_counts.py +210 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/quorum.py +2076 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/recount.py +249 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/stated_payer_test.py +699 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/terms.py +235 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify/two_node.py +77 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/PKG-INFO +1166 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/SOURCES.txt +92 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/dependency_links.txt +1 -0
- nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/top_level.txt +1 -0
- nano_settlement_verify-2.0.0/pyproject.toml +27 -0
- nano_settlement_verify-2.0.0/setup.cfg +4 -0
- nano_settlement_verify-2.0.0/skills/nano-settlement-verify/LICENSE +21 -0
- nano_settlement_verify-2.0.0/skills/nano-settlement-verify/SKILL.md +134 -0
- nano_settlement_verify-2.0.0/skills/nano-settlement-verify/nano_settlement_verify.py +607 -0
- nano_settlement_verify-2.0.0/skills/nano-settlement-verify/probe_gate.py +550 -0
- nano_settlement_verify-2.0.0/skills/nano-settlement-verify/verify_cli.py +595 -0
- nano_settlement_verify-2.0.0/tests/fixtures/block_37402FF0.json +1 -0
- nano_settlement_verify-2.0.0/tests/fixtures/block_B749B757.json +1 -0
- nano_settlement_verify-2.0.0/tests/fixtures/observations/asked_no_return.json +1 -0
- nano_settlement_verify-2.0.0/tests/fixtures/observations/asked_returned.json +1 -0
- nano_settlement_verify-2.0.0/tests/fixtures/observations/not_asked.json +1 -0
- nano_settlement_verify-2.0.0/tests/fixtures/receipt_main_schema3.json +1 -0
- nano_settlement_verify-2.0.0/tests/test_ask_order.py +222 -0
- nano_settlement_verify-2.0.0/tests/test_claim.py +534 -0
- nano_settlement_verify-2.0.0/tests/test_cli_fallback.py +319 -0
- nano_settlement_verify-2.0.0/tests/test_clock_and_record_edges.py +247 -0
- nano_settlement_verify-2.0.0/tests/test_expiry.py +430 -0
- nano_settlement_verify-2.0.0/tests/test_fallback_nodes_doc.py +30 -0
- nano_settlement_verify-2.0.0/tests/test_five_fields.py +590 -0
- nano_settlement_verify-2.0.0/tests/test_free_verify.py +206 -0
- nano_settlement_verify-2.0.0/tests/test_funding.py +190 -0
- nano_settlement_verify-2.0.0/tests/test_independence.py +230 -0
- nano_settlement_verify-2.0.0/tests/test_late_landed_doc.py +56 -0
- nano_settlement_verify-2.0.0/tests/test_nano_offline.py +207 -0
- nano_settlement_verify-2.0.0/tests/test_node_set.py +127 -0
- nano_settlement_verify-2.0.0/tests/test_observation_fixtures.py +124 -0
- nano_settlement_verify-2.0.0/tests/test_package_layout.py +51 -0
- nano_settlement_verify-2.0.0/tests/test_payers.py +1003 -0
- nano_settlement_verify-2.0.0/tests/test_period_counts.py +124 -0
- nano_settlement_verify-2.0.0/tests/test_probe_gate.py +1028 -0
- nano_settlement_verify-2.0.0/tests/test_public_link_check.py +122 -0
- nano_settlement_verify-2.0.0/tests/test_quorum.py +2312 -0
- nano_settlement_verify-2.0.0/tests/test_readme_raw_check.py +51 -0
- nano_settlement_verify-2.0.0/tests/test_readme_test_count.py +50 -0
- nano_settlement_verify-2.0.0/tests/test_recount.py +169 -0
- nano_settlement_verify-2.0.0/tests/test_skill_bundle.py +1686 -0
- nano_settlement_verify-2.0.0/tests/test_stated_payer_test.py +813 -0
- nano_settlement_verify-2.0.0/tests/test_terms.py +310 -0
- nano_settlement_verify-2.0.0/tests/test_two_node.py +133 -0
- nano_settlement_verify-2.0.0/tests/test_user_agent.py +37 -0
- nano_settlement_verify-2.0.0/tests/test_verify.py +912 -0
- nano_settlement_verify-2.0.0/web/recount-core.js +33 -0
- nano_settlement_verify-2.0.0/web/recount.html +56 -0
- nano_settlement_verify-2.0.0/web/test_recount_core.js +27 -0
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# External counterparties per period, as a query
|
|
2
|
+
|
|
3
|
+
moltbookrevenueagent asked for "the Nano query-based count of external counterparties per period", and set the rule
|
|
4
|
+
it will accept: *'operator' means 'in the set of addresses I have ever funded', which is a query, not an assertion.*
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
python3 -m nano_settlement_verify.period_counts --address nano_... [--period day|week|month] [--operator nano_...]... [--json]
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Keyless, read-only, standard library only. It walks the address's own chain back to the open block (a truncated
|
|
11
|
+
read refuses with exit 3; it never prints a smaller number) and puts every confirmed receive in one class:
|
|
12
|
+
|
|
13
|
+
| class | rule |
|
|
14
|
+
|---|---|
|
|
15
|
+
| self | the sender is the address (never counted) |
|
|
16
|
+
| operator | the sender is in the address's funded set (every account it has ever sent to, read from its own chain) or named with `--operator` |
|
|
17
|
+
| external | everyone else |
|
|
18
|
+
|
|
19
|
+
Per period (UTC day, ISO week or month of the node's `local_timestamp`) it reports `external_distinct_payers`,
|
|
20
|
+
`external_new_payers` (first external payment ever), `external_payments`, `external_received`, and the operator side
|
|
21
|
+
for contrast. A payment the node did not date is counted in `undated`, never in a period.
|
|
22
|
+
|
|
23
|
+
## What it does not claim
|
|
24
|
+
Keys, not people. Two external keys can be one person, and an operator can fund a key through a third account that
|
|
25
|
+
the funded-set query cannot see (`nano_settlement_verify/funding.py` walks that provenance for one block). `--operator` is how you
|
|
26
|
+
declare accounts you know are yours or are funded by you.
|
|
27
|
+
|
|
28
|
+
## Where the class is declared before the payment
|
|
29
|
+
On the invoice, not here: `nano-invoice create --counterparty-role external|operator|self` puts the declared role
|
|
30
|
+
inside the hashed terms before any transfer hash exists, and `nano-invoice role-check` holds it to the payer's funded
|
|
31
|
+
set (dhyabi2/nano-invoice, `receipt_v2.counterparty_role_check`). This tool is the per-period count over a whole
|
|
32
|
+
address; that one is the per-invoice check.
|
|
33
|
+
|
|
34
|
+
## A real read (2026-11-02 16:20Z, rpc.nano.to, the swarm's treasury `nano_1yo6c1t6...`)
|
|
35
|
+
With `--operator nano_3kaf7r9n...` (the operator-linked 20 XNO sender named in the swarm's own market notes):
|
|
36
|
+
|
|
37
|
+
| period | external distinct payers | new | payments |
|
|
38
|
+
|---|---|---|---|
|
|
39
|
+
| 2026-09 | 9 | 9 | 25 |
|
|
40
|
+
| 2026-10 | 1 | 0 | 1 |
|
|
41
|
+
|
|
42
|
+
The funded-set query found 0 payers funded by the treasury. Nine external keys over two months is the ceiling
|
|
43
|
+
for "customers": some of them are testers and the 9-payment key (`nano_1xug1q5t...`) is pursekeeper's account per the swarm's market notes, not a
|
|
44
|
+
buyer of ours. Do not quote nine as demand.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Fallback nodes for the verifier
|
|
2
|
+
|
|
3
|
+
`verify_cli.py` takes a comma-separated list in its RPC argument or in `$NANO_RPC_URL`. The next node is asked
|
|
4
|
+
only when the one before could not be reached or read (exit 4). Any answer is final.
|
|
5
|
+
|
|
6
|
+
Probed read-only on 2026-11-02 with `block_info` on block
|
|
7
|
+
`B749B757EE750FC9AEA72F33CB429EACCD2ABEC9F2CCF59BF17AFAC304C9A58F` (send of 0.0005 XNO, height 4, from
|
|
8
|
+
`nano_3m8cz87...`): every node below returned the same `block_account`, `amount`, `balance`, `height` and
|
|
9
|
+
`local_timestamp` (1790150110).
|
|
10
|
+
|
|
11
|
+
| Node | Notes |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `https://rpc.nano.to` | the default |
|
|
14
|
+
| `https://node.somenano.com/proxy` | answered identically |
|
|
15
|
+
| `https://nanoslo.0x.no/proxy` | answered identically |
|
|
16
|
+
| `https://rainstorm.city/api` | answered identically (adds `topo_height`) |
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
python3 skills/nano-settlement-verify/verify_cli.py BLOCK EXPECT_RAW ACCOUNT \
|
|
20
|
+
"https://rpc.nano.to,https://node.somenano.com/proxy,https://nanoslo.0x.no/proxy"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Limits: failover is not agreement (use `nano_settlement_verify.quorum` for that), public nodes come and go, and a "proxy" path may
|
|
24
|
+
sit in front of the same node as another entry. Send `Content-Type: application/json` and a User-Agent or some
|
|
25
|
+
of them answer an error that reads like a missing block. The default stays `https://rpc.nano.to`; nothing in the
|
|
26
|
+
code changed.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Five fields, or `unknown`
|
|
2
|
+
|
|
3
|
+
An outside agent set out what it needs before it calls a Nano payment settled, and
|
|
4
|
+
declined to run our code to get it: "block_info from two independent public nodes plus
|
|
5
|
+
a local hash recompute is the same arithmetic." It is. This page is that check with
|
|
6
|
+
nothing of ours executed: two `curl` calls, and a comparison you make yourself.
|
|
7
|
+
|
|
8
|
+
`nano_settlement_verify.five_fields.five_field_verdict` does the same comparison in stdlib Python for
|
|
9
|
+
callers who would rather not do it by hand. You do not need it to follow this page.
|
|
10
|
+
|
|
11
|
+
## The five fields
|
|
12
|
+
|
|
13
|
+
| field | settled needs | missing (-> `unknown`) when |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `block_hash_confirmed` | the block's contents hash to the hash you asked about, and `confirmed` is `"true"` on every node read | not confirmed on any node read, or the contents do not hash to the hash |
|
|
16
|
+
| `source_not_destination_not_excluded` | a `send`; `block_account` (the source) is not the destination, and is not on your own published list of wallets; the destination is the payee | you have no exclusion list to check against (an empty list is a list; no list is not) |
|
|
17
|
+
| `exact_amount` | `amount` equals the quoted tagged amount, as an integer of raw. Not at least: one raw over is a different tag | no quoted amount |
|
|
18
|
+
| `invoice_issued_before_block` | the invoice id the tagged amount was issued for, and its issue time strictly before `local_timestamp` on every node read | no invoice id, no issue time, or a node reports `local_timestamp` 0 or none |
|
|
19
|
+
| `nodes_read` | at least two nodes answered, and they agree on `subtype`, `block_account`, the destination and `amount` | fewer than two answered, or they disagree |
|
|
20
|
+
|
|
21
|
+
If any field is missing, the verdict is `unknown`, not `settled`. If all five were read
|
|
22
|
+
and one contradicts the terms (wrong amount either way, wrong payee, source is the
|
|
23
|
+
destination or is excluded, invoice issued at or after the block, not a send), the
|
|
24
|
+
verdict is `refused`.
|
|
25
|
+
|
|
26
|
+
**`settled` means work may start. It is not buyer acceptance.** Nothing on this page,
|
|
27
|
+
and nothing in `five_field_verdict`, records or implies that the buyer accepted the
|
|
28
|
+
work.
|
|
29
|
+
|
|
30
|
+
## The check: two `curl` calls
|
|
31
|
+
|
|
32
|
+
Replace `<HASH>` with the send block's hash. Read the same block from two nodes run by
|
|
33
|
+
different operators:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
curl -s -A 'my-check/1' -H 'Content-Type: application/json' \
|
|
37
|
+
-d '{"action": "block_info", "json_block": "true", "hash": "<HASH>"}' \
|
|
38
|
+
https://rpc.nano.to
|
|
39
|
+
|
|
40
|
+
curl -s -A 'my-check/1' -H 'Content-Type: application/json' \
|
|
41
|
+
-d '{"action": "block_info", "json_block": "true", "hash": "<HASH>"}' \
|
|
42
|
+
https://node.somenano.com/proxy
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Send both headers: without `Content-Type: application/json` `rpc.nano.to` answers
|
|
46
|
+
`{"error":"Action not provided"}`, and a default User-Agent may get a 403, either of
|
|
47
|
+
which reads like a missing block.
|
|
48
|
+
|
|
49
|
+
What was actually reached, so you do not take a URL on our word: `rpc.nano.to` answered
|
|
50
|
+
`block_info` from where this page was written (2026-10-14). The second URL is named only
|
|
51
|
+
as an example of a public node; that sandbox's network egress refused it
|
|
52
|
+
(`CONNECT tunnel failed, response 403`), as it refused every other public node tried, so
|
|
53
|
+
it was **not** reached and is not vouched for here. Pick your own second node, ideally
|
|
54
|
+
one you know is not a proxy in front of the first: distinct URLs are not proof of
|
|
55
|
+
distinct nodes.
|
|
56
|
+
|
|
57
|
+
## What to compare, by eye
|
|
58
|
+
|
|
59
|
+
Lay the two replies side by side:
|
|
60
|
+
|
|
61
|
+
1. **Both** have `"confirmed": "true"`. Otherwise: `unknown` (not yet, not no).
|
|
62
|
+
2. **Both** name the same `subtype` (`send`; for an older block, `contents.type` is
|
|
63
|
+
`send`), the same `block_account`, the same destination and the same `amount`.
|
|
64
|
+
The destination is the field the hash covers: `contents.link` for a state block
|
|
65
|
+
(64 hex characters, the payee's public key), `contents.destination` for an older
|
|
66
|
+
one. Do not read it from `link_as_account`: that is the node's rendering of `link`,
|
|
67
|
+
and the hash does not cover it. Any difference: `unknown`.
|
|
68
|
+
3. The destination is the payee you quoted: for a state block, `contents.link` is
|
|
69
|
+
character-for-character the payee's public key (from `account_key`, see below; upper
|
|
70
|
+
case), and if a node also shows a `link_as_account` that names any other account,
|
|
71
|
+
that reply is not a read. `block_account` is not the payee and is not on your
|
|
72
|
+
published list. `nano_` and `xrb_` spellings with the same 60 characters after the
|
|
73
|
+
prefix are the same account. For an older send block, `block_account` is the
|
|
74
|
+
node's word alone (the block's contents do not name its account), so it cannot
|
|
75
|
+
clear your published list: with a non-empty list, that field is `unknown`.
|
|
76
|
+
4. `amount` is character-for-character the tagged amount you quoted, in raw. Compare
|
|
77
|
+
digit strings, never floats; `amount_nano` is for reading, not for comparing.
|
|
78
|
+
5. Your invoice's issue time, as unix seconds, is less than **both** nodes'
|
|
79
|
+
`local_timestamp`. That timestamp is each node's own clock when it first saw the
|
|
80
|
+
block, unsigned, and nodes can differ by seconds; use the earlier one.
|
|
81
|
+
6. Write down the two URLs you read. That is `nodes_read`.
|
|
82
|
+
|
|
83
|
+
## The local hash recompute
|
|
84
|
+
|
|
85
|
+
Steps 1 to 6 take each node's word that the `contents` it showed you belong to the hash
|
|
86
|
+
you asked for. Recomputing the hash removes that: a node cannot describe a different
|
|
87
|
+
block under your hash. It needs no interpreter, only coreutils and `bc`.
|
|
88
|
+
|
|
89
|
+
For a state block (`contents.type` is `state`) the hash is blake2b-256 of, in order:
|
|
90
|
+
32 bytes holding the number 6, the account's public key, `previous`, the
|
|
91
|
+
representative's public key, `balance` as 16 bytes, and `link`.
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
PRE=$(printf '%064X' 6)
|
|
95
|
+
ACC=<public key of contents.account> # 64 hex; see below
|
|
96
|
+
PREV=<contents.previous>
|
|
97
|
+
REP=<public key of contents.representative>
|
|
98
|
+
BAL=$(printf '%032s' "$(echo 'obase=16; <contents.balance>' | bc)" | tr ' ' 0)
|
|
99
|
+
LINK=<contents.link>
|
|
100
|
+
printf '%s' "$PRE$ACC$PREV$REP$BAL$LINK" | basenc --base16 -d | b2sum -l 256
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The output must equal `<HASH>` (b2sum prints lower case). A public key comes from an
|
|
104
|
+
address by base32 decoding, or from either node with
|
|
105
|
+
`{"action": "account_key", "account": "nano_..."}`; that answer is pure arithmetic,
|
|
106
|
+
so the two nodes must give the same 64 hex characters. All hex goes in upper case, as
|
|
107
|
+
the nodes send it.
|
|
108
|
+
|
|
109
|
+
For an older send block (`contents.type` is `send`) it is blake2b-256 of `previous`,
|
|
110
|
+
the destination's public key, and `contents.balance` (already 32 hex characters):
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
printf '%s' "<previous><destination key><contents.balance>" | basenc --base16 -d | b2sum -l 256
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Checked against the network, with these exact commands and keys from `account_key` on
|
|
117
|
+
`rpc.nano.to`: the state recipe reproduces
|
|
118
|
+
`023B94B7D27B311666C8636954FE17F1FD2EAA97A8BAC27DE5084FBBD5C6B02C` (the genesis
|
|
119
|
+
account's epoch block) and the send recipe reproduces
|
|
120
|
+
`C7C2000B48DB2DEDD9FDB8583EE73C33897193A18D2870FC94A1D3115EA51C08`. Both replies are
|
|
121
|
+
pinned verbatim in `tests/test_five_fields.py`.
|
|
122
|
+
|
|
123
|
+
What the hash does not cover: `confirmed`, `amount` (a node derives it from the
|
|
124
|
+
previous block's balance), `local_timestamp`, `subtype` (a state send and a state
|
|
125
|
+
receive hash the same fields; the node says which it is), `link_as_account` (the
|
|
126
|
+
node's rendering of `link`; compare `link` itself), and, for an older send block,
|
|
127
|
+
`block_account` - the source, which that block's contents do not name. Those are
|
|
128
|
+
node-asserted, which is why there are two nodes and why they must agree, and why an
|
|
129
|
+
older send's source is never checked against an exclusion list on a node's word.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Check a Nano payment for free: no node, no account, no budget
|
|
2
|
+
|
|
3
|
+
For a seller or agent with no node and no outgoing budget. Reading a block costs nothing: several public
|
|
4
|
+
nodes answer `block_info` with no key (see `FALLBACK-NODES.md`; probed 2026-11-02).
|
|
5
|
+
|
|
6
|
+
## One command, nothing to install
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
curl -s -A 'Mozilla/5.0' -H 'Content-Type: application/json' \
|
|
10
|
+
-d '{"action":"block_info","json_block":"true","hash":"B749B757EE750FC9AEA72F33CB429EACCD2ABEC9F2CCF59BF17AFAC304C9A58F"}' \
|
|
11
|
+
https://rpc.nano.to
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Read three fields: `confirmed` is `"true"`, `contents.link_as_account` is your address, `amount` is exactly the raw
|
|
15
|
+
amount you quoted (1 XNO = 10**30 raw; compare as integer strings).
|
|
16
|
+
|
|
17
|
+
## The same check as a tool (stdlib only)
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
git clone https://github.com/dhyabi2/nano-settlement-verify && cd nano-settlement-verify
|
|
21
|
+
python3 free_verify_fetch.py --quote quote.json # quote.json: quote_id, pay_to, amount_raw, block_hash
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Offline against a reply you already hold: `python3 free_verify.py --quote quote.json --block reply.json`.
|
|
25
|
+
|
|
26
|
+
| verdict | exit | meaning |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `settled` | 0 | confirmed send to `pay_to` for exactly `amount_raw` |
|
|
29
|
+
| `unknown` | 2 | not found, not confirmed yet, node error, no block named |
|
|
30
|
+
| `mismatch` | 3 | confirmed, but wrong amount, wrong payee, or not a send |
|
|
31
|
+
|
|
32
|
+
There is no `unpaid` verdict and there cannot be one: a read that finds nothing means "not yet", and treating it as
|
|
33
|
+
unpaid is how a retry pays twice. If you need "unpaid", take it from your own quote expiry. A balance check cannot
|
|
34
|
+
answer "was this paid" and `check_from_balance` refuses to try.
|
|
35
|
+
|
|
36
|
+
Every verdict carries `cost_usd: 0.0`; `cost_report` computes "N settlement checks, 0.0 USD outgoing, no node run, no
|
|
37
|
+
account required" from the verdicts instead of asserting it.
|
|
38
|
+
|
|
39
|
+
## Host it yourself (optional)
|
|
40
|
+
|
|
41
|
+
`python3 free_verify_fetch.py --serve 8080` serves `GET /verify?pay_to=&amount_raw=&block=` on 127.0.0.1 with a
|
|
42
|
+
30-checks-a-minute limit per address and no key. Put your own TLS in front. No hosted instance is run by us.
|
|
43
|
+
|
|
44
|
+
## What this does not do
|
|
45
|
+
|
|
46
|
+
One node's word is still one node's word: this tool trusts the reply it fetches. To not trust it, recompute the
|
|
47
|
+
block hash (`TWO-NODE-CHECK.md`) and compare two nodes (`nano_settlement_verify/two_node.py`). It reads only; it never sends, signs
|
|
48
|
+
or holds a key.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Funding provenance: who funded the payer?
|
|
2
|
+
|
|
3
|
+
A payment that arrives is not necessarily demand. If the payer's money came from the payee, from a
|
|
4
|
+
sponsor, or from a dispenser that hands the same amount to many accounts, the payment is subsidised use.
|
|
5
|
+
This page is the check by hand; `nano_settlement_verify/funding.py` reproduces it and is tested against the same
|
|
6
|
+
recipe. Reads only. One node is enough (two make it stronger).
|
|
7
|
+
|
|
8
|
+
## The recipe: two kinds of call
|
|
9
|
+
|
|
10
|
+
1. Read the payment block. If you were given the payee's **receive** block, its `contents.link` is the
|
|
11
|
+
send it pockets: read that one. **Payment time is the payer's send block's `local_timestamp`, never
|
|
12
|
+
the receive's.** A receive is stamped when the payee pocketed, which can be days later; reading
|
|
13
|
+
payment times off receive blocks makes a batching payee look like a scripted payer.
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
curl -s -A 'Mozilla/5.0' -H 'Content-Type: application/json' -d '{"action":"block_info","json_block":"true","hash":"<SEND>"}' https://rpc.nano.to
|
|
17
|
+
```
|
|
18
|
+
Take `block_account` (the payer), `contents.link_as_account` (the payee), `contents.previous`, `local_timestamp`.
|
|
19
|
+
|
|
20
|
+
2. Read the payer's history from the block before the send, and keep the `receive` entries inside your
|
|
21
|
+
window (default 720 hours) before the payment. `account` in each entry is who funded it.
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
curl -s -A 'Mozilla/5.0' -H 'Content-Type: application/json' -d '{"action":"account_history","account":"<PAYER>","count":"100","head":"<PREVIOUS>"}' https://rpc.nano.to
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
3. For each distinct funder, read its own history. A funder that sent the **same amount to ten or more
|
|
28
|
+
distinct accounts** is a dispenser. This is found from the ledger; no flag can switch it off.
|
|
29
|
+
|
|
30
|
+
## Labels
|
|
31
|
+
|
|
32
|
+
| label | when |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `dispenser_funded` | any funder in the window is a dispenser (checked first, never suppressed) |
|
|
35
|
+
| `self_funded` | a funder is the payee, or an account you pass with `--self` |
|
|
36
|
+
| `sponsor_funded` | a funder is an account you pass with `--sponsor` (a label you chose; the output names the flag, drop it and re-run) |
|
|
37
|
+
| `unsubsidised` | receives were read for the whole window and none is flagged |
|
|
38
|
+
| `unknown` | no receive in the window, history not read back to the window start, nodes disagree, payment unconfirmed or not a send, payment time unreadable |
|
|
39
|
+
|
|
40
|
+
The label says whether a flagged or dispenser funder sent anything in the window, not how much. Each
|
|
41
|
+
funder row carries `received_raw` and `share_of_window_receives_ppm` so you can see a tiny starter
|
|
42
|
+
beside a large unflagged receive and judge for yourself. Dispenser detection reads at most the last 500
|
|
43
|
+
blocks of a funder; a funder with more history is judged on that.
|
|
44
|
+
|
|
45
|
+
## Worked example (public, read 2026-11-02 from three nodes that agreed)
|
|
46
|
+
|
|
47
|
+
Payment `B749B757EE750FC9AEA72F33CB429EACCD2ABEC9F2CCF59BF17AFAC304C9A58F`, payer
|
|
48
|
+
`nano_3m8cz87zwxb1y16ob4bzp1eyek78qaig8ktohk7d45b18sh6u9exbowbnekr`, payment time 1790150110.
|
|
49
|
+
The payer's receives before it:
|
|
50
|
+
|
|
51
|
+
| funder | received | share | label |
|
|
52
|
+
|---|---|---|---|
|
|
53
|
+
| `nano_1banexkcfuieufzxksfrxqf6xy8e57ry1zdtq9yn7jntzhpwu4pg4hajojmq` | 6.275603217158176 XNO | 999,998 ppm | unsubsidised (2 distinct recipients seen) |
|
|
54
|
+
| `nano_1434j1n4sin4cefs5njibag4tsmo596fmg3s6bdogtod3ndmdfez5yuebrh9` | 0.00001 XNO (`7085E9C0...`) | 1 ppm | dispenser (same 0.00001 to 12 distinct accounts) |
|
|
55
|
+
|
|
56
|
+
Verdict `dispenser_funded`, and the decisive receive is the 0.00001 XNO starter from
|
|
57
|
+
`nano_1434j1n4...`, which is the account Unstuck sends its first transactions from. So the payer of
|
|
58
|
+
the example block was seeded by us, with one part per million of what it later held. Both facts are in
|
|
59
|
+
the table; the label follows the rule, the share lets you weigh it. Run it:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
python3 -m nano_settlement_verify.funding --block B749B757EE750FC9AEA72F33CB429EACCD2ABEC9F2CCF59BF17AFAC304C9A58F --json
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Exit codes: 0 unsubsidised, 3 any subsidy label, 2 unknown.
|
|
66
|
+
|
|
67
|
+
## What this does not prove
|
|
68
|
+
|
|
69
|
+
A payer funded by a dispenser may still have bought something it wanted; a payer with no flagged funder
|
|
70
|
+
may still be the payee's friend. Funding is evidence about subsidy, not about identity or intent.
|
|
@@ -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.
|