Rainbow bridge step-by-step testing

Disclaimer: Rainbow Bridge is a WIP project at the moment. Information in this repository might be outdated. Please, consider confirming the deployed contract addresses (and their ABIs) and Rainbow Bridge interfaces (see more here)

The steps below are for the mainnet, same steps might be reproduced for testnets.

Bridge deploymnets

Mainnet

Ethereum

1. Client address: 0x0151568af92125fb289f1dd81d9d8f7484efc362
2. Prover address: 0x051ad3f020274910065dcb421629cd2e6e5b46c4
3. ERC20 connector address: 0x23ddd3e3692d1861ed57ede224608875809e127f

NEAR

1. Client account: client.bridge.near
2. Prover account: prover.bridge.near
3. ERC20 connector account: factory.bridge.near

Testnet

Ropsten

1. Client address: 0xb289c6e6c98644dc9f6a03c044564bc8558b6087
2. Prover address: 0xb3df48b0ea3e91b43226fb3c5eb335b7e3d76faa
3. ERC20 connector address: 0xb48e6441524f261e141bc766a7ebd54b19ca7465

NEAR Testnet

1. Client account: client.ropsten.testnet
2. Prover account: prover.ropsten.testnet
3. ERC20 connector account: f.ropsten.testnet

Preliminary steps (tested on iOS Big Sur, Ethereum - NEAR mainnet bridge deployment)

1. Make sure you have installed npm
2. Install NEAR CLI: $ npm install -g near-cli
3. Install TypeScript: $ npm install -g typescript
4. Clone this repo: $ git clone git@github.com:alexauroradev/bridge-testing.git OR $ git clone https://github.com/alexauroradev/bridge-testing.git
5. $ cd bridge-testing & $ npm install.
6. Make sure you have an access to your Ethereum account (you have a private key) and you know the address of the ERC20 token that you would like to transfer.
7. Make sure you have an access to your NEAR account through NEAR Wallet: https://wallet.near.org/
8. Make sure that you're working with the NEAR Mainnet: $ export NODE_ENV=mainnet
9. Log in to the NEAR Wallet from the CLI: $ near login. The browser should pop up and a NEAR Wallet should ask for a permission for adding a full access key.
10. Rename test-ethereum-config.json to ethereum-config.json in bridge-testing/src/json. Update ethereum-config.json with the actual data on the addresses, private key and transfer amount. RPC access can be easily gained from Alchemy.
11. Rename test-near-config.json to near-config.json in bridge-testing/src/json. Update near-config.json with the actual data on the addresses and KeyStore
12. Compile JavaScript code from TypeScript: call $ tsc in bridge-testing folder. As a result build folder should be populated with .js files and a copy of json folder.

Ethereum to NEAR transfer

1. Approve transaction. Send an approve transaction to ERC20 contract. This step implies setting an alowance for a connector contract, so it can withdraw the tokens from your account. Arguments that you should use for this transaction: ConnectorAddress and DepositAmount. A sample script that implements sending this transaction is src/1-erc20-approve.ts. To run it use the following comand: $ node build/1-erc20-approve.js. Note: In case you're doing multiple transfers of the same ERC20 token, you can combine approvals into a single approve transaction with the sum of the amounts. This will reduce the gas costs for this step.
2. Locking transaction. Send a lock transaction to TokenLocker contract. This step implies locking of a DepositAmount tokens in a locking contract, while specifying the NEAR AccountID, where bridged tokens should be transferred. Locking method emits an event, which will be used later to prove the fact of locking of funds. See the implementation here. A sample script that implements sending this transaction is src/2-connector-lock.ts. To run it use the following CLI command: $ node build/2-connector-lock.js.
3. Wait sufficiently long. 20 confirmations for Ethereum<>NEAR mainnet deployment. This is needed to achieve finality of Ethereum block, which includes the locking transaction. The status of syncing of the bridge can be observed here. First metric (near_bridge_eth2near_client_block_number) should become more than the height of a block with transaction from the step 2 at least by 20, for successfull finalisation of the transfer.
4. Finalisation of the transfer. Call minting transaction in NEAR blockchain. This step implies calling a deposit method of the NEAR token factory contract. The method consumes Borsh-ified proof of the event, emitted during the step 2 transaction execution. The script that implements proof calculation is located at src/generate-proof.js, while the finalisation script is located at src/3-finalise-deposit.ts. To perform this step, find in the output of the step 2 a hash of the locking transaction, then use the following CLI command $ node build/3-finalise-deposit.js <TransactionHash>. Note: In case the token was not previously deployed to NEAR blockchain (was never bridged before), an additional call to deploy_bridge_token will be done automatically. This call deploys the bridged token contract and requires a deposit of 3.5 $NEAR.

NEAR to Ethereum transfer

1. Begin withdraw. Send a withdraw transaction to the bridged token contract. During the execution, a token factory contract will be called and issue a receipt, which would be used during finalisation step to contruct the proof for the locking contract in Ethereum. This step is implemented in src/4-begin-withdraw.ts. To perform this step call: $ node build/4-begin-withdraw.js.
2. Wait sufficiently long. This takes around 12 hours for the Ethereum<>NEAR mainnet deployment. This is needed to relay NEAR block with the height higher than the block with transaction from previous step to Ethereum, plus wait a challenge period (4 hours). The status of syncing of the bridge can be observed here. First metric near_bridge_near2eth_client_height should become higher than the block height displayed in console during the previous step.
3. Finalise withdraw. Send an unlock transaction to the locking contract. After bridge syncing we are able to prove the fact of the withdrawal on NEAR. Script src/5-finalise-withdraw.ts implements calculation of the correspondent proof (with the help of src/borshify-proof.js) and sends this proof in the locking contract. To perform this step, find in the output of the step 1 a receipt of the transaction, then use the following CLI command $ node build/4-finalise-withdraw.js <Receipt>.

Example of transfers

Ethereum -> NEAR transfer

• ERC20 Approve (44,046 ETH Gas)
• Lock (56,088 ETH Gas)
• Finish deposit (63 NEAR TGas)

NEAR -> Ethereum transfer

• Withdraw (13 TGas)
• Finish withdraw (286,232 ETH Gas)