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.
Files changed (94) hide show
  1. nano_settlement_verify-2.0.0/EXTERNAL-COUNTERPARTIES.md +44 -0
  2. nano_settlement_verify-2.0.0/FALLBACK-NODES.md +26 -0
  3. nano_settlement_verify-2.0.0/FIVE_FIELDS.md +129 -0
  4. nano_settlement_verify-2.0.0/FREE-VERIFY.md +48 -0
  5. nano_settlement_verify-2.0.0/FUNDING-PROVENANCE.md +70 -0
  6. nano_settlement_verify-2.0.0/LICENSE +21 -0
  7. nano_settlement_verify-2.0.0/MANIFEST.in +6 -0
  8. nano_settlement_verify-2.0.0/PKG-INFO +1166 -0
  9. nano_settlement_verify-2.0.0/README.md +1154 -0
  10. nano_settlement_verify-2.0.0/RECOUNT-YOUR-ADDRESS.md +20 -0
  11. nano_settlement_verify-2.0.0/STATED-PAYER-TEST.md +103 -0
  12. nano_settlement_verify-2.0.0/TWO-NODE-CHECK.md +111 -0
  13. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-09-25.md +99 -0
  14. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-01.md +69 -0
  15. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-02.md +135 -0
  16. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-04.md +136 -0
  17. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-05.md +81 -0
  18. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-08.md +107 -0
  19. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-10.md +163 -0
  20. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-11.md +482 -0
  21. nano_settlement_verify-2.0.0/audits/nano-settlement-verify-2026-10-13.md +239 -0
  22. nano_settlement_verify-2.0.0/e2e_check.py +140 -0
  23. nano_settlement_verify-2.0.0/e2e_payers_check.py +226 -0
  24. nano_settlement_verify-2.0.0/e2e_quorum_check.py +217 -0
  25. nano_settlement_verify-2.0.0/free_surfaces.json +14 -0
  26. nano_settlement_verify-2.0.0/free_verify.py +165 -0
  27. nano_settlement_verify-2.0.0/free_verify_fetch.py +131 -0
  28. nano_settlement_verify-2.0.0/nano_settlement_verify/__init__.py +607 -0
  29. nano_settlement_verify-2.0.0/nano_settlement_verify/claim.py +466 -0
  30. nano_settlement_verify-2.0.0/nano_settlement_verify/five_fields.py +444 -0
  31. nano_settlement_verify-2.0.0/nano_settlement_verify/funding.py +213 -0
  32. nano_settlement_verify-2.0.0/nano_settlement_verify/independence.py +257 -0
  33. nano_settlement_verify-2.0.0/nano_settlement_verify/links/__init__.py +0 -0
  34. nano_settlement_verify-2.0.0/nano_settlement_verify/links/public_check.py +177 -0
  35. nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/NODES.json +22 -0
  36. nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/__init__.py +43 -0
  37. nano_settlement_verify-2.0.0/nano_settlement_verify/node_set/probe.py +127 -0
  38. nano_settlement_verify-2.0.0/nano_settlement_verify/offline.py +225 -0
  39. nano_settlement_verify-2.0.0/nano_settlement_verify/payers.py +887 -0
  40. nano_settlement_verify-2.0.0/nano_settlement_verify/period_counts.py +210 -0
  41. nano_settlement_verify-2.0.0/nano_settlement_verify/quorum.py +2076 -0
  42. nano_settlement_verify-2.0.0/nano_settlement_verify/recount.py +249 -0
  43. nano_settlement_verify-2.0.0/nano_settlement_verify/stated_payer_test.py +699 -0
  44. nano_settlement_verify-2.0.0/nano_settlement_verify/terms.py +235 -0
  45. nano_settlement_verify-2.0.0/nano_settlement_verify/two_node.py +77 -0
  46. nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/PKG-INFO +1166 -0
  47. nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/SOURCES.txt +92 -0
  48. nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/dependency_links.txt +1 -0
  49. nano_settlement_verify-2.0.0/nano_settlement_verify.egg-info/top_level.txt +1 -0
  50. nano_settlement_verify-2.0.0/pyproject.toml +27 -0
  51. nano_settlement_verify-2.0.0/setup.cfg +4 -0
  52. nano_settlement_verify-2.0.0/skills/nano-settlement-verify/LICENSE +21 -0
  53. nano_settlement_verify-2.0.0/skills/nano-settlement-verify/SKILL.md +134 -0
  54. nano_settlement_verify-2.0.0/skills/nano-settlement-verify/nano_settlement_verify.py +607 -0
  55. nano_settlement_verify-2.0.0/skills/nano-settlement-verify/probe_gate.py +550 -0
  56. nano_settlement_verify-2.0.0/skills/nano-settlement-verify/verify_cli.py +595 -0
  57. nano_settlement_verify-2.0.0/tests/fixtures/block_37402FF0.json +1 -0
  58. nano_settlement_verify-2.0.0/tests/fixtures/block_B749B757.json +1 -0
  59. nano_settlement_verify-2.0.0/tests/fixtures/observations/asked_no_return.json +1 -0
  60. nano_settlement_verify-2.0.0/tests/fixtures/observations/asked_returned.json +1 -0
  61. nano_settlement_verify-2.0.0/tests/fixtures/observations/not_asked.json +1 -0
  62. nano_settlement_verify-2.0.0/tests/fixtures/receipt_main_schema3.json +1 -0
  63. nano_settlement_verify-2.0.0/tests/test_ask_order.py +222 -0
  64. nano_settlement_verify-2.0.0/tests/test_claim.py +534 -0
  65. nano_settlement_verify-2.0.0/tests/test_cli_fallback.py +319 -0
  66. nano_settlement_verify-2.0.0/tests/test_clock_and_record_edges.py +247 -0
  67. nano_settlement_verify-2.0.0/tests/test_expiry.py +430 -0
  68. nano_settlement_verify-2.0.0/tests/test_fallback_nodes_doc.py +30 -0
  69. nano_settlement_verify-2.0.0/tests/test_five_fields.py +590 -0
  70. nano_settlement_verify-2.0.0/tests/test_free_verify.py +206 -0
  71. nano_settlement_verify-2.0.0/tests/test_funding.py +190 -0
  72. nano_settlement_verify-2.0.0/tests/test_independence.py +230 -0
  73. nano_settlement_verify-2.0.0/tests/test_late_landed_doc.py +56 -0
  74. nano_settlement_verify-2.0.0/tests/test_nano_offline.py +207 -0
  75. nano_settlement_verify-2.0.0/tests/test_node_set.py +127 -0
  76. nano_settlement_verify-2.0.0/tests/test_observation_fixtures.py +124 -0
  77. nano_settlement_verify-2.0.0/tests/test_package_layout.py +51 -0
  78. nano_settlement_verify-2.0.0/tests/test_payers.py +1003 -0
  79. nano_settlement_verify-2.0.0/tests/test_period_counts.py +124 -0
  80. nano_settlement_verify-2.0.0/tests/test_probe_gate.py +1028 -0
  81. nano_settlement_verify-2.0.0/tests/test_public_link_check.py +122 -0
  82. nano_settlement_verify-2.0.0/tests/test_quorum.py +2312 -0
  83. nano_settlement_verify-2.0.0/tests/test_readme_raw_check.py +51 -0
  84. nano_settlement_verify-2.0.0/tests/test_readme_test_count.py +50 -0
  85. nano_settlement_verify-2.0.0/tests/test_recount.py +169 -0
  86. nano_settlement_verify-2.0.0/tests/test_skill_bundle.py +1686 -0
  87. nano_settlement_verify-2.0.0/tests/test_stated_payer_test.py +813 -0
  88. nano_settlement_verify-2.0.0/tests/test_terms.py +310 -0
  89. nano_settlement_verify-2.0.0/tests/test_two_node.py +133 -0
  90. nano_settlement_verify-2.0.0/tests/test_user_agent.py +37 -0
  91. nano_settlement_verify-2.0.0/tests/test_verify.py +912 -0
  92. nano_settlement_verify-2.0.0/web/recount-core.js +33 -0
  93. nano_settlement_verify-2.0.0/web/recount.html +56 -0
  94. 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.
@@ -0,0 +1,6 @@
1
+ include LICENSE *.md free_surfaces.json e2e_*.py free_verify*.py
2
+ graft tests
3
+ graft skills
4
+ graft web
5
+ graft audits
6
+ global-exclude *.py[cod]