This repository is the source of truth for Eureka-related deployments.
It is used by operators to deploy and perform maintenance operations. In addition, it can be used by anyone to find the most up-to-date contract addresses for different deployments and even verify that they match what is on-chain.
To use most of the functionality in this repo, you will need to install the following software:
Most recipes in this repo depend on values defined in .eureka-env.
To set yours up, copy the .eureka-env.example file and fill in the values, according to the environment you are going to run against.
The functionality of this repo is implemented through Just recipes (which are somewhat similar to Make targets). To see available recipes, run:
just --listAny on-chain verification that is not implemented as recipes yet should be documented below:
To verify that the Ethereum Light on the hub is running a specific version of the CosmWasm smart contract from the solidity-ibc-eureka repo, follow the steps below:
- Acquire the binary you want to verify against by for instance downloading the binary from the release page
- Get the binary checksum by running
gunzip -c path/to/cw_ics08_wasm_eth.wasm.gz | sha256sum - Fetch the checksum of the Ethereum light client (example below for Cosmos Hub mainnet, where the Ethereum light client ID is
08-wasm-1369) and convert it from base64 to hex:gaiad q ibc client state 08-wasm-1369 --output json | jq -r ".client_state.checksum" | base64 --decode | xxd -p -c 32
- Verify that the output from step 2 matches the output from step 3
Migrating/upgrading a light client is done in two steps:
- Deploying the new light client contract
- Migrating the existing light client to use the new contract
To deploy a new light client contract that is intended to be migrated, you want to essentially make a "copy" (with any modifications you might want, such as new vkeys) of the existing light client with a new contract.
Deploying the new light client contract can be done by anyone, but it is important for whoever is running the migration to verify both the contract and constructor parameters of the new light client.
- Update any fields you want changed in the relevant light client entry in the deployment JSON file.
- Update the deployment JSON entry with the latest client and consensus state from the existing light client with:
just deploy-update-light-client-state # You will be prompted for the client ID of the light client you want updated - Deploy the light client with:
just deploy-light-client # You will be prompted for the client ID of the light client to deploy
The last step will deploy the light client, but not add it to the IBC Client router. It is just a deployed contract with permissions set up for it. The implementation address will be updated in the deployment JSON entry for the light client, making it ready for step 2: migrating the existing light client.
⚠️ Only a wallet with the Light Client Migrator role for the given light client can migrate. Here, we're assuming a timelock admin has those permissions.
- Generate the timelock schedule transaction for the light client with:
just timelock-migrate-light-client schedule
- Follow the instructions to create the timelock transactions
After the timelock delay has passed, do the above steps again but replace schedule with execute
⚠️ Only a wallet with the Token Operator role is able to update the IBCERC20 Metadata
To update the Metadata for an IBCERC20 contract, you need to do the following:
- Grant the metadata role for the IBCERC20 contract with:
just ops-grant-metadata-role # You will be prompted for the IBCERC20 Address and the address of the grantee - Set the metadata:
just ops-set-metadata # You will be prompted for the IBCERC20 Address to update and the values to set
Modify one (and only one at the time) of the implementation values in the deployment json for one of the ERC1967Proxy contracts (ICS26Router for instance).
Run the script to generate the information needed to submit a proposal to the Safe Wallet:
just timelock-upgrade-proxy