RPC endpoints and failover

Client accepts one Blurt RPC endpoint or an ordered endpoint list. Use this guide when your application needs resilient blockchain queries or broadcast operations across node outages, timeouts or temporary endpoint failures.

Endpoint strategy is application policy. The SDK provides timeout and failover behavior, but your application still decides which endpoints are trusted and how much retry behavior is acceptable.

Configure an endpoint list

import { Client } from '@beblurt/dblurt';

const client = new Client([
    'https://rpc.blurt.blog',
    'https://rpc.beblurt.com',
    'https://blurt-rpc.saboin.com'
], {
    timeout: 15_000,
    failoverThreshold: 3,
    consoleOnFailover: true
});

Use multiple endpoints when your application should survive one node being unavailable. Keep the list ordered by your trust and reliability preference.

What failover does

The currently validated behavior includes:

• the first healthy endpoint remains sticky across repeated successful calls;
• timeout failures can move the client to the next endpoint;
• client.currentAddress reflects the active endpoint;
• timeout: 0 remains a compatibility-sensitive no-immediate-timeout path on healthy local endpoints;
• FC-style JSON-RPC application errors map to the public RPCError shape;
• JSON-RPC responses with mismatched ids are rejected.

Do not assume every HTTP status, timeout or JSON-RPC application error should be retried the same way. Broadcast operations need stricter handling than ordinary blockchain queries.

Client options

Option	Default owner	Use it for
timeout	SDK default; see API details	Bounding a single RPC request.
failoverThreshold	SDK default; see API details	Limiting retry/failover rounds.
consoleOnFailover	SDK default; see API details	Debugging endpoint switching during development.
backoff	SDK transport behavior	Custom retry delay calculation.
chainId	Blurt mainnet default	Non-mainnet or custom-chain use.
addressPrefix	Blurt mainnet default	Non-mainnet or custom-prefix use.

Exact defaults and option types belong to the API reference, not this guide.

Query retries vs broadcast retries

Blockchain queries can often be retried with bounded backoff because they do not submit a transaction.

Broadcast operations are different. A timeout after submission can be ambiguous: the transaction may have been accepted, rejected, still propagating or never received.

Use this policy:

Workflow	Retry guidance
Blockchain query	Bounded retry/failover is usually reasonable.
Local operation builder	Retry is not relevant; fix the input.
Broadcast operation	Do not blindly retry; preserve local transaction context and reconcile status.

See Broadcast safely before retrying broadcast operations.

Endpoint trust

RPC endpoints can affect what your application sees. A malicious, stale or misconfigured endpoint can:

• return stale chain state;
• fail selectively;
• delay responses;
• influence reference data used when preparing transactions;
• cause confusing UX around account balances, votes or broadcast status.

Use trusted HTTPS endpoints in production. Server-side applications should not accept arbitrary user-provided RPC URLs without allowlisting and network egress controls.

Browser considerations

Browser clients also depend on CORS, network reachability and the user environment. An endpoint that works in Node.js may not be usable from a browser page.

For browser apps:

• prefer endpoints known to support browser requests;
• set reasonable timeouts;
• show users when endpoint failover occurs only if it helps them act;
• avoid handling private keys in browser code unless your threat model supports it.

See Runtime and browser.

Operational monitoring

For node health monitoring outside the SDK, see the Blurt node checker:

https://gitlab.com/beblurt/blurt-nodes-checker

Operational monitoring can inform endpoint lists, but the SDK does not automatically choose endpoints from that project.

Example: bounded query with failover

const props = await client.condenser.getDynamicGlobalProperties();

console.log({
    endpoint: client.currentAddress,
    head: props.head_block_number,
    irreversible: props.last_irreversible_block_num
});

This confirms which endpoint served the query and what chain state it reported.

Related docs

• Read chain data
• Handle errors
• Broadcast safely
• Runtime and browser
• Security policy

API details

Use the API reference for exact option names, default behavior and types:

• Client
• ClientOptions
• classifyError