Settlement Contract Overview

Architecture and design decisions of the settlement-verifier Soroban contract

Overview

The settlement-verifier contract is the on-chain anchor for x402 payments on Stellar. It is compiled to WebAssembly targeting wasm32v1-none using soroban-sdk = "26.1.0" and Rust 1.92.0.

Live Deployments

Network	Contract ID	Explorer Link
Stellar Testnet	CATZACNU6KVGZXYF7J4O4NLINRKL5FWC2YAQPHTIQMSQPDAJSSOMRUNL	View on StellarExpert

Core Responsibilities

1. Replay Protection: Tracks per-payer nonces in persistent contract storage. If an attacker attempts to replay an authorization payload, the contract detects that provided_nonce != current_nonce + 1 and reverts with error code 4 (InvalidNonce).

2. Atomic Fee Distribution: Transfers funds from the payer to the merchant and collects a protocol fee in basis points (10,000 bps = 100%) in a single atomic transaction. Either all transfers succeed or the transaction reverts.

3. Storage Tiering & TTL Management:

   • Instance Storage: Stores protocol configuration (Admin, FeeBps, FeeRecipient). Automatically renewed during calls.
   • Persistent Storage: Stores payer nonces with TTL extension helpers to prevent data eviction while keeping costs predictable.

4. Structured Event Logging: Emits SettlementReceipt and InitializedEvent on-chain, allowing off-chain indexers and accounting systems to track payments by topic.