Readme update and rewrite, and check for accuracy

omgnetwork · May 10, 2021 · 3ff2bc5 · 3ff2bc5
1 parent b8c9303
commit 3ff2bc5
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 89 deletions.
diff --git a/.env.example b/.env.example
@@ -1,10 +1,10 @@
 # Rinkeby
 NODE_ENV=local
-L1_NODE_WEB3_URL=
+L1_NODE_WEB3_URL=https://rinkeby.infura.io/v3/YOUR_INFURA_KEY_HERE
 L2_NODE_WEB3_URL=http://3.85.224.26:8545
 ETH1_ADDRESS_RESOLVER_ADDRESS=0xa32cf2433ba24595d3aCE5cc9A7079d3f1CC5E0c
-TEST_PRIVATE_KEY_1=
-TEST_PRIVATE_KEY_2=
+TEST_PRIVATE_KEY_1=0xPRIVATE_KEY_OF_THE_FIRST_TEST_WALLET
+TEST_PRIVATE_KEY_2=0xPRIVATE_KEY_OF_THE_SECOND_TEST_WALLET
 TARGET_GAS_LIMIT=9000000000
 CHAIN_ID=28
 

diff --git a/README.md b/README.md
@@ -1,37 +1,39 @@
-# Integration Tests
-
-Typescript based integration test repo for OMGX.
-
-- [1. Basic Setup and Configuration](#1-basic-setup-and-configuration)
-  * [1.1 Using Rinkeby Testnet](#11-using-rinkeby-testnet)
-  * [1.2 Using Local Net](#12-using-local-net)
-- [2. Running the Integration Tests](#2-running-the-integration-tests)
-- [3. Wallet Specific Smart Contracts](#3-wallet-specific-smart-contracts)
-  * [3.1 L1liquidityPool.sol](#31-l1liquiditypoolsol)
-    + [Known Gaps/Problems](#known-gaps/problems)
-    + [Initial values](#initial-values)
-    + [Events](#events)
-    + [Functions](#functions)
-  * [3.2 L2liquidityPool.sol](#32-l2liquiditypoolsol)
-  * [3.3 Deploy Liquidity Pools](#33-deploy-liquidity-pools)
-  * [3.4 AtomicSwap](#34-atomicswap)
-    + [Functions](#functions-1)
-
-If you want to run these locally, you need a local OMGX system. 
+# OMGX Web Wallet, Related Smart Contracts, and Integration Tests
+
+- [OMGX Web Wallet, Related Smart Contracts, and Integration Tests](#omgx-web-wallet--related-smart-contracts--and-integration-tests)
+  * [1. Basic Setup and Configuration](#1-basic-setup-and-configuration)
+    + [1.1 Using Rinkeby Testnet](#11-using-rinkeby-testnet)
+    + [1.2 Using Local Testnet](#12-using-local-testnet)
+  * [2. Running the Integration Tests](#2-running-the-integration-tests)
+  * [3. Wallet Specific Smart Contracts](#3-wallet-specific-smart-contracts)
+    + [3.1 L1liquidityPool.sol](#31-l1liquiditypoolsol)
+      - [Known Gaps/Problems](#known-gaps-problems)
+      - [Initial values](#initial-values)
+      - [Events](#events)
+      - [Functions](#functions)
+    + [3.2 L2liquidityPool.sol](#32-l2liquiditypoolsol)
+    + [3.3 Deploy Liquidity Pools](#33-deploy-liquidity-pools)
+    + [3.4 AtomicSwap](#34-atomicswap)
+      - [Functions](#functions-1)
+    + [3.5 ERC721Mock aka NFTs](#35-erc721mock-aka-nfts)
+  * [4. Running the Web Wallet](#4-running-the-web-wallet)
+    + [.ENV Settings](#env-settings)
+    + [MetaMask Settings](#metamask-settings)
+    + [Wallet Use and Supported Functions](#wallet-use-and-supported-functions)
 
 ## 1. Basic Setup and Configuration
 
-Create a `.env` file in the root directory of this project. Add environment-specific variables on new lines in the form of `NAME=VALUE`. 
+Create a `.env` file in the root directory of this project. Add environment-specific variables on new lines in the form of `NAME=VALUE`. Examples are given in the `.env.example` file. Just pick which net you want to work on and copy either the "Rinkeby" _or_ the "Local" envs to your `.env`.
 
 ### 1.1 Using Rinkeby Testnet
 
-If you just want to work on the wallet, you can use the stable testnet on Rinkeby (ChainID 4) and AWS. To test on Rinkeby, you will need an Infura key and two accounts with Rinkeby ETH in them. The test wallets must contain enough ETH to cover the tests. The `.env` parameters are
+The stable general purpose testnet is on Rinkeby (ChainID 4) and AWS. To test on Rinkeby, you will need an Infura key and two accounts with Rinkeby ETH in them. The test wallets must contain enough ETH to cover the tests. The `.env` parameters are
 
 ```bash
 
 NODE_ENV=local
-L1_NODE_WEB3_URL=https://rinkeby.infura.io/v3/KEY
-L2_NODE_WEB3_URL=http://54.161.5.63:8545
+L1_NODE_WEB3_URL=https://rinkeby.infura.io/v3/YOUR_INFURA_KEY_HERE
+L2_NODE_WEB3_URL=http://3.85.224.26:8545
 ETH1_ADDRESS_RESOLVER_ADDRESS=0xa32cf2433ba24595d3aCE5cc9A7079d3f1CC5E0c
 TEST_PRIVATE_KEY_1=0xPRIVATE KEY OF THE FIRST TEST WALLET
 TEST_PRIVATE_KEY_2=0xPRIVATE KEY OF THE SECOND TEST WALLET
@@ -40,9 +42,7 @@ CHAIN_ID=28
 
 ```
 
-If you do not know what these values are, you can get them from the values written to the terminal as your local OMGX spins up. 
-
-### 1.2 Using a Local Testnet
+### 1.2 Using Local Testnet
 
 If would like to change the wallet-associated smart contracts and/or work on other aspects of the system, you should run a local development system. You can do this by
 
@@ -56,17 +56,17 @@ $ ./up_local.sh
 
 ```
 
-As the system boots, you'll see several things zip by in the terminal that you will need to correctly configure your `.env`, namely the values for the
+As the system boots, you'll see several things in the terminal that you will need to correctly configure your `.env`, namely the values for the
 
 ```bash
 
 ETH1_ADDRESS_RESOLVER_ADDRESS=0x______
 TEST_PRIVATE_KEY_1=0x_____
-TEST_PRIVATE_KEY_2=0x______
+TEST_PRIVATE_KEY_2=0x_____
 
 ```
 
-For the test private keys, we normally use the ones generated by hardhat as it sets up the local L1. Each of those is funded with 1000 ETH. You can get the test private keys from the hardhat (`l1_chain`) Docker terminal or from your main terminal. You will also need the `ADDRESS_RESOLVER_ADDRESS`, which will zip by as your local system deploys (see the `deployer` Docker terminal output or your main terminal window). Fill these values into your `.env`. Your final `.env` should look something like this
+For the test private keys, we normally use the ones generated by hardhat as it sets up the local L1. Each of those is funded with 1000 ETH. You can get the test private keys from the hardhat (`l1_chain`) Docker terminal or from your main terminal. You will also need the `ADDRESS_RESOLVER_ADDRESS`, which will zip by as your local system deploys (see the `deployer` Docker terminal output or your main terminal window). Your `.env` should look something like this
 
 ```bash
 
@@ -83,15 +83,18 @@ CHAIN_ID=28
 
 ## 2. Running the Integration Tests
 
+Note that the integration tests also set up parts of the system that the web wallet will need to work, such as liquidity pools and bridge contracts. 
+
 ```bash
 
 $ yarn install
-$ yarn build #builds the contracts
+$ yarn build  #builds the contracts
 $ yarn deploy #if needed - this will test and deploy the contracts, and write their addresses to /deployments/addresses.json
+              #you do not need to deploy onto Rinkeby (unless you really want to) since all the needed contracts are already #deployed and tested
 
 ```
 
-The information generated during the deploy (e.g the `/deployments/addresses.json`) is used by the web wallet front end to set things up correctly. **The full test suite includes some very slow transactions such as withdrawals, which can take 300 seconds each. Please be patient.**
+The information generated during the deploy (e.g the `/deployment/local/addresses.json`) is used by the web wallet to set things up correctly. **The full test suite includes some very slow transactions such as withdrawals, which can take 100 seconds to complete. Please be patient.**
 
 ## 3. Wallet Specific Smart Contracts
 
@@ -107,10 +110,7 @@ The Layer 1 liquidity pool accepts ERC20 and ETH. `L1liquidityPool.sol` charges
 
 #### Known Gaps/Problems
 
-- [ ] The contract owner can't currently get funds back out of the liquidy pool.
-- [ ] Fee calculations are unsafe.
-- [ ] Need to verify correct usage of the withdraw/transfer patterns.
-- [ ] Need to verify correct access limitations.
+- [ ] The contract owner can't currently get funds back out of the liquidy pool. This is a bug/feature, depending.
 - [ ] Need system to allow _others_ to add liquidity and pay them for their liquidity.
 
 #### Initial values
@@ -140,30 +140,30 @@ The Layer 1 liquidity pool accepts ERC20 and ETH. `L1liquidityPool.sol` charges
 
 ### 3.2 L2liquidityPool.sol
 
-Just like the contract for L1, but with small changes e.g. to deal with the fact that the L2 does not have native ETH.
+Just like the contract for L1, but with changes e.g. to deal with the fact that the L2 does not have native ETH.
 
 ### 3.3 Deploy Liquidity Pools
 
-If you are working on a local testnet, please deploy **L2LiquidityPool.sol** first, then use the address of **L2LiquidityPool** as the parameter for deploying the **L1Liquidity**. See **/test/setup_test.spec.ts** to see the whole process.
+If you are working on a local testnet, please deploy **L2LiquidityPool.sol** first, then use the address of **L2LiquidityPool** as the parameter for deploying the **L1Liquidity**. See **/test/a_setup.spec.ts** to see the whole process.
 
 ```javascript
 
-  L2LiquidityPool = await Factory__L2LiquidityPool.deploy(
-    env.watcher.l2.messengerAddress,
-  )
-  await L2LiquidityPool.deployTransaction.wait()
-  
-  L1LiquidityPool = await Factory__L1LiquidityPool.deploy(
-    L2LiquidityPool.address,
-    env.watcher.l1.messengerAddress,
-    env.L2ETHGateway.address,
-    3
-  )
-  await L1LiquidityPool.deployTransaction.wait()
-  
-  const L2LiquidityPoolTX = await L2LiquidityPool.init(L1LiquidityPool.address, "3")
-  await L2LiquidityPoolTX.wait()
-  console.log(' L2 LP initialized:',L2LiquidityPoolTX.hash);
+L2LiquidityPool = await Factory__L2LiquidityPool.deploy(
+  env.watcher.l2.messengerAddress,
+)
+await L2LiquidityPool.deployTransaction.wait()
+
+L1LiquidityPool = await Factory__L1LiquidityPool.deploy(
+  L2LiquidityPool.address,
+  env.watcher.l1.messengerAddress,
+  env.L2ETHGateway.address,
+  3 //this is the 3% fee
+)
+await L1LiquidityPool.deployTransaction.wait()
+
+const L2LiquidityPoolTX = await L2LiquidityPool.init(L1LiquidityPool.address, "3")
+await L2LiquidityPoolTX.wait()
+console.log(' L2 LP initialized:',L2LiquidityPoolTX.hash);
 
 ```
 
@@ -176,10 +176,16 @@ Used to swap ERC20 tokens.
 * `open` creates **Swap** struct, which contains the information of the buyer and sender.
 * `close` closes the swap. It swaps the ERC20 tokens of the sender and the buyer.
 * `expire` sets the status of the swap to be **EXPIRED**.
-* `check` returns the **Swap** construct
+* `check` returns the **Swap** construct.
+
+### 3.5 ERC721Mock aka NFTs
+
+This contract sets up a very rudimentary interface to the @OpenZeppelin ERC721 contracts. Used to set up a very basic NFT system where the owner can mint NFTs and send them to others, who can then see their NFTs. Have a look at Alice's NFTs.
 
 ## 4. Running the Web Wallet
 
+The web wallet is a react front end that makes it easy to see your balances, transfer funds, and build on for your own uses. The code is deliberately basic, to make it easy for you to repurpose it for your own needs. It's a work in progress - for example, we are adding some basic support for NFTs and and an interface for people to contribute to the conjoined liquidity pools that live on the L1 and L2. 
+
 ```bash
 
 $ cd /wallet 
@@ -188,50 +194,36 @@ $ yarn start
 
 ```
 
-You will need to set up MetaMask to know about the two accounts you are using for local testing. You will need to point MetaMask at your local chains (at :9545 and :8545) and add the account used for testing, which is typically whatever you used a `TEST_PRIVATE_KEY_2` aka `Alice`:
+### .ENV Settings
+
+Create a `.env` in `/wallets` and provide your Infura and Etherscan keys:
 
 ```bash
 
-TEST_PRIVATE_KEY_2=0x23d9aeeaa08ab710a57972eb56fc711d9ab13afdecc92c89586e0150bfa380a6
+REACT_APP_INFURA_ID=
+REACT_APP_ETHERSCAN_API=
 
 ```
 
-### Metamask Settings
-
-You also need to add networks to your MetaMask: 
-
-* Local L1
-
-  ```
-  URL = http://localhost:9545
-  ChainID = 31337
-  ```
+At that point, the wallet will start when you run `$ yarn start`. You can interact with the wallet at `http://localhost:3000.`
 
-* Local L2
+### MetaMask Settings
 
-  ```
-  URL = http://localhost:8545
-  ChainID = 28
-  ```
+On the MetaMask side, some set up is needed.
 
-> You might have to reset MetaMask when you re-start the local network. The reset button is in **Settings > Advanced > Reset Account**.
+1. Add your two test accounts to MetaMask (through **MetaMask>Import Account**). In the test code, PK_1 is the `Bob` account, and PK_2 is the `Alice`  account. 
 
-* Rinkeby L1
+2. You also need to point Metamask at the correct chain. 
+  * For work on Rinkeby L1, chose **MetaMask>Networks>Rinkeby Test Network**.
+  * For work on the OMGX Rinkeby L2, chose **MetaMask>Networks>Custom RPC** and enter `http://3.85.224.26:8545` with a ChainID of 28.
+  * For work on a local L1, chose **MetaMask>Networks>Custom RPC** and enter `http://localhost:9545` with a ChainID of 31337.
+  * For work on a local OMGX L2, chose **MetaMask>Networks>Custom RPC** and enter `http://localhost:8545` with a ChainID of 28.
 
-  Select the dewfault Rinkeby Test Network
-
-* OMGX L2
-
-  ```
-  URL = http://18.208.138.49:8545
-  ChainID = 28
-  ```
+*NOTE* You might have to reset MetaMask when you re-start the local network. The reset button is in **MetaMask>Settings>Advanced>Reset Account**.
 
 ### Wallet Use and Supported Functions
 
-1. Open the MetaMask browser extension and click on your currently connected network at the top pane, next to your jazzicon.
-
-2. You'll see a modal open up with list of networks. If you are working on a local system, click on the "Custom RPC" button at the very bottom. Enter/select your L1 and L2 network parameters.
+1. Open the MetaMask browser extension and select the chain you want to work on.
 
-3. Account Page. here you can see your balances, and move tokens from L1 to L2, and back. 
+2. On the top right of the wallet landing page, select either `local` or `rinkeby`. You will then be taken to your account page. Here you can see your balances and move tokens from L1 to L2, and back, for example.