Data Flows

API indexing and sponsoring

This flow is used by all write actions, that create transactions on chain, as creation/registration of TradeAccounts, initialization of sessions, creation/cancelation of orders. So we don't explicitly mention again this flow on the other flows and instead it will be encapsulated as just API.

sequenceDiagram
    autonumber
    participant User
    participant API
    participant GasSponsor as Gas Sponsor
    participant Indexer
    participant Blockchain

    User->>API: Submit request
    API->>GasSponsor: Add resources to pay for gas
    GasSponsor->>Blockchain: Forward transaction to chain
    Blockchain-->>API: Return transaction ID
    API-->>User: Return transaction ID

    Blockchain--)Indexer: Listen for pre-conf events<br/>(OrderCreation, AccountCreation, etc.)
    Indexer--)API: Update state
    API--)User: Send WebSocket notification

Trade Account - Create Account

On this flow users request the creation of a trading account, this process deploys a contract for users that, can be upgraded later by the users enforced by a Oracle system. For better convenience it uses the sponsor mechanism, in this way users do not need to pay for transactions. The address owner of this trade accounts, can be a EVM address or a Fuel address, allowing to use any of this two signatures.

sequenceDiagram
    autonumber
    participant User
    participant API
    participant Blockchain

    User->>API: Request account creation
    API->>Blockchain: Deploy trade account proxy
    Blockchain-->>API: Transaction ID
    
    Note over API: Wait for finalization
    
    API->>Blockchain: Register trade account<br/>Registry.register_trade_account(...)
    Blockchain-->>Blockchain: Emit TradeAccountRegistered event
    Blockchain-->>API: Event confirmation
    API-->>User: Return trade_account_id

Trade Account - Register Session

Session keys, can execute any action on the contract, this is really permissive, so users should not use their trade accounts, to interact with other contracts, this is not enforced on the contract logic. A session id, is equal to a EOA public key, where the private key, can be store in a less safe environment as LocalStorage, due to the nature of time bond, and revoke mechanims.

sequenceDiagram
    autonumber
    participant User
    participant API
    participant Blockchain

    Note over User: Create payload for `TradeAccount.set_session`<br/>including signature and session address
    User->>API: Send payload for on-chain execution
    API->>Blockchain: Call TradeAccount.set_session(signature, session)
    Blockchain-->>API: Transaction ID
    API-->>User: Return transaction ID

Trade Account - Order Placement

Orders on o2, can be posted directly OnChain or though sponsred API, for this flow we focus mainly on the usage of Tranding Accounts, with sponsor transactions.

sequenceDiagram
    autonumber
    participant User
    participant API
    box rgba(100, 149, 237, 0.1) Blockchain
        participant TA as Trade Account
        participant OB as Order Book
    end
    
    Note over User: Create payload for `TradeAccount.session_call_contract`<br/>including signature over OrderBook.create_order
    Note over User: Sign over contract call args
    User->>API: Submit order creation request
    
    API->>TA: Call TradeAccount.session_call_contract
    TA->>OB: Call `OrderBook.create_order(...)`
    
    Note over OB: Emit events:<br/>OrderCreatedEvent<br/>OrderMatchedEvent<br/>OrderCancelledEvent
    OB-->>TA: Events emitted
    TA-->>API: Transaction complete
    
    OB--)API: Index events and update state
    API-->>User: Return transaction_id and orders created
    API--)User: Send WebSocket notification