tornado-packages/ethers.js
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Check-in old v5 docs changes.

Browse Source
This commit is contained in:
Richard Moore 2020-06-09 23:56:58 -04:00
parent ddad98ab32
commit 716ec324d0
No known key found for this signature in database
GPG Key ID: 665176BE8E9DC651
265 changed files with 30659 additions and 6042 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/README.md
View File

@ -7,66 +7,50 @@ Documentation: [html](https://docs-beta.ethers.io/)
Documentation
=============
What is Ethers?
---------------
The ethers.js library aims to be a complete and compact library for
interacting with the Ethereum Blockchain and its ecosystem. It was
originally designed for use with [ethers.io](Users/ricmoo/Development/ethers/ethers.js-v5/https:/ethers.io) and
has since expanded into a much more general-purpose library.
Features
--------
* Keep your private keys in your client, **safe** and sound
* Import and export **JSON wallets** (Geth, Parity and crowdsale)
* Import and export BIP 39 **mnemonic phrases** (12 word backup phrases) and HD Wallets (English, Italian, Japanese, Korean, Simplified Chinese, Traditional Chinese; more coming soon)
* Meta-classes create JavaScript objects from any contract ABI, including **ABIv2** and **Human-Readable ABI**
* Connect to Ethereum nodes over [JSON-RPC](Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/wiki/wiki/JSON-RPC), [INFURA](Users/ricmoo/Development/ethers/ethers.js-v5/https:/infura.io), [Etherscan](Users/ricmoo/Development/ethers/ethers.js-v5/https:/etherscan.io), [Alchemy](Users/ricmoo/Development/ethers/ethers.js-v5/https:/alchemyapi.io), [Cloudflare](Users/ricmoo/Development/ethers/ethers.js-v5/https:/developers.cloudflare.com/distributed-web/ethereum-gateway) or [MetaMask](Users/ricmoo/Development/ethers/ethers.js-v5/https:/metamask.io).
* **ENS names** are first-class citizens; they can be used anywhere an Ethereum addresses can be used
* **Tiny** (~88kb compressed; 284kb uncompressed)
* **Complete** functionality for all your Ethereum needs
* Extensive [documentation](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io)
* Large collection of **test cases** which are maintained and added to
* Fully **TypeScript** ready, with definition files and full TypeScript source
* **MIT License** (including *ALL* dependencies); completely open source to do with as you please
Developer Documentation
-----------------------
* [Getting Started](getting-started)
* [Installing](getting-started)
* [Importing](getting-started)
* [Concepts](concepts)
* [Common Terminology](getting-started)
* [Connecting to Ethereum: Metamask](getting-started)
* [Contracts](getting-started)
* [Signing Messages](getting-started)
* [Ethereum Basics](concepts)
* [Events](concepts/events)
* [Solidity Topics](concepts/events)
* [Logs and Filtering](concepts/events)
* [Gas](concepts/gas)
* [Gas Price](concepts/gas)
* [Gas Limit](concepts/gas)
* [Security](concepts/security)
* [Key Derivation Functions](concepts/security)
* [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 ^^//(inheritted from [[contract]])//^^](api/contract/example)
* [Methods ^^//(inheritted from [[contract]])//^^](api/contract/example)
* [Events ^^//(inheritted from Contract)//^^](api/contract/example)
* [Meta-Class Methods ^^//(added at Runtime)//^^](api/contract/example)
* [Meta-Class Filters ^^//(added at Runtime)//^^](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)
@ -85,11 +69,12 @@ Developer Documentation
* [JsonRpcProvider](api/providers/jsonrpc-provider)
* [JsonRpcSigner](api/providers/jsonrpc-provider)
* [JsonRpcUncheckedSigner](api/providers/jsonrpc-provider)
* [Node-Specific Methods](api/providers/jsonrpc-provider)
* [API Providers](api/providers/api-providers)
* [EtherscanProvider](api/providers/api-providers)
* [InfuraProvider](api/providers/api-providers)
* [AlchemyProvider](api/providers/api-providers)
* [CloudfrontProvider](api/providers/api-providers)
* [CloudflareProvider](api/providers/api-providers)
* [Other Providers](api/providers/other)
* [FallbackProvider](api/providers/other)
* [IpcProvider](api/providers/other)
@ -123,7 +108,9 @@ Developer Documentation
* [ParamType](api/utils/abi/fragments)
* [Addresses](api/utils/address)
* [Address Formats](api/utils/address)
* [Functions](api/utils/address)
* [Converting and Verifying](api/utils/address)
* [Derivation](api/utils/address)
* [Contracts Addresses](api/utils/address)
* [BigNumber](api/utils/bignumber)
* [Types](api/utils/bignumber)
* [Creating Instances](api/utils/bignumber)
@ -154,8 +141,9 @@ Developer Documentation
* [Methods](api/utils/fixednumber)
* [FixedFormat](api/utils/fixednumber)
* [Hashing Algorithms](api/utils/hashing)
* [Cryptographic Hashing](api/utils/hashing)
* [Common Hashing Helpers](api/utils/hashing)
* [Cryptographic Hash Functions](api/utils/hashing)
* [HMAC](api/utils/hashing)
* [Hashing Helpers](api/utils/hashing)
* [Solidity Hashing Algorithms](api/utils/hashing)
* [HD Wallet](api/utils/hdnode)
* [Types](api/utils/hdnode)
@ -201,6 +189,10 @@ Developer Documentation
* [Nodes](api/other/assembly/ast)
* [Hardware Wallets](api/other/hardware)
* [LedgerSigner](api/other/hardware)
* [Experimental](api/experimental)
* [BrainWallet](api/experimental)
* [EIP1193Bridge](api/experimental)
* [NonceManager](api/experimental)
* [Command Line Interfaces](cli)
* [Sandbox Utility](cli/ethers)
* [Help](cli/ethers)
@ -240,24 +232,12 @@ Developer Documentation
* [Flatworm Docs](documentation)
* [Fragments](documentation)
* [Markdown](documentation)
* [Code](documentation)
* [Tables](documentation)
* [Configuration](documentation)
* [Extended Directive Functions](documentation)
* [Extensions](documentation)
* [License and Copyright](license)
Legacy Documentation
--------------------
This section will be kept up to date, linking to documentation of
older versions of the library.
* [version 4.0](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io/ethers.js)
* [version 3.0](Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ethers.io/ethers.js/v3.0/html)
-----
**Content Hash:** 1ccc27c4ba6e59efa2be69cc0fb345ea9c397f1f4444d08ec13780d0d1a46b60

39
docs/api/README.md
View File

@ -7,23 +7,24 @@ Documentation: [html](https://docs-beta.ethers.io/)
Application Programming Interface
=================================
Here...
* [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 ^^//(inheritted from [[contract]])//^^](contract/example)
* [Methods ^^//(inheritted from [[contract]])//^^](contract/example)
* [Events ^^//(inheritted from Contract)//^^](contract/example)
* [Meta-Class Methods ^^//(added at Runtime)//^^](contract/example)
* [Meta-Class Filters ^^//(added at Runtime)//^^](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)
@ -42,11 +43,12 @@ Here...
* [JsonRpcProvider](providers/jsonrpc-provider)
* [JsonRpcSigner](providers/jsonrpc-provider)
* [JsonRpcUncheckedSigner](providers/jsonrpc-provider)
* [Node-Specific Methods](providers/jsonrpc-provider)
* [API Providers](providers/api-providers)
* [EtherscanProvider](providers/api-providers)
* [InfuraProvider](providers/api-providers)
* [AlchemyProvider](providers/api-providers)
* [CloudfrontProvider](providers/api-providers)
* [CloudflareProvider](providers/api-providers)
* [Other Providers](providers/other)
* [FallbackProvider](providers/other)
* [IpcProvider](providers/other)
@ -80,7 +82,9 @@ Here...
* [ParamType](utils/abi/fragments)
* [Addresses](utils/address)
* [Address Formats](utils/address)
* [Functions](utils/address)
* [Converting and Verifying](utils/address)
* [Derivation](utils/address)
* [Contracts Addresses](utils/address)
* [BigNumber](utils/bignumber)
* [Types](utils/bignumber)
* [Creating Instances](utils/bignumber)
@ -111,8 +115,9 @@ Here...
* [Methods](utils/fixednumber)
* [FixedFormat](utils/fixednumber)
* [Hashing Algorithms](utils/hashing)
* [Cryptographic Hashing](utils/hashing)
* [Common Hashing Helpers](utils/hashing)
* [Cryptographic Hash Functions](utils/hashing)
* [HMAC](utils/hashing)
* [Hashing Helpers](utils/hashing)
* [Solidity Hashing Algorithms](utils/hashing)
* [HD Wallet](utils/hdnode)
* [Types](utils/hdnode)
@ -158,8 +163,8 @@ Here...
* [Nodes](other/assembly/ast)
* [Hardware Wallets](other/hardware)
* [LedgerSigner](other/hardware)
* [Experimental](experimental)
* [BrainWallet](experimental)
* [EIP1193Bridge](experimental)
* [NonceManager](experimental)
-----
**Content Hash:** 792936ddc8c609e435d356c2bfde1adacf9f0b5b708481720f22081f1a61f73d

23
docs/api/contract/README.md
View File

@ -7,24 +7,21 @@ Documentation: [html](https://docs-beta.ethers.io/)
Contract Interaction
====================
Explain what contracts are...
* [Contract](contract)
* [Creating Instances](contract)
* [Properties](contract)
* [Methods](contract)
* [Events](contract)
* [Meta-Class](contract)
* [ContractFactory](contract-factory)
* [Creating Instances](contract-factory)
* [Properties](contract-factory)
* [Methods](contract-factory)
* [Example: ERC-20 Contract](example)
* [Connecting to a Contract](example)
* [Properties ^^//(inheritted from [[contract]])//^^](example)
* [Methods ^^//(inheritted from [[contract]])//^^](example)
* [Events ^^//(inheritted from Contract)//^^](example)
* [Meta-Class Methods ^^//(added at Runtime)//^^](example)
* [Meta-Class Filters ^^//(added at Runtime)//^^](example)
* [Properties](example)
* [Methods](example)
* [Events](example)
* [Meta-Class Methods](example)
* [Meta-Class Filters](example)
-----
**Content Hash:** f1a5079be018a7b2e6ce8b86a5a191f7a1352b976434766ea16cec21d0ce3b80

93
docs/api/contract/contract-factory/README.md Normal file
View File

@ -0,0 +1,93 @@
-----
Documentation: [html](https://docs-beta.ethers.io/)
-----
ContractFactory
===============
Creating Instances
------------------
#### **new ***ethers* . **ContractFactory**( interface , bydecode [ , signer ] )
#### *ContractFactory* . **fromSolidity**( compilerOutput [ , signer ] ) => *[ContractFactory](/api/contract/contract-factory/)*
#### *contractFactory* . **connect**( signer ) => *[Contract](/api/contract/contract/)*
Properties
----------
#### *contractFactory* . **interface** => *[Interface](/api/utils/abi/interface/)*
#### *contractFactory* . **bytecode** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
#### *contractFactory* . **signer** => *[Signer](/api/signer/#Signer)*
Methods
-------
#### *contractFactory* . **attach**( address ) => *[Contract](/api/contract/contract/)*
Return an instance of a [Contract](/api/contract/contract/) attched to *address*. This is the same as using the [Contract constructor](/api/contract/contract/#contract--creating) with *address* and this the the *interface* and *signerOrProvider* passed in when creating the ContractFactory.
#### *contractFactory* . **getDeployTransaction**( ...args ) => *[UnsignedTransaction](/api/utils/transactions/#UnsignedTransaction)*
Returns the unsigned transaction which would deploy this Contract with *args* passed to the Contract's constructor.
#### *contractFactory* . **deploy**( ...args ) => *Promise< [Contract](/api/contract/contract/) >*
Uses the signer to deploy the Contract with *args* passed into tgee constructor and retruns a Contract which is attached to the address where this contract **will** be deployed once the transction is mined.
The transction can be found at `contract.deployTransaction`, and no interactions should be made until the transaction is mined.
```
// <hide>
const signer = ethers.LocalSigner();
const ContractFactory = ethers.ContractFactory;
// </hide>
// If your contract constructor requires parameters, the ABI
// must include the constructor
const abi = [
"constructor(address owner, uint256 initialValue)"
];
const factory = new ContractFactory(abi, bytecode, signer)
const contract = await factory.deploy("ricmoo.eth", 42);
// The address is available immediately, but the contract
// is NOT deployed yet
contract.address
//!
// The transaction that the signer sent to deploy
contract.deployTransaction
//!
// Wait until the transaction is mined
contract.deployTransaction.wait()
//!
// Now the contract is safe to ineract with
contract.value()
//!
```

77
docs/api/contract/contract-factory/index.html Normal file
View File

File diff suppressed because one or more lines are too long

252
docs/api/contract/contract/README.md
View File

@ -7,278 +7,170 @@ Documentation: [html](https://docs-beta.ethers.io/)
Contract
========
Creating Instances
------------------
#### **new ***ethers* . **Contract**( address , abi , signerOrProvider )
#### *contract* . **attach**( addressOrName ) => *[Contract](/api/contract/contract/)*
Returns a new instance of the **Contract** attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them.
#### *contract* . **connect**( providerOrSigner ) => *[Contract](/api/contract/contract/)*
Returns a new instance of the Contract, but connected to *providerOrSigner*.
By passing in a [Provider](/api/providers/provider/), this will return a downgraded **Contract** which only has read-only access (i.e. constant calls).
By passing in a [Signer](/api/signer/#Signer). the will return a **Contract** which will act on behalf of that signer.
Properties
----------
#### *contract* . **address** **=>** *string< [Address](../../utils/address) >*
#### *contract* . **address** => *string< [Address](/api/utils/address/#address) >*
This is the address (or ENS name) the contract was constructed with.
#### *contract* . **resolvedAddress** => *string< [Address](/api/utils/address/#address) >*
This is a promise that will resolve to the address the **Contract** object is attached to. If an [Address](/api/utils/address/#address) was provided to the constructor, it will be equal to this; if an ENS name was provided, this will be the resolved address.
#### *contract* . **addressPromise** **=>** *string< [Address](../../utils/address) >*
#### *contract* . **deployTransaction** => *[TransactionResponse](/api/providers/types/#providers-TransactionResponse)*
This is a promise that will resolve to the address the **Contract**
object is attached to. If an [Address](../../utils/address) was provided to the constructor,
it will be equal to this; if an ENS name was provided, this will be the
resolved address.
If the **Contract** object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.
#### *contract* . **interface** => *[Interface](/api/utils/abi/interface/)*
This is the ABI as an [Interface](/api/utils/abi/interface/).
#### *contract* . **deployTransaction** **=>** *[TransactionResponse](../../providers/types)*
#### *contract* . **provider** => *[Provider](/api/providers/provider/)*
If the **Contract** object is the result of a ContractFactory deployment,
this is the transaction which was used to deploy the contract.
If a provider was provided to the constructor, this is that provider. If a signer was provided that had a [Provider](/api/providers/provider/), this is that provider.
#### *contract* . **interface** **=>** *[Interface](../../utils/abi/interface)*
This is the ABI as an [Interface](../../utils/abi/interface).
#### *contract* . **provider** **=>** *[Provider](../../providers/provider)*
If a provider was provided to the constructor, this is that provider. If
a signer was provided that had a [Provider](../../providers/provider), this is that provider.
#### *contract* . **signer** **=>** *[Signer](../../signer)*
#### *contract* . **signer** => *[Signer](/api/signer/#Signer)*
If a signer was provided to the constructor, this is that signer.
Methods
-------
#### *contract* . **attach** ( addressOrName ) **=>** *[Contract](./)*
Returns a new instance of the **Contract** attached to a new
address. This is useful if there are multiple similar or identical
copies of a Contract on the network and you wish to interact with
each of them.
#### *contract* . **connect** ( providerOrSigner ) **=>** *[Contract](./)*
Returns a new instance of the Contract, but connected to
*providerOrSigner*.
By passing in a [Provider](../../providers/provider), this will return a downgraded
**Contract** which only has read-only access (i.e. constant calls).
By passing in a [Signer](../../signer). the will return a **Contract** which
will act on behalf of that signer.
#### *contract* . **deployed** ( ) **=>** *Promise< [Contract](./) >*
#### *Contract* . **isIndexed** ( value ) **=>** *boolean*
#### *contract* . **deployed**( ) => *Promise< [Contract](/api/contract/contract/) >*
#### *Contract* . **isIndexed**( value ) => *boolean*
Events
------
#### *contract* . **queryFilter** ( event [ , fromBlockOrBlockHash [ , toBlock ] ) **=>** *Promise< Array< Event > >*
#### *contract* . **queryFilter**( event [ , fromBlockOrBlockHash [ , toBlock ] ) => *Promise< Array< Event > >*
Return Events that match the *event*.
#### *contract* . **listenerCount**( [ event ] ) => *number*
Return the number of listeners that are subscribed to *event*. If no event is provided, returns the total count of all events.
#### *contract* . **listenerCount** ( [ event ] ) **=>** *number*
Return the number of listeners that are subscribed to *event*. If
no event is provided, returns the total count of all events.
#### *contract* . **listeners** ( event ) **=>** *Array< Listener >*
#### *contract* . **listeners**( event ) => *Array< Listener >*
Return a list of listeners that are subscribed to *event*.
#### *contract* . **off** ( event , listener ) **=>** *this*
#### *contract* . **off**( event , listener ) => *this*
Unsubscribe *listener* to *event*.
#### *contract* . **on** ( event , listener ) **=>** *this*
#### *contract* . **on**( event , listener ) => *this*
Subscribe to *event* calling *listener* when the event occurs.
#### *contract* . **once**( event , listener ) => *this*
Subscribe once to *event* calling *listener* when the event occurs.
#### *contract* . **once** ( event , listener ) **=>** *this*
Subscribe once to *event* calling *listener* when the event
occurs.
#### *contract* . **removeAllListeners** ( [ event ] ) **=>** *this*
Unsubscribe all listeners for *event*. If no event is provided,
all events are unsubscribed.
#### *contract* . **removeAllListeners**( [ event ] ) => *this*
Unsubscribe all listeners for *event*. If no event is provided, all events are unsubscribed.
Meta-Class
----------
A Meta-Class is a Class which has any of its properties determined
at run-time. The **Contract** object uses a Contract's ABI to
determine what methods are available, so the following sections
describe the generic ways to interact with the properties added
at run-time during the **Contract** constructor.
### Read-Only Methods (constant)
A constant method is read-only and evaluates a small amount of EVM
code against the current blockchain state and can be computed by
asking a single node, which can return a result. It is therefore
free and does not require any ether, but **cannot make changes** to
the blockchain state..
#### *contract* . **METHOD_NAME** ( ...args [ overrides ] ) **=>** *Promise< any >*
#### *contract* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< any >*
The type of the result depends on the ABI.
For values that have a simple meaning in JavaScript, the types are fairly
straight forward; strings and booleans are returned as JavaScript strings
and booleans.
For values that have a simple meaning in JavaScript, the types are fairly straight forward; strings and booleans are returned as JavaScript strings and booleans.
For numbers, if the **type** is in the JavaSsript safe range (i.e. less
than 53 bits, such as an `int24` or `uint48`) a normal JavaScript
number is used. Otherwise a [BigNumber](../../utils/bignumber) is returned.
For numbers, if the **type** is in the JavaSsript safe range (i.e. less than 53 bits, such as an `int24` or `uint48`) a normal JavaScript number is used. Otherwise a [BigNumber](/api/utils/bignumber/) is returned.
For bytes (both fixed length and dynamic), a [DataHexstring](../../utils/bytes) is returned.
For bytes (both fixed length and dynamic), a [DataHexString](/api/utils/bytes/#DataHexString) is returned.
#### *contract* . *functions* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< [Result](/api/utils/abi/interface/#Result) >*
The result will always be a [Result](/api/utils/abi/interface/#Result), even if there is only a single return value type.
This simplifies frameworks which wish to use the [Contract](/api/contract/contract/) object, since they do not need to inspect the return types to unwrap simplified functions.
Another use for this method is for error recovery. For example, if a function result is an invalid UTF-8 string, the normal call using the above meta-class function will throw an exception. This allows using the Result access error to access the low-level bytes and reason for the error allowing an alternate UTF-8 error strategy to be used.
Most developers should not require this.
### Write Methods (non-constant)
#### *contract* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< [TransactionResponse](/api/providers/types/#providers-TransactionResponse) >*
A non-constant method requires a transaction to be signed and requires
payment in the form of a fee to be paid to a miner. This transaction
will be verified by every node on the entire network as well by the
miner who will compute the new state of the blockchain after executing
it against the current state.
It cannot return a result. If a result is required, it should be logged
using a Solidity event (or EVM log), which can then be queried from the
transaction receipt.
#### *contract* . **METHOD_NAME** ( ...args [ , overrides ] ) **=>** *Promise< [TransactionResponse](../../providers/types) >*
Returns a [TransactionResponse](../../providers/types) for the transaction after
it is sent to the network. This requires the **Contract** has a
signer.
Returns a [TransactionResponse](/api/providers/types/#providers-TransactionResponse) for the transaction after it is sent to the network. This requires the **Contract** has a signer.
### Write Methods Analysis
#### *contract* . *estimateGas* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
There are secveral options to analyze properties and results of a
write method without actually executing it.
Returns the estimate units of gas that would be required to execute the *METHOD_NAME* with *args* and *overrides*.
#### *contract* . *estimate* . **METHOD_NAME** ( ...args [ , overrides ] ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
#### *contract* . *populateTransaction* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< [UnsignedTx](/api/utils/transactions/#UnsignedTransaction) >*
Returns the estimate units of gas that would be required to
execute the *METHOD_NAME* with *args* and *overrides*.
Returns an [UnsignedTransaction](/api/utils/transactions/#UnsignedTransaction) which represents the transaction that would need to be signed and submitted to the network to execute *METHOD_NAME* with *args* and *overrides*.
#### *contract* . *staticCall* . **METHOD_NAME**( ...args [ , overrides ] ) => *Promise< any >*
Rather than executing the state-change of a transaction, it is possible to ask a node to *pretend* that a call is not state-changing and return the result.
#### *contract* . *populateTransaction* . **METHOD_NAME** ( ...args [ , overrides ] ) **=>** *Promise< [UnsignedTx](../../utils/transactions) >*
Returns an [UnsignedTransaction](../../utils/transactions) which represents the transaction
that would need to be signed and submitted to the network to execute
*METHOD_NAME* with *args/ and *overrides//.
#### *contract* . *staticCall* . **METHOD_NAME** ( ...args [ , overrides ] ) **=>** *Promise< any >*
Rather than executing the state-change of a transaction, it is possible
to ask a node to *pretend* that a call is not state-changing and
return the result.
This does not actually chagne any state, but is free. This in some cases
can be used to determine if a transaction will fail or succeed.
This otherwise functions the same as a [Read-Only Method](./).
This does not actually chagne any state, but is free. This in some cases can be used to determine if a transaction will fail or succeed.
This otherwise functions the same as a [Read-Only Method](/api/contract/contract/#contract--readonly).
### Event Filters
#### *contract* . *filters* . **EVENT_NAME**( ...args ) => *Filter*
An event filter is made up of topics, which are values logged in a
[Bloom Filter](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Bloom_filter), allowing efficient searching for entries
which match a filter.
Return a filter for *EVENT_NAME*, optionally filtering by additional constraints.
Only `indexed` event parameters may be filtered. If a parameter is null (or not provided) then any value in that field matches.
#### *contract* . *filters* . **EVENT_NAME** ( ...args ) **=>** *Filter*
Return a filter for *EVENT_NAME*, optionally filtering by additional
constraints.
Only `indexed` event parameters may be filtered. If a parameter is
null (or not provided) then any value in that field matches.
-----
**Content Hash:** 8f1f64a28b2501d01dcf4b55c405c43096f3a9daca7169a96022000a315b2ef2

149
docs/api/contract/contract/index.html
View File

File diff suppressed because one or more lines are too long

275
docs/api/contract/example/README.md
View File

@ -7,14 +7,10 @@ Documentation: [html](https://docs-beta.ethers.io/)
Example: ERC-20 Contract
========================
Connecting to a Contract
------------------------
```
```javascript
// A Human-Readable ABI; any supported ABI format could be used
const abi = [
// Read-Only Functions
@ -30,13 +26,13 @@ const abi = [
];
// This can be an address or an ENS name
const address = "demotoken.ethers.eth";
const address = "dai.tokens.ethers.eth";
// An example Provider (connceted to testnet)
const provider = ethers.getDefaultProvider("ropsten");
// An example Provider
const provider = ethers.getDefaultProvider();
// An example Signer
const signer = ethers.Wallet.createRandom(provider);
const signer = ethers.Wallet.createRandom().connect(provider);
// Read-Only; By connecting to a Provider, allows:
// - Any constant function
@ -52,272 +48,161 @@ const erc20 = new ethers.Contract(address, abi, provider);
const erc20_rw = new ethers.Contract(address, abi, signer)
```
### ERC20Contract
#### **new ***ethers* . **Contract**( address , abi , providerOrSigner )
See the above code example for creating an Instance which will (in addition to the Contact methods and properties) automatically add the additional properties defined in *abi* to a **Contract** connected to *address* using the *providerOrSigner*.
#### **new** *ethers* . **Contract** ( address , abi , providerOrSigner )
Properties
----------
See the above code example for creating an Instance which will
(in addition to the Contact methods and properties) automatically
add the additional properties defined in *abi* to a **Contract**
connected to *address* using the *providerOrSigner*.
Properties ^(*(inheritted from [Contract](../contract))*)
---------------------------------------------------------
#### *erc20* . **address** **=>** *string< [Address](../../utils/address) >*
#### *erc20* . **address** => *string< [Address](/api/utils/address/#address) >*
This is the address (or ENS name) the contract was constructed with.
#### *erc20* . **resolvedAddress** => *string< [Address](/api/utils/address/#address) >*
This is a promise that will resolve to the address the **Contract** object is attached to. If an [Address](/api/utils/address/#address) was provided to the constructor, it will be equal to this; if an ENS name was provided, this will be the resolved address.
#### *erc20* . **addressPromise** **=>** *string< [Address](../../utils/address) >*
#### *erc20* . **deployTransaction** => *[TransactionResponse](/api/providers/types/#providers-TransactionResponse)*
This is a promise that will resolve to the address the **Contract**
object is attached to. If an [Address](../../utils/address) was provided to the constructor,
it will be equal to this; if an ENS name was provided, this will be the
resolved address.
If the **Contract** object is the result of a ContractFactory deployment, this is the transaction which was used to deploy the contract.
#### *erc20* . **interface** => *[Interface](/api/utils/abi/interface/)*
This is the ABI as an [Interface](/api/utils/abi/interface/).
#### *erc20* . **deployTransaction** **=>** *[TransactionResponse](../../providers/types)*
#### *erc20* . **provider** => *[Provider](/api/providers/provider/)*
If the **Contract** object is the result of a ContractFactory deployment,
this is the transaction which was used to deploy the contract.
If a provider was provided to the constructor, this is that provider. If a signer was provided that had a [Provider](/api/providers/provider/), this is that provider.
#### *erc20* . **interface** **=>** *[Interface](../../utils/abi/interface)*
This is the ABI as an [Interface](../../utils/abi/interface).
#### *erc20* . **provider** **=>** *[Provider](../../providers/provider)*
If a provider was provided to the constructor, this is that provider. If
a signer was provided that had a [Provider](../../providers/provider), this is that provider.
#### *erc20* . **signer** **=>** *[Signer](../../signer)*
#### *erc20* . **signer** => *[Signer](/api/signer/#Signer)*
If a signer was provided to the constructor, this is that signer.
Methods
-------
#### *erc20* . **attach**( addressOrName ) => *[Contract](/api/contract/contract/)*
Returns a new instance of the **Contract** attached to a new address. This is useful if there are multiple similar or identical copies of a Contract on the network and you wish to interact with each of them.
Methods ^(*(inheritted from [Contract](../contract))*)
------------------------------------------------------
#### *erc20* . **connect**( providerOrSigner ) => *[Contract](/api/contract/contract/)*
Returns a new instance of the Contract, but connected to *providerOrSigner*.
By passing in a [Provider](/api/providers/provider/), this will return a downgraded **Contract** which only has read-only access (i.e. constant calls).
By passing in a [Signer](/api/signer/#Signer). the will return a **Contract** which will act on behalf of that signer.
#### *erc20* . **deployed**( ) => *Promise< Contract >*
#### *erc20* . **attach** ( addressOrName ) **=>** *[Contract](../contract)*
Returns a new instance of the **Contract** attached to a new
address. This is useful if there are multiple similar or identical
copies of a Contract on the network and you wish to interact with
each of them.
#### *Contract* . **isIndexed**( value ) => *boolean*
Events
------
#### *erc20* . **connect** ( providerOrSigner ) **=>** *[Contract](../contract)*
Returns a new instance of the Contract, but connected to
*providerOrSigner*.
By passing in a [Provider](../../providers/provider), this will return a downgraded
**Contract** which only has read-only access (i.e. constant calls).
By passing in a [Signer](../../signer). the will return a **Contract** which
will act on behalf of that signer.
#### *erc20* . **deployed** ( ) **=>** *Promise< Contract >*
#### *Contract* . **isIndexed** ( value ) **=>** *boolean*
Events ^(*(inheritted from Contract)*)
--------------------------------------
#### *erc20* . **queryFilter** ( event [ , fromBlockOrBlockHash [ , toBlock ] ) **=>** *Promise< Array< Event > >*
#### *erc20* . **queryFilter**( event [ , fromBlockOrBlockHash [ , toBlock ] ) => *Promise< Array< Event > >*
Return Events that match the *event*.
#### *erc20* . **listenerCount**( [ event ] ) => *number*
Return the number of listeners that are subscribed to *event*. If no event is provided, returns the total count of all events.
#### *erc20* . **listenerCount** ( [ event ] ) **=>** *number*
Return the number of listeners that are subscribed to *event*. If
no event is provided, returns the total count of all events.
#### *erc20* . **listeners** ( event ) **=>** *Array< Listener >*
#### *erc20* . **listeners**( event ) => *Array< Listener >*
Return a list of listeners that are subscribed to *event*.
#### *erc20* . **off** ( event , listener ) **=>** *this*
#### *erc20* . **off**( event , listener ) => *this*
Unsubscribe *listener* to *event*.
#### *erc20* . **on** ( event , listener ) **=>** *this*
#### *erc20* . **on**( event , listener ) => *this*
Subscribe to *event* calling *listener* when the event occurs.
#### *erc20* . **once**( event , listener ) => *this*
Subscribe once to *event* calling *listener* when the event occurs.
#### *erc20* . **once** ( event , listener ) **=>** *this*
#### *erc20* . **removeAllListeners**( [ event ] ) => *this*
Subscribe once to *event* calling *listener* when the event
occurs.
Unsubscribe all listeners for *event*. If no event is provided, all events are unsubscribed.
Meta-Class Methods
------------------
#### *erc20* . **decimals**( [ overrides ] ) => *Promise< number >*
Returns the number of decimal places used by this ERC-20 token. This can be used with [parseUnits](/api/utils/display-logic/#utils-parseUnits) when taking input from the user or [formatUnits](utils-formatunits] when displaying the token amounts in the UI.
#### *erc20* . **removeAllListeners** ( [ event ] ) **=>** *this*
Unsubscribe all listeners for *event*. If no event is provided,
all events are unsubscribed.
Meta-Class Methods ^(*(added at Runtime)*)
------------------------------------------
Since the Contract is a Meta-Class, the methods available here depend
on the ABI which was passed into the **Contract**.
#### *erc20* . **decimals** ( [ overrides ] ) **=>** *Promise< number >*
Returns the number of decimal places used by this ERC-20 token. This can be
used with [parseUnits](../../utils/display-logic) when taking input from the user or
[formatUnits](utils-formatunits] when displaying the token amounts in the UI.
#### *erc20* . **getBalance** ( owner [ , overrides ] ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
#### *erc20* . **getBalance**( owner [ , overrides ] ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the balance of *owner* for this ERC-20 token.
#### *erc20* . **symbol** ( [ overrides ] ) **=>** *Promise< string >*
#### *erc20* . **symbol**( [ overrides ] ) => *Promise< string >*
Returns the symbol of the token.
#### *erc20_rw* . **transfer**( target , amount [ , overrides ] ) => *Promise< [TransactionResponse](/api/providers/types/#providers-TransactionResponse) >*
Transfers *amount* tokens to *target* from the current signer. The return value (a boolean) is inaccessible during a write operation using a transaction. Other techniques (such as events) are required if this value is required. On-chain contracts calling the `transfer` function have access to this result, which is why it is possible.
#### *erc20_rw* . **transfer** ( target , amount [ , overrides ] ) **=>** *Promise< [TransactionResponse](../../providers/types) >*
#### *erc20* . *callStatic* . **transfer**( target , amount [ , overrides ] ) => *Promise< boolean >*
Transfers *amount* tokens to *target* from the current signer.
The return value (a boolean) is inaccessible during a write operation
using a transaction. Other techniques (such as events) are required
if this value is required. On-chain contracts calling the `transfer`
function have access to this result, which is why it is possible.
#### *erc20* . *callStatic* . **transfer** ( target , amount [ , overrides ] ) **=>** *Promise< boolean >*
Performs a dry-run of transferring *amount* tokens to *target* from
the current signer, without actually signing or sending a transaction.
Performs a dry-run of transferring *amount* tokens to *target* from the current signer, without actually signing or sending a transaction.
This can be used to preflight check that a transaction will be successful.
#### *erc20* . *estimateGas* . **transfer**( target , amount [ , overrides ] ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns an estimate for how many units of gas would be required to transfer *amount* tokens to *target*.
#### *erc20* . *estimate* . **transfer** ( target , amount [ , overrides ] ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
Returns an estimate for how many units of gas would be required
to transfer *amount* tokens to *target*.
#### *erc20* . *populateTransaction* . **transfer** ( target , amount [ , overrides ] ) **=>** *Promise< [UnsignedTx](../../utils/transactions) >*
Returns an [UnsignedTransaction](../../utils/transactions) which could be signed and submitted
to the network to transaction *amount* tokens to *target*.
#### *erc20* . *populateTransaction* . **transfer**( target , amount [ , overrides ] ) => *Promise< [UnsignedTx](/api/utils/transactions/#UnsignedTransaction) >*
Returns an [UnsignedTransaction](/api/utils/transactions/#UnsignedTransaction) which could be signed and submitted to the network to transaction *amount* tokens to *target*.
#### Note on Estimating and Static Calling
When you perform a static call, the current state is taken into account as
best as Ethereum can determine. There are many cases where this can provide
false positives and false negatives. The eventually consistent model of the
blockchain also means there are certain consistency modes that cannot be
known until an actual transaction is attempted.
When you perform a static call, the current state is taken into account as best as Ethereum can determine. There are many cases where this can provide false positives and false negatives. The eventually consistent model of the blockchain also means there are certain consistency modes that cannot be known until an actual transaction is attempted.
Meta-Class Filters
------------------
#### *erc20* . *filters* . **Transafer**( [ fromAddress [ , toAddress ] ] ) => *Filter*
Returns a new Filter which can be used to [query](/api/contract/example/#erc20-queryfilter) or to [subscribe/unsubscribe to events](/api/contract/example/#erc20-events).
If *fromAddress* is null or not provided, then any from address matches. If *toAddress* is null or not provided, then any to address matches.
Meta-Class Filters ^(*(added at Runtime)*)
------------------------------------------
Since the Contract is a Meta-Class, the methods available here depend
on the ABI which was passed into the **Contract**.
#### *erc20* . *filters* . **Transafer** ( [ fromAddress [ , toAddress ] ] ) **=>** *Filter*
Returns a new Filter which can be used to [query](./) or
to [subscribe/unsubscribe to events](./).
If *fromAddress* is null or not provided, then any from address matches.
If *toAddress* is null or not provided, then any to address matches.
-----
**Content Hash:** a3d2ad294a2b4b4500d3f80c7a1cdc76420fee234ad271d90f5c609b040e93fa

164
docs/api/contract/example/index.html
View File

File diff suppressed because one or more lines are too long

36
docs/api/contract/index.html
View File

File diff suppressed because one or more lines are too long

57
docs/api/experimental/README.md Normal file
View File

@ -0,0 +1,57 @@
-----
Documentation: [html](https://docs-beta.ethers.io/)
-----
Experimental
============
BrainWallet
-----------
#### *BrainWallet* . **generate**( username , password [ , progressCallback ] ) => *[BrainWallet](/api/experimental/#experimental-brainwallet)*
Generates a brain wallet, with a slightly improved experience, in which the generated wallet has a mnemonic.
#### *BrainWallet* . **generateLegacy**( username , password [ , progressCallback ] ) => *[BrainWallet](/api/experimental/#experimental-brainwallet)*
Generate a brain wallet which is compatibile with the ethers v3 and earlier.
EIP1193Bridge
-------------
NonceManager
------------
#### **new ****NonceManager**( signer )
Create a new NonceManager.
#### *nonceManager* . **signer** => *[Signer](/api/signer/#Signer)*
The signer whose nonce is being managed.
#### *nonceManager* . **provider** => *[Provider](/api/providers/provider/)*
The provider associated with the signer.
#### *nonceManager* . **setTransactionCount**( count ) => *void*
Set the current transaction count (nonce) for the signer.
This may be useful it interacting with the signer outside of using this class.
#### *nonceManager* . **increaseTransactionCount**( [ count = 1 ] ) => *void*
Bump the current transaction count (nonce) by *count*.
This may be useful it interacting with the signer outside of using this class.

61
docs/api/experimental/index.html Normal file
View File

File diff suppressed because one or more lines are too long

34
docs/api/index.html
View File

File diff suppressed because one or more lines are too long

10
docs/api/other/README.md
View File

@ -7,12 +7,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
Other Libraries
===============
Now that ethers is more modular, it is possible to have additional
ancillary packages, which are not part of the core but optionally
add functionality only needed in certain situations.
* [Assembly](assembly)
* [Ethers ASM Dialect](assembly/dialect)
* [Opcodes](assembly/dialect)
@ -34,7 +28,3 @@ add functionality only needed in certain situations.
* [Hardware Wallets](hardware)
* [LedgerSigner](hardware)
-----
**Content Hash:** 90507a9035452f2463c81dc6ce204622750f4781dd52673cf666afae6e607577

6
docs/api/other/assembly/README.md
View File

@ -7,8 +7,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
Assembly
========
* [Ethers ASM Dialect](dialect)
* [Opcodes](dialect)
* [Labels](dialect)
@ -27,7 +25,3 @@ Assembly
* [Types](ast)
* [Nodes](ast)
-----
**Content Hash:** c29497e2f7fe90669ffd6c67b0231649074fcb869470caa58750ddbc39905727

120
docs/api/other/assembly/api/README.md
View File

@ -7,178 +7,108 @@ Documentation: [html](https://docs-beta.ethers.io/)
Utilities
=========
Assembler
---------
#### *asm* . **parse**( code ) => *[Node](/api/other/assembly/ast/#asm-node)*
The assembler utilities allow parsing and assembling an
[Ethers ASM Dialect](../dialect) source file.
Parse an ethers-format assembly file and return the [Abstract Syntax Tree](/api/other/assembly/ast/).
#### *asm* . **parse** ( code ) **=>** *[Node](../ast)*
Parse an ethers-format assembly file and return the [Abstract Syntax Tree](../ast).
#### *asm* . **assemble** ( node ) **=>** *string< [DataHexstring](../../../utils/bytes) >*
Performs assembly of the [Abstract Syntax Tree](../ast) *node* and return the
resulting bytecode representation.
#### *asm* . **assemble**( node ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Performs assembly of the [Abstract Syntax Tree](/api/other/assembly/ast/) *node* and return the resulting bytecode representation.
Disassembler
------------
The **Disassembler** utilities make it easy to convert bytecode
into an object which can easily be examined for program structure.
#### *asm* . **disassemble** ( bytecode ) **=>** *[Bytecode](./)*
#### *asm* . **disassemble**( bytecode ) => *[Bytecode](/api/other/assembly/api/#asm-bytecode)*
Returns an array of Operations given *bytecode*.
#### *asm* . **formatBytecode**( operations ) => *string*
#### *asm* . **formatBytecode** ( operations ) **=>** *string*
Create a formatted output of an array of [Operation](./).
Create a formatted output of an array of [Operation](/api/other/assembly/api/#asm-operation).
### Bytecode
#### *bytecode* . **getOperation**( offset ) => *[Operation](/api/other/assembly/api/#asm-operation)*
Each arary index represents an operation, collapsing multi-byte operations
(i.e. `PUSH`) into a single operation.
#### *bytecode* . **getOperation** ( offset ) **=>** *[Operation](./)*
Get the operation at a given *offset* into the bytecode. This ensures that
the byte at *offset* is an operation and not data contained within a `PUSH`,
in which case null it returned.
Get the operation at a given *offset* into the bytecode. This ensures that the byte at *offset* is an operation and not data contained within a `PUSH`, in which case null it returned.
### Operation
An **Operation** is a single command from a disassembled bytecode
stream.
#### *operation* . **opcode** **=>** *[Opcode](./)*
#### *operation* . **opcode** => *[Opcode](/api/other/assembly/api/#asm-opcode)*
The opcode for this Operation.
#### *operation* . **offset** **=>** *number*
#### *operation* . **offset** => *number*
The offset into the bytecode for this Operation.
#### *operation* . **pushValue** **=>** *string< [DataHexstring](../../../utils/bytes) >*
#### *operation* . **pushValue** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
If the opcode is a `PUSH`, this is the value of that push
Opcode
------
#### *asm* . *Opcode* . **from**( valueOrMnemonic ) => *[Opcode](/api/other/assembly/api/#asm-opcode)*
#### *asm* . *Opcode* . **from** ( valueOrMnemonic ) **=>** *[Opcode](./)*
Create a new instnace of an Opcode for a given numeric value
(e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").
Create a new instnace of an Opcode for a given numeric value (e.g. 0x60 is PUSH1) or mnemonic string (e.g. "PUSH1").
### Properties
#### *opcode* . **value** **=>** *number*
#### *opcode* . **value** => *number*
The value (bytecode as a number) of this opcode.
#### *opcode* . **mnemonic** **=>** *string*
#### *opcode* . **mnemonic** => *string*
The mnemonic string of this opcode.
#### *opcode* . **delta** **=>** *number*
#### *opcode* . **delta** => *number*
The number of items this opcode will consume from the stack.
#### *opcode* . **alpha** **=>** *number*
#### *opcode* . **alpha** => *number*
The number of items this opcode will push onto the stack.
#### *opcode* . **doc** **=>** *string*
#### *opcode* . **doc** => *string*
A short description of what this opcode does.
#### *opcode* . **isMemory** ( ) **=>** *"read"|"write"|"full"*
#### *opcode* . **isMemory**( ) => *"read" | "write" | "full"*
Returns true if the opcode accesses memory.
#### *opcode* . **isStatic** ( ) **=>** *boolean*
#### *opcode* . **isStatic**( ) => *boolean*
Returns true if the opcode cannot change state.
#### *opcode* . **isJump** ( ) **=>** *boolean*
#### *opcode* . **isJump**( ) => *boolean*
Returns true if the opcode is a jumper operation.
#### *opcode* . **isPush**( ) => *number*
Returns 0 if the opcode is not a `PUSH*`, or the number of bytes this opcode will push if it is.
#### *opcode* . **isPush** ( ) **=>** *number*
Returns 0 if the opcode is not a `PUSH*`, or the number
of bytes this opcode will push if it is.
-----
**Content Hash:** d71fdeafad470effc353664c161dec6982a9c29b1015a5726fd2a3f576f8e377

102
docs/api/other/assembly/api/index.html
View File

File diff suppressed because one or more lines are too long

170
docs/api/other/assembly/ast/README.md
View File

@ -7,245 +7,125 @@ Documentation: [html](https://docs-beta.ethers.io/)
Abstract Syntax Tree
====================
Parsing a file using the [Ethers ASM Dialect](../dialect) will
generate an Abstract Syntax Tree. The root node will always
be a [ScopeNode](./) whose name is `_`.
To parse a file into an Abstract Syntax tree, use the [parse](../api)
function.
Types
-----
### Location
#### **offset** **=>** *number*
#### **offset** => *number*
The offset into the source code to the start of this node.
#### **length** **=>** *number*
#### **length** => *number*
The length of characters in the source code to the end of this node.
#### **source** **=>** *string*
#### **source** => *string*
The source code of this node.
Nodes
-----
@TODO: Place a diagram here showing the hierarchy
### Node
#### *node* . **tag** **=>** *string*
#### *node* . **tag** => *string*
A unique tag for this node for the lifetime of the process.
#### *node* . **location** => *[Location](/api/other/assembly/ast/#asm-location)*
#### *node* . **location** **=>** *[Location](./)*
The source code and location within the source code that this
node represents.
The source code and location within the source code that this node represents.
### ValueNode
A **ValueNode** is a node which may manipulate the stack.
### LiteralNode
#### *literalNode* . **value** => *string*
The literal value of this node, which may be a [DataHexString](/api/utils/bytes/#DataHexString) or string of a decimal number.
#### *literalNode* . **value** **=>** *string*
The literal value of this node, which may be a [DataHexstring](../../../utils/bytes) or
string of a decimal number.
#### *literalNode* . **verbatim** **=>** *boolean*
This is true in a [DataNode](./) context, since in that case the
value should be taken verbatim and no `PUSH` operation shoud be
added, otherwise false.
#### *literalNode* . **verbatim** => *boolean*
This is true in a [DataNode](/api/other/assembly/ast/#asm-datanode) context, since in that case the value should be taken verbatim and no `PUSH` operation shoud be added, otherwise false.
### PopNode
#### *literalNode* . **index** => *number*
A **PopNode** is used to store a place-holder for an implicit pop from the
stack. It represents the code for an implicit place-holder (i.e. `$$`) or an
explicit place-holder (e.g. `$1`), which indicates the expect stack position
to consume.
#### *literalNode* . **index** **=>** *number*
The index this **PopNode** is representing. For an implicit place-holder
this is `0`.
The index this **PopNode** is representing. For an implicit place-holder this is `0`.
### LinkNode
A **LinkNode** represents a link to another [Node](./)'s data,
for example `$foo` or `#bar`.
#### *linkNode* . **label** **=>** *string*
#### *linkNode* . **label** => *string*
Te name of the target node.
#### *linkNode* . **type** => *"offset" | "length"*
#### *linkNode* . **type** **=>** *"offset"|"length"*
Whether this node is for an offset or a length value of the
target node.
Whether this node is for an offset or a length value of the target node.
### OpcodeNode
#### *opcodeNode* . **opcode** **=>** *[Opcode](../api)*
#### *opcodeNode* . **opcode** => *[Opcode](/api/other/assembly/api/#asm-opcode)*
The opcode for this Node.
#### *opcodeNode* . **operands** **=>** *Array< [ValueNode](./) >*
#### *opcodeNode* . **operands** => *Array< [ValueNode](/api/other/assembly/ast/#asm-valuenode) >*
A list of all operands passed into this Node.
### EvaluationNode
#### *literalNode* . **verbatim** => *boolean*
An **EvaluationNode** is used to execute code and insert the results
but does not generate
any output assembly, using the `{{! code here }}` syntax.
This is true in a [DataNode](/api/other/assembly/ast/#asm-datanode) context, since in that case the value should be taken verbatim and no `PUSH` operation shoud be added, otherwise false.
#### *literalNode* . **verbatim** **=>** *boolean*
This is true in a [DataNode](./) context, since in that case the
value should be taken verbatim and no `PUSH` operation shoud be
added, otherwise false.
#### *evaluationNode* . **script** **=>** *string*
#### *evaluationNode* . **script** => *string*
The code to evaluate and produce the result to use as a literal.
### ExecutionNode
An **ExecutionNode** is used to execute code but does not generate
any output assembly, using the `{{! code here }}` syntax.
#### *evaluationNode* . **script** **=>** *string*
#### *evaluationNode* . **script** => *string*
The code to execute. Any result is ignored.
### LabelledNode
A **LabelledNode** is used for any Node that has a name, and can therefore
be targetted by a [LinkNode](./).
#### *labelledNode* . **name** **=>** *string*
#### *labelledNode* . **name** => *string*
The name of this node.
### LabelNode
A **LabelNode** is used as a place to `JUMP` to by referencing it
name, using `@myLabel:`. A `JUMPDEST` is automatically inserted
at the bytecode offset.
### DataNode
A **DataNode** allows for data to be inserted directly into the output
assembly, using `@myData[ ... ]`. The data is padded if needed to ensure
values that would otherwise be regarded as a `PUSH` value does not impact
anything past the data.
#### *dataNode* . **data** **=>** *Array< [ValueNode](./) >*
#### *dataNode* . **data** => *Array< [ValueNode](/api/other/assembly/ast/#asm-valuenode) >*
The child nodes, which each represent a verbatim piece of data in insert.
### ScopeNode
A **ScopeNode** allows a new frame of reference that all [LinkNode](./)'s
will use when resolving offset locations, using `@myScope{ ... }`.
#### *scopeNode* . **statements** **=>** *Array< [Node](./) >*
#### *scopeNode* . **statements** => *Array< [Node](/api/other/assembly/ast/#asm-node) >*
The list of child nodes for this scope.
-----
**Content Hash:** 27350094145eafe8e3b166698c29705f2edee81f6126de4e45d957a7c35a7109

134
docs/api/other/assembly/ast/index.html
View File

File diff suppressed because one or more lines are too long

109
docs/api/other/assembly/dialect/README.md
View File

@ -7,139 +7,30 @@ Documentation: [html](https://docs-beta.ethers.io/)
Ethers ASM Dialect
==================
This provides a quick, high-level overcview of the **Ethers ASM Dialect**
for EVM, which is defined by the [Ethers ASM Dialect Grammar](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/asm/grammar.jison)
Once a program is compiled by a higher level langauge into ASM (assembly),
or hand-coded directly in ASM, it needs to be assembled into bytecode.
The assembly process performs a very small set of operations and is
intentionally simple and closely related to the underlying EVM bytecode.
Operations include embedding programs within programs (for example the
deployment bootstrap has the runtime embedded in it) and computing the
necessary offsets for jump operations.
The [Command-Line Assembler](../../../../cli/asm) can be used to assemble an
*Ethers ASM Dialect* file or to disassemble bytecode into its
human-readable (ish) opcodes and literals.
Opcodes
-------
An **Opcode** may be provided in either a *functional* or
*instructional* syntax. For Opcodes that require parameters,
the *functional* syntax is recommended and the *instructional*
syntax will raise a warning.
@TODO: Examples
Labels
------
A **Label** is a position in the program which can be jumped to. A
`JUMPDEST` is automatically added to this point in the assembled
output.
@TODO: Exmaples
Literals
--------
A **Literal** puts data on the stack when executed using a `PUSH`
operation.
A **Literal** can be provided using a [DataHexstring](../../../utils/bytes) or a decimal
byte value.
@TODO: exmples
Comments
--------
To enter a comment in the **Ethers ASM Dialect**, any text following
a semi-colon (i.e. `;`) is ignored by the assembler.
Scopes
------
A common case in Ethereum is to have one program embedded in another.
The most common use of this is embedding a Contract **runtime bytecode**
within a **deployment bytecode**, which can be used as **init code**.
When deploying a program to Ethereum, an **init transaction** is used. An
*init transaction* has a null `to` address and contains bytecode in
the `data`. This `data` bytecode is a program, that when executed
returns some other bytecode as a result, this restul is the bytecode
to be installed.
Therefore it is important that embedded code uses jumps relative to itself,
not the entire program it is embedded in, which also means that a jump
can **only** target its own scope, no parent or child scopes. This is
enforced by the assembler.
A scope may access the offset of any child [Data Segment](./) or
child [Scopes](./) (with respect to itself) and may access the length
of any [Data Segment](./) or [Scopes](./) anywhere in the program.
Every program in the **Ethers ASM Dialect** has a top-leve scope named `_`.
Data Segment
------------
A **Data Segment** allows arbitrary data to be embedded into a program,
which can be useful for lookup tables or deploy-time constants.
An emtpty **Data Segment** can also be used when a labelled location is
required, but without the `JUMPDEST` which a [Labels](./) adds.
@TODO: Example
Links
-----
A **Link** allows access to a [Scopes](./), [Data Segment](./) or [Labels](./).
To access the byte offset of a labelled item, use `$foobar`.
For a [Labels](./), the target must be directly reachable within this scope. For
a [Data Segment](./) or a [Scopes](./), it can be inside the same scope or any
child scope.
For a [Data Segment](./) or a [Labels](./), there is an additional type of
**Link**, which provides the length of the data or bytecode respectively. A
**Length Link** is accessed by `#foobar` and is pushed on the stack as a
literal.
Stack Placeholders
------------------
@TODO: exampl
Evaluation and Excution
-----------------------
-----
**Content Hash:** b8f100efb0bd6c794cc6d4ae97c0243e10e6c2fe471cf16ba4e751ed43722bba

104
docs/api/other/assembly/dialect/index.html
View File

File diff suppressed because one or more lines are too long

32
docs/api/other/assembly/index.html
View File

File diff suppressed because one or more lines are too long

26
docs/api/other/hardware/README.md
View File

@ -7,31 +7,17 @@ Documentation: [html](https://docs-beta.ethers.io/)
Hardware Wallets
================
LedgerSigner
------------
The [Ledger Hardware Wallets](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.ledger.com) are a fairly
popular brand.
TODO: importing
```
import { LedgerSigner } from "@ethersproject/hardware-wallets";
```
### API
#### **new ****LedgerSigner**( [ provider [ , type [ , path ] ] ] ) => *[LedgerSigner](/api/other/hardware/#hw-ledger)*
Connects to a Ledger Hardware Wallet. The *type* if left unspecified is determined by the environment; in node the default is "hid" and in the browser "u2f" is the default. The default Ethereum path is used if *path* is left unspecified.
#### **new** **LedgerSigner** ( [ provider [ , type [ , path ] ] ] ) **=>** *[LedgerSigner](./)*
Connects to a Ledger Hardware Wallet. The *type* if left unspecified is
determined by the environment; in node the default is "hid" and in the browser
"u2f" is the default. The default Ethereum path is used if *path* is left unspecified.
-----
**Content Hash:** 04412211499f34796f91e7112977e6f84607638be72dc600e488df07c4465805

38
docs/api/other/hardware/index.html
View File

File diff suppressed because one or more lines are too long

34
docs/api/other/index.html
View File

File diff suppressed because one or more lines are too long

54
docs/api/providers/README.md
View File

@ -7,53 +7,34 @@ Documentation: [html](https://docs-beta.ethers.io/)
Providers
=========
A **Provider** is an abstraction of a connection to the
Ethereum network, providing a concise, consistent interface
to standard Ethereum node functionality.
The ethers.js library provides several options which should
cover the vast majority of use-cases, but also includes the
necessary functions and classes for sub-classing if a more
custom configuration is necessary.
Most users should be able to simply use the [Default Provider](./).
Default Provider
----------------
#### *ethers* . **getDefaultProvider**( [ network , [ options ] ] ) => *[Provider](/api/providers/provider/)*
The default provider is the safest, easiest way to begin
developing on *Ethereum*, and it is also robust enough
for use in production.
Returns a new Provider, backed by multiple services, connected to *network*. Is no *network* is provided, **homestead** (i.e. mainnet) is used.
It creates a [FallbackProvider](other) connected to as many backend
services as possible. When a request is made, it is sent to
multiple backends simulatenously. As responses from each backend
are returned, they are checked that they agree. Once a quorum
has been reached (i.e. enough of the backends agree), the response
is provided to your application.
This ensures that if a backend has become out-of-sync, or if it
has been compromised that its responses are dropped in favor of
responses that match the majority.
The *options* is an object, with the following properties:
#### *ethers* . **getDefaultProvider** ( [ network ] ) **=>** *[Provider](provider)*
Returns a new Provider, backed by multiple services, connected
to *network*. Is no *network* is provided, **homestead**
(i.e. mainnet) is used.
Option Properties
#### Note: API Keys
It is highly recommended for production services that to acquire and specify an API Key for each sercice.
The deafult API Keys used by ethers are shared across all users, so services may throttle all services that are using the default API Keys during periods of load without realizing it.
Many services also have monitoring and usage metrics, which are only available if an API Key is specifie. This allows tracking how many requests are being sent and which methods are being used the most.
Some services also provide additional paid features, whichare only available when specifying an API Key.
Provider Documentation
----------------------
* [Provider](provider)
* [Accounts Methods](provider)
* [Blocks Methods](provider)
@ -66,11 +47,12 @@ Provider Documentation
* [JsonRpcProvider](jsonrpc-provider)
* [JsonRpcSigner](jsonrpc-provider)
* [JsonRpcUncheckedSigner](jsonrpc-provider)
* [Node-Specific Methods](jsonrpc-provider)
* [API Providers](api-providers)
* [EtherscanProvider](api-providers)
* [InfuraProvider](api-providers)
* [AlchemyProvider](api-providers)
* [CloudfrontProvider](api-providers)
* [CloudflareProvider](api-providers)
* [Other Providers](other)
* [FallbackProvider](other)
* [IpcProvider](other)
@ -83,7 +65,3 @@ Provider Documentation
* [Events and Logs](types)
* [Transactions](types)
-----
**Content Hash:** 29575fb7fa8a7a126446a463e402b3d444aaf8a36c9226d0644466e3ff899b07

179
docs/api/providers/api-providers/README.md
View File

@ -7,103 +7,190 @@ Documentation: [html](https://docs-beta.ethers.io/)
API Providers
=============
There are many services which offer a web API for accessing
the Ethereum Blockchain. These Providers allow connecting
to them, which simplifies development, since you do not need
to run your own instance or cluster of Ethereum nodes.
However, this reliance on third-party services can reduce
resiliance, security and increase the amount of required trust.
To mitigate these issues, it is recommended you use a
[Default Provider](..).
EtherscanProvider
-----------------
#### **new ***ethers* . *providers* . **EtherscanProvider**( [ network = "homestead" , [ apiKey ] ] )
The **EtherscanProvider** is backed by a combination of the various
[Etherscan APIs](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/etherscan.io/apis).
Create a new **EtherscanProvider** connected to *network* with the optional *apiKey*.
The *network* may be specified as **string** for a common network name, a **number** for a common chain ID or a [Network Object]provider-(network).
If no *apiKey* is provided, a shared API key will be used, which may result in reduced performance and throttled requests. It is highly recommended for production, you register with [Etherscan](https://etherscan.io) for your own API key.
#### *provider* . **getHistory** ( address ) **=>** *Array< History >*
@TODO... Explain
#### Note: Default API keys
If no *apiKey* is provided, a shared API key will be used, which may result in reduced performance and throttled requests.
It is highly recommended for production, you register with [Etherscan](https://etherscan.io) for your own API key.
#### **Supported Networks**
- Homestead (Mainnet)
- Ropsten (proof-of-work testnet)
- Rinkeby (proof-of-authority testnet)
- Gorli (clique testnet)
- Kovan (proof-of-authority testnet)
* Homestead (Mainnet)
* Ropsten (proof-of-work testnet)
* Rinkeby (proof-of-authority testnet)
* G&ouml;rli (clique testnet)
* Kovan (proof-of-authority testnet)
```javascript
// <hide>
const EtherscanProvider = ethers.providers.EtherscanProvider;
const apiKey = "...";
// </hide>
// Connect to mainnet (homestead)
provider = new EtherscanProvider();
// Connect to rinkeby testnet (these are equivalent)
provider = new EtherscanProvider("rinkeby");
provider = new EtherscanProvider(4);
const network = ethers.providers.getNetwork("rinkeby");
// <hide>
delete network._defaultProvider;
network
// </hide>
//!
provider = new EtherscanProvider(network);
// Connect to mainnet (homestead) with an API key
provider = new EtherscanProvider(null, apiKey);
provider = new EtherscanProvider("homestead", apiKey);
```
#### *provider* . **getHistory**( address ) => *Array< History >*
@TODO... Explain
InfuraProvider
--------------
#### **new ***ethers* . *providers* . **InfuraProvider**( [ network = "homestead" , [ apiKey ] ] )
The **InfuraProvider** is backed by the popular [INFURA](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/infura.io)
Ethereum service.
Create a new **InfuraProvider** connected to *network* with the optional *apiKey*.
The *network* may be specified as **string** for a common network name, a **number** for a common chain ID or a [Network Object]provider-(network).
The *apiKey* can be a **string** Project ID or an **object** with the properties `projectId` and `projectSecret` to specify a [Project Secret](https://infura.io/docs/gettingStarted/authentication) which can be used on non-public sources (like on a server) to further secure your API access and quotas.
#### Note: Default API keys
If no *apiKey* is provided, a shared API key will be used, which may result in reduced performance and throttled requests.
It is highly recommended for production, you register with [INFURA](https://infura.io) for your own API key.
#### **Supported Networks**
* Homestead (Mainnet)
* Ropsten (proof-of-work testnet)
* Rinkeby (proof-of-authority testnet)
* G&ouml;rli (clique testnet)
* Kovan (proof-of-authority testnet)
- Homestead (Mainnet)
- Ropsten (proof-of-work testnet)
- Rinkeby (proof-of-authority testnet)
- Gorli (clique testnet)
- Kovan (proof-of-authority testnet)
```javascript
// <hide>
const InfuraProvider = ethers.providers.InfuraProvider;
const projectId = "...";
const projectSecret = "...";
// </hide>
// Connect to mainnet (homestead)
provider = new InfuraProvider();
// Connect to the ropsten testnet
// (see EtherscanProvider above for other network examples)
provider = new InfuraProvider("ropsten");
// Connect to mainnet with a Project ID (these are equivalent)
provider = new InfuraProvider(null, projectId);
provider = new InfuraProvider("homestead", projectId);
// Connect to mainnet with a Project ID and Project Secret
provider = new InfuraProvider("homestead", {
projectId: projectId,
projectSecret: projectSecret
});
```
AlchemyProvider
---------------
#### **new ***ethers* . *providers* . **AlchemyProvider**( [ network = "homestead" , [ apiKey ] ] )
The **AlchemtProvider** is backed by [Alchemy](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/alchemyapi.io).
Create a new **AlchemyProvider** connected to *network* with the optional *apiKey*.
The *network* may be specified as **string** for a common network name, a **number** for a common chain ID or a [Network Object](/api/providers/types/#providers-Network).
#### Note: Default API keys
If no *apiKey* is provided, a shared API key will be used, which may result in reduced performance and throttled requests.
It is highly recommended for production, you register with [Alchemy](https://alchemyapi.io) for your own API key.
#### **Supported Networks**
* Homestead (Mainnet)
* Ropsten (proof-of-work testnet)
* Rinkeby (proof-of-authority testnet)
* G&ouml;rli (clique testnet)
* Kovan (proof-of-authority testnet)
- Homestead (Mainnet)
- Ropsten (proof-of-work testnet)
- Rinkeby (proof-of-authority testnet)
- Gorli (clique testnet)
- Kovan (proof-of-authority testnet)
CloudfrontProvider
```javascript
// <hide>
const AlchemyProvider = ethers.providers.AlchemyProvider;
const apiKey = "...";
// </hide>
// Connect to mainnet (homestead)
provider = new AlchemyProvider();
// Connect to the ropsten testnet
// (see EtherscanProvider above for other network examples)
provider = new AlchemyProvider("ropsten");
// Connect to mainnet with an API key (these are equivalent)
provider = new AlchemyProvider(null, apiKey);
provider = new AlchemyProvider("homestead", apiKey);
```
CloudflareProvider
------------------
#### **new ***ethers* . *providers* . **CloudflareProvider**( )
The CloudfrontProvider is backed by the [Cloudflare Ethereum Gateway](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developers.cloudflare.com/distributed-web/ethereum-gateway).
Create a new **CloudflareProvider** connected to mainnet (i.e. "homestead").
#### **Supported Networks**
* Homestead (Mainnet)
- Homestead (Mainnet)
```javascript
// <hide>
const CloudflareProvider = ethers.providers.CloudflareProvider;
// </hide>
// Connect to mainnet (homestead)
provider = new CloudflareProvider();
```
-----
**Content Hash:** 79ad5dae92f00fc2ef2aceff6620ed9ae5f12d92d9e29ebc6be1c5752e65322f

159
docs/api/providers/api-providers/index.html
View File

File diff suppressed because one or more lines are too long

60
docs/api/providers/index.html
View File

File diff suppressed because one or more lines are too long

110
docs/api/providers/jsonrpc-provider/README.md
View File

@ -7,127 +7,63 @@ Documentation: [html](https://docs-beta.ethers.io/)
JsonRpcProvider
===============
#### **new ***ethers* . *providers* . **JsonRpcProvider**( [ url [ , aNetworkish ] ] )
The [JSON-RPC API](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/wiki/wiki/JSON-RPC) is a
very popular method for interacting with Ethereum and is available in all
major Ethereum node implementations (e.g. [Geth](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/geth.ethereum.org)
and [Parity](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.parity.io)) as well as many third-party web
services (e.g. [INFURA](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/infura.io))
#### **new** *ethers* . *providers* . **JsonRpcProvider** ( [ url [ , aNetworkish ] ] )
Connect to a JSON-RPC API located at *url* using the /aNetworkish// network.
If *url* is not specified, the default (i.e. `http://localhost:8545`) is used
and if no network is specified, it will be determined automatically by
querying the node.
Connect to a JSON-RPC API located at *url* using the *aNetworkish* network. If *url* is not specified, the default (i.e. `http://localhost:8545`) is used and if no network is specified, it will be determined automatically by querying the node.
#### Note: Connecting to a Local Node
Each node implementation is slightly different and may require specific command-line
flags or changes in their Settings UI to enable JSON-RPC, unlock accounrs
or expose specific APIs. Please consult theit documentation.
Each node implementation is slightly different and may require specific command-line flags, configuration or settings in their UI to enable JSON-RPC, unlock accounrs or expose specific APIs. Please consult their documentation.
#### *jsonRpcProvider* . **getSigner**( [ addressOrIndex ] ) => *[JsonRpcSigner](/api/providers/jsonrpc-provider/#JsonRpcSigner)*
Returns a [JsonRpcSigner](/api/providers/jsonrpc-provider/#JsonRpcSigner) which is managed by this Ethereum node, at *addressOrIndex*. If no *addressOrIndex* is provided, the first account (account #0) is used.
#### *jsonRpcProvider* . **getUncheckedSigner**( [ addressOrIndex ] ) => *[JsonRpcUncheckedSigner](/api/providers/jsonrpc-provider/#UncheckedJsonRpcSigner)*
#### *jsonRpcProvider* . **getSigner** ( [ addressOrIndex ] ) **=>** *[JsonRpcSigner](./)*
Returns a [JsonRpcSigner](./) which is managed by this Ethereum node, at
*addressOrIndex*. If no *addressOrIndex* is provided, the first
account (account #0) is used.
#### *jsonRpcProvider* . **getUncheckedSigner** ( [ addressOrIndex ] ) **=>** *[JsonRpcUncheckedSigner](./)*
#### *jsonRpcProvider* . **listAccounts** ( ) **=>** *Array< string >*
#### *jsonRpcProvider* . **listAccounts**( ) => *Array< string >*
Returns a list of all account addresses managed by this provider.
#### *jsonRpcProvider* . **send** ( method , params ) **=>** *Promise< any >*
#### *jsonRpcProvider* . **send**( method , params ) => *Promise< any >*
Allows sending raw messages to the provider.
This can be used for backend-specific calls, such as for debugging or
specific account management.
This can be used for backend-specific calls, such as for debugging or specific account management.
JsonRpcSigner
-------------
A **JsonRpcSigner** is a simple Signer which is backed by a connected
[JsonRpcProvider](./).
#### *signer* . **provider** **=>** *[JsonRpcProvider](./)*
#### *signer* . **provider** => *[JsonRpcProvider](/api/providers/jsonrpc-provider/)*
The provider this signer was established from.
#### *signer* . **connectUnchecked**( ) => *[JsonRpcUncheckedSigner](/api/providers/jsonrpc-provider/#UncheckedJsonRpcSigner)*
Returns a new Signer object which does not perform addtional checks when sending a transaction. See [getUncheckedSigner](/api/providers/jsonrpc-provider/#JsonRpcProvider-getUncheckedSigner) for more details.
#### *signer* . **connectUnchecked** ( ) **=>** *[JsonRpcUncheckedSigner](./)*
#### *signer* . **sendUncheckedTransaction**( transaction ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > > >*
Returns a new Signer object which does not perform addtional checks when
sending a transaction. See [JsonRpcUncheckedSigner](./) for more details.
Sends the *transaction* and returns a Promise which resolves to the opacque transaction hash.
#### *signer* . **sendUncheckedTransaction** ( transaction ) **=>** *Promise< string< [DataHexstring](../../utils/bytes)< 32 > > >*
Sends the *transaction* and returns a Promise which resolves to the
opacque transaction hash.
#### *signer* . **unlock** ( password ) **=>** *Promise< boolean >*
#### *signer* . **unlock**( password ) => *Promise< boolean >*
Request the node unlock the account (if locked) using *password*.
JsonRpcUncheckedSigner
----------------------
Node-Specific Methods
---------------------
The JSON-RPC API only provides a transaction hash as the response when a
transaction is sent, but the ethers Provider requires populating all details
of a transaction before returning it. For example, the gas price and gas limit
may be adjusted by the node or the nonce automatically included, in which case
the opaque transaction hash has discarded this.
To remedy this, the [JsonRpcSigner](./) immeidately queries the provider for
the details using the returned transaction hash to populate the [TransactionResponse](../types)
object.
Some backends do not respond immediately and instead defer releasing the
details of a transaction it was responsible for signing until it is mined.
The **UncheckedSigner** does not populate any additional information and will
immediately return the result as a mock [TransactionResponse](../types)-like
object, with most of the properties set to null, but allows access to the
transaction hash quickly, if that is all that is required.
-----
**Content Hash:** d60a1c5ef2f317ae59bc4b22a1e9d079f1762f60f6321b5da1efbe07d8284284

84
docs/api/providers/jsonrpc-provider/index.html
View File

File diff suppressed because one or more lines are too long

165
docs/api/providers/other/README.md
View File

@ -7,181 +7,116 @@ Documentation: [html](https://docs-beta.ethers.io/)
Other Providers
===============
Others...
FallbackProvider
----------------
#### **new ***ethers* . *providers* . **FallbackProvider**( providers [ , quorum ] )
The **FallbackProvider** is the most advanced [Provider](../provider) available in
ethers.
Creates a new instance of a FallbackProvider connected to *providers*. If quorum is not specified, half of the total sum of the provider weights is used.
It uses a quorum and connects to multiple [Providers](../provider) as backends,
each configured with a *priority* and a *weight* .
When a request is made, the request is dispatched to multiple backends, randomly
choosen (higher prioirty backends are always selected first) and the results from
each are compared against the others. Only once the quorum has been reached will that
result be accepted and returned to the caller.
By default the quorum requires 50% (rounded up) of the backends to agree. The *weight*
can be used to give a backend Provider more influence.
The *providers* can be either an array of [Provider](/api/providers/provider/) or [FallbackProviderConfig](/api/providers/other/#FallbackProviderConfig). If a [Provider](/api/providers/provider/) is provided, the defaults are a priority of 1 and a weight of 1.
#### **new** *ethers* . *providers* . **FallbackProvider** ( providers [ , quorum ] )
Creates a new instance of a FallbackProvider connected to *providers*. If
quorum is not specified, half of the total sum of the provider weights is
used.
The *providers* can be either an array of [Provider](../provider) or [FallbackProviderConfig](./).
If a [Provider](../provider) is provided, the defaults are a priority of 1 and a weight of 1.
#### *provider* . **providerConfigs** **=>** *Array< [FallbackProviderConfig](./) >*
#### *provider* . **providerConfigs** => *Array< [FallbackProviderConfig](/api/providers/other/#FallbackProviderConfig) >*
The list of Provider Configurations that describe the backends.
#### *provider* . **quorum** => *number*
#### *provider* . **quorum** **=>** *number*
The quorum the backend responses must agree upon before a result will be
resolved. By default this is *half the sum of the weights*.
The quorum the backend responses must agree upon before a result will be resolved. By default this is *half the sum of the weights*.
### FallbackProviderConfig
#### *fallbackProviderConfig* . **provider** **=>** *[Provider](../provider)*
#### *fallbackProviderConfig* . **provider** => *[Provider](/api/providers/provider/)*
The provider for this configuration.
#### *fallbackProviderConfig* . **priority** => *number*
The priority used for the provider. Higher priorities are favoured over lower priorities. If multiple providers share the same prioirty, they are choosen at random.
#### *fallbackProviderConfig* . **priority** **=>** *number*
#### *fallbackProviderConfig* . **stallTimeout** => *number*
The priority used for the provider. Higher priorities are favoured over lower
priorities. If multiple providers share the same prioirty, they are choosen
at random.
The timeout (in ms) after which another [Provider](/api/providers/provider/) will be attempted. This does not affect the current Provider; if it returns a result it is counted as part of the quorum.
Lower values will result in more network traffic, but may reduce the response time of requests.
#### *fallbackProviderConfig* . **weight** => *number*
#### *fallbackProviderConfig* . **stallTimeout** **=>** *number*
The timeout (in ms) after which another [Provider](../provider) will be attempted. This
does not affect the current Provider; if it returns a result it is counted
as part of the quorum.
Lower values will result in more network traffic, but may reduce the response
time of requests.
#### *fallbackProviderConfig* . **weight** **=>** *number*
The weight a response from this provider provides. This can be used if a given
[Provider](../provider) is more trusted, for example.
The weight a response from this provider provides. This can be used if a given [Provider](/api/providers/provider/) is more trusted, for example.
IpcProvider
-----------
#### *ipcProvider* . **path** => *string*
The **IpcProvider** allows the JSON-RPC API to be used over a local
filename on the file system, exposed by Geth, Parity and other nodes.
This is only available in *node.js* (as it requires file system access,
and may have additional complications due to file permissions. See any
related notes on the documentation for the actual node implementation websites.
#### *ipcProvider* . **path** **=>** *string*
The path this [Provider](../provider) is connected to.
The path this [Provider](/api/providers/provider/) is connected to.
UrlJsonRpcProvider
------------------
#### **new ***ethers* . *providers* . **UrlJsonRpcProvider**( [ network [ , apiKey ] ] )
This class is intended to be sub-classed and not used directly. It
simplifies creating a [Provider](../provider) where a normal [JsonRpcProvider](../jsonrpc-provider)
would suffice, with a little extra effort needed to generate the JSON-RPC
URL.
Sub-classes do not need to override this. Instead they should override the static method `getUrl` and optionally `getApiKey`.
#### **new** *ethers* . *providers* . **UrlJsonRpcProvider** ( [ network [ , apiKey ] ] )
Sub-classes do not need to override this. Instead they should override the
static method `getUrl` and optionally `getApiKey`.
#### *urlJsonRpcProvider* . **apiKey** **=>** *any*
#### *urlJsonRpcProvider* . **apiKey** => *any*
The value of the apiKey that was returned from `InheritedClass.getApiKey`.
#### *InheritingClass* . **getApiKey**( apiKey ) => *any*
This function should examine the *apiKey* to ensure it is valid and return a (possible modified) value to use in `getUrl`.
#### *InheritingClass* . **getApiKey** ( apiKey ) **=>** *any*
This function should examine the *apiKey* to ensure it is valid and
return a (possible modified) value to use in `getUrl`.
#### *InheritingClass* . **getUrl** ( network , apiKey ) **=>** *string*
#### *InheritingClass* . **getUrl**( network , apiKey ) => *string*
The URL to use for the JsonRpcProvider instance.
Web3Provider
------------
#### **new ***ethers* . *providers* . **Web3Provider**( externalProvider [ , network ] )
The Web3Provider is meant to ease moving from a [web3.js based](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/web3.js)
application to ethers by wraping an existing Web3-compatible (such as a
[Web3HttpProvider](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-http)[Web3IpcProvider](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ipc) or
[Web3WsProvider](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/web3.js/tree/1.x/packages/web3-providers-ws)) and exposing it as an ethers.js [Provider](../provider)
which can then be used with the rest of the library.
Create a new **Web3Provider**, which wraps an [EIP-1193 Provider](https://eips.ethereum.org/EIPS/eip-1193) or Web3Provider-compatible Provider.
#### **new** *ethers* . *providers* . **Web3Provider** ( web3Provider [ , network ] )
Create a new **Web3Provider**, which wraps an [EIP-1193 Provider]() or
Web3Provider-compatible Provider.
#### *web3Provider* . **provider** **=>** *Web3CompatibleProvider*
#### *web3Provider* . **provider** => *Web3CompatibleProvider*
The provider used to create this instance.
### ExternalProvider
#### *externalProvider* . **request**( request ) => *Promise< any >*
This follows the [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) API signature.
The *request* should be a standard JSON-RPC payload, which should at a minimum specify the `method` and `params`.
The result should be the actual result, which differs from the Web3.js response, which is a wrapped JSON-RPC response.
#### *externalProvider* . **sendAsync**( request , callback ) => *void*
This follows the [Web3.js Provider Signature](https://github.com/ethereum/web3.js/blob/1.x/packages/web3-providers-http/types/index.d.ts#L57).
The *request* should be a standard JSON-RPC payload, which should at a minimum specify the `method` and `params`.
The *callback* should use the error-first calling semantics, so `(error, result)` where the result is a JSON-RPC wrapped result.
#### *externalProvider* . **send**( request , callback ) => *void*
This is identical to `sendAsync`. Historically, this used a synchronous web request, but no current browsers support this, so its use this way was deprecated quite a long time ago
-----
**Content Hash:** e85f8ef6e4b1924ef63365dd6f761aa0ef5db23ebdd124686763d5061551a8bf

124
docs/api/providers/other/index.html
View File

File diff suppressed because one or more lines are too long

351
docs/api/providers/provider/README.md
View File

@ -7,269 +7,306 @@ Documentation: [html](https://docs-beta.ethers.io/)
Provider
========
Explain what a provider is...
Accounts Methods
----------------
#### *provider* . **getBalance** ( address [ , blockTag="latest" ] ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
#### *provider* . **getBalance**( address [ , blockTag = latest ] ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the balance of *address* as of the *blockTag* block height.
#### *provider* . **getCode**( address [ , blockTag = latest ] ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString) > >*
Returns the contract code of *address* as of the *blockTag* block height. If there is no contract currently deployed, the result is `0x`.
#### *provider* . **getCode** ( address [ , blockTag="latest" ] ) **=>** *Promise< string< [DataHexstring](../../utils/bytes) > >*
Returns the contract code of *address* as of the *blockTag* block height. If there is
no contract currently deployed, the result is `0x`.
#### *provider* . **getStorageAt** ( addr , pos [ , blockTag="latest" ] ) **=>** *Promise< string< [DataHexstring](../../utils/bytes) > >*
#### *provider* . **getStorageAt**( addr , pos [ , blockTag = latest ] ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString) > >*
Returns the `Bytes32` value of the position *pos* at address *addr*, as of the *blockTag*.
#### *provider* . **getTransactionCount**( address [ , blockTag = latest ] ) => *Promise< number >*
#### *provider* . **getTransactionCount** ( address [ , blockTag="latest" ] ) **=>** *Promise< number >*
Returns the number of transactions *address* has ever **sent**, as of *blockTag*.
This value is required to be the nonce for the next transaction from *address*
sent to the network.
### Examples
Returns the number of transactions *address* has ever **sent**, as of *blockTag*. This value is required to be the nonce for the next transaction from *address* sent to the network.
```javascript
Skipping JavaScript Evaluation.
// Get the balance for an account...
provider.getBalance("ricmoo.firefly.eth");
//!
// Get the code for a contract...
provider.getCode("registrar.firefly.eth");
//!
// Get the storage value at position 0...
provider.getStorageAt("registrar.firefly.eth", 0)
//!
// Get transaction count of an account...
provider.getTransactionCount("ricmoo.firefly.eth");
//!
```
Blocks Methods
--------------
#### *provider* . **getBlock**( block ) => *Promise< [Block](/api/providers/types/#providers-Block) >*
Get the *block* from the network, where the `result.transactions` is a list of transaction hashes.
#### *provider* . **getBlock** ( block ) **=>** *Promise< [Block](../types) >*
#### *provider* . **getBlockWithTransactions**( block ) => *Promise< [BlockWithTransactions](/api/providers/types/#providers-BlockWithTransactions) >*
Get the *block* from the network, where the `result.transactions` is a list
of transaction hashes.
#### *provider* . **getBlockWithTransactions** ( block ) **=>** *Promise< [BlockWithTransactions](../types) >*
Get the *block* from the network, where the `result.transactions` is
an Array of [TransactionResponse](../types) objects.
Get the *block* from the network, where the `result.transactions` is an Array of [TransactionResponse](/api/providers/types/#providers-TransactionResponse) objects.
```javascript
provider.getBlock(100004)
//!
provider.getBlockWithTransactions(100004)
//!
```
Ethereum Naming Service (ENS) Methods
-------------------------------------
#### *provider* . **lookupAddress**( address ) => *Promise< string >*
TODO: Explain ENS here...
Performs a reverse lookup of the *address* in ENS using the *Reverse Registrar*. If the name does not exist, or the forward lookup does not match, `null` is returned.
#### *provider* . **lookupAddress** ( address ) **=>** *Promise< string >*
Performs a reverse lookup of the *address* in ENS using the
*Reverse Registrar*. If the name does not exist, or the
forward lookup does not match, `null` is returned.
#### *provider* . **resolveName** ( name ) **=>** *Promise< string< [Address](../../utils/address) > >*
Looks up the address of *name*. If the name is not owned, or
does not have a *Resolver* configured, or the *Resolver* does
not have an address configured, `null` is returned.
### Examples
#### *provider* . **resolveName**( name ) => *Promise< string< [Address](/api/utils/address/#address) > >*
Looks up the address of *name*. If the name is not owned, or does not have a *Resolver* configured, or the *Resolver* does not have an address configured, `null` is returned.
```javascript
Skipping JavaScript Evaluation.
// Reverse lookup of an ENS by address...
provider.lookupAddress("0x6fC21092DA55B392b045eD78F4732bff3C580e2c");
//!
// Lookup an address of an ENS name...
provider.resolveName("ricmoo.firefly.eth");
//!
```
Logs Methods
------------
#### *provider* . **getLogs**( filter ) => *Promise< Array< [Log](/api/providers/types/#providers-Log) > >*
Returns the Array of [Log](/api/providers/types/#providers-Log) matching the *filter*.
#### *provider* . **getLogs** ( filter ) **=>** *Promise< Array< [Log](../types) > >*
Returns the Array of [Log](../types) matching the *filter*.
Keep in mind that many backends will discard old events, and that requests
which are too broad may get dropped as they require too many resources to
execute the query.
Keep in mind that many backends will discard old events, and that requests which are too broad may get dropped as they require too many resources to execute the query.
Network Status Methods
----------------------
#### *provider* . **getNetwork**( ) => *Promise< [Network](/api/providers/types/#providers-Network) >*
Returns the [Network](/api/providers/types/#providers-Network) this Provider is connected to.
#### *provider* . **getNetwork** ( ) **=>** *Promise< [Network](../types) >*
Returns the [Network](../types) this Provider is connected to.
#### *provider* . **getBlockNumber** ( ) **=>** *Promise< number >*
#### *provider* . **getBlockNumber**( ) => *Promise< number >*
Returns the block number (or height) of the most recently mined block.
#### *provider* . **getGasPrice**( ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns a *best guess* of the [Gas Price](/concepts/gas/#gas-price) to use in a transaction.
#### *provider* . **getGasPrice** ( ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
Returns a *best guess* of the [Gas Price](../../../concepts/gas) to use in a transaction.
```javascript
// The network information
provider.getNetwork()
// <hide>
//!
network = utils.shallowCopy(_)
delete network._defaultProvider
network
// </hide>
//!
// The current block number
provider.getBlockNumber()
//!
// Get the current suggested gas price (in wei)...
gasPrice = await provider.getGasPrice()
//! async gasPrice
// ...often this gas price is easier to understand or
// display to the user in gwei (giga-wei, or 1e9 wei)
utils.formatUnits(gasPrice, "gwei")
//!
```
Transactions Methods
--------------------
#### *provider* . **call**( transaction [ , blockTag = latest ] ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString) > >*
Returns the result of executing the *transaction*, using *call*. A call does not require any ether, but cannot change any state. This is useful for calling gettings on Contracts.
#### *provider* . **call** ( transaction [ , blockTag="latest" ] ) **=>** *Promise< string< [Hexstring](../../utils/bytes) > >*
#### *provider* . **estimateGas**( transaction ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the result of executing the *transaction*, using *call*. A call
does not require any ether, but cannot change any state. This is useful
for calling gettings on Contracts.
Returns an estimate of the amount of gas that would be required to submit *transaction* to the network.
An estimate may not be accurate since there could be another transaction on the network that was not accounted for, but after being mined affected relevant state.
#### *provider* . **sendTransaction**( transaction ) => *Promise< [TransactionResponse](/api/providers/types/#providers-TransactionResponse) >*
Submits *transaction* to the network to be mined. The *transaction* **must** be signed, and be valid (i.e. the nonce is correct and the account has sufficient balance to pay for the transaction).
#### *provider* . **estimateGas** ( transaction ) **=>** *Promise< [BigNumber](../../utils/bignumber) >*
Returns an estimate of the amount of gas that would be required to submit *transaction*
to the network.
An estimate may not be accurate since there could be another transaction
on the network that was not accounted for, but after being mined affected
relevant state.
#### *provider* . **sendTransaction** ( transaction ) **=>** *Promise< [TransactionResponse](../types) >*
Submits *transaction* to the network to be mined. The *transaction* **must** be signed,
and be valid (i.e. the nonce is correct and the account has sufficient balance to pay
for the transaction).
#### *provider* . **waitForTransaction** ( transactionHash ) **=>** *Promise< [TransactionReceipt](../types) >*
#### *provider* . **waitForTransaction**( hash [ , confirms = 1 [ , timeout ] ] ) => *Promise< [TxReceipt](/api/providers/types/#providers-TransactionReceipt) >*
Returns a Promise which will not resolve until *transactionHash* is mined.
Event Emitter Methods
---------------------
Explain events here...
#### *provider* . **on** ( eventName , listener ) **=>** *this*
#### *provider* . **on**( eventName , listener ) => *this*
Add a *listener* to be triggered for each *eventName*.
#### *provider* . **once**( eventName , listener ) => *this*
Add a *listener* to be triggered for only the next *eventName*, at which time it be removed.
#### *provider* . **once** ( eventName , listener ) **=>** *this*
#### *provider* . **emit**( eventName , ...args ) => *boolean*
Add a *listener* to be triggered for only the next *eventName*,
at which time it be removed.
Notify all listeners of *eventName*, passing *args* to each listener. This is generally only used internally.
#### *provider* . **off**( eventName [ , listener ] ) => *this*
Remove a *listener* for *eventName*. If no *listener* is provided, all listeners for *eventName* are removed.
#### *provider* . **emit** ( eventName , ...args ) **=>** *boolean*
#### *provider* . **removeAllListeners**( [ eventName ] ) => *this*
Notify all listeners of *eventName*, passing *args* to each listener. This
is generally only used internally.
Remove all the listeners for *eventName*. If no *eventName* is provided, **all** events are removed.
#### *provider* . **listenerCount**( [ eventName ] ) => *number*
Returns the number of listeners for *eventName*. If no *eventName* is provided, the total number of listeners is returned.
#### *provider* . **off** ( eventName [ , listener ] ) **=>** *this*
Remove a *listener* for *eventName*. If no *listener* is provided,
all listeners for *eventName* are removed.
#### *provider* . **removeAllListeners** ( [ eventName ] ) **=>** *this*
Remove all the listeners for *eventName*. If no *eventName* is provided,
**all** events are removed.
#### *provider* . **listenerCount** ( [ eventName ] ) **=>** *number*
Returns the number of listeners for *eventName*. If no *eventName* is
provided, the total number of listeners is returned.
#### *provider* . **listeners** ( eventName ) **=>** *Array< Listener >*
#### *provider* . **listeners**( eventName ) => *Array< Listener >*
Returns the list of Listeners for *eventName*.
### Events
#### **Log Filter**
A filter is an object, representing a contract log Filter, which has the optional properties `address` (the source contract) and `topics` (a topic-set to match).
If `address` is unspecified, the filter matches any contract address.
See events for more information on how to specify topic-sets.
#### **Topic-Set Filter**
The value of a **Topic-Set Filter** is a array of Topic-Sets.
This event is identical to a *Log Filter* with the address omitted (i.e. from any contract).
#### **Transaction Filter**
The value of a **Transaction Filter** is any transaction hash.
This event is emitted on every block that is part of a chain that includes the given mined transaction. It is much more common that the [once](/api/providers/provider/#Provider-once) method is used than the [on](/api/providers/provider/#Provider-on) method.
In addition to transaction and filter events, there are several named events.
Named Provider Events
```javascript
// <hide>
const txHash = utils.id("dummy-data");
const myAddress = ethers.constants.HashZero;
const myOtherAddress = ethers.constants.HashZero;
// </hide>
provider.on("block", (blockNumber) => {
// Emitted on every block change
})
provider.once(txHash, (transaction) => {
// Emitted when the transaction has been mined
})
// This filter could also be generated with the Contract or
// Interface API. If address is not specified, any address
// matches and if topics is not specified, any log matches
filter = {
address: "dai.tokens.ethers.eth",
topics: [
utils.id("Transfer(address,address,uint256")
]
}
provider.on(filter, (log, event) => {
// Emitted whenever a DAI token transfer occurs
})
// 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"),
null,
[
myAddress,
myOtherAddress
]
]
provider.on(topicSets, (log, event) => {
// Emitted any token is sent TO either address
})
provider.on("pending", (tx) => {
// Emitted when any new pending transaction is noticed
});
provider.on("error", (tx) => {
// Emitted when any error occurs
});
// <hide>
// Make sure our documentation builds without waiting forever
provider.removeAllListeners()
// </hide>
```
Inspection Methods
------------------
#### *Provider* . **isProvider** ( object ) **=>** *boolean*
#### *Provider* . **isProvider**( object ) => *boolean*
Returns true if and only if *object* is a Provider.
-----
**Content Hash:** 22872aec1236c5cf8fb457e93f36ca9bcd260acddc08c1ededc642931fd1625f

249
docs/api/providers/provider/index.html
View File

File diff suppressed because one or more lines are too long

418
docs/api/providers/types/README.md
View File

@ -7,579 +7,351 @@ Documentation: [html](https://docs-beta.ethers.io/)
Types
=====
BlockTag
--------
A **BlockTag** specifies a specific location in the Blockchain.
* **`"latest"`** -- The most recently mined block
* **`"earliest"`** -- Block #0
* **`"pending"`** -- The block currently being prepared for mining; not all operations and backends support this BlockTag
* ***number*** -- The block at this height
* ***a negative number*** -- The block this many blocks ago
### EventType
And **EventType** can be any of the following.
* ***string*** -- TODO...
* ***Array<string<[DataHexstring](../../utils/bytes)<32>> | Array<string<[DataHexstring](../../utils/bytes)<32>>>>*** -- TODO...
* ***[EventFilter](./)*** -- TODO...
Network
-------
#### *network* . **name** => *string*
A **Network** represents an Etherem network.
The human-readable name of the network, such as `homestead`. If the network name is unknown, this will be `"unknown"`.
#### *network* . **name** **=>** *string*
The human-readable name of the network, such as `homestead`. If the network
name is unknown, this will be `"unknown"`.
#### *network* . **chainId** **=>** *number*
#### *network* . **chainId** => *number*
The Chain ID of the network.
#### *network* . **ensAddress** **=>** *string< [Address](../../utils/address) >*
#### *network* . **ensAddress** => *string< [Address](/api/utils/address/#address) >*
The address at which the ENS registry is deployed on this network.
Block
-----
#### *block* . **hash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *block* . **hash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The hash of this block.
#### *block* . **parentHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *block* . **parentHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The hash of the previous block.
#### *block* . **number** **=>** *number*
#### *block* . **number** => *number*
The height (number) of this block.
#### *block* . **timestamp** **=>** *number*
#### *block* . **timestamp** => *number*
The timestamp of this block.
#### *block* . **nonce** **=>** *string< [DataHexstring](../../utils/bytes) >*
#### *block* . **nonce** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
The nonce used as part of the proof-of-work to mine this block.
This property is generally of little interest developers.
#### *block* . **difficulty** **=>** *number*
#### *block* . **difficulty** => *number*
The difficulty target required to be met by the miner of the block.
This property is generally of little interest developers.
#### *block* . **gasLimit** => *[BigNumber](/api/utils/bignumber/)*
#### *block* . **gasLimit** **=>** *[BigNumber](../../utils/bignumber)*
The maximum amount of gas that this block was permitted to use. This
is a value that can be voted up or voted down by miners and is used
to automatically adjust the bandwidth requirements of the network.
The maximum amount of gas that this block was permitted to use. This is a value that can be voted up or voted down by miners and is used to automatically adjust the bandwidth requirements of the network.
This property is generally of little interest developers.
#### *block* . **gasUsed** **=>** *[BigNumber](../../utils/bignumber)*
#### *block* . **gasUsed** => *[BigNumber](/api/utils/bignumber/)*
The total amount of gas used by all transactions in this block.
#### *block* . **miner** => *string*
The coinbase address of this block, which indicates the address the miner that mined this block would like the subsidy reward to go to.
#### *block* . **miner** **=>** *string*
The coinbase address of this block, which indicates the address the
miner that mined this block would like the subsidy reward to go to.
#### *block* . **extraData** **=>** *string*
#### *block* . **extraData** => *string*
This is extra data a miner may choose to include when mining a block.
This property is generally of little interest developers.
### Block (with transaction hashes)
#### *block* . **transactions** => *Array< string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > > >*
Often only the hashes of the transactions included in a block are needed,
so by default a block only contains this information, as it is
substantially less data.
#### *block* . **transactions** **=>** *Array< string< [DataHexstring](../../utils/bytes)< 32 > > >*
A list of the transactions hashes for each transaction this block
includes.
A list of the transactions hashes for each transaction this block includes.
### BlockWithTransactions
If all transactions for a block are needed, this object instead includes
the full details on each transaction.
#### *block* . **transactions** **=>** *Array< [TransactionResponse](./) >*
#### *block* . **transactions** => *Array< [TransactionResponse](/api/providers/types/#providers-TransactionResponse) >*
A list of the transactions this block includes.
Events and Logs
---------------
### EventFilter
#### *filter* . **address** **=>** *string< [Address](../../utils/address) >*
#### *filter* . **address** => *string< [Address](/api/utils/address/#address) >*
The address to filter by, or `null` to match any address.
#### *filter* . **topics** => *Array< string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > > | Array< string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > > > >*
#### *filter* . **topics** **=>** *Array< string< [DataHexstring](../../utils/bytes)< 32 > >|Array< string< [DataHexstring](../../utils/bytes)< 32 > > > >*
The topics to filter by, or `null` to match any topics. Each entry represents an
**AND** condition that must match, or may be `null` to match anything. If a given
entry is an Array, then that entry is treated as an **OR** for any value in the entry.
The topics to filter by, or `null` to match any topics. Each entry represents an **AND** condition that must match, or may be `null` to match anything. If a given entry is an Array, then that entry is treated as an **OR** for any value in the entry.
### Filter
#### *filter* . **fromBlock** **=>** *[BlockTag](./)*
#### *filter* . **fromBlock** => *[BlockTag](/api/providers/types/#providers-BlockTag)*
The starting block (inclusive) to search for logs matching the filter criteria.
#### *filter* . **toBlock** **=>** *[BlockTag](./)*
#### *filter* . **toBlock** => *[BlockTag](/api/providers/types/#providers-BlockTag)*
The end block (inclusive) to search for logs matching the filter criteria.
### FilterByBlockHash
#### *filter* . **blockHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *filter* . **blockHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The specific block (by its block hash) to search for logs matching the filter criteria.
### Log
#### *log* . **blockNumber** **=>** *number*
#### *log* . **blockNumber** => *number*
The block height (number) of the block including the transaction of this log.
#### *log* . **blockHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *log* . **blockHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The block hash of the block including the transaction of this log.
#### *log* . **removed** => *boolean*
During a re-org, if a transaction is orphaned, this will be set to true to indicate the Log entry has been removed; it will likely be emitted again in the near future when another block is mined with the transaction that triggered this log, but keep in mind the values may change.
#### *log* . **removed** **=>** *boolean*
During a re-org, if a transaction is orphaned, this will be set to true
to indicate the Log entry has been removed; it will likely be emitted
again in the near future when another block is mined with the transaction
that triggered this log, but keep in mind the values may change.
#### *log* . **transactionLogIndex** **=>** *number*
#### *log* . **transactionLogIndex** => *number*
The index of this log in the transaction.
#### *log* . **address** **=>** *string< [Address](../../utils/address) >*
#### *log* . **address** => *string< [Address](/api/utils/address/#address) >*
The address of the contract that generated this log.
#### *log* . **data** **=>** *string< [DataHexstring](../../utils/bytes) >*
#### *log* . **data** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
The data included in this log.
#### *log* . **topics** **=>** *Array< string< [DataHexstring](../../utils/bytes)< 32 > > >*
#### *log* . **topics** => *Array< string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > > >*
The list of topics (indexed properties) for this log.
#### *log* . **transactionHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *log* . **transactionHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The transaction hash of the transaction of this log.
#### *log* . **transactionIndex** **=>** *number*
#### *log* . **transactionIndex** => *number*
The index of the transaction in the block of the transaction of this log.
#### *log* . **logIndex** **=>** *number*
#### *log* . **logIndex** => *number*
The index of this log across all logs in the entire **block**.
Transactions
------------
### TransactionRequest
A transaction request describes a transaction that is to
be sent to the network or otherwise processed.
All fields are optional and may be a promise which resolves
to the required type.
#### *transactionRequest* . **to** **=>** *string|Promise< string >*
#### *transactionRequest* . **to** => *string | Promise< string >*
The address (or ENS name) this transaction it to.
#### *transactionRequest* . **from** **=>** *string< [Address](../../utils/address) >|Promise< string< [Address](../../utils/address) > >*
#### *transactionRequest* . **from** => *string< [Address](/api/utils/address/#address) > | Promise< string< [Address](/api/utils/address/#address) > >*
The address this transaction is from.
#### *transactionRequest* . **nonce** => *number | Promise< number >*
The nonce for this transaction. This should be set to the number of transactions ever sent **from** this address.
#### *transactionRequest* . **nonce** **=>** *number|Promise< number >*
The nonce for this transaction. This should be set to the number of
transactions ever sent **from** this address.
#### *transactionRequest* . **gasLimit** **=>** *[BigNumber](../../utils/bignumber)|Promise< [BigNumber](../../utils/bignumber) >*
#### *transactionRequest* . **gasLimit** => *[BigNumber](/api/utils/bignumber/) | Promise< [BigNumber](/api/utils/bignumber/) >*
The maximum amount of gas this transaction is permitted to use.
#### *transactionRequest* . **gasPrice** **=>** *[BigNumber](../../utils/bignumber)|Promise< [BigNumber](../../utils/bignumber) >*
#### *transactionRequest* . **gasPrice** => *[BigNumber](/api/utils/bignumber/) | Promise< [BigNumber](/api/utils/bignumber/) >*
The price (in wei) per unit of gas this transaction will pay.
#### *transactionRequest* . **data** **=>** *[DataHexstring](../../utils/bytes)|Promise< [DataHexstring](../../utils/bytes) >*
#### *transactionRequest* . **data** => *[DataHexString](/api/utils/bytes/#DataHexString) | Promise< [DataHexString](/api/utils/bytes/#DataHexString) >*
The transaction data.
#### *transactionRequest* . **value** **=>** *[BigNumber](../../utils/bignumber)|Promise< [BigNumber](../../utils/bignumber) >*
#### *transactionRequest* . **value** => *[BigNumber](/api/utils/bignumber/) | Promise< [BigNumber](/api/utils/bignumber/) >*
The amount (in wei) this transaction is sending.
#### *transactionRequest* . **chainId** => *number | Promise< number >*
The chain ID this transaction is authorized on, as specified by [EIP-155](https://eips.ethereum.org/EIPS/eip-155).
#### *transactionRequest* . **chainId** **=>** *number|Promise< number >*
The chain ID this transaction is authorized on, as specified by
[EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155).
If the chain ID is 0 will disable EIP-155 and the transaction will be valid
on any network. This can be **dangerous** and care should be taken, since it
allows transactions to be replayed on networks that were possibly not
intended.
If the chain ID is 0 will disable EIP-155 and the transaction will be valid on any network. This can be **dangerous** and care should be taken, since it allows transactions to be replayed on networks that were possibly not intended.
### TransactionResponse
#### *transaction* . **blockNumber** => *number*
A **TransactionResponse** includes all properties of a [Transaction](../../utils/transactions) as well as several
properties that are useful once it has been mined.
The number ("height") of the block this transaction was mined in. If the block has not been mined, this is `null`.
#### *transaction* . **blockNumber** **=>** *number*
#### *transaction* . **blockHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The number ("height") of the block this transaction was mined in. If the block has not been mined,
this is `null`.
The hash of the block this transaction was mined in. If the block has not been mined, this is `null`.
#### *transaction* . **timestamp** => *number*
The timestamp of the block this transaction was mined in. If the block has not been mined, this is `null`.
#### *transaction* . **blockHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *transaction* . **confirmations** => *number*
The hash of the block this transaction was mined in. If the block has not been mined,
this is `null`.
The number of blocks that have been mined (including the initial block) since this transaction was mined.
#### *transaction* . **timestamp** **=>** *number*
The timestamp of the block this transaction was mined in. If the block has not been mined,
this is `null`.
#### *transaction* . **confirmations** **=>** *number*
The number of blocks that have been mined (including the initial block) since this
transaction was mined.
#### *transaction* . **raw** **=>** *string< [DataHexstring](../../utils/bytes) >*
#### *transaction* . **raw** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
The serialized transaction.
#### *transaction* . **wait**( [ confirmations = 1 ] ) => *Promise< [TransactionReceipt](/api/providers/types/#providers-TransactionReceipt) >*
#### *transaction* . **wait** ( [ confirmations=1 ] ) **=>** *Promise< [TransactionReceipt](./) >*
Wait for *confirmations*. If 0, and the transaction has not been mined,
`null` is returned.
Wait for *confirmations*. If 0, and the transaction has not been mined, `null` is returned.
### TransactionReceipt
#### *receipt* . **to** => *string< [Address](/api/utils/address/#address) >*
The address this transaction is to. This is `null` if the the transaction was an **init transaction**, used to deploy a contract.
#### *receipt* . **to** **=>** *string< [Address](../../utils/address) >*
The address this transaction is to. This is `null` if the the
transaction was an **init transaction**, used to deploy a contract.
#### *receipt* . **from** **=>** *string< [Address](../../utils/address) >*
#### *receipt* . **from** => *string< [Address](/api/utils/address/#address) >*
The address this transaction is from.
#### *receipt* . **contractAddress** => *string< [Address](/api/utils/address/#address) >*
If this transaction has a `null` to address, it is an **init transaction** used to deploy a contract, in which case this is the address created by that contract.
To compute a contract address, the [getContractAddress](/api/utils/address/#utils-getContractAddress) utility function can also be used with a [TransactionResponse](/api/providers/types/#providers-TransactionResponse) object, which requires the transaction nonce and the address of the sender.
#### *receipt* . **contractAddress** **=>** *string< [Address](../../utils/address) >*
#### *receipt* . **transactionIndex** => *number*
If this transaction has a ``null` to address, it is an **init transaction**
used to deploy a contract, in which case this is the address created by that
contract.
To compute a contract address, the [getContractAddress](../../utils/address)
utility function can also be used with a [TransactionResponse](./)
object, which requires the transaction nonce and the address of the sender.
The index of this transaction in the list of transactions included in the block this transaction was mined in.
#### *receipt* . **transactionIndex** **=>** *number*
The index of this transaction in the list of transactions included in
the block this transaction was mined in.
#### *receipt* . **root** **=>** *string*
#### *receipt* . **root** => *string*
The intermediate state root of a receipt.
Only transactions included in blocks **before** the [Byzantium Hard Fork](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-609)
have this property, as it was replaced by the `status` property.
Only transactions included in blocks **before** the [Byzantium Hard Fork](https://eips.ethereum.org/EIPS/eip-609) have this property, as it was replaced by the `status` property.
The property is generally of little use to developers. At the time
it could be used to verify a state transition with a fraud-proof
only considering the single transaction; without it the full block
must be considered.
The property is generally of little use to developers. At the time it could be used to verify a state transition with a fraud-proof only considering the single transaction; without it the full block must be considered.
#### *receipt* . **gasUsed** **=>** *[BigNumber](../../utils/bignumber)*
#### *receipt* . **gasUsed** => *[BigNumber](/api/utils/bignumber/)*
The amount of gas actually used by this transaction.
#### *receipt* . **logsBloom** => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
A [bloom-filter](https://en.wikipedia.org/wiki/Bloom_filter), which incldues all the addresses and topics included in any log in this transaction.
#### *receipt* . **logsBloom** **=>** *string< [DataHexstring](../../utils/bytes) >*
A [bloom-filter](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Bloom_filter), which
incldues all the addresses and topics included in any log in this
transaction.
#### *receipt* . **blockHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *receipt* . **blockHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The block hash of the block that this transaction was included in.
#### *receipt* . **transactionHash** **=>** *string< [DataHexstring](../../utils/bytes)< 32 > >*
#### *receipt* . **transactionHash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The transaction hash of this transaction.
#### *receipt* . **logs** **=>** *Array< [Log](./) >*
#### *receipt* . **logs** => *Array< [Log](/api/providers/types/#providers-Log) >*
All the logs emitted by this transaction.
#### *receipt* . **blockNumber** => *number*
The block height (number) of the block that this transaction was included in.
#### *receipt* . **blockNumber** **=>** *number*
#### *receipt* . **confirmations** => *number*
The block height (number) of the block that this transaction was
included in.
The number of blocks that have been mined since this transaction, including the actual block it was mined in.
#### *receipt* . **cumulativeGasUsed** => *[BigNumber](/api/utils/bignumber/)*
#### *receipt* . **confirmations** **=>** *number*
The number of blocks that have been mined since this transaction,
including the actual block it was mined in.
#### *receipt* . **cumulativeGasUsed** **=>** *[BigNumber](../../utils/bignumber)*
For the block this transaction was included in, this is the sum of the
gas used used by each transaction in the ordered list of transactions
up to (and including) this transaction.
For the block this transaction was included in, this is the sum of the gas used used by each transaction in the ordered list of transactions up to (and including) this transaction.
This is generally of little interest to developers.
#### *receipt* . **byzantium** => *boolean*
This is true if the block is in a [post-Byzantium Hard Fork](https://eips.ethereum.org/EIPS/eip-609) block.
#### *receipt* . **byzantium** **=>** *boolean*
#### *receipt* . **status** => *boolean*
This is true if the block is in a [post-Byzantium Hard Fork](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-609)
block.
The status of a transaction is 1 is successful or 0 if it was reverted. Only transactions included in blocks [post-Byzantium Hard Fork](https://eips.ethereum.org/EIPS/eip-609) have this property.
#### *receipt* . **status** **=>** *boolean*
The status of a transaction is 1 is successful or 0 if it was
reverted. Only transactions included in blocks [post-Byzantium Hard Fork](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-609)
have this property.
-----
**Content Hash:** 911f42520657ebece6d9fe0456cae0540134758a7253057c42acffac94fb0895

267
docs/api/providers/types/index.html
View File

File diff suppressed because one or more lines are too long

373
docs/api/signer/README.md
View File

@ -7,356 +7,321 @@ Documentation: [html](https://docs-beta.ethers.io/)
Signers
=======
A Signer represents...
Signer
------
#### *signer* . **connect**( provider ) => *[Signer](/api/signer/#Signer)*
The **Signer** class is abstract and cannot be directly instaniated. Instead
use one of the concreate sub-classes, such as the [Wallet](./), [VoidSigner](./)
or [JsonRpcSigner](../providers/jsonrpc-provider).
Sub-classes **must** implement this, however they may simply throw an error if changing providers is not supported.
#### *signer* . **connect** ( provider ) **=>** *[Signer](./)*
Sub-classes **must** implement this, however they may simply throw an error
if changing providers is not supported.
#### *signer* . **getAddress** ( ) **=>** *Promise< string< [Address](../utils/address) > >*
#### *signer* . **getAddress**( ) => *Promise< string< [Address](/api/utils/address/#address) > >*
Returns a Promise that resolves to the account address.
This is a Promise so that a **Signer** can be designed around an
asynchronous source, such as hardware wallets.
This is a Promise so that a **Signer** can be designed around an asynchronous source, such as hardware wallets.
Sub-classes **must** implement this.
#### *Signer* . **isSigner** ( object ) **=>** *boolean*
#### *Signer* . **isSigner**( object ) => *boolean*
Returns true if an only if *object* is a **Signer**.
### Blockchain Methods
#### *signer* . **getBalance** ( [ blockTag="latest" ] ) **=>** *Promise< [BigNumber](../utils/bignumber) >*
#### *signer* . **getBalance**( [ blockTag = "latest" ] ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the balance of this wallet at *blockTag*.
#### *signer* . **getChainId** ( ) **=>** *Promise< number >*
#### *signer* . **getChainId**( ) => *Promise< number >*
Returns ths chain ID this wallet is connected to.
#### *signer* . **getGasPrice** ( ) **=>** *Promise< [BigNumber](../utils/bignumber) >*
#### *signer* . **getGasPrice**( ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the current gas price.
#### *signer* . **getTransactionCount**( [ blockTag = "latest" ] ) => *Promise< number >*
Returns the number of transactions this account has ever sent. This is the value required to be included in transactions as the `nonce`.
#### *signer* . **getTransactionCount** ( [ blockTag="latest" ] ) **=>** *Promise< number >*
#### *signer* . **call**( transactionRequest ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString) > >*
Returns the number of transactions this account has ever sent. This
is the value required to be included in transactions as the `nonce`.
Returns the result of calling using the *transactionRequest*, with this account address being used as the `from` field.
#### *signer* . **estimateGas**( transactionRequest ) => *Promise< [BigNumber](/api/utils/bignumber/) >*
Returns the result of estimating the cost to send the *transactionRequest*, with this account address being used as the `from` field.
#### *signer* . **call** ( transactionRequest ) **=>** *Promise< string< [DataHexstring](../utils/bytes) > >*
Returns the result of calling using the *transactionRequest*, with this
account address being used as the `from` field.
#### *signer* . **estimateGas** ( transactionRequest ) **=>** *Promise< [BigNumber](../utils/bignumber) >*
Returns the result of estimating the cost to send the *transactionRequest*,
with this account address being used as the `from` field.
#### *signer* . **resolveName** ( ensName ) **=>** *Promise< string< [Address](../utils/address) > >*
#### *signer* . **resolveName**( ensName ) => *Promise< string< [Address](/api/utils/address/#address) > >*
Returns the address associated with the *ensName*.
### Signing
#### *signer* . **signMessage**( message ) => *Promise< string< [RawSignature](/api/utils/bytes/#signature-raw) > >*
This returns a Promise which resolves to the [Raw Signature](/api/utils/bytes/#signature-raw) of *message*.
#### *signer* . **signMessage** ( message ) **=>** *Promise< string< [FlatSignature](../utils/bytes) > >*
This returns a Promise which resolves to the [Flat-Format Signature](../utils/bytes)
of *message*.
Sub-classes **must** implement this, however they may throw if signing a
message is not supported.
Sub-classes **must** implement this, however they may throw if signing a message is not supported, such as in a Contract-based Wallet or Meta-Transaction-based Wallet.
#### Note
If *message* is a string, it is **treated as a string** and
converted to its representation in UTF8 bytes.
If *message* is a string, it is **treated as a string** and converted to its representation in UTF8 bytes.
**If and only if** a message is a [Bytes](../utils/bytes) will it be treated as
binary data.
**If and only if** a message is a [Bytes](/api/utils/bytes/#Bytes) will it be treated as binary data.
For example, the string `"0x1234"` is 6 characters long (and in
this case 6 bytes long). This is **not** equivalent to the array
`[ 0x12, 0x34 ]`, which is 2 bytes long.
For example, the string `"0x1234"` is 6 characters long (and in this case 6 bytes long). This is **not** equivalent to the array `[ 0x12, 0x34 ]`, which is 2 bytes long.
A common case is to sign a hash. In this case, if the hash is a
string, it **must** be converted to an array first, using the
[arrayify](../utils/bytes) utility function.
A common case is to sign a hash. In this case, if the hash is a string, it **must** be converted to an array first, using the [arrayify](/api/utils/bytes/#utils-arrayify) utility function.
#### *signer* . **signTransaction** ( transactionRequest ) **=>** *Promise< string< [DataHexstring](../utils/bytes) > >*
#### *signer* . **signTransaction**( transactionRequest ) => *Promise< string< [DataHexString](/api/utils/bytes/#DataHexString) > >*
Returns a Promise which resolves to the signed transaction of the
*transactionRequest*. This method does not populate any missing fields.
Returns a Promise which resolves to the signed transaction of the *transactionRequest*. This method does not populate any missing fields.
Sub-classes **must** implement this, however they may throw if signing a
transaction is not supported.
Sub-classes **must** implement this, however they may throw if signing a transaction is not supported, which is common for security reasons in many clients.
#### *signer* . **sendTransaction**( transactionRequest ) => *Promise< [TransactionResponse](/api/providers/types/#providers-TransactionResponse) >*
This method populates the transactionRequest with missing fields, using [populateTransaction](/api/signer/#Signer-populateTransaction) and returns a Promise which resolves to the transaction.
#### *signer* . **sendTransaction** ( transactionRequest ) **=>** *Promise< [TransactionResponse](../providers/types) >*
This method populates the transactionRequest with missing fields, using
[populateTransaction](./) and returns a Promise which resolves to the transaction.
Sub-classes **must** implement this, however they may throw if signing a
transaction is not supported.
Sub-classes **must** implement this, however they may throw if sending a transaction is not supported, such as the [VoidSigner](/api/signer/#VoidSigner) or if the Wallet is offline and not connected to a [Provider](/api/providers/provider/).
### Sub-Classes
#### *signer* . **checkTransaction**( transactionRequest ) => *[TransactionRequest](/api/providers/types/#providers-TransactionRequest)*
It is very important that all important properties of a **Signer** are
**immutable**. Since Ethereum is very asynchronous and deals with critical
data (such as ether and other potentially valuable crypto assets), keeping
properties such as the *provider* and *address* static helps prevent
serious issues.
This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.
A sub-class **must** call `super()`.
This should return a **copy** of the *transactionRequest*, with any properties needed by `call`, `estimateGas` and `populateTransaction` (which is used by sendTransaction). It should also throw an error if any unknown key is specified.
The default implementation checks only valid [TransactionRequest](/api/providers/types/#providers-TransactionRequest) properties exist and adds `from` to the transaction if it does not exist.
If there is a `from` field it **must** be verified to be equal to the Signer's address.
#### *signer* . **checkTransaction** ( transactionRequest ) **=>** *[TransactionRequest](../providers/types)*
#### *signer* . **populateTransaction**( transactionRequest ) => *Promise< [TransactionRequest](/api/providers/types/#providers-TransactionRequest) >*
This is generally not required to be overridden, but may needed to provide
custom behaviour in sub-classes.
This should return a **copy** of the *transactionRequest*, with any properties
needed by `call`, `estimateGas` and `populateTransaction` (which is used
by sendTransaction). It should also throw an error if any unknown key is specified.
The default implementation checks only valid [TransactionRequest](../providers/types) properties
exist and adds `from` to the transaction if it does not exist, or verifies it is equal
to the Signer's address if it does exist.
#### *signer* . **populateTransaction** ( transactionRequest ) **=>** *Promise< [TransactionRequest](../providers/types) >*
This is generally not required to be overridden, but may needed to provide
custom behaviour in sub-classes.
This should return a **copy** of *transactionRequest*, follow the same procedure
as `checkTransaction` and fill in any properties required for sending a transaction.
The result should have all promises resolved; if needed the [resolveProperties](../utils/properties)
utility function can be used for this.
The default implementation calls `checkTransaction` and resolves to if it is an
ENS name, adds `gasPrice`, `nonce`, `gasLimit` and `chainId` based on the
related operations on Signer.
This is generally not required to be overridden, but may needed to provide custom behaviour in sub-classes.
This should return a **copy** of *transactionRequest*, follow the same procedure as `checkTransaction` and fill in any properties required for sending a transaction. The result should have all promises resolved; if needed the [resolveProperties](/api/utils/properties/#utils-resolveproperties) utility function can be used for this.
The default implementation calls `checkTransaction` and resolves to if it is an ENS name, adds `gasPrice`, `nonce`, `gasLimit` and `chainId` based on the related operations on Signer.
Wallet
------
#### **new ***ethers* . **Wallet**( privateKey [ , provider ] )
The Wallet class inherits [Signer](./) and can sign transactions and messages
using a private key as a standard Externally Owned Account (EOA).
Create a new Wallet instance for *privateKey* and optionally connected to the *provider*.
#### **new** *ethers* . **Wallet** ( privateKey [ , provider ] )
#### *ethers* . *Wallet* . **createRandom**( [ options = {} ] ) => *[Wallet](/api/signer/#Wallet)*
Create a new Wallet instance for *privateKey* and optionally
connected to the *provider*.
Returns a new Wallet with a random private key, generated from cryptographically secure entropy sources. If the current environment does not have a secure entropy source, an error is thrown.
Wallets created using this method will have a mnemonic.
#### *ethers* . *Wallet* . **fromEncryptedJson**( json , password [ , progress ] ) => *Promise< [Wallet](/api/signer/#Wallet) >*
Create an instance from an encrypted JSON wallet.
If *progress* is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.
#### *ethers* . *Wallet* . **createRandom** ( [ options={} ] ) **=>** *[Wallet](./)*
#### *ethers* . *Wallet* . **fromEncryptedJsonSync**( json , password ) => *[Wallet](/api/signer/#Wallet)*
Returns a new Wallet with a random private key, generated from
cryptographically secure entropy sources. If the current environment
does not have a secure entropy source, an error is thrown.
Create an instance from an encrypted JSON wallet.
This operation will operate synchronously which will lock up the user interface, possibly for a non-trivial duration. Most applications should use the asynchronous `fromEncryptedJson` instead.
#### *ethers* . *Wallet* . **fromEncryptedJson** ( json , password [ , progress ] ) **=>** *Promise< [Wallet](./) >*
Create an instance from an encrypted JSON wallet. If *progress*
is provided it will be called during decryption with a value between 0 and
1 indicating the progress towards completion.
#### *ethers* . *Wallet* . **fromMnemonic** ( mnemonic [ , path , [ wordlist ] ] ) **=>** *[Wallet](./)*
#### *ethers* . *Wallet* . **fromMnemonic**( mnemonic [ , path , [ wordlist ] ] ) => *[Wallet](/api/signer/#Wallet)*
Create an instance from a mnemonic phrase.
If path is not specified, the Ethereum default path is used (i.e. m/44'/60'/0'/0/0).
If path is not specified, the Ethereum default path is used (i.e. `m/44'/60'/0'/0/0`).
If wordlist is not specified, the English Wordlist is used.
### Properties
#### *wallet* . **address** **=>** *string< [Address](../utils/address) >*
#### *wallet* . **address** => *string< [Address](/api/utils/address/#address) >*
The address for the account this Wallet represents.
#### *wallet* . **provider** => *[Provider](/api/providers/provider/)*
#### *wallet* . **provider** **=>** *[Provider](../providers/provider)*
The provider this wallet is connected to, which will ge used for any [Blockchain Methods](./)
methods. This can be null.
The provider this wallet is connected to, which will ge used for any [Blockchain Methods](/api/signer/#Signer--blockchain-methods) methods. This can be null.
#### Note
A **Wallet** instance is immuatable, so if you wish to change the Provider, you
may use the [connect](./) method to create a new instance connected
to the desired provider.
A **Wallet** instance is immuatable, so if you wish to change the Provider, you may use the [connect](/api/signer/#Signer-connect) method to create a new instance connected to the desired provider.
#### *wallet* . **publicKey** **=>** *string< [DataHexstring](../utils/bytes)< 65 > >*
#### *wallet* . **publicKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 65 > >*
The uncompressed public key for this Wallet represents.
### Methods
#### *wallet* . **encrypt**( password , [ options = {} , [ progress ] ] ) => *Promise< string >*
Encrypt the wallet using *password* returning a Promise which resolves to a JSON wallet.
If *progress* is provided it will be called during decryption with a value between 0 and 1 indicating the progress towards completion.
#### *wallet* . **encrypt** ( password , [ options={} , [ progress ] ] ) **=>** *Promise< string >*
```javascript
// Create a wallet instance from a mnemonic...
mnemonic = "announce room limb pattern dry unit scale effort smooth jazz weasel alcohol"
walletMnemonic = Wallet.fromMnemonic(mnemonic)
Encrypt the wallet using *password* returning a Promise which resolves
to a JSON wallet.
// ...or from a private key
walletPrivateKey = new Wallet(walletMnemonic.privateKey)
walletMnemonic.address === walletPrivateKey.address
//!
// The address as a Promise per the Signer API
walletMnemonic.getAddress()
//!
// A Wallet address is also available synchronously
walletMnemonic.address
//!
// The internal cryptographic components
walletMnemonic.privateKey
//!
walletMnemonic.publicKey
//!
// The wallet mnemonic
walletMnemonic.mnemonic
//!
// Note: A wallet created with a private key does not
// have a mnemonic (the derivation prevents it)
walletPrivateKey.mnemonic
//!
// Signing a message
walletMnemonic.signMessage("Hello World")
//!
tx = {
to: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
value: utils.parseEther("1.0")
}
// Signing a transaction
walletMnemonic.signTransaction(tx)
//!
// The connect method returns a new instance of the
// Wallet connected to a provider
wallet = walletMnemonic.connect(provider)
// Querying the network
wallet.getBalance();
//!
wallet.getTransactionCount();
//!
// Sending ether
wallet.sendTransaction(tx)
// <hide>
//! error
// </hide>
```
VoidSigner
----------
A **VoidSigner** is a simple Signer which cannot sign.
It is useful as a read-only signer, when an API requires a
Signer as a parameter, but it is known only read-only operations
will be carried.
For example, the `call` operation will automatically have the
provided address passed along during the execution.
#### **new** *ethers* . **VoidSigner** ( address ) **=>** *[VoidSigner](./)*
#### **new ***ethers* . **VoidSigner**( address [ , provider ] ) => *[VoidSigner](/api/signer/#VoidSigner)*
Create a new instance of a **VoidSigner** for *address*.
#### *voidSigner* . **address** **=>** *string< [Address](../utils/address) >*
#### *voidSigner* . **address** => *string< [Address](/api/utils/address/#address) >*
The address of this **VoidSigner**.
```javascript
address = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
signer = new ethers.VoidSigner(address, provider)
// The DAI token contract
abi = [
"function balanceOf(address) view returns (uint)",
"function transfer(address, uint) returns (bool)"
]
contract = new ethers.Contract("dai.tokens.ethers.eth", abi, signer)
// <hide>
//!
// </hide>
// Get the number of tokens for this account
tokens = await contract.balanceOf(signer.getAddress())
//! async tokens
//
// Pre-flight (check for revert) on DAI from the signer
//
// Note: We do not have the private key at this point, this
// simply allows us to check what would happen if we
// did. This can be useful to check before prompting
// a request in the UI
//
// This will pass since the token balance is available
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
```
ExternallyOwnedAccount
----------------------
#### *eoa* . **address** => *string< [Address](/api/utils/address/#address) >*
This is an interface which contains a minimal set of properties
required for Externally Owned Accounts which can have certain
operations performed, such as encoding as a JSON wallet.
The [Address](/api/utils/address/#address) of this EOA.
#### *eoa* . **address** **=>** *string< [Address](../utils/address) >*
The [Address](../utils/address) of this EOA.
#### *eoa* . **privateKey** **=>** *string< [DataHexstring](../utils/bytes)< 32 > >*
#### *eoa* . **privateKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The privateKey of this EOA
#### *eoa* . **mnemonic** => *[Mnemonic](/api/utils/hdnode/#Mnemonic)*
*Optional*. The account HD mnemonic, if it has one and can be determined. Some sources do not encode the mnemonic, such as an HD extended keys.
#### *eoa* . **mnemonic** **=>** *[Mnemonic](../utils/hdnode)*
*Optional*. The account HD mnemonic, if it has one and can be
determined. Some sources do not encode the mnemonic, such as an
HD extended keys.
-----
**Content Hash:** 142e4d9da1f8b8a900a2e97de899649447054c6addb8cba0fb3342ff02d29fd8

295
docs/api/signer/index.html
View File

File diff suppressed because one or more lines are too long

18
docs/api/utils/README.md
View File

@ -7,11 +7,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
Utilities
=========
These utilities are used extensively within the library, but
are also quite useful for application developers.
* [Application Binary Interface](abi)
* [Interface](abi/interface)
* [Creating Instances](abi/interface)
@ -33,7 +28,9 @@ are also quite useful for application developers.
* [ParamType](abi/fragments)
* [Addresses](address)
* [Address Formats](address)
* [Functions](address)
* [Converting and Verifying](address)
* [Derivation](address)
* [Contracts Addresses](address)
* [BigNumber](bignumber)
* [Types](bignumber)
* [Creating Instances](bignumber)
@ -64,8 +61,9 @@ are also quite useful for application developers.
* [Methods](fixednumber)
* [FixedFormat](fixednumber)
* [Hashing Algorithms](hashing)
* [Cryptographic Hashing](hashing)
* [Common Hashing Helpers](hashing)
* [Cryptographic Hash Functions](hashing)
* [HMAC](hashing)
* [Hashing Helpers](hashing)
* [Solidity Hashing Algorithms](hashing)
* [HD Wallet](hdnode)
* [Types](hdnode)
@ -91,7 +89,3 @@ are also quite useful for application developers.
* [Wordlist](wordlists)
* [Languages](wordlists)
-----
**Content Hash:** 5be9157e89f865d007e6b7e1fb3bb47369a474882824264c5241e5bb05c80865

6
docs/api/utils/abi/README.md
View File

@ -7,8 +7,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
Application Binary Interface
============================
* [Interface](interface)
* [Creating Instances](interface)
* [Properties](interface)
@ -28,7 +26,3 @@ Application Binary Interface
* [FunctionFragment](fragments)
* [ParamType](fragments)
-----
**Content Hash:** 8705c8efbee955960d66f6e6a387af64ad3392dc48f0db81645c1b900ff315e8

296
docs/api/utils/abi/fragments/README.md
View File

@ -7,392 +7,230 @@ Documentation: [html](https://docs-beta.ethers.io/)
Fragments
=========
Explain an ABI.
Formats
-------
### JSON String ABI (Solidity Output JSON)
The **JSON ABI Format** is the format that is
[output from the Solidity compiler](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html).
A JSON serialized object is always a string, which represents an Array
of Objects, where each Object has various properties describing the [Fragment](./) of the ABI.
The deserialied JSON string (which is a normal JavaScript Object) may
also be passed into any function which accepts a JSON String ABI.
### Humanb-Readable ABI
The Human-Readable ABI was
[article](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917)
### Output Formats
#### *ethers* . *utils* . *FragmentTypes* . **full** => *string*
Each [Fragment](./) and [ParamType](./) may be output using its `format`
method.
This is a full human-readable string, including all parameter names, any optional modifiers (e.g. `indexed`, `public`, etc) and white-space to aid in human readabiliy.
#### *ethers* . *utils* . *FragmentTypes* . **full** **=>** *string*
#### *ethers* . *utils* . *FragmentTypes* . **minimal** => *string*
This is a full human-readable string, including all parameter names, any
optional modifiers (e.g. `indexed`, `public`, etc) and white-space
to aid in human readabiliy.
This is similar to `full`, except with no unnecessary whitespace or parameter names. This is useful for storing a minimal string which can still fully reconstruct the original Fragment using [Fragment&thinsp;.&thinsp;from](/api/utils/abi/fragments/#Fragment-from).
#### *ethers* . *utils* . *FragmentTypes* . **json** => *string*
This returns a JavaScript Object which is safe to call `JSON.stringify` on to create a JSON string.
#### *ethers* . *utils* . *FragmentTypes* . **minimal** **=>** *string*
This is similar to `full`, except with no unnecessary whitespace or parameter
names. This is useful for storing a minimal string which can still fully
reconstruct the original Fragment using [Fragment&thinsp;.&thinsp;from](./).
#### *ethers* . *utils* . *FragmentTypes* . **json** **=>** *string*
This returns a JavaScript Object which is safe to call `JSON.stringify`
on to create a JSON string.
#### *ethers* . *utils* . *FragmentTypes* . **sighash** **=>** *string*
This is a minimal output format, which is used by Solidity when computing a
signature hash or an event topic hash.
#### *ethers* . *utils* . *FragmentTypes* . **sighash** => *string*
This is a minimal output format, which is used by Solidity when computing a signature hash or an event topic hash.
#### Note
The `sighash` format is **insufficient** to re-create the original [Fragment](./),
since it discards modifiers such as indexed, anonymous, stateMutability, etc.
The `sighash` format is **insufficient** to re-create the original [Fragment](/api/utils/abi/fragments/#Fragment), since it discards modifiers such as indexed, anonymous, stateMutability, etc.
Fragment
--------
An ABI is a collection of **Fragments**, where each fragment specifies:
* An [Event](./)
* A [Function](./)
* A [Constructor](./)
### Properties
#### *fragment* . **name** => *string*
This is the name of the Event or Function. This will be null for a [ConstructorFragment](/api/utils/abi/fragments/#ConstructorFragment).
#### *fragment* . **name** **=>** *string*
#### *fragment* . **type** => *string*
This is the name of the Event or Function. This will be null for
a [ConstructorFragment](./).
This is a string which indicates the type of the [Fragment](/api/utils/abi/fragments/#Fragment). This will be one of:
- `constructor`
- `event`
- `function`
#### *fragment* . **type** **=>** *string*
This is a string which indicates the type of the [Fragment](./). This
will be one of:
* `constructor`
* `event`
* `function`
#### *fragment* . **inputs** **=>** *Array< [ParamType](./) >*
This is an array of of each [ParamType](./) for the input parameters to
the Constructor, Event of Function.
#### *fragment* . **inputs** => *Array< [ParamType](/api/utils/abi/fragments/#ParamType) >*
This is an array of of each [ParamType](/api/utils/abi/fragments/#ParamType) for the input parameters to the Constructor, Event of Function.
### Methods
#### *ethers* . *utils* . *Fragment* . **from** ( objectOrString ) **=>** *[Fragment](./)*
#### *ethers* . *utils* . *Fragment* . **from**( objectOrString ) => *[Fragment](/api/utils/abi/fragments/#Fragment)*
Returns a
#### *ethers* . *utils* . *Fragment* . **isFragment** ( object ) **=>** *boolean*
#### *ethers* . *utils* . *Fragment* . **isFragment**( object ) => *boolean*
Tra lal al
ConstructorFragment
-------------------
### Properties
#### *fragment* . **gas** => *[BigNumber](/api/utils/bignumber/)*
This is the gas limit that should be used during deployment. It may be null.
#### *fragment* . **gas** **=>** *[BigNumber](../../bignumber)*
#### *fragment* . **payable** => *boolean*
This is the gas limit that should be used during deployment. It may be
null.
This is whether the constructor may receive ether during deployment as an endowment (i.e. msg.value != 0).
#### *fragment* . **payable** **=>** *boolean*
This is whether the constructor may receive ether during deployment as
an endowment (i.e. msg.value != 0).
#### *fragment* . **stateMutability** **=>** *string*
#### *fragment* . **stateMutability** => *string*
This is the state mutability of the constructor. It can be any of:
* `nonpayable`
* `payable`
- `nonpayable`
- `payable`
### Methods
#### *ethers* . *utils* . *ConstructorFragment* . **from** ( objectOrString ) **=>** *[ConstructorFragment](./)*
#### *ethers* . *utils* . *ConstructorFragment* . **from**( objectOrString ) => *[ConstructorFragment](/api/utils/abi/fragments/#ConstructorFragment)*
Tra la la...
#### *ethers* . *utils* . *ConstructorFragment* . **isConstructorFragment** ( object ) **=>** *boolean*
#### *ethers* . *utils* . *ConstructorFragment* . **isConstructorFragment**( object ) => *boolean*
Tra lal al
EventFragment
-------------
### Properties
#### *fragment* . **anonymous** => *boolean*
#### *fragment* . **anonymous** **=>** *boolean*
This is whether the event is anonymous. An anonymous Event does not inject its
topic hash as topic0 when creating a log.
This is whether the event is anonymous. An anonymous Event does not inject its topic hash as topic0 when creating a log.
### Methods
#### *ethers* . *utils* . *EventFragment* . **from** ( objectOrString ) **=>** *[EventFragment](./)*
#### *ethers* . *utils* . *EventFragment* . **from**( objectOrString ) => *[EventFragment](/api/utils/abi/fragments/#EventFragment)*
Tra la la...
#### *ethers* . *utils* . *EventFragment* . **isEventFragment** ( object ) **=>** *boolean*
#### *ethers* . *utils* . *EventFragment* . **isEventFragment**( object ) => *boolean*
Tra lal al
FunctionFragment
----------------
### Properties
#### *fragment* . **constant** => *boolean*
This is whether the function is constant (i.e. does not change state). This is true if the state mutability is `pure` or `view`.
#### *fragment* . **constant** **=>** *boolean*
This is whether the function is constant (i.e. does not change state). This
is true if the state mutability is `pure` or `view`.
#### *fragment* . **stateMutability** **=>** *string*
#### *fragment* . **stateMutability** => *string*
This is the state mutability of the constructor. It can be any of:
* `nonpayable`
* `payable`
* `pure`
* `view`
- `nonpayable`
- `payable`
- `pure`
- `view`
#### *fragment* . **outputs** **=>** *Array< [ParamType](./) >*
#### *fragment* . **outputs** => *Array< [ParamType](/api/utils/abi/fragments/#ParamType) >*
A list of the Function output parameters.
### Method
#### *ethers* . *utils* . *FunctionFragment* . **from** ( objectOrString ) **=>** *[FunctionFragment](./)*
#### *ethers* . *utils* . *FunctionFragment* . **from**( objectOrString ) => *[FunctionFragment](/api/utils/abi/fragments/#FunctionFragment)*
Tra la la...
#### *ethers* . *utils* . *FunctionFragment* . **isFunctionFragment** ( object ) **=>** *boolean*
#### *ethers* . *utils* . *FunctionFragment* . **isFunctionFragment**( object ) => *boolean*
Tra lal al
ParamType
---------
The following examples will represent the Solidity parameter:
`string foobar`
### Properties
#### *paramType* . **name** => *string*
The local parameter name. This may be null for unnamed parameters. For example, the parameter definition `string foobar` would be `foobar`.
#### *paramType* . **name** **=>** *string*
#### *paramType* . **type** => *string*
The local parameter name. This may be null for unnamed parameters. For example,
the parameter definition `string foobar` would be `foobar`.
The full type of the parameter, including tuple and array symbols. This may be null for unnamed parameters. For the above example, this would be `foobar`.
#### *paramType* . **baseType** => *string*
The base type of the parameter. For primitive types (e.g. `address`, `uint256`, etc) this is equal to [type](/api/utils/abi/fragments/#ParamType-type). For arrays, it will be the string `array` and for a tuple, it will be the string `tuple`.
#### *paramType* . **type** **=>** *string*
#### *paramType* . **indexed** => *boolean*
The full type of the parameter, including tuple and array symbols. This may be null
for unnamed parameters. For the above example, this would be `foobar`.
Whether the parameter has been marked as indexed. This **only** applies to parameters which are part of an [EventFragment](/api/utils/abi/fragments/#EventFragment).
#### *paramType* . **arrayChildren** => *[ParamType](/api/utils/abi/fragments/#ParamType)*
The type of children of the array. This is null for for any parameter wjhich is not an array.
#### *paramType* . **basetype** **=>** *string*
#### *paramType* . **arrayLength** => *number*
The base type of the parameter. For primitive types (e.g. `address`, `uint256`, etc)
this is equal to [type](./). For arrays, it will be the string `array` and for
a tuple, it will be the string `tuple`.
The length of the array, or `-1` for dynamic-length arrays. This is null for parameters which is not arrays.
#### *paramType* . **indexed** **=>** *boolean*
Whether the parameter has been marked as indexed. This **only** applies
to parameters which are part of an [EventFragment](./).
#### *paramType* . **arrayChildren** **=>** *[ParamType](./)*
The type of children of the array. This is null for for any parameter
wjhich is not an array.
#### *paramType* . **arrayLength** **=>** *number*
The length of the array, or `-1` for dynamic-length arrays. This is
null for parameters which is not arrays.
#### *paramType* . **components** **=>** *Array< [ParamType](./) >*
#### *paramType* . **components** => *Array< [ParamType](/api/utils/abi/fragments/#ParamType) >*
The components of a tuple. This is null for non-tuple parameters.
### Methods
#### *paramType* . **format**( [ outputType = sighash ] )
Tra la la...
#### *paramType* . **format** ( [ outputType=sighash ] )
#### *ethers* . *utils* . *ParamType* . **from**( objectOrString ) => *[ParamType](/api/utils/abi/fragments/#ParamType)*
Tra la la...
#### *ethers* . *utils* . *ParamType* . **from** ( objectOrString ) **=>** *[ParamType](./)*
#### *ethers* . *utils* . *ParamType* . **isParamType**( object ) => *boolean*
Tra la la...
#### *ethers* . *utils* . *ParamType* . **isParamType** ( object ) **=>** *boolean*
Tra la la...
-----
**Content Hash:** b3b5bca0e0fe90226032a0727af0e449044a395b8bceb808b47a022024ee560b

185
docs/api/utils/abi/fragments/index.html
View File

File diff suppressed because one or more lines are too long

36
docs/api/utils/abi/index.html
View File

File diff suppressed because one or more lines are too long

280
docs/api/utils/abi/interface/README.md
View File

@ -7,347 +7,201 @@ Documentation: [html](https://docs-beta.ethers.io/)
Interface
=========
The **Interface** Class abstracts the encoding and decoding required
to interact with contracts on the Ethereum network.
Many of the standards organically evolved along side the [Solidity](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/solidity.readthedocs.io/en/v0.6.2)
language, which other languages have adopted to remain compatibile with
existing deployed contracts.
The EVM itself does not understand what the ABI is. It is simply an agreed
upon set of formats to encode various types of data which each contract can
expect so they can interoperate with each other.
Creating Instances
------------------
#### **new ***ethers* . *utils* . **Interface**( abi )
Create a new **Interface** from a JSON string or object representing *abi*.
#### **new** *ethers* . *utils* . **Interface** ( abi )
Create a new **Interface** from a JSON string or object representing
*abi*.
The *abi* may be a JSON string or the parsed Object (using JSON.parse)
which is emitted by the [Solidity compiler](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html) (or compatible languages).
The *abi* may also be a [Human-Readable Abi](../../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917),
which is a format the Ethers created to simplify manually typing the ABI
into the source and so that a Contract ABI can also be referenced easily
within the same source file.
The *abi* may be a JSON string or the parsed Object (using JSON.parse) which is emitted by the [Solidity compiler](https://solidity.readthedocs.io/en/v0.6.0/using-the-compiler.html#output-description) (or compatible languages).
The *abi* may also be a [Human-Readable Abi](https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917), which is a format the Ethers created to simplify manually typing the ABI into the source and so that a Contract ABI can also be referenced easily within the same source file.
Properties
----------
#### *interface* . **fragments** => *Array< [Fragment](/api/utils/abi/fragments/#Fragment) >*
All the [Fragments](/api/utils/abi/fragments/#Fragment) in the interface.
#### *interface* . **fragments** **=>** *Array< [Fragment](../fragments) >*
#### *interface* . **events** => *Array< [EventFragment](/api/utils/abi/fragments/#EventFragment) >*
All the [Fragments](../fragments) in the interface.
All the [Event Fragments](/api/utils/abi/fragments/#EventFragment) in the interface.
#### *interface* . **functions** => *Array< [FunctionFragment](/api/utils/abi/fragments/#FunctionFragment) >*
All the [Function Fragments](/api/utils/abi/fragments/#FunctionFragment) in the interface.
#### *interface* . **events** **=>** *Array< [EventFragment](../fragments) >*
All the [Event Fragments](../fragments) in the interface.
#### *interface* . **functions** **=>** *Array< [FunctionFragment](../fragments) >*
All the [Function Fragments](../fragments) in the interface.
#### *interface* . **deploy** **=>** *[ConstructorFragment](../fragments)*
The [Constructor Fragments](../fragments) for the interface.
#### *interface* . **deploy** => *[ConstructorFragment](/api/utils/abi/fragments/#ConstructorFragment)*
The [Constructor Fragments](/api/utils/abi/fragments/#ConstructorFragment) for the interface.
Formatting
----------
#### *interface* . **format**( [ format ] ) => *string | Array< string >*
#### *interface* . **format** ( [ format ] ) **=>** *string|Array< string >*
Return the formatted **Interface**. If the format type is `json` a
single string is returned, otherwise an Array of the human-readable
strings is returned.
Return the formatted **Interface**. If the format type is `json` a single string is returned, otherwise an Array of the human-readable strings is returned.
Fragment Access
---------------
#### *interface* . **getFunction**( fragment ) => *[FunctionFragment](/api/utils/abi/fragments/#FunctionFragment)*
Returns the [FunctionFragment](/api/utils/abi/fragments/#FunctionFragment) for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)).
#### *interface* . **getFunction** ( fragment ) **=>** *[FunctionFragment](../fragments)*
Returns the [FunctionFragment](../fragments) for *fragment* (see [Specifying Fragments](./)).
#### *interface* . **getEvent** ( fragment ) **=>** *[EventFragment](../fragments)*
Returns the [EventFragment](../fragments) for *fragment* (see [Specifying Fragments](./)).
#### *interface* . **getEvent**( fragment ) => *[EventFragment](/api/utils/abi/fragments/#EventFragment)*
Returns the [EventFragment](/api/utils/abi/fragments/#EventFragment) for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)).
Signature and Topic Hashes
--------------------------
#### *interface* . **getSighash**( fragment ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 4 > >*
Return the sighash (or Function Selector) for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)).
#### *interface* . **getSighash** ( fragment ) **=>** *string< [DataHexstring](../../bytes)< 4 > >*
Return the sighash (or Function Selector) for *fragment* (see [Specifying Fragments](./)).
#### *interface* . **getEventTopic** ( fragment ) **=>** *string< [DataHexstring](../../bytes)< 32 > >*
Return the topic hash for *fragment* (see [Specifying Fragments](./)).
#### *interface* . **getEventTopic**( fragment ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Return the topic hash for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)).
Encoding Data
-------------
#### *interface* . **encodeDeploy**( [ values ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Return the encoded deployment data, which can be concatenated to the deployment bytecode of a contract to pass *values* into the contract constructor.
#### *interface* . **encodeDeploy** ( [ values ] ) **=>** *string< [DataHexstring](../../bytes) >*
#### *interface* . **encodeFilterTopics**( fragment [ , values ] ) => *Array< topic | Array< topic > >*
Return the encoded deployment data, which can be concatenated to the
deployment bytecode of a contract to pass *values* into the contract
constructor.
Returns the encoded topic filter, which can be passed to getLogs for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *values*.
Each *topic* is a 32 byte (64 nibble) [DataHexString](/api/utils/bytes/#DataHexString).
#### *interface* . **encodeFunctionData**( fragment [ , values ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns the encoded data, which can be used as the data for a transaction for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *values*.
#### *interface* . **encodeFilterTopics** ( fragment [ , values ] ) **=>** *Array< topic|Array< topic > >*
#### *interface* . **encodeFunctionResult**( fragment [ , values ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns the encoded topic filter, which can be passed to getLogs for *fragment*
(see [Specifying Fragments](./)) for the given *values*.
Each *topic* is a 32 byte (64 nibble) [DataHexstring](../../bytes).
#### *interface* . **encodeFunctionData** ( fragment [ , values ] ) **=>** *string< [DataHexstring](../../bytes) >*
Returns the encoded data, which can be used as the data for a transaction for
*fragment* (see [Specifying Fragments](./)) for the given *values*.
#### *interface* . **encodeFunctionResult** ( fragment [ , values ] ) **=>** *string< [DataHexstring](../../bytes) >*
Returns the encoded result, which would normally be the response from a call for
*fragment* (see [Specifying Fragments](./)) for the given *values*.
Returns the encoded result, which would normally be the response from a call for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *values*.
Most developers will not need this method, but may be useful for authors of a mock blockchain.
Decoding Data
-------------
#### *interface* . **decodeEventLog**( fragment , data [ , topics ] ) => *[Result](/api/utils/abi/interface/#Result)*
#### *interface* . **decodeEventLog** ( fragment , data [ , topics ] ) **=>** *[Result](./)*
Returns the decoded event values from an event log for
*fragment* (see [Specifying Fragments](./)) for the given *data*
with the optional *topics*.
Returns the decoded event values from an event log for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *data* with the optional *topics*.
If *topics* is not specified, placeholders will be inserted into the result.
#### *interface* . **decodeFunctionData**( fragment , data ) => *[Result](/api/utils/abi/interface/#Result)*
Returns the decoded values from transaction data for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *data*.
Most developers will not need this method, but may be useful for debugging or inspecting transactions.
#### *interface* . **decodeFunctionData** ( fragment , data ) **=>** *[Result](./)*
Returns the decoded values from transaction data for
*fragment* (see [Specifying Fragments](./)) for the given *data*.
Most developers will not need this method, but may be useful for debugging
or inspecting transactions.
#### *interface* . **decodeFunctionResult** ( fragment , data ) **=>** *[Result](./)*
Returns the decoded values from the result of a call for
*fragment* (see [Specifying Fragments](./)) for the given *data*.
#### *interface* . **decodeFunctionResult**( fragment , data ) => *[Result](/api/utils/abi/interface/#Result)*
Returns the decoded values from the result of a call for *fragment* (see [Specifying Fragments](/api/utils/abi/interface/#Interface--specifying-fragments)) for the given *data*.
Parsing
-------
#### *interface* . **parseLog**( log ) => *[LogDescription](/api/utils/abi/interface/#LogDescription)*
The functions are generally the most useful for most developers. They will
automatically search the ABI for a matching Event or Function and decode
the components as a fully specified description.
Search the event that matches the *log* topic hash and parse the values the log represents.
#### *interface* . **parseLog** ( log ) **=>** *[LogDescription](./)*
Search the event that matches the *log* topic hash and parse the values
the log represents.
#### *interface* . **parseTransaction** ( transaction ) **=>** *[TransactionDescription](./)*
Search for the function that matches the *transaction* data sighash
and parse the transaction properties.
#### *interface* . **parseTransaction**( transaction ) => *[TransactionDescription](/api/utils/abi/interface/#TransactionDescription)*
Search for the function that matches the *transaction* data sighash and parse the transaction properties.
Types
-----
### Result
A **Result** is an array, so each value can be accessed as a positional
argument.
Additionally, if values are named, the identical object as its positional
value can be accessed by its name.
The name `length` is however reserved as it is part of the Array, so
any named value for this key is renamed to `_length`. If there is a
name collision, only the first is available by its key.
### LogDescription
#### *logDescription* . **args** **=>** *[Result](./)*
#### *logDescription* . **args** => *[Result](/api/utils/abi/interface/#Result)*
The values of the input parameters of the event.
#### *logDescription* . **eventFragment** => *[EventFragment](/api/utils/abi/fragments/#EventFragment)*
The [EventFragment](/api/utils/abi/fragments/#EventFragment) which matches the topic in the Log.
#### *logDescription* . **eventFragment** **=>** *[EventFragment](../fragments)*
The [EventFragment](../fragments) which matches the topic in the Log.
#### *logDescription* . **name** **=>** *string*
#### *logDescription* . **name** => *string*
The event name. (e.g. `Transfer`)
#### *logDescription* . **signature** **=>** *string*
#### *logDescription* . **signature** => *string*
The event signature. (e.g. `Transfer(address,address,uint256)`)
#### *logDescription* . **topic** **=>** *string*
#### *logDescription* . **topic** => *string*
The topic hash.
### TransactionDescription
#### *transactionDescription* . **args** => *[Result](/api/utils/abi/interface/#Result)*
The decoded values from the transaction data which were passed as the input parameters.
#### *transactionDescription* . **args** **=>** *[Result](./)*
#### *transactionDescription* . **functionFragment** => *[FunctionFragment](/api/utils/abi/fragments/#FunctionFragment)*
The decoded values from the transaction data which were passed
as the input parameters.
The [FunctionFragment](/api/utils/abi/fragments/#FunctionFragment) which matches the sighash in the transaction data.
#### *transactionDescription* . **functionFragment** **=>** *[FunctionFragment](../fragments)*
The [FunctionFragment](../fragments) which matches the sighash in the transaction data.
#### *transactionDescription* . **name** **=>** *string*
#### *transactionDescription* . **name** => *string*
The name of the function. (e.g. `transfer`)
#### *transactionDescription* . **sighash** **=>** *string*
#### *transactionDescription* . **sighash** => *string*
The sighash (or function selector) that matched the transaction data.
#### *transactionDescription* . **signature** **=>** *string*
#### *transactionDescription* . **signature** => *string*
The signature of the function. (e.g. `transfer(address,uint256)`)
#### *transactionDescription* . **value** **=>** *[BigNumber](../../bignumber)*
#### *transactionDescription* . **value** => *[BigNumber](/api/utils/bignumber/)*
The value from the transaction.
Specifying Fragments
--------------------
When specifying a fragment to any of the functions in an **Interface**,
any of the following may be used:
* The name of the event or function, if it is unique and non-ambiguous within the ABI (e.g. `transfer`)
* The signature of the event or function. The signature is normalized, so, for example, `uint` and `uint256` are equivalent (e.g. `transfer(address, uint)`)
* The sighash or topichash of the function. The sighash is often referred to the function selector in Solidity (e.g. `0xa9059cbb`)
* A [Fragment](../fragments)
-----
**Content Hash:** ed5159ed39b943e91bae3e17384c149e4b55f4d80650672a092c2781a3883934

167
docs/api/utils/abi/interface/index.html
View File

File diff suppressed because one or more lines are too long

89
docs/api/utils/address/README.md
View File

@ -7,99 +7,58 @@ Documentation: [html](https://docs-beta.ethers.io/)
Addresses
=========
Explain addresses,formats and checksumming here.
Also see: [constants.AddressZero](../constants)
Address Formats
---------------
### Address
An **Address** is a [DataHexstring](../bytes) of 20 bytes (40 nibbles), with optional
mixed case.
If the case is mixed, it is a **Checksum Address**, which uses a specific pattern
of uppercase and lowercase letters within a given address to reduce the risk
of errors introduced from typing an address or cut and paste issues.
All functions that return an Address will return a Checksum Address.
### ICAP Address
Converting and Verifying
------------------------
The **ICAP Address Format** was an early attempt to introduce a checksum
into Ethereum addresses using the popular banking industry's
[IBAN](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/International_Bank_Account_Number)
format with the country code specified as **XE**.
Due to the way IBAN encodes address, only addresses that fit into 30 base-36
characters are actually compatible, so the format was adapted to support 31
base-36 characters which is large enough for a full Ethereum address, however
the preferred method was to select a private key whose address has a `0` as
the first byte, which allows the address to be formatted as a fully compatibly
standard IBAN address with 30 base-36 characters.
In general this format is no longer widely supported anymore, however any function that
accepts an address can receive an ICAP address, and it will be converted internally.
To convert an address into the ICAP format, see [getIcapAddress](./).
Functions
---------
#### *ethers* . *utils* . **getAddress** ( address ) **=>** *string< [Address](./) >*
#### *ethers* . *utils* . **getAddress**( address ) => *string< [Address](/api/utils/address/#address) >*
Returns *address* as a Checksum Address.
If *address* is an invalid 40-nibble [Hexstring](../bytes) or if it contains mixed case and
the checksum is invalid, an InvalidArgument Error is throw.
If *address* is an invalid 40-nibble [HexString](/api/utils/bytes/#HexString) or if it contains mixed case and the checksum is invalid, an InvalidArgument Error is throw.
The value of *address* may be any supported address format.
#### *ethers* . *utils* . **getIcapAddress**( address ) => *string< [IcapAddress](/api/utils/address/#address-icap) >*
Returns *address* as an [ICAP address](https://github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29). Supports the same restrictions as [utils.getAddress](/api/utils/address/#utils-getAddress).
#### *ethers* . *utils* . **isAddress** ( address ) **=>** *boolean*
#### *ethers* . *utils* . **isAddress**( address ) => *boolean*
Returns true if *address* is valid (in any supported format).
Derivation
----------
#### *ethers* . *utils* . **computeAddress**( publicOrPrivateKey ) => *string< [Address](/api/utils/address/#address) >*
Returns the address for *publicOrPrivateKey*. A public key may be compressed or uncompressed, and a private key will be converted automatically to a public key for the derivation.
#### *ethers* . *utils* . **getIcapAddress** ( address ) **=>** *string< [IcapAddress](./) >*
#### *ethers* . *utils* . **recoverAddress**( digest , signature ) => *string< [Address](/api/utils/address/#address) >*
Returns *address* as an [ICAP address](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/wiki/wiki/Inter-exchange-Client-Address-Protocol-%28ICAP%29).
Supports the same restrictions as [utils.getAddress](./).
Use [ECDSA Public Key Recovery](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm#Public_key_recovery) to determine the address that signed *digest* to which generated *signature*.
Contracts Addresses
-------------------
#### *ethers* . *utils* . **getContractAddress**( transaction ) => *string< [Address](/api/utils/address/#address) >*
Returns the contract address that would result if *transaction* was used to deploy a contract.
#### *ethers* . *utils* . **getContractAddress** ( transaction ) **=>** *string< [Address](./) >*
#### *ethers* . *utils* . **getCreate2Address**( from , salt , initCodeHash ) => *string< [Address](/api/utils/address/#address) >*
Returns the contract address that would result if *transaction* was
used to deploy a contract.
Returns the contract address that would result from the given [CREATE2](https://eips.ethereum.org/EIPS/eip-1014) call.
#### *ethers* . *utils* . **getCreate2Address** ( from , salt , initCodeHash ) **=>** *string< [Address](./) >*
Returns the contract address that would result from the given
[CREATE2](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-1014) call.
-----
**Content Hash:** 94de1affabe23203e5796f6ad2bd7ccacfb9dd51e5ea7db004c10cd2aea8fded

80
docs/api/utils/address/index.html
View File

File diff suppressed because one or more lines are too long

384
docs/api/utils/bignumber/README.md
View File

@ -7,409 +7,231 @@ Documentation: [html](https://docs-beta.ethers.io/)
BigNumber
=========
Many operations in Ethereum operation on numbers which are
[outside the range of safe values](./) to use
in JavaScript.
A **BigNumber** is an object which safely allows mathematic operations
on numbers of any magnitude.
Most operations which need to return a value will return a **BigNumber**
and parameters which accept values will generally accept them.
### Importing
```
/////
// CommonJS:
// From the Umbrella ethers package...
const { BigNumber } = require("ethers");
// From the bignumber pacakge...
const { BigNumber } = require("@ethersproject/bignumber");
/////
// ES6 and TypeScript:
// From the Umbrella ethers package...
import { BigNumber } from "ethers";
// From the bignumber pacakge...
import { BigNumber } from "@ethersproject/bignumber";
```
Types
-----
### BigNumberish
Many functions and methods in this library take in values which
can be non-ambiguously and safely converted to a BigNumber. These
values can be sepcified as:
#### ***string***
A [hexstring](../bytes) or a decimal string, either of which may
be negative.
A [HexString](/api/utils/bytes/#HexString) or a decimal string, either of which may be negative.
#### ***BytesLike***
A [BytesLike](../bytes) Object, such as an Array or Uint8Array.
A [BytesLike](/api/utils/bytes/#BytesLike) Object, such as an Array or Uint8Array.
#### ***BigNumber***
An existing [BigNumber](./) instance.
An existing [BigNumber](/api/utils/bignumber/) instance.
#### ***number***
A number that is within the [safe range](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) for JavaScript numbers.
A number that is within the [safe range](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER#Description) for JavaScript numbers.
#### ***BigInt***
A JavaScript [BigInt](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
object, on environments that support BigInt.
A JavaScript [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) object, on environments that support BigInt.
Creating Instances
------------------
The constructor of BigNumber cannot be called directly. Instead, Use the static `BigNumber.from`.
#### *ethers* . *BigNumber* . **from** ( aBigNumberish ) **=>** *[BigNumber](./)*
#### *ethers* . *BigNumber* . **from**( aBigNumberish ) => *[BigNumber](/api/utils/bignumber/)*
Returns an instance of a **BigNumber** for *aBigNumberish*.
### Examples:
```javascript
Skipping JavaScript Evaluation.
// From a decimal string...
BigNumber.from("42")
//!
// From a HexString...
BigNumber.from("0x2a")
//!
// From a negative HexString...
BigNumber.from("-0x2a")
//!
// From an Array (or Uint8Array)...
BigNumber.from([ 42 ])
//!
// From an existing BigNumber...
let one1 = constants.One;
let one2 = BigNumber.from(one1)
one2
//!
// ...which returns the same instance
one1 === one2
//!
// From a (safe) number...
BigNumber.from(42)
//!
// From a ES2015 BigInt... (only on platforms with BigInt support)
BigNumber.from(42n)
//!
// Numbers outside the safe range fail:
BigNumber.from(Number.MAX_SAFE_INTEGER);
//! error
```
Methods
-------
The BigNumber class is immutable, so no operations can change the value
it represents.
### Math Operations
#### *BigNumber* . **add**( otherValue ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **+** *otherValue*.
#### *bignumber* . **add** ( otherValue ) **=>** *[BigNumber](./)*
#### *BigNumber* . **sub**( otherValue ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *bignumber* **+** *otherValue*.
Returns a BigNumber with the value of *BigNumber* **-** *otherValue*.
#### *BigNumber* . **mul**( otherValue ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* **\*** *otherValue*.
#### *bignumber* . **sub** ( otherValue ) **=>** *[BigNumber](./)*
#### *BigNumber* . **div**( divisor ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *bignumber* **&ndash;** *otherValue*.
Returns a BigNumber with the value of *BigNumber* **/** *divisor*.
#### *BigNumber* . **mod**( divisor ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of the **remainder** of *BigNumber* / *divisor*.
#### *bignumber* . **mul** ( otherValue ) **=>** *[BigNumber](./)*
#### *BigNumber* . **pow**( exponent ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *bignumber* **&times;** *otherValue*.
Returns a BigNumber with the value of *BigNumber* to the power of *exponent*.
#### *BigNumber* . **abs**( ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the absolute value of *BigNumber*.
#### *bignumber* . **div** ( divisor ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of *bignumber* **&#247;** *divisor*.
#### *bignumber* . **mod** ( divisor ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of the **remainder** of *bignumber* &#247; *divisor*.
#### *bignumber* . **pow** ( exponent ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of *bignumber* to the power of *exponent*.
#### *bignumber* . **abs** ( ) **=>** *[BigNumber](./)*
Returns a BigNumber with the absolute value of *bignumber*.
#### *bignumber* . **maskn** ( bitcount ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of *bignumber* with bits beyond
the *bitcount* least significant bits set to zero.
#### *BigNumber* . **mask**( bitcount ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* with bits beyond the *bitcount* least significant bits set to zero.
### Two's Compliment
#### *BigNumber* . **fromTwos**( bitwidth ) => *[BigNumber](/api/utils/bignumber/)*
[Two's Complicment](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Two%27s_complement)
is an elegant method used to encode and decode fixed-width signed values
while efficiently preserving mathematic operations.
Most users will not need to interact with these.
Returns a BigNumber with the value of *BigNumber* converted from twos-compliment with *bitwidth*.
#### *bignumber* . **fromTwos** ( bitwidth ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of *bignumber* converted from twos-compliment with *bitwidth*.
#### *bignumber* . **toTwos** ( bitwidth ) **=>** *[BigNumber](./)*
Returns a BigNumber with the value of *bignumber* converted to twos-compliment with *bitwidth*.
#### *BigNumber* . **toTwos**( bitwidth ) => *[BigNumber](/api/utils/bignumber/)*
Returns a BigNumber with the value of *BigNumber* converted to twos-compliment with *bitwidth*.
### Comparison and Equivalence
#### *BigNumber* . **eq**( otherValue ) => *boolean*
Returns true if and only if the value of *BigNumber* is equal to *otherValue*.
#### *bignumber* . **eq** ( otherValue ) **=>** *boolean*
#### *BigNumber* . **lt**( otherValue ) => *boolean*
Returns true if and only if the value of *bignumber* is equal to *otherValue*.
Returns true if and only if the value of *BigNumber* **<** *otherValue*.
#### *BigNumber* . **lte**( otherValue ) => *boolean*
Returns true if and only if the value of *BigNumber* **<=** *otherValue*.
#### *bignumber* . **lt** ( otherValue ) **=>** *boolean*
#### *BigNumber* . **gt**( otherValue ) => *boolean*
Returns true if and only if the value of *bignumber* **<** *otherValue*.
Returns true if and only if the value of *BigNumber* **>** *otherValue*.
#### *BigNumber* . **gte**( otherValue ) => *boolean*
Returns true if and only if the value of *BigNumber* **>=** *otherValue*.
#### *bignumber* . **lte** ( otherValue ) **=>** *boolean*
Returns true if and only if the value of *bignumber* **&le;** *otherValue*.
#### *bignumber* . **gt** ( otherValue ) **=>** *boolean*
Returns true if and only if the value of *bignumber* **>** *otherValue*.
#### *bignumber* . **gte** ( otherValue ) **=>** *boolean*
Returns true if and only if the value of *bignumber* **&ge;** *otherValue*.
#### *bignumber* . **isZero** ( ) **=>** *boolean*
Returns true if and only if the value of *bignumber* is zero.
#### *BigNumber* . **isZero**( ) => *boolean*
Returns true if and only if the value of *BigNumber* is zero.
### Conversion
#### *BigNumber* . **toNumber**( ) => *number*
Returns the value of *BigNumber* as a JavaScript value.
This will **throw an error** if the value is greater than or equal to *Number.MAX_SAFE_INTEGER* or less than or equal to *Number.MIN_SAFE_INTEGER*.
#### *bignumber* . **toNumber** ( ) **=>** *number*
#### *BigNumber* . **toString**( ) => *string*
Returns the value of *bignumber* as a JavaScript value.
This will **throw an error**
if the value is greater than or equal to *Number.MAX_SAFE_INTEGER* or less than or
equal to *Number.MIN_SAFE_INTEGER*.
Returns the value of *BigNumber* as a base-10 string.
#### *BigNumber* . **toHexString**( ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
#### *bignumber* . **toString** ( ) **=>** *string*
Returns the value of *bignumber* as a base-10 string.
#### *bignumber* . **toHexString** ( ) **=>** *string< [DataHexstring](../bytes) >*
Returns the value of *bignumber* as a base-16, `0x`-prefixed [DataHexstring](../bytes).
Returns the value of *BigNumber* as a base-16, `0x`-prefixed [DataHexString](/api/utils/bytes/#DataHexString).
### Inspection
#### *ethers* . *BigNumnber* . **isBigNumber** ( object ) **=>** *boolean*
#### *ethers* . *BigNumnber* . **isBigNumber**( object ) => *boolean*
Returns true if and only if the *object* is a BigNumber object.
### Examples
```javascript
Skipping JavaScript Evaluation.
let a = BigNumber.from(42);
let b = BigNumber.from("91");
a.mul(b);
//!
```
Notes
-----
This section is a for a couple of questions that come up frequently.
### Why can't I just use numbers?
The first problem many encounter when dealing with Ethereum is
the concept of numbers. Most common currencies are broken down
with very little granularity. For example, there are only 100
cents in a single dollar. However, there are 10^18 **wei** in a
single **ether**.
JavaScript uses [IEEE 754 double-precision binary floating point](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Double-precision_floating-point_format)
numbers to represent numeric values. As a result, there are *holes*
in the integer set after 9,007,199,254,740,991; which is
problematic for *Ethereum* because that is only around 0.009
ether (in wei), which means any value over that will begin to
experience rounding errors.
To demonstrate how this may be an issue in your code, consider:
```javascript
Skipping JavaScript Evaluation.
(Number.MAX_SAFE_INTEGER + 2 - 2) == (Number.MAX_SAFE_INTEGER)
//!
```
To remedy this, all numbers (which can be large) are stored
and manipulated as [Big Numbers](./).
To remedy this, all numbers (which can be large) are stored and manipulated as [Big Numbers](/api/utils/bignumber/).
The functions [parseEther( etherString )](http://linkto) and
[formatEther( wei )](http://linkto) can be used to convert
between string representations, which are displayed to or entered
by the user and Big Number representations which can have
mathematical operations handled safely.
The functions [parseEther( etherString )](/api/utils/display-logic/#utils-parseEther) and [formatEther( wei )](/api/utils/display-logic/#utils-formatEther) can be used to convert between string representations, which are displayed to or entered by the user and Big Number representations which can have mathematical operations handled safely.
### Why not BigNumber.js, BN.js, BigDecimal, etc?
Everyone has their own favourite Big Number library, and once someone
has choosen one, it becomes part of their identity, like their editor,
vi vs emacs. There are over 100 Big Number libraries on [npm](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.npmjs.com/search?q=bignumber).
One of the biggest differences between the Ethers [BigNumber](./) object and
other libraries is that it is immutable, which is very important when
dealing with the asynchronous nature of the blockchain.
Capturing the value is not safe in async functions, so immutability
protects us from easy to make mistakes, which is not possible on the
low-level library's objects which supports myriad in-place operations.
Second, the Ethers [BigNumber](./) provides all the functionality required
internally and should generally be sufficient for most developers while
not exposing some of the more advanced and rare functionality. So it will
be eaiser to swap out the underlying library without impacting consumers.
For example, if [BN.js](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.npmjs.com/package/bn.js) was exposed, someone may use the
greatest-common-denominator functions, which would then be functionality
the replacing library should also provide to ensure anyone depending on
that functionality is not broken.
### Why BN.js??
### Allow us to set a global Big Number library?
The reason why [BN.js](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.npmjs.com/package/bn.js) is used internally as the big
number is because that is the library used by [elliptic](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/www.npmjs.com/package/elliptic).
Therefore it **must** be included regardless, so we leverage that
library rather than adding another Big Number library, which would
mean two different libraries offering the same functionality.
This has saved about 85kb (80% of this library size) of library size
over other libraries which include separate Big Number libraries for
various purposes.
### Why not allow us to set a global Big Number library?
Another comment that comes up frequently is tha desire to specify a
global user-defined Big Number library, which all functions would
return.
This becomes problematic since your code may live along side other
libraries or code that use Ethers. In fact, even Ethers uses a lot
of the public functions internally.
If you, for example, used a library that used `a.plus(b)` instead
of `a.add(b)`, this would break Ethers when it tries to compute
fees internally, and other libraries likely have similar logic.
But, the [BigNumber](./) prototype is exposed, so you can always add a
`toMyCustomBigNumber()` method to all [BigNumber](./)'s globally
which is safe.
-----
**Content Hash:** 8f8f918b6d3350f7494845577cf2d350c6f0c556a963040cadbde6520395311d

230
docs/api/utils/bignumber/index.html
View File

File diff suppressed because one or more lines are too long

242
docs/api/utils/bytes/README.md
View File

@ -7,257 +7,173 @@ Documentation: [html](https://docs-beta.ethers.io/)
Byte Manipulation
=================
Tra la la...
Types
-----
### Bytes
A **Bytes** is any object which is an
[Array](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) or [TypedArray](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) with
each value in the valid byte range (i.e. between 0 and 255 inclusive),
or is an Object with a `length` property where each indexed property
is in the valid byte range.
### BytesLike
### DataHexString
A **BytesLike** can be either a [Bytes](./) or a [DataHexstring](./).
### DataHexstring
A **DataHexstring** is identical to a [Hexstring](./) except that it has
an even number of nibbles, and therefore is a valid representation of
binary data as a string.
### Hexstring
A **Hexstring** is a string which has a `0x` prefix followed by any
number of nibbles (i.e. case-insensitive hexidecumal characters, `0-9` and `a-f`).
### HexString
### Signature
* **r** and **s** --- The x co-ordinate of **r** and the **s** value of the signature
* **v** --- The parity of the y co-ordinate of **r**
* **_vs** --- The [compact representation](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-2098) of the **s** and **v**
* **recoveryParam** --- The normalized (i.e. 0 or 1) value of **v**
### Flat-Format Signature
A **Flat-Format Signature** is a common Signature format where
the r, s and v are concanenated into a 65 byte (130 nibble)
[DataHexstring](./).
### Raw Signature
### SignatureLike
A **SignatureLike** is similar to a [Signature](./), except redundant properties
may be omitted or it may be a [Flat-Format Signature](./).
For example, if **_vs** is specified, **s** and **v** may be omitted. Likewise,
if **recoveryParam** is provided, **v** may be omitted (as in these cases the
missing values can be computed).
Inspection
----------
#### *ethers* . *utils* . **isBytes**( object ) => *boolean*
Returns true if and only if *object* is a valid [Bytes](/api/utils/bytes/#Bytes).
#### *ethers* . *utils* . **isBytes** ( object ) **=>** *boolean*
#### *ethers* . *utils* . **isBytesLike**( object ) => *boolean*
Returns true if and only if *object* is a valid [Bytes](./).
Returns true if and only if *object* is a [Bytes](/api/utils/bytes/#Bytes) or [DataHexString](/api/utils/bytes/#DataHexString).
#### *ethers* . *utils* . **isHexString**( object , [ length ] ) => *boolean*
#### *ethers* . *utils* . **isBytesLike** ( object ) **=>** *boolean*
Returns true if and only if *object* is a [Bytes](./) or [DataHexstring](./).
#### *ethers* . *utils* . **isHexString** ( object , [ length ] ) **=>** *boolean*
Returns true if and only if *object* is a valid hex string.
If *length* is specified and *object* is not a valid [DataHexstring](./) of
*length* bytes, an InvalidArgument error is thrown.
Returns true if and only if *object* is a valid hex string. If *length* is specified and *object* is not a valid [DataHexString](/api/utils/bytes/#DataHexString) of *length* bytes, an InvalidArgument error is thrown.
Converting between Arrays and Hexstrings
----------------------------------------
#### *ethers* . *utils* . **arrayify**( DataHexStringOrArrayish [ , options ] ) => *Uint8Array*
Converts *DataHexStringOrArrayish* to a Uint8Array.
#### *ethers* . *utils* . **arrayify** ( datahexstringOrArrayish [ , options ] ) **=>** *Uint8Array*
#### *ethers* . *utils* . **hexlify**( hexstringOrArrayish ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Converts *datahexstringOrArrayish* to a Uint8Array.
Converts *hexstringOrArrayish* to a [DataHexString](/api/utils/bytes/#DataHexString).
#### *ethers* . *utils* . **hexValue**( aBigNumberish ) => *string< [HexString](/api/utils/bytes/#HexString) >*
#### *ethers* . *utils* . **hexlify** ( hexstringOrArrayish ) **=>** *string< [DataHexstring](./) >*
Converts *hexstringOrArrayish* to a [DataHexstring](./).
#### *ethers* . *utils* . **hexValue** ( aBigNumberish ) **=>** *string< [Hexstring](./) >*
Converts *aBigNumberish* to a [Hexstring](./), with no *unnecessary* leading
zeros.
### Examples
Converts *aBigNumberish* to a [HexString](/api/utils/bytes/#HexString), with no *unnecessary* leading zeros.
```javascript
Skipping JavaScript Evaluation.
// Convert a hexstring to a Uint8Array
arrayify("0x1234")
//!
// Convert an Array to a hexstring
hexlify([1, 2, 3, 4])
//!
// Convert an Object to a hexstring
hexlify({ length: 2, "0": 1, "1": 2 })
//!
// Convert an Array to a hexstring
hexlify([ 1 ])
//!
// Convert a number to a stripped hex value
hexValue(1)
//!
// Convert an Array to a stripped hex value
hexValue([ 1, 2 ])
//!
```
Array Manipulation
------------------
#### *ethers* . *utils* . **concat**( arrayOfBytesLike ) => *Uint8Array*
Concatenates all the [BytesLike](/api/utils/bytes/#BytesLike) in *arrayOfBytesLike* into a single Uint8Array.
#### *ethers* . *utils* . **concat** ( arrayOfBytesLike ) **=>** *Uint8Array*
Concatenates all the [BytesLike](./) in *arrayOfBytesLike* into a single Uint8Array.
#### *ethers* . *utils* . **stripZeros** ( aBytesLike ) **=>** *Uint8Array*
#### *ethers* . *utils* . **stripZeros**( aBytesLike ) => *Uint8Array*
Returns a Uint8Array with all leading `0` bytes of *aBtyesLike* removed.
#### *ethers* . *utils* . **zeroPad**( aBytesLike , length ) => *Uint8Array*
Retutns a Uint8Array of the data in *aBytesLike* with `0` bytes prepended to *length* bytes long.
#### *ethers* . *utils* . **zeroPad** ( aBytesLike , length ) **=>** *Uint8Array*
Retutns a Uint8Array of the data in *aBytesLike* with `0` bytes prepended to
*length* bytes long.
If *aBytesLike* is already longer than *length* bytes long, an InvalidArgument
error will be thrown.
If *aBytesLike* is already longer than *length* bytes long, an InvalidArgument error will be thrown.
Hexstring Manipulation
----------------------
#### *ethers* . *utils* . **hexConcat**( arrayOfBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Concatenates all the [BytesLike](/api/utils/bytes/#BytesLike) in *arrayOfBytesLike* into a single [DataHexString](/api/utils/bytes/#DataHexString)
#### *ethers* . *utils* . **hexConcat** ( arrayOfBytesLike ) **=>** *string< [DataHexstring](./) >*
Concatenates all the [BytesLike](./) in *arrayOfBytesLike* into a single [DataHexstring](./)
#### *ethers* . *utils* . **hexDataLength** ( aBytesLike ) **=>** *string< [DataHexstring](./) >*
#### *ethers* . *utils* . **hexDataLength**( aBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns the length (in bytes) of *aBytesLike*.
#### *ethers* . *utils* . **hexDataSlice**( aBytesLike , offset [ , endOffset ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns a [DataHexString](/api/utils/bytes/#DataHexString) representation of a slice of *aBytesLike*, from *offset* (in bytes) to *endOffset* (in bytes). If *endOffset* is omitted, the length of *aBytesLike* is used.
#### *ethers* . *utils* . **hexDataSlice** ( aBytesLike , offset [ , endOffset ] ) **=>** *string< [DataHexstring](./) >*
#### *ethers* . *utils* . **hexStripZeros**( aBytesLike ) => *string< [HexString](/api/utils/bytes/#HexString) >*
Returns a [DataHexstring](./) representation of a slice of *aBytesLike*, from
*offset* (in bytes) to *endOffset* (in bytes). If *endOffset* is
omitted, the length of *aBytesLike* is used.
Returns a [HexString](/api/utils/bytes/#HexString) representation of *aBytesLike* with all leading zeros removed.
#### *ethers* . *utils* . **hexZeroPad**( aBytesLike , length ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns a [DataHexString](/api/utils/bytes/#DataHexString) representation of *aBytesLike* padded to *length* bytes.
#### *ethers* . *utils* . **hexStripZeros** ( aBytesLike ) **=>** *string< [Hexstring](./) >*
Returns a [Hexstring](./) representation of *aBytesLike* with all
leading zeros removed.
#### *ethers* . *utils* . **hexZeroPad** ( aBytesLike , length ) **=>** *string< [DataHexstring](./) >*
Returns a [DataHexstring](./) representation of *aBytesLike* padded to *length* bytes.
If *aBytesLike* is already longer than *length* bytes long, an InvalidArgument
error will be thrown.
If *aBytesLike* is already longer than *length* bytes long, an InvalidArgument error will be thrown.
Signature Conversion
--------------------
#### *ethers* . *utils* . **joinSignature**( aSignatureLike ) => *string< [RawSignature](/api/utils/bytes/#signature-raw) >*
Return the raw-format of *aSignaturelike*, which is 65 bytes (130 nibbles) long, concatenating the **r**, **s** and (normalized) **v** of a Signature.
#### *ethers* . *utils* . **joinSignature** ( aSignatureLike ) **=>** *string< [FlatSignature](./) >*
Return the flat-format of *aSignaturelike*, which is 65 bytes (130 nibbles)
long, concatenating the **r**, **s** and (normalized) **v** of a Signature.
#### *ethers* . *utils* . **splitSignature** ( aSignatureLikeOrBytesLike ) **=>** *[Signature](./)*
Return the full expanded-format of *aSignaturelike* or a flat-format [DataHexstring](./).
Any missing properties will be computed.
#### *ethers* . *utils* . **splitSignature**( aSignatureLikeOrBytesLike ) => *[Signature](/api/utils/bytes/#Signature)*
Return the full expanded-format of *aSignaturelike* or a raw-format [DataHexString](/api/utils/bytes/#DataHexString). Any missing properties will be computed.
Random Bytes
------------
#### *ethers* . *utils* . **randomBytes** ( length ) **=>** *Uint8Array*
#### *ethers* . *utils* . **randomBytes**( length ) => *Uint8Array*
Return a new Uint8Array of *length* random bytes.
#### *ethers* . *utils* . **shuffled**( array ) => *Array< any >*
Return a copy of *array* shuffled using [Fisher-Yates Shuffle](https://en.wikipedia.org/wiki/Fisher-Yates_shuffle).
#### *ethers* . *utils* . **shuffled** ( array ) **=>** *Array< any >*
```javascript
utils.randomBytes(8)
//!
Return a copy of *array* shuffled using [Fisher-Yates Shuffle](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Fisher-Yates_shuffle).
const data = [ 1, 2, 3, 4, 5, 6, 7 ];
// Returns a new Array
utils.shuffled(data);
//!
// The Original is unscathed...
data
//!
```
-----
**Content Hash:** 8736c2f7c64aa2a0ba9f987036158ef0cecc8110bbc30f88c7365f24809af3fc

161
docs/api/utils/bytes/index.html
View File

File diff suppressed because one or more lines are too long

66
docs/api/utils/constants/README.md
View File

@ -7,99 +7,57 @@ Documentation: [html](https://docs-beta.ethers.io/)
Constants
=========
The **ethers.contants** Object contains commonly used values.
### Importing
```javascript
Skipping JavaScript Evaluation.
```
Bytes
-----
#### *ethers* . *constants* . **AddressZero** **=>** *string< [Address](../address) >*
#### *ethers* . *constants* . **AddressZero** => *string< [Address](/api/utils/address/#address) >*
The Address Zero, which is 20 bytes (40 nibbles) of zero.
#### *ethers* . *constants* . **HashZero** **=>** *string< [DataHexstring](../bytes)< 32 > >*
#### *ethers* . *constants* . **HashZero** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The Hash Zero, which is 32 bytes (64 nibbles) of zero.
Strings
-------
#### *ethers* . *constants* . **EtherSymbol** => *string*
#### *ethers* . *constants* . **EtherSymbol** **=>** *string*
The Ether symbol, **&Xi;**.
The Ether symbol, **Xi**.
BigNumber
---------
#### *ethers* . *constants* . **NegativeOne** **=>** *[BigNumber](../bignumber)*
#### *ethers* . *constants* . **NegativeOne** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing `"-1"`.
#### *ethers* . *constants* . **Zero** **=>** *[BigNumber](../bignumber)*
#### *ethers* . *constants* . **Zero** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing `"0"`.
#### *ethers* . *constants* . **One** **=>** *[BigNumber](../bignumber)*
#### *ethers* . *constants* . **One** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing `"1"`.
#### *ethers* . *constants* . **Two** **=>** *[BigNumber](../bignumber)*
#### *ethers* . *constants* . **Two** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing `"2"`.
#### *ethers* . *constants* . **WeiPerEther** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing `"1000000000000000000"`, which is the number of Wei per Ether.
#### *ethers* . *constants* . **WeiPerEther** **=>** *[BigNumber](../bignumber)*
The BigNumber value representing `"1000000000000000000"`, which is the
number of Wei per Ether.
#### *ethers* . *constants* . **MaxUint256** **=>** *[BigNumber](../bignumber)*
#### *ethers* . *constants* . **MaxUint256** => *[BigNumber](/api/utils/bignumber/)*
The BigNumber value representing the maximum `uint256` value.
-----
**Content Hash:** 2c8c7edeece6a1d7d8c07e666c59ffeec57423a4b908bed03e62d47b6ae758fb

63
docs/api/utils/constants/index.html
View File

File diff suppressed because one or more lines are too long

78
docs/api/utils/display-logic/README.md
View File

@ -7,106 +7,46 @@ Documentation: [html](https://docs-beta.ethers.io/)
Display Logic and Input
=======================
When creating an Application, it is useful to convert between
user-friendly strings (usually displaying **ether**) and the
machine-readable values that contracts and maths depend on
(usually in **wei**).
For example, a Wallet may specify the balance in ether, and
gas prices in gwei for the User Interface, but when sending
a transaction, both must be specified in wei.
The [parseUnits](./) will parse a string representing
ether, such as `1.1` into a [BigNumber](../bignumber) in wei, and is
useful when a user types in a value, such as sending 1.1 ether.
The [formatUnits](./) will format a [BigNumberish](../bignumber)
into a string, which is useful when displaying a balance.
Units
-----
### Decimal Count
The *unit* specified may be an integer, which indicates how
many decimal place the unit has. For example, 1 ether has 18 decimal
places for wei, and if this library were used with Bitcoin, 1 BTC
has 8 decimal places for satoshis.
### Named Units
In addition to specifying *unit* as a number of decimals, there
are several common units, which can be passed in as a string:
* **wei** --- 0
* **kwei** --- 3
* **mwei** --- 6
* **gwei** --- 9
* **szabo** --- 12
* **finney** --- 15
* **ether** --- 18
Functions
---------
### Formatting
#### *ethers* . *utils* . **commify** ( value ) **=>** *string*
#### *ethers* . *utils* . **commify**( value ) => *string*
Returns a string with value grouped by 3 digits, separated by `,`.
### Conversion
#### *ethers* . *utils* . **formatUnits**( value [ , unit = "ether" ] ) => *string*
Returns a string representation of *value* formatted with *unit* digits (if it is a number) or to the unit specified (if a string).
#### *ethers* . *utils* . **formatUnits** ( value [ , unit="ether" ] ) **=>** *string*
Returns a string representation of *value* formatted with *unit*
digits (if it is a number) or to the unit specified (if a string).
#### *ethers* . *utils* . **formatEther** ( value ) **=>** *string*
#### *ethers* . *utils* . **formatEther**( value ) => *string*
The equivalent to calling `formatUnits(value, "ether")`.
#### *ethers* . *utils* . **parseUnits**( value [ , unit = "ether" ] ) => *[BigNumber](/api/utils/bignumber/)*
Returns a [BigNumber](/api/utils/bignumber/) representation of *value*, parsed with *unit* digits (if it is a number) or from the unit specified (if a string).
#### *ethers* . *utils* . **parseUnits** ( value [ , unit="ether" ] ) **=>** *[BigNumber](../bignumber)*
Returns a [BigNumber](../bignumber) representation of *value*, parsed with
*unit* digits (if it is a number) or from the unit specified (if
a string).
#### *ethers* . *utils* . **parseEther** ( value ) **=>** *[BigNumber](../bignumber)*
#### *ethers* . *utils* . **parseEther**( value ) => *[BigNumber](/api/utils/bignumber/)*
The equivalent to calling `parseUnits(value, "ether")`.
-----
**Content Hash:** dc749d05e2f4c378032440c4cdc06b705479b15b2582dca2c838021861f86a03

70
docs/api/utils/display-logic/index.html
View File

File diff suppressed because one or more lines are too long

68
docs/api/utils/encoding/README.md
View File

@ -7,96 +7,56 @@ Documentation: [html](https://docs-beta.ethers.io/)
Encoding Utilities
==================
Base58
------
#### *ethers* . *utils* . *base58* . **decode**( textData ) => *Uin8Array*
Return a typed Uint8Array representation of *textData* decoded using base-58 encoding.
#### *ethers* . *utils* . *base58* . **decode** ( textData ) **=>** *Uin8Array*
Return a typed Uint8Array representation of *textData* decoded using
base-58 encoding.
#### *ethers* . *utils* . *base58* . **encode** ( aBytesLike ) **=>** *string*
#### *ethers* . *utils* . *base58* . **encode**( aBytesLike ) => *string*
Return *aBytesLike* encoded as a string using the base-58 encoding.
Base64
------
#### *ethers* . *utils* . *base64* . **decode**( textData ) => *Uin8Array*
Return a typed Uint8Array representation of *textData* decoded using base-64 encoding.
#### *ethers* . *utils* . *base64* . **decode** ( textData ) **=>** *Uin8Array*
Return a typed Uint8Array representation of *textData* decoded using
base-64 encoding.
#### *ethers* . *utils* . *base64* . **encode** ( aBytesLike ) **=>** *string*
#### *ethers* . *utils* . *base64* . **encode**( aBytesLike ) => *string*
Return *aBytesLike* encoded as a string using the base-64 encoding.
Recursive-Length Prefix
-----------------------
The [Recursive Length Prefix](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/ethereum/wiki/wiki/RLP) encoding is used throughout Ethereum to serialize nested
structures of Arrays and data.
#### *ethers* . *utils* . *RLP* . **encode** ( dataObject ) **=>** *string< [DataHexstring](../bytes) >*
#### *ethers* . *utils* . *RLP* . **encode**( dataObject ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Encode a structured Data Object into its RLP-encoded representation.
Each Data component may be an valid [BytesLike](../bytes).
Each Data component may be an valid [BytesLike](/api/utils/bytes/#BytesLike).
#### *ethers* . *utils* . *RLP* . **decode** ( aBytesLike ) **=>** *[DataObject](./)*
#### *ethers* . *utils* . *RLP* . **decode**( aBytesLike ) => *[DataObject](/api/utils/encoding/#rlp--dataobject)*
Decode an RLP-encoded *aBytesLike* into its structured Data Object.
All Data components will be returned as a [DataHexstring](../bytes).
All Data components will be returned as a [DataHexString](/api/utils/bytes/#DataHexString).
### Data Object
A **Data Object** is a recursive structure which is used to serialize many
internal structures in Ethereum. Each **Data Object** can either be:
* Binary Data
* An Array of **Data Objects** (i.e. this recursively includes Nesting)
#### **Examples**
* `"0x1234"`
* `[ "0x1234", [ "0xdead", "0xbeef" ], [ ] ]`
- `"0x1234"`
- `[ "0x1234", [ "0xdead", "0xbeef" ], [ ] ]`
-----
**Content Hash:** ebb4f7f25cb19e1ca1f2b2fa0a73140ec30365c55a2ff6b15c3637b5ef58ff06

67
docs/api/utils/encoding/index.html
View File

File diff suppressed because one or more lines are too long

168
docs/api/utils/fixednumber/README.md
View File

@ -7,227 +7,128 @@ Documentation: [html](https://docs-beta.ethers.io/)
FixedNumber
===========
A **FixedNumber** is a fixed-width (in bits) number with an internal
base-10 divisor, which allows it to represent a decimal fractional
component.
Creating Instances
------------------
The FixedNumber constructor cannot be called directly. There are several
static methods for creating a FixedNumber.
#### *FixedNumber* . **from** ( value [ , format="fixed" ] ) **=>** *[FixedNumber](./)*
#### *FixedNumber* . **from**( value [ , format = "fixed" ] ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns an instance of a **FixedNumber** for *value* as a *format*.
#### *FixedNumber* . **fromBytes** ( aBytesLike [ , format="fixed" ] ) **=>** *[FixedNumber](./)*
#### *FixedNumber* . **fromBytes**( aBytesLike [ , format = "fixed" ] ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns an instance of a **FixedNumber** for *value* as a *format*.
#### *FixedNumber* . **fromString**( value [ , format = "fixed" ] ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns an instance of a **FixedNumber** for *value* as a *format*. The *value* must not contain more decimals than the *format* permits.
#### *FixedNumber* . **fromString** ( value [ , format="fixed" ] ) **=>** *[FixedNumber](./)*
Returns an instance of a **FixedNumber** for *value* as a *format*. The *value* must
not contain more decimals than the *format* permits.
#### *FixedNumber* . **fromValue** ( value [ , decimals=0 [ , format="fixed" ] ] ) **=>** *[FixedNumber](./)*
#### *FixedNumber* . **fromValue**( value [ , decimals = 0 [ , format = "fixed" ] ] ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns an instance of a **FixedNumber** for *value* with *decimals* as a *format*.
Properties
----------
#### *fixednumber* . **format**
The [FixedFormat](./) of *fixednumber*.
The [FixedFormat](/api/utils/fixednumber/#FixedFormat) of *fixednumber*.
Methods
-------
### Math Operations
#### *fixednumber* . **addUnsafe** ( otherValue ) **=>** *[FixedNumber](./)*
#### *fixednumber* . **addUnsafe**( otherValue ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* **+** *otherValue*.
#### *fixednumber* . **subUnsafe**( otherValue ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* **-** *otherValue*.
#### *fixednumber* . **subUnsafe** ( otherValue ) **=>** *[FixedNumber](./)*
#### *fixednumber* . **mulUnsafe**( otherValue ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* **&ndash;** *otherValue*.
Returns a new FixedNumber with the value of *fixedvalue* **\*** *otherValue*.
#### *fixednumber* . **divUnsafe**( otherValue ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* **/** *otherValue*.
#### *fixednumber* . **mulUnsafe** ( otherValue ) **=>** *[FixedNumber](./)*
Returns a new FixedNumber with the value of *fixedvalue* **&times;** *otherValue*.
#### *fixednumber* . **divUnsafe** ( otherValue ) **=>** *[FixedNumber](./)*
Returns a new FixedNumber with the value of *fixedvalue* **&#247;** *otherValue*.
#### *fixednumber* . **round** ( [ decimals=0 ] ) **=>** *[FixedNumber](./)*
#### *fixednumber* . **round**( [ decimals = 0 ] ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* rounded to *decimals*.
### Conversion
#### *fixednumber* . **toFormat** ( format ) **=>** *[FixedNumber](./)*
#### *fixednumber* . **toFormat**( format ) => *[FixedNumber](/api/utils/fixednumber/)*
Returns a new FixedNumber with the value of *fixedvalue* with *format*.
#### *fixednumber* . **toHexString**( ) => *string*
Returns a [HexString](/api/utils/bytes/#HexString) representation of *fixednumber*.
#### *fixednumber* . **toHexString** ( ) **=>** *string*
Returns a [Hexstring](../bytes) representation of *fixednumber*.
#### *fixednumber* . **toString** ( ) **=>** *string*
#### *fixednumber* . **toString**( ) => *string*
Returns a string representation of *fixednumber*.
#### *fixednumber* . **toUnsafeFloat**( ) => *float*
#### *fixednumber* . **toUnsafeFloat** ( ) **=>** *float*
Returns a floating-point JavaScript number value of *fixednumber*.
Due to rounding in JavaScript numbers, the value is only approximate.
Returns a floating-point JavaScript number value of *fixednumber*. Due to rounding in JavaScript numbers, the value is only approximate.
### Inspection
#### *FixedNumber* . **isFixedNumber** ( value ) **=>** *boolean*
#### *FixedNumber* . **isFixedNumber**( value ) => *boolean*
Returns true if and only if *value* is a **FixedNumber**.
FixedFormat
-----------
A **FixedFormat** is a simple object which represents a decimal
(base-10) Fixed-Point data representation. Usually using this
class directly is uneccessary, as passing in a [Format Strings](./)
directly into the [FixedNumber](./) will automatically create this.
### Format Strings
A format string is composed of three components, including signed-ness,
bit-width and number of decimals.
A signed format string begins with `fixed`, which an unsigned format
string begins with `ufixed`, followed by the width (in bits) and the
number of decimals.
The width must be conguent to 0 mod 8 (i.e. `(width % 8) == 0`) and no
larger than 256 bits and the number of decimals must be no larger than 80.
For example:
* **fixed128x18** is signed, 128 bits wide and has 18 decimals; this is useful for most purposes
* **fixed32x0** is signed, 32 bits wide and has 0 decimals; this would be the same as a ``int32_t` in C
* **ufixed32x0** is unsigned, 32 bits wide and has 0 decimals; this would be the same as a ``uint32_t` in C
* **fixed** is shorthand for ``fixed128x18`
* **ufixed** is shorthand for ``ufixed128x18`
### Creating Instances
#### *FixedFormat* . **from**( value = "fixed128x18" ) => *[FixedFormat](/api/utils/fixednumber/#FixedFormat)*
#### *FixedFormat* . **from** ( value="fixed128x18" ) **=>** *[FixedFormat](./)*
Returns a new instance of a **FixedFormat** defined by *value*. Any valid [Format Strings](./)
may be passed in as well as any object which has any of `signed`, `width` and `decimals`
defined, including a [FixedFormat](./) object.
Returns a new instance of a **FixedFormat** defined by *value*. Any valid [Format Strings](/api/utils/fixednumber/#FixedFormat--strings) may be passed in as well as any object which has any of `signed`, `width` and `decimals` defined, including a [FixedFormat](/api/utils/fixednumber/#FixedFormat) object.
### Properties
#### *fixedFormat* . **signed** **=>** *boolean*
#### *fixedFormat* . **signed** => *boolean*
The signed-ness of *fixedFormat*, true if negative values are supported.
#### *fixedFormat* . **width** **=>** *number*
#### *fixedFormat* . **width** => *number*
The width (in bits) of *fixedFormat*.
#### *fixedFormat* . **decimals** **=>** *number*
#### *fixedFormat* . **decimals** => *number*
The number of decimal points of *fixedFormat*.
#### *fixedFormat* . **name** => *string*
#### *fixedFormat* . **name** **=>** *string*
The name of the *fixedFormat*, which can be used to recreate the format
and is the string that the Solidity language uses to represent this format.
The name of the *fixedFormat*, which can be used to recreate the format and is the string that the Solidity language uses to represent this format.
#### ***"fixed"***
@ -235,8 +136,3 @@ and is the string that the Solidity language uses to represent this format.
A shorthand for `fixed128x80`.
-----
**Content Hash:** 60fa7fc0a5e28ce6608684d52fe57c2758aa6c9482cd19f71cb5b91fd7d392b8

123
docs/api/utils/fixednumber/index.html
View File

File diff suppressed because one or more lines are too long

199
docs/api/utils/hashing/README.md
View File

@ -7,133 +7,200 @@ Documentation: [html](https://docs-beta.ethers.io/)
Hashing Algorithms
==================
Cryptographic Hash Functions
----------------------------
Explain what hash functions are?
#### *ethers* . *utils* . **id**( text ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The Ethereum Identity function computs the [KECCAK256](https://en.wikipedia.org/wiki/SHA-3) hash of the *text* bytes.
Cryptographic Hashing
---------------------
#### *ethers* . *utils* . **keccak256**( aBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Returns the [KECCAK256](https://en.wikipedia.org/wiki/SHA-3) digest *aBytesLike*.
The [Cryptographic Hash Functions](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Cryptographic_hash_function)
are a specific family of hash functions.
#### *ethers* . *utils* . **ripemd160**( aBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 20 > >*
Returns the [RIPEMD-160](https://en.m.wikipedia.org/wiki/RIPEMD) digest of *aBytesLike*.
#### *ethers* . *utils* . **keccak256** ( aBytesLike ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
#### *ethers* . *utils* . **sha256**( aBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Returns the [KECCAK256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-3) digest *aBytesLike*.
Returns the [SHA2-256](https://en.wikipedia.org/wiki/SHA-2) digest of *aBytesLike*.
#### *ethers* . *utils* . **sha512**( aBytesLike ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 64 > >*
Returns the [SHA2-512](https://en.wikipedia.org/wiki/SHA-2) digest of *aBytesLike*.
#### *ethers* . *utils* . **ripemd160** ( aBytesLike ) **=>** *string< [DataHexstring](../bytes)< 20 > >*
```javascript
utils.keccak256([ 0x12, 0x34 ])
//!
Returns the [RIPEMD-160](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.m.wikipedia.org/wiki/RIPEMD) digest of *aBytesLike*.
utils.keccak256("0x")
//!
utils.keccak256("0x1234")
//!
// The value MUST be data, such as:
// - an Array of numbers
// - a data hex string (e.g. "0x1234")
// - a Uint8Array
// Do NOT use UTF-8 strings that are not a DataHexstring
utils.keccak256("hello world")
//! error
#### *ethers* . *utils* . **sha256** ( aBytesLike ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
// If needed, convert strings to bytes first:
utils.keccak256(utils.toUtf8Bytes("hello world"))
//!
Returns the [SHA2-256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-2) digest of *aBytesLike*.
// Or equivalently use the identity function:
utils.id("hello world")
//!
// Keep in mind that the string "0x1234" represents TWO
// bytes (i.e. [ 0x12, 0x34 ]. If you wish to compute the
// hash of the 6 characters "0x1234", convert it to UTF-8
// bytes first using utils.toUtf8Bytes.
// Consider the following examples:
// Hash of TWO (2) bytes:
utils.keccak256("0x1234")
//!
#### *ethers* . *utils* . **sha512** ( aBytesLike ) **=>** *string< [DataHexstring](../bytes)< 64 > >*
// Hash of TWO (2) bytes: (same result)
utils.keccak256([ 0x12, 0x34 ])
//!
Returns the [SHA2-512](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-2) digest of *aBytesLike*.
const bytes = utils.toUtf8Bytes("0x1234");
// <hide>
bytes
// </hide>
//!
// Hash of SIX (6) characters (different than above)
utils.keccak256(bytes)
//!
// Hash of SIX (6) characters (same result)
utils.id("0x1234")
//!
```
```javascript
utils.ripemd160("0x")
//!
#### *ethers* . *utils* . **computeHmac** ( algorithm , key , data ) **=>** *string< [DataHexstring](../bytes) >*
utils.ripemd160("0x1234")
//!
```
Returns the [HMAC](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/HMAC) of *data* with *key*
using the [Algorithm](./) *algorithm*.
```javascript
utils.sha256("0x")
//!
utils.sha256("0x1234")
//!
utils.sha512("0x")
//!
utils.sha512("0x1234")
//!
```
HMAC
----
#### *ethers* . *utils* . **computeHmac**( algorithm , key , data ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Returns the [HMAC](https://en.wikipedia.org/wiki/HMAC) of *data* with *key* using the [Algorithm](/api/utils/hashing/#utils--hmac-supported-algorithm) *algorithm*.
### HMAC Supported Algorithms
#### *ethers* . *utils* . *SupportedAlgorithm* . **sha256** => *string*
Use the [SHA2-256](https://en.wikipedia.org/wiki/SHA-2) hash algorithm.
#### *ethers* . *utils* . *SupportedAlgorithm* . **sha256** **=>** *string*
#### *ethers* . *utils* . *SupportedAlgorithm* . **sha512** => *string*
Use the [SHA2-256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-2) hash algorithm.
Use the [SHA2-512](https://en.wikipedia.org/wiki/SHA-2) hash algorithm.
```javascript
const key = "0x0102";
const data = "0x1234";
utils.computeHmac("sha256", key, data)
//!
```
Hashing Helpers
---------------
#### *ethers* . *utils* . **hashMessage**( message ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Computes the [EIP-191](https://eips.ethereum.org/EIPS/eip-191) personal message digest of *message*. Personal messages are converted to UTF-8 bytes and prefixed with `\x19Ethereum Signed Message:` and the length of *message*.
#### *ethers* . *utils* . *SupportedAlgorithm* . **sha512** **=>** *string*
#### *ethers* . *utils* . **namehash**( name ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Use the [SHA2-512](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-2) hash algorithm.
Returns the [ENS Namehash](https://docs.ens.domains/contract-api-reference/name-processing#hashing-names) of *name*.
```javascript
// @TODO: include exampels of hashMessage; it can be complex. :)
```
```javascript
utils.namehash("")
//!
Common Hashing Helpers
----------------------
#### *ethers* . *utils* . **hashMessage** ( message ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Computes the [EIP-191](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-191) personal message digest of *message*. Personal messages are
converted to UTF-8 bytes and prefixed with `\x19Ethereum Signed Message:`
and the length of *message*.
#### *ethers* . *utils* . **id** ( text ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
The Ethereum Identity function computs the [KECCAK256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-3) hash of the *text* bytes.
#### *ethers* . *utils* . **namehash** ( name ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Returns the [ENS Namehash](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/docs.ens.domains/contract-api-reference/name-processing) of *name*.
utils.namehash("eth")
//!
utils.namehash("ricmoo.firefly.eth")
//!
utils.namehash("ricmoo.xyz")
//!
```
Solidity Hashing Algorithms
---------------------------
#### *ethers* . *utils* . **solidityPack**( types , values ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
When using the Solidity `abi.packEncoded(...)` function, a non-standard
*tightly packed* version of encoding is used. These functions implement
the tightly packing algorithm.
Returns the non-standard encoded *values* packed according to their respecive type in *types*.
#### *ethers* . *utils* . **solidityPack** ( arrayOfTypes , arrayOfValues ) **=>** *string< [DataHexstring](../bytes) >*
#### *ethers* . *utils* . **solidityKeccak256**( types , values ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Returns the non-standard encoded *arrayOfValues* packed according to
their respecive type in *arrayOfTypes*.
Returns the [KECCAK256](https://en.wikipedia.org/wiki/SHA-3) of the non-standard encoded *values* packed according to their respective type in *types*.
#### *ethers* . *utils* . **soliditySha256**( types , values ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Returns the [SHA2-256](https://en.wikipedia.org/wiki/SHA-2) of the non-standard encoded *values* packed according to their respective type in *types*.
#### *ethers* . *utils* . **solidityKeccak256** ( arrayOfTypes , arrayOfValues ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
```javascript
utils.solidityPack([ "int16", "uint48" ], [ -1, 12 ])
//!
Returns the [KECCAK256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-3) of the non-standard encoded *arrayOfValues* packed
according to their respective type in *arrayOfTypes*.
utils.solidityPack([ "string", "uint8" ], [ "Hello", 3 ])
//!
utils.solidityKeccak256([ "int16", "uint48" ], [ -1, 12 ])
//!
utils.soliditySha256([ "int16", "uint48" ], [ -1, 12 ])
//!
```
#### *ethers* . *utils* . **soliditySha256** ( arrayOfTypes , arrayOfValues ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Returns the [SHA2-256](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/SHA-2) of the non-standard encoded *arrayOfValues* packed
according to their respective type in *arrayOfTypes*.
-----
**Content Hash:** 5c27393d66c46e7175edbe51257fb8cb69e8dc965d45ed7913b9599deec14e80

173
docs/api/utils/hashing/index.html
View File

File diff suppressed because one or more lines are too long

180
docs/api/utils/hdnode/README.md
View File

@ -7,237 +7,147 @@ Documentation: [html](https://docs-beta.ethers.io/)
HD Wallet
=========
TODO: Explain [BIP32](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) [BIP-39](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.bitcoin.it/wiki/BIP_0039) and whatnot here...
Types
-----
### Constants
#### *ethers* . *utils* . **defaultPath** **=>** *"m/44'/60'/0'/0/0"*
#### *ethers* . *utils* . **defaultPath** => *"m/44'/60'/0'/0/0"*
The default path for Ethereum in an HD Wallet
### Mnemonic
#### *mnemonic* . **phrase** => *string*
The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long and separated by the whitespace specified by the `locale`.
#### *mnemonic* . **phrase** **=>** *string*
The mnemonic phrase for this mnemonic. It is 12, 15, 18, 21 or 24 words long
and separated by the whitespace specified by the `locale`.
#### *mnemonic* . **path** **=>** *string*
#### *mnemonic* . **path** => *string*
The HD path for this mnemonic.
#### *mnemonic* . **locale** **=>** *string*
#### *mnemonic* . **locale** => *string*
The language of the wordlist this mnemonic is using.
HDNode
------
### Creating Instances
#### *ethers* . *HDNode* . **fromMnemonic**( phrase [ , password [ , wordlist ] ] ) => *[HDNode](/api/utils/hdnode/#HDNode)*
Return the [HDNode](/api/utils/hdnode/#HDNode) for *phrase* with the optional *password* and *wordlist*.
#### *ethers* . *HDNode* . **fromMnemonic** ( phrase [ , password [ , wordlist ] ] ) **=>** *[HDNode](./)*
#### *ethers* . *HDNode* . **fromSeed**( aBytesLike ) => *[HDNode](/api/utils/hdnode/#HDNode)*
Return the [HDNode](./) for *phrase* with the optional *password*
and *wordlist*.
Return the [HDNode](/api/utils/hdnode/#HDNode) for the seed *aBytesLike*.
#### *ethers* . *HDNode* . **fromExtendedKey**( extendedKey ) => *[HDNode](/api/utils/hdnode/#HDNode)*
#### *ethers* . *HDNode* . **fromSeed** ( aBytesLike ) **=>** *[HDNode](./)*
Return the [HDNode](./) for the seed *aBytesLike*.
#### *ethers* . *HDNode* . **fromExtendedKey** ( extendedKey ) **=>** *[HDNode](./)*
Return the [HDNode](./) for the *extendedKey*. If *extendedKey* was
neutered, the **HDNode** will only be able to compute addresses and not
private keys.
Return the [HDNode](/api/utils/hdnode/#HDNode) for the *extendedKey*. If *extendedKey* was neutered, the **HDNode** will only be able to compute addresses and not private keys.
### Properties
#### *hdNode* . **privateKey** **=>** *string< [DataHexstring](../bytes)< 32 > >*
#### *hdNode* . **privateKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The private key for this HDNode.
#### *hdNode* . **publicKey** **=>** *string< [DataHexstring](../bytes)< 33 > >*
#### *hdNode* . **publicKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 33 > >*
The (compresses) public key for this HDNode.
#### *hdNode* . **fingerprint** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 4 > >*
#### *hdNode* . **fingerprint** **=>** *string< [DataHexstring](../bytes)< 4 > >*
The fingerprint is meant as an index to quickly match parent and
children nodes together, however collisions may occur and software
should verify matching nodes.
The fingerprint is meant as an index to quickly match parent and children nodes together, however collisions may occur and software should verify matching nodes.
Most developers will not need to use this.
#### *hdNode* . **parentFingerprint** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 4 > >*
#### *hdNode* . **parentFingerprint** **=>** *string< [DataHexstring](../bytes)< 4 > >*
The fingerprint of the parent node. See *fingerprint* for more
details.
The fingerprint of the parent node. See *fingerprint* for more details.
Most developers will not need to use this.
#### *hdNode* . **address** **=>** *string< [Address](../address) >*
#### *hdNode* . **address** => *string< [Address](/api/utils/address/#address) >*
The address of this HDNode.
#### *hdNode* . **mnemonic** **=>** *[Mnemonic](./)*
#### *hdNode* . **mnemonic** => *[Mnemonic](/api/utils/hdnode/#Mnemonic)*
The mnemonic of this HDNode, if known.
#### *hdNode* . **path** => *string*
The path of this HDNode, if known. If the *mnemonic* is also known, this will match `mnemonic.path`.
#### *hdNode* . **path** **=>** *string*
#### *hdNode* . **chainCode** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The path of this HDNode, if known. If the *mnemonic* is also known,
this will match `mnemonic.path`.
#### *hdNode* . **chainCode** **=>** *string< [DataHexstring](../bytes)< 32 > >*
The chain code is used as a non-secret private key which is then used
with EC-multiply to provide the ability to derive addresses without
the private key of child non-hardened nodes.
The chain code is used as a non-secret private key which is then used with EC-multiply to provide the ability to derive addresses without the private key of child non-hardened nodes.
Most developers will not need to use this.
#### *hdNode* . **index** => *number*
#### *hdNode* . **index** **=>** *number*
The index of this HDNode. This will match the last component of
the *path*.
The index of this HDNode. This will match the last component of the *path*.
Most developers will not need to use this.
#### *hdNode* . **depth** => *number*
#### *hdNode* . **depth** **=>** *number*
The depth of this HDNode. This will match the number of components
(less one, the `m/`) of the *path*.
The depth of this HDNode. This will match the number of components (less one, the `m/`) of the *path*.
Most developers will not need to use this.
#### *hdNode* . **extendedKey** => *string*
#### *hdNode* . **extendedKey** **=>** *string*
A serialized string representation of this HDNode. Not all properties
are included in the serialization, such as the mnemonic and path, so
serializing and deserializing (using the `fromExtendedKey` class
method) will result in reduced information.
A serialized string representation of this HDNode. Not all properties are included in the serialization, such as the mnemonic and path, so serializing and deserializing (using the `fromExtendedKey` class method) will result in reduced information.
### Methods
#### *hdNode* . **neuter**( ) => *[HDNode](/api/utils/hdnode/#HDNode)*
Return a new instance of *hdNode* with its private key removed but all otehr properties preserved. This ensures that the key can not leak the private key of itself or any derived children, but may still be used to compute the addresses of itself and any non-hardened children.
#### *hdNode* . **neuter** ( ) **=>** *[HDNode](./)*
Return a new instance of *hdNode* with its private key removed
but all otehr properties preserved. This ensures that the key
can not leak the private key of itself or any derived children,
but may still be used to compute the addresses of itself and
any non-hardened children.
#### *hdNode* . **derivePath** ( path ) **=>** *[HDNode](./)*
Return a new [HDNode](./) which is the child of *hdNode* found
by deriving *path*.
#### *hdNode* . **derivePath**( path ) => *[HDNode](/api/utils/hdnode/#HDNode)*
Return a new [HDNode](/api/utils/hdnode/#HDNode) which is the child of *hdNode* found by deriving *path*.
Other Functions
---------------
#### *ethers* . *utils* . **mnemonicToSeed**( phrase [ , password ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 64 > >*
Convert a mnemonic phrase to a seed, according to [BIP-39](https://en.bitcoin.it/wiki/BIP_0039).
#### *ethers* . *utils* . **mnemonicToSeed** ( phrase [ , password ] ) **=>** *string< [DataHexstring](../bytes)< 64 > >*
#### *ethers* . *utils* . **mnemonicToEntropy**( phrase [ , wordlist ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Convert a mnemonic phrase to a seed, according to [BIP-39](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.bitcoin.it/wiki/BIP_0039).
Convert a mnemonic phrase to its entropy, according to [BIP-39](https://en.bitcoin.it/wiki/BIP_0039).
#### *ethers* . *utils* . **isValidMnemonic**( phrase [ , wordlist ] ) => *boolean*
Returns true if *phrase* is a valid mnemonic phrase, by testing the checksum.
#### *ethers* . *utils* . **mnemonicToEntropy** ( phrase [ , wordlist ] ) **=>** *string< [DataHexstring](../bytes) >*
Convert a mnemonic phrase to its entropy, according to [BIP-39](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.bitcoin.it/wiki/BIP_0039).
#### *ethers* . *utils* . **isValidMnemonic** ( phrase [ , wordlist ] ) **=>** *boolean*
Returns true if *phrase* is a valid mnemonic phrase, by
testing the checksum.
-----
**Content Hash:** 042e28f2a611879151bc40783559c6310e23d466a310b508b22f264fa40d53e8

120
docs/api/utils/hdnode/index.html
View File

File diff suppressed because one or more lines are too long

34
docs/api/utils/index.html
View File

File diff suppressed because one or more lines are too long

222
docs/api/utils/logger/README.md
View File

@ -7,246 +7,145 @@ Documentation: [html](https://docs-beta.ethers.io/)
Logging
=======
These are just a few simple logging utilities provided to simplify
and standardize the error facilities across the Ethers library.
The [Logger](./) library has zero dependencies and is intentionally
very light so it can be easily included in each library.
The [Censorship](./) functionality relies on one instance
of the Ethers library being included. In large bundled packages or when
`npm link` is used, this may not be the case. If you require this
functionality, ensure that your bundling is configured properly.
Logger
------
#### **new** *ethers* . *utils* . **Logger** ( version )
#### **new ***ethers* . *utils* . **Logger**( version )
Create a new logger which will include *version* in all errors thrown.
#### *Logger* . **globalLogger** ( ) **=>** *[Logger](./)*
#### *Logger* . **globalLogger**( ) => *[Logger](/api/utils/logger/#Logger)*
Returns the singleton global logger.
### Logging Output
#### *logger* . **debug** ( ...args ) **=>** *void*
#### *logger* . **debug**( ...args ) => *void*
Log debugging information.
#### *logger* . **info** ( ...args ) **=>** *void*
#### *logger* . **info**( ...args ) => *void*
Log generic information.
#### *logger* . **warn** ( ...args ) **=>** *void*
#### *logger* . **warn**( ...args ) => *void*
Log warnings.
### Errors
#### *logger* . **makeError**( message [ , code = UNKNOWN_ERROR [ , params ] ] ) => *Error*
These functions honor the current [Censorship](./) and help create
a standard error model for detecting and processing errors within Ethers.
Create an Error object with *message* and an optional *code* and additional *params* set. This is useful when an error is needed to be rejected instead of thrown.
#### *logger* . **makeError** ( message [ , code=UNKNOWN_ERROR [ , params ] ] ) **=>** *Error*
#### *logger* . **throwError**( message [ , code = UNKNOWN_ERROR [ , params ] ] ) => *never*
Create an Error object with *message* and an optional *code* and
additional *params* set. This is useful when an error is needed to be
rejected instead of thrown.
Throw an Error with *message* and an optional *code* and additional *params* set.
#### *logger* . **throwArgumentError**( message , name , value ) => *never*
#### *logger* . **throwError** ( message [ , code=UNKNOWN_ERROR [ , params ] ] ) **=>** *never*
Throw an Error with *message* and an optional *code* and
additional *params* set.
#### *logger* . **throwArgumentError** ( message , name , value ) **=>** *never*
Throw an [INVALID_ARGUMENT](./) Error with *name* and *value*.
Throw an [INVALID_ARGUMENT](/api/utils/logger/#errors-InvalidArgument) Error with *name* and *value*.
### Usage Validation
#### *logger* . **checkAbstract**( target , kind ) => *void*
There can be used to ensure various properties and actions are safe.
Checks that *target* is not *kind* and performs the same operatons as `checkNew`. This is useful for ensuring abstract classes are not being instantiated.
#### *logger* . **checkAbstract** ( target , kind ) **=>** *void*
#### *logger* . **checkArgumentCount**( count , expectedCound [ , message ) => *void*
Checks that *target* is not *kind* and performs the same operatons
as `checkNew`. This is useful for ensuring abstract classes are not
being instantiated.
If *count* is not equal to *expectedCount*, throws a [MISSING_ARGUMENT](/api/utils/logger/#errors-MissingArgument) or [UNEXPECTED_ARGUMENT](/api/utils/logger/#errors-UnexpectedArgument) error.
#### *logger* . **checkNew**( target , kind ) => *void*
If *target* is not a valid `this` or `target` value, throw a [MISSING_NEW](/api/utils/logger/#errors-MissingNew) error. This is useful to ensure callers of a Class are using `new`.
#### *logger* . **checkArgumentCount** ( count , expectedCound [ , message ) **=>** *void*
#### *logger* . **checkNormalize**( message ) => *void*
If *count* is not equal to *expectedCount*, throws a [MISSING_ARGUMENT](./)
or [UNEXPECTED_ARGUMENT](./) error.
Check that the environment has a correctly functioning [String.normalize](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize). If not, a [UNSUPPORTED_OPERATION](/api/utils/logger/#errors-UnsupportedOperation) error is thrown.
#### *logger* . **checkSafeUint53**( value [ , message ] ) => *void*
#### *logger* . **checkNew** ( target , kind ) **=>** *void*
If *target* is not a valid `this` or `target` value, throw a
[MISSING_NEW](./) error. This is useful to ensure
callers of a Class are using `new`.
#### *logger* . **checkNormalize** ( message ) **=>** *void*
Check that the environment has a correctly functioning [String.normalize](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize). If not, a
[UNSUPPORTED_OPERATION](./) error is thrown.
#### *logger* . **checkSafeUint53** ( value [ , message ] ) **=>** *void*
If *value* is not safe as a [JavaScript number](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Double-precision_floating-point_format), throws a
[NUMERIC_FAULT](./) error.
If *value* is not safe as a [JavaScript number](https://en.wikipedia.org/wiki/Double-precision_floating-point_format), throws a [NUMERIC_FAULT](/api/utils/logger/#errors-NumericFault) error.
### Censorship
#### *Logger* . **setCensorship** ( censor [ , permanent=false ] ) **=>** *void*
#### *Logger* . **setCensorship**( censor [ , permanent = false ] ) => *void*
Set error censorship, optionally preventing errors from being uncensored.
In production applications, this prevents any error from leaking information
by masking the message and values of errors.
In production applications, this prevents any error from leaking information by masking the message and values of errors.
This can impact debugging, making it substantially more difficult.
#### *Logger* . **setLogLevel**( logLevel ) => *void*
#### *Logger* . **setLogLevel** ( logLevel ) **=>** *void*
Set the log level, to suppress logging output below a [particular log level](./).
Set the log level, to suppress logging output below a [particular log level](/api/utils/logger/#Logger-levels).
Errors
------
Every error in Ethers has a `code` value, which is a string that will
match one of the following error codes.
### Generic Error Codes
#### *Logger* . *errors* . **NOT_IMPLEMENTED**
The operation is not implemented.
#### *Logger* . *errors* . **SERVER_ERROR**
There was an error communicating with a server.
#### *Logger* . *errors* . **TIMEOUT**
A timeout occurred.
#### *Logger* . *errors* . **UNKNOWN_ERROR**
A generic unknown error.
#### *Logger* . *errors* . **UNSUPPORTED_OPERATION**
The operation is not supported.
### Safety Error Codes
#### *Logger* . *errors* . **BUFFER_OVERRUN**
The amount of data needed is more than the amount of data required,
which would cause the data buffer to read past its end.
The amount of data needed is more than the amount of data required, which would cause the data buffer to read past its end.
#### *Logger* . *errors* . **NUMERIC_FAULT**
There was an invalid operation done on numeric values.
Common cases of this occur when there is [overflow](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Integer_overflow),
[arithmetic underflow](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Arithmetic_underflow) in fixed numeric types or division by zero.
Common cases of this occur when there is [overflow](https://en.wikipedia.org/wiki/Integer_overflow), [arithmetic underflow](https://en.wikipedia.org/wiki/Arithmetic_underflow) in fixed numeric types or division by zero.
### Usage Error Codes
#### *Logger* . *errors* . **INVALID_ARGUMENT**
The type or value of an argument is invalid. This will generally also
include the `name` and `value` of the argument. Any function which
accepts sensitive data (such as a private key) will include the string
`[[REDACTED]]` instead of the value passed in.
The type or value of an argument is invalid. This will generally also include the `name` and `value` of the argument. Any function which accepts sensitive data (such as a private key) will include the string `[[REDACTED]]` instead of the value passed in.
#### *Logger* . *errors* . **MISSING_ARGUMENT**
@ -254,44 +153,28 @@ accepts sensitive data (such as a private key) will include the string
An expected parameter was not specified.
#### *Logger* . *errors* . **MISSING_NEW**
An object is a Class, but is now being called with `new`.
#### *Logger* . *errors* . **UNEXPECTED_ARGUMENT**
Too many parameters we passed into a function.
### Ethereum Error Codes
#### *Logger* . *errors* . **CALL_EXCEPTION**
An attempt to call a blockchain contract (getter) resulted in a
revert or other error.
An attempt to call a blockchain contract (getter) resulted in a revert or other error.
#### *Logger* . *errors* . **INSUFFICIENT_FUNDS**
The account is attempting to make a transaction which costs more than is
available.
A sending account must have enough ether to pay for the value, the gas limit
(at the gas price) as well as the intrinsic cost of data. The intrinsic cost
of data is 4 gas for each zero byte and 68 gas for each non-zero byte.
The account is attempting to make a transaction which costs more than is available.
A sending account must have enough ether to pay for the value, the gas limit (at the gas price) as well as the intrinsic cost of data. The intrinsic cost of data is 4 gas for each zero byte and 68 gas for each non-zero byte.
#### *Logger* . *errors* . **NETWORK_ERROR**
@ -299,85 +182,54 @@ of data is 4 gas for each zero byte and 68 gas for each non-zero byte.
An Ethereum network validation error, such as an invalid chain ID.
#### *Logger* . *errors* . **NONCE_EXPIRED**
The nonce being specified has already been used in a mined transaction.
#### *Logger* . *errors* . **REPLACEMENT_UNDERPRICED**
When replacing a transaction, by using a nonce which has already been sent to
the network, but which has not been mined yet the new transaction must specify
a higher gas price.
This error occurs when the gas price is insufficient to *bribe* the transaction
pool to prefer the new transaction over the old one. Generally, the new gas price
should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the
replacement should be 15.000000001 gwei.
When replacing a transaction, by using a nonce which has already been sent to the network, but which has not been mined yet the new transaction must specify a higher gas price.
This error occurs when the gas price is insufficient to *bribe* the transaction pool to prefer the new transaction over the old one. Generally, the new gas price should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the replacement should be 15.000000001 gwei.
#### *Logger* . *errors* . **UNPREDICTABLE_GAS_LIMIT**
When estimating the required amount of gas for a transaction, a node is queried for
its best guess.
When estimating the required amount of gas for a transaction, a node is queried for its best guess.
If a node is unable (or unwilling) to predict the cost, this error occurs.
The best remedy for this situation is to specify a gas limit in the transaction
manually.
This error can also indicate that the transaction is expected to fail regardless,
if for example an account with no tokens is attempting to send a token.
The best remedy for this situation is to specify a gas limit in the transaction manually.
This error can also indicate that the transaction is expected to fail regardless, if for example an account with no tokens is attempting to send a token.
Log Levels
----------
#### *Logger* . *levels* . **DEBUG**
Log all output, including debugging information.
#### *Logger* . *levels* . **INFO**
Only log output for infomational, warnings and errors.
#### *Logger* . *levels* . **WARNING**
Only log output for warnings and errors.
#### *Logger* . *levels* . **ERROR**
Only log output for errors.
#### *Logger* . *levels* . **OFF**
Do not output any logs.
-----
**Content Hash:** 22f86858ee436554a50ae97e21e1866ac72fc3b0d0aec16ae331ab718c122c95

184
docs/api/utils/logger/index.html
View File

File diff suppressed because one or more lines are too long

35
docs/api/utils/properties/README.md
View File

@ -7,50 +7,27 @@ Documentation: [html](https://docs-beta.ethers.io/)
Property Utilities
==================
#### *ethers* . *utils* . **checkPropertoes** ( ) **=>** *void*
#### *ethers* . *utils* . **checkProperties**( ) => *void*
#### *ethers* . *utils* . **deepCopy**( anObject ) => *any*
#### *ethers* . *utils* . **deepCopy** ( anObject ) **=>** *any*
#### *ethers* . *utils* . **defineReadOnly**( anObject , name , value ) => *void*
#### *ethers* . *utils* . **getStatic**( aConstructor , key ) => *any*
#### *ethers* . *utils* . **defineReadOnly** ( anObject , name , value ) **=>** *void*
#### *ethers* . *utils* . **resolveProperties**( anObject ) => *Promise< any >*
#### *ethers* . *utils* . **shallowCopy**( anObject ) => *any*
#### *ethers* . *utils* . **getStatic** ( aConstructor , key ) **=>** *any*
#### *ethers* . *utils* . **resolveProperties** ( anObject ) **=>** *Promise< any >*
#### *ethers* . *utils* . **shallowCopy** ( anObject ) **=>** *any*
-----
**Content Hash:** 8e7a07176855d0fdb51c85a0d3ab0bdc2049989a4015d134914275ed11a57b65

42
docs/api/utils/properties/index.html
View File

File diff suppressed because one or more lines are too long

80
docs/api/utils/signing-key/README.md
View File

@ -7,97 +7,57 @@ Documentation: [html](https://docs-beta.ethers.io/)
Signing Key
===========
#### **new** *ethers* . *utils* . **SigningKey** ( privateKey )
#### **new ***ethers* . *utils* . **SigningKey**( privateKey )
Create a new SigningKey for *privateKey*.
#### *signingKey* . **privateKey** **=>** *string< [DataHexstring](../bytes)< 32 > >*
#### *signingKey* . **privateKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The private key for this Signing Key.
#### *signingKey* . **publicKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 65 > >*
The uncompressed public key for this Signing Key. It will always be 65 bytes (130 nibbles) and begine with `0x04`.
#### *signingKey* . **publicKey** **=>** *string< [DataHexstring](../bytes)< 65 > >*
#### *signingKey* . **compressedPublicKey** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 33 > >*
The uncompressed public key for this Signing Key. It will always be
65 bytes (130 nibbles) and begine with `0x04`.
The compressed public key for this Signing Key. It will always be 33 bytes (66 nibbles) and begine with either `0x02` or `0x03`.
#### *signingKey* . **compressedPublicKey** **=>** *string< [DataHexstring](../bytes)< 33 > >*
The compressed public key for this Signing Key. It will always be
33 bytes (66 nibbles) and begine with either `0x02` or `0x03`.
#### *signingKey* . **signDisgest** ( digest ) **=>** *[Signature](../bytes)*
#### *signingKey* . **signDigest**( digest ) => *[Signature](/api/utils/bytes/#Signature)*
Sign the *digest* and return the signature.
#### *signingKey* . **computeSharedSecret**( otherKey ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Compute the ECDH shared secret with *otherKey*. The *otherKey* may be either a public key or a private key, but generally will be a public key from another party.
It is best practice that each party computes the hash of this before using it as a symmetric key.
#### *signingKey* . **computeSharedSecret** ( otherKey ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Compute the ECDH shared secret with *otherKey*. The *otherKey* may be
either a public key or a private key, but generally will be a public key from
another party.
It is best practice that each party computes the hash of this before using it
as a symmetric key.
#### *SigningKey* . **isSigningKey** ( anObject ) **=>** *boolean*
#### *SigningKey* . **isSigningKey**( anObject ) => *boolean*
Returns true if *anObject* is a SigningKey.
Other Functions
---------------
#### *ethers* . *utils* . **verifyMessage**( message , signature ) => *string< [Address](/api/utils/address/#address) >*
Returns the address that signed *message* producing *signature*. The signature may have a non-canonical v (i.e. does not need to be 27 or 28), in which case it will be normalized to compute the `recoveryParam` which will then be used to compute the address; this allows systems which use the v to encode additional data (such as [EIP-155](https://eips.ethereum.org/EIPS/eip-155)) to be used since the v parameter is still completely non-ambiguous.
#### *ethers* . *utils* . **verifyMessage** ( message , signature ) **=>** *string< [Address](../address) >*
Returns the address that signed *message* producing *signature*. The
signature may have a non-canonical v (i.e. does not need to be 27 or 28),
in which case it will be normalized to compute the `recoveryParam` which
will then be used to compute the address; this allows systems which use
the v to encode additional data (such as [EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155))
to be used since the v parameter is still completely non-ambiguous.
#### *ethers* . *utils* . **recoverPublicKey**( digest , signature ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 65 > >*
#### *ethers* . *utils* . **computePublicKey**( key [ , compressed = false ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
#### *ethers* . *utils* . **recocverPublicKey** ( digest , signature ) **=>** *string< [DataHexstring](../bytes)< 65 > >*
Computes the public key of *key*, optionally compressing it. The *key* can be any form of public key (compressed or uncompressed) or a private key.
#### *ethers* . *utils* . **computePublicKey** ( key [ , compressed=false ] ) **=>** *string< [DataHexstring](../bytes) >*
Computes the public key of *key*, optionally compressing it. The *key*
can be any form of public key (compressed or uncompressed) or a private
key.
-----
**Content Hash:** 285e65d57c4ba5901703c8a99e95632bd13aca7392d31734251d5d876e7df43e

62
docs/api/utils/signing-key/index.html
View File

File diff suppressed because one or more lines are too long

214
docs/api/utils/strings/README.md
View File

@ -7,297 +7,153 @@ Documentation: [html](https://docs-beta.ethers.io/)
Strings
=======
Tra la la
Bytes32String
-------------
A string in Solidity is length prefixed with its 256-bit (32 byte)
length, which means that even short strings require 2 words (64 bytes)
of storage.
In many cases, we deal with short strings, so instead of prefixing
the string with its length, we can null-terminate it and fit it in a
single word (32 bytes). Since we need only a single byte for the
null termination, we can store strings up to 31 bytes long in a
word.
#### Note
Strings that are 31 **bytes** long may contain fewer than 31 **characters**,
since UTF-8 requires multiple bytes to encode international characters.
Strings that are 31 **bytes** long may contain fewer than 31 **characters**, since UTF-8 requires multiple bytes to encode international characters.
#### *ethers* . *utils* . **parseBytes32String** ( aBytesLike ) **=>** *string*
#### *ethers* . *utils* . **parseBytes32String**( aBytesLike ) => *string*
Returns the decoded string represented by the `Bytes32` encoded data.
#### *ethers* . *utils* . **formatBytes32String**( text ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
#### *ethers* . *utils* . **formatBytes32String** ( text ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Returns a `bytes32` string representation of *text*. If the
length of *text* exceeds 31 bytes, it will throw an error.
Returns a `bytes32` string representation of *text*. If the length of *text* exceeds 31 bytes, it will throw an error.
UTF-8 Strings
-------------
#### *ethers* . *utils* . **toUtf8Bytes**( text [ , form = current ] ) => *Uint8Array*
Returns the UTF-8 bytes of *text*, optionally normalizing it using the [UnicodeNormalizationForm](/api/utils/strings/#strings--unicode-normalization-form) *form*.
#### *ethers* . *utils* . **toUtf8Bytes** ( text [ , form=current ] ) **=>** *Uint8Array*
Returns the UTF-8 bytes of *text*, optionally normalizing it using the
[UnicodeNormalizationForm](./) *form*.
#### *ethers* . *utils* . **toUtf8CodePoints** ( text [ , form=current ] ) **=>** *Array< number >*
Returns the Array of codepoints of *text*, optionally normalized using the
[UnicodeNormalizationForm](./) *form*.
#### *ethers* . *utils* . **toUtf8CodePoints**( text [ , form = current ] ) => *Array< number >*
Returns the Array of codepoints of *text*, optionally normalized using the [UnicodeNormalizationForm](/api/utils/strings/#strings--unicode-normalization-form) *form*.
#### Note
This function correctly splits each **user-perceived character** into
its codepoint, accounting for surrogate pairs. This should not be confused with
`string.split("")`, which destroys surrogate pairs, spliting between each UTF-16
codeunit instead.
This function correctly splits each **user-perceived character** into its codepoint, accounting for surrogate pairs. This should not be confused with `string.split("")`, which destroys surrogate pairs, spliting between each UTF-16 codeunit instead.
#### *ethers* . *utils* . **toUtf8String** ( aBytesLike [ , onError=error ] ) **=>** *string*
#### *ethers* . *utils* . **toUtf8String**( aBytesLike [ , onError = error ] ) => *string*
Returns the string represented by the UTF-8 bytes of *aBytesLike*.
The *onError* is a [Custom UTF-8 Error function](./) and if not specified
it defaults to the [error](./) function, which throws an error
on **any** UTF-8 error.
The *onError* is a [Custom UTF-8 Error function](/api/utils/strings/#strings--error-handling) and if not specified it defaults to the [error](/api/utils/strings/#strings--Utf8Error) function, which throws an error on **any** UTF-8 error.
UnicodeNormalizationForm
------------------------
There are several [commonly used forms](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Unicode_equivalence)
when normalizing UTF-8 data, which allow strings to be compared or hashed in a stable
way.
#### *ethers* . *utils* . *UnicodeNormalizationForm* . **current**
Maintain the current normalization form.
#### *ethers* . *utils* . *UnicodeNormalizationForm* . **NFC**
The Composed Normalization Form. This form uses single codepoints
which represent the fully composed character.
For example, the **&eacute;** is a single codepoint, `0x00e9`.
The Composed Normalization Form. This form uses single codepoints which represent the fully composed character.
For example, the **e** is a single codepoint, `0x00e9`.
#### *ethers* . *utils* . *UnicodeNormalizationForm* . **NFD**
The Decomposed Normalization Form. This form uses multiple codepoints
(when necessary) to compose a character.
For example, the **&eacute;**
is made up of two codepoints, `"0x0065"` (which is the letter `"e"`)
and `"0x0301"` which is a special diacritic UTF-8 codepoint which
indicates the previous character should have an acute accent.
The Decomposed Normalization Form. This form uses multiple codepoints (when necessary) to compose a character.
For example, the **e** is made up of two codepoints, `"0x0065"` (which is the letter `"e"`) and `"0x0301"` which is a special diacritic UTF-8 codepoint which indicates the previous character should have an acute accent.
#### *ethers* . *utils* . *UnicodeNormalizationForm* . **NFKC**
The Composed Normalization Form with Canonical Equivalence. The Canonical
representation folds characters which have the same syntactic representation
but different semantic meaning.
For example, the Roman Numeral **I**, which has a UTF-8
codepoint `"0x2160"`, is folded into the capital letter I, `"0x0049"`.
The Composed Normalization Form with Canonical Equivalence. The Canonical representation folds characters which have the same syntactic representation but different semantic meaning.
For example, the Roman Numeral **I**, which has a UTF-8 codepoint `"0x2160"`, is folded into the capital letter I, `"0x0049"`.
#### *ethers* . *utils* . *UnicodeNormalizationForm* . **NFKD**
The Decomposed Normalization Form with Canonical Equivalence.
See NFKC for more an example.
The Decomposed Normalization Form with Canonical Equivalence. See NFKC for more an example.
#### Note
Only certain specified characters are folded in Canonical Equivalence, and thus
it should **not** be considered a method to acheive *any* level of security from
[homoglyph attacks](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/IDN_homograph_attack).
Only certain specified characters are folded in Canonical Equivalence, and thus it should **not** be considered a method to acheive *any* level of security from [homoglyph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack).
Custom UTF-8 Error Handling
---------------------------
#### **errorFunction**( reason , offset , bytes , output [ , badCodepoint ] ) => *number*
When converting a string to its codepoints, there is the possibility
of invalid byte sequences. Since certain situations may need specific
ways to handle UTF-8 errors, a custom error handling function can be used,
which has the signature:
#### **errorFunction** ( reason , offset , bytes , output [ , badCodepoint ] ) **=>** *number*
The *reason* is one of the [UTF-8 Error Reasons](./), *offset* is the index
into *bytes* where the error was first encountered, output is the list
of codepoints already processed (and may be modified) and in certain Error
Reasons, the *badCodepoint* indicates the currently computed codepoint,
but which would be rejected because its value is invalid.
This function should return the number of bytes to skip past keeping in
mind the value at *offset* will already be consumed.
The *reason* is one of the [UTF-8 Error Reasons](/api/utils/strings/#strings--error-reasons), *offset* is the index into *bytes* where the error was first encountered, output is the list of codepoints already processed (and may be modified) and in certain Error Reasons, the *badCodepoint* indicates the currently computed codepoint, but which would be rejected because its value is invalid.
This function should return the number of bytes to skip past keeping in mind the value at *offset* will already be consumed.
### UTF-8 Error Reasons
#### *ethers* . *utils* . *Utf8ErrorReason* . **BAD_PREFIX**
A byte was encountered which is invalid to begin a UTF-8 byte
sequence with.
A byte was encountered which is invalid to begin a UTF-8 byte sequence with.
#### *ethers* . *utils* . *Utf8ErrorReason* . **MISSING_CONTINUE**
A UTF-8 sequence was begun, but did not have enough continuation
bytes for the sequence. For this error the *ofset* is the index
at which a continuation byte was expected.
A UTF-8 sequence was begun, but did not have enough continuation bytes for the sequence. For this error the *ofset* is the index at which a continuation byte was expected.
#### *ethers* . *utils* . *Utf8ErrorReason* . **OUT_OF_RANGE**
The computed codepoint is outside the range for valid UTF-8
codepoints (i.e. the codepoint is greater than 0x10ffff).
This reason will pass the computed *badCountpoint* into
the custom error function.
The computed codepoint is outside the range for valid UTF-8 codepoints (i.e. the codepoint is greater than 0x10ffff). This reason will pass the computed *badCountpoint* into the custom error function.
#### *ethers* . *utils* . *Utf8ErrorReason* . **OVERLONG**
Due to the way UTF-8 allows variable length byte sequences
to be used, it is possible to have multiple representations
of the same character, which means
[overlong sequences](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/UTF-8)
allow for a non-distinguished string to be formed, which can
impact security as multiple strings that are otherwise
equal can have different hashes.
Generally, overlong sequences are an attempt to circumvent
some part of security, but in rare cases may be produced by
lazy libraries or used to encode the null terminating
character in a way that is safe to include in a `char*`.
This reason will pass the computed *badCountpoint* into the
custom error function, which is actually a valid codepoint, just
one that was arrived at through unsafe methods.
Due to the way UTF-8 allows variable length byte sequences to be used, it is possible to have multiple representations of the same character, which means [overlong sequences](https://en.wikipedia.org/wiki/UTF-8#Overlong_encodings) allow for a non-distinguished string to be formed, which can impact security as multiple strings that are otherwise equal can have different hashes.
Generally, overlong sequences are an attempt to circumvent some part of security, but in rare cases may be produced by lazy libraries or used to encode the null terminating character in a way that is safe to include in a `char*`.
This reason will pass the computed *badCountpoint* into the custom error function, which is actually a valid codepoint, just one that was arrived at through unsafe methods.
#### *ethers* . *utils* . *Utf8ErrorReason* . **OVERRUN**
The string does not have enough characters remaining for the
length of this sequence.
The string does not have enough characters remaining for the length of this sequence.
#### *ethers* . *utils* . *Utf8ErrorReason* . **UNEXPECTED_CONTINUE**
This error is similar to BAD_PREFIX, since a continuation byte
cannot begin a valid sequence, but many may wish to process this
differently. However, most developers would want to trap this
and perform the same operation as a BAD_PREFIX.
This error is similar to BAD_PREFIX, since a continuation byte cannot begin a valid sequence, but many may wish to process this differently. However, most developers would want to trap this and perform the same operation as a BAD_PREFIX.
#### *ethers* . *utils* . *Utf8ErrorReason* . **UTF16_SURROGATE**
The computed codepoint represents a value reserved for
UTF-16 surrogate pairs.
This reason will pass the computed surrogate half
*badCountpoint* into the custom error function.
The computed codepoint represents a value reserved for UTF-16 surrogate pairs. This reason will pass the computed surrogate half *badCountpoint* into the custom error function.
### Provided UTF-8 Error Handling Functions
There are already several functions available for the most common
situations.
#### *ethers* . *utils* . *Utf8ErrorFuncs* . **error**
The will throw an error on **any** error with a UTF-8 sequence, including
invalid prefix bytes, overlong sequences, UTF-16 surrogate pairs.
The will throw an error on **any** error with a UTF-8 sequence, including invalid prefix bytes, overlong sequences, UTF-16 surrogate pairs.
#### *ethers* . *utils* . *Utf8ErrorFuncs* . **ignore**
This will drop all invalid sequences (by consuming invalid prefix bytes and
any following continuation bytes) from the final string as well as permit
overlong sequences to be converted to their equivalent string.
This will drop all invalid sequences (by consuming invalid prefix bytes and any following continuation bytes) from the final string as well as permit overlong sequences to be converted to their equivalent string.
#### *ethers* . *utils* . *Utf8ErrorFuncs* . **replace**
This will replace all invalid sequences (by consuming invalid prefix bytes and
any following continuation bytes) with the
[UTF-8 Replacement Character](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Specials_%28Unicode_block%29),
(i.e. U+FFFD).
This will replace all invalid sequences (by consuming invalid prefix bytes and any following continuation bytes) with the [UTF-8 Replacement Character](https://en.wikipedia.org/wiki/Specials_%28Unicode_block%29#Replacement_character), (i.e. U+FFFD).
-----
**Content Hash:** 07249bd69db30a03c4095abd99904dd50f0d1b924138023085e78a43e0b5e4c4

139
docs/api/utils/strings/index.html
View File

File diff suppressed because one or more lines are too long

191
docs/api/utils/transactions/README.md
View File

@ -7,235 +7,128 @@ Documentation: [html](https://docs-beta.ethers.io/)
Transactions
============
Types
-----
### UnsignedTransaction
An unsigned transaction represents a transaction that has not been
signed and its values are flexible as long as they are not ambiguous.
#### *unsignedTransaction* . **to** **=>** *string< [Address](../address) >*
#### *unsignedTransaction* . **to** => *string< [Address](/api/utils/address/#address) >*
The addres this transaction is to.
#### *unsignedTransaction* . **nonce** **=>** *number*
#### *unsignedTransaction* . **nonce** => *number*
The nonce of this transaction.
#### *unsignedTransaction* . **gasLimit** **=>** *[BigNumberish](../bignumber)*
#### *unsignedTransaction* . **gasLimit** => *[BigNumberish](/api/utils/bignumber/#BigNumberish)*
The gas limit for this transaction.
#### *unsignedTransaction* . **gasPrice** **=>** *[BigNumberish](../bignumber)*
#### *unsignedTransaction* . **gasPrice** => *[BigNumberish](/api/utils/bignumber/#BigNumberish)*
The gas price for this transaction.
#### *unsignedTransaction* . **data** **=>** *[BytesLike](../bytes)*
#### *unsignedTransaction* . **data** => *[BytesLike](/api/utils/bytes/#BytesLike)*
The data for this transaction.
#### *unsignedTransaction* . **value** **=>** *[BigNumberish](../bignumber)*
#### *unsignedTransaction* . **value** => *[BigNumberish](/api/utils/bignumber/#BigNumberish)*
The value (in wei) for this transaction.
#### *unsignedTransaction* . **chainId** => *number*
#### *unsignedTransaction* . **chainId** **=>** *number*
The chain ID for this transaction. If the chain ID is 0 or null,
then [EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155) is disabled and legacy signing is
used, unless overridden in a signature.
The chain ID for this transaction. If the chain ID is 0 or null, then [EIP-155](https://eips.ethereum.org/EIPS/eip-155) is disabled and legacy signing is used, unless overridden in a signature.
### Transaction
#### *transaction* . **hash** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
A generic object to represent a transaction.
The transaction hash, which can be used as an identifier for *transaction*. This is the keccak256 of the serialized RLP encoded representation of *transaction*.
#### *transaction* . **hash** **=>** *string< [DataHexstring](../bytes)< 32 > >*
The transaction hash, which can be used as an identifier for
*transaction*. This is the keccak256 of the serialized RLP encoded
representation of *transaction*.
#### *unsignedTransaction* . **to** **=>** *string< [Address](../address) >*
#### *unsignedTransaction* . **to** => *string< [Address](/api/utils/address/#address) >*
The address *transaction* is to.
#### *transaction* . **from** **=>** *string< [Address](../address) >*
#### *transaction* . **from** => *string< [Address](/api/utils/address/#address) >*
The address *transaction* is from.
#### *transaction* . **nonce** => *number*
The nonce for *transaction*. Each transaction sent to the network from an account includes this, which ensures the order and non-replayability of a transaction. This must be equal to the current number of transactions ever sent to the network by the **from** address.
#### *transaction* . **nonce** **=>** *number*
#### *transaction* . **gasLimit** => *[BigNumber](/api/utils/bignumber/)*
The nonce for *transaction*. Each transaction sent to the network
from an account includes this, which ensures the order and
non-replayability of a transaction. This must be equal to the current
number of transactions ever sent to the network by the **from** address.
The gas limit for *transaction*. An account must have enough ether to cover the gas (at the specified **gasPrice**). Any unused gas is refunded at the end of the transaction, and if there is insufficient gas to complete execution, the effects of the trasaction are reverted, but the gas is **fully consumed** and an out-of-gas error occurs.
#### *transaction* . **gasLimit** **=>** *[BigNumber](../bignumber)*
The gas limit for *transaction*. An account must have enough ether to
cover the gas (at the specified **gasPrice**). Any unused gas is
refunded at the end of the transaction, and if there is insufficient gas
to complete execution, the effects of the trasaction are reverted, but
the gas is **fully consumed** and an out-of-gas error occurs.
#### *transaction* . **gasPrice** **=>** *[BigNumber](../bignumber)*
#### *transaction* . **gasPrice** => *[BigNumber](/api/utils/bignumber/)*
The price (in wei) per unit of gas for *transaction*.
#### *transaction* . **data** **=>** *[BytesLike](../bytes)*
#### *transaction* . **data** => *[BytesLike](/api/utils/bytes/#BytesLike)*
The data for *transaction*. In a contract this is the call data.
#### *transaction* . **value** **=>** *[BigNumber](../bignumber)*
#### *transaction* . **value** => *[BigNumber](/api/utils/bignumber/)*
The value (in wei) for *transaction*.
#### *transaction* . **chainId** => *number*
The chain ID for *transaction*. This is used as part of [EIP-155](https://eips.ethereum.org/EIPS/eip-155) to prevent replay attacks on different networks.
For example, if a transaction was made on ropsten with an account also used on homestead, it would be possible for a transaction signed on ropsten to be executed on homestead, which is likely unintended.
There are situations where replay may be desired, however these are very rare and it is almost always recommended to specify the chain ID.
#### *transaction* . **chainId** **=>** *number*
#### *transaction* . **r** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The chain ID for *transaction*. This is used as part of
[EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155) to prevent replay attacks on different
networks.
For example, if a transaction was made on ropsten with an account
also used on homestead, it would be possible for a transaction
signed on ropsten to be executed on homestead, which is likely
unintended.
There are situations where replay may be desired, however these
are very rare and it is almost always recommended to specify the
chain ID.
The r portion of the elliptic curve signatures for *transaction*. This is more accurately, the x coordinate of the point r (from which the y can be computed, along with v).
#### *transaction* . **r** **=>** *string< [DataHexstring](../bytes)< 32 > >*
The r portion of the elliptic curve signatures for *transaction*.
This is more accurately, the x coordinate of the point r (from
which the y can be computed, along with v).
#### *transaction* . **s** **=>** *string< [DataHexstring](../bytes)< 32 > >*
#### *transaction* . **s** => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
The s portion of the elliptic curve signatures for *transaction*.
#### *transaction* . **v** => *number*
#### *transaction* . **v** **=>** *number*
The v portion of the elliptic curve signatures for *transaction*.
This is used to refine which of the two possible points a given
x-coordinate can have, and in [EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155) is additionally
used to encode the chain ID into the serialized transaction.
The v portion of the elliptic curve signatures for *transaction*. This is used to refine which of the two possible points a given x-coordinate can have, and in [EIP-155](https://eips.ethereum.org/EIPS/eip-155) is additionally used to encode the chain ID into the serialized transaction.
Functions
---------
#### *ethers* . *utils* . **computeAddress** ( publicOrPrivateKey ) **=>** *string< [Address](../address) >*
Compute the address of *publicOrPrivateKey*. If a public key is
provided, it may be either compressed or uncompressed.
#### *ethers* . *utils* . **parse** ( aBytesLike ) **=>** *[Transaction](./)*
#### *ethers* . *utils* . **parseTransaction**( aBytesLike ) => *[Transaction](/api/utils/transactions/#Transaction)*
Parses the transaction properties from a serialized transactions.
#### *ethers* . *utils* . **serializeTransaction**( tx [ , signature ] ) => *string< [DataHexString](/api/utils/bytes/#DataHexString) >*
Computes the serialized *transaction*, optionally serialized with the a *signature*. If *signature* is not present, the unsigned serialized transaction is returned, which can be used to compute the hash necessary to sign.
This function uses [EIP-155](https://eips.ethereum.org/EIPS/eip-155) if a chainId is provided, otherwise legacy serialization is used. It is **highly** recommended to always specify a *chainId*.
If *signature* includes a chain ID (explicitly or implicitly by using an [EIP-155](https://eips.ethereum.org/EIPS/eip-155) `v` or `_vs`) it will be used to compute the chain ID.
If there is a mismatch between the chain ID of *transaction* and *signature* an error is thrown.
#### *ethers* . *utils* . **recoverAddress** ( digest , aSignatureLike ) **=>** *string< [Address](../address) >*
Computes the address that signed *digest* to get *aSignatureLike* using the
ecrecover algorithm.
#### *ethers* . *utils* . **serialize** ( transaction [ , signature ] ) **=>** *string< [DataHexstring](../bytes) >*
Computes the serialized *transaction*, optionally serialized with
the a *signature*. If *signature* is not present, the unsigned
serialized transaction is returned, which can be used to compute the
hash necessary to sign.
This function uses [EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155) if a chainId is provided,
otherwise legacy serialization is used. It is **highly** recommended
to always specify a *chainId*.
If *signature* includes a chain ID (explicitly or implicitly by using an
[EIP-155](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/eips.ethereum.org/EIPS/eip-155) `v` or `_vs`) it will be used to compute the
chain ID.
If there is a mismatch between the chain ID of *transaction* and *signature*
an error is thrown.
-----
**Content Hash:** cda81a14250e9640ccedf9111dbb11772c4f513b10adac75aedf70271273a2c3

115
docs/api/utils/transactions/index.html
View File

File diff suppressed because one or more lines are too long

112
docs/api/utils/web/README.md
View File

@ -7,128 +7,88 @@ Documentation: [html](https://docs-beta.ethers.io/)
Web Utilities
=============
#### *ethers* . *utils* . **fetchJson**( urlOrConnectionInfo [ , json [ , processFunc ] ] ) => *Promise< any >*
Fetch and parse the JSON content from *urlOrConnectionInfo*, with the optiona body *json* and optionally processing the result with *processFun* before returning it.
#### *ethers* . *utils* . **fetchJson** ( urlOrConnectionInfo [ , json [ , processFunc ] ] ) **=>** *Promise< any >*
#### *ethers* . *utils* . **poll**( pollFunc [ , options ] ) => *Promise< any >*
Fetch and parse the JSON content from *urlOrConnectionInfo*, with the
optiona body *json* and optionally processing the result with *processFun*
before returning it.
Repeatedly call pollFunc using the [PollOptions](/api/utils/web/#PollOptions) until it returns a value other than undefined.
### ConnectionInfo
#### *ethers* . *utils* . **poll** ( pollFunc [ , options ] ) **=>** *Promise< any >*
Repeatedly call pollFunc using the [Poll Options](./) until it returns a
value other than undefined.
### Connection Info
#### *connection* . **url** **=>** *string*
#### *connection* . **url** => *string*
The URL to connect to.
#### *connection* . **user** => *string*
The username to use for [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). The default is null (i.e. do not use basic authentication)
#### *connection* . **user** **=>** *string*
#### *connection* . **password** => *string*
The username to use for [Basic Authentication](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Basic_access_authentication).
The default is null (i.e. do not use basic authentication)
The password to use for [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). The default is null (i.e. do not use basic authentication)
#### *connection* . **allowInsecureAuthentication** => *boolean*
Allow [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over non-secure HTTP. The default is false.
#### *connection* . **password** **=>** *string*
The password to use for [Basic Authentication](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Basic_access_authentication).
The default is null (i.e. do not use basic authentication)
#### *connection* . **allowInsecureAuthentication** **=>** *boolean*
Allow [Basic Authentication](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Basic_access_authentication) over non-secure HTTP. The default is false.
#### *connection* . **timeout** **=>** *number*
#### *connection* . **timeout** => *number*
How long to wait before rejecting with a *timeout* error.
#### *connection* . **headers** **=>** *{[key:string]:string}*
#### *connection* . **headers** => *{[key:string]:string}*
Additional headers to include in the connection.
### PollOptions
#### *options* . **timeout** => *number*
The amount of time allowed to ellapse before triggering a timeout error.
### Poll Options
#### *options* . **floor** => *number*
#### *options* . **timeout** **=>** *number*
The amount of time allowed to ellapse before triggering a timeout
error.
#### *options* . **floor** **=>** *number*
The minimum time limit to allow for [Exponential Backoff](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Exponential_backoff).
The minimum time limit to allow for [Exponential Backoff](https://en.wikipedia.org/wiki/Exponential_backoff).
The default is 0s.
#### *options* . **ceiling** => *number*
#### *options* . **ceiling** **=>** *number*
The maximum time limit to allow for [Exponential Backoff](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Exponential_backoff).
The maximum time limit to allow for [Exponential Backoff](https://en.wikipedia.org/wiki/Exponential_backoff).
The default is 10s.
#### *options* . **interval** => *number*
#### *options* . **interval** **=>** *number*
The interval used during [Exponential Backoff](../../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Exponential_backoff) calculation.
The interval used during [Exponential Backoff](https://en.wikipedia.org/wiki/Exponential_backoff) calculation.
The default is 250ms.
#### *options* . **retryLimit** => *number*
The number of times to retry in the event of an error or *undefined* is returned.
#### *options* . **retryLimit** **=>** *number*
#### *options* . **onceBlock** => *[Provider](/api/providers/provider/)*
The number of times to retry in the event of an error or *undefined* is
returned.
If this is specified, the polling will wait on new blocks from *provider* before attempting the *pollFunc* again.
#### *options* . **oncePoll** => *[Provider](/api/providers/provider/)*
If this is specified, the polling will occur on each poll cycle of *provider* before attempting the *pollFunc* again.
#### *options* . **onceBlock** **=>** *[Provider](../../providers/provider)*
If this is specified, the polling will wait on new blocks from
*provider* before attempting the *pollFunc* again.
-----
**Content Hash:** 595f603aa2c0b7be3b5139c1ea9ea198dabddd6dc76793b1558911ab70bda06f

82
docs/api/utils/web/index.html
View File

File diff suppressed because one or more lines are too long

118
docs/api/utils/wordlists/README.md
View File

@ -7,135 +7,89 @@ Documentation: [html](https://docs-beta.ethers.io/)
Wordlists
=========
Wordlist
--------
#### *wordlist* . **locale** **=>** *string*
#### *wordlist* . **locale** => *string*
The locale for this wordlist.
#### *wordlist* . **getWord** ( index ) **=>** *string*
#### *wordlist* . **getWord**( index ) => *string*
Returns the word at *index*.
#### *wordlist* . **getWordIndex** ( word ) **=>** *number*
#### *wordlist* . **getWordIndex**( word ) => *number*
Returns the index of *word* within the wordlist.
#### *wordlist* . **split**( mnemonic ) => *Array< string >*
Returns the mnemonic split into each individual word, according to a locale's valid whitespace character set.
#### *wordlist* . **split** ( mnemonic ) **=>** *Array< string >*
#### *wordlist* . **join**( words ) => *string*
Returns the mnemonic split into each individual word, according to a
locale's valid whitespace character set.
Returns the mnemonic by joining *words* together using the whitespace that is standard for the locale.
#### *Wordlist* . **check**( wordlists ) => *string< [DataHexString](/api/utils/bytes/#DataHexString)< 32 > >*
Checks that all words map both directions correctly and return the hash of the lists. Sub-classes should use this to validate the wordlist is correct against the official wordlist hash.
#### *wordlist* . **join** ( words ) **=>** *string*
Returns the mnemonic by joining *words* together using the
whitespace that is standard for the locale.
#### *Wordlist* . **check** ( wordlists ) **=>** *string< [DataHexstring](../bytes)< 32 > >*
Checks that all words map both directions correctly and return the
hash of the lists. Sub-classes should use this to validate the wordlist
is correct against the official wordlist hash.
#### *Wordlist* . **register** ( wordlist [ , name ] ) **=>** *void*
Register a wordlist with the list of wordlists, optionally overriding
the registered *name*.
#### *Wordlist* . **register**( wordlist [ , name ] ) => *void*
Register a wordlist with the list of wordlists, optionally overriding the registered *name*.
Languages
---------
#### *ethers* . *wordlists* . **cz** => *Wordlist*
The Czech [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **cz** **=>** *Wordlist*
#### *ethers* . *wordlists* . **en** => *Wordlist*
The Czech [Wordlist](./).
The English [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **es** => *Wordlist*
The Spanish [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **en** **=>** *Wordlist*
#### *ethers* . *wordlists* . **fr** => *Wordlist*
The English [Wordlist](./).
The French [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **it** => *Wordlist*
The Italian [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **es** **=>** *Wordlist*
#### *ethers* . *wordlists* . **ja** => *Wordlist*
The Spanish [Wordlist](./).
The Japanese [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **ko** => *Wordlist*
The Korean [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **fr** **=>** *Wordlist*
#### *ethers* . *wordlists* . **zh_cn** => *Wordlist*
The French [Wordlist](./).
The Simplified Chinese [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **zh_tw** => *Wordlist*
The Traditional Chinese [Wordlist](/api/utils/wordlists/#Wordlist).
#### *ethers* . *wordlists* . **it** **=>** *Wordlist*
The Italian [Wordlist](./).
#### *ethers* . *wordlists* . **ja** **=>** *Wordlist*
The Japanese [Wordlist](./).
#### *ethers* . *wordlists* . **ko** **=>** *Wordlist*
The Korean [Wordlist](./).
#### *ethers* . *wordlists* . **zh_cn** **=>** *Wordlist*
The Simplified Chinese [Wordlist](./).
#### *ethers* . *wordlists* . **zh_tw** **=>** *Wordlist*
The Traditional Chinese [Wordlist](./).
-----
**Content Hash:** a5616892113b9a9a384590f4154ea1c32b078a3eb0c3eb82ac80a79c894394d7

81
docs/api/utils/wordlists/index.html
View File

File diff suppressed because one or more lines are too long

6
docs/cli/README.md
View File

@ -7,8 +7,6 @@ Documentation: [html](https://docs-beta.ethers.io/)
Command Line Interfaces
=======================
* [Sandbox Utility](ethers)
* [Help](ethers)
* [Examples](ethers)
@ -28,7 +26,3 @@ Command Line Interfaces
* [Plugin](plugin)
* [ArgParser](plugin)
-----
**Content Hash:** 6d3508b2651887d84014e0ad49384e9d90385f23e63d1543869f700b7fdb61c5

153
docs/cli/asm/README.md
View File

@ -7,17 +7,9 @@ Documentation: [html](https://docs-beta.ethers.io/)
Assembler
=========
The assembler Command-Line utility allows you to assemble the
[Ethers ASM Dialect](../../api/other/assembly/dialect) into deployable EVM bytecode
and disassemle EVM bytecode into human-readable mnemonics.
Help
----
```
Usage:
ethers-asm [ FILENAME ] [ OPTIONS ]
@ -35,20 +27,9 @@ OTHER OPTIONS
--version Show this version and exit
```
Example Input Files
-------------------
#### **SimpleStore.asm**
```
; SimpleStore (uint)
@ -95,53 +76,31 @@ return(0, #myContract)
; There is no *need* for the PUSH32, it just makes
; decompiled code look nicer
@checksum[
{{= (defines.checksum ? concat([ Opcode.from("PUSH32"), id(myContract.source) ]): "0x") }}
{{= (defines.checksum ? concat([
Opcode.from("PUSH32"),
id(myContract.source)
]): "0x")
}}
]
}
```
#### **SimpleStore.bin**
```
0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
0x5514602457806355241077146030575b60006000fd5b60005460005260206000
0xf35b6024361415601e5760043560005560006000f3
```
#### Note: Bytecode File Syntax
A bin file may be made up of multiple blocks of bytecode, each may
optionally begin with a `0x` prefix, all of which **must** be of
even length (since bytes are required, with 2 nibbles per byte)
A bin file may be made up of multiple blocks of bytecode, each may optionally begin with a `0x` prefix, all of which **must** be of even length (since bytes are required, with 2 nibbles per byte)
All whitespace is ignored.
Assembler Examples
------------------
The assembler converts an [Ethers ASM Dialect](../../api/other/assembly/dialect) into
bytecode by running multiple passes of an assemble stage, each pass
more closely approximating the final result.
This allows small portions of the bytecode to be massaged and tweaked
until the bytecode stablizes. This allows for more compact jump
destinations and for code to be include more advanced meta-programming
techniques.
```
/home/ethers> ethers-asm SimpleStore.asm
0x602a6000556044601160003960446000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f3
@ -155,128 +114,92 @@ techniques.
0x602a6000556065601160003960656000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f37f10358310d664c9aeb4bf4ce7a10a6a03176bd23194c8ccbd3160a6dac90774d6
```
### Options
#### **--define KEY=VALUE** *or* **--define FLAG**
This allows key/value pairs (where the value is a string) and
flags (which the value is `true`) to be passed along to the
assembler, which can be accessed in
[Scripting Blocks](../../api/other/assembly/dialect), such as `{{= defined.someKey }}`.
This allows key/value pairs (where the value is a string) and flags (which the value is `true`) to be passed along to the assembler, which can be accessed in [Scripting Blocks](/api/other/assembly/dialect/#asm-dialect-scripting), such as `{{= defined.someKey }}`.
#### **--ignore-warnings**
By default any warning will be treated like an error. This enabled
by-passing warnings.
By default any warning will be treated like an error. This enabled by-passing warnings.
#### **--pic**
When a program is assembled, the labels are usually given as an
absolute byte position, which can be jumped to for loops and
control flow. This means that a program must be installed at a specific
location.
When a program is assembled, the labels are usually given as an absolute byte position, which can be jumped to for loops and control flow. This means that a program must be installed at a specific location.
Byt specifying the **Position Independent Code** flag, code
will be generated in a way such that all offsets are relative, allowing
the program to be moved without any impact to its logic.
Byt specifying the **Position Independent Code** flag, code will be generated in a way such that all offsets are relative, allowing the program to be moved without any impact to its logic.
This does incur an additional gsas cost of 8 gas per offset access though.
#### **--target LABEL**
All programs have a root scope named `_` which is by default
assembled. This option allows another labelled target (either a
[Scopes](../../api/other/assembly/dialect) or a [Data Segment](../../api/other/assembly/dialect) to be
assembled instead. The entire program is still assembled per usual,
so this only impacts which part of the program is output.
All programs have a root scope named `_` which is by default assembled. This option allows another labelled target (either a [Scopes](/api/other/assembly/dialect/#asm-dialect-scope) or a [Data Segment](/api/other/assembly/dialect/#asm-dialect-datasegment) to be assembled instead. The entire program is still assembled per usual, so this only impacts which part of the program is output.
Disassembler Examples
---------------------
A disassembled program shows offsets and mnemonics for the given
bytecode. This format may change in the future to be more
human-readable.
```
/home/ethers> ethers-asm --disassemble SimpleStore.bin
0000 : 0x2a ; #1
0002 : 0x00 ; #1
0000 : 0x2a ; #1
0002 : 0x00 ; #1
0004 : SSTORE
0005 : 0x44 ; #1
0007 : 0x11 ; #1
0009 : 0x00 ; #1
0005 : 0x44 ; #1
0007 : 0x11 ; #1
0009 : 0x00 ; #1
000b : CODECOPY
000c : 0x44 ; #1
000e : 0x00 ; #1
000c : 0x44 ; #1
000e : 0x00 ; #1
0010 : RETURN
0011 : CALLVALUE
0012 : 0x1e ; #1
0012 : 0x1e ; #1
0014 : JUMPI
0015 : 0x00 ; #1
0015 : 0x00 ; #1
0017 : CALLDATALOAD
0018 : 0xe0 ; #1
0018 : 0xe0 ; #1
001a : SHR
001b : DUP1
001c : 0x20965255 ; #4
001c : 0x20965255 ; #4
0021 : EQ
0022 : 0x24 ; #1
0022 : 0x24 ; #1
0024 : JUMPI
0025 : DUP1
0026 : 0x55241077 ; #4
0026 : 0x55241077 ; #4
002b : EQ
002c : 0x30 ; #1
002c : 0x30 ; #1
002e : JUMPI
002f*: JUMPDEST
0030 : 0x00 ; #1
0032 : 0x00 ; #1
0030 : 0x00 ; #1
0032 : 0x00 ; #1
0034 : REVERT
0035*: JUMPDEST
0036 : 0x00 ; #1
0036 : 0x00 ; #1
0038 : SLOAD
0039 : 0x00 ; #1
0039 : 0x00 ; #1
003b : MSTORE
003c : 0x20 ; #1
003e : 0x00 ; #1
003c : 0x20 ; #1
003e : 0x00 ; #1
0040 : RETURN
0041*: JUMPDEST
0042 : 0x24 ; #1
0042 : 0x24 ; #1
0044 : CALLDATASIZE
0045 : EQ
0046 : ISZERO
0047 : 0x1e ; #1
0047 : 0x1e ; #1
0049 : JUMPI
004a : 0x04 ; #1
004a : 0x04 ; #1
004c : CALLDATALOAD
004d : 0x00 ; #1
004d : 0x00 ; #1
004f : SSTORE
0050 : 0x00 ; #1
0052 : 0x00 ; #1
0050 : 0x00 ; #1
0052 : 0x00 ; #1
0054 : RETURN
/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble
/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble
# Same as above
```
-----
**Content Hash:** a948279ca64461ea65339332c81e2ae6705ff5eae5cf930e8ddd78e80739746e

202
docs/cli/asm/index.html
View File

File diff suppressed because one or more lines are too long

13
docs/cli/ens/README.md
View File

@ -7,13 +7,9 @@ Documentation: [html](https://docs-beta.ethers.io/)
Ethereum Naming Service
=======================
Help
----
```
Usage:
ethers-ens COMMAND [ ARGS ] [ OPTIONS ]
@ -86,15 +82,6 @@ OTHER OPTIONS
your bash history file. This is NOT recommended.
```
Examples
--------
TODO examples
-----
**Content Hash:** d7930b78b29531a5f2ea467260bd5f809711fd1747a4c0d5781708c1c4db867e

103
docs/cli/ens/index.html
View File

File diff suppressed because one or more lines are too long

113
docs/cli/ethers/README.md
View File

@ -7,20 +7,9 @@ Documentation: [html](https://docs-beta.ethers.io/)
Sandbox Utility
===============
The sandbox utility provides a simple way to use the most common
ethers utilities required during learning, debuging and managing
interactions with the Ethereum network.
If no command is given, it will enter a REPL interface with many
of the ethers utilities already exposed.
Help
----
```
Usage:
ethers [ COMMAND ] [ ARGS ] [ OPTIONS ]
@ -89,17 +78,9 @@ OTHER OPTIONS
your bash history file. This is NOT recommended.
```
Examples
--------
### Creating Wallets
```
/home/ethers> ethers init wallet.json
Creating a new JSON Wallet - wallet.json
@ -117,12 +98,6 @@ Saved: wallet.json
Transaction Hash: 0x8dc55b8f8dc8076acded97f9e3ed7d6162460c0221e2769806006b6d7d1156e0
```
### Sending Ether and Tokens
```
# Sending ether
/home/ricmoo> ethers --account wallet.json send ricmoo.firefly.eth 0.123
@ -169,12 +144,6 @@ Response:
Hash: 0xd609ecb7e3b5e8d36fd781dffceede3975ece6774b6322ea56cf1e4d0a17e3a1
```
### Signing Messages
```
/home/ethers> ethers --account wallet.json sign-message 'Hello World'
Password (wallet.json): ******
@ -192,51 +161,60 @@ Signature
recid: 0
```
### Scripting
The `eval` command can be used to execute simple one-line scripts from
the command line to be passed into other commands or stored in script
environment variables.
```
/home/ethers> ethers --network ropsten \
--account wallet.json \
eval \
'accounts[0].getBalance().then(b => formatEther(b))'
3.141592653589793238
```
```
# Get the formatted balance of an account
/home/ethers> ethers --network ropsten --account wallet.json eval 'accounts[0].getBalance().then(b => formatEther(b))'
3.141592653589793238
# Get the current block number
/home/ethers> ethers --network rinkeby eval "provider.getBlockNumber()"
/home/ethers> ethers --network rinkeby \
eval "provider.getBlockNumber()"
5761009
```
# Convert a Solidity signature to JSON
/home/ethers> ethers eval 'utils.Fragment.from("function balanceOf(address owner) view returns (uint)").format("json")'
{"type":"function","name":"balanceOf","constant":true,"stateMutability":"view","payble":false,"inputs":[{"type":"address","name":"owner"}],"ouputs":[{"type":"uint256"}]}
```
/home/ethers> ethers eval 'utils.Fragment.from(
"function balanceOf(address) view returns (uint)"
).format("json")' | json_pp
{
"inputs" : [
{
"type" : "address",
"name" : "owner"
}
],
"type" : "function",
"payble" : false,
"stateMutability" : "view",
"ouputs" : [
{
"type" : "uint256"
}
],
"name" : "balanceOf",
"constant" : true
}
```
# Compute a topic hash
```
/home/ricmoo> ethers eval 'id("Transfer(address,address,uint256")'
0xd99659a21de82e379975ce8df556f939a4ccb95e92144f38bb0dd35730ffcdd5
```
# Create a random mnemonic
```
/home/ricmoo> ethers eval 'Wallet.createRandom().mnemonic'
useful pond inch knock ritual matrix giggle attend dilemma convince coach amazing
```
### Using Mnemonics (with a password)
All mnemonic phrases have a password, but the default is to use the empty
string (i.e. `""`) as the password. If you have a password on your
mnemonic, the `--mnemonic-password` will prompt for the password to
use to decrypt the account.
```
/home/ricmoo> ethers --account public-mnemonic.txt --mnemonic-password
/home/ricmoo> ethers --account mnemonic.txt --mnemonic-password
Password (mnemonic): ******
network: homestead (chainId: 1)
homestead> accounts[0].getAddress()
@ -245,18 +223,8 @@ homestead> accounts[0].getAddress()
homestead>
```
### Using Mnemonics (with experimental memory-hard passwords)
The `--xxx-mnemonic-password` is similar to the `--mnemonic-password` options,
which uses a password to decrypt the account for a mnemonic, however it passes
the password through the [scrypt](../../Users/ricmoo/Development/ethers/ethers.js-v5/https:/en.wikipedia.org/wiki/Scrypt)
*password-based key derivation function* first, which is intentionally slow and makes
a brute-force attack far more difficult.
```
/home/ricmoo> ethers --account mnemonic.txt --xxx-mnemonic-password
Password (mnemonic; experimental - hard): ******
@ -268,15 +236,8 @@ homestead> accounts[0].getAddress()
homestead>
```
#### Note
This is still an experimental feature (hence the `xxx`).
-----
**Content Hash:** 634cbc81bb5078d3676f94600cb7b4083777ff1b02e4681ae52ad62e5962bf5a

225
docs/cli/ethers/index.html
View File

File diff suppressed because one or more lines are too long

31
docs/cli/index.html
View File

File diff suppressed because one or more lines are too long

207
docs/cli/plugin/README.md
View File

@ -7,210 +7,111 @@ Documentation: [html](https://docs-beta.ethers.io/)
Making Your Own
===============
The *cli* library is meant to make it easy to create command
line utilities of your own.
CLI
---
#### **addPlugin**( command , pluginClass ) => *void*
A **CLI** handles parsing all the command-line flags, options and arguments
and instantiates a [Plugin](./) to process the command.
A **CLI** may support multiple [Plugin](./)'s in which case the first
argument is used to determine which to run (or if no arguments, the default
plugin will be selected) or may be designed to be standalone, in which case
exactly one [Plugin](./) will be used and no command argument is allowed.
Add a *plugin* class for the *command*. After all options and flags have been consumed, the first argument will be consumed and the associated plugin class will be instantiated and run.
#### **addPlugin** ( command , pluginClass ) **=>** *void*
#### **setPlugin**( pluginClass ) => *void*
Add a *plugin* class for the *command*. After all options and flags
have been consumed, the first argument will be consumed and the
associated plugin class will be instantiated and run.
Set a dedicated [Plugin](/cli/plugin/#cli-plugin) class which will handle all input. This may not be used in conjuction with addPlugin and will not automatically accept a command from the arguments.
#### **setPlugin** ( pluginClass ) **=>** *void*
Set a dedicated [Plugin](./) class which will handle all input. This
may not be used in conjuction with addPlugin and will not automatically
accept a command from the arguments.
#### **showUsage** ( [ message="" [ , status=0 ] ] ) **=>** *never*
#### **showUsage**( [ message = "" [ , status = 0 ] ] ) => *never*
Shows the usage help screen for the CLI and terminates.
#### **run** ( args ) **=>** *Promise< void >*
#### **run**( args ) => *Promise< void >*
Usually the value of *args* passed in will be `process.argv.slice(2)`.
Plugin
------
Each **Plugin** manages each command of a CLI and is executed in phases.
If the usage (i.e. help) of a CLI is requested, the static methods `getHelp`
and `getOptionHelp` are used to geneate the help screen.
Otherwise, a plugin is instantiated and the `prepareOptions` is called. Each
plugin **must** call `super.prepareOptions`, otherwise the basic options are
not yet processed. During this time a Plugin should consume all the flags and
options it understands, since any left over flags or options will cause the
CLI to bail and issue an *unknown option* error. This should throw if a value
for a given option is invalid or some combination of options and flags is not
allowed.
Once the prepareOptions is complete (the returned promise is resolved), the `prepareArguments`
is called. This should validate the number of arguments is expected and throw
and error if there are too many or too few arguments or if any arguments do not
make sense.
Once the prepareArguments is complete (the returned promise is resolved), the `run`
is called.
#### *plugin* . **network** **=>** *[Network](../../api/providers/types)*
#### *plugin* . **network** => *[Network](/api/providers/types/#providers-Network)*
The network this plugin is running for.
#### *plugin* . **provider** **=>** *[Provider](../../api/providers/provider)*
#### *plugin* . **provider** => *[Provider](/api/providers/provider/)*
The provider for this plugin is running for.
#### *plugin* . **accounts** => *Array< [Signer](/api/signer/#Signer) >*
The accounts passed into the plugin using `--account`, `--account-rpc` and `--account-void` which this plugin can use.
#### *plugin* . **accounts** **=>** *Array< [Signer](../../api/signer) >*
The accounts passed into the plugin using `--account`,
`--account-rpc` and `--account-void` which this plugin can use.
#### *plugin* . **gasLimit** **=>** *[BigNumber](../../api/utils/bignumber)*
#### *plugin* . **gasLimit** => *[BigNumber](/api/utils/bignumber/)*
The gas limit this plugin should use. This is null if unspecified.
#### *plugin* . **gasPrice** **=>** *[BigNumber](../../api/utils/bignumber)*
#### *plugin* . **gasPrice** => *[BigNumber](/api/utils/bignumber/)*
The gas price this plugin should use. This is null if unspecified.
#### *plugin* . **nonce** **=>** *number*
#### *plugin* . **nonce** => *number*
The initial nonce for the account this plugin should use.
### Methods
#### *plugin* . **prepareOptions** ( argParser [ , verifyOnly=false ] ) **=>** *Promise< void >*
#### *plugin* . **prepareOptions**( argParser [ , verifyOnly = false ] ) => *Promise< void >*
#### *plugin* . **prepareArgs**( args ) => *Promise< void >*
#### *plugin* . **prepareArgs** ( args ) **=>** *Promise< void >*
#### *plugin* . **run**( ) => *Promise< void >*
#### *plugin* . **getAddress**( addressOrName [ , message = "" , [ allowZero = false ] ] ) => *Promise< string >*
A plugin should use this method to resolve an address. If the resovled address is the zero address and *allowZero* is not true, an error is raised.
#### *plugin* . **dump**( header , info ) => *void*
#### *plugin* . **run** ( ) **=>** *Promise< void >*
Dumps the contents of *info* to the console with a *header* in a nicely formatted style. In the future, plugins may support a JSON output format which will automatically work with this method.
#### *plugin* . **throwUsageError**( [ message = "" ] ) => *never*
Stops exectuion of the plugin and shows the help screen of the plugin with the optional *message*.
#### *plugin* . **getAddress** ( addressOrName [ , message="" , [ allowZero=false ] ] ) **=>** *Promise< string >*
A plugin should use this method to resolve an address. If the resovled address is
the zero address and *allowZero* is not true, an error is raised.
#### *plugin* . **dump** ( header , info ) **=>** *void*
Dumps the contents of *info* to the console with a *header* in a nicely
formatted style. In the future, plugins may support a JSON output format
which will automatically work with this method.
#### *plugin* . **throwUsageError** ( [ message="" ] ) **=>** *never*
Stops exectuion of the plugin and shows the help screen of the plugin with
the optional *message*.
#### *plugin* . **throwError** ( message ) **=>** *never*
#### *plugin* . **throwError**( message ) => *never*
Stops execution of the plugin and shows *message*.
### Static Methods
#### *Plugin* . **getHelp** => *Help*
Each subclass should implement this static method which is used to generate the help screen.
#### *Plugin* . **getHelp** **=>** *Help*
Each subclass should implement this static method which is used to
generate the help screen.
#### *Plugin* . **getOptionHelp** **=>** *Array< Help >*
Each subclass should implement this static method if it supports
additional options which is used to generate the help screen.
#### *Plugin* . **getOptionHelp** => *Array< Help >*
Each subclass should implement this static method if it supports additional options which is used to generate the help screen.
ArgParser
---------
The **ArgParser** is used to parse a command line into flags, options
and arguments.
```
/home/ethers> ethers --account wallet.json --yes send ricmoo.eth 1.0
# An Option ----------^ ^ ^
@ -225,52 +126,32 @@ and arguments.
```
Flags are simple binary options (such as the `--yes`), which are true if present
otherwise false.
Flags are simple binary options (such as the `--yes`), which are true if present otherwise false.
Options require a single parameter follow them on the command line
(such as `--account wallet.json`, which nhas the name `account` and the value
`wallet.json`)
Options require a single parameter follow them on the command line (such as `--account wallet.json`, which nhas the name `account` and the value `wallet.json`)
Arguments are all other values on the command line, and are not accessed through
the **ArgParser** directly.
Arguments are all other values on the command line, and are not accessed through the **ArgParser** directly.
When a CLI is run, an **ArgParser** is used to validate the command line by using
prepareOptions, which consumes all flags and options leaving only the arguments
behind, which are then passed into prepareArgs.
When a CLI is run, an **ArgParser** is used to validate the command line by using prepareOptions, which consumes all flags and options leaving only the arguments behind, which are then passed into prepareArgs.
#### *argParser* . **consumeFlag** ( name ) **=>** *boolean*
#### *argParser* . **consumeFlag**( name ) => *boolean*
Remove the flag *name* and return true if it is present.
#### *argParser* . **consumeMultiOptions**( names ) => *Array< {name:string,value:string} >*
Remove all options which match any name in the Array of *names* with their values returning the list (in order) of values.
#### *argParser* . **consumeMultiOptions** ( names ) **=>** *Array< {name:string,value:string} >*
#### *argParser* . **consumeOption**( name ) => *string*
Remove all options which match any name in the Array of *names*
with their values returning the list (in order) of values.
Remove the option with its value for *name* and return the value. This will throw a UsageError if the option is included multiple times.
#### *argParser* . **consumeOptions**( name ) => *Array< string >*
Remove all options with their values for *name* and return the list (in order) of values.
#### *argParser* . **consumeOption** ( name ) **=>** *string*
Remove the option with its value for *name* and return the value. This
will throw a UsageError if the option is included multiple times.
#### *argParser* . **consumeOptions** ( name ) **=>** *Array< string >*
Remove all options with their values for *name* and return the list
(in order) of values.
-----
**Content Hash:** f9148238ca768a6f2bbbc0d0d062bc5934629f900aca1df124fe07d1582fa03f

142
docs/cli/plugin/index.html
View File

File diff suppressed because one or more lines are too long

13
docs/cli/typescript/README.md
View File

@ -7,13 +7,9 @@ Documentation: [html](https://docs-beta.ethers.io/)
TypeScript
==========
Help
----
```
Usage:
ethers-ts FILENAME [ ... ] [ OPTIONS ]
@ -34,15 +30,6 @@ OTHER OPTIONS
your bash history file. This is NOT recommended.
```
Examples
--------
TODO
-----
**Content Hash:** 0ec816338871905483b5982dc90ebcc446a5466f8279ff0c741e0497656247c0

51
docs/cli/typescript/index.html
View File

File diff suppressed because one or more lines are too long

17
docs/concepts/README.md
View File

@ -4,22 +4,15 @@ Documentation: [html](https://docs-beta.ethers.io/)
-----
Concepts
========
This is a very breif overview of some aspects of *Ethereum*
and blockchains which developers can make use of or should
be aware of.
Ethereum Basics
===============
* [Events](events)
* [Solidity Topics](events)
* [Logs and Filtering](events)
* [Gas](gas)
* [Gas Price](gas)
* [Gas Limit](gas)
* [Security](security)
* [Key Derivation Functions](security)
-----
**Content Hash:** b83b7830eb49f49872ff5bc88f533e97ff5ea8c2977a72fb689cf37514365547

28
docs/concepts/best-practices/README.md Normal file
View File

@ -0,0 +1,28 @@
-----
Documentation: [html](https://docs-beta.ethers.io/)
-----
Best Practices
==============
Network Changes
---------------
```
// Force page refreshes on network changes
{
// The "any" network will allow spontaneous network changes
const provider = new ethers.providers.Web3Provider(window.ethereum, "any");
provider.on("network", (newNetwork, oldNetwork) => {
// When a Provider makes its initial connection, it emits a "network"
// event with a null oldNetwork along with the newNetwork. So, if the
// oldNetwork exists, it represents a changing network
if (oldNetwork) {
window.location.reload();
}
});
}
```

52
docs/concepts/best-practices/index.html Normal file
View File

@ -0,0 +1,52 @@
<!DOCTYPE html>
<html class="paged">
<head>
<title>Best Practices</title>
<link rel="stylesheet" type="text/css" href="/static/style.css">
</head>
<body>
<div class="sidebar">
<div class="header">
<div class="logo"><a href="/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0-beta</div></a></div>
</div>
<div class="toc"><div>
<div class="link title"><a href="/">Documentation</a></div><div class="base show link depth-1"><a href="/getting-started/">Getting Started</a></div><div class="base ancestor show link depth-1"><a href="/concepts/">Ethereum Basics</a></div><div class="show link depth-2"><a href="/concepts/events/">Events</a></div><div class="show link depth-2"><a href="/concepts/gas/">Gas</a></div><div class="show link depth-2"><a href="/concepts/security/">Security</a></div><div class="base show link depth-1"><a href="/api/">Application Programming Interface</a></div><div class="hide link depth-2"><a href="/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/api/contract/example/">Example: ERC-20 Contract</a></div><div class="hide link depth-2"><a href="/api/signer/">Signers</a></div><div class="hide link depth-2"><a href="/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/api/providers/provider/">Provider</a></div><div class="hide link depth-3"><a href="/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="hide link depth-3"><a href="/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-3"><a href="/api/providers/other/">Other Providers</a></div><div class="hide link depth-3"><a href="/api/providers/types/">Types</a></div><div class="hide link depth-2"><a href="/api/utils/">Utilities</a></div><div class="hide link depth-3"><a href="/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/api/utils/abi/interface/">Interface</a></div><div class="hide link depth-4"><a href="/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-3"><a href="/api/utils/address/">Addresses</a></div><div class="hide link depth-3"><a href="/api/utils/bignumber/">BigNumber</a></div><div class="hide link depth-3"><a href="/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-3"><a href="/api/utils/constants/">Constants</a></div><div class="hide link depth-3"><a href="/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-3"><a href="/api/utils/encoding/">Encoding Utilities</a></div><div class="hide link depth-3"><a href="/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-3"><a href="/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-3"><a href="/api/utils/hdnode/">HD Wallet</a></div><div class="hide link depth-3"><a href="/api/utils/logger/">Logging</a></div><div class="hide link depth-3"><a href="/api/utils/properties/">Property Utilities</a></div><div class="hide link depth-3"><a href="/api/utils/signing-key/">Signing Key</a></div><div class="hide link depth-3"><a href="/api/utils/strings/">Strings</a></div><div class="hide link depth-3"><a href="/api/utils/transactions/">Transactions</a></div><div class="hide link depth-3"><a href="/api/utils/web/">Web Utilities</a></div><div class="hide link depth-3"><a href="/api/utils/wordlists/">Wordlists</a></div><div class="hide link depth-2"><a href="/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/api/other/hardware/">Hardware Wallets</a></div><div class="hide link depth-2"><a href="/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/testing/">Testing</a></div><div class="base show link depth-1"><a href="/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/license/">License and Copyright</a></div>
</div></div>
</div>
<div class="content">
<div class="breadcrumbs"><a href="/">Documentation</a>&nbsp;&nbsp;&raquo;&nbsp;&nbsp;<a href="/concepts/">Ethereum Basics</a>&nbsp;&nbsp;&raquo;&nbsp;&nbsp;<span class="current">Best Practices</span></div>
<a name="best-practices"></a><a name="best-practices"></a><h1 class="show-anchors"><div>Best Practices<div class="anchors"><a class="self" href="/concepts/best-practices/#best-practices"></a></div></div></h1>
<a name="best-practices--network-changes"></a><h2 class="show-anchors"><div>Network Changes<div class="anchors"><a class="self" href="/concepts/best-practices/#best-practices--network-changes"></a></div></div></h2><p>Handling a change in the network (e.g. Ropsten vs Mainnet) is incredibly complex and a slight failure can at best make your application seem confusing and at worst cause the loss of funds, leak private data or misrepresent what an action performed.</p>
<p>Luckily, standard users should likely never change their networks unless tricked to do so or they make a mistake.</p>
<p>This is a problem you mainly need to worry about for developers, and most developers should understand the vast array of issues surrounding a network change during application operation and will understand the page reloading (which is already the default behaviour in many clients).</p>
<p>So, the best practice when a network change occurs is to simply refresh the page. This should cause all your UI components to reset to a known-safe state, including any banners and warnings to your users if they are on an unsupported network.</p>
<p>This can be acomplished by using the following function:</p>
<div class="code-title"><div>Automatically Refresh on Network Change</div></div><div class="code">// Force page refreshes on network changes
{
// The "any" network will allow spontaneous network changes
const provider = new ethers.providers.Web3Provider(window.ethereum, "any");
provider.on("network", (newNetwork, oldNetwork) =&gt; {
// When a Provider makes its initial connection, it emits a "network"
// event with a null oldNetwork along with the newNetwork. So, if the
// oldNetwork exists, it represents a changing network
if (oldNetwork) {
window.location.reload();
}
});
}</div>
<div class="footer">
<div class="nav previous"><!--PREV_LINK--></div>
<div class="nav next"><!--NEXT_LINK--></div>
</div>
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 8, 2020, 9:6pm.</div>
</div>
<script src="/static/script.js" type="text/javascript"></script>
</body>
</html>

116
docs/concepts/events/README.md
View File

@ -7,17 +7,119 @@ Documentation: [html](https://docs-beta.ethers.io/)
Events
======
Explain how topics and such work
Solidity Topics
---------------
Logs and Filtering
------------------
How to compute the topic...
### Filters
Example Log Matching
-----
**Content Hash:** 2e822e6d641a11d92d9dc649fd5e688844e36f4b93074854a0b59c6daf831995
```javascript
// <hide>
const tokenAddress = ethers.constants.AddressZero;
const myAddress = ethers.constants.AddressZero;
const myOtherAddress = ethers.constants.AddressZero;
const id = ethers.utils.id;
const hexZeroPad = ethers.utils.hexZeroPad;
// </hide>
// Short example of manually creating filters for an ERC-20
// Transfer event.
//
// Most users should generally use the Contract API to
// compute filters, as it is much simpler, but this is
// provided as an illustration for those curious. See
// below for examples of the equivalent Contract API.
// ERC-20:
// Transfer(address indexed src, address indexed dst, uint val)
//
// -------------------^
// ----------------------------------------^
//
// Notice that only *src* and *dst* are *indexed*, so ONLY they
// qualify for filtering.
//
// Also, note that in Solidity an Event uses the first topic to
// identify the Event name; for Transfer this will be:
// id("Transfer(address,address,uint256)")
//
// Other Notes:
// - A topic must be 32 bytes; so shorter types must be padded
// List all token transfers *from* myAddress
filter = {
address: tokenAddress,
topics: [
id("Transfer(address,address,uint256)"),
hexZeroPad(myAddress, 32)
]
}
// List all token transfers *to* myAddress:
filter = {
address: tokenAddress,
topics: [
id("Transfer(address,address,uint256)"),
null,
hexZeroPad(myAddress, 32)
]
}
// List all token transfers *to* myAddress or myOtherAddress:
filter = {
address: tokenAddress,
topics: [
id("Transfer(address,address,uint256)"),
null,
[
hexZeroPad(myAddress, 32),
hexZeroPad(myOtherAddress, 32),
]
]
}
```
To simplify life, ..., explain here, the contract API
```javascript
// <hide>
const tokenAddress = "0x6B175474E89094C44Da98b954EedeAC495271d0F"; // DAI
const myAddress = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
const otherAddress = "0xEA517D5a070e6705Cc5467858681Ed953d285Eb9";
const provider = ethers.getDefaultProvider();
const Contract = ethers.Contract;
// </hide>
const abi = [
"event Transfer(address indexed src, address indexed dst, uint val)"
];
const contract = new Contract(tokenAddress, abi, provider);
// List all token transfers *from* myAddress
contract.filters.Transfer(myAddress)
//!
// List all token transfers *to* myAddress:
contract.filters.Transfer(null, myAddress)
//!
// List all token transfers *from* myAddress *to* otherAddress:
contract.filters.Transfer(myAddress, otherAddress)
//!
// List all token transfers *to* myAddress OR otherAddress:
contract.filters.Transfer(null, [ myAddress, otherAddress ])
//!
```
### Other Things? TODO

145
docs/concepts/events/index.html
View File

File diff suppressed because one or more lines are too long

15
docs/concepts/gas/README.md
View File

@ -7,24 +7,9 @@ Documentation: [html](https://docs-beta.ethers.io/)
Gas
===
Explain attack vectors
Gas Price
---------
The gas price is used somewhat like a bid, indicating an amount
you are willing to pay (per unit of execution) to have your transaction
processed.
Gas Limit
---------
-----
**Content Hash:** b1f234871903b3e3a73197e38b55138313000a83a4f4e613e7347c9983c3343f

40
docs/concepts/gas/index.html
View File

File diff suppressed because one or more lines are too long

36
docs/concepts/index.html
View File

File diff suppressed because one or more lines are too long

38
docs/concepts/security/README.md Normal file
View File

@ -0,0 +1,38 @@
-----
Documentation: [html](https://docs-beta.ethers.io/)
-----
Security
========
Key Derivation Functions
------------------------
### Why does it take so long?
### Mitigating the User Experience
### Work-Arounds (not recommended)
```javascript
// Our wallet object
const wallet = Wallet.createRandom();
// The password to encrypt with
const password = "password123";
// WARNING: Doing this substantially reduces the security
// of the wallet. This is highly NOT recommended.
// We override the default scrypt.N value, which is used
// to indicate the difficulty to crack this wallet.
const json = wallet.encrypt(password, {
scrypt: {
// The number must be a power of 2 (default: 131072)
N: 64
}
});
```

Some files were not shown because too many files have changed in this diff Show More