Add Stellar Blockchain Support

[marcelosalloum]

Description

This PR adds comprehensive Stellar blockchain support to the x402 (v2) payment protocol, enabling payments using Stellar's Soroban smart contracts alongside existing EVM and Solana implementations. The implementation follows the x402 v2 specification with CAIP-2 network identifiers and modernized protocol structure.

Note

This PR partially addresses the issue #633

Key Implementation Details

Payment Mechanism

Leverages Stellar's SEP-41 through Soroban smart contracts:

• Client-side: Signs authentication entries for token transfer authorization
• Facilitator-side: Rebuilds and submits transactions with facilitator's account (paying gas fees)
• Transaction format: Uses a Stellar transaction with a single invokeHostFunction operation for SEP-41 token transfers

Network Support

CAIP-2 Network Identifiers (per CAIP-28):

• stellar:pubnet - Mainnet (requires custom RPC URL configuration)
• stellar:testnet - Testnet (default RPC: https://soroban-testnet.stellar.org)
• stellar:* - Wildcard pattern matching all Stellar networks

Required Payment Format

The Stellar exact scheme requires these fields in PaymentRequirements:

{
  scheme: "exact",
  network: "stellar:*",    // CAIP-2 identifier
  amount: "10000",         // Token amount in atomic units. Since USDC has 7 decimals, 10000 is $0.001.
  asset: "CCZE...TPHS",    // SEP-41 contract address (C-account)
  payTo: "GBHE...W3KO",    // Recipient address (G or C-account)
  extra: {
    maxLedgerOffset: 12    // Ledger maximum offset for tx validity window. If the signature is valid beyond 12 ledgers, it's deemed too unsafe.
  }
}

Critical field: extra.maxLedgerOffset specifies the number of ledgers to add to the current ledger for transaction expiration. The client fetches the current ledger from RPC and calculates the absolute maxLedger = currentLedger + maxLedgerOffset. This uses Stellar's ledger-based timeout (not timestamp-based like EVM). Default offset is 12 ledgers ≈ 60 seconds.

Dynamic maxLedgerOffset

The facilitator provides a maxLedgerOffset value (default: 12 ledgers ≈ 60 seconds) that clients use to calculate transaction expiration:

• Facilitator: Returns { maxLedgerOffset: 12 } via getExtra() in the /supported endpoint
• Server: Passes maxLedgerOffset through to payment requirements
• Client: Fetches current ledger from RPC and calculates absolute maxLedger = currentLedger + maxLedgerOffset
• Configurable: Custom offset via constructor parameter (e.g., 20 ledgers ≈ 100 seconds)

Modified Components

TypeScript Packages Updated

• TypeScript Packages: @x402/core (docs), @x402/express, @x402/hono, @x402/next, @x402/fetch, @x402/axios

• TypeScript Examples: facilitator, servers/express, servers/hono, servers/custom, servers/advanced, clients/axios, clients/fetch, clients/custom

Testing & Quality Assurance

Unit Tests: test/unit/ - 117 tests across 9 test files
Integration Tests: test/integrations/ - 8 tests across 1 test file

Manual Testing

Tested with different combinations of the example applications:

• examples/typescript/facilitator - Multi-chain facilitator (EVM + SVM + Stellar)
• examples/typescript/servers/* - Express, Hono, Next, and custom servers with Stellar routes
• examples/typescript/clients/* - Axios, Fetch, and custom clients with Stellar payments

Key Differences from EVM/SVM

Ledger-Based Expiration

• Stellar: Uses maxLedgerOffset for signature expiration timing. Unlike timestamp-based systems, Stellar's smart contracts only support ledger-based expiration boundaries. It defaults to 12 ledgers ≈ 60 seconds (currently).
• EVM/SVM: Uses validUntil (Unix timestamp)

Auth Entry Signatures

• Stellar: Client signs auth entry, facilitator rebuilds and submits transaction
• EVM: EIP-3009 transferWithAuthorization with signature
• SVM: SPL token transfer with client signature

Network Configuration

• Mainnet: Requires custom RPC URL (no default public endpoint)
• Testnet: Default RPC provided (https://soroban-testnet.stellar.org)

Asset Decimals

• Stellar USDC: 7 decimals
• EVM USDC: 6 decimals
• SVM USDC: 6 decimals

Future Enhancements

Planned for subsequent PRs:

• Fee Bump Transactions: Update facilitator to use Stellar's FeeBumpTransaction for higher throughput and more reliable settlement
• E2E Test Coverage: Add Stellar-specific test cases to the e2e folder
• Paywall Integration: Add Stellar-compatible browser wallets (e.g., Freighter, xBull) as paywall options

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@marcelosalloum is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[marcelosalloum]

FYI: I'm about to rebase this PR on the latest changes (x402 v2)

[marcelosalloum]

Finished rebasing this code to use x402 v2 ✅. This PR is ready for review

[phdargen]

Hi @marcelosalloum, thanks a lot for your contribution!

The first step for adding a new chain is usually to write a document that outlines the implementation for the exact payment scheme on your chain, see eg for EVM: https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md and the contributing guide https://github.com/coinbase/x402/blob/main/CONTRIBUTING.md#new-chains.

Could you please provide such a document for Stellar? The team will then review it and give feedback. Once this is approved, we can proceed with the actual implementation.

[marcelosalloum]

@phdargen: cool, thanks for the reply and references. I'll open a PR with the Stellar scheme and we can continue our discussion there.

[marcelosalloum]

@phdargen: created a PR with the Stellar exact spec here: #941