From e091ab6aa1ac88086746a7ea0305e060d7d592db Mon Sep 17 00:00:00 2001 From: Marcelo Fornet Date: Fri, 6 Aug 2021 13:27:37 +0200 Subject: [PATCH] Fixing badges, and cleaning sub repositories (#590) * Update badges * First iteration of updating READMEs - Remove other READMEs and CHANGELOGs but the one in the root - Add badges --- CHANGELOG.md | 2 + MIGRATION.md | 74 ------------------- README.md | 100 +++++++++++++++----------- cli/index.js | 15 ++-- contracts/eth/CHANGELOG.md | 4 -- contracts/eth/nearbridge/README.md | 6 -- contracts/eth/nearprover/README.md | 6 -- contracts/eth/nearprover/package.json | 2 +- contracts/near/eth-client/README.md | 9 --- 9 files changed, 69 insertions(+), 149 deletions(-) delete mode 100644 MIGRATION.md delete mode 100644 contracts/eth/CHANGELOG.md delete mode 100644 contracts/eth/nearbridge/README.md delete mode 100644 contracts/eth/nearprover/README.md delete mode 100644 contracts/near/eth-client/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d726529cc..a20820761 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,9 @@ # Next release + - near2eth-relay prints more informative logs # 3.0.0 + - Use rainbow-bridge-lib 3.0.0 and rainbow-bridge-sol 2.0.0. This uses upgraded NearOnEthClient which accepts additional construction argument `replaceDuration_` that allows relay to submit header on top of header that has not passed challenge period yet. # 2.0.0 diff --git a/MIGRATION.md b/MIGRATION.md deleted file mode 100644 index 370bcad58..000000000 --- a/MIGRATION.md +++ /dev/null @@ -1,74 +0,0 @@ -# Migration Instructions - -## From 1.x to 2.0.0 - -2.0.0 introduce three incompatible change in Ethereum and NEAR contracts: bridge-token-factory, generic token locker and TToken. - -### Migration Instruction for your code - -#### Token Factory on NEAR - -Token factory is a new concept introduced in rainbow bridge lib/cli 2.0. It follows ERC721 that allow you to create multiple ERC20 tokens on NEAR. Back in 1.x, there was only one ERC token implemented as [mintable-fungible-token](https://github.com/near/rainbow-bridge-rs/tree/master/mintable-fungible-token) and only need initialize that. In 2.0, you need to first initalize the token factory contract - -https://github.com/near/rainbow-bridge-lib/blob/master/init/near-token-factory.js#L74 - -And then deploy a erc20 token in factory: - -https://github.com/near/rainbow-bridge-lib/blob/master/transfer-eth-erc20/deploy-token.js#L76 - -After that deployed erc20 token is very similar to 1.x mintable-fungible-token, you can deposit (renamed from mint, usage is same) or withdraw (renamed from burn, usage is same) it. - -#### Token Locker on Ethereum - -Token locker soldity contract has changed from: - -``` -constructor(IERC20 ethToken, bytes memory nearToken, INearProver prover) public; -function lockToken(uint256 amount, string memory accountId) public; -function unlockToken(bytes memory proofData, uint64 proofBlockHeight) public; -``` - -to: - -``` -constructor(bytes memory nearTokenFactory, INearProver prover) public; -function lockToken(IERC20 token, uint256 amount, string memory accountId) public; -function unlockToken(bytes memory proofData, uint64 proofBlockHeader) public; -``` - -You will need to call updated method. Basically, token locker in rainbow bridge lib/cli 1.x can only lock one kind of token, -specified when initialized the locker. Locker in rainbow bridge 2.0 (provided by [rainbow-token-connector](https://github.com/near/rainbow-token-connector)) can lock and unlock any erc20 token created in `nearTokenFactory`. Therefore when locking, which token to lock is required parameter. - -#### TToken on Ethereum - -[MyERC20.sol](https://github.com/near/rainbow-bridge-sol/blob/a3968cee82f2923aee9fbe2387b7045993eafc0f/token-locker/contracts/MyERC20.sol) in rainbow bridge 1.0 has been replaced with [TToken.sol](https://github.com/near/rainbow-token-connector/blob/master/erc20-connector/contracts/test/TToken.sol). This is a compatible change. - -### Migration Instruction to Use NEAR Deployed Contracts and Bridge Services - -You only need to update the config file to use new contract addresses, see [Using Bridge on Testnet](README.md#using-bridge-on-testnet) and look for `rainbow-bridge-cli 2.x` - -### Migration Instruction for Deployment - -If you are deploying your own bridge, eth2near relayer, near2eth relayer, eth ed25519, eth client, eth prover, near client and near prover can be reused. you need to remove these lines from your `~/.rainbow/config.json`: - -``` - "ethErc20Address": "...", - "ethLockerAddress": "...", - "nearFunTokenAccount": "..." -``` - -And add this line: - -``` - "nearTokenFactoryAccount": "fill a non exist near account in your namespace, going to be created as your token factory account", -``` - -Then redeploy these contracts: - -``` -rainbow init-eth-erc20 # use TToken -rainbow init-eth-locker # use new generic locker -rainbow init-near-token-factory # use token factory -``` - -You should be able to use bridge again with same transfer from near and to near command as before! diff --git a/README.md b/README.md index cbebf9b87..9d5a9a06a 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,14 @@

- Buildkite Build - npm + Build status + Bridge Version + Telegram Chat

## Table of Contents + - [Pre-requisites](#pre-requisites) - [Usage](#usage) - [Security](#security) @@ -47,6 +49,7 @@ rustup target add wasm32-unknown-unknown - python3 pip , for nearup #### Install nearup + ```bash pip3 install nearup @@ -91,10 +94,11 @@ As of 2020-07-14 (gas price is 40 gwei) the cost of running bridge on NEAR mainn ### PoA vs PoW Ethereum networks Rainbow bridge can be deployed either on PoW or PoA networks. However, the main use case of the bridge is Ethereum Mainnet, which makes its design very PoW-centric and it is only trustless and decentralized for PoW networks. Unfortunately, the only popular PoW testnet is Ropsten, which frequently undergoes huge reorgs of more than [16k blocks](https://github.com/near/rainbow-bridge-cli/issues/329), because people test 51% attacks on it. 16k reorgs can wipe out entire contracts and revert days of computations. Overall, Ropsten has the following unfortunate specifics that does not exist with Ethereum Mainnet: -* Extremely long re-orgs; -* Gas price volatility -- Ropsten blocks might have orders of magnitude different median gas price; -* Slow block production -- sometimes Ropsten blocks are produced once per several minutes; -* [Infura is unreliable on Ropsten](https://github.com/near/rainbow-bridge-cli/issues/330) + +- Extremely long re-orgs; +- Gas price volatility -- Ropsten blocks might have orders of magnitude different median gas price; +- Slow block production -- sometimes Ropsten blocks are produced once per several minutes; +- [Infura is unreliable on Ropsten](https://github.com/near/rainbow-bridge-cli/issues/330) Therefore we advise users to not use Ropsten for bridge testing. Instead, we recommend using one of Ethereum's PoA testnet. Unfortunately, PoA networks have a differen header format and are also centralized by nature. Therefore when deploying bridge on PoA network please use `--near-client-trusted-signer` parameter. This will force `EthOnNearClient` to not validate Ethereum headers (since PoA headers are not valid PoW headers) and accept them only from the provided authority. @@ -105,85 +109,95 @@ The documenation below assumes Rinkeby testnet. This section explains how to use existing bridge with mock ERC20 token that was already deployed. You would need to have some amount of this token on Rinkeby, so reach out to max@near.org if you want to give it a try. We assume you have two accounts: -* One NEAR account on NEAR testnet with at least 1 NEAR token. We denote it as `` and its secret key as ``; -* One Ethereum account on Rinkeby testnet with at least 1 ETH and 100 ERC20 tokens (this example uses ERC20 deployed to `0x8151a8F90267bFf183E06921841C5dE774499388` as an example. If you want some of these ERC20 tokens please contact max@near.org). We denote it as `` and its private key as ``; + +- One NEAR account on NEAR testnet with at least 1 NEAR token. We denote it as `` and its secret key as ``; +- One Ethereum account on Rinkeby testnet with at least 1 ETH and 100 ERC20 tokens (this example uses ERC20 deployed to `0x8151a8F90267bFf183E06921841C5dE774499388` as an example. If you want some of these ERC20 tokens please contact max@near.org). We denote it as `` and its private key as ``; Make sure you have rainbow cli installed: + ```bash yarn install ``` If you have already used the bridge on this machine run a cleanup: + ```bash cli/index.js clean ``` If you're using rainbow-bridge-cli 1.x, create `~/.rainbow/config.json` file with the following content: + ```json { - "nearNetworkId": "testnet", - "nearNodeUrl": "https://rpc.testnet.near.org/", - "ethNodeUrl": "https://rinkeby.infura.io/v3/", - "nearMasterAccount": "", - "nearMasterSk": "", - "nearClientAccount": "ethonnearclient10", - "nearProverAccount": "ethonnearprover10", - "nearClientTrustedSigner": "eth2nearrelay10.testnet", - "ethMasterSk": "", - "ethEd25519Address": "0x9003342d15B21b4C42e1702447fE2f39FfAF55C2", - "ethClientAddress": "0xF721c979db97413AA9D0F91ad531FaBF769bb09C", - "ethProverAddress": "0xc5D62d66B8650E6242D9936c7e50E959BA0F9E37", - "ethErc20Address": "0x8151a8F90267bFf183E06921841C5dE774499388", - "ethLockerAddress": "0x5f7Cc23F90b5264a083dcB3b171c7111Dc32dD00", - "nearFunTokenAccount": "mintablefuntoken11" + "nearNetworkId": "testnet", + "nearNodeUrl": "https://rpc.testnet.near.org/", + "ethNodeUrl": "https://rinkeby.infura.io/v3/", + "nearMasterAccount": "", + "nearMasterSk": "", + "nearClientAccount": "ethonnearclient10", + "nearProverAccount": "ethonnearprover10", + "nearClientTrustedSigner": "eth2nearrelay10.testnet", + "ethMasterSk": "", + "ethEd25519Address": "0x9003342d15B21b4C42e1702447fE2f39FfAF55C2", + "ethClientAddress": "0xF721c979db97413AA9D0F91ad531FaBF769bb09C", + "ethProverAddress": "0xc5D62d66B8650E6242D9936c7e50E959BA0F9E37", + "ethErc20Address": "0x8151a8F90267bFf183E06921841C5dE774499388", + "ethLockerAddress": "0x5f7Cc23F90b5264a083dcB3b171c7111Dc32dD00", + "nearFunTokenAccount": "mintablefuntoken11" } ``` If you are using rainbow-bridge-cli 2.x, create `~/.rainbow/config.json` file with the following content: + ```json { - "nearNetworkId": "testnet", - "nearNodeUrl": "https://rpc.testnet.near.org/", - "ethNodeUrl": "https://rinkeby.infura.io/v3/", - "nearMasterAccount": "", - "nearMasterSk": "", - "nearClientAccount": "ethonnearclient10", - "nearProverAccount": "ethonnearprover10", - "nearClientTrustedSigner": "eth2nearrelay10.testnet", - "ethMasterSk": "", - "ethEd25519Address": "0x9003342d15B21b4C42e1702447fE2f39FfAF55C2", - "ethClientAddress": "0xF721c979db97413AA9D0F91ad531FaBF769bb09C", - "ethProverAddress": "0xc5D62d66B8650E6242D9936c7e50E959BA0F9E37", - "nearTokenFactoryAccount": "ntf4.bridge2.testnet", - "ethErc20Address": "0x21e7381368baa3f3e9640fe19780c4271ad96f37", - "ethLockerAddress": "0x7f66c116a4f51e43e7c1c33d3714a4acfa9c40fb", - "nearErc20Account": "21e7381368baa3f3e9640fe19780c4271ad96f37.ntf4.bridge2.testnet" + "nearNetworkId": "testnet", + "nearNodeUrl": "https://rpc.testnet.near.org/", + "ethNodeUrl": "https://rinkeby.infura.io/v3/", + "nearMasterAccount": "", + "nearMasterSk": "", + "nearClientAccount": "ethonnearclient10", + "nearProverAccount": "ethonnearprover10", + "nearClientTrustedSigner": "eth2nearrelay10.testnet", + "ethMasterSk": "", + "ethEd25519Address": "0x9003342d15B21b4C42e1702447fE2f39FfAF55C2", + "ethClientAddress": "0xF721c979db97413AA9D0F91ad531FaBF769bb09C", + "ethProverAddress": "0xc5D62d66B8650E6242D9936c7e50E959BA0F9E37", + "nearTokenFactoryAccount": "ntf4.bridge2.testnet", + "ethErc20Address": "0x21e7381368baa3f3e9640fe19780c4271ad96f37", + "ethLockerAddress": "0x7f66c116a4f51e43e7c1c33d3714a4acfa9c40fb", + "nearErc20Account": "21e7381368baa3f3e9640fe19780c4271ad96f37.ntf4.bridge2.testnet" } ``` You can get infura project id, by registering at [infura.io](http://infura.io/). To transfer ERC20 from ETH to NEAR run: + ```bash cli/index.js TESTING transfer-eth-erc20-to-near --amount 10 --eth-sender-sk --near-receiver-account ``` (If the command interrupts in the middle re-run it and it will resume the transfer. PoA RPC sometimes has issues) Wait for the transfer to finish. You should see: + ``` Transferred Balance of after the transfer is 10 ``` To transfer ERC20 back from NEAR to ETH run: + ```bash cli/index.js TESTING transfer-eth-erc20-from-near --amount 1 --near-sender-account --near-sender-sk --eth-receiver-address ``` You should see: + ``` ERC20 balance of after the transfer: 91 ``` + Congratulations, you have achieved a roundtrip of ERC20 token through the bridge!