162 lines
6.8 KiB
Plaintext
162 lines
6.8 KiB
Plaintext
_section: Other Providers
|
|
|
|
_subsection: FallbackProvider @<FallbackProvider> @INHERIT<[[Provider]]> @SRC<providers/fallback-provider:class.FallbackProvider>
|
|
|
|
The **FallbackProvider** is the most advanced [[Provider]] available in
|
|
ethers.
|
|
|
|
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
|
|
chosen (lower-value priority 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.
|
|
|
|
_property: 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]] or [[FallbackProviderConfig]].
|
|
If a [[Provider]] is provided, the defaults are a priority of 1 and a weight of 1.
|
|
|
|
_property: provider.providerConfigs => Array<[[FallbackProviderConfig]]>
|
|
The list of Provider Configurations that describe the backends.
|
|
|
|
_property: 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//.
|
|
|
|
|
|
_heading: FallbackProviderConfig @<FallbackProviderConfig>
|
|
|
|
_property: fallbackProviderConfig.provider => [[Provider]]
|
|
The provider for this configuration.
|
|
|
|
_property: fallbackProviderConfig.priority => number
|
|
The priority used for the provider. Lower-value priorities are favoured over
|
|
higher-value priorities. If multiple providers share the same priority, they
|
|
are chosen at random.
|
|
|
|
_property: fallbackProviderConfig.stallTimeout => number
|
|
The timeout (in ms) after which another [[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.
|
|
|
|
_property: fallbackProviderConfig.weight => number
|
|
The weight a response from this provider provides. This can be used if a given
|
|
[[Provider]] is more trusted, for example.
|
|
|
|
|
|
_subsection: IpcProvider @<IpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.IpcProvider>
|
|
|
|
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.
|
|
|
|
_property: ipcProvider.path => string
|
|
The path this [[Provider]] is connected to.
|
|
|
|
|
|
_subsection: UrlJsonRpcProvider @<UrlJsonRpcProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.UrlJsonRpcProvider>
|
|
|
|
This class is intended to be sub-classed and not used directly. It
|
|
simplifies creating a [[Provider]] where a normal [[JsonRpcProvider]]
|
|
would suffice, with a little extra effort needed to generate the JSON-RPC
|
|
URL.
|
|
|
|
_property: 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``.
|
|
|
|
_property: urlJsonRpcProvider.apiKey => any
|
|
The value of the apiKey that was returned from ``InheritedClass.getApiKey``.
|
|
|
|
_property: 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``.
|
|
|
|
_property: InheritingClass.getUrl(network, apiKey) => string
|
|
The URL to use for the JsonRpcProvider instance.
|
|
|
|
|
|
|
|
_subsection: Web3Provider @<Web3Provider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.Web3Provider>
|
|
|
|
The Web3Provider is meant to ease moving from a [web3.js based](link-web3)
|
|
application to ethers by wrapping an existing Web3-compatible (such as a
|
|
[Web3HttpProvider](link-web3-http), [Web3IpcProvider](link-web3-ipc) or
|
|
[Web3WsProvider](link-web3-ws)) and exposing it as an ethers.js [[Provider]]
|
|
which can then be used with the rest of the library.
|
|
|
|
This may also be used to wrap a standard [EIP-1193 Provider](link-eip-1193].
|
|
|
|
_property: new ethers.providers.Web3Provider(externalProvider [, network ])
|
|
Create a new **Web3Provider**, which wraps an [EIP-1193 Provider](link-eip-1193) or
|
|
Web3Provider-compatible Provider.
|
|
|
|
_property: web3Provider.provider => Web3CompatibleProvider
|
|
The provider used to create this instance.
|
|
|
|
_heading: ExternalProvider @<Web3Provider--ExternalProvider>
|
|
|
|
An **ExternalProvider** can be either one for the above mentioned Web3
|
|
Providers (or otherwise compatible) or an [[link-eip-1193]] provider.
|
|
|
|
An ExternalProvider must offer one of the following signatures, and the
|
|
first matching is used:
|
|
|
|
_property: externalProvider.request(request) => Promise<any>
|
|
|
|
This follows the [[link-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.
|
|
|
|
_property: externalProvider.sendAsync(request, callback) => void
|
|
|
|
This follows the [Web3.js Provider Signature](link-web3-send).
|
|
|
|
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.
|
|
|
|
_property: 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
|
|
|
|
|
|
_subsection: WebSocketProvider @<WebSocketProvider> @INHERIT<[[JsonRpcProvider]]> @SRC<providers:class.WebSocketProvider>
|
|
|
|
The **WebSocketProvider** connects to a JSON-RPC WebSocket-compatible backend
|
|
which allows for a persistent connection, multiplexing requests and pub-sub
|
|
events for a more immediate event dispatching.
|
|
|
|
The WebSocket API is newer, and if running your own infrastructure, note that
|
|
WebSockets are much more intensive on your server resources, as they must manage
|
|
and maintain the state for each client. For this reason, many services may also
|
|
charge additional fees for using their WebSocket endpoints.
|
|
|
|
_property: new ethers.providers.WebSocketProvider([ url [ , network ] ])
|
|
Returns a new [[WebSocketProvider]] connected to //url// as the //network//.
|
|
|
|
If //url// is unspecified, the default ``"ws:/\/localhost:8546"`` will be used.
|
|
If //network// is unspecified, it will be queried from the network.
|