Guides & reference

This part covers running and operating a deployed instance: the configuration surface, the HTTP API and observability endpoints, a Docker deployment, two fully worked examples, a symptom-first troubleshooting index, and a benchmark baseline. It is for an operator or integrator working against a running blockwatcher, not for someone deciding whether to adopt 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
classDef dim fill:none,stroke:#999999,color:#999999,opacity:0.35
classDef focus fill:#ffd43b,stroke:#d9480f,stroke-width:3px,color:#1a1a1a
class rpc,sources,sinks,storage,engine,decoder,matcher,gate dim
class api,metrics focus
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 "http-api.html"
click metrics "observability.html"
click engine "../concepts/pipeline.html"

Key takeaways

• This part is for operating a running deployment, not for deciding whether to adopt blockwatcher.

• Configuration and the HTTP API cover how an instance is configured and controlled; observability covers how to watch it run.

• The two worked examples build the same monitor against confirmed blocks and against pending transactions.

• Troubleshooting indexes failure modes by symptom rather than by component.

• Configuration: the instance configuration file and its environment overrides.

• Resource reference: every resource kind’s fields, defaults, and write-time refusals, one page per kind.

• HTTP API: the REST control plane.

• Observability: the status endpoint and the Prometheus metrics.

• Running with Docker: the Compose stack and its own configuration.

• Monitoring ERC-20 transfers [RPC]: a worked example against confirmed blocks.

• Monitoring ERC-20 transfers [Mempool]: the same example against pending transactions instead.

• Troubleshooting: a symptom-first index into failure modes and their fixes.

• Benchmarks: what’s measured, how to reproduce it, and the baseline results.