engine.example.toml

# Annotated engine config template for `shepherd`.
#
# This file describes the engine: its state directory, its RPC endpoints,
# the modules it loads, and the CoW venue. A module's own manifest is its
# `component.toml`.
#
# Copy this file to `engine.toml`, which git ignores, and run
# `shepherd --engine-config engine.toml`. See docs/deployment.md.
#
# Keep an RPC URL that holds a key out of this file. Write a token of the
# form dollar-brace-NAME-brace as the value, as `[chains.1]` does below,
# and the engine replaces it with the environment variable of that name
# when it loads the file. A variable that is not set stops the boot.

[engine]
state_dir = "./data"
log_level = "info"
# Every [[modules]] entry must carry a `digest` pin, verified against the
# bytes handed to the compiler. Produce one with `shepherd digest <path>`.
# Set false only for a dev config where the artifact is rebuilt each run.
# require_component_digest = true

# Operator resource ceilings, applied per component. Every field is
# optional; omitted values resolve to built-in defaults (1B fuel per
# dispatch, 64 MiB memory).
[policy]
# max_fuel_per_dispatch = 1_000_000_000
# max_memory_bytes      = 67_108_864
# max_state_bytes       = 268_435_456

# Per-component narrowing of the ceilings above, keyed on the
# `[[modules]].id` the operator wrote. `http_allow` is the outbound
# wasi:http host allowlist for that component; it does not reach a venue,
# which is native code inside the binary.
# [policy.component.ccow-monitor]
# http_allow = ["api.cow.fi"]

# Outbound wasi:http limits. The *_max_ms values are ceilings on the
# guest-settable request-options timeouts: values above a ceiling are
# clamped down, unset ones inherit it. total_deadline_ms bounds one
# whole exchange (connect through body streaming); a response body
# beyond response_body_max_bytes fails with HTTP-response-body-size.
# Millisecond values saturate into [1 ms, 24 h].
[limits.http]
# connect_timeout_max_ms       = 10_000
# first_byte_timeout_max_ms    = 30_000
# between_bytes_timeout_max_ms = 30_000
# total_deadline_ms            = 60_000
# response_body_max_bytes      = 16_777_216

# Chain JSON-RPC response size cap, applied host-side before a response
# is copied into guest memory. A single response - and the aggregate of
# one request-batch - beyond the cap fails with a typed invalid-input
# fault instead of inflating the module toward its max_memory_bytes limit.
# Modules that need more data per call should paginate (block-range
# chunking, request-batch). 0 saturates to 1. Default 1 MiB.
[limits.chain]
# response_body_max_bytes = 1_048_576

# Per-run log retention. bytes_per_run is the byte budget for one run's
# in-memory ring (oldest records evict first, the newest is never evicted
# to nothing); runs_retained is how many past runs are kept per module.
# Both saturate up to 1 if set to 0.
[limits.logs]
# bytes_per_run  = 262_144
# runs_retained  = 16

# Poison-pill quarantine thresholds. A module that reaches max_failures
# traps within a sliding window_secs is quarantined (the check fires at
# the threshold, not one past it): the supervisor stops dispatching to it
# until an engine restart clears the state. Both saturate up to 1 if set
# to 0.
[limits.poison]
# max_failures = 5
# window_secs  = 600

# One [chains.<id>] table for each chain that a module trigger names. The
# key is the decimal chain id. The shipped modules read chain 1 only.
#
# A ws:// or wss:// URL receives new blocks by subscription. An http:// or
# https:// URL polls.
#
# Optional keys:
#   request_timeout_secs = 30      the timeout of one JSON-RPC request
#   max_log_range_blocks = 1000    the largest eth_getLogs block range

[chains.1]
rpc_url = "${MAINNET_RPC_URL}"

# ---- modules ----
#
# One entry for each module. `id` is the name you give the module, and it
# is the key of a `[policy.component.<id>]` table. `digest` is mandatory
# unless `[engine] require_component_digest` is false. Get it from
# `shepherd digest <path>`.

# [[modules]]
# id = "ccow-monitor"
# path = "target/wasm32-wasip2/release/ccow_monitor.wasm"
# manifest = "modules/ccow-monitor/component.toml"
# digest = "sha256:<64 hex chars>"

# [[modules]]
# id = "ethflow-watcher"
# path = "target/wasm32-wasip2/release/ethflow_watcher.wasm"
# manifest = "modules/ethflow-watcher/component.toml"
# digest = "sha256:<64 hex chars>"

# ---- venue ----
#
# The CoW venue is native code in the `shepherd` binary. `cow` is the only
# venue id that the binary links.
#
#   chain          required: a decimal chain id or an orderbook slug
#   orderbook_url  optional: a different orderbook base URL
#   owner          optional: the address for the pre-sign submit path
#   timeout_ms     optional: the time limit of one orderbook request
#
# Set `chain` to the chain that the modules read. Without this table the
# engine registers no venue, and a module that declares
# `[venue] body_version` refuses to boot.

# [extensions.videre.venues.cow]
# chain = 1