Skip to content

atomic-swaps.md

Latest commit

 

History

History
196 lines (154 loc) · 6.86 KB

atomic-swaps.md

File metadata and controls

196 lines (154 loc) · 6.86 KB

Atomic Swaps: Cross-Chain Payment for Stealth x402

Problem

XST has limited exchange listings and low liquidity. Requiring users to hold XST before they can access x402-gated content creates a high barrier to entry. Most potential users hold USDC, ETH, or BTC — not XST.

Solution

Cross-chain atomic swaps allow users to pay in any supported currency (USDC, ETH, BTC) while the payment settles in XST on the Stealth chain. The swap is trustless — neither party can steal funds, and if the swap fails, both parties get their money back.

This creates real demand for XST: every content purchase through the swap generates on-chain XST volume and can offer a discount vs. paying in USDC directly, incentivizing users to acquire XST.

Protocol Foundation

Stealth's scripting engine supports all opcodes required for Hash Time-Locked Contracts (HTLCs):

  • OP_IF / OP_ELSE / OP_ENDIF — conditional execution
  • OP_HASH160 — SHA256 + RIPEMD160 hash
  • OP_EQUALVERIFY — hash comparison
  • OP_CHECKLOCKTIMEVERIFY — time-locked refunds
  • OP_CHECKSIG — signature verification

These are implemented and evaluated in src/blockchain/script.cpp (confirmed in the codebase).

HTLC Script (Stealth side)

OP_IF
    OP_HASH160 <hash_of_secret> OP_EQUALVERIFY
    <recipient_pubkey> OP_CHECKSIG
OP_ELSE
    <locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP
    <sender_pubkey> OP_CHECKSIG
OP_ENDIF
  • Claim path (top branch): recipient reveals the secret (preimage) to claim funds. The hash of the secret must match hash_of_secret.
  • Refund path (bottom branch): after locktime expires, the sender can reclaim their funds if the recipient never claimed.

Atomic Swap Flow

Party A (buyer): has USDC on Base
Party B (seller/service): has XST on Stealth

1. Party B generates a random secret S, computes H = HASH160(S)
2. Party B creates an HTLC on Stealth:
   - Locks X XST with hash H
   - Claimable by Party A if they reveal S
   - Refundable by Party B after 2 hours
3. Party A verifies the HTLC on Stealth, then creates an HTLC on Base:
   - Locks Y USDC with the same hash H
   - Claimable by Party B if they reveal S
   - Refundable by Party A after 1 hour (shorter than Stealth side)
4. Party B claims USDC on Base by revealing S
   - This publishes S on the Base blockchain
5. Party A sees S on Base, uses it to claim XST on Stealth

If Party B never claims (step 4), both HTLCs expire and funds return.
If Party A never creates the Base HTLC (step 3), the Stealth HTLC expires.

Time Lock Asymmetry

The Stealth-side HTLC must have a longer timeout than the Base-side HTLC. This ensures Party A always has time to claim XST after Party B reveals the secret on Base.

Recommended timeouts:

  • Stealth HTLC: 2 hours (2400 blocks at 5s/block = ~3.3 hours max)
  • Base HTLC: 1 hour

Integration with x402 Paywall

The paywall's accepts array advertises multiple payment options:

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "stealth:mainnet",
      "asset": "XST",
      "amount": "100000000",
      "payTo": "S8m66...",
      "extra": { "feeless": true, "discount": "85%" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "100000",
      "payTo": "0x...",
      "extra": { "name": "USDC", "swapTo": "XST" }
    }
  ]
}

When a user pays in USDC, the swap coordinator:

  1. Creates an HTLC on Stealth (locking XST from liquidity reserve)
  2. Creates an HTLC contract call on Base (for the user's USDC)
  3. Completes the swap atomically
  4. Issues the x402 access token

The user experience is: click "Pay with USDC", approve one transaction in MetaMask, wait ~15 seconds, access granted. The swap happens in the background.

Implementation Phases

Phase 1: Stealth HTLC Tooling

  • Build a Go CLI tool to create and spend HTLC transactions on Stealth
  • Uses createrawtransaction and signrawtransaction RPC methods
  • Handles secret generation, hash computation, script construction
  • Test on testnet first

Phase 2: EVM HTLC Contract

  • Deploy a standard HTLC smart contract on Base
  • Solidity implementation (well-established pattern, many open-source examples)
  • Supports ERC-20 tokens (USDC)
  • Audit against known HTLC vulnerabilities

Phase 3: Swap Coordinator Service

  • Go service that orchestrates cross-chain swaps
  • Watches both Stealth (via StealthCoind RPC) and Base (via ethers/web3)
  • Manages swap lifecycle: create → monitor → claim → complete
  • Handles timeouts and refunds
  • Maintains a liquidity pool of XST for swaps

Phase 4: Paywall Integration

  • Add USDC payment option to the x402 paywall
  • Frontend: MetaMask/WalletConnect for EVM wallet connection
  • Backend: swap coordinator creates HTLCs, monitors completion
  • User flow: select USDC → approve tx → swap completes → access granted

Pricing Strategy

XST payments should be discounted vs. USDC to create demand:

Content USDC Price XST Price XST Discount
Tier 1 item $0.10 1 XST (~$0.015) 85% off
Tier 2 item $1.00 10 XST (~$0.15) 85% off
PRO report $5.00 50 XST (~$0.75) 85% off

This creates a clear incentive: "Why pay $0.10 in USDC when you can pay $0.015 in XST?" Users who transact frequently will buy XST to save money, driving exchange volume and price.

Liquidity Requirements

The swap coordinator needs a reserve of both XST and USDC:

  • XST reserve: locked in HTLCs during swaps, returned if swap completes
  • USDC reserve: accumulated from completed swaps

Initial bootstrapping:

  • Start with a manual XST reserve (e.g., 10,000 XST)
  • Revenue from USDC swaps can be used to buy more XST on exchanges
  • As volume grows, consider automated market-making

Security Considerations

  • Time lock ordering: Stealth HTLC must always expire after the EVM HTLC
  • Secret length: use 32-byte random secrets (256-bit security)
  • Hash function: HASH160 (SHA256 + RIPEMD160) is standard for both chains
  • Front-running: EVM HTLC claims should use commit-reveal if gas griefing is a concern
  • Liquidity risk: never lock more XST in HTLCs than you can afford to have temporarily unavailable

Dependencies

  • StealthCoind with HTLC script support (confirmed available)
  • Base (or other EVM chain) with HTLC smart contract
  • StealthCoind createrawtransaction and signrawtransaction RPC methods
  • Web3/ethers.js for EVM interaction
  • Swap coordinator service (new, to be built)

References