​
Default behavior

If you omit the relay parameter, Nexus will default to cycling requests between providers. The default maxAttempts is 3, and the default order is sequential. This means that Nexus will send requests to the first provider in the list, and if it fails, it will try the next provider, and so on. If all providers fail, Nexus will return an error response.

// this first example is equivalent to the second example below
const nexus = Nexus.create({
  nodeProviders: [alchemyProvider, infuraProvider],
  //...
});

// this second example is equivalent to the first example above
const nexus = Nexus.create({
  nodeProviders: [alchemyProvider, infuraProvider],
  relay: {
    failure: {
      kind: "cycle-requests",
      maxAttempts: 3,
    },
    order: "sequential",
  },
  //...
});

​
Request cycling

If you configure Nexus with multiple providers that support the same chain, Nexus will by default cycle requests between them. If a request to one provider fails, Nexus will try the next provider in the list. This is useful for load balancing and failovers. You can configure this behavior through the relay parameter.

const nexus = Nexus.create({
  nodeProviders: [alchemyProvider, infuraProvider],
  relay: {
    failure: {
      kind: "cycle-requests",
      maxAttempts: 3,
    },
  },
  //...
});

​
Disabling request cycling

If you want to disable request cycling, you can set the failure.kind parameter to fail-immediately. This will cause Nexus to send requests to the first provider in the list, and if it fails, Nexus will return an error response.

const nexus = Nexus.create({
  nodeProviders: [alchemyProvider, infuraProvider],
  relay: {
    failure: {
      kind: "fail-immediately",
    },
  },
  //...
});

​
Load balancing

If you want to load balance requests between providers, you can set the order parameter to random. This will cause Nexus to send requests to a random provider in the list. This setting also impacts failure recovery. When failure.kind is set to cycle-requests, Nexus will cycle requests between providers in random order. Load balancing weights can be configured at the NodeProvider level.

const llamaRpcNodeProvider = new NodeProvider({
  name: "llama-rpc",
  chain: CHAIN.ETHEREUM_MAINNET,
  url: "https://eth.llamarpc.com",
  weight: 3, // 30% of requests will go to this provider
});

const tenderlyNodeProvider = new NodeProvider({
  name: "tenderly",
  chain: CHAIN.ETHEREUM_MAINNET,
  url: "https://gateway.tenderly.co/public/mainnet",
  weight: 7 // 70% of requests will go to this provider
});

const nexus = Nexus.create<FastifyContext>({
  nodeProviders: [llamaRpcNodeProvider, tenderlyNodeProvider],
  relay: {
    order: "random",
    failure: {
      kind: "cycle-requests",
      maxAttempts: 3,
    },
  },
});

Was this page helpful?

Suggest edits