Consensus

How consensus works

1. Send the request to up to maxParticipants healthy upstreams in parallel; group identical results.
2. If any valid group meets agreementThreshold, it wins.
3. If no winner, apply behaviors: low participants → lowParticipantsBehavior; otherwise → disputeBehavior.
4. Preferences (preferNonEmpty, preferLargerResponses, preferHighestValueFor) may override selection in specific contexts.
5. Ties without preferences → dispute.
6. All upstreams return identical error → return that error; otherwise return a low-participants error.

Performance note: consensus increases costs and latency since it waits for multiple responses. Use it selectively for critical workloads rather than all methods.

ConsensusPolicyConfig — every field

disputeBehavior values

The block head leader is the upstream reporting the highest block number, determined by each upstream's state poller.

lowParticipantsBehavior values

Same set of values as disputeBehavior, with one addition:

Tag-based participant quotas (requiredParticipants)

By default consensus fills its maxParticipants slots with the first N healthy upstreams by score. requiredParticipants adds a per-tag floor on top of that: each entry says "at least minParticipants of the participants must carry tag". Use it for diversity guarantees — e.g. always include a node from a second region or a second provider in every consensus round.

The engine front-loads enough tag-matching upstreams into the participant set so the first maxParticipants drawn satisfy every entry. It does not change maxParticipants, and it leaves the order of non-required participants (their score ranking) intact — only set membership matters for voting.

consensus:
  maxParticipants: 3
  agreementThreshold: 2
  requiredParticipants:
    - tag: "region:us-*"   # glob; matched against each upstream's tags
      minParticipants: 1   # ≥1 US participant every round
    - tag: "provider:quicknode"
      minParticipants: 1   # ≥1 QuickNode participant every round

Tag the upstreams accordingly:

upstreams:
  - id: alchemy-us
    tags: [region:us-east, provider:alchemy]
  - id: quicknode-eu
    tags: [region:eu-west, provider:quicknode]
  # ...

Semantics:

• Off by default — omit requiredParticipants and consensus behaves exactly as before.
• Best-effort — if a required group has fewer healthy upstreams than minParticipants (or the quotas can't all fit within maxParticipants), consensus runs with what it can promote and the resulting participation is handled by your existing lowParticipantsBehavior / agreementThreshold — exactly like any organic low-participation round. No new failure mode is introduced.
• Healthy-only — quotas are satisfied from the upstreams already eligible for this request (post selection-policy filtering), so a cordoned or excluded upstream is never forced in.
• tag is a glob pattern (*, ?); a single upstream can satisfy multiple entries it matches.

preferNonEmpty semantics

Prioritizes meaningful data over empty responses, and empty over errors:

• Above threshold: if both a non-empty and a consensus-valid error group meet threshold, pick the best non-empty (by count, then size).
• Below threshold: with exactly one non-empty and at least one empty, pick the non-empty.
• Prevents short-circuiting to empty or consensus-error when a non-empty result may still arrive.

preferLargerResponses semantics

• Below threshold with acceptMostCommonValidResult: choose the largest non-empty.
• Above threshold with multiple valid groups: choose the largest non-empty.
• If a smaller non-empty meets threshold but a larger non-empty exists:
  • acceptMostCommonValidResult → choose the largest.
  • returnError → dispute (don't accept the smaller).

Tail-latency caps (maxWaitOnResult / maxWaitOnEmpty)

When one participant is consistently slow — e.g. a 10 s archive query while siblings return in 50 ms — that single laggard drags the whole request's wall-clock. The wait caps bound this after the first response arrives:

When the cap fires, the analyzer resolves with what it has using the configured disputeBehavior / lowParticipantsBehavior. In-flight participants are cancelled (or left running under fireAndForget). The earlier of the two caps wins.

Defaults (applied whenever consensus is configured):

The quantiles read from the same per-method DDSketch the timeout policy uses. Adaptive caps self-tune across methods — eth_chainId (typical p50 ~5ms) gets a tight cap; eth_getLogs over a wide range (typical p50 ~200ms) gets a proportional one.

Static overrides when you'd rather not adapt:

consensus:
  maxParticipants:    5
  agreementThreshold: 3
  maxWaitOnResult:    200ms     # static: scalar shorthand
  maxWaitOnEmpty:     2s        # static: scalar shorthand

Custom adaptive bounds:

consensus:
  maxParticipants:    5
  agreementThreshold: 3
  maxWaitOnResult:
    quantile: 0.5
    min:      10ms
    max:      500ms
  maxWaitOnEmpty:
    quantile: 0.9
    min:      100ms
    max:      3s

The erpc_consensus_wait_capped_total{trigger} metric counts firings by trigger (result or empty); a high rate signals an upstream that should be tightened or dropped from the pool.

ignoreFields — matcher syntax

ignoreFields is a map of JSON-RPC method name → list of dot-path field patterns to exclude from canonical hash comparison. Useful for fields that legitimately differ across upstreams (timestamps, chain-specific extras).

Dot-path syntax:

• fieldName — top-level field
• a.b.c — nested path
• *.fieldName — wildcard at any array index (e.g. *.blockTimestamp in an array of receipts)
• transactions.*.gasPrice — field inside every element of a nested array

Example — real-world safe-to-ignore fields:

ignoreFields:
  eth_getLogs:
    - "*.blockTimestamp"
  eth_getTransactionReceipt:
    - "blockTimestamp"
    - "logs.*.blockTimestamp"
    - "l1Fee"
    - "l1GasPrice"
    - "l1GasUsed"
    - "gasUsedForL1"
    - "timeboosted"
    - "l1BlockNumber"
  eth_getBlockByHash:
    - "requestsHash"
    - "transactions.*.gasPrice"
    - "transactions.*.accessList"
    - "transactions.*.chainId"
    - "transactions.*.l1Fee"
    - "transactions.*.yParity"
    - "transactions.*.isSystemTx"
    - "transactions.*.depositReceiptVersion"
  eth_getBlockByNumber:
    - "requestsHash"
    - "transactions.*.gasPrice"
    - "transactions.*.accessList"
    - "transactions.*.chainId"
    - "transactions.*.l1Fee"
    - "transactions.*.yParity"
    - "transactions.*.isSystemTx"
    - "transactions.*.depositReceiptVersion"
  eth_getBlockReceipts:
    - "*.blockTimestamp"
    - "*.l1Fee"
    - "*.l1GasPrice"
    - "*.l1GasUsed"
    - "*.logs.*.blockTimestamp"

PunishMisbehaviorConfig — every field

MisbehaviorsDestinationConfig — every field

filePattern placeholders:

Notes:

• File writes use atomic append. Use external rotation for large volumes.
• S3 uploads are buffered and flushed by record count, byte size, or time interval.
• Each record is a JSONL line containing: full JSON-RPC request, all participant responses or errors, analysis summary, winner, and policy snapshot. No truncation.

S3FlushConfig — every field

S3 credentials modes:

The same AwsAuthConfig block is used for DynamoDB cache credentials — see the DynamoDB driver reference for worked examples with each mode.

Common pitfalls

• agreementThreshold too low — agreementThreshold: 1 means any single upstream wins, which defeats the purpose of consensus entirely (equivalent to no consensus). Use at least maxParticipants/2 + 1 for majority voting.
• ignoreFields too aggressive — ignoring structural fields like blockHash or transactionIndex can mask real disagreements. Only ignore fields you have verified are non-deterministic across correct nodes.
• S3 costs at high dispute rates — if many methods dispute frequently, misbehavior logging can generate substantial S3 traffic. Start with file type and switch to S3 after validating dispute volume.
• disputeBehavior: returnError in production — this surfaces disputes as errors to clients, which can cause retries and amplify load. Prefer acceptMostCommonValidResult unless you specifically need strict failure signaling.
• fireAndForget: true on read methods — designed for broadcast writes. On read methods, it causes unnecessary in-flight requests that consume upstream quota without benefiting the client.
• Forgetting to scale maxParticipants with upstream count — if you have only 2 upstreams but set maxParticipants: 3, the policy silently proceeds with 2 and requires both to agree (or triggers lowParticipantsBehavior).
• punishMisbehavior with a very short disputeWindow — a 1-second window combined with a low disputeThreshold can cause flapping. Use windows of minutes and thresholds of 10+ for production.

Real-world examples

Multi-chain correctness check — require majority agreement:

failsafe:
  - matchMethod: "eth_call|eth_getBalance|eth_getLogs"
    consensus:
      maxParticipants: 3
      agreementThreshold: 2
      disputeBehavior: acceptMostCommonValidResult
      preferNonEmpty: true
      ignoreFields:
        eth_getLogs: ["*.blockTimestamp"]
      punishMisbehavior:
        disputeThreshold: 5
        disputeWindow: 5m
        sitOutPenalty: 15m

Archive node — accept best available when data is sparse:

failsafe:
  - matchMethod: "eth_getBlockByNumber|eth_getBlockByHash"
    consensus:
      maxParticipants: 2
      agreementThreshold: 1
      disputeBehavior: preferBlockHeadLeader
      ignoreFields:
        eth_getBlockByNumber:
          - "requestsHash"
          - "transactions.*.accessList"

Transaction pipeline — nonce, gas, broadcast:

See the transaction inclusion example at the top of this page.