TheDZhon / jumpgates

Jumpgates are a class of contracts that streamline cross-chain token transfers under the Lido DAO.

Jumpgates

Jumpgates facilitate cross-chain token transfers under the Lido DAO incentive programs. Although autonomous, jumpgates are meant to be part of the Easy Track Rewards Program pipeline.

🌀 About jumpgates

A jumpgate is a simple contract that transfers tokens via a cross-chain token bridge, such as Wormhole, Terra Shuttle, etc. The parameters of the transportation (the token, recipient, bridge) are predefined and immutable for each invididual jumpgate which makes its operation safe and permissionless. Jumpgates also provide permissioned ways to recover ether, ERC20, ERC721 and ERC1155 tokens.

As Ethereum-native Lido expands other blockchains, jumpgates reduce operational overhead associated with routine cross-chain token transfers under the Lido DAO by providing a permissionless way to bridge tokens.

For further details read ADR.

🏁 Getting started

This project uses Brownie development framework. Learn more about Brownie.

Prerequisites

• Python 3.8+

Step 1. Create a Python virtual environment.

$ python3 -m venv venv

Step 2. Activate the virtual environment.

$ source venv/bin/activate

Step 3. Install Python dependencies.

$ pip3 install -r requirements.txt

Note! The solana package may have conflicts with eth_brownie, in which case try installing the former individually,

$ pip3 install solana

Step 4. Specify your Infura project id.

Replace %YOUR-INFURA-PROJECT-ID% below with your actual project id. Learn more about Infura.

$ export WEB3_INFURA_PROJECT_ID=%YOUR-INFURA-PROJECT-ID%

Step 5 (recommended). Specify your Etherscan API key.

Replace %YOUR-ETHERSCAN-TOKEN% below with your actual API key. Learn more about Etherscan API.

$ export ETHERSCAN_TOKEN=%YOUR-ETHERSCAN-TOKEN%

🧪 Testing a jumpgate

Before you proceed, please follow Getting Started instructions.

To run the entire test suit, execute the following command,

$ brownie test

Alternatively, you can run a specific test module by specifying the path,

$ brownie test tests/test_jumpgate_unit.py

Learn more about Brownie tests.

🚛 Deploying a jumpgate

Before you proceed, please follow Getting Started instructions.

Step 1. Add a local account.

You can add a local account either from a private key or a keystore. If you do not have either of them, consider generating a new account. Learn more about Brownie local accounts.

Step 2. Specify environment variables.

You can do this by copying the contents of sample.env into .env and filling it out. The necessary variables are listed below,

• DEPLOYER - your local account id;
• NETWORK - name of the network you want to deploy a jumpgate to, e.g., mainnet, goerli, ropsten, etc.;
• TOKEN - address of the ERC20 token you want to transfer;
• BRIDGE - address of the Wormhole Token Bridge;
• RECIPIENT_CHAIN - Wormhole id of the target chain, e.g. 1 for Solana, 3 for Terra;
• RECIPIENT - address of the recipient;
• ARBITER_FEE - bridge arbiter fee, defaults to 0.

Step 3. Run the deploy script.

$ brownie run scripts/deploy.py

Upon running the script you will prompted to enter the password to your local account. After that, all the deploy parameters will be displayed in your terminal. Confirm them and enter 'y' to proceed. E.g.,

If all is correct, you should be able to see your transaction hash and the address of the jumpgate in the terminal. You will also find the deployment parameters in a newly created JSON file in the deployed directory that is named %NETWORK%-%RECIPIENT%.json.

Step 4 (optional). Check your deployment.

Specify the newly deployed jumpgate address in JUMPGATE in .env and run the check script.

$ brownie run scripts/check_jumpgate.py

You should be able to tell whether the deployment was successful by the outputs in the terminal.

🕳 Bridging tokens

Before you proceed, please follow Getting Started instructions.

The bridging of tokens is the core function of jumpgates. You can do it by running the bridging script.

Step 1. Add a local account.

Skip this step if you have already done it in the Deploying a jumpgate section.

You can add a local account either from a private key or a keystore. If you do not have either of them, consider generating a new account. Learn more about Brownie local accounts.

Step 2. Specify environment variables.

You can do this by copying the contents of sample.env into .env and filling it out. The necessary variables are listed below,

• DEPLOYER - your local account id (in case of bridging the variable name is a bit misleading because bridging is permissionless and can be sent by any account with some ether);
• NETWORK - name of the network your jumpgate was deployed to, e.g., mainnet, goerli, ropsten, etc.;
• JUMPGATE - address of the jumpgate you want to active (you can find the list of deployed jumpgates in the deployed directory);

Step 3. Run the script

$ brownie run scripts/bridge_tokens.py

Upon running the script you will prompted to enter the password to your local account. After that, all the bridging parameters will be displayed in your terminal. Confirm them and enter 'y' to proceed. E.g.,

If all is correct, you should be able to see your transaction hash in the terminal.