deposit

sequenceDiagram
    title Deposit Flow
    participant C1 as Clearinghouse
    participant P1 as Relayer (Off-chain)
    participant S1 as Sequencer
    participant M1 as MySQL
    participant U1 as USDC
    actor A1 as User/SDK
      %% DK Comment
        %% REVIEW: Eventually we should tag the actions that emit WS events with the event name.

    Note over A1,M1: For first-time users:<br/>Smart Account must be created first<br/>(See Smart Account Creation Flow)

    Note over P1: Relayer includes built-in redundancies<br/>and fail-safes for transaction processing
    A1 ->> U1: 1. Approve ERC20 transfer <br/> to ClearingHouse Contract
    A1 ->> P1: 2. User confirms gas expense (if applicable) <br/> submits signed deposit Tx via Sequencer
    Note over S1: Pre-deposit validations:<br/>- Verify user approvals<br/>- Check available balance<br/>- Ensure EOA -> SA mapping
    P1 ->> C1: 3. Call deposit function on ClearingHouse Contract <br/> (debit external user account, credit clearingHouse)
    Note over P1,C1: Include all settlement instructions<br/>for user account
    C1 ->> C1: 4. Transfer Asset, Update Ledger, emit Deposit Event
    C1 ->> S1: 5. Process User Deposit (via Relayer)<br/>TX Confirmation Required

    %% Success Path
    Note over A1,S1: Success Scenario
    S1 ->> S1: 6a. Add to Sequencer Queue
    S1 ->> M1: 7a. Update Equity State (deposit)
    S1 ->> A1: 8a. Notify deposit success

    %% Failure Path
    Note over A1,S1: Failure Scenario
    S1 -->> A1: 6b. Notify deposit failure with error details
      %% REVIEW: What are the failure reasons/codes expected ie Insufficient Balance, Approval Amount, Sig Invalid, Expired, Timeout, etc?
    Note over S1: Processing stops - no further actions taken