ioTube v3 -- Faster, Cheaper, and Unified!

Welcome to ioTube!

ioTube is a decentralized cross-chain bridge that connects IoTeX to the blockchain universe. ioTube enables the bi-directional exchange of crypto-assets and data between IoTeX and other blockchain networks. This means Ethereum tokens (ERC20) can live on IoTeX, and IoTeX tokens (XRC20) live on Ethereum and other blockchains! ioTube is fully open-source on GitHub, compatible with ioPay & Metamask, and supports ERC20 assets including ETH, wBTC, BUSD, PAXG, UNI, and more.

In this thread, we explain ioTube’s history, latest features, and technical architecture. To learn how to use ioTube to convert tokens from Ethereum-to-IoTeX and vice versa, see this thread.

Past Versions: ioTube v1 (Apr 2019) & ioTube v2 (Aug 2020)

In April 2019, ioTube v1 was launched as part of Mainnet Alpha to convert IOTX-E (ERC20) on Ethereum to native IOTX on IoTeX. In August 2020, ioTube v2 was introduced with major upgrades to support the conversion of other Ethereum assets (e.g., ETH, WBTC, BUSD) to IoTeX. In v2, we also introduced the concept of “witnesses” to make ioTube decentralized and secure, such that a transfer is settled if and only if it is backed by more than two-thirds of all witnesses.

Current Version: ioTube v3 (Feb 2021)

Due to all-time high Ethereum gas prices, ioTube v3 was designed to significantly reduce the costs of cross-chain token transfers between Ethereum and IoTeX. We also added new optimizations to greatly improve efficiency and reliability. With ioTube v3, the gas required to complete a cross-chain token transfer has been reduced by 40% as compared to ioTube v2. The new benefits of ioTube v3 are summarized below:

  • Reduced transfer costs: for EVM-based Solidity contracts, storage in contract is the largest driver of gas consumption. Instead of storing transfer details in contracts as in previous versions, ioTube v3 collects transfer details from emitted events by reading logs, greatly reducing gas consumption.
  • Reduced settlement costs: in previous versions, each witness submitted an individual attestation to the blockchain and all attestations were stored in the contract, which means every attestation triggered a costly “check of transfer status” action. In ioTube v3, we introduce a new “relayer” role that collects the signatures of all witnesses and sends them to the contract for settlement, lowering gas consumption by 74%.
  • Unification: we have also taken the chance to merge the legacy ioTube v1 + ioTube v2 contracts into a unified ioTube v3 contract, which is now seamless to setup and interact with.

ioTube v3 – Overview & Architecture

Cross-chain token transfers via ioTube utilize multiple smart contracts on both the origin/destination blockchain. It starts when a user deposits assets into a “cashier contract” on Chain A, which is an event that is observed by multiple witness nodes. These witnesses verify this event and send a signature to the relayer network, which aggregates all signatures and instructs a “validator contract” on Chain B to mint the same amount of tokens that were deposited on Chain A.

The entire ioTube v3 architecture is composed of the following contracts:

  • WitnessList: stores the list of active witnesses
  • TokenList: stores the list of whitelisted tokens
  • TokenSafe: stores the tokens deposited to token cashier, and these stored tokens are used to transfer to recipients by transfer validator
  • MinterPool: holds the minter authorities of all mintable tokens
  • TokenCashier: accepts token/coin deposits and emit a receipt for each deposit
  • TransferValidator: validates witness signatures and then withdraws tokens from token safe to recipients.

For depositing assets, the TokenCashier contract validates the following:

  • Checks if the asset is whitelisted and active via TokenList
  • Checks if the amount is within the maximum limits
  • Checks if the asset is a proxy token (e.g., ioETH on IoTeX is a proxy token)
  • If proxy, burns it and create a receipt; if not proxy, deposits it into the TokenSafe.


Once a witness detects a deposit, they will sign an attestation and send it to the relayer, which collects attestation from witnesses and submit them to TransferValidator.

For minting (i.e., issuing corresponding assets), the TokenValidator contract ensure:

  • The asset being converted is whitelisted and active via TokenList
  • The transfer has attestations from at least two-thirds of all witnesses
  • If so, the contract mints proxy tokens to transfer tokens to the given recipient.


Ready to get started with ioTube?

Ready to get started with ioTube and bring new crypto-assets to the IoTeX Network? It’s easy – just download ioPay, visit the ioTube website, and follow these instructions. For any questions, you can reach out to an Admin on Telegram.