Skip to main content

Atomic Token Swap via Escrow Contracts

This document describes a protocol by which two parties, Alice and Bob, can atomically swap tokens across two distinct smart contract platforms using Hash Time-Locked Contracts (HTLCs). The protocol ensures that either both token transfers happen or neither does, eliminating counterparty risk.

In the scenario considered, Alice wishes to trade 10 units of token A for 20 units of Bob's token B.

Assumptions​

Tokens & Contracts​

  • Token A
    • Defined by contract A, deployed to pod PA
    • Contract address: A.addr
  • Token B
    • Defined by contract B, deployed to pod PB
    • Contract address: B.addr
  • HTLC_A
    • Escrow contract for token A, deployed to pod PA
    • Address: HTLC_A.addr
  • HTLC_B
    • Escrow contract for token B, deployed to pod PB
    • Address: HTLC_B.addr

Parties​

  • Alice
    • Holds at least 10 A tokens
    • Address: Alice.addr
  • Bob
    • Holds at least 20 B tokens
    • Address: Bob.addr

Happy path Steps​

Step-by-step Description​

  1. Agreement: Alice and Bob agree to swap 10 A tokens for 20 B tokens.
    • This agreement may be reached in different forms, e.g., in person or using a matching application.
  2. Approval: Alice allows HTLC_A to spend 10 A tokens on her behalf.
  3. Contract Creation: Alice creates a contract via HTLC_A.new_contract, specifying Bob's address, the hash of a secret S, a deadline t+D, the token address A.addr, and the amount 10.
  4. HTLC_A stores the escrow details and returns escrow_id_A.
  5. HTLC_A transfers 10 A tokens from Alice to itself.
  6. Alice sends hash(S) and escrow_id_A to Bob.
  7. Bob allows HTLC_B to spend 20 B tokens.
  8. Bob creates a contract via HTLC_B.new_contract, specifying Alice's address, hash(S), a deadline t, token B.addr, and the amount 20.
  9. HTLC_B stores the escrow details and returns escrow_id_B.
  10. HTLC_B transfers 20 B tokens from Bob to itself.
  11. Bob informs Alice of escrow_id_B.
  12. Alice calls HTLC_B.withdraw(escrow_id_B, S) to claim the 20 B tokens.
  13. HTLC_B transfers 20 B tokens to Alice.
  14. Bob, having learned S from Alice's transaction, calls HTLC_A.withdraw(escrow_id_A, S).
  15. HTLC_A transfers 10 A tokens to Bob.

Fallback Scenario: Bob Disappears​

If Bob disappears after step 6 (e.g., to stall the trade or attempt sabotage), Alice waits for the t+D deadline and recovers her tokens.

  1. Alice waits until time t+D.
  2. Alice calls HTLC_A.refund(escrow_id_A) to recover her 10 A tokens.
  3. HTLC_A refunds the tokens to Alice.

Choosing the Delay Parameter D​

  • If D is too small, Alice might wait until just before time t to withdraw the B tokens, leaving Bob insufficient time to claim the A tokens before t+D. In that case, Alice could also reclaim her A tokens, unfairly acquiring both tokens.
  • If D is too large, and Bob disappears, Alice must wait unnecessarily long to reclaim her A tokens.

Thus, D must be chosen to provide Bob with a fair time window, while not overly delaying refunds for Alice.

Choosing the Timeout t​

  • If Bob colludes with a validator, they may see Alice's withdrawal and intercept the secret S without broadcasting her transaction. This would let Bob use S to claim the A tokens and later refund the B tokens, effectively stealing from Alice.
  • To prevent this, t must be long enough to allow Alice to retry her transaction via multiple validators.

A sufficiently large value of t reduces the likelihood that a censoring validator could cause the swap to fail unfairly.