Providers

A Provider abstracts a connection to the Ethereum blockchain, for issuing queries and sending signed state changing transactions.

The EtherscanProvider and InfuraProvider offer the ability to connect to public third-party providers without the need to run any Ethereum node yourself.

The JsonRpcProvider and IpcProvider allow you to connect to Ethereum nodes you control or have access to, including mainnet, testnets, proof-of-authority (PoA) nodes or Ganache.

If you already have a Web3 application, or Web3-compatible Provider (e.g. MetaMask’s web3.currentProvider), it can be wrapped by a Web3Provider to make it compatible with the ethers Provider API.

For most situations, it is recommended that you use a default provider, which will connect to both Etherscan and INFURA simultaneously:

connect to a default provider
// You can use any standard network name
//  - "homestead"
//  - "rinkeby"
//  - "ropsten"
//  - "kovan"
//  - "goerli"

let provider = ethers.getDefaultProvider('ropsten');
connect to MetaMask
// The network will be automatically detected; if the network is
// changed in MetaMask, it causes a page refresh.

let provider = new ethers.providers.Web3Provider(web3.currentProvider);

Connecting to Ethereum

There are several methods to connect to the Ethereum network provided. If you are not running your own local Ethereum node, it is recommended that you use the getDefaultProvider() method.

ethers . getDefaultProvider( [ network = “homestead” ] )   =>   Provider

This creates a FallbackProvider backed by multiple backends (INFURA and Etherscan).

This is the recommended method of connecting to the Ethereum network if you are not running your own Ethereum node.

new ethers . providers . EtherscanProvider( [ network = “homestead” ] [ , apiToken ] )

Connect to the Etherscan blockchain web service API.

Also See: Etherscan provider-specific Properties and Operations

new ethers . providers . InfuraProvider( [ network = “homestead” ] [ , apiAccessToken ] )

Connect to the INFURA hosted network of Ethereum nodes.

Also See: INFURA provider-specific Properties

new ethers . providers . JsonRpcProvider( [ urlOrInfo = “http://localhost:8545” ] [ , network ] )

Connect to the JSON-RPC API URL urlorInfo of an Ethereum node, such as Parity or Geth.

The urlOrInfo may also be specified as an object with the properties:

  • url — the JSON-RPC URL (required)
  • user — a username to use for Basic Authentication (optional)
  • password — a password to use for Basic Authentication (optional)
  • allowInsecure — allow Basic Authentication over an insecure HTTP network (default: false)

Also See: JSON-RPC provider-specific Properties and Operations

new ethers . providers . Web3Provider( web3Provider [ , network ] )

Connect to an existing Web3 provider (e.g. web3Instance.currentProvider).

The network is also automatically detected if not specified; see the above description of network for JsonRpcProvider for details.

Also See: Web3 provider-specific Properties and Operations

new ethers . providers . FallbackProvider( providers )

Improves reliability by attempting each provider in turn, falling back to the next in the list if an error was encountered. The network is determined from the providers and the must match each other.

Also See: Fallback provider-specific Properties

new ethers . providers . IpcProvider( path [ , network ] )

Connect to the JSON-RPC API path over IPC (named pipes) to an Ethereum node, such as Parity or Geth.

The network is also automatically detected if not specified; see the above description of network for JsonRpcProvider for details.

Also See: IPC provider-specific Properties and Operations

connect to third-party providers
// You can use any standard network name
//  - "homestead"
//  - "rinkeby"
//  - "ropsten"
//  - "kovan"

let defaultProvider = ethers.getDefaultProvider('ropsten');

// ... OR ...

let etherscanProvider = new ethers.providers.EtherscanProvider('ropsten');

// ... OR ...

let infuraProvider = new ethers.providers.InfuraProvider('ropsten');
connect to a Geth or Parity node
// When using the JSON-RPC API, the network will be automatically detected


// Default: http://localhost:8545
let httpProvider = new ethers.providers.JsonRpcProvider();


// To connect to a custom URL:
let url = "http://something-else.com:8546";
let customHttpProvider = new ethers.providers.JsonRpcProvider(url);


// Connect over named pipes using IPC:
let path = "/var/run/parity.ipc";
let ipcProvider = new ethers.providers.IpcProvider(path);
connect to an existing Web3 Provider
// When using a Web3 provider, the network will be automatically detected

// e.g. HTTP provider
let currentProvider = new web3.providers.HttpProvider('http://localhost:8545');

let web3Provider = new ethers.providers.Web3Provider(currentProvider);

Properties

All properties are immutable unless otherwise specified, and will reflect their default values if left unspecified.

Provider

prototype . blockNumber
The most recent block number (block height) this provider has seen and has triggered events for. If no block has been seen, this is null.
prototype . polling

mutable

If the provider is currently polling because it is actively watching for events. This may be set to enable/disable polling temporarily or disabled permanently to allow a node process to exit.

prototype . pollingInterval

mutable

The frequency (in ms) that the provider is polling. The default interval is 4 seconds.

This may make sense to lower for PoA networks or when polling a local node. When polling Etherscan or INFURA, setting this too low may result in the service blocking your IP address or otherwise throttling your API calls.

EtherscanProvider ( inherits from Provider )

prototype . apiToken
The Etherscan API Token (or null if not specified)

InfuraProvider ( inherits from JsonRpcProvider )

prototype . apiAccessToken
The INFURA API Access Token (or null if not specified)

JsonRpcProvider ( inherits from Provider )

prototype . connection

An object describing the connection of the JSON-RPC endpoint with the properties:

  • url — the JSON-RPC URL
  • user — a username to use for Basic Authentication (optional)
  • password — a password to use for Basic Authentication (optional)
  • allowInsecure — allows Basic Authentication over an insecure HTTP network

Web3Provider ( inherits from JsonRpcProvider )

prototype . provider

The underlying Web3-compatible provider from the Web3 library, for example an HTTPProvider or IPCProvider. The only required method on a Web3 provider is:

  • sendAsync ( method , params , callback )

FallbackProvider ( inherits from Provider )

prototype . providers
A copy of the array of providers (modifying this variable will not affect the attached providers)

IpcProvider ( inherits from JsonRpcProvider )

prototype . path
The JSON-RPC IPC (named pipe) path the provider is connected to.

Network

prototype . getNetwork ( )   =>   Promise<Network>
A Promise that resolves to a Network object describing the connected network and chain.

Account

prototype . getBalance ( addressOrName [ , blockTag = “latest” ] )   =>   Promise<BigNumber>
Returns a Promise with the balance (as a BigNumber) of addressOrName at blockTag. (See: Block Tags)
prototype . getTransactionCount ( addressOrName [ , blockTag = “latest” ] )   =>   Promise<number>
Returns a Promise with the number of sent transactions (as a Number) from addressOrName at blockTag. This is also the nonce required to send a new transaction. (See: Block Tags)
get the balance of an account
let address = "0x02F024e0882B310c6734703AB9066EdD3a10C6e0";

provider.getBalance(address).then((balance) => {

    // balance is a BigNumber (in wei); format is as a sting (in ether)
    let etherString = ethers.utils.formatEther(balance);

    console.log("Balance: " + etherString);
});
get the transaction count of an account
let address = "0x02F024e0882B310c6734703AB9066EdD3a10C6e0";

provider.getTransactionCount(address).then((transactionCount) => {
    console.log("Total Transactions Ever Sent: " + transactionCount);
});

Blockchain Status

prototype . getBlockNumber ( )   =>   Promise<number>
Returns a Promise with the latest block number (as a Number).
prototype . getGasPrice ( )   =>   Promise<BigNumber>
Returns a Promise with the current gas price (as a BigNumber).
prototype . getBlock ( blockHashOrBlockNumber )   =>   Promise<Block>
Returns a Promise with the block at blockHashOrBlockNumber. (See: Block Responses)
prototype . getTransaction ( transactionHash )   =>   Promise<TransactionResponse>
Returns a Promise with the transaction with transactionHash. (See: Transaction Responses)
prototype . getTransactionReceipt ( transactionHash )   =>   Promise<TransactionReceipt>
Returns a Promise with the transaction receipt with transactionHash. (See: Transaction Receipts)
current state
provider.getBlockNumber().then((blockNumber) => {
    console.log("Current block number: " + blockNumber);
});

provider.getGasPrice().then((gasPrice) => {
    // gasPrice is a BigNumber; convert it to a decimal string
    gasPriceString = gasPrice.toString();

    console.log("Current gas price: " + gasPriceString);
});
blocks
// See: https://ropsten.etherscan.io/block/3346773

// Block Number
provider.getBlock(3346773).then((block) => {
    console.log(block);
});

// Block Hash
let blockHash = "0x7a1d0b010393c8d850200d0ec1e27c0c8a295366247b1bd6124d496cf59182ad";
provider.getBlock(blockHash).then((block) => {
    console.log(block);
});
transactions
// See: https://ropsten.etherscan.io/tx/0xa4ddad980075786c204b45ab8193e543aec4411bd94894abef47dc90d4d3cc01

let transactionHash = "0xa4ddad980075786c204b45ab8193e543aec4411bd94894abef47dc90d4d3cc01"

provider.getTransaction(transactionHash).then((transaction) => {
    console.log(transaction);
});

provider.getTransactionReceipt(transactionHash).then((receipt) => {
    console.log(receipt);
});

Ethereum Naming Service

The Ethereum Naming Service (ENS) allows easy to remember and use names to be assigned to Ethereum addresses. Any provider operation which takes an address may also take an ENS name.

ENS also provides the ability for a reverse lookup, which determines the name for an address if it has been configured.

prototype . resolveName ( ensName )   =>   Promise<Address>
Returns a Promise which resolves to the address of that the ensName resolves to (or null is not configured).
prototype . lookupAddress ( address )   =>   Promise<string>
Returns a Promise which resolves to the ENS name that address resolves to (or null if not configured).
resolve an ENS name to an address
provider.resolveName("registrar.firefly.eth").then(function(address) {
    console.log("Address: " + address);
    // "0x6fC21092DA55B392b045eD78F4732bff3C580e2c"
});
lookup the ENS name of an address
let address = "0x6fC21092DA55B392b045eD78F4732bff3C580e2c";
provider.lookupAddress(address).then(function(address) {
    console.log("Name: " + address);
    // "registrar.firefly.eth"
});

Contract Execution

These are relatively low-level calls. The Contracts API should usually be used instead.

prototype . call ( transaction )   =>   Promise<hex>

Send the read-only (constant) transaction to a single Ethereum node and return a Promise with the result (as a hex string) of executing it. (See Transaction Requests)

This is free, since it does not change any state on the blockchain.

prototype . estimateGas ( transaction )   =>   Promise<BigNumber>

Send a transaction to a single Ethereum node and return a Promise with the estimated amount of gas required (as a BigNumber) to send it. (See Transaction Requests)

This is free, but only an estimate. Providing too little gas will result in a transaction being rejected (while still consuming all provided gas).

prototype . sendTransaction ( signedTransaction )   =>   Promise<TransactionResponse>

Send the signedTransaction to the entire Ethereum network and returns a Promise that resolves to the Transaction Response.

If an error occurs after the netowrk may have received the transaction, the promise will reject with the error, with the additional property transactionHash so that further processing may be done.

This will consume gas from the account that signed the transaction.

calling constant functions
// See: https://ropsten.etherscan.io/address/0x6fc21092da55b392b045ed78f4732bff3c580e2c

// Setup a transaction to call the FireflyRegistrar.fee() function

// FireflyRegistrar contract address
let address = "0x6fC21092DA55B392b045eD78F4732bff3C580e2c";

// First 4 bytes of the hash of "fee()" for the sighash selector
let data = ethers.utils.hexDataSlice(ethers.utils.id('fee()'), 0, 4);

let transaction = {
    to: ensName,
    data: data
}

let callPromise = defaultProvider.call(transaction);

callPromise.then((result) => {
    console.log(result);
    // "0x000000000000000000000000000000000000000000000000016345785d8a0000"

    console.log(ethers.utils.formatEther(result));
    // "0.1"
});
sending a transaction
let privateKey = '0x0123456789012345678901234567890123456789012345678901234567890123';
let wallet = new ethers.Wallet(privateKey, provider);

let transaction = {
    to: "ricmoo.firefly.eth",
    value: ethers.utils.parseEther("0.1")
};

// Send the transaction
let sendTransactionPromise = wallet.sendTransaction(transaction);

sendTransactionPromise.then((tx) => {
   console.log(tx);
});

Contract State

prototype . getCode ( addressOrName )   =>   Promise<hex>
Returns a Promise with the bytecode (as a hex string) at addressOrName.
prototype . getStorageAt ( addressOrName , position [ , blockTag = “latest” ] )   =>   Promise<hex>
Returns a Promise with the value (as a hex string) at addressOrName in position at blockTag. (See Block Tags)
prototype . getLogs ( filter )   =>   Promise< Log [ ] >
Returns a Promise with an array (possibly empty) of the logs that match the filter. (See Filters)
get contract code
let contractEnsName = 'registrar.firefly.eth';

let codePromise = provider.getCode(contractEnsName);

codePromise.then((result) => {
   console.log(result);
});
get contract storage value
let contractEnsName = 'registrar.firefly.eth';

// Position 0 in the FireflyRegistrar contract holds the ENS address

let storagePromise = provider.getStorageAt(contractEnsName, 0);

storagePromise.then((result) => {
   console.log(result);
   // "0x000000000000000000000000112234455c3a32fd11230c42e7bccd4a84e02010"
});
get contract event logs
let contractEnsName = 'registrar.firefly.eth';

let topic = ethers.utils.id("nameRegistered(bytes32,address,uint256)");

let filter = {
    address: contractEnsName,
    fromBlock: 3313425,
    toBlock: 3313430,
    topics: [ topic ]
}

provider.getLogs(filter).then((result) => {
    console.log(result);
    // [ {
    //    blockNumber: 3313426,
    //    blockHash: "0xe01c1e437ed3af9061006492cb07454eca8561479454a709809b7897f225387d",
    //    transactionIndex: 5,
    //    removed: false,
    //    address: "0x6fC21092DA55B392b045eD78F4732bff3C580e2c",
    //    data: "0x00000000000000000000000053095760c154a1531a69fc718119d14c4aa1506f" +
    //            "000000000000000000000000000000000000000000000000016345785d8a0000",
    //    topics: [
    //      "0x179ef3319e6587f6efd3157b34c8b357141528074bcb03f9903589876168fa14",
    //      "0xe625ed7b108857745d1d9889a7ae05861d8aee38e0e92fd3a31191de01c2515b"
    //    ],
    //    transactionHash: "0x61d641aaf3dcf4cf6bafc3e79d332d8773ea0688f87eb00f8b60c3f0050e55f0",
    //    logIndex: 5
    // } ]

});

Events

These methods allow management of callbacks on certain events on the blockchain and contracts. They are largely based on the EventEmitter API.

prototype . on ( eventType , callback )   =>   Provider
Register a callback for any future eventType; see below for callback parameters
prototype . once ( eventType , callback)   =>   Provider
Register a callback for the next (and only next) eventType; see below for callback parameters
prototype . removeListener ( eventType , callback )   =>   boolean
Unregister the callback for eventType; if the same callback is registered more than once, only the first registered instance is removed
prototype . removeAllListeners ( eventType )   =>   Provider
Unregister all callbacks for eventType
prototype . listenerCount ( [ eventType ] )   =>   number
Return the number of callbacks registered for eventType, or if ommitted, the total number of callbacks registered
prototype . resetEventsBlock ( blockNumber )   =>   void
Begin scanning for events from blockNumber. By default, events begin at the block number that the provider began polling at.

Event Types

“block”

Whenever a new block is mined

callback( blockNumber )

“pending”

Whenever a new transaction is added to the transaction pool. This is NOT available on Etherscan or INFURA providers and may not be reliable on any provider.

callback( transactionHash )

“error”

Whenever an error occurs during an event.

callback( error )

any address

When the balance of the corresponding address changes.

callback( balance )

any transaction hash

When the corresponding transaction has been included in a block; also see Waiting for Transactions.

callback( transactionReceipt )

a filtered event object

When the an event is logged by a transaction to the address with the associated topics. The filtered event properties are:

  • address — the contract address to filter by (optional)
  • topics — the log topics to filter by (optional)

callback( log )

an array of topics

When any of the topics are logs by a transaction to any address. This is equivalent to using a filter object with no address.

callback( log )

Waiting for Transactions

prototype . waitForTransaction ( transactionHash )   =>   Promise<TransactionReceipt>
Return a Promise which resolves to the Transaction Receipt once transactionHash is mined.
new blocks
provider.on('block', (blockNumber) => {
    console.log('New Block: ' + blockNumber);
});
account balance changes
provider.on('0x46Fa84b9355dB0708b6A57cd6ac222950478Be1d', (balance) => {
    console.log('New Balance: ' + balance);
});
transaction mined
provider.once(transactionHash, (receipt) => {
    console.log('Transaction Minded: ' + receipt.hash);
    console.log(receipt);
);

// ... OR ...

provider.waitForTransaction(transactionHash).then((receipt) => {
    console.log('Transaction Mined: ' + receipt.hash);
    console.log(receipt);
});
a filtered event has been logged
let contractEnsName = 'registrar.firefly.eth';

let topic = ethers.utils.id("nameRegistered(bytes32,address,uint256)");

let filter = {
    address: contractEnsName,
    topics: [ topic ]
}

provider.on(filter, (result) => {
    console.log(result);
    // {
    //    blockNumber: 3606106,
    //    blockHash: "0x878aa7059c93239437f66baeec82332dcb2f9288bcdf6eb1ff3ba6998cdf8f69",
    //    transactionIndex: 6,
    //    removed: false,
    //    address: "0x6fC21092DA55B392b045eD78F4732bff3C580e2c",
    //    data: "0x00000000000000000000000006b5955a67d827cdf91823e3bb8f069e6c89c1d6" +
    //            "000000000000000000000000000000000000000000000000016345785d8a0000",
    //    topics: [
    //      "0x179ef3319e6587f6efd3157b34c8b357141528074bcb03f9903589876168fa14",
    //      "0x90a4d0958790016bde1de8375806da3be227ff48e611aefea36303fb86bca5ad"
    //    ],
    //    transactionHash: "0x0d6f43accb067ca8e391666f37f8e8ad75f88ebd8036c9166fd2d0b93b214d2e",
    //    logIndex: 6
    // }
});

Objects and Types

There are several common objects and types that are commonly used as input parameters or return types for various provider calls.

Block Tag

A block tag is used to uniquely identify a block’s position in the blockchain:

a Number or hex string:
Each block has a block number (eg. 42 or "0x2a.
“latest”:
The most recently mined block.
“pending”:
The block that is currently being mined.

Block Responses

Example
{
    parentHash: "0x3d8182d27303d92a2c9efd294a36dac878e1a9f7cb0964fa0f789fa96b5d0667",
    hash: "0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b",
    number: 3346463,

    difficulty: 183765779077962,
    timestamp: 1489440489,
    nonce: "0x17060cb000d2c714",
    extraData: "0x65746865726d696e65202d20555331",

    gasLimit: utils.bigNumberify("3993225"),
    gasUsed: utils.bigNuberify("3254236"),

    miner: "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
    transactions: [
        "0x125d2b846de85c4c74eafb6f1b49fdb2326e22400ae223d96a8a0b26ccb2a513",
        "0x948d6e8f6f8a4d30c0bd527becbe24d15b1aba796f9a9a09a758b622145fd963",
        ... [ 49 more transaction hashes ] ...
        "0xbd141969b164ed70388f95d780864210e045e7db83e71f171ab851b2fba6b730"
    ]
}

Network

A network repsents various properties of a network, such as mainnet (i.e. “homestead”) or one of the testnets (e.g. “ropsten”, “rinkeby” or “kovan”) or alternative networks (e.g. “classic”). A Network has the following properties:

  • name — the name of the network (e.g. “homestead”, “rinkeby”)
  • chainId — the chain ID (network ID) of the connected network
  • ensAddress — the address of ENS if it is deployed to the network, otherwise null

If a network does not have the ENS contract deployed to it, names cannot be resolved to addresses.

get a standard network
let network = ethers.providers.getNetwork('homestead');
// {
//    chainId: 1,
//    ensAddress: "0x314159265dd8dbb310642f98f50c066173c1259b",
//    name: "homestead"
// }
a custom development network
let network = {
    chainId: 1337,
    name: "dev"
}

Transaction Requests

Any property which accepts a number may also be specified as a BigNumber or hex string. Any property may also be given as a Promise which resolves to the expected type.

Example
{
    // Required unless deploying a contract (in which case omit)
    to: addressOrName,  // the target address or ENS name

    // These are optional/meaningless for call and estimateGas
    nonce: 0,           // the transaction nonce
    gasLimit: 0,        // the maximum gas this transaction may spend
    gasPrice: 0,        // the price (in wei) per unit of gas

    // These are always optional (but for call, data is usually specified)
    data: "0x",         // extra data for the transaction, or input for call
    value: 0,           // the amount (in wei) this transaction is sending
    chainId: 3          // the network ID; usually added by a signer
}

Transaction Response

Example
{
    // Only available for mined transactions
    blockHash: "0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b",
    blockNumber: 3346463,
    timestamp: 1489440489,

    // Exactly one of these will be present (send vs. deploy contract)
    // They will always be a properly formatted checksum address
    creates: null,
    to: "0xc149Be1bcDFa69a94384b46A1F91350E5f81c1AB",

    // The transaction hash
    hash: "0xf517872f3c466c2e1520e35ad943d833fdca5a6739cfea9e686c4c1b3ab1022e",

    // See above "Transaction Requests" for details
    data: "0x",
    from: "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
    gasLimit: utils.bigNumberify("90000"),
    gasPrice: utils.bigNumberify("21488430592"),
    nonce: 0,
    value: utils.parseEther(1.0017071732629267),

    // The chain ID; 0 indicates replay-attack vulnerable
    // (eg. 1 = Homestead mainnet, 3 = Ropsten testnet)
    chainId: 1,

    // The signature of the transaction (TestRPC may fail to include these)
    r: "0x5b13ef45ce3faf69d1f40f9d15b0070cc9e2c92f3df79ad46d5b3226d7f3d1e8",
    s: "0x535236e497c59e3fba93b78e124305c7c9b20db0f8531b015066725e4bb31de6",
    v: 37,

    // The raw transaction (TestRPC may be missing this)
    raw: "0xf87083154262850500cf6e0083015f9094c149be1bcdfa69a94384b46a1f913" +
           "50e5f81c1ab880de6c75de74c236c8025a05b13ef45ce3faf69d1f40f9d15b0" +
           "070cc9e2c92f3df79ad46d5b3226d7f3d1e8a0535236e497c59e3fba93b78e1" +
           "24305c7c9b20db0f8531b015066725e4bb31de6"
}

Transaction Receipts

Example
{
    transactionHash: "0x7dec07531aae8178e9d0b0abbd317ac3bb6e8e0fd37c2733b4e0d382ba34c5d2",

    // The block this transaction was mined into
    blockHash: "0xca1d4d9c4ac0b903a64cf3ae3be55cc31f25f81bf29933dd23c13e51c3711840",
    blockNumber: 3346629,

    // The index into this block of the transaction
    transactionIndex: 1,

    // The address of the contract (if one was created)
    contractAddress: null,

    // Gas
    cumulativeGasUsed: utils.bigNumberify("42000"),
    gasUsed: utils.bigNumberify("21000"),

    // Logs (an Array of Logs)
    log: [ ],
    logsBloom: "0x00" ... [ 256 bytes of 0 ] ... "00",

    // Post-Byzantium hard-fork
    byzantium: false

    ////////////
    // Pre-byzantium blocks will have a state root:
    root: "0x8a27e1f7d3e92ae1a01db5cce3e4718e04954a34e9b17c1942011a5f3a942bf4",

    ////////////
    // Post-byzantium blocks will have a status (0 indicated failure during execution)
    // status: 1
}

Log

Example
{
    // The block this log was emitted by
    blockNumber:
    blockHash:

    // The transaction this log was emiited by
    transactionHash:
    transactionIndex:
    logIndex:

    // Whether the log has been removed (due to a chain re-org)
    removed: false,

    // The contract emitting the log
    address:

    // The indexed data (topics) and non-indexed data (data) for this log
    topics: []
    data:
}

Filters

Filtering on topics supports a somewhat complicated specification, however, for the vast majority of filters, a single topic is usually sufficient (see the example below).

The EtherscanProvider currently only supports a single topic.

Example
{
    // Optional; The range of blocks to limit querying (See: Block Tags above)
    fromBlock: "latest",
    toBlock: "latest",

    // Optional; The specific block to limit the query to
    // Note: This may NOT be used with fromBlock or toBlock
    // Note: EtherscanProvider does not support blockHash
    // Note: This may be used for getLogs, but not as a provider Event (i.e. .on)
    blockHash: blockHash,

    // Optional; An address (or ENS name) to filter by
    address: addressOrName,

    // Optional; A (possibly nested) list of topics
    topics: [ topic1 ]
}

@TODO: Link to cookbook entry for filtering ERC-20 events for an address

Provider Specific Extra API Calls

Etherscan

prototype . getEtherPrice ( )
Returns a Promise with the price of ether in USD.
prototype . getHistory ( addressOrName [ , startBlock = 0 [ , endBlock = “latest” ] ] )
Returns a Promise with an array of Transaction Responses for each transaction to or from addressOrName between startBlock and endBlock (inclusive).
a filtered event has been logged
let etherscanProvider = new ethers.providers.EtherscanProvider();

// Getting the current Ethereum price
etherscanProvider.getEtherPrice().then(function(price) {
    console.log("Ether price in USD: " + price);
});


// Getting the transaction history of an address
let address = '0xb2682160c482eB985EC9F3e364eEc0a904C44C23';
let startBlock = 3135808;
let endBlock = 5091477;
etherscanProvider.getHistory(address, startBlock, endBlock).then(function(history) {
    console.log(history);
    // [
    //   {
    //     hash: '0x327632ccb6d7bb47b455383e936b2f14e6dc50dbefdc214870b446603b468675',
    //     blockHash: '0x0415f0d2741de45fb748166c7dc2aad9b3ff66bcf7d0a127f42a71d3e286c36d',
    //     blockNumber: 3135808,
    //     transactionIndex: 1,
    //     from: '0xb2682160c482eB985EC9F3e364eEc0a904C44C23',
    //     gasPrice: ethers.utils.bigNumberify('0x4a817c800'),
    //     gasLimit: ethers.utils.bigNumberify('0x493e0'),
    //     to: '0xAe572713CfE65cd7033774170F029B7219Ee7f70',
    //     value: ethers.utils.bigNumberify('0xd2f13f7789f0000'),
    //     nonce: 25,
    //     data: '0x',
    //     creates: null,
    //     chainId: 0
    //   },
    //   {
    //     hash: '0x7c10f2e7125a1fa5e37b54f5fac5465e8d594f89ff97916806ca56a5744812d9',
    //     ...
    //   }
    // ]
});

JsonRpcProvider

prototype . send ( method , params )   =>   Promise<any>
Send the JSON-RPC method with params. This is useful for calling non-standard or less common JSON-RPC methods. A Promise is returned which will resolve to the parsed JSON result.
prototype . listAccounts ( )   =>   Promise<Address [ ] >
Returns a Promise with a list of all account addresses the node connected to this Web3 controls.
prototype . getSigner( [ indexOrAddress ] )   =>   JsonRpcSigner
Returns a JsonRpcSigner attached to an account on the Ethereum node the Web3 object is connected to. If indexOrAddress is not specified, the first account on the node is used.
send vendor specific JSON-RPC API
let hash = "0x2ddf6dd2ec23adf525dac59d7c9189b25b172d679aad951e59e232045f2c811f";
jsonRpcProvider.send('debug_traceTransaction', [ hash ]).then((result) => {
    console.log(result);
});
list accounts and load the second account
// Get a signer for the account at index 1
jsonRpcProvider.listAccounts().then((accounts) => {
    let signer = jsonRpcProvider.getSigner(accounts[1]);
    console.log(signer);
});

JsonRpcSigner

An account from a JSON-RPC API connection the conforms to the Signer API. The getSigner method of a JsonRpcProvider should be used to instantiate these.

prototype . provider
The provider that this Signer is connected to.
prototype . getAddress ( )   =>   Promise<Address>
Returns a Promise that resolves to the account address.
prototype . getBalance ( [ blockTag = “latest” ] )   =>   Promise<BigNumber>
Returns a Promise for the account balance.
prototype . getTransactionCount ( [ blockTag = “latest” ] )   =>   Promise<number>
Returns a Promise for the account transaction count. This can be used to determine the next nonce to use for a transaction.
prototype . sendTransaction ( [ transactionRequest ] )   =>   Promise<TransactionResponse>

Returns a Promise that resolves to the Transaction Response for the sent transaction.

If an error occurs after the netowrk may have received the transaction, the promise will reject with the error, with the additional property transactionHash so that further processing may be done.

prototype . signMessage ( message )   =>   Promise<hex>
Returns a Promise that resolves the signature of a signed message, in the Flat Format.
prototype . unlock ( password )   =>   Promise<boolean>
Returns a Promise the resolves to true or false, depending on whether the account unlock was successful.