rfc: x402 protocol support for Hathor Network by andreabadesso · Pull Request #109 · HathorNetwork/rfcs

andreabadesso · 2026-04-02T12:47:30Z

Summary

Design specification for adding x402 payment protocol support to Hathor Network
Uses nano contract escrow as the payment mechanism — trustless, zero double-spend risk
Facilitator built as a hathor-wallet-headless plugin (not a new service)
Client SDK (@hathor/x402-client) and server middleware (@hathor/x402-server) for programmatic integration
Targets AI agents and automated clients paying for API access with HTR

Rendered

Test plan

Review blueprint design against nano contract constraints
Validate protocol message formats against x402 spec
Review facilitator plugin architecture against headless plugin system
Review security considerations
Discuss open questions

🤖 Generated with Claude Code

Add design specification for integrating the x402 payment protocol with Hathor using nano contract escrow. Covers architecture, blueprint design, facilitator plugin, client SDK, and server middleware. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Server can accept multiple tokens via multiple accepts entries - Renamed tokenUid to asset to match x402 spec - Added example showing HTR + custom token acceptance - Clarified token-agnostic nature of the escrow blueprint Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add two new RFC documents for the x402 implementation: - 0002-x402-client-sdk.md: Design for @hathor/x402-client npm package. A fetch() wrapper that transparently handles 402 -> escrow -> retry. Supports headless wallet and wallet-lib backends, multi-token selection, amount limits, and payment callbacks. - 0003-x402-server-middleware.md: Design for @hathor/x402-server npm package. Express/Fastify/Hono middleware that gates routes with x402 payments. Declarative route pricing, multi-token support, async settlement, facilitator auto-discovery, and dynamic pricing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

andreabadesso · 2026-04-02T13:37:35Z

Added: SDK Design RFCs

Two new RFC documents added to the x402 project:

0002-x402-client-sdk.md — `@hathor/x402-client`

A fetch() wrapper that transparently handles 402 → escrow → retry. Key design decisions:

Two wallet backends: hathor-wallet-headless (for agents/servers) and @hathor/wallet-lib (for lightweight Node.js apps)
Token preference: configurable order for multi-token payment selection
Safety limits: maxAmountPerRequest prevents runaway spending
Payment callbacks: onPayment / onPaymentError for logging and budget tracking
Low-level API: payForResource() for developers who want manual control

0003-x402-server-middleware.md — `@hathor/x402-server`

Express/Fastify/Hono middleware that gates routes with x402 payments:

Declarative route pricing: 'GET /weather': { amount: '100', asset: '00' }
Multi-token per route: accept HTR and/or stablecoins
Facilitator auto-discovery: GET /x402/info endpoint for auto-configuration
Async settlement: don't block the response (configurable)
Dynamic pricing: price function receives the request object
Free tier: built-in rate limiting before payment gate kicks in

Both designs are informed by building the x402-poc end-to-end.

Add the three x402 design documents to the Open RFCs table: - x402-1: Protocol support (nano contract escrow) - x402-2: Client SDK (@hathor/x402-client) - x402-3: Server middleware (@hathor/x402-server) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Pre-funded nano contract channels that allow multiple x402 payments from a single deposit. Client deposits once, facilitator calls spend(amount, seller) per request. Eliminates per-request latency after initial channel setup. Includes X402Channel blueprint design, protocol flow, comparison with escrow mode, and trust model analysis. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

obiyankenobi · 2026-04-07T20:23:50Z

+| Refund on timeout | Impossible without timelock hacks | **Built-in** — contract refunds automatically |
+| Trust model | Must trust facilitator won't hold tx | **Trustless** — contract enforces rules |
+| Multi-party | Hard | **Native** — contract tracks all parties |
+


I think the UX with nano contracts will be super slow. From what I understand, every payment depends on deploying a contract, which will be slow and probably more expensive.

But this has a fundamental flaw: the client can double-spend the UTXOs before the facilitator settles.

If we wait just for one block confirmation, which is as fast a nano tx, we don't have this problem. And it could be up to the facilitator. I imagine most txs are micropayments, so it should be ok not to wait for block confirmation. That's not possible with nanos, as execution always happen when a block arrives.

Another positive of using a regular transaction instead of nanos is the upcoming privacy solution. That won't be available for nanos, at least not initially.

obiyankenobi · 2026-04-07T20:32:57Z

+
+### 3.4 Why This Blueprint Design
+
+**One escrow per payment.** Each x402 request creates a new nano contract instance. This is clean because:


Why do we need one blueprint per payment? Can't we achieve all the features below with a single x402 contract? Or one contract per facilitator or per resource? One contract per payment seems cumbersome and probably more expensive (need to deploy multiple nano contracts).

obiyankenobi · 2026-04-08T19:51:24Z

+
+### 1.2 Why Nano Contracts (Not Pre-Signed Transactions)
+
+The naive approach for UTXO chains is pre-signed transactions. But this has a fundamental flaw: **the client can double-spend the UTXOs before the facilitator settles**. On EVM chains this is solved by EIP-3009 nonces; on Solana by recent blockhash expiry. Hathor has neither.


How does EIP3009 prevent this? From what I understand, it allows for gas payment by the receiver (or a third-party), but it does not guarantee settlement.

Update 0001 to use x402Version: 2, base64-encoded PAYMENT-SIGNATURE and PAYMENT-RESPONSE headers, price field (replacing amount), and x-payment fallback for V1 clients. Adds idempotency cache and health check to the facilitator plugin. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Investigates replacing nano contract escrow with regular Hathor transactions so x402 payments can eventually benefit from confidential transactions. Surveys Hathor's tx-layer constraints (no SIGHASH variants, no OP_IF, data outputs, mempool visibility) and evaluates three candidate schemes. Recommends adding 'hathor-direct' alongside 'hathor-escrow' via the x402 accepts[] mechanism, gated on a trust-model decision. Marked as research, not an RFC — meant to drive the debate Yan flagged in the x402 initiative about whether nano contracts should settle every x402 payment. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

obiyankenobi · 2026-05-07T18:13:57Z

+
+### 3.1 No SIGHASH variants
+
+Hathor has exactly one signing mode: `sighash_all` (`hathorlib/hathorlib/transaction.py:178`). The digest commits to every input, every output, parents, weight, timestamp, and nano headers.


SIGHASH_BITMASK would solve this.

obiyankenobi · 2026-05-07T18:15:36Z

+The two redeem templates in the wild are:
+- **P2PKH (+ optional timelock prefix):** `<timelock> OP_GREATERTHAN_TIMESTAMP OP_DUP OP_HASH160 <pkh> OP_EQUALVERIFY OP_CHECKSIG`
+- **P2SH MultiSig (+ optional timelock prefix):** `<timelock> OP_GREATERTHAN_TIMESTAMP <M> <pk1>…<pkN> <N> OP_CHECKMULTISIG` (wrapped in P2SH)
+


What does this solve?

On the EVM scheme, server can request payment, receive the signed data and not deliver the resource.

obiyankenobi · 2026-05-07T18:22:45Z

+
+**What's in the wire protocol:**
+
+`PAYMENT-REQUIRED` adds a server-generated `requestHash` (random 32 bytes) and a short `deadline` (seconds). Client's payment tx must include both the value output to `payTo` and a data output containing `requestHash`. The data output binds this payment to this request, and prevents the client from reusing one payment for two resources.


Do we need to store the requestHash on the transaction? That would make it more expensive.

andreabadesso self-assigned this Apr 2, 2026

andreabadesso added this to Hathor Network Apr 2, 2026

andreabadesso moved this to In Progress (WIP) in Hathor Network Apr 2, 2026

andreabadesso requested a review from pedroferreira1 April 2, 2026 12:48

andreabadesso and others added 3 commits April 2, 2026 10:05

rfc: add link to x402-poc repository

aba9e43

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

andreabadesso and others added 2 commits April 2, 2026 10:39

andreabadesso mentioned this pull request Apr 6, 2026

feat: x402 payment protocol — complete POC with escrow, channels, dApp, and deployment HathorNetwork/x402-poc#1

Open

9 tasks

obiyankenobi reviewed Apr 7, 2026

View reviewed changes

obiyankenobi reviewed Apr 8, 2026

View reviewed changes

andreabadesso and others added 2 commits April 20, 2026 13:18

pedroferreira1 assigned pedroferreira1 and unassigned andreabadesso May 7, 2026

obiyankenobi reviewed May 7, 2026

View reviewed changes

pedroferreira1 moved this from In Progress (WIP) to Todo in Hathor Network May 14, 2026

pedroferreira1 moved this from Todo to In Progress (WIP) in Hathor Network May 26, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rfc: x402 protocol support for Hathor Network#109

rfc: x402 protocol support for Hathor Network#109
andreabadesso wants to merge 8 commits into
masterfrom
feat/x402-support

andreabadesso commented Apr 2, 2026

Uh oh!

andreabadesso commented Apr 2, 2026

Uh oh!

obiyankenobi Apr 7, 2026

Uh oh!

obiyankenobi Apr 7, 2026

Uh oh!

obiyankenobi Apr 8, 2026 •

edited

Loading

Uh oh!

obiyankenobi May 7, 2026

Uh oh!

obiyankenobi May 7, 2026

Uh oh!

obiyankenobi May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### 3.4 Why This Blueprint Design

		One escrow per payment. Each x402 request creates a new nano contract instance. This is clean because:


		### 1.2 Why Nano Contracts (Not Pre-Signed Transactions)

		The naive approach for UTXO chains is pre-signed transactions. But this has a fundamental flaw: the client can double-spend the UTXOs before the facilitator settles. On EVM chains this is solved by EIP-3009 nonces; on Solana by recent blockhash expiry. Hathor has neither.


		### 3.1 No SIGHASH variants

		Hathor has exactly one signing mode: `sighash_all` (`hathorlib/hathorlib/transaction.py:178`). The digest commits to every input, every output, parents, weight, timestamp, and nano headers.


		What's in the wire protocol:

		`PAYMENT-REQUIRED` adds a server-generated `requestHash` (random 32 bytes) and a short `deadline` (seconds). Client's payment tx must include both the value output to `payTo` and a data output containing `requestHash`. The data output binds this payment to this request, and prevents the client from reusing one payment for two resources.

Conversation

andreabadesso commented Apr 2, 2026

Summary

Rendered

Test plan

Uh oh!

andreabadesso commented Apr 2, 2026

Added: SDK Design RFCs

0002-x402-client-sdk.md — @hathor/x402-client

0003-x402-server-middleware.md — @hathor/x402-server

Uh oh!

obiyankenobi Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

obiyankenobi Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

obiyankenobi Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

obiyankenobi May 7, 2026

Choose a reason for hiding this comment

Uh oh!

obiyankenobi May 7, 2026

Choose a reason for hiding this comment

Uh oh!

obiyankenobi May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

0002-x402-client-sdk.md — `@hathor/x402-client`

0003-x402-server-middleware.md — `@hathor/x402-server`

obiyankenobi Apr 8, 2026 •

edited

Loading