Skip to content

X402.md

Latest commit

 

History

History
98 lines (74 loc) · 4.84 KB

X402.md

File metadata and controls

98 lines (74 loc) · 4.84 KB
Raw

x402 v2 Solana-Devnet Adapter

Scope

SolGuard implements a strict x402 v2 protocol adapter for the exact scheme on Solana devnet. It proves that an x402 payment requirement can be normalized into the existing canonical request, evaluated by the unchanged core security engine, and reach a payment payload signer only after SolGuard returns ALLOW.

The default settlement boundary is deliberately X402_DEVNET_SIMULATED. It does not hold a wallet key, submit a transaction, contact a facilitator, or move devnet or mainnet funds. An isolated, opt-in real devnet demonstration is also available; it requires disposable credentials, explicit confirmation, and public test services.

Official contract used

The adapter follows x402 protocol version 2:

  • Server challenge header: PAYMENT-REQUIRED
  • Client payment header: PAYMENT-SIGNATURE
  • Header representation: Base64-encoded JSON
  • Scheme: exact
  • Network format: CAIP-2
  • Solana devnet: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
  • Solana devnet USDC mint: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
  • USDC amount mapping: atomic units converted with six decimals

The implementation was reviewed against x402-foundation/x402 commit 5a587d3165ea96f77ab7760427583a3030a2fac1, including the v2 core specification, v2 HTTP transport, and exact SVM scheme.

Security flow

  1. Require HTTP 402 and exactly one case-insensitive PAYMENT-REQUIRED header.
  2. Decode the Base64 JSON with bounded input size, require x402 v2, and select exactly one supported Solana-devnet USDC exact option.
  3. Validate the HTTPS resource, atomic amount, recipient, and timeout.
  4. Hash the complete canonical PaymentRequired object.
  5. Bind that hash and a caller-supplied attempt identifier into the canonical SolGuard request nonce and digest.
  6. Run the existing integrity, mandate, behavioural, and fail-closed gateway controls.
  7. For BLOCK or REQUIRE_APPROVAL, return without calling the payload signer.
  8. For ALLOW, consume the short-lived exact-request SolGuard authorization once.
  9. Call the injected payload signer and validate that its v2 accepted requirement exactly matches the requirement evaluated by SolGuard.
  10. Emit only a digest and byte length for the simulated payment header; never expose the header or scheme payload in normal evidence.

The full PaymentRequired digest in canonical request metadata prevents changes to resource or extension data from escaping the SolGuard authorization binding. The explicit attempt identifier prevents two separate attempts for a reusable route requirement from sharing a nonce.

Demonstration

Run:

uv run solguard-x402-demo

The deterministic command evaluates two devnet-labelled x402 v2 requirements:

  • 0.01 USDC satisfies the mandate, returns ALLOW, and calls the simulated signer.
  • 1 USDC exceeds the 0.1 USDC mandate, returns BLOCK, and never calls the signer.

The resulting JSON computes the decisions, request digests, signing-call count, and simulated settlement evidence from the running code. PREPARED_SIMULATION is not a valid signed Solana transaction or proof of network settlement.

Tested failure cases

The adapter tests cover malformed Base64/JSON, wrong protocol versions, unsafe resource URLs, unsupported network/asset/scheme combinations, ambiguous requirements, invalid amounts and timeouts, altered canonical bindings, missing and replayed authorizations, mismatched payment payloads, signer failure, an allowed flow, and a policy-blocked flow.

No x402-specific branch exists in the canonical contracts, gateway, mandate policy, behaviour engine, integrity guard, or wallet authorization guard.

Optional real devnet path

The devnet dependency extra provides an official-SDK executor that can request real USDC settlement through the x402.org facilitator on Solana devnet. The command remains separate from the deterministic demo and reports success only after checking returned settlement evidence. See Real x402 Solana-Devnet Demonstration.

No transaction is claimed merely because the implementation or tests pass.

Production work not included

The optional devnet executor keeps a disposable key in process memory and relies on public test services. Durable replay protection, managed key custody, independent transaction validation, authenticated configuration, operational monitoring, and mainnet review are outside this demonstration.