How OATS Works

OATS facilitates cross-chain token transfers by defining a set of interfaces that your token (or an associated bridge contract) implements. These interfaces interact with the Analog GMP Gateway contract.

Key Components & Process

A cross-chain transfer occurs in three main stages: initiation on the source chain, relay by the Timechain, and execution on the destination chain.

1. Setup: Implement OATS Interfaces

To make your token compatible with OATS, your contracts must implement specific interfaces:

1. Source Chain Contract: This is typically your main token contract or a dedicated bridge contract. It must implement ISender for simple transfers or ISenderCaller for transfers that trigger a subsequent function call.

interface ISender {
    /// @notice Get GMP message cost for cross-chain tokens transfer
    /// @param networkId Chain Id of the target network
    function cost(uint16 networkId) external view returns (uint256);
    /// @notice Transfer tokens to another network.
    /// Note this is payable, caller should transfer GMP fee amount provided by cost function above
    /// @param networkId Chain Id of the target network
    /// @param recipient address of the recipient account
    /// @param amount amount to transfer
    /// @return msgId GMP message Id
    function send(uint16 networkId, address recipient, uint256 amount) external payable returns (bytes32 msgId);
}

interface ISenderCaller {
    function cost(uint16 networkId, uint256 gasLimit, bytes memory caldata) external view returns (uint256);
 
    function sendAndCall(
        uint16 networkId,
        address recipient,
        uint256 amount,
        uint256 gasLimit,
        address callee,
        bytes memory caldata
    ) external payable returns (bytes32 msgId);
}

2. Destination Chain Contract: This contract, which will receive the transfer, must implement the IGmpReceiver interface. See IGmpReceiver Interface for more details.

2. The Transfer Flow

Step 1: Initiation (Source Chain): A user initiates a transfer by calling either send() or sendAndCall() on the source chain contract.

1. User Action: The user specifies the destination chain, recipient address, and token amount. They also pay a fee to cover the cross-chain transaction cost.
2. Source Contract's Logic:
   • Handles the token state change on the source chain (e.g., burning the tokens or locking them in the contract).
   • Constructs a message payload with all the transfer details.
   • Finally, it calls submitMessage() on the Analog GMP Gateway, passing the payload and fee.

Step 2: Relay (Analog GMP) The Analog network securely relays the transfer message.

1. Event Emission: The source chain's GMP Gateway emits a GmpCreated event.
2. Validation: The Timechain observes this event, and its validators reach a consensus to approve the message, generating a TSS signature.
3. Relay: A Timechain node submits the signed message to the GMP Gateway on the destination chain by calling its execute() or batchExecute() function.

Step 3: Execution (Destination Chain) The GMP Gateway on the destination chain completes the process.

1. Verification: The Gateway verifies the TSS signature from the Timechain.
2. Receiving the Transfer: Upon successful verification, the Gateway calls the onGmpReceived() function on your destination contract.
3. Destination's Contract's Logic:
   • It decodes the message payload to get the transfer details.
   • It performs security checks, such as verifying the source chain.
   • It completes the transfer by minting new tokens for the recipient or unlocking tokens from the contract.
   • If the original call was sendAndCall, your contract can now execute the specified function call on a target contract.