Necrotizing Pineapple Music

    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




    npm i mycrypto-shepherd

    DownloadsWeekly Downloads






    Unpacked Size

    707 kB

    Total Files


    Last publish


    • mycrypto-admin