Skip to content

security: Add Independent RPC Evidence Quorum for Chain State Reads (… - #1227

Merged
Mosas2000 merged 1 commit into
StellaBridge:mainfrom
DevNetlife:security/rpc-evidence-quorum-1014
Aug 29, 2026
Merged

security: Add Independent RPC Evidence Quorum for Chain State Reads (…#1227
Mosas2000 merged 1 commit into
StellaBridge:mainfrom
DevNetlife:security/rpc-evidence-quorum-1014

Conversation

@DevNetlife

@DevNetlife DevNetlife commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

PR Description for Closes #1014

## Security: Add Independent RPC Evidence Quorum for Chain State Reads (#1014)

## Description
Adds an **Independent RPC Evidence Quorum** engine for critical chain state reads (#1014). Provider failover changes endpoints on connection errors but cannot detect lagging or malicious providers feeding plausible but inconsistent data. This feature anchors chain state reads with header evidence across independently grouped provider endpoints to detect disagreement, compute degraded confidence scores, and enforce explicit fail-open/fail-closed policies.

## Key Changes
- **Data Model & Persistence**: Added Knex migration `20260829000001_rpc_evidence_quorum.ts` creating `rpc_evidence_quorum_configs`, `rpc_provider_groups`, and `rpc_evidence_logs`.
- **Service Behavior (`RpcEvidenceQuorumService`)**:
  - **Header Anchoring**: Includes `blockNumber`, `blockHash`, `stateRoot`, and `timestamp` header evidence to anchor contract reads and reserve calculations.
  - **Correlated Provider Grouping**: Groups provider endpoints by `providerGroup` / ASN (e.g., Infura, Alchemy, QuickNode, self-hosted) so multiple nodes under the same provider infrastructure do not bias the quorum vote.
  - **Lag & Disagreement Classification**: Identifies providers lagging beyond `maxLagBlocks` relative to chain tip or returning divergent block hashes/data values.
  - **Degraded Confidence Scoring**: Computes a dynamic confidence score (0.0 to 1.0) and persists evidence in `rpc_evidence_logs` rather than hiding provider disagreement behind silent retries.
  - **Configurable Policies**: Per-chain and per-operation thresholds (`minQuorumSize`, `quorumThresholdRatio`, `maxLagBlocks`, `failClosed`).
  - **Prometheus Metrics**: Exports `bridge_watch_rpc_quorum_evaluations_total`, `bridge_watch_rpc_quorum_disagreements_total`, and `bridge_watch_rpc_quorum_confidence_score`.
- **API Surface**: Added REST endpoints under `/api/v1/rpc-quorum`:
  - `POST /verify` — Perform multi-provider evidence quorum evaluation
  - `GET /configs` & `POST /configs` — View and configure chain/operation quorum thresholds
  - `GET /logs` — Retrieve historical verification logs and disagreement details
  - `POST /provider-groups` — Map RPC endpoint URLs to independent provider groups
- **Integration**: Integrated header evidence anchoring into `CrossChainStateVerificationService`.
- **Documentation & Tests**:
  - Created security architecture guide in `docs/RPC_EVIDENCE_QUORUM.md`.
  - Added unit and route integration tests in `rpcEvidenceQuorum.service.test.ts` and `rpcEvidenceQuorum.routes.test.ts`.

## Acceptance Criteria Verification
- [x] Critical reads include header evidence used to anchor them.
- [x] Disagreement is persisted and exposed as degraded confidence score.
- [x] Quorum thresholds are configurable per chain and operation.
- [x] Correlated endpoints are grouped so they do not count as independent.
- [x] Fail-open vs fail-closed behavior is explicit for each caller/policy.

## How to Test
```bash
npm run test --workspace=backend -- rpcEvidenceQuorum

@Mosas2000

Copy link
Copy Markdown
Contributor

Enforcing independent RPC quorums with correlated provider grouping is a brilliant defense-in-depth measure against compromised or lagging endpoints, the implementation is robust, thoroughly tested, and provides excellent auditability through the new evidence logs. Thank you.

@Mosas2000
Mosas2000 merged commit 28d5ef6 into StellaBridge:main Aug 29, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

security: Add Independent RPC Evidence Quorum for Chain State Reads

2 participants