From db7202578dad6c44b1e1037c77eff59374101f42 Mon Sep 17 00:00:00 2001
From: Yuet Loo Wong <contact@yuetloo.com>
Date: Mon, 6 Jul 2020 17:47:51 -0400
Subject: [PATCH] migration from web3

---
 docs.wrm/migration/web3.wrm | 165 +++++++++++++++++++++++++++++++++++-
 1 file changed, 162 insertions(+), 3 deletions(-)

diff --git a/docs.wrm/migration/web3.wrm b/docs.wrm/migration/web3.wrm
index c10b9c021..9c0abd322 100644
--- a/docs.wrm/migration/web3.wrm
+++ b/docs.wrm/migration/web3.wrm
@@ -1,13 +1,172 @@
 _section: Migration: From Web3.js
 
-TODO
-
-_subsection: Contracts
+This migration guide focuses on migrating web3.js version 1.2.9 to ethers.js v5.
 
 _subsection: Providers
 
+In ethers, a provider provides an abstraction for a connection to the Ethereum Network. It can be used to issue read only queries and send signed state changing transactions to the Ethereum Network.
+
+_heading: Connecting to Ethereum
+
+_code: @lang<script>
+
+// web3
+var Web3 = require('web3');
+var web3 = new Web3('http://localhost:8545');
+
+// ethers
+var ethers = require('ethers');
+const url = "http://127.0.0.1:8545";
+const provider = new ethers.providers.JsonRpcProvider(url);
+
+
+_heading: Connecting to Ethereum: Metamask
+
+
+_code: @lang<script>
+
+// web3
+const web3 = new Web3(Web3.givenProvider);
+
+// ethers
+import { ethers } from "./dist/ethers.esm.js";
+const provider = new ethers.providers.Web3Provider(window.ethereum);
+
+_subsection: Signers
+
+In ethers, a **signer** is an abstraction of an Ethereum Account. It can be used to sign messages and transactions and send signed transactions to the Ethereum Network.
+
+In web3, an account can be used to sign messages and transactions.
+
+_heading: Creating signer
+
+_code: @lang<script>
+
+// web3
+const account = web3.eth.accounts.create();
+
+// ethers
+const signer = ethers.Wallet.createRandom();
+// getting signer from JSON RPC providers
+const signer = provider.getSigner();
+
+_heading: Signing a message
+
+_code: @lang<script>
+
+// web3
+let signature = web3.eth.accounts.sign('Some data', privateKey);
+
+// ethers
+let signature = await signer.signMessage('Some data');
+
+_subsection: Contracts
+
+A contract object is an abstraction of a smart contract on the Ethereum Network. It allows for easy interaction with the smart contact.
+
+_heading: Deploying a Contract
+
+_code: @lang<script>
+
+// web3
+const contract = new web3.eth.Contract(abi);
+contract.deploy({
+   data: bytecode,
+   arguments: ["my string"]
+})
+.send({
+   from: "0x12598d2Fd88B420ED571beFDA8dD112624B5E730",
+   gas: 150000,
+   gasPrice: "30000000000000"
+}), function(error, transactionHash){ ... })
+.then(function(newContract){
+    console.log('new contract', newContract.options.address) 
+});
+
+// ethers
+const signer = provider.getSigner();
+const factory = new ethers.ContractFactory(abi, bytecode, signer);
+const contract = await factory.deploy("hello world");
+console.log('contract address', contract.address);
+
+// wait for contract creation transaction to be mined
+await contract.deployTransaction.wait();
+
+
+_heading: Interacting with a Contract
+
+_code: @lang<script>
+
+// web3
+const contract = new web3.eth.Contract(abi, contractAddress);
+// read only query
+contract.methods.getValue().call();
+// state changing operation
+contract.methods.changeValue(42).send({from: ....})
+.on('receipt', function(){
+    ...
+});
+
+// ethers
+// pass a provider when initiating a contract for read only queries
+const contract = new ethers.Contract(contractAddress, abi, provider);
+const value = await contract.getValue();
+
+
+// pass a signer to create a contract instance for state changing operations
+const contract = new ethers.Contract(contractAddress, abi, signer);
+const tx = await contract.changeValue(33);
+
+// wait for the transaction to be mined
+const receipt = await tx.wait();
+
+
+_heading: Overloaded Functions
+
+Overloaded functions are functions that have the same name but different parameter types. In ethers, the syntax to call an overloaded contract function is different from the non-overloaded function. This section shows the differences between web3 and ethers when calling overloaded functions. See [issue #407](https://github.com/ethers-io/ethers.js/issues/407) for more details.
+
+_code: @lang<script>
+
+// web3
+const message = await contract.methods.getMessage('nice').call();
+console.log('message', message);
+
+
+// ethers
+const abi = ['function getMessage(string memory prefix) public view returns (string memory)',
+             'function getMessage() public view returns (string memory)'];
+const contract = new ethers.Contract(address, abi, signer);
+
+// this is how ethers identifies which function to call for overloaded functions
+const message = await contract['getMessage(string)']('nice');
+console.log('message', message);
+
 _subsection: Numbers
 
+_heading: BigNumber
+
+Convert to BigNumber:
+
+_code: @lang<script>
+
+// web3
+const bn = web3.utils.toBN('123456');
+
+// ethers
+const bn = ethers.BigNumber.from(123456);
+
 _subsection: Utilities
 
+_heading: Hash
+
+Computing Keccak256 hash of a UTF-8 string in web3 and ethers:
+
+_code: @lang<script>
+
+// web3
+web3.utils.sha3('hello world');
+web3.utils.keccak256('hello world');
+
+// ethers
+ethers.utils.id('hello world')