132 lines
4.3 KiB
Plaintext
132 lines
4.3 KiB
Plaintext
_section: Providers @<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 use the [[providers-getDefaultProvider]].
|
|
|
|
|
|
_subsection: Default Provider @<providers-getDefaultProvider>
|
|
|
|
The default provider is the safest, easiest way to begin
|
|
developing on //Ethereum//, and it is also robust enough
|
|
for use in production.
|
|
|
|
It creates a [[FallbackProvider]] connected to as many backend
|
|
services as possible. When a request is made, it is sent to
|
|
multiple backends simultaneously. 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.
|
|
|
|
_property: ethers.getDefaultProvider([ network, [ options ] ]) => [[Provider]]
|
|
Returns a new Provider, backed by multiple services, connected
|
|
to //network//. If no //network// is provided, **homestead**
|
|
(i.e. mainnet) is used.
|
|
|
|
The //network// may also be a URL to connect to, such as ``http:/\/localhost:8545``
|
|
or ``wss:/\/example.com``.
|
|
|
|
The //options// is an object, with the following properties:
|
|
|
|
_table: Option Properties
|
|
|
|
$Alchemy: [[link-alchemy]] API Token
|
|
$Etherscan: [[link-etherscan]] API Token
|
|
$Infura: [[link-infura]] Project ID or ``{ projectId, projectSecret }``
|
|
$Pocket: [[link-pocket]] Application ID or ``{ applicationId, applicationSecretKey }``
|
|
$Quorum: The number of backends that must agree
|
|
//(default: 2 for mainnet, 1 for testnets)//
|
|
|
|
| **Property** | **Description** |
|
|
| //alchemy// | $Alchemy |
|
|
| //etherscan// | $Etherscan |
|
|
| //infura// | $Infura |
|
|
| //pocket// | $Pocket |
|
|
| //quorum// | $Quorum |
|
|
|
|
_note: Note: API Keys
|
|
|
|
It is highly recommended for production services to acquire
|
|
and specify an API Key for each service.
|
|
|
|
The default 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 specified. This allows tracking
|
|
how many requests are being sent and which methods are being
|
|
used the most.
|
|
|
|
Some services also provide additional paid features, which are only
|
|
available when specifying an API Key.
|
|
|
|
_subsection: Networks
|
|
|
|
There are several official common Ethereum networks as well as custom
|
|
networks and other compatible projects.
|
|
|
|
Any API that accept a [[providers-Networkish]] can be passed a common
|
|
name (such as ``"mainnet"`` or ``"ropsten"``) or chain ID to use that
|
|
network definition or may specify custom parameters.
|
|
|
|
_property: ethers.providers.getNetwork(aNetworkish) => [[providers-Network]]
|
|
|
|
Returns the full [[providers-Network]] for the given standard
|
|
//aNetworkish// [[providers-Networkish]].
|
|
|
|
This is useful for functions and classes which wish to accept [[providers-Networkish]]
|
|
as an input parameter.
|
|
|
|
_code: @lang<javascript>
|
|
|
|
//_hide: const getNetwork = ethers.providers.getNetwork;
|
|
|
|
// By Chain Name
|
|
//_result:
|
|
getNetwork("homestead");
|
|
//_hide: delete _._defaultProvider;
|
|
//_log:
|
|
|
|
// By Chain ID
|
|
//_result:
|
|
getNetwork(1);
|
|
//_hide: delete _._defaultProvider;
|
|
//_log:
|
|
|
|
_heading: Custom ENS Contract
|
|
|
|
One common reason to specify custom properties for a [[providers-Network]] is to override
|
|
the address of the root ENS registry, either on a common network to intercept
|
|
the [ENS Methods](Provider--ens-methods) or to specify the ENS registry on a
|
|
dev network (on most dev networks you must deploy the ENS contracts manually).
|
|
|
|
_code: Example: Override the ENS registry @lang<script>
|
|
|
|
const network = {
|
|
name: "dev",
|
|
chianId: 1337,
|
|
ensAddress: customEnsAddress
|
|
};
|
|
|
|
|
|
_subsection: Provider Documentation
|
|
|
|
_toc:
|
|
provider
|
|
jsonrpc-provider
|
|
api-providers
|
|
other
|
|
types
|