Bootstrapping the bridge

Overview

The Ethereum bridge is not enabled at the launch of a Namada chain. Instead, there are two governance parameters:

eth_bridge_proxy_address
eth_bridge_wnam_address

Both are initialized to the zero Ethereum address ("0x0000000000000000000000000000000000000000"). An overview of the steps to enable the Ethereum bridge for a given Namada chain are:

A governance proposal should be held to agree on a block height h at which to launch the Ethereum bridge by means of a hard fork.
If the proposal passes, the Namada chain must halt after finalizing block h-1. This requires
The Ethereum bridge smart contracts are deployed to the relevant EVM chain, with the active validator set at block height h as the initial validator set that controls the bridge.
Details are published so that the deployed contracts can be verified by anyone who wishes to do so.
If active validators for block height h regard the deployment as valid, the chain should be restarted with a new genesis file that specifies eth_bridge_proxy_address as the Ethereum address of the proxy contract.

At this point, the bridge is launched and it may start being used. Validators' ledger nodes will immediately and automatically coordinate in order to craft the first validator set update protocol transaction.

Facets

Governance proposal

The governance proposal can be freeform and simply indicate what the value of h should be. Validators should then configure their nodes to halt at this height. The grace_epoch is arbitrary as there is no code to be executed as part of the proposal, instead validators must take action manually as soon as the proposal passes. The block height h must be in an epoch that is strictly greater than voting_end_epoch.

Value for launch height `h`

The active validator set at the launch height chosen for starting the Ethereum bridge will have the extra responsibility of restarting the chain if they consider the deployed smart contracts as valid. For this reason, the validator set at this height must be known in advance of the governance proposal resolving, and a channel set up for offchain communication and co-ordination of the chain restart. In practise, this means the governance proposal to launch the chain should commit to doing so within an epoch of passing, so that the validator set is definitely known in advance.

Deployer

Once the smart contracts are fully deployed, only the active validator set for block height h should have control of the contracts so in theory anyone could do the Ethereum bridge smart contract deployment.

Backing out of Ethereum bridge launch

If for some reason the validity of the smart contract deployment cannot be agreed upon by the validators who will responsible for restarting Namada, it must remain possible to restart the chain with the Ethereum bridge still not enabled.

Example

In this example, all epochs are assumed to be 100 blocks long, and the active validator set does not change at any point.

A governance proposal is made to launch the Ethereum bridge at height h = 3400, i.e. the first block of epoch 34.

{
    "content": {
        "title": "Launch the Ethereum bridge",
        "authors": "[email protected]",
        "discussions-to": "[email protected]",
        "created": "2023-01-01T08:00:00Z",
        "license": "Unlicense",
        "abstract": "Halt the chain and launch the Ethereum bridge at Namada block height 3400",
        "motivation": "",
    },
    "author": "[email protected]",
    "voting_start_epoch": 30,
    "voting_end_epoch": 33,
    "grace_epoch": 33,
}

The governance proposal passes at block 3300 (the first block of epoch 33)
Validators for epoch 33 manually configure their nodes to halt after having finalized block 3399, before that block is reached
The chain halts after having finalized block 3399 (the last block of epoch 33)
Putative Ethereum bridge smart contracts are deployed at this point, with the proxy contract located at 0x00000000000000000000000000000000DeaDBeef
Verification of the Ethereum bridge smart contracts take place
Validators coordinate to craft a new genesis file for the chain restart at 3400, with the governance parameter eth_bridge_proxy_address set to 0x00000000000000000000000000000000DeaDBeef and eth_bridge_wnam_address at 0x000000000000000000000000000000000000Cafe
The chain restarts at 3400 (the first block of epoch 34)
The first ever validator set update (for epoch 35) becomes possible within a few blocks (e.g. by block 3410)
A validator set update for epoch 35 is submitted to the Ethereum bridge smart contracts

Security Ethereum events attestation