Docs: updated dist files.

This commit is contained in:
Richard Moore 2020-09-08 01:12:15 -04:00
parent 2b83feb6bd
commit 6e10675adf
No known key found for this signature in database
GPG Key ID: 665176BE8E9DC651
89 changed files with 2685 additions and 1015 deletions

8
docs/api-keys/index.html Normal file

@ -0,0 +1,8 @@
<html>
<head>
<title>API Keys - ethers</title>
</head>
<body>
Redirect to /v5/api-keys.
</body>
</html>

@ -33,30 +33,12 @@ Developer Documentation
* [Gas Limit](concepts/gas)
* [Security](concepts/security)
* [Key Derivation Functions](concepts/security)
* [Provider API Keys](api-keys)
* [Etherscan](api-keys)
* [INFURA](api-keys)
* [Alchemy](api-keys)
* [Creating a Default Provider](api-keys)
* [Application Programming Interface](api)
* [Contract Interaction](api/contract)
* [Contract](api/contract/contract)
* [Creating Instances](api/contract/contract)
* [Properties](api/contract/contract)
* [Methods](api/contract/contract)
* [Events](api/contract/contract)
* [Meta-Class](api/contract/contract)
* [ContractFactory](api/contract/contract-factory)
* [Creating Instances](api/contract/contract-factory)
* [Properties](api/contract/contract-factory)
* [Methods](api/contract/contract-factory)
* [Example: ERC-20 Contract](api/contract/example)
* [Connecting to a Contract](api/contract/example)
* [Properties](api/contract/example)
* [Methods](api/contract/example)
* [Events](api/contract/example)
* [Meta-Class Methods](api/contract/example)
* [Meta-Class Filters](api/contract/example)
* [Signers](api/signer)
* [Signer](api/signer)
* [Wallet](api/signer)
* [VoidSigner](api/signer)
* [ExternallyOwnedAccount](api/signer)
* [Providers](api/providers)
* [Provider](api/providers/provider)
* [Accounts Methods](api/providers/provider)
@ -84,10 +66,34 @@ Developer Documentation
* [WebSocketProvider](api/providers/other)
* [Types](api/providers/types)
* [BlockTag](api/providers/types)
* [Networkish](api/providers/types)
* [Network](api/providers/types)
* [Block](api/providers/types)
* [Events and Logs](api/providers/types)
* [Transactions](api/providers/types)
* [Signers](api/signer)
* [Signer](api/signer)
* [Wallet](api/signer)
* [VoidSigner](api/signer)
* [ExternallyOwnedAccount](api/signer)
* [Contract Interaction](api/contract)
* [Contract](api/contract/contract)
* [Creating Instances](api/contract/contract)
* [Properties](api/contract/contract)
* [Methods](api/contract/contract)
* [Events](api/contract/contract)
* [Meta-Class](api/contract/contract)
* [ContractFactory](api/contract/contract-factory)
* [Creating Instances](api/contract/contract-factory)
* [Properties](api/contract/contract-factory)
* [Methods](api/contract/contract-factory)
* [Example: ERC-20 Contract](api/contract/example)
* [Connecting to a Contract](api/contract/example)
* [Properties](api/contract/example)
* [Methods](api/contract/example)
* [Events](api/contract/example)
* [Meta-Class Methods](api/contract/example)
* [Meta-Class Filters](api/contract/example)
* [Utilities](api/utils)
* [Application Binary Interface](api/utils/abi)
* [AbiCoder](api/utils/abi/coder)
@ -221,10 +227,14 @@ Developer Documentation
* [Plugin](cli/plugin)
* [ArgParser](cli/plugin)
* [Cookbook](cookbook)
* [React Native (and ilk)](cookbook/react-native)
* [Installing](cookbook/react-native)
* [Security](cookbook/react-native)
* [Migration Guide](migration)
* [Migration: From Web3.js](migration/web3)
* [Contracts](migration/web3)
* [Providers](migration/web3)
* [Signers](migration/web3)
* [Contracts](migration/web3)
* [Numbers](migration/web3)
* [Utilities](migration/web3)
* [Migration: From Ethers v4](migration/ethers-v4)
@ -232,9 +242,12 @@ Developer Documentation
* [Contracts](migration/ethers-v4)
* [Errors](migration/ethers-v4)
* [Interface](migration/ethers-v4)
* [Utilities](migration/ethers-v4)
* [Wallet](migration/ethers-v4)
* [Testing](testing)
* [Supported Platforms](testing)
* [Test Suites](testing)
* [Test Suite API](testing)
* [Schemas](testing)
* [Contributing and Hacking](contributing)
* [Building](contributing)
* [Making your changes](contributing)

@ -0,0 +1,35 @@
-----
Documentation: [html](https://docs.ethers.io/)
-----
Provider API Keys
=================
Etherscan
---------
INFURA
------
Alchemy
-------
Creating a Default Provider
---------------------------
```
// Use the mainnet
const network = "homestead";
// Specify your own API keys
// Each is optional, and if you omit it the default
// API key for that service will be used.
const provider = ethers.getDefaultProvider(network, {
etherscan: YOUR_ETHERSCAN_API_KEY,
infura: YOUR_INFURA_PROJECT_ID,
alchemy: YOUR_ALCHEMY_API_KEY
});
```

File diff suppressed because one or more lines are too long

@ -7,29 +7,6 @@ Documentation: [html](https://docs.ethers.io/)
Application Programming Interface
=================================
* [Contract Interaction](contract)
* [Contract](contract/contract)
* [Creating Instances](contract/contract)
* [Properties](contract/contract)
* [Methods](contract/contract)
* [Events](contract/contract)
* [Meta-Class](contract/contract)
* [ContractFactory](contract/contract-factory)
* [Creating Instances](contract/contract-factory)
* [Properties](contract/contract-factory)
* [Methods](contract/contract-factory)
* [Example: ERC-20 Contract](contract/example)
* [Connecting to a Contract](contract/example)
* [Properties](contract/example)
* [Methods](contract/example)
* [Events](contract/example)
* [Meta-Class Methods](contract/example)
* [Meta-Class Filters](contract/example)
* [Signers](signer)
* [Signer](signer)
* [Wallet](signer)
* [VoidSigner](signer)
* [ExternallyOwnedAccount](signer)
* [Providers](providers)
* [Provider](providers/provider)
* [Accounts Methods](providers/provider)
@ -57,10 +34,34 @@ Application Programming Interface
* [WebSocketProvider](providers/other)
* [Types](providers/types)
* [BlockTag](providers/types)
* [Networkish](providers/types)
* [Network](providers/types)
* [Block](providers/types)
* [Events and Logs](providers/types)
* [Transactions](providers/types)
* [Signers](signer)
* [Signer](signer)
* [Wallet](signer)
* [VoidSigner](signer)
* [ExternallyOwnedAccount](signer)
* [Contract Interaction](contract)
* [Contract](contract/contract)
* [Creating Instances](contract/contract)
* [Properties](contract/contract)
* [Methods](contract/contract)
* [Events](contract/contract)
* [Meta-Class](contract/contract)
* [ContractFactory](contract/contract-factory)
* [Creating Instances](contract/contract-factory)
* [Properties](contract/contract-factory)
* [Methods](contract/contract-factory)
* [Example: ERC-20 Contract](contract/example)
* [Connecting to a Contract](contract/example)
* [Properties](contract/example)
* [Methods](contract/example)
* [Events](contract/example)
* [Meta-Class Methods](contract/example)
* [Meta-Class Filters](contract/example)
* [Utilities](utils)
* [Application Binary Interface](utils/abi)
* [AbiCoder](utils/abi/coder)

@ -10,7 +10,7 @@ ContractFactory
Creating Instances
------------------
#### **new ***ethers* . **ContractFactory**( interface , bydecode [ , signer ] )
#### **new ***ethers* . **ContractFactory**( interface , bytecode [ , signer ] )

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -199,7 +199,7 @@ When you perform a static call, the current state is taken into account as best
Meta-Class Filters
------------------
#### *erc20* . *filters* . **Transafer**( [ fromAddress [ , toAddress ] ] ) => *Filter*
#### *erc20* . *filters* . **Transfer**( [ fromAddress [ , toAddress ] ] ) => *Filter*
Returns a new Filter which can be used to [query](/v5/api/contract/example/#erc20-queryfilter) or to [subscribe/unsubscribe to events](/v5/api/contract/example/#erc20-events).

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -14,6 +14,8 @@ Default Provider
Returns a new Provider, backed by multiple services, connected to *network*. Is no *network* is provided, **homestead** (i.e. mainnet) is used.
The *network* may also be a URL to connect to, such as `http://localhost:8545` or `wss://example.com`.
The *options* is an object, with the following properties:
@ -32,6 +34,19 @@ Many services also have monitoring and usage metrics, which are only available i
Some services also provide additional paid features, which are only available when specifying an API Key.
Networks
--------
### Custom ENS Contract
```
const network = {
name: "dev",
chianId: 1337,
ensAddress: customEnsAddress
};
```
Provider Documentation
----------------------
@ -61,6 +76,7 @@ Provider Documentation
* [WebSocketProvider](other)
* [Types](types)
* [BlockTag](types)
* [Networkish](types)
* [Network](types)
* [Block](types)
* [Events and Logs](types)

@ -162,6 +162,9 @@ provider = new AlchemyProvider("ropsten");
// Connect to mainnet with an API key (these are equivalent)
provider = new AlchemyProvider(null, apiKey);
provider = new AlchemyProvider("homestead", apiKey);
// Connect to the Alchemy WebSocket endpoints with a WebSocketProvider
provider = AlchemyProvider.getWebSocketProvider()
```
CloudflareProvider

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -123,7 +123,7 @@ This is identical to `sendAsync`. Historically, this used a synchronous web requ
WebSocketProvider
-----------------
#### **new ***ethers* . *provider* . **WebSockerProvider**( [ url [ , network ] ] )
#### **new ***ethers* . *provider* . **WebSocketProvider**( [ url [ , network ] ] )
Returns a new [WebSocketProvider](/v5/api/providers/other/#WebSocketProvider) connected to *url* as the *network*.

File diff suppressed because one or more lines are too long

@ -33,7 +33,7 @@ Returns the number of transactions *address* has ever **sent**, as of *blockTag*
```javascript
// Get the balance for an account...
provider.getBalance("ricmoo.firefly.eth");
// { Promise: { BigNumber: "1578527309436018765" } }
// { Promise: { BigNumber: "1492974808274631213" } }
// Get the code for a contract...
provider.getCode("registrar.firefly.eth");
@ -45,7 +45,7 @@ provider.getStorageAt("registrar.firefly.eth", 0)
// Get transaction count of an account...
provider.getTransactionCount("ricmoo.firefly.eth");
// { Promise: 673 }
// { Promise: 679 }
```
Blocks Methods
@ -96,7 +96,7 @@ provider.getBlockWithTransactions(100004)
// blockHash: '0xf93283571ae16dcecbe1816adc126954a739350cd1523a1559eabeae155fbb63',
// blockNumber: 100004,
// chainId: 0,
// confirmations: 10297123,
// confirmations: 10719007,
// creates: null,
// data: '0x',
// from: '0xcf00A85f3826941e7A25BFcF9Aac575d40410852',
@ -177,16 +177,16 @@ provider.getNetwork()
// The current block number
provider.getBlockNumber()
// { Promise: 10397126 }
// { Promise: 10819010 }
// Get the current suggested gas price (in wei)...
gasPrice = await provider.getGasPrice()
// { BigNumber: "19000001123" }
// { BigNumber: "69000000000" }
// ...often this gas price is easier to understand or
// display to the user in gwei (giga-wei, or 1e9 wei)
utils.formatUnits(gasPrice, "gwei")
// '19.000001123'
// '69.0'
```
Transactions Methods
@ -302,7 +302,7 @@ provider.once(txHash, (transaction) => {
filter = {
address: "dai.tokens.ethers.eth",
topics: [
utils.id("Transfer(address,address,uint256")
utils.id("Transfer(address,address,uint256)")
]
}
provider.on(filter, (log, event) => {
@ -313,7 +313,7 @@ provider.on(filter, (log, event) => {
// Notice this is an array of topic-sets and is identical to
// using a filter with no address (i.e. match any address)
topicSets = [
utils.id("Transfer(address,address,uint256"),
utils.id("Transfer(address,address,uint256)"),
null,
[
myAddress,

File diff suppressed because one or more lines are too long

@ -12,6 +12,9 @@ BlockTag
### EventType
Networkish
----------
Network
-------

File diff suppressed because one or more lines are too long

@ -285,7 +285,7 @@ contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
// Get the number of tokens for this account
tokens = await contract.balanceOf(signer.getAddress())
// { BigNumber: "9709905125722568213383" }
// { BigNumber: "11386855832278858351495" }
//
// Pre-flight (check for revert) on DAI from the signer
@ -302,7 +302,7 @@ contract.callStatic.transfer("donations.ethers.eth", tokens)
// This will fail since it is greater than the token balance
contract.callStatic.transfer("donations.ethers.eth", tokens.add(1))
// Error: call revert exception (method="transfer(address,uint256)", errorSignature="Error(string)", errorArgs=["Dai/insufficient-balance"], reason="Dai/insufficient-balance", code=CALL_EXCEPTION, version=abi/5.0.1)
// Error: call revert exception (method="transfer(address,uint256)", errorSignature="Error(string)", errorArgs=["Dai/insufficient-balance"], reason="Dai/insufficient-balance", code=CALL_EXCEPTION, version=abi/5.0.4)
```
ExternallyOwnedAccount

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -85,7 +85,7 @@ BigNumber.from(42n)
// Numbers outside the safe range fail:
BigNumber.from(Number.MAX_SAFE_INTEGER);
// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.3)
// Error: overflow (fault="overflow", operation="BigNumber.from", value=9007199254740991, code=NUMERIC_FAULT, version=bignumber/5.0.6)
```
Methods

File diff suppressed because one or more lines are too long

@ -164,20 +164,20 @@ Return a copy of *array* shuffled using [Fisher-Yates Shuffle](https://en.wikipe
```javascript
utils.randomBytes(8)
// Uint8Array [ 158, 14, 185, 6, 8, 37, 214, 172 ]
// Uint8Array [ 98, 93, 74, 126, 111, 146, 146, 3 ]
const data = [ 1, 2, 3, 4, 5, 6, 7 ];
// Returns a new Array
utils.shuffled(data);
// [
// 5,
// 2,
// 6,
// 1,
// 3,
// 4,
// 7,
// 2,
// 5,
// 6
// 3
// ]
// The Original is unscathed...

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -52,7 +52,7 @@ utils.keccak256("0x1234")
// Do NOT use UTF-8 strings that are not a DataHexstring
utils.keccak256("hello world")
// Error: invalid arrayify value (argument="value", value="hello world", code=INVALID_ARGUMENT, version=bytes/5.0.1)
// Error: invalid arrayify value (argument="value", value="hello world", code=INVALID_ARGUMENT, version=bytes/5.0.4)
// If needed, convert strings to bytes first:
utils.keccak256(utils.toUtf8Bytes("hello world"))

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -7,3 +7,7 @@ Documentation: [html](https://docs.ethers.io/)
Cookbook
========
* [React Native (and ilk)](react-native)
* [Installing](react-native)
* [Security](react-native)

File diff suppressed because one or more lines are too long

@ -0,0 +1,27 @@
-----
Documentation: [html](https://docs.ethers.io/)
-----
React Native (and ilk)
======================
Installing
----------
```
/home/ricmoo/my-react-project> npm install @ethersproject/shims --save
```
```
// Pull in the shims (BEFORE importing ethers)
import "@ethersproject/shims"
// Import the ethers library
import { ethers } from "ethers";
```
Security
--------

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -11,7 +11,7 @@ Installing
----------
```
/home/ricmoo> npm install --save ethers@next
/home/ricmoo> npm install --save ethers
```
Importing
@ -58,6 +58,20 @@ const provider = new ethers.providers.Web3Provider(window.ethereum)
// The Metamask plugin also allows signing transactions to
// send ether and pay to change state within the blockchain.
// For this, you need the account signer...
const signer = provider.getSigner()
```
Connecting to Ethereum: RPC
---------------------------
```
// If you don't specify a //url//, Ethers connects to the default
// (i.e. ``http:/\/localhost:8545``)
const provider = new ethers.providers.JsonRpcProvider();
// The provider also allows signing transactions to
// send ether and pay to change state within the blockchain.
// For this, we need the account signer...
const signer = provider.getSigner()
```
@ -67,18 +81,18 @@ const signer = provider.getSigner()
```javascript
// Look up the current block number
provider.getBlockNumber()
// { Promise: 10397126 }
// { Promise: 10819010 }
// Get the balance of an account (by address or ENS name)
// Get the balance of an account (by address or ENS name, if supported by network)
balance = await provider.getBalance("ethers.eth")
// { BigNumber: "2337132817842795605" }
// Often you will need to format the output for the user
// which prefer to see values in ether (instead of wei)
// Often you need to format the output to something more user-friendly,
// such as in ether (instead of wei)
ethers.utils.formatEther(balance)
// '2.337132817842795605'
// Or if a user enters a string in an input field, you may need
// If a user enters a string in an input field, you may need
// to convert it from ether (as a string) to wei (as a BigNumber)
ethers.utils.parseEther("1.0")
// { BigNumber: "1000000000000000000" }
@ -98,13 +112,13 @@ Contracts
---------
```javascript
// We can use an ENS name for the contract address
// You can also use an ENS name for the contract address
const daiAddress = "dai.tokens.ethers.eth";
// The ERC-20 Contract ABI, which is a common contract interface
// for tokens (this is the Human-Readable ABI format)
const daiAbi = [
// Some simple details about the token
// Some details about the token
"function name() view returns (string)",
"function symbol() view returns (string)",
@ -135,19 +149,19 @@ daiContract.symbol()
// Get the balance of an address
balance = await daiContract.balanceOf("ricmoo.firefly.eth")
// { BigNumber: "9709905125722568213383" }
// { BigNumber: "11386855832278858351495" }
// Format the DAI for displaying to the user
ethers.utils.formatUnits(balance, 18)
// '9709.905125722568213383'
// '11386.855832278858351495'
```
### State Changing Methods
```
// The DAI Contract is currently connected to the Provider,
// which is read-only. We need to connect to a Signer, so
// that we can pay to send state-changing transactions.
// which is read-only. You need to connect to a Signer, so
// that you can pay to send state-changing transactions.
const daiWithSigner = contract.connect(signer);
// Each DAI has 18 decimal places
@ -279,7 +293,7 @@ daiContract.queryFilter(filterFrom, 9843470, 9843480)
// number of entries; but they provide some useful examples
//
// List all transfers I sent in the last 10,000 blocks
// List all transfers sent in the last 10,000 blocks
daiContract.queryFilter(filterFrom, -10000)
// List all transfers ever sent to me
@ -290,11 +304,11 @@ Signing Messages
----------------
```javascript
// To sign a simple string, which can often be used for
// logging into a service, such as CryptoKitties simply
// To sign a simple string, which are used for
// logging into a service, such as CryptoKitties,
// pass the string in.
signature = await signer.signMessage("Hello World");
// '0x7b8d663c680b165bb7b0601a65d730f532fa6427b2e30f1d91ff1d929712b3a50b427a672b90c1dc48a4e5fbde292fbded51f670ab57d15d5794b6ff015649611c'
// '0x94fac815fc18f295c4860128d8960dfdb1d88acf891a48e345368f3f4d52c95e59d0f8b35d05d554905a39c63c11b66f61abf0211fcaba36bef5dfaf1ea5f1331c'
//
// A common case is also signing a hash, which is 32
@ -302,7 +316,7 @@ signature = await signer.signMessage("Hello World");
// data it MUST be an Array (or TypedArray)
//
// This string is 66 chacacters long
// This string is 66 characters long
message = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
// This array representation is 32 bytes long
@ -311,6 +325,6 @@ messageBytes = ethers.utils.arrayify(message);
// To sign a hash, you most often want to sign the bytes
signature = await signer.signMessage(messageBytes)
// '0xc791b3d29aa1754f9e392784273f076ef39ca5d81f2729c92af61f89db724a604074acbd725d9d95e1d3c9630211c8eee8e34f6d948d537dd82c11be4bcf676e1c'
// '0xa77f9018a3ad3078056d529d5ccaca8796cdb5bc84e799d13b63a53646ab73f87f0895df7bbe2ee6016c95eb78a2e77013ab8f8d4855143d3567932cb5331e881c'
```

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -8,8 +8,9 @@ Migration Guide
===============
* [Migration: From Web3.js](web3)
* [Contracts](web3)
* [Providers](web3)
* [Signers](web3)
* [Contracts](web3)
* [Numbers](web3)
* [Utilities](web3)
* [Migration: From Ethers v4](ethers-v4)
@ -17,6 +18,5 @@ Migration Guide
* [Contracts](ethers-v4)
* [Errors](ethers-v4)
* [Interface](ethers-v4)
* [Utilities](ethers-v4)
* [Wallet](ethers-v4)

@ -38,8 +38,64 @@ ethers.BigNumber.from(someValue)
Contracts
---------
### ENS Name Resolution
```
// @TODO
// v4
contract.addressPromise
// v5
contract.resolvedAddress
```
### Gas Estimation
```
// v4
contract.estimate.transfer(toAddress, amount)
// v5
contract.estimateGas.transfer(toAddress, amount)
```
### Functions
```
const abi = [
// Returns a single value
"function single() view returns (uint8)",
// Returns two values
"function double() view returns (uint8, uint8)",
];
// v4
await contract.single()
// 123
await contract.functions.single()
// 123
// v5 (notice the change in the .function variant)
await contract.single()
// 123
await contract.functions.single()
// [ 123 ]
// v4
await contract.double()
// [ 123, 5 ]
await contract.functions.double()
// [ 123, 5 ]
// v5 (no difference from v4)
await contract.double()
// [ 123, 5 ]
await contract.functions.double()
// [ 123, 5 ]
```
Errors
@ -164,15 +220,6 @@ const eventSig = eventFragment.format()
const topic = interface.getTopic(eventFragment)
```
Utilities
---------
### Renaming
```
// @TODO
```
Wallet
------

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -7,15 +7,171 @@ Documentation: [html](https://docs.ethers.io/)
Migration: From Web3.js
=======================
Providers
---------
### Connecting to Ethereum
```
// 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);
```
### Connecting to Ethereum: Metamask
```
// web3
const web3 = new Web3(Web3.givenProvider);
// ethers
const provider = new ethers.providers.Web3Provider(window.ethereum);
```
Signers
-------
### Creating signer
```
// web3
const account = web3.eth.accounts.create();
// ethers (create random new account)
const signer = ethers.Wallet.createRandom();
// ethers (connect to JSON-RPC accounts)
const signer = provider.getSigner();
```
### Signing a message
```
// web3 (using a private key)
signature = web3.eth.accounts.sign('Some data', privateKey)
// web3 (using a JSON-RPC account)
// @TODO
// ethers
signature = await signer.signMessage('Some data')
```
Contracts
---------
Providers
---------
### Deploying a Contract
```
// 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();
```
### Interacting with a Contract
```
// 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();
```
### Overloaded Functions
```
// web3
message = await contract.methods.getMessage('nice').call();
// ethers
const abi = [
"function getMessage(string) public view returns (string)",
"function getMessage() public view returns (string)"
]
const contract = new ethers.Contract(address, abi, signer);
// for ambiguous functions (two functions with the same
// name), the signature must also be specified
message = await contract['getMessage(string)']('nice');
```
Numbers
-------
### BigNumber
```
// web3
web3.utils.toBN('123456');
// ethers (from a number; must be within safe range)
ethers.BigNumber.from(123456)
// ethers (from base-10 string)
ethers.BigNumber.from("123456")
// ethers (from hex string)
ethers.BigNumber.from("0x1e240")
```
Utilities
---------
### Hash
```
// web3
web3.utils.sha3('hello world');
web3.utils.keccak256('hello world');
// ethers (hash of a string)
ethers.utils.id('hello world')
// ethers (hash of binary data)
ethers.utils.keccak256('0x4242')
```

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

@ -7,3 +7,244 @@ Documentation: [html](https://docs.ethers.io/)
Testing
=======
Supported Platforms
-------------------
Test Suites
-----------
Test Suites
Test Suite API
--------------
#### *testcases* . **loadTests**( tag ) => *Array< TestCase >*
Load all the given testcases for the *tag*.
A tag is the string in the above list of test case names not including any extenstion (e.g. `"solidity-hashes"`)
#### *testcases* . *TestCase* . **TEST_NAME**
Most testcases have its schema available as a TypeScript type to make testing each property easier.
### Deterministic Random Numbers (DRNG)
#### *testcases* . **randomBytes**( seed , lower [ , upper ] ) => *Uint8Array*
Return at least *lower* random bytes, up to *upper* (exclusive) if specified, given *seed*. If *upper* is omitted, exactly */lower* bytes are returned.
#### *testcases* . **randomHexString**( seed , lower [ , upper ] ) => *string< [DataHexString](/v5/api/utils/bytes/#DataHexString) >*
Identical to randomBytes, except returns the value as a [DataHexString](/v5/api/utils/bytes/#DataHexString) instead of a Uint8Array.
#### *testcases* . **randomNumber**( seed , lower , upper ) => *number*
Returns a random number of at least *lower* and less than *upper* given *seed*.
Schemas
-------
### Accounts
Properties
```
{
"name": "random-1023",
"address": "0x53bff74b9af2e3853f758a8d2bd61cd115d27782",
"privateKey": "0x8ab0e165c2ea461b01cdd49aec882d179dccdbdb5c85c3f9c94c448aa65c5ace",
"checksumAddress": "0x53bFf74b9Af2E3853f758A8D2Bd61CD115d27782",
"icapAddress": "XE709S6NUSJR6SXQERCMYENAYYOZ2Y91M6A"
}
```
### Contract Interface
```
{
"name": "random-1999",
"source": "contract Test {\n function test() constant returns (address, bool, bytes14[1]) {\n address a = address(0x061C7F399Ee738c97C7b7cD840892B281bf772B5);\n bool b = bool(true);\n bytes14[1] memory c;\n c[0] = bytes14(0x327621c4abe12d4f21804ed40455);\n return (a, b, c);\n }\n}\n",
"types": "[\"address\",\"bool\",\"bytes14[1]\"]",
"interface": "[{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"},{\"name\":\"\",\"type\":\"bool\"},{\"name\":\"\",\"type\":\"bytes14[1]\"}],\"type\":\"function\"}]\n",
"bytecode": "0x6060604052610175806100126000396000f360606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256",
"result": "0x000000000000000000000000061c7f399ee738c97c7b7cd840892b281bf772b50000000000000000000000000000000000000000000000000000000000000001327621c4abe12d4f21804ed40455000000000000000000000000000000000000",
"values": "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
"normalizedValues": "[{\"type\":\"string\",\"value\":\"0x061C7F399Ee738c97C7b7cD840892B281bf772B5\"},{\"type\":\"boolean\",\"value\":true},[{\"type\":\"buffer\",\"value\":\"0x327621c4abe12d4f21804ed40455\"}]]",
"runtimeBytecode": "0x60606040526000357c010000000000000000000000000000000000000000000000000000000090048063f8a8fd6d1461003957610037565b005b610046600480505061009d565b604051808473ffffffffffffffffffffffffffffffffffffffff1681526020018315158152602001826001602002808383829060006004602084601f0104600f02600301f150905001935050505060405180910390f35b600060006020604051908101604052806001905b60008152602001906001900390816100b157905050600060006020604051908101604052806001905b60008152602001906001900390816100da5790505073061c7f399ee738c97c7b7cd840892b281bf772b59250600191506d327621c4abe12d4f21804ed404557201000000000000000000000000000000000000028160006001811015610002579090602002019071ffffffffffffffffffffffffffffffffffff191690818152602001505082828295509550955061016d565b50505090919256"
}
```
### Contract Signatures
```
{
"name": "random-1999",
"sigHash": "0xf51e9244",
"abi": "[{\"constant\":false,\"inputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"name\":\"testSig\",\"outputs\":[],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"constant\":true,\"inputs\":[],\"name\":\"test\",\"outputs\":[{\"name\":\"r0\",\"type\":\"string[2]\"},{\"name\":\"r1\",\"type\":\"uint128\"},{\"components\":[{\"name\":\"a\",\"type\":\"bytes\"},{\"name\":\"b\",\"type\":\"bytes\"},{\"name\":\"c\",\"type\":\"bytes\"}],\"name\":\"r2\",\"type\":\"tuple\"},{\"name\":\"r3\",\"type\":\"bytes\"}],\"payable\":false,\"stateMutability\":\"pure\",\"type\":\"function\"}]",
"signature": "testSig(string[2],uint128,(bytes,bytes,bytes),bytes)"
}
```
### Hashes
```
{
"data": "0x3718a88ceb214c1480c32a9d",
"keccak256": "0x82d7d2dc3d384ddb289f41917b8280675bb1283f4fe2b601ac7c8f0a2c2824fa",
"sha512": "0xe93462bb1de62ba3e6a980c3cb0b61728d3f771cea9680b0fa947b6f8fb2198a2690a3a837495c753b57f936401258dfe333a819e85f958b7d786fb9ab2b066c",
"sha256": "0xe761d897e667aa72141dd729264c393c4ddda5c62312bbd21b0f4d954eba1a8d"
}
```
### Hierarchal Deterministic Node (BIP-32)
```
{
"name": "trezor-23",
"entropy": "0xf585c11aec520db57dd353c69554b21a89b20fb0650966fa0a9d6f74fd989d8f",
"mnemonic": "void come effort suffer camp survey warrior heavy shoot primary clutch crush open amazing screen patrol group space point ten exist slush involve unfold",
"locale": "en",
"password": "TREZOR",
"hdnodes": [
{
"path": "m",
"address": "0xfd8eb95169ce57eab52fb69bc6922e9b6454d9aa",
"privateKey": "0x679bf92c04cf16307053cbed33784f3c4266b362bf5f3d7ee13bed6f2719743c"
},
{
"address": "0xada964e9f10c4fc9787f9e17f00c63fe188722b0",
"privateKey": "0xdcbcb48a2b11eef0aab93a8f88d83f60a3aaabb34f9ffdbe939b8f059b30f2b7",
"path": "m/8'/8'/2/3/4"
},
{
"privateKey": "0x10fd3776145dbeccb3d6925e4fdc0d58b452fce40cb8760b12f8b4223fafdfa6",
"address": "0xf3f6b1ef343d5f5f231a2287e801a46add43eb06",
"path": "m/1'/3'"
},
{
"address": "0xb7b0fdb6e0f79f0529e95400903321e8a601b411",
"privateKey": "0x093a8ff506c95a2b79d397aed59703f6212ff3084731c2f03089b069ae76e69d",
"path": "m/8'/4'/7'"
},
{
"path": "m/7'/5'/11",
"privateKey": "0x6bd79da4dfa7dd0abf566a011bdb7cba0d28bba9ca249ba25880d5dabf861b42",
"address": "0x1b3ad5fa50ae32875748107f4b2160829cc10536"
},
{
"path": "m/9'/6'/2'/7'/3'",
"address": "0x42eb4bed59f3291d02387cf0fb23098c55d82611",
"privateKey": "0xfc173acba7bc8bb2c434965d9e99f5a221f81add421bae96a891d08d60be11dd"
}
],
"seed": "0x01f5bced59dec48e362f2c45b5de68b9fd6c92c6634f44d6d40aab69056506f0e35524a518034ddc1192e1dacd32c1ed3eaa3c3b131c88ed8e7e54c49a5d0998"
}
```
### ENS Namehash
```
{
"expected": "0x33868cc5c3fd3a9cd3adbc1e868ea133d2218f60dc2660c3bc48d8b1f4961384",
"name": "ViTalIk.WALlet.Eth",
"test": "mixed case"
}
```
### RLP Coder
```
{
"name": "arrayWithNullString3",
"encoded": "0xc3808080",
"decoded": [ "0x", "0x", "0x" ]
}
```
### Solidity Hashes
```
{
"name": "random-1999",
"keccak256": "0x7d98f1144a0cd689f720aa2f11f0a73bd52a2da1117175bc4bacd93c130966a1",
"ripemd160": "0x59384617f8a06efd57ab106c9e0c20c3e64137ac000000000000000000000000",
"sha256": "0xf9aeea729ff39f8d372d8552bca81eb2a3c5d433dc8f98140040a03b7d81ac92",
"values": [
"0xcdffcb5242e6",
"0xc1e101b60ebe4688",
"0x5819f0ef5537796e43bdcd48309f717d6f7ccffa",
"0xec3f3f9f",
false,
true
],
"types": [
"int184",
"int176",
"address",
"int64",
"bool",
"bool"
]
}
```
### Transactions
```
{
"name": "random-998",
"privateKey": "0xd16c8076a15f7fb583f05dc12686fe526bc59d298f1eb7b9a237b458133d1dec",
"signedTransactionChainId5": "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc82ea059891894eb180cb7c6c45a52f62d2103420d3ad0bc3ba518d0a25ed910842522a0155c0ea2aee2ea82e75843aab297420bad907d46809d046b13d692928f4d78aa",
"gasLimit": "0x36fcf36da03ee4",
"to": "0x9577303fd4e0acbe72c6c116acab5bf63f0b1e9c",
"data": "0x7dc8",
"accountAddress": "0x6d4a6aff30ca5ca4b8422eea0ebcb669c7d79859",
"unsignedTransaction": "0xed8391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8",
"nonce": "0x91d450",
"gasPrice": "0x8517cfba",
"signedTransaction": "0xf8708391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc81ba05030832331e6be48c95e1569a1ca9505c495486f72d6009b3a30fadfa05d9686a05cd3116b416d2362da1e9b0ca7fb1856c4e591cc22e63b395bd881ce2d3735e6",
"unsignedTransactionChainId5": "0xf08391d450848517cfba8736fcf36da03ee4949577303fd4e0acbe72c6c116acab5bf63f0b1e9c8365fdc7827dc8058080",
"value": "0x65fdc7"
}
```
### Units
```
{
"name": "one-two-three-3",
"gwei_format": "-1234567890123456.789012345",
"ether_format": "-1234567.890123456789012345",
"gwei": "-1234567890123456.789012345",
"ether": "-1234567.890123456789012345",
"finney": "-1234567890.123456789012345",
"wei": "-1234567890123456789012345",
"finney_format": "-1234567890.123456789012345"
}
```
### Wallets
```
{
"mnemonic": null,
"name": "secretstorage_password",
"type": "secret-storage",
"password": "foo",
"privateKey": "0xf03e581353c794928373fb0893bc731aefc4c4e234e643f3a46998b03cd4d7c5",
"hasAddress": true,
"json": "{\"address\":\"88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290\",\"Crypto\":{\"cipher\":\"aes-128-ctr\",\"ciphertext\":\"10adcc8bcaf49474c6710460e0dc974331f71ee4c7baa7314b4a23d25fd6c406\",\"cipherparams\":{\"iv\":\"1dcdf13e49cea706994ed38804f6d171\"},\"kdf\":\"scrypt\",\"kdfparams\":{\"dklen\":32,\"n\":262144,\"p\":1,\"r\":8,\"salt\":\"bbfa53547e3e3bfcc9786a2cbef8504a5031d82734ecef02153e29daeed658fd\"},\"mac\":\"1cf53b5ae8d75f8c037b453e7c3c61b010225d916768a6b145adf5cf9cb3a703\"},\"id\":\"fb1280c0-d646-4e40-9550-7026b1be504a\",\"version\":3}\n",
"address": "0x88a5c2d9919e46f883eb62f7b8dd9d0cc45bc290"
}
```

File diff suppressed because one or more lines are too long