hyperlane-monorepo/docs/xapps/token-bridge.md

Token Bridge xApp

Summary

The Token Bridge xApp implements a bridge that is capable of sending tokens across blockchains.

Features:

• Ensures that circulating token supply remains constant across all chains.

Protocol

Handling Messages

• the BridgeRouter contract only accepts messages from other remote BridgeRouter contracts, which are registered by each BridgeRouter
  • therefore, every message received follows the same "rules" that the local BridgeRouter expects
  • for example, any tokens sent in a message are ensured to be valid, because the remote BridgeRouter sending the message should locally enforce that a user has custody before sending the message to the remote chain
• the messages from remote BridgeRouter contracts must be sent via Optics, dispatched by a local Replica contract, which are registered with the UsingOptics contract
  • thus, the BridgeRouter depends on the UsingOptics contract for a valid registry of local Replicas
• if another chain has sent a token that's "native" to this chain, we send that token from the Router contract's escrow to the recipient on this chain
• if we're receiving a token that's not "native" to this chain,
  • we check whether a representation token contract has already been deployed by the Router contract on this chain; if not, we deploy that representation token contract and add its address to the token registry
  • we mint representation tokens on this chain and send them to the recipient

Dispatching Messages

• TODO: describe rules — person must approve token to Router on local chain (if it's a native token) proving they have ownership over that token and can send to the native chain
• sending tokens
  • the user uses ERC-20 approve to grant allowance for the tokens being sent to the local BridgeRouter contract
  • the user calls send on the local BridgeRouter to transfer the tokens to a remote
• if the token being sent is "native" to the BridgeRouter's chain, the BridgeRouter contract holds the token in escrow
• if the token being sent is not "native" to the chain, then the local token is a representation token contract deployed by the BridgeRouter in the first place; the BridgeRouter contract burns the tokens before sending them to another chain

Message Format

• TODO: specify how messages are encoded for this application

Architecture

BridgeRouter (code)

• Receives incoming messages from local Replica contracts sending tokens from another chain
• Dispatches outgoing messages to local Home contract in order to send tokens to other chains
• Manages a registry of representation ERC-20 token contracts that it deploys on its local chain
• Maintains a registry of remote BridgeRouter contracts to
  • authenticate that incoming messages come from a remote BridgeRouter contract
  • properly address outgoing messages to remote BridgeRouter contracts

TokenRegistry (code)

• Responsible for deploying and keeping track of representation ERC-20 token contracts on this chain
• When a new token is transferred, deploys a new representation token contract on this chain, and stores a two-way mapping between the information of the original token contract & the address of the representation on this chain
• Inherited by the BridgeRouter, who uses this to make sure a representation of the token exists on this chain before minting/burning

BridgeMessage library (code)

• Library for handling all the nitty gritty of encoding / decoding messages in a standardized way so they can be sent via Optics

Message Flow

The logical steps and flow of information involved in sending tokens from one chain to another.

• Chain A
  • User wants to send their tokens to Chain B
    • If it's a native token, the user must first approve tokens to the local BridgeRouter-A
  • User calls send on the local BridgeRouter-A
    • If it's a native token, tokens are pulled from the User's wallet to BridgeRouter-A and held in escrow
    • If it's a non-native token, tokens are burned from User's wallet by BridgeRouter-A
      • Note: BridgeRouter-A can burn non-native tokens because the representative contract for the token on its non-native chain was originally deployed by BridgeRouter-A when it received a message sending the token from another chain. The router has administrative rights on representations
  • BridgeRouter-A constructs a message to BridgeRouter-B
    • BridgeRouter-A keeps a mapping of BridgeRouter contracts on other chains so it knows where to send the message on Chain B
  • BridgeRouter-A calls enqueue on Home-A contract to send the message to Chain B
• Off-Chain
  • Standard Optics behavior. Updater → Relayer → Processor
  • Relayers see message on Home-A
  • Relayers pass message to Replica-A on Chain B
• Chain B
  • After waiting for the acceptance timeout, Replica-A processes the message and dispatches it to BridgeRouter-B
  • BridgeRouter-B keeps a mapping Replica contracts that it trusts on the local chain. It uses this to authenticate that the incoming message came from chain A
  • BridgeRouter-B keeps a mapping of BridgeRouter contracts on other chains, so it can authenticate that this message came from BridgeRouter-A
  • BridgeRouter-B looks for the corresponding ERC-20 token contract in its registry, and deploys a new representative one if it doesn't already exist
  • BridgeRouter-B sends the token to the recipient
    • If it's a native token, BridgeRouter-B sends the tokens from the pool it's holding in escrow
    • If it's a non-native token, BridgeRouter-B mints the token to the recipient (
      • Note: BridgeRouter-B can mint non-native tokens because the representative contract for the token on its non-native chain is deployed by BridgeRouter-B when it received a message sending the token from another chain. The router has administrative rights on representations.