Providers API¶

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

var providers = ethers.providers;

Connecting to Ethereum¶

There are several ways to connect to the Ethereum blockchain:

new ^providers . EtherscanProvider( [ testnet ] [ , apiToken ] )

Connect to the Etherscan blockchain web service API.

default: testnet=false, apiToken=null

new ^providers . JsonRpcProvider( [ url ] [ , testnet ] [, chainId ] )

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

default: url=”http://localhost:8545/”, testnet=false, chainId=network default

new ^providers . InfuraProvider( [ testnet ] [ , apiAccessToken ] )

Connect to the INFURA hosted network of Ethereum nodes.

default: testnet=false, apiAccessToken=null

new ^providers . FallbackProvider( providers )

Improves reliability by attempting each provider in turn, falling back to the next in the list if an error was encountered.

^providers . getDefaultProvider( [ testnet ] )

This automatically creates a FallbackProvider backed by INFURA and Etherscan; recommended

default: testnet=false

Examples¶

var providers = require('ethers').providers;

// Connect to Ropsten (the test network)
var testnet = true;

// Connect to INFUA
var infuraProvider = new providers.InfuraProvider(testnet);

// Connect to Etherscan
var etherscanProvider = new providersInfuraProvider(testnet);

// Creating a provider to automatically fallback onto Etherscan
// if INFURA is down
var fallbackProvider = new providers.FallbackProvider([
    infuraProvider,
    etherscanProvider
]);

// This is equivalent to using the getDefaultProvider
var provider = providers.getDefaultProvider(testnet)

// Connect to a local Parity instance
var provider = new providers.JsonRpcProvider('http://localhost:8545', testnet);

Prototype¶

All properties are immutable, and reflect their default value if not specified, or if indirectly populated by child Objects.

Provider¶

^prototype . testnet: Whether the provider is on the testnet (Ropsten)
^prototype . chainId: The chain ID (or network ID) this provider is connected as; this is used by signers to prevent replay attacks across compatible networks

FallbackProvider ^{( inherits from Provider )}¶

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

JsonRpcProvider ^{( inherits from Provider )}¶

^prototype . url: The JSON-RPC URL the provider is connected to
^prototype . send ( method , params ): 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.

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)

Account Actions¶

^prototype . getBalance ( address [ , blockTag ] )

Returns a Promise with the balance (as a BigNumber) of address at blockTag. (See: Block Tags)

default: blockTag=”latest”

^prototype . getTransactionCount ( address [ , blockTag ] )

Returns a Promise with the number of sent transactions (as a Number) from address at blockTag. This is also the nonce required to send a new transaction. (See: Block Tags)

default: blockTag=”latest”

Examples¶

var provider = providers.getDefaultProvider();

var address = "0x02F024e0882B310c6734703AB9066EdD3a10C6e0";

provider.getBalance(address).then(function(balance) {

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

    console.log("Balance: " + etherString);
});

provider.getTransactionCount(address).then(function(transactionCount) {
    console.log("Total Transactions Ever Send: " + transactionCount);
});

Blockchain Status¶

^prototype . getBlockNumber ( ): Returns a Promise with the latest block number (as a Number).
^prototype . getGasPrice ( ): Returns a Promise with the current gas price (as a BigNumber).
^prototype . getBlock ( blockHashOrBlockNumber ): Returns a Promise with the block at blockHashorBlockNumber. (See: Block Responses)
^prototype . getTransaction ( transactionHash ): Returns a Promise with the transaction with transactionHash. (See: Transaction Results)
^prototype . getTransactionReceipt ( transactionHash ): Returns a Promise with the transaction receipt with transactionHash. (See: Transaction Receipts)

Examples¶

Current State

var provider = providers.getDefaultProvider();

provider.getBlockNumber().then(function(blockNumber) {
    console.log("Current block number: " + blockNumber);
});

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

    console.log("Current gas price: " + gasPriceString);
});

Blocks

var provider = providers.getDefaultProvider();

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

// Block Hash
var blockHash = "0x7a1d0b010393c8d850200d0ec1e27c0c8a295366247b1bd6124d496cf59182ad";
provider.getBlock(blockHash).then(function(block) {
    console.log(block);
});

Transactions

var provider = providers.getDefaultProvider();

var transactionHash = "0x7baea23e7d77bff455d94f0c81916f938c398252fb62fce2cdb43643134ce4ed";

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

provider.getTransactionReceipt(transactionHash).then(function(transactionReceipt) {
    console.log(transactionReceipt);
});

Contract Execution¶

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

^prototype . call ( transaction )

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 )

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 )

Send the signedTransaction to the entire Ethereum network and returns a Promise with the transaction hash.

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

Examples¶

@TODO

Contract State¶

^prototype . getCode ( address )

Returns a Promise with the bytecode (as a hex string) at address.

^prototype . getStorageAt ( address, position [ , blockTag ] )

Returns a Promise with the value (as a hex string) at address in position at blockTag. (See Block Tags)

default: blockTag= “latest”

^prototype . getLogs ( filter )

Returns a Promise with an array (possibly empty) of the logs that match the filter. (See Filters)

Examples¶

@TODO

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 ): Register a callback for any future eventType; see below for callback parameters
^prototype . once ( eventType, callback): Register a callback for the next (and only next) eventType; see below for callback parameters
^prototype . removeListener ( eventType, callback ): Unregister the callback for eventType; if the same callback is registered more than once, only the first registered instance is removed
^prototype . removeAllListeners ( eventType ): Unregister all callbacks for eventType
^prototype . listenerCount ( [ eventType ] ): Return the number of callbacks registered for eventType, or if ommitted, the total number of callbacks registered

Event Types¶

“block”

Whenever a new block is mined

callback( blockNumber )

any transaction hash

When the coresponding transaction is mined; also see Waiting for Transactions

callback( transaction )

an array of topics

When any of the topics are triggered in a block’s logs; when using the Contract API, this is automatically handled;

callback( log )

Waiting for Transactions¶

^prototype . waitForTransaction ( transachtionHash [ , timeout ] ): Return a Promise which returns the transaction once transactionHash is mined, with an optional timeout (in milliseconds)

Examples¶

// Get notified on every new block
provider.on('block', function(blockNumber) {
    console.log('New Block: ' + blockNumber);
});


// Get notified when a transaction is mined
provider.once(transactionHash, function(transction) {
    console.log('Transaction Minded: ' + transaction.hash);
    console.log(transaction);
);

// OR equivalently the waitForTransaction() returns a Promise

provider.waitForTransaction(transactionHash).then(function(transaction) {
    console.log('Transaction Minded: ' + transaction.hash);
    console.log(transaction);
});


// Get notified when a contract event is logged
provider.on([ eventTopic ], function(log) {
    console.log('Event Log');
    console.log(log);
});

Objects¶

Block Tag¶

A block tag is used to uniquely identify a block’s position in th 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¶

{
    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"
    ]
}

Transaction Requests¶

Any property which accepts a number may also be specified as a BigNumber or hex string.

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

    // 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 Results¶

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

    // Exactly one of these will be present (send vs. deploy contract)
    creates: null,
    to: "0xc149Be1bcDFa69a94384b46A1F91350E5f81c1AB",

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

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

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

    // The signature of the transaction
    r: "0x5b13ef45ce3faf69d1f40f9d15b0070cc9e2c92f3df79ad46d5b3226d7f3d1e8",
    s: "0x535236e497c59e3fba93b78e124305c7c9b20db0f8531b015066725e4bb31de6",
    v: 37,

    // The raw transaction
    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
    log: [ ],
    logsBloom: "0x00" ... [ 256 bytes of 0 ] ... "00",

    // State root
    root: "0x8a27e1f7d3e92ae1a01db5cce3e4718e04954a34e9b17c1942011a5f3a942bf4",
}

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 only supports a single topic.

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

    // Optional; An address to filter by
    address: address,

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

Provider Specific Extra API Calls¶

^{EtherscanProvider} . getEtherPrice(): Returns a Promise with the price of ether in USD.

Examples¶

provider.EtherscanProvider.getEtherPrice().then(function(price) {
    console.log("Ether price in USD: " + price);
});

Providers API¶

Connecting to Ethereum¶

Examples¶

Prototype¶

Provider¶

FallbackProvider ( inherits from Provider )¶

JsonRpcProvider ( inherits from Provider )¶

EtherscanProvider ( inherits from Provider )¶

InfuraProvider ( inherits from JsonRpcProvider )¶

Account Actions¶

Examples¶

Blockchain Status¶

Examples¶

Contract Execution¶

Examples¶

Contract State¶

Examples¶

Events¶

Event Types¶

Waiting for Transactions¶

Examples¶

Objects¶

Block Tag¶

Block Responses¶

Transaction Requests¶

Transaction Results¶

Transaction Receipts¶

Filters¶

Provider Specific Extra API Calls¶

Examples¶

FallbackProvider ^{( inherits from Provider )}¶

JsonRpcProvider ^{( inherits from Provider )}¶

EtherscanProvider ^{( inherits from Provider )}¶

InfuraProvider ^{( inherits from JsonRpcProvider )}¶