Skip to content

wrapper/x402: add a self-hosted Nano facilitator - #5065

Open
dhyabi2 wants to merge 1 commit into
micro:masterfrom
dhyabi2:feat/nano-exact
Open

dhyabi2 wants to merge 1 commit into
micro:masterfrom
dhyabi2:feat/nano-exact

Conversation

@dhyabi2

@dhyabi2 dhyabi2 commented Nov 19, 2026

Copy link
Copy Markdown

XNO is already merged into 14 other projects' code and 26 directories: https://github.com/dhyabi2/the-unowned-rail/blob/main/docs/MERGED-UPSTREAM.md

This adds wrapper/x402/nano, a self-hosted facilitator that accepts nano:mainnet payments with scheme exact. It uses only the standard library, needs no key or seed, and verifies a payment by reading one block from a node RPC URL the operator configures. It is opt-in: nothing changes unless a service sets it as Config.Facilitator.

Changes to the existing wrapper are small: an optional Challenger interface lets a facilitator add per-challenge data to the 402 body (the six writeChallenge calls go through challengeFor; facilitators that do not implement it behave exactly as before), and NormalizeNetwork maps nano. A short section is added to docs/guides/x402-payments.md.

Binding and replay: each 402 carries a fresh order id and a representative account derived from (order id, payTo, amount), and a block is accepted only if it is a confirmed send that pays payTo the exact amount in raw (1 XNO = 10^30 raw, derived, never restated) and carries that representative, so a payment for one request cannot be presented for another. The block hash is claimed in an append-only, file-locked and fsynced claims file before the request is served, so a block pays for one order once, across restarts.

Testing: the new tests (21, plus 7 subtests) pass in isolation with go test -count=1 -race ./wrapper/x402/... (Go 1.24, in a scratch module holding only wrapper/x402, since this sandbox has no Go 1.26), alongside the 23 existing wrapper/x402 tests; gofmt -l and go vet (linux and windows) are clean. I did not run the full suite locally; this project's CI on this pull request is the check for the integration, and I will fix what it reports.

wrapper/x402/nano verifies nano:mainnet payments with scheme exact
against a node RPC the operator configures. Standard library only, no
key or seed, off unless set as Config.Facilitator.

Each 402 carries a fresh order id and a representative account that
commits to (order id, payTo, amount); a block must be confirmed, pay
the exact amount and carry that commitment. It is claimed in an
append-only, locked claims file before the request is served, so a
block pays for one order once, across restarts.

The wrapper gains an optional Challenger interface so a facilitator can
add per-challenge data to the 402 body; facilitators that do not
implement it behave as before. NormalizeNetwork maps "nano".

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant