written by
Major Tom

Designing a Cross Chain Token Bridge with CCIP

8 min read

Goals of this is to think through the design of a cross chain token bridge, not only at the functional level, but at the implementation requirements.

Token bridges are an illustration of an application which illustrate what cross blockchain interoperability could look like and their underlying requirements.

The requirements also include an overview of CCIP and how it can potentially address user requirements based on proposed (but not yet finalized) design and release.


Two primary Personas:

  1. Users of the Token Bridge
  2. Developers of the Token Bridge

Persona #1: Users of the Token Bridge

The end-users may often have little technical expertise, particularly as crypto and DeFi grows.

As more complex assets, chains, and DeFi “products” come to market, the requirements will evolve, so we do need to think about future, generalized use cases.

Some of their major functional requirements include:

Cross Chain Asset Swap

  • Exchange one token, typically a stable coin such as USDT, for a wrapped or native token such as ETH with a reliable price.
  • Send current and future token standards on the bridge (e.g. ERC-20, ERC-721, ERC-1155) and exchange for similar or different standards
  • Any given source or destination chain and their assets are available for swap

Cross Chain Protocol Utility

  • Send fungible token from one chain to another to improve yield or leverage different DeFi protocols ranging from staking, lending, or participating in liquidity pools
  • Send a non-fungible token, NFT, from one chain for functions on another chain (identity, content access, or gaming asset transfer)

Access Controls

  • Gate certain operations or data based on permissions or roles of the User
  • Support public-private chain messaging (where private chains enforce access controls)
  • Multi-sig support (for example,


  • Execute a transaction workflow that leverages different features from different chains (such as security, consensus, off-chain data such as supply-chain or IoT, or identity) within a single dApp


  • Sequence execution of chains (for example, a token, under one set of conditions, is one Chain A; but when circumstances change, is then automatically moved to Chain B)
  • Support conditions on chaining sequences, whether logic (if-then) or time-based (complete chaining where t<t1)


  • Specify transaction prioritization or gas fees, with the overall goal of lower fees without compromising speed

Non-Transfer Functionality (e.g. Governance)

  • A user with an existing token may want to be able to send a governance-related message (e.g. voting) on another chain (e.g. FWB token-holders are able to vote on FF)

Non-Functional Requirements

More sophisticated users probably have additional non-functional requirements. In other words, besides achieving tactical “jobs-to-be-done,” they have concerns around the environment and the experience.


  • Prevent fat-fingering addresses for contracts or other identifiers
  • Easy to identify options or review impact before executing
  • Clarity of errors or success in transactions


  • Prevent tokens from theft
  • Keep private keys secure
  • Prevent spoofing destinations
  • Resist man-in-the-middle attacks
  • Prevent impersonation attacks of user, originators, source chains or router


  • Keep transaction data private to prevent data leaks


  • End-user isn’t waiting for transaction (e.g. insufficient liquidity for a given token swap across the bridge)
  • End-user isn’t stuck when any blockchain is congested when there are a lot of transactions on the bridge
  • Prevent malicious denial-of-service which prevents a transaction across the bridge from completing

Cost Controls

  • Reduce gas fees paid to execute transaction
  • Control slippage tolerance of negative price action on a token swap
  • Protections against front-running by bots


End-users may not specify this as a non-functional requirement and, instead, this design is implemented as a means for improve security by minimizing trust assumptions for the bridge or its maintainers. This may also be a desired implementation approach opaque to many end-users to improve price accuracy (for example, prevent front-running or price-manipulation in a more centralized environment).

However, some end-users may explicitly desire a high-level of decentralization as not just a mechanic to achieve better security, but as a design principle in and of itself.

Persona #2: Developers of the Token Bridge

Sometimes the token bridge is a stand-alone dApp, which may take fees or issue its own token as part of its business model.

There are potentially two different set of developers as part of the effort: those building the actual token bridge dApp, and developers working with a given source or destination chain and creating a chain to increase utility and liquidity of their assets.

A high-level set of requirements for developers would include:

  • Generalizability to reduce rework of existing code to support new user requirements
  • Ease of Integration: the ability to either themselves or developers for a given chain to easily integrate, especially for non-EVM or even chains that do not support smart contracts natively (I explore this briefly here)
  • Security: developers can focus more on business logic and more security and dev-ops are off-loaded, including authentication and data-privacy, as well as generate principles like reduce the blast-radius of a breach.

As part of building and maintaining the token bridge, some requirements include:

  • Developer should be able to select a token by ID, a source Chain, a destination Chain, and the amount sent, and fee
  • The developer can use invoke burn/mint and lock/unlock functions as part of the transaction
  • Developer can specify within the message additional state changes or logic rules that are executed by the destination Chains smart contracts
  • The developer should know the status of the transaction (success, failures, and granular details as needed)
  • The developer should have access to transaction telemetry, including logs from the branches of the main transaction for error handling
  • Developer can provide a nonce (or it is automatic) for each transaction to prevent relay attacks

Non-Functional Requirements

In addition to what types of jobs-to-be-done as part of building the bridge, there are some non-functional requirements (many of which are the same as those for end-users, such as security, speed, and decentralization):

Ease of use for bridging to additional block chains

A generalized bridge typically wants to be able to scale to as many blockchains as possible. However, the bridge developer often doesn’t want to bear that weight to build and maintain those chain specific clients or contracts.

As a result, they would prefer the developers of specific chains to support this, if possible.

In either case, the bridge developers would like a standard or existing infrastructure that minimizes the work for either themselves or for a given chain’s own developers.

Low Gas/Transaction costs

Although many chains are trying to lower costs and improve scalability, the design should consider ways to continue to reduce those costs on chain.

Telemetry and monitoring

Developers may want to be able to understand errors and fraudulent behavior with enough information to triage by session or user, especially for multi-chain transactions.


Potential metrics for the bridge include the following:

  • Number of users
  • Volume transactions / growth of volume by asset and by chain
  • Latency of transactions executed
  • Number of chains supported / growth
  • Number of pair-wise token exchanges and total volume
  • Success and failures of transactions


The user would want to be able to make basic decisions such as those in the mock-up.

This initial layout is to think through the core-base of token bridges and explore whether there are issues in comparison with other token bridges for users.

The second is to think about differentiating options or future-thinking options beyond a traditional token bridge.

Sequence Diagram

Although a system-level sequence diagram would be designed by the engineering team, it’s helpful to identify key areas to consider for both the End User, the Bridge Developer, and the Blockchain Developers.

This helps us to think through the DEX and system attributes such as decentralization and security issues around signing as part of the flow if necessary.

Here’s one high-level concept combining the notion of relays (routers) which perform listening, routing, and writing features, and a decentralized federation of off-chain nodes for validation and transport.

Sequence Diagram for Token Bridge

Transaction Content

Based on many of the requirements above, we can begin to describe what should be available in the transaction content.

First let’s define what the content must be each direction on the transmission from the source chain to the remote chain.

What elements need to be included in each cross-chain transmission within the message?

Here are some possible elements to consider in the design (these are generalized, and some of them incorporating my understanding of CCIP with a handful of conversations and limited content online):

  • nonce: way to identify the sender’s transactions for uniqueness to prevent replay attacks (ideally random, but for this POC will just be an integer)
  • fee: what is the proposed fee for processing (could be optional with a default)
  • originator public key: a way to identify the user and ensure a given transaction is associated with the originator
  • originator signature: some way to sign to cryptographically verify the request and the chain (although this may not always be necessary)
  • orchestrations: what executables (functions 1....n) should be run on destination chain smart contracts (destination chain contracts 1....n) and under what conditions
  • status: error or success codes for a given transaction
  • callback: this option would be useful as a way for using data generated from a destination chain that can then be processed on the source chain’s contract (not sure if this would just be part of orchestration versus a separate callback)
  • token ID: what token is being moved or swapped
  • amount: the quantity of a given token or asset
  • sender address: for audit, verification, proof of transfer tracing
  • recipient address: for crediting the token
  • data: associated data for the token
  • bridgeId: it seems CCIP require registration of chain-pairs, so this would need to be included in the payload (probably not specified by the dApp explicitly, but to direct to the appropriate DONs)

Chainlink and CCIP considerations

DONs vs a “hub chain”

Secure, decentralized networks that can perform certain operations such as multiple observers for different transactions to collapse into a single message to save gas fees, for example, seems to make sense.

Without a monolithic blockchain which needs to be consistent in every way, the DONs can provide heterogenous functionality while still providing crypto-economic security to prevent bad-acting nodes.

Front Running

Front Running by bad-acting miners on a destination chain could be mitigated by the DONs enforcing transaction sequence of the miners. This seems like an interesting idea to ensure fairness enforced by DONs.

Confidential Computing

Privacy concerns could potentially be addressed with TEE within DONs.

Other Things

Graph-based Telemetry?

Ways to understand behavior of transactions at scale for token bridge developers to understand potential fraud or breaches....perhaps a way to show full transactions at the session level, especially for multi-chain transactions.....

Graphs as a way for detection of bad actors/faulty contracts....