Multi-Blockchain Token Bridge

Created a configurable token bridge framework for representing one blockchain's native currency as a token on another blockchain. The framework supports converting a blockchain's native currency to and from a token representation on another blockchain, as well as directly swapping native currencies between blockchains. The initial deliverable included support for Ethereum and our client's two blockchains.

Context

Our client develops and maintains two blockchains with relatively small ecosystems. They wanted to allow their users to participate in the broader Decentralized Finance (DeFi) ecosystem, but DeFi liquidity is currently highly concentrated in a small number of ecosystems. Building a competitive DeFi ecosystem across their blockchains was not a practical alternative. Instead, they wanted to make their native currencies accessible within the Ethereum DeFi ecosystem by representing them as ERC-20 tokens. Coinbase provides a similar offering (cbBTC), which allows BTC held at Coinbase to participate in DeFi ecosystems.

Engineering Approach

We began this engagement by reviewing existing token bridges and identifying common requirements. Our review identified four distinct responsibilities: tracking bridge account state, discovering conversion requests, fulfilling those requests on the destination network, and independently confirming their fulfillment. Rather than combining these responsibilities into a long-running bridge service, we implemented them as independent, single-purpose processes. The framework assumes that bridge account private keys are managed through an appropriately secured operational environment. Custody and key-management infrastructure were outside the scope of this engagement.

Single-Purpose Workflows

We created a set of single-purpose Python scripts to perform each of the identified actions:

1. Track bridge account state (only required for Stake mode)
   Retrieves bridge account balance changes to calculate the exact token-to-native conversion rate. This workflow must process all blocks after the last checkpoint to capture both directly observable and indirect balance changes. Upon completion, it advances the checkpoint to the last processed block. This is the only workflow that requires block-by-block processing.
2. Discover conversion requests
   Downloads conversion requests sent to the bridge account on the source network. Valid requests are queued as unprocessed. Invalid requests are flagged as errors and not further processed. This is the only workflow that downloads transactions sent to the bridge account.
3. Fulfill conversion requests
   Processes pending conversion requests and initiates corresponding payouts on the destination network. For each unprocessed request, the converted amount is calculated net of fees. Requests that cannot cover the required fees are rejected and flagged as errors. Otherwise, the payout is submitted and the request is marked as sent. Transient failures, such as insufficient bridge funds or exceeding configurable throttling limits, stop processing without losing progress. After such a failure, processing resumes from the same point when restarted.
4. Verify fulfillment
   Monitors destination-network payouts until they become finalized (irreversible). The status of each pending payout is independently queried from the destination network. Its corresponding conversion request is marked as completed only after finalization.

All of the scripts are implemented in a blockchain-agnostic way. The shared initialization routine reads the source and destination blockchains from its configuration and instantiates a blockchain-specific facade for each. This also simplifies the reverse operation of converting a token representation back to a native currency. Because the same facade interface is implemented around the source and destination blockchains, the same processing pipeline can be used with the two facades swapped.

Three Operation Modes

The general bridge framework supports three operating modes:

1. Wrap: Convert a native currency to a token at a fixed 1:1 conversion rate.
2. Stake: Convert a native currency to a token at a dynamic conversion rate. As the bridge account receives additional native currency, such as staking rewards, the conversion rate increases so that each outstanding token represents a proportionally larger amount of native currency.
3. Swap: Directly convert one blockchain's native currency to another blockchain's native currency using an external price oracle.

The single set of scripts supports all of these modes as well as the corresponding unwrap and unstake operations, which are the inverses of wrap and stake. The exact mode is specified in the configuration provided to the scripts. A blockchain-specific facade may only support a subset of these modes.

Results

One Framework Across Chains and Modes

We delivered a configurable bridge framework composed of a single set of scripts that supports multiple blockchains through blockchain-specific facades and multiple operation modes. Running these scripts as scheduled jobs provides an automated bridge between two blockchains. The client can selectively deploy the blockchain and bridge-mode combinations they need without supporting every mode across every blockchain pair.

Well-Defined Conversion Lifecycle

Every conversion request progresses through a well-defined lifecycle:

1. Unprocessed - The request is valid but no payout has been sent.
2. Sent - The payout has been submitted but has not yet become irreversible.
3. Completed (terminal) - The payout has become irreversible.
4. Failed (terminal) - The request cannot be fulfilled and there will be no payout.

This lifecycle distinguishes submitted payouts from finalized ones and makes the state of each request explicit. Processing can resume after transient failures without losing progress. Operators can distinguish requests that are still in progress from those that have reached a terminal outcome.

Extensible Blockchain Support

The core scripts are blockchain-agnostic. Adding another blockchain requires implementing the shared facade interface for that blockchain and validating the desired bridge modes. The core processing scripts do not need to change because they interact with each blockchain exclusively through that interface.