Internals

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

flowchart LR
    rpc["RPC endpoints<br/>(external chains)"]
    %% Source modules are family-owned; the running list is GET /catalog, not this map.
    sources["Sources<br/>one per network"]
    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.

• Architecture decisions are invariants of the system. Conventions are invariants of a change. Neither page is a copy of the other.

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

• Testing strategy describes how the test suite is layered. Extending blockwatcher walks a new module through the whole process end to end.

• Conventions: what a pull request must not forget.

• 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 system invariants the workspace is shaped to keep.

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