Internals

This part is for a contributor changing blockwatcher’s own code: how the workspace’s crates are grouped and why, what each crate owns, how the test suite is layered, and the binding decisions those boundaries answer to. It assumes the concepts pages already, and reads the source alongside it.

flowchart LR
    rpc["RPC endpoints<br/>(external chains)"]
    sources["Sources<br/>evm-rpc · evm-mempool"]
    sinks["Sinks<br/>webhook · script · log"]
    storage["Storage<br/>checkpoints · dead letters · resources"]
    api["REST API"]
    metrics["Metrics"]
    engine["engine<br/>bounded channels · checkpoints"]

    subgraph pipeline["Engine pipeline"]
        direction LR
        decoder["Decoder"]
        matcher["Matcher<br/>predicates"]
        gate["Gate<br/>threshold · max_once"]
        decoder --> matcher
        matcher --> gate
    end

    rpc --> sources
    sources -->|"decode and match"| decoder
    gate --> sinks
    api -->|"manages resources"| storage
    storage <--> engine
    engine -->|"drives"| pipeline
    engine -.->|"reports"| metrics

    classDef module fill:none,stroke:#a9a3e3
    classDef core fill:none,stroke:#8a8d86,stroke-dasharray: 5 5

    class rpc,sources,sinks,decoder,matcher,gate module
    class engine,api,storage,metrics core
click sources "../concepts/selectors.html"
click decoder "../concepts/chain-agnosticism.html"
click matcher "../concepts/predicates.html"
click gate "../concepts/gates.html"
click sinks "../concepts/delivery.html"
click storage "../concepts/resources.html"
click api "../reference/http-api.html"
click metrics "../reference/observability.html"
click engine "../concepts/pipeline.html"

Key takeaways

• This part is for a contributor changing blockwatcher’s own code, and assumes the concepts pages already.

• The workspace map explains how crates are grouped by role and how they depend on each other.

• Testing strategy and architecture decisions describe how the test suite is layered and which decisions are binding.

• Extending blockwatcher walks a new module through the whole process end to end.

• Workspace map: the crates, grouped by role, with their dependency edges.

• Testing strategy: the layers of tests and what each one proves.

• Extending blockwatcher: the mechanical steps a new module goes through, worked through a real one end to end.

• Architecture decisions: the binding decisions restated from the contributor rulebook.

• The trust boundary (API scopes, companion login, ingest header) lives in the repository’s docs/threat-model.md, next to SECURITY.md.