Skip to main content

State Sourcing and Caching

Home · Generic Index · Chain Overlays

The sidecar can pull state from multiple sources. This document covers the state pipeline implemented in credible-sdk/crates/state-worker and credible-sdk/crates/state-store.

State Pipeline​

Components​

  • State Worker (credible-sdk/crates/state-worker):

    • Subscribes to newHeads via WebSocket.
    • Uses trace_replayBlockTransactions (Parity) or debug_traceBlockByHash/Number (Geth) to collect state diffs.
    • Writes block state updates to MDBX in a revm::DatabaseRef-compatible format.
    • Loads genesis from file during startup to seed the state cache before processing blocks.

  • State Store (credible-sdk/crates/state-store):

    • MDBX backing store + Redis support.
    • Provides read/write interfaces used by state-worker and sidecar.

  • Sidecar State Sources (credible-sdk/crates/sidecar/src/cache/sources):

    • MdbxSource: reads cached state from MDBX.
    • EthRpcSource: fallback state reader from RPC.
    • Both sources are composed via Sources with an overlay cache for execution.

Operational Notes​

  • The sidecar can operate with either or both state sources; configuration decides if MDBX and/or RPC are enabled.
  • state-checker (see docs/generic/supporting-tools.md) validates cached state roots against block metadata.

State Worker Startup​