System Architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nhestrompia/shielded-x402/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture Overview

Shielded x402 is a multi-chain credit payment system that combines:

1. One authoritative sequencer for real-time nonce/balance enforcement
2. Per-chain relayers (Base, Solana) that execute only sequencer-authorized payments
3. Periodic Base commitment roots for delayed independent auditability
4. Shielded onchain settlement as the funding source for credit balances

​

Runtime Components

The system is split into three primary runtime components:

​

1. Credit Sequencer

Location: services/credit-sequencer The sequencer is the authoritative source of truth for all balances and nonces. It provides:

• Authoritative nonce/balance ledger - Maintains the canonical state of all agent accounts
• Signed authorizations - Issues cryptographically signed AuthorizationV1 payloads
• Reclaim + execution recording - Processes execution reports and handles expiration reclaims
• Hourly commitment root batches - Builds Merkle trees and posts audit checkpoints to Base

Key Responsibilities:

• Enforce per-agent nonce/balance invariants in real time
• Issue signed AuthorizationV1 payloads
• Process relayer execution reports with idempotency checks
• Handle reclaim transitions for expired issued authorizations
• Build periodic commitment epochs and optional Base postings

​

2. Payment Relayer

Location: services/payment-relayer Chain-bound executors that perform the actual on-chain payment operations. Each relayer instance is configured for a specific chain (e.g., eip155:8453 for Base, solana:devnet for Solana). Key Responsibilities:

• Verify sequencer signatures - Validate authorization signatures before execution
• Execute chain-specific payment actions - Perform native transfers or smart contract calls
• Post signed execution reports - Report back to sequencer with cryptographically signed results

Payout Modes:

• forward - HTTP proxy to merchant endpoint
• noop - Synthetic hash generation for testing
• evm - Native EVM transfers on Base or other EVM chains
• solana - Solana program invocation with ZK proof verification

​

3. Base Commitment Registry

Location: contracts/src/CommitmentRegistryV1.sol An on-chain smart contract that stores periodic audit checkpoints. This contract:

• Stores delayed audit checkpoints only - does not gate execution
• Records epoch commitments with (epochId, root, count, prevRoot, sequencerKeyId)
• Enables independent verification of authorization history

​

Data Flow Architecture

​

Authorization Flow

​

Commitment Flow

​

Chain Support

​

Base (EVM)

Chain Reference: eip155:8453 (mainnet) or eip155:84532 (testnet)

• Native ETH transfers via relayer-controlled accounts
• Optional noop mode for testing (generates synthetic transaction hashes)
• Commitment registry contract deployed on Base for audit checkpoints

​

Solana

Chain Reference: solana:devnet or solana:mainnet-beta Solana execution requires additional zero-knowledge proof verification:

• Noir smt_exclusion circuit - Proves payer is not blacklisted
• Sunspot Groth16 verifier - On-chain ZK proof verifier program
• Native Solana gateway - CPI (Cross-Program Invocation) to verifier and SOL transfer
• Relayer reports confirmed transaction signature as executionTxHash

​

Security Model

​

Key Management

The system uses Ed25519 signature schemes throughout:

• Sequencer signing key - Signs all authorizations (sequencerKeyId included in metadata)
• Agent signing keys - Each agent has a keypair for signing intents
• Relayer reporting keys - Each relayer signs execution reports with a registered key

​

Trust Boundaries

1. Agents trust the sequencer to maintain accurate balances and not double-spend credits
2. Relayers trust the sequencer to provide valid authorizations and not issue conflicting ones
3. The system trusts relayers to execute payments honestly and report accurate results
4. External verifiers trust the Base commitment registry for audit checkpoints

​

Scalability Considerations

​

Real-time vs. Delayed

• Real-time: Sequencer authorization and relayer execution happen in milliseconds
• Delayed: Commitment roots are posted hourly (configurable via SEQUENCER_EPOCH_SECONDS)

This design allows for high-throughput payment processing without waiting for on-chain confirmations.

​

Multi-chain Parallelism

Since each relayer is chain-specific, payments to different chains can be processed in parallel. An agent can have multiple in-flight authorizations across different chains simultaneously.

​

Database-backed State

The sequencer uses PostgreSQL for durable state storage:

• agents table - Balance and nonce per agent
• authorizations table - All issued authorizations with status
• executions table - Execution reports from relayers
• idempotency table - Deduplication of requests

​

System Diagram

​

Next Steps