Skip to content

feat(x402): add a nano:mainnet offer family verified by block_info - #25

Open
dhyabi2 wants to merge 1 commit into
devlab-group:masterfrom
dhyabi2:feat/x402-nano
Open

dhyabi2 wants to merge 1 commit into
devlab-group:masterfrom
dhyabi2:feat/x402-nano

Conversation

@dhyabi2

@dhyabi2 dhyabi2 commented Oct 14, 2026

Copy link
Copy Markdown

NICE-TO-HAVE, experimental. An optional offer family; EVM, Solana and NEAR offers are unchanged.

Problem

Nano (XNO) is feeless and fast, which suits per-call agent payments. Today findX402Network('nano:mainnet') returns undefined, and config load refuses a Nano offer.

Change

  • nano family and a nano:mainnet profile: native XNO, 30 decimals, asset: XNO.
  • nano-address.ts (no SDK) checks nano_ and xrb_ addresses, including the BLAKE2b-40 checksum. Node's crypto has only 64-byte BLAKE2b, so a short RFC 7693 one is inlined; no new dependency.
  • nano.ts, loaded lazily like near.ts. The payload is { blockHash }. Verify calls block_info (json_block) on the offer's rpcUrl and requires a confirmed state send with link_as_account == payTo and amount >= the offer's raw amount. The replay key is sha256 of the network and the hash. Settle re-reads the block under the replay reservation; nothing is sent. No facilitator call, no key, no broadcast.
  • If the node is down or its answer is unreadable, verify and settle throw PAYMENT_PROVIDER_UNAVAILABLE. Settle also sets settlementNotSubmitted, so the attempt is released for a retry.
  • Health: version must report network: live.
  • The gateway has no XNO rate. A resource with a Nano offer must be priced in XNO and list only Nano offers; config load and createRequirement refuse anything else. Use a resource's own x402.accepts; others keep USDC.
  • Docs: config section, x402 paragraph, experimental matrix rows. Contract surface unchanged.

Tests

Mocked RPC or stubbed fetch only; the facilitator mock is asserted never called.

  • nano.test.ts: BLAKE2b vs node's blake2b512; genesis address round-trip; xrb_ alias; bad checksum and malformed addresses; payload and verifier refusals.
  • provider-nano.test.ts negative cases: no payment block, malformed hash, wrong amount, wrong recipient, wrong network, wrong asset, unconfirmed block, receive block, node down. Also a USD price refused.
  • integration/x402-nano.test.ts: config cases, and a gateway run of 402, then 200, then the same hash refused with PAYMENT_REPLAYED. The backend is called once.

Against master's sources, these tests fail (40 failures: "nano:mainnet is not a known network").

What I ran (Node 22.22.0)

  • npm ci && npm test: before, 129 files, 2665 passed / 35 skipped. After, 132 files, 2726 passed / 35 skipped.
  • npm run check:contract passes (88 symbols, unchanged); npm run lint and npm run typecheck are clean.
  • check:metadata, build, test:cli:dist and the packaging test pass.
  • npm run test:coverage: without Foundry, the src/payments/** branch threshold fails on master (87.06%) and on this branch (87.45%).
  • Not run: test:e2e, Docker, a live Nano node.

Limits

  • Not yet settled against a live node.
  • The buyer pays first, and sends are public. Anyone could present an unclaimed send to payTo, so use a payTo that receives only gateway payments.
  • An overpayment is accepted; amountBaseUnits records what was sent.
  • Mainnet only. A Nano offer cannot share a list with USD-priced tokens.
  • The facilitator block and mainnet guardrails still apply, though Nano never calls the facilitator.

Add an experimental x402 network family for Nano beside EVM, Solana and
NEAR. The buyer publishes a send block of native XNO to payTo and presents
its hash; the gateway reads the block from the offer's Nano node with
block_info and requires a confirmed state send to payTo of at least the
offered raw amount. No facilitator is called, no key is held and nothing
is broadcast. The block hash is the replay key, settle reads the block
again under the replay reservation, and a node that does not answer is
PAYMENT_PROVIDER_UNAVAILABLE.

Addresses are checked with their BLAKE2b checksum (nano_ and legacy xrb_).
XNO has no USD rate in the gateway, so a resource with a Nano offer must
be priced in XNO and list only Nano offers.
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