# The Bridge Message Standard

status: Proof of Concept

## Summary

We propose a bridge message standard to be applied across different bridges and chains. For a proof of concept we:
+ bridge Toucan protocol (deployed on Polygon) TCO2 tokens with Regen Eco Credits
+ using a bridge controller smart contract to connect with a Axelar bridge service connecting Polygon and Regen Ledger
+ Regen Ledger as a Cosmos SDK with it's own token registry.

Code:
+ https://github.com/regen-network/toucan-the-bridge: Bridge controller implementing The Bridge Message Standard
+ https://github.com/robert-zaremba/ethamsterdam-the-bridge: fork of Regen Ledger (Cosmos SDK chain) with:
+ [`x/axelarbridge`](https://github.com/robert-zaremba/ethamsterdam-the-bridge/tree/master/x/axelarbridge) module implementing the The Bridge Message Standard.
+ [`x/ecocredits handler`](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/x/ecocredit/core/bridge.go) with custom logic handling the message to process TCO2 token registration.

regen-ledger code diff: https://github.com/robert-zaremba/ethamsterdam-the-bridge/compare/regen-master...master

The solution can be also applied to any smart contract chain or Layer-2 (Evmos, Optimism, Juno, Agoric, Solana ....).

## Context & Use Case

Toucan TCO2 is a leading Carbon Credits registry in the Ethereum world.
Regen Ledger is a leading Eco Credits (super class for carbon credits) registry in the Cosmos world.

Toucan focuses on tranferring tokens from traditional registires (like [Verra](https://verra.org/)) to web3 world, with it's registry implementation on Polygon. Regen Network Registry focuses on creating methodologies and "native" registration of new credit classes and carbon credit in the [Regen Ledger](https://github.com/regen-network/regen-ledger).

Connecting the two registires and two worlds (Cosmos and Ethereum) is important to bring more market efficiency, where users can easily transfer the credits to take advantage of new protocols and opportunities happening in the Ethereum and Cosmos world.

Unfortunately a traditional token based standard is not enough. For the business reasons we:
+ can't simply transfer tokens: the tokens must be retired and burned on one side and registered on another side. This requires sending additional information alongside the tokens.
+ Credits on Regen are not represented as token (which in Cosmos world are created using the /x/bank module) and are not connected via Inter-Blockchain Communication protocol (IBC) (standard protocol to transfer x/bank denoms across Cosmos chains).

Regen Network, as core maintainers of the Cosmos SDK, aim to propose a Interchain message standard for cross-chain asset transfer, which can then be used for our Polygon<>Regen use case.

## Problem Definition

Following [discussions](https://regennetwork.notion.site/Toucan-TCO2-Bridge-Strategy-4df1631eb5004be2b42d968dc2e2a389) between Regen and Toucan earlier this year, it has been decided in March to start with:
1. a semi-automated and centralized,
2. burn/retire on Polygon and mint credits (non x/bank tokens) on Regen,
3. 1-way (Polygon->Cosmos)

bridge.

However, the mid-term goal is to switch to a **decentralized 2-way bridge**.

The 2nd requirement means that we cannot use the token transfer feature offered by numerous bridges (e.g. Axear, Gravity, Nomad), as they escrow the tokens. We have to rely on arbitrary cross-chain message passing.

Our first idea was to implement this arbitrary cross-chain protocol and create an PoC for our specific Regen use case. However, after some thought, we realized arbitrary cross-chain message passing standard is a feature desired by numerous blockchains (other use cases would include: sending instructions ot other chains to perform some operations, eg portfolio rebalancing). It would be beneficial to define an Interchain wide standard, agnostic form the blockchain perspective.

## Solution

1. We propose The Bridge Message Standard, a specification providing standardized cross-chain message passing protocol on top of any bridge of choosing.
2. Cosmos SDK module handler & controller module to be included in any Cosmos chain.
3. An implementation of The Bridge Message Standard for TC02 token transfer from Polygon to Regen, via Axelar.

### Deliverable 1. The Bridge Message Standard.

We describe the protocol using Axelar as a bridge transport layer.

#### Flow EVM -> Cosmos Chain

1. Create your own `appBridge` contract in an EVM chain
2. `appBridge` contract calls Axelar's contract `axelarBridge.callContract(string destChain, string method, bytes payload)` [see docs](https://docs.axelar.dev/dev/gmp#call-a-contract-on-chain-b-from-chain-a), where
* `destChain` is the destination Cosmos chain (e.g. `"regen"`)
* `method` is:
* a Contract Address in a EVM based chain.
* for a Cosmos based chain, it's a [**handler**](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/x/ecocredit/core/bridge.go#L16) name which must be [registered](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/app/app.go#L548) in the bridge module.
* `payload` is the any arbitrary bytes to pass to the destination chain (defined by the app). App should specify the serialization format. We propose Protobuf (for it's overall performance, small encoded format size and compatibility for extensions). Another good options is [CBOR](https://github.com/fxamacker/cbor/wiki/Why-CBOR) or Ethereum ABI encoding. All have an implementation in Solidity and all major programming languages.
4. Axelar network listens for the Axelar bridge contract events.
5. Axelar network handle the event request and enhances it with the chain and transaction ID [information](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/proto/axelar/bridge/v1/tx.proto#L25-L26)
6. Axelar records the Bridge Standard's [`MsgRecordBridgeEvent`](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/proto/axelar/bridge/v1/tx.proto#L22) via [IBC Interchain Accounts](https://ibc.cosmos.network/main/apps/interchain-accounts/overview.html) on the target chain (incl. the source chain/caller and the arbitrary payload).
7. Any user can call `MsgExecBridgeEvent` to execute this bridge event using the handler defined in step 2.

#### Flow Cosmos Chain -> EVM

1. Create your own `appBridge` contract in an EVM chain.
1. Call [`MsgSendBridgeEvent`](https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/master/proto/axelar/bridge/v1/tx.proto#L44) on the Axelar Chain using the [IBC Interchain Accounts](https://ibc.cosmos.network/main/apps/interchain-accounts/overview.html) with the following arguments:
- `string sender` is the address initiating the cross-chain message
- `string handler` is the contract address of your `appBridge`
- `bytes payload` are arbitrary bytes to be passed into the handler.
1. The Axelar network will charge Axelar tokens the account sending `MsgSendBridgeEvent` message.
1. Axelar network handle the event and enhances it with the chain and transaction ID information.
1. Axelar network’s smart contract will call the `handler` contract (your `appBridge` contract) with the given payload.

#### Code

https://github.com/robert-zaremba/ethamsterdam-the-bridge/compare/regen-master...master

- Protobuf definitions
- x/axelarbridge Cosmos SDK module

### Deliverable 2: Toucan<->Regen Bridge

### Smart contract on Polygon

We created a bridge smart contract following the specification described above to handle bridge requests (both in and out): https://github.com/regen-network/toucan-the-bridge

### Handler on Cosmos

Using The Bridge Standard, any chain that wishes to leverage cross-chain message passing only needs to define a mapping of handler name to handler implementation.

In our bridge, we choose the name `"toucan-bridge"` and we added in our own `ecocredit` module an implementation as follows:

https://github.com/robert-zaremba/ethamsterdam-the-bridge/blob/4cc58eca6d7d918add7d774caf88ea3a26084850/x/ecocredit/core/bridge.go#L16-L53

Things to note:
- the arbitrary message we pass is a `ToucanPayload`:

// ToucanPayload is the payload to be passed.
message ToucanPayload {
  // recipient is the account of the recipient.
  string recipient = 1;

  // tco2_contract_address is the ERC20 smart contract of the TC02 token on Toucan.
  string tco2_contract_address = 2;

  // amount is the number of credits in this issuance that can be
  // traded by this recipient. Decimal values are acceptable.
  string amount = 3;

  // reference note for accounting, will be passed to an event
  string note = 4;
}

- The Bridge Standard passes bytes, which we decode Protobuf into a `ToucanPayload`, and do some basic validation (correct amount, correct TCO2 contract address, convert it into a Regen ecocredit batch denom
- we then create a `MsgMintBatchCredits` transaction on Regen

## Next Steps

1. Get in touch with Axelar to present The Bridge Message Standard.
2. Talk with bridge protocols to get feedback and define an Interchain / EIP standard.
3. Integrate this bridge into Regen Ledger next release (or the following).

### Authors:

+ [Amaury Martiny](https://github.com/amaurym)
+ [Robert Zaremba](https://github.com/robert-zaremba)