Skip to content

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

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

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".

@asim asim left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution. I reviewed the implementation and ran the x402 package tests with race detection; those pass. Additional local checks reproduced the client amount-limit and settlement-requirements issues noted inline. The existing tests do not cover these cases. Repository CI is still awaiting approval, so it has not validated the integration.

There is also a scope and maintenance concern. This adds roughly 1,770 lines, including a custom BLAKE2b implementation and a persistent claim store with platform-specific locking. Go Micro already depends on golang.org/x/crypto; maintaining another cryptographic implementation solely to avoid dependencies in this package is unnecessary.

My recommendation is to maintain the Nano facilitator in a separate integration package using the existing Facilitator/Settler interfaces. If a generic challenge-extension interface is needed in core, that can be proposed separately with focused tests. Adoption in other projects does not by itself establish the fit for this framework. I would not merge this implementation into core as submitted.

```go
claims, err := nano.OpenFileClaimStore("/var/lib/myservice/nano-claims")
fac, err := nano.NewFacilitator("https://node.example/rpc", "nano_1...", claims)
price, err := nano.RawFromXNO("0.001") // 1 XNO = 10^30 raw

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documented 0.001 XNO price becomes 1000000000000000000000000000 raw units (10^27). The existing x402.Client.Do parses MaxAmountRequired with strconv.ParseInt(..., 64), so it rejects this challenge before invoking Payer, even with Budget == 0. I reproduced this against the middleware using the PR's gateway fixture. Please cover the real client-to-middleware path and resolve or explicitly scope this incompatibility; the current tests submit payment headers directly and miss it.

// Settle implements x402.Settler. A confirmed Nano send is already final, so
// settlement only hands back the block hash of a payment this facilitator
// verified and has not settled yet; anything else is refused.
func (f *Facilitator) Settle(ctx context.Context, payment string, req x402.Requirements) (x402.Result, error) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Settle ignores req entirely, and the verified map retains only block hash -> order ID. I reproduced a successful Verify followed by Settle with a different network, recipient and amount; Settle still returned Valid: true. The standard middleware currently passes the same requirements, so this is not a demonstrated bypass of that middleware, but the exported Settler implementation accepts mismatched requirements. Retain and validate the relevant verified requirements before consuming the entry, and add a regression test.

@dhyabi2

dhyabi2 commented Nov 19, 2026

Copy link
Copy Markdown
Author

Thanks for running it and for the exact reproductions - you are right on both. The documented 0.001 XNO is 10^27 raw, which x402.Client.Do rejects as a 64-bit MaxAmountRequired before Payer is called, and the tests missed it because they post payment headers straight to the middleware. And Settle should keep the verified network, recipient and amount and check req against them before it consumes the entry.

I agree this does not belong in core as submitted, so I am closing it. The facilitator will move to a separate integration package on the existing Facilitator and Settler interfaces, using golang.org/x/crypto/blake2b instead of its own BLAKE2b, with both cases as regression tests through the real client-to-middleware path. If the amount width ever needs a core change, that would be its own small proposal with focused tests.

@dhyabi2 dhyabi2 closed this Nov 19, 2026

asim commented Nov 19, 2026

Copy link
Copy Markdown
Member

Thanks for acknowledging the findings and moving this into a separate integration package. That is the right direction for vendor- and network-specific integrations.

We're adding an Integrations page and a submission path in #5068. Once your external package is ready, you're welcome to open an integration issue or submit a listing PR with the repository, maintainer, license, supported Go Micro versions, working example and integration tests. Community listings are free.

We're also introducing optional sponsored placement, clearly labelled as Sponsored, to help fund framework maintenance. Integration development or maintenance can be scoped separately. Neither sponsorship nor payment guarantees acceptance into core, endorsement, or maintenance by Micro, and sponsorship is not required to contribute or request a community listing.

For this package, please include regression coverage for the amount-width and settlement-requirements issues discussed above. Any generic core changes needed to support it can be considered in separate, focused PRs.

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.

2 participants