Alpha Software

Ensure high-availability for your JSON-RPC calls while improving user-experience. Shepherd automatically cancels calls that are taking too long to respond and executes them against fresh provider infrastructure. Shepherd is incredibly configurable — you can set filters on provider infrastructure to ensure that sensitive JSON-RPC calls are contained, dynamically bias against poorly performing provider infrastructure, and more!

Shepherd is built to have high configurability for users.

Installation

npm i aux-shepherd

Examples

Find examples here on how to get started with Shepherd

Shepherd API

init()

Initializes the balancer, returning a single instance of a provider to be used across your application

Parameters

| Name | Type | Description | | | -------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | { customProviders, ...config }={} | IInitConfig | Initialization configuration parameter, custom providers are your own supplied implementations that adhere to the {IProvider} interface. The {providerCallRetryThreshold} determines how many times a provider can fail a call before its determined to be offline. The {network} is what network the balancer will initialize to, defaulting to 'AUX' | Optional |

Returns

• Promise.<IProvider> A provider instance to be used for making rpc calls

addProvider(providerName, Provider)

Adds a custom Provider implementation to be later used and instantiated by useProvider. This library comes with default Provider implementations of 'rpc' 'etherscan' 'infura' 'web3' 'myccustom' already availble for use in useProvider. This method can be used before init

Parameters

| Name | Type | Description | | ------------ | --------------------- | ---------------------------------------------------- | | providerName | string | | | Provider | IProviderContructor | The provider implementation to store for later usage |

Returns

• Void

auto()

Switches the balancer back to "auto" mode. This is the default mode of the balancer. If the balancer was previously in "manual" mode, this will now instead change it back to normal behaviour, which means balancing between all available providers of the current network

Returns

• Void

manual(providerId, skipOfflineCheck)

Switches the balancer to "manual" mode. This will switch the balancer's current network to the manual providers network if it is different, then route all requests to the provider. This method can be used before init

Parameters

| Name | Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------ | | providerId | string | | | skipOfflineCheck | boolean | Will not fail and throw an error if the manual provider switched to is offline |

Returns

• Promise.<string> Resolves when the manual provider has successfully been switched to, returns a promise containing the provider ID switched to

useProvider(providerName, instanceName, config, args)

Add a provider instance to the balancer to be used for incoming rpc calls, this is distinctly different from addProvider, as addProvider does not add any providers to be used for incoming calls. All addProvider does is add a custom implementation to the pool of default implementations that you can specify in this method to be used and have instances created from. This method can be used before init

Parameters

| Name | Type | Description | | ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | providerName | string | The name of the Provider implementation to use as previously defined in either init (as customProviders), or addProvider, or one of the default implementations supplied: 'rpc' 'etherscan' 'infura' 'web3' 'myccustom' | | instanceName | string | The unique name of the instance to be used | | config | IProviderConfig | | | args | Array.<any> | The constructor arguments to be supplied to the specifed Provider constructor |

Returns

• Void

switchNetworks(network)

Switch the network for the balancer to use, all provider instances added by useProvider that match the same network to be swiched to will be used. Can not be used when the balancer is in manual mode, switch to auto mode first.

Parameters

| Name | Type | Description | | ------- | -------- | ----------- | | network | string | |

Returns

• Promise.<undefined> Resolves when the network is finished being switched to

enableLogging()

Enables logging for the library

Returns

• Void

IProviderConfig

| Name | Type | Description | | ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | concurrency | string | The maximum number of concurrent calls to make to the provider instance using this config. This number determines how many workers to spawn to process incoming rpc requests | | requestFailureThreshold | string | The threshold of failed calls before deeming a provider to be offline (which means it will no longer have rpc calls routed to it), which will then be polled until it responds. If it responds, it will be changed to an online state and continue to have applicable calls as outlined in supportedMethods routed to it | | timeoutThresholdMs | string | How long to wait on an rpc call (also applies to the initial ping to determine if a provider is online) before determining that it has timed out | | supportedMethods | string | All supported rpc methods by this provider config, disable a method for a config by setting it to false, this will prevent any rpc calls set to false to be routed to the provider instance using this config | | network | string | The associated network name of this provider config to be used by the balancer when switching networks | | storeRoot | string | The root the shepherd rootReducer when using a custom store. E.g If the top level is { foo, shepherdReducer } then storeRoot would be shepherdReducer. Note that this setting only supports one level of nesting | | store | Store<any> | The custom store to use if you want to use your own, make sure to supply the setting above too or else it will not work. | | queueTimeout | number | Timeout based on when there are pending calls that have not been assigned to a worker. The most common case of this happening is when the balancer is offline and there's calls to the balancer still happening. |

FAQ

Timeout behavior

The tracking of timeouts is currently started when a request is made to a provider, not when the request is initially received to the balancer. If a call to the balancer times out before being processed by a worker, the entire queue is flushed.

Node balancer status

When the set of all online provider's rpc methods is a proper subset of the set of all available rpc methods (globally set), the balancer is set to a state of offline All pending and incoming requests remain queued until either: a) the network switches b) the balancer comes back online (if it takes too long, as set by queueTimeout, the pending calls are flushed and cancelled, returning as a promise rejection to the user)

requestFailureThreshold vs providerCallRetryThreshold

providerCallRetryThreshold determines how many times a provider can fail a call before its determined to be offline, while a request failure threshold is how many times a specific call can be retried before it fails. In the context of a single request failing with both providerCallRetryThreshold and request failure threshold being set to the same number, the provider will be set offline one iteration before providerCallRetryThreshold would take effect, because one keeps track of failures, while the other keeps track of retries.

Enabling redux dev tools for debugging

Run the package with the environment variable DEV_TOOLS set.

Example

DEV_TOOLS=true yarn test