Documentation

Documentation »API »Providers »Subclassing Provider

Subclassing Provider

The available providers should suffice for most developers purposes, but the AbstractProvider class has many features which enable sub-classing it for specific purposes.

TYPES

<src>AbstractProviderOptions⇒ { cacheTimeout?: number , pollingInterval?: number }

Options for configuring some internal aspects of an AbstractProvider.

cacheTimeout - how long to cache a low-level _perform for, based on input parameters. This reduces the number of calls to getChainId and getBlockNumber, but may break test chains which can perform operations (internally) synchronously. Use -1 to disable, 0 will only buffer within the same event loop and any other value is in ms. (default: 250)

<src>DebugEventAbstractProvider⇒ { action: "sendCcipReadFetchRequest" , index: number , request: FetchRequest , urls: Array< string > } | { action: "receiveCcipReadFetchResult" , request: FetchRequest , result: any } | { action: "receiveCcipReadFetchError" , request: FetchRequest , result: any } | { action: "sendCcipReadCall" , transaction: { data: string , to: string } } | { action: "receiveCcipReadCallResult" , result: string , transaction: { data: string , to: string } } | { action: "receiveCcipReadCallError" , error: Error , transaction: { data: string , to: string } }

The types of additional event values that can be emitted for the "debug" event.

<src>PerformActionFilter⇒ { address?: string | Array< string > , fromBlock?: BlockTag , toBlock?: BlockTag , topics?: Array< null | string | Array< string > > } | { address?: string | Array< string > , blockHash?: string , topics?: Array< null | string | Array< string > > }

A normalized filter used for PerformActionRequest objects.

<src>PerformActionRequest⇒ { method: "broadcastTransaction" , signedTransaction: string } | { blockTag: BlockTag , method: "call" , transaction: PerformActionTransaction } | { method: "chainId" } | { method: "estimateGas" , transaction: PerformActionTransaction } | { address: string , blockTag: BlockTag , method: "getBalance" } | { blockTag: BlockTag , includeTransactions: boolean , method: "getBlock" } | { blockHash: string , includeTransactions: boolean , method: "getBlock" } | { method: "getBlockNumber" } | { address: string , blockTag: BlockTag , method: "getCode" } | { method: "getGasPrice" } | { filter: PerformActionFilter , method: "getLogs" } | { method: "getPriorityFee" } | { address: string , blockTag: BlockTag , method: "getStorage" , position: bigint } | { hash: string , method: "getTransaction" } | { address: string , blockTag: BlockTag , method: "getTransactionCount" } | { hash: string , method: "getTransactionReceipt" } | { hash: string , method: "getTransactionResult" }

The AbstractProvider methods will normalize all values and pass this type to abstractProvider._perform.

<src>Subscription⇒ { tag: string , type: "block" | "close" | "debug" | "error" | "finalized" | "network" | "pending" | "safe" } | { hash: string , tag: string , type: "transaction" } | { filter: EventFilter , tag: string , type: "event" } | { filter: OrphanFilter , tag: string , type: "orphan" }

The value passed to the abstractProvider._getSubscriber method.

Only developers sub-classing [[AbstractProvider[[ will care about this, if they are modifying a low-level feature of how subscriptions operate.

FUNCTIONS

<src>getPollingSubscriber(provider: AbstractProvider, event: ProviderEvent)⇒ Subscriber

Return the polling subscriber for common events.

class AbstractProvider

inherits from Provider, ContractRunner, EventEmitterable, NameResolver

An AbstractProvider provides a base class for other sub-classes to implement the Provider API by normalizing input arguments and formatting output results as well as tracking events for consistent behaviour on an eventually-consistent network.

PROPERTIES

<src>abstractProvider.destroyed⇒ booleanread-only

If this provider has been destroyed using the destroy method.

Once destroyed, all resources are reclaimed, internal event loops and timers are cleaned up and no further requests may be sent to the provider.

<src>abstractProvider.disableCcipRead⇒ boolean

Prevent any CCIP-read operation, regardless of whether requested in a call using enableCcipRead.

<src>abstractProvider.paused⇒ boolean

Whether the provider is currently paused.

A paused provider will not emit any events, and generally should not make any requests to the network, but that is up to sub-classes to manage.

Setting paused = true is identical to calling .pause(false), which will buffer any events that occur while paused until the provider is unpaused.

<src>abstractProvider.plugins⇒ Array< AbstractProviderPlugin >read-only

Returns all the registered plug-ins.

<src>abstractProvider.pollingInterval⇒ numberread-only

<src>abstractProvider.provider⇒ thisread-only

Returns this, to allow an AbstractProvider to implement the ContractRunner interface.

CREATING INSTANCES

<src>new AbstractProvider(network?: "any" | Networkish, options?: AbstractProviderOptions)

Create a new AbstractProvider connected to network, or use the various network detection capabilities to discover the Network if necessary.

METHODS

<src>abstractProvider._clearTimeout(timerId: number)⇒ void

Clear a timer created using the _setTimeout method.

<src>abstractProvider._detectNetwork()⇒ Promise< Network >

Resolves to the Network, forcing a network detection using whatever technique the sub-class requires.

Sub-classes must override this.

<src>abstractProvider._forEachSubscriber(func: (s: Subscriber) => void)⇒ void

Perform func on each subscriber.

<src>abstractProvider._getAddress(address: AddressLike)⇒ string | Promise< string >

Returns or resolves to the address for address, resolving ENS names and Addressable objects and returning if already an address.

<src>abstractProvider._getBlockTag(blockTag?: BlockTag)⇒ string | Promise< string >

Returns or resolves to a valid block tag for blockTag, resolving negative values and returning if already a valid block tag.

<src>abstractProvider._getFilter(filter: Filter | FilterByBlockHash)⇒ PerformActionFilter | Promise< PerformActionFilter >

Returns or resolves to a filter for filter, resolving any ENS names or Addressable object and returning if already a valid filter.

<src>abstractProvider._getProvider(chainId: number)⇒ AbstractProvider

<src>abstractProvider._getSubscriber(sub: Subscription)⇒ Subscriber

Sub-classes may override this to customize subscription implementations.

<src>abstractProvider._getTransactionRequest(request: TransactionRequest)⇒ PerformActionTransaction | Promise< PerformActionTransaction >

Returns or resolves to a transaction for request, resolving any ENS names or Addressable and returning if already a valid transaction.

<src>abstractProvider._perform(req: PerformActionRequest)⇒ Promise< T >

Sub-classes should use this to perform all built-in operations. All methods sanitizes and normalizes the values passed into this.

Sub-classes must override this.

<src>abstractProvider._recoverSubscriber(oldSub: Subscriber, newSub: Subscriber)⇒ void

If a Subscriber fails and needs to replace itself, this method may be used.

For example, this is used for providers when using the eth_getFilterChanges method, which can return null if state filters are not supported by the backend, allowing the Subscriber to swap in a PollingEventSubscriber.

<src>abstractProvider._setTimeout(func: () => void, timeout?: number)⇒ number

Create a timer that will execute func after at least timeout (in ms). If timeout is unspecified, then func will execute in the next event loop.

Pausing the provider will pause any associated timers.

<src>abstractProvider._wrapBlock(value: BlockParams, network: Network)⇒ Block

Provides the opportunity for a sub-class to wrap a block before returning it, to add additional properties or an alternate sub-class of Block.

<src>abstractProvider._wrapLog(value: LogParams, network: Network)⇒ Log

Provides the opportunity for a sub-class to wrap a log before returning it, to add additional properties or an alternate sub-class of Log.

<src>abstractProvider._wrapTransactionReceipt(value: TransactionReceiptParams, network: Network)⇒ TransactionReceipt

Provides the opportunity for a sub-class to wrap a transaction receipt before returning it, to add additional properties or an alternate sub-class of TransactionReceipt.

<src>abstractProvider._wrapTransactionResponse(tx: TransactionResponseParams, network: Network)⇒ TransactionResponse

Provides the opportunity for a sub-class to wrap a transaction response before returning it, to add additional properties or an alternate sub-class of TransactionResponse.

<src>abstractProvider.attachPlugin(plugin: AbstractProviderPlugin)⇒ this

Attach a new plug-in.

<src>abstractProvider.ccipReadFetch(tx: PerformActionTransaction, calldata: string, urls: Array< string >)⇒ Promise< null | string >

Resolves to the data for executing the CCIP-read operations.

<src>abstractProvider.destroy()⇒ void

Sub-classes may use this to shutdown any sockets or release their resources and reject any pending requests.

Sub-classes must call super.destroy().

<src>abstractProvider.getAvatar(name: string)⇒ Promise< null | string >

<src>abstractProvider.getPlugin(name: string)⇒ null | T

Get a plugin by name.

<src>abstractProvider.getResolver(name: string)⇒ Promise< null | EnsResolver >

<src>abstractProvider.pause(dropWhilePaused?: boolean)⇒ void

Pause the provider. If dropWhilePaused, any events that occur while paused are dropped, otherwise all events will be emitted once the provider is unpaused.

<src>abstractProvider.resume()⇒ void

Resume the provider.

interface AbstractProviderPlugin

An AbstractPlugin is used to provide additional internal services to an AbstractProvider without adding backwards-incompatible changes to method signatures or other internal and complex logic.

PROPERTIES

<src>abstractProviderPlugin.name⇒ stringread-only

The reverse domain notation of the plugin.

METHODS

<src>abstractProviderPlugin.connect(provider: AbstractProvider)⇒ AbstractProviderPlugin

Creates a new instance of the plugin, connected to provider.

class FilterIdEventSubscriber

inherits from FilterIdSubscriber, Subscriber

A FilterIdSubscriber for receiving contract events.

CREATING INSTANCES

<src>new FilterIdEventSubscriber(provider: JsonRpcApiProvider, filter: EventFilter)

Creates a new FilterIdEventSubscriber attached to provider listening for filter.

class FilterIdPendingSubscriber

inherits from FilterIdSubscriber, Subscriber

A FilterIdSubscriber for receiving pending transactions events.

class FilterIdSubscriber

inherits from Subscriber

Some backends support subscribing to events using a Filter ID.

When subscribing with this technique, the node issues a unique Filter ID. At this point the node dedicates resources to the filter, so that periodic calls to follow up on the Filter ID will receive any events since the last call.

CREATING INSTANCES

<src>new FilterIdSubscriber(provider: JsonRpcApiProvider)

Creates a new FilterIdSubscriber which will used _subscribe and _emitResults to setup the subscription and provide the event to the provider.

METHODS

<src>filterIdSubscriber._emitResults(provider: AbstractProvider, result: Array< any >)⇒ Promise< void >

Sub-classes must override this handle the events.

<src>filterIdSubscriber._recover(provider: AbstractProvider)⇒ Subscriber

Sub-classes must override this handle recovery on errors.

<src>filterIdSubscriber._subscribe(provider: JsonRpcApiProvider)⇒ Promise< string >

Sub-classes must override this to begin the subscription.

class OnBlockSubscriber

inherits from Subscriber

An OnBlockSubscriber can be sub-classed, with a _poll implmentation which will be called on every new block.

CREATING INSTANCES

<src>new OnBlockSubscriber(provider: AbstractProvider)

Create a new OnBlockSubscriber attached to provider.

METHODS

<src>onBlockSubscriber._poll(blockNumber: number, provider: AbstractProvider)⇒ Promise< void >

Called on every new block.

interface PerformActionTransaction

inherits from PreparedTransactionRequest

A normalized transactions used for PerformActionRequest objects.

PROPERTIES

<src>performActionTransaction.from⇒ string

The sender of the transaction.

<src>performActionTransaction.to⇒ string

The to address of the transaction.

class PollingBlockSubscriber

inherits from Subscriber

A PollingBlockSubscriber polls at a regular interval for a change in the block number.

PROPERTIES

<src>pollingBlockSubscriber.pollingInterval⇒ number

The polling interval.

CREATING INSTANCES

<src>new PollingBlockSubscriber(provider: AbstractProvider)

Create a new PollingBlockSubscriber attached to provider.

class PollingEventSubscriber

inherits from Subscriber

A PollingEventSubscriber will poll for a given filter for its logs.

CREATING INSTANCES

<src>new PollingEventSubscriber(provider: AbstractProvider, filter: EventFilter)

Create a new PollingTransactionSubscriber attached to provider, listening for filter.

class PollingTransactionSubscriber

inherits from OnBlockSubscriber, Subscriber

A PollingTransactionSubscriber will poll for a given transaction hash for its receipt.

CREATING INSTANCES

<src>new PollingTransactionSubscriber(provider: AbstractProvider, hash: string)

Create a new PollingTransactionSubscriber attached to provider, listening for hash.

interface Subscriber

A Subscriber manages a subscription.

Only developers sub-classing [[AbstractProvider[[ will care about this, if they are modifying a low-level feature of how subscriptions operate.

PROPERTIES

<src>subscriber.pollingInterval⇒ number

The frequency (in ms) to poll for events, if polling is used by the subscriber.

For non-polling subscribers, this must return undefined.

METHODS

<src>subscriber.pause(dropWhilePaused?: boolean)⇒ void

Called when the subscription should pause.

If dropWhilePaused, events that occur while paused should not be emitted resume.

<src>subscriber.resume()⇒ void

Resume a paused subscriber.

<src>subscriber.start()⇒ void

Called initially when a subscriber is added the first time.

<src>subscriber.stop()⇒ void

Called when there are no more subscribers to the event.

class UnmanagedSubscriber

inherits from Subscriber

An UnmanagedSubscriber is useful for events which do not require any additional management, such as "debug" which only requires emit in synchronous event loop triggered calls.

PROPERTIES

<src>unmanagedSubscriber.name⇒ string

The name fof the event.

CREATING INSTANCES

<src>new UnmanagedSubscriber(name: string)

Create a new UnmanagedSubscriber with name.

Socket Providers

Generic long-lived socket provider.

Sub-classing notes

a sub-class MUST call the `_start()` method once connected
a sub-class MUST override the `_write(string)` method
a sub-class MUST call `_processMessage(string)` for each message

class SocketBlockSubscriber

inherits from SocketSubscriber, Subscriber

A SocketBlockSubscriber listens for newHeads events and emits "block" events.

class SocketEventSubscriber

inherits from SocketSubscriber, Subscriber

A SocketEventSubscriber listens for event logs.

PROPERTIES

<src>socketEventSubscriber.logFilter⇒ EventFilterread-only

The filter.

class SocketPendingSubscriber

inherits from SocketSubscriber, Subscriber

A SocketPendingSubscriber listens for pending transacitons and emits "pending" events.

class SocketProvider

inherits from JsonRpcApiProvider, AbstractProvider

A SocketProvider is backed by a long-lived connection over a socket, which can subscribe and receive real-time messages over its communication channel.

CREATING INSTANCES

<src>new SocketProvider(network?: Networkish, options?: JsonRpcApiProviderOptions)

Creates a new SocketProvider connected to network.

If unspecified, the network will be discovered.

METHODS

<src>socketProvider._processMessage(message: string)⇒ Promise< void >

Sub-classes must call this with messages received over their transport to be processed and dispatched.

<src>socketProvider._register(filterId: number | string, subscriber: SocketSubscriber)⇒ void

Register a new subscriber. This is used internalled by Subscribers and generally is unecessary unless extending capabilities.

<src>socketProvider._write(message: string)⇒ Promise< void >

Sub-classes must override this to send message over their transport.

class SocketSubscriber

inherits from Subscriber

A SocketSubscriber uses a socket transport to handle events and should use _emit to manage the events.

PROPERTIES

<src>socketSubscriber.filter⇒ Array< any >read-only

The filter.

CREATING INSTANCES

<src>new SocketSubscriber(provider: SocketProvider, filter: Array< any >)

Creates a new SocketSubscriber attached to provider listening to filter.

METHODS

<src>socketSubscriber._emit(provider: SocketProvider, message: any)⇒ Promise< void >

Sub-classes must override this to emit the events on the provider.