AnomaPay Intent-Based Swap: Sequence Diagrams

intent-swap-diagrams.md

AnomaPay Intent-Based Swap: Sequence Diagrams

1. Maker-Taker Flow (New Design)

sequenceDiagram
    participant Alice as Alice (Maker)
    participant Server as AnomaPay Server
    participant Pool as Intent Pool
    participant Bob as Bob (Taker)
    participant PA as Protocol Adapter

    Note over Alice,Bob: Discovery Phase
    
    Alice->>Server: POST /intent/submit
    Note right of Alice: IntentAdvertisement<br/>(offers 100 USDC, wants 50 DAI)
    Server->>Pool: store(advertisement)
    Pool-->>Server: intent_id
    Server-->>Alice: {"intent_id": "abc-123"}

    Bob->>Server: GET /intents
    Server->>Pool: list_all()
    Pool-->>Server: [intents...]
    Server-->>Bob: [{id, offered_label, wanted_label, ...}]
    
    Note over Bob: Bob sees Alice's offer<br/>and wants to accept it

    Note over Alice,Bob: Accept Phase (Option A: Preview First)
    
    Bob->>Server: POST /intent/abc-123/accept
    Note right of Bob: AcceptIntentRequest<br/>(resource, receiver_info)
    Server->>Pool: get(abc-123)
    Pool-->>Server: Alice's intent
    Server->>Server: derive_taker_intent()
    Server->>Server: preview_settlement()
    Server-->>Bob: {taker_intent, preview, is_compatible: true}
    
    Note over Alice,Bob: Settlement Phase
    
    Bob->>Server: POST /intent/settle
    Note right of Bob: Both intents + secrets
    Server->>Server: validate_secrets()
    Server->>Server: generate_proofs()
    Server->>PA: submit_transaction()
    PA-->>Server: tx_hash
    Server->>Pool: remove(abc-123)
    Server-->>Bob: {"transaction_hash": "0x..."}

Loading

2. One-Click Swap Flow

sequenceDiagram
    participant Alice as Alice (Maker)
    participant Server as AnomaPay Server
    participant Pool as Intent Pool
    participant Bob as Bob (Taker)
    participant PA as Protocol Adapter

    Note over Alice: Alice publishes intent
    Alice->>Server: POST /intent/submit
    Server->>Pool: store(advertisement)
    Server-->>Alice: {"intent_id": "abc-123"}
    
    Note over Alice,Bob: Off-chain: Alice shares<br/>intent_id + her secret with Bob

    Note over Bob: Bob executes one-click swap
    Bob->>Server: POST /intent/abc-123/accept-and-settle
    Note right of Bob: AcceptAndSettleRequest<br/>{accept, taker_secret, maker_secret}
    
    Server->>Pool: get(abc-123)
    Pool-->>Server: Alice's intent
    Server->>Server: derive_taker_intent()
    Server->>Server: validate_secrets()
    Server->>Server: are_compatible() ✓
    Server->>Pool: remove(abc-123)
    
    Note over Server: Proof Generation
    Server->>Server: compliance_proofs_async()
    Server->>Server: logic_proofs_async()
    Server->>Server: aggregate_proof_async()
    
    Server->>PA: submit_transaction()
    PA-->>Server: tx_hash
    Server-->>Bob: {"transaction_hash": "0x..."}

Loading

3. Old vs New Flow Comparison

flowchart LR
    subgraph OLD["Old: Symmetric Matching"]
        A1[Alice crafts intent] --> A2[Alice submits]
        B1[Bob crafts intent] --> B2[Bob submits]
        A2 --> M[Both search /matches]
        B2 --> M
        M --> S1[Find each other]
        S1 --> S2[Call /settle]
    end
    
    subgraph NEW["New: Maker-Taker"]
        A3[Alice crafts intent] --> A4[Alice submits]
        A4 --> B3[Bob browses /intents]
        B3 --> B4[Bob clicks Accept]
        B4 --> D[Server derives Bob's intent]
        D --> S3[Settle atomically]
    end

Loading

4. Data Flow

flowchart TD
    subgraph Maker["Maker (Alice)"]
        MA[IntentAdvertisement]
        MS[SettlementSecret]
    end
    
    subgraph Taker["Taker (Bob)"]
        TR[offered_resource]
        TK[receiver_info]
        TS[SettlementSecret]
    end
    
    subgraph Server["Server derives"]
        DI[Taker's IntentAdvertisement]
    end
    
    MA -->|"wanted_label<br/>wanted_quantity"| DI
    TR -->|"must match<br/>maker's wanted"| DI
    TK -->|"where to<br/>receive tokens"| DI
    
    MA --> SR[Settlement Request]
    DI --> SR
    MS --> SR
    TS --> SR
    
    SR --> TX[Transaction]
    TX --> PA[Protocol Adapter]

Loading

Key Insight

In the maker-taker model, Bob (taker) only provides:

• His resource (must match what Alice wants)
• His keys (where to receive)
• His secret (at settlement)

The server derives everything else from Alice's intent.

sequenceDiagram
    participant Alice as Alice (Maker)
    participant Server as AnomaPay Server
    participant Pool as Intent Pool
    participant Bob as Bob (Taker)
    participant PA as Protocol Adapter

    Note over Alice: Alice publishes intent
    Alice->>Server: POST /intent/submit
    Server->>Pool: store(advertisement)
    Server-->>Alice: {"intent_id": "abc-123"}
    
    Note over Alice,Bob: Off-chain: Alice shares<br/>intent_id + her secret with Bob

    Note over Bob: Bob executes one-click swap
	rect rgb(0,200,100)
    Bob->>Bob: complete_to_tx_witness()
    Bob->>Server: POST /intent/abc-123/accept-and-settle
    Note right of Bob: AcceptAndSettleRequest<br/>{TODO: minimal data no secret}
	end
    
    Server->>Pool: get(abc-123)
    Pool-->>Server: Alice's intent
	rect rgb(0,200,100)
    Server->>Server: CHECK_taker_intent()
	end
    Server->>Server: validate_secrets()
    Server->>Server: are_compatible() ✓
    Server->>Pool: remove(abc-123)
    
    Note over Server: Proof Generation
    Server->>Server: compliance_proofs_async()
    Server->>Server: logic_proofs_async()
    Server->>Server: aggregate_proof_async()
    
    Server->>PA: submit_transaction()
    PA-->>Server: tx_hash
    Server-->>Bob: {"transaction_hash": "0x..."}
    

Loading