Warp Route Spec

[nambrot]

Trade Route Product Spec

This document specifies the requirements for a token wrapping product called Trade Route.

Stakeholders and their needs

Asset issuers

Stakeholders who have a token (ERC20s or ERC721s) that are already issued on an existing single chain. They have an interested in a representation of said token to be available on another chain on which it can be used and it can be easily transferred to/from the issued chain. Ideally the issuer is able to easily include a transfer page on their UI or at least on their subdomain. Worst case they point their users to a generic version hosted by Abacus Works.

New Chains

New chains (especially ones deploying Hyperlane via #258 ) generally will want a way to "import value". This is commonly done via creating wrapped representations of high-liquidity tokens like ETH or USDC on Ethereum. That allows value on the new network to be bootstrapped easily without the need for centralized exchanges. New chain operators want to be able to point their users to a UI that allows them to actually import said value.

High-Level Requirements

• Stakeholders should be able to create wrapped synthetics with as little permission as possible.
• Stakeholders should be able to have those synthetics be usable by their users with as little effort as possible.
• => This implies that for any given canonical token/destination chain there could be many different synthetics that could be used, however in practice it is expected that the need to build social consensus for liquidity purposes will constrain the proliferation of competing synthetics.
• Ownership of synthetics should be the creator of a synthetic (as it implies issues like security and chain expansion considerations)
• Stakeholders should be able to easily point their users to a UI that they fork/integrate into their own UI.
• A generic Abacus Works hosted version can (with a lot of warnings) allow users to use a specific synthetic.

Smart Contract Architecture

Synthetics are basically just HypERC20 routers except on the canonical chain, they lock/mint from a HypERC20Collateral contract which holds the canonical token as collateral.

flowchart LR
    subgraph canonical chain
        sender --"approve(HypERC20Collateral)"--> ERC20
        sender --"transferRemote()"--> HypERC20Collateral
        HypERC20Collateral --"transferFrom()"--> ERC20        
    end

    subgraph remote chain
        HypERC20Collateral <--"Router"--> HypERC20
    end

    subgraph remote chain 2
        HypERC20Collateral <--"Router"--> HypERC202(HypERC20)
        HypERC20 <--"Router"--> HypERC202
    end

Since HypERC20 just implement the router pattern, at deploy time, the owner of the synthetic effectively specifies things like security or upgradability. Each synthetic is effectively its own logical and isolated application, making TradeRoute technically a framework of applications, not an application in of itself. Synthetics can be identified by its unique HypERC20Collateral contract address on the canonical chain. For UIs, all they have to specify is which HypERC20Collateral is to be used for a given canonical chain + destination chain (which is non-trivial from a UX perspective).

Synthetic Lists: While most other token wrapping bridges have a single, permissioned Collateral contract, Trade Route is an entirely new concept. There can be many different HypERC20Collateral contracts which determines the synthetic that a user would get on the destination chain and thus have significant security and liquidity considerations that have to be communicated to the user. Approving a malicious HypERC20Collateral contract can (like approving any malicious contract) cause the loss of funds, not too dissimilar from swapping into the wrong token on a DEX. Thus having trusted sources for HypERC20Collateral contracts becomes critical.

DEXs have "solved" this problem with the use of Token lists (https://tokenlists.org/) which effectively encode a mapping from Token symbols (DAI) to contract addresses (0x..). We can piggyback upon this standard by having lists of HypERC20Collateral that the author of the lists deems as "trustworthy" or "vetted". The reference UI should only default to a very small list and stakeholders who fork the UI can replace the default (and thus take responsibility over the contents of that list).

Synthetic lists exist mostly for security, not for disambiguation reasons. It is not expected there will actually be competing synthetics (remote HypERC20's on the same destination chain for the same canonical token on the origin chain) for the most part, as the existence of a synthetic will only be practical if the owner/issuer of the synthetic will build liquidity for it.

User flows

Deployment

Deployment Configuration:

• Which chains and which ISMs to use
• Who the owner is on every chain

Deployment is tricky as router deployment today takes about 3n transactions on n networks:

• Router deployment
• Router initialization
• enrollRemoteRouters

Our router deployment tooling today is geared towards a non-interactive ethers-rs signer.

v0:

• A infra script that takes some configuration format and then deploys a synthetic using the existing MultiProvider based router deployment tooling (overlap with permissionless deployment scripting needs)

v1:

• create a webpage but use a hosted key to pay for the deployment by a central entity.

v2:

• A smart contract factory that deploys the routers from a single origin chain using the Hyperlane messaging system itself.

End-User bridging UI

Users are mainly expected to use a fork of the reference UI or the reference UI itself. The reference UI uses a Synthetic List as specified above. For a given synthetic list, do pre-processing by fetching the full synthetic details of each HypERC20Collateral list entry (i.e. list of enrolled remote routers (address + chain).

UI inputs:

• Token symbol (XYZ)
• Origin Chain
• Destination Chain
• Recipient
• Amount

Desired outputs before transfer submission:

• Matching Synthetic derived from Synthetic List
• Sender Balance for XYZ on origin chain
• Recipient Balance for XYZ on destination chain

For a given Token symbol and origin/destination chain pair, there are the following cases:

• No matching synthetic
  • Indicate to the user that a transfer is not possible as no trusted synthetic could be found in the list
• Exactly 1 synthetic
  • Indicate that a matching synthetic was determined from the list
• More than 1 synthetic
  • Refuse transfer as it could not be determined which synthetic to use

To actually complete the transfer, there are the following two cases:

• Send from the canonical chain of the token
  • There are two transactions that have to be sent, 1) to approve the HypERC20Collateral contract from the canonical token and 2) call transferRemote on HypERC20Collateral
• Send from a remote chain
  • Just a single transferRemote on HypERC20 has to be called

Once the transaction has been submitted, the UI should determine whether the message explorer API supports this chain pair and use it to indicate message processing status to the user.

Forkability

Stakeholders should be able to easily fork the app and make the following changes:

• Basic brand adjustments like logo, colors
• Default synthetic list
• List of chains supported

Open Questions

Terminology/Branding Really this token wrapping bridge is not a product in of itself, but more like a framework for quickly building a wrapped synthetic application for a given canonical token with associated tooling/UIs. All those "bridge applications" share their standardized use of Hyperlane, but aren't really connected more broadly speaking. So it seems like we should have terminology for 1) the framework itself 2) instantiations of the framework in the form of the synthetics

Trade Route for me makes more sense for a specific synthetic, i.e. the Fuel Trade Route, or the ImpactMarket trade route. For the framework, I wonder what we think of Caravanserai

Out of scope

• Tooling to assess synthetics (their use of ISMs, owners, mutability) for Synthetic List creators (https://github.com/hyperlane-xyz/hyperlane-monorepo/issues/1335)
• Message explorer is able to detect messages for HypErc20 and show metadata for the transfer in the explorer
• The UI should also be able to show a list of transfers that were initiated or received by a particular address (again via the message explorer)
  • Message explorer needs to be able to query by the initiator of a message, not just the msg.sender of a message (since that will end up just being the HypERC20/HypERC20Collateral contracts) (likely requires scraper agent support)
  • Message explorer needs to be able to query by the "beneficiary" of a message, i.e. the recipient of tokens of HypERC20/caninical token (same as above) (likely requires scraper agent support)
• Make including the UI inside an existing React/next.js app easy
  • For now, it is sufficient for stakeholders to just fork the app and replace some configuration values

[nambrot]

Remaining Scope Left:

UI

• 1336

• 1337

• 1338

• 1339

• 1320

• 1342

• 1323

• 1472

• Token List management?

"Backend":

• https://github.com/hyperlane-xyz/hyperlane-monorepo/issues/1462
• https://github.com/hyperlane-xyz/hyperlane-monorepo/issues/1463
• https://github.com/hyperlane-xyz/hyperlane-monorepo/issues/1549

Docs:

• https://github.com/hyperlane-xyz/issues/issues/334
• https://github.com/hyperlane-xyz/issues/issues/335

[asaj]

Deployment is tricky as router deployment today takes about 3n transactions on n networks:

Router deployment Router initialization enrollRemoteRouters

There's probably a way to simplify this using CREATE2, where you can know the address of the remote routers without them being deployed.

[asaj]

At some point it would be worth deploying a TokenRouterFactory that uses minimal proxies to minimize the gas costs of deploying new tokens

[nambrot]

Blast from the past cc @yorhodes :)

[avious00]

@nambrot @yorhodes any nuggets here that should be captured in docs?