Getting Started with IMA

The IMA bridge allows users to transfer tokens and messages across chains within the SKALE Network and with Ethereum. The IMA bridge supports ETH, ERC20, ERC721, and ERC1155 tokens out of the box. IMA can be expanded to any arbitrary message or token standard using the base messaging system Message Proxy.

IMA bridge consists of four general parts:

Deposit Box contracts
Token Manager contracts
Message Proxy contracts
IMA Agent - a containerized service on each SKALE Chain node that relays messages between chains.

Simplified Diagram of 4 SKALE Chains and Ethereum. Chains 1 and 3 are connected to Ethereum. Chain 2 is connected to chain 1. Chain 4 is not yet connected.

Figure 1. Simplified Diagram of 4 SKALE Chains and Ethereum. Chains 1 and 3 are connected to Ethereum. Chain 2 is connected to chain 1. Chain 4 is not yet connected.

Developing with IMA using out of the box contracts is straight forward. You will only need to interact with the IMA contracts on each chain using Web3. The IMA Agent works behind the scenes to relay messages between chains.

The high-level flow between chains consists of the following:

Tokens that leave an origin chain are locked, and the same number of tokens are minted on a target chain.
Tokens that leave a target chain are burned, and then unlocked on the origin chain to complete the round-trip transfer.

Transfers take only seconds and are secured using BLS threshold signatures and secure enclaves from each of the randomly chosen 16 validator-nodes that support each SKALE Chain.

Ethereum - SKALE

You can transfer tokens and messages between Ethereum and SKALE. Using the off-the-shelf code, IMA transfers generally require Ethereum gas costs for approval, deposit, and exit functions. There is an additional deposit required (CommunityPool) to ensure exit safety with Ethereum gas price volatility.

Dapp developers implementing the IMA bridge for Ethereum and SKALE transfers may choose to apply custom logic to their bridge, such as subsidizing exit or communityPool deposits, or change other parts of the deposit/exit flow for end-users.

Transfers usually resolve in seconds and are dependent on when the Ethereum network will mine the transactions, and of course how many block confirmations is required by a dApp. SKALE Chains typically mine transactions within seconds. For inbound transactions from Ethereum the default is set to several Ethereum block confirmations. This setting may be customized on each SKALE Chain.

How are messages from Ethereum secured using BLS threshold signatures?

Incoming messages from Ethereum to SKALE are detected by the IMA agent and are sent to all 16 nodes of a SKALE Chain. Each node then verifies the messages and BLS signs it. Once 2/3rd of nodes sign the message, the signatures are glued into one BLS signature and the signed message is submitted to IMA pre-deployed contracts on the SKALE Chain.

SKALE - SKALE (S2S)

You can transfer tokens and messages, for free between any two SKALE chains. Transfers complete in seconds.

Key Concepts for the SKALE IMA Bridge

There are origin and target chains. Origin chains define where the original token contract is located. Target chains define where the clones of the original token contract are used.

Tokens move by one chain

In the IMA bridge, you can only move tokens by one chain. In other words, you cannot move a token X originating on chain A to chain B and then to chain C. You may move the X token from chain A to chain B (Xclone). On chain B you may create a token pair between Xclone and Y, and move Y to chain C (Yclone).

Manual vs Automatic Deployment

You can choose to manually map tokens between chains, or you can choose to use automatic deployment, which automatically creates a token clone on the target chain.

There are several limits to using automatic deployment. When using this method:

All token types support only basic token functionality. For example, special features such as ERC777 hooks and operators, fee-on-transfer, inflationary, etc., will not be mapped over. Be sure to review the token features supported by automatic deployment of each token type here: https://github.com/skalenetwork/IMA/tree/develop/proxy/contracts/schain/tokens. If you require any specialized features, please use the manual mapping process.
ERC20 token clones are based on OpenZeppelin’s library and use 18 decimals. See: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/d4d8d2ed9798cc3383912a23b5e8d5cb602f7d4b/contracts/token/ERC20/ERC20.sol#L87. If you require a different representation, then use the manual deployment process.

Manual token mapping requires you to manually deploy a token clone on the target chain, and set the minter to the Token Manager.
If using manual token mapping, your token contract’s clone may need to be modified to include MINTABLE and BURNABLE functions. SKALE Chain IMA contracts need to mint and burn the token on SKALE chains. If the token is already using OpenZeppelin’s framework, you can do this by importing Mintable and Burnable contracts that extend the functionality to include mintable and burnable functions. You can also do this by manually modifying the contract by adding mintable and burnable functions.
The SKALE Chain contracts "TokenManager.." must be assigned the minter role for your modified token contract. This enables IMA to mint token clones as the tokens are Locked on mainnet contracts.

Custom Messages

The IMA bridge is highly configurable and expandable. Using the base Message Proxy system, you can design any arbitrary flow for end-users. What is presented out-of-the-box is a suggested system. DYOR and security assessment! Configuration options for the bridge can be controlled by a multisig.

Edit on Github