Interchain Swap

Sequence diagram and description of the interchain (cross-chain) swap.

Description of the interchain (cross-chain) swap.

Initiation:

• The User initiates an interchain swap through the Frontend interface.

• The Frontend constructs the swap transaction and requests the User to sign it.

• The User signs the transaction and returns it to the Frontend.

Network 1 Processing:

• The Frontend broadcasts the signed transaction to the Network 1 and Executor contract is called.

• The Executor validates the transaction.

• If the assets are not already in stablecoin form:

  • The Executor requests the Swap Protocol on Network 1 to convert the assets to stablecoin.

  • The Swap Protocol executes the conversion and returns the result.

• The Executor transfers the stablecoin and LP fee to the Vault on Network 1.

• The Executor transfers out the protocol fee.

• The Vault confirms the transfer to the Executor.

Cross-Chain Message Transmission:

• The Executor on Network 1 sends a cross-chain message to the Gateway on Network 1.

• The Gateway emits an Event that is monitored by the Messaging and Swap Service.

• The Messaging and Swap Service collects and processes the messages.

Network 2 Message Handling:

• The Messaging and Swap Service submits the processed messages to the Gateway on Network 2.

• The Gateway on Network 2 forwards these messages to the Executor on Network 2 for storage.

• The Executor on Network 2 confirms the storage of messages.

• The Gateway on Network 2 acknowledges the message submission to the Messaging and Swap Service.

Swap Execution on Network 2:

• The Messaging and Swap Service forms a swap transaction for Network 2.

• It sends this transaction to the Executor on Network 2 for execution.

• The Executor on Network 2 requests funds from the Vault on Network 2, limited to the amount specified in the stored message.

• The Vault provides the requested funds to the Executor.

• The Executor sends a request to the Swap Protocol on Network 2 to execute the swap.

• The Swap Protocol performs the swap and returns the result to the Executor.

• The Executor updates its state and the message status to reflect the completed swap.

• The Executor confirms the swap execution to the Messaging and Swap Service.

Status Monitoring and User Update:

• The Frontend periodically checks the message status on the Executor of Network 2.

• Based on the returned status, the Frontend updates the User:

  • If the swap is completed, it displays a success message.

  • If the swap is still pending, it shows a pending status.

  • If the swap has failed or timed out, it displays an appropriate error message.

• This checking process continues until the swap is completed or a timeout occurs.

Error Handling:

• If the initial transaction is invalid, the Executor on Network 1 returns an error to the Frontend, which then informs the User.

• If any step in the process fails, the appropriate error is propagated back through the system to be reflected in the message status, which the Frontend will detect during its status checks.

Diagram Code

sequenceDiagram
    actor User
    participant Frontend
    participant Executor1 as Executor (Network 1)
    participant Vault1 as Vault (Network 1)
    participant SwapProtocol1 as Swap Protocol (Network 1)
    participant Gateway1 as Gateway (Network 1)
    participant MsgSwapService as Messaging and Swap Service
    participant Gateway2 as Gateway (Network 2)
    participant Executor2 as Executor (Network 2)
    participant Vault2 as Vault (Network 2)
    participant SwapProtocol2 as Swap Protocol (Network 2)

    User->>Frontend: Initiate interchain swap
    Frontend->>Frontend: Construct swap transaction
    Frontend->>User: Request transaction signature
    User->>Frontend: Sign transaction
    Frontend->>Executor1: Broadcast signed transaction
    Executor1->>Executor1: Validate transaction
    alt Transaction is valid
        alt Assets not in stablecoin
            Executor1->>SwapProtocol1: Request swap to stablecoin
            SwapProtocol1->>SwapProtocol1: Execute swap to stablecoin
            SwapProtocol1-->>Executor1: Return swap result
        end
        Executor1->>Vault1: Transfer stablecoin & LP fees to vault
        Vault1-->>Executor1: Confirm transfer
        Executor1->>Executor1: Transfer protocol fees
        Executor1->>Gateway1: Send cross-chain message
        Gateway1->>MsgSwapService: Relay message
        MsgSwapService->>MsgSwapService: Collect and process messages
        MsgSwapService->>Gateway2: Submit processed messages
        Gateway2->>Executor2: Store messages
        Executor2-->>Gateway2: Confirm storage
        Gateway2-->>MsgSwapService: Acknowledge message submission
        MsgSwapService->>MsgSwapService: Form swap transaction
        MsgSwapService->>Executor2: Execute swap transaction
        Executor2->>Vault2: Request funds
        Vault2-->>Executor2: Provide requested funds
        Executor2->>SwapProtocol2: Execute swap
        SwapProtocol2->>SwapProtocol2: Perform swap
        SwapProtocol2-->>Executor2: Return swap result
        Executor2->>Executor2: Update state and message status
        Executor2-->>MsgSwapService: Confirm swap execution
    else Transaction is invalid
        Executor1-->>Frontend: Return error
    end
    loop Until swap completion or timeout
        Frontend->>Executor2: Check message status
        Executor2-->>Frontend: Return message status
        alt Swap completed
            Frontend->>User: Display successful swap result
        else Swap pending
            Frontend->>User: Display pending status
        else Swap failed or timeout
            Frontend->>User: Display failure or timeout message
        end
    end