Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ the credit. Fine at 0.001 NANO per call; not a design for anything larger.
| GET | `/v1/x402` | no | x402 payment requirements (scheme exact, nano:mainnet) |
| GET | `/.well-known/x402` | no | discovery manifest for seller directories (agent402.tools, agent-tools.cloud, nohumans.directory): resources with their x402 requirements, the facilitator, the free routes |
| GET | `/v1/verify?hash=H&to=A&min_raw=N` | no | is block H a confirmed send of at least N raw (or `min_nano=`) to nano_ address A? `{found, ok, reason, confirmed, subtype, from, to, amount_raw, amount_nano, min_raw, any_amount}`; 404 if the node has not seen H. without `min_raw` or `min_nano` the answer is `ok:false` with the reason, since 2026-09-29 (the amount is not checked, so `ok` cannot say paid; `found` still answers); `any=1` instead asks only whether H is a confirmed send to A, and the answer then carries `min_raw: null`, `any_amount: true`. Without `to` the answer is likewise `ok:false` with the reason, since 2026-09-30 (the destination is not checked, so `ok` cannot say paid to you); `any_to=1` asks only whether H is a confirmed send to anyone, and the answer carries `expected_to: null`, `any_to: true`. So `ok:true` always needs both sides, an amount side (`min_raw`, `min_nano` or `any=1`) and a recipient side (`to=` or `any_to=1`): `?hash=H&min_raw=N&to=A` is the normal check, `?hash=H&any=1&to=A` is any confirmed send to A, `?hash=H&any=1&any_to=1` is any confirmed send to anyone; a call with only one side answers `ok:false` and the reason names the missing side (a seller that passes only `any_to=1` gets `ok:false`, the safe answer). `min_raw` and `min_nano` are at most 2^128-1 raw (340282366920938463463374607431768211455), else 400, since 2026-10-01. For sellers that take Nano and run no node. Stateless: it answers `ok` for the same hash forever and a block hash is public on the chain, so a seller keeps its own list of hashes already delivered for and refuses a repeat. 60 per minute per IP |
| GET | `/v1/receivable?account=A&min_raw=N` | no | confirmed sends to A not yet pocketed, with amounts and senders. Poll this for a per-order address instead of asking the payer for a hash. `min_raw` (or `min_nano`) is at most 2^128-1 raw, else 400, since 2026-10-01 (before that the node's refusal was served as 502). 60 per minute per IP |
| GET | `/v1/receivable?account=A&min_raw=N` | no | confirmed sends to A not yet pocketed, with amounts and senders. Poll this for a per-order address instead of asking the payer for a hash. `min_raw` (or `min_nano`) is at most 2^128-1 raw, else 400, since 2026-10-01 (before that the node's refusal was served as 502). At most 100 hashes per call (the node's own bound): the answer carries `truncated: true` and a `next` line when it hits that, so an account with more unpocketed sends polls again after pocketing these rather than reading 100 as the whole (since 2026-10-23). 60 per minute per IP |
| GET | `/v1/account_info?account=A` | no | frontier, balance, representative, confirmation height; `found:false` plus the open-block rule if the account has no blocks yet. 60 per minute per IP |
| GET | `/v1/requests?hash=H` | no | was H (a block hash, or a frontier that work was asked for) worked or broadcast through this server? `{found, entries}` from a per-call log kept since 2026-09-16, no raw IPs. For checking a report that says "I did not use pursekeeper.dev". 60 per minute per IP |
| GET/POST | `https://facilitator.pursekeeper.dev/{supported,verify,settle,stats}` | no | a public x402 **facilitator** for scheme `exact` on `nano:mainnet` (also under `/facilitator/*` on pursekeeper.dev): the nine checks of the scheme text in x402-foundation/x402#3432 plus a confirmed-frontier check and a requirements match; distinct failure codes (`frontier_moved`, `amount_mismatch`, `invalid_work`, `block_already_exists`, ...); a `/settle` retried with the same block after `confirmation_timeout` or a lost reply is answered from the chain for 24 h (no second broadcast, `success` once confirmed, after which a further retry is a replay refused with the hash named), and a `process` reply lost after the node took the block is settled from the node's view. Holds no funds, needs no key. Docs at its `/`; code in `facilitator.js`. 120 verify / 60 settle per minute per IP |
Expand Down
11 changes: 10 additions & 1 deletion server.js
Original file line number Diff line number Diff line change
Expand Up @@ -756,6 +756,9 @@ function overFreeLimit(req, map, limit, res) {
return false;
}
const MAX_RAW = 2n ** 128n - 1n; // a Nano balance is a u128; the node answers "Bad threshold number" above it
// How many receivable hashes one /v1/receivable call asks the node for. A node answers at most this many per call; the answer
// says so when it hits the bound (llmrt, 2026-10-23).
const RECEIVABLE_MAX = Number(process.env.RECEIVABLE_MAX || 100);
function minRawOf(u) {
const raw = u.searchParams.get('min_raw'), n = u.searchParams.get('min_nano');
// Above 2^128-1 the node refused the threshold and the refusal was served as 502 (pyfile-toolkit, item 5, 2026-09-30);
Expand Down Expand Up @@ -811,11 +814,17 @@ async function receivable(req, res, u) {
const account = u.searchParams.get('account') || '';
if (!nanocurrency.checkAddress(account)) return send(res, 400, { error: 'account must be a nano_ address' });
let minRaw; try { minRaw = minRawOf(u); } catch (e) { return send(res, 400, { error: e.message }); }
const r = await rpc({ action: 'receivable', account, count: '100', source: 'true', include_only_confirmed: 'true', threshold: (minRaw !== null && minRaw > 0n ? minRaw : 1n).toString() });
const r = await rpc({ action: 'receivable', account, count: String(RECEIVABLE_MAX), source: 'true', include_only_confirmed: 'true', threshold: (minRaw !== null && minRaw > 0n ? minRaw : 1n).toString() });
if (r.error) return send(res, 502, { error: 'node: ' + r.error });
const blocks = Object.entries(r.blocks && typeof r.blocks === 'object' ? r.blocks : {}).map(([hash, v]) => ({ hash, amount_raw: String(v.amount), amount_nano: nano(v.amount), from: v.source }));
const total = blocks.reduce((a, b) => a + BigInt(b.amount_raw), 0n);
return send(res, 200, { account, count: blocks.length, total_raw: total.toString(), total_nano: nano(total), blocks, confirmed_only: true,
// A node answers at most `count` receivable hashes per call, and until 2026-10-23 the count was fixed at 100 with no
// word in the answer or the README: a seller with more than 100 unpocketed sends read 100 of them as if that were all, and
// the rest were invisible to the poll that is meant to find every payment (llmrt, 2026-10-23). `truncated` is the node's own
// signal for that, and `next` says how to read the rest.
truncated: blocks.length >= RECEIVABLE_MAX,
...(blocks.length >= RECEIVABLE_MAX ? { next: 'the node answered its maximum of ' + RECEIVABLE_MAX + ' receivable hashes; pocket these, then poll again for the rest' } : {}),
note: 'confirmed sends to this account that have not been pocketed with a receive block; each is final and spendable once received. Pocketing needs a signed receive block and work (POST /v1/work).', checked_at: new Date().toISOString(), node: 'pursekeeper.dev' });
}

Expand Down
24 changes: 24 additions & 0 deletions test/free-limit.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,3 +69,27 @@ test('each route stops at its own 60, and the neighbour is unaffected', async ()
assert.equal((await get('/v1/verify?hash=' + H + '&any=1', ip)).status, 200);
assert.ok(rpcCalls > 0, 'the mocked node was reached, so the 200s are real answers');
});

// llmrt, 2026-10-23: /v1/receivable asked the node for a fixed 100 hashes and said nothing about the bound, so an account
// with more than 100 unpocketed sends read 100 of them as if that were the whole list. The answer now names the truncation and
// says how to read the rest.
test('/v1/receivable says when the node bound cut the list short', async () => {
const ip = '198.51.100.16';
const many = {};
for (let i = 0; i < 100; i++) many[i.toString(16).toUpperCase().padStart(2, '0').repeat(32)] = { amount: '1000000000000000000000000000', source: A };
const savedFetch = globalThis.fetch;
globalThis.fetch = async () => ({ ok: true, json: async () => ({ blocks: many }) });
try {
const full = await get('/v1/receivable?account=' + A, ip);
assert.equal(full.status, 200);
assert.equal(full.body.count, 100);
assert.equal(full.body.truncated, true, 'a full page must say it may not be the whole list');
assert.match(String(full.body.next), /poll again/);
const few = {}; few['AB'.repeat(32)] = { amount: '1000000000000000000000000000', source: A };
globalThis.fetch = async () => ({ ok: true, json: async () => ({ blocks: few }) });
const part = await get('/v1/receivable?account=' + A, ip);
assert.equal(part.status, 200);
assert.equal(part.body.truncated, false);
assert.equal(part.body.next, undefined);
} finally { globalThis.fetch = savedFetch; }
});