TypeScript icon, indicating that this package has built-in type declarations

1.4.0 • Public • Published

Coverage Status Build Status code style: prettier

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.


npm i mycrypto-shepherd


Find examples here on how to get started with Shepherd

Shepherd API


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

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 'ETH' Optional
  • 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

Name Type Description
providerName string
Provider IProviderContructor The provider implementation to store for later usage
  • Void


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

  • 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

Name Type Description
providerId string
skipOfflineCheck boolean Will not fail and throw an error if the manual provider switched to is offline
  • 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

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
  • Void


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.

Name Type Description
network string
  • Promise.<undefined> Resolves when the network is finished being switched to


Enables logging for the library

  • Void


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.


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.


DEV_TOOLS=true yarn test




Package Sidebar


npm i mycrypto-shepherd

Weekly Downloads






Unpacked Size

707 kB

Total Files


Last publish


  • mycrypto-admin