engine.example.toml

# Engine-side runtime configuration for `nexum`.
#
# Distinct from `module.toml` (per-module manifest): this file
# describes the *engine*'s I/O wiring. Copy to `engine.toml` next to
# the binary, or pass the path as the third positional argument.
#
# ## Secrets workflow
#
# Paid RPC URLs (Alchemy / drpc / Infura / QuickNode keys) live in
# environment variables, not in this file. The engine substitutes
# `${VAR_NAME}` tokens at load time:
#
#   export MAINNET_RPC_URL=wss://eth-mainnet.g.alchemy.com/v2/<KEY>
#   export GNOSIS_RPC_URL=wss://gnosis-mainnet.g.alchemy.com/v2/<KEY>
#   export SEPOLIA_RPC_URL=wss://eth-sepolia.g.alchemy.com/v2/<KEY>
#   export ARBITRUM_RPC_URL=wss://arb-mainnet.g.alchemy.com/v2/<KEY>
#   export BASE_RPC_URL=wss://base-mainnet.g.alchemy.com/v2/<KEY>
#
# The Docker compose path picks these up from a gitignored `.env`
# file at the repo root - see `.env.example` and
# `docs/deployment/docker.md`.
#
# ## RPC scheme choice
#
# Both `wss://`/`ws://` and `https://`/`http://` work. A WebSocket URL
# pushes new blocks via `eth_subscribe(newHeads)`; an HTTP URL polls
# `eth_getBlockByNumber` at the chain's block time instead (logs already
# poll `eth_getLogs` on either transport). Prefer `wss://` where the
# provider exposes it - push is lower-latency and cheaper than polling.

[engine]
state_dir = "./data"
log_level = "info"

# Per-module wasmtime resource limits. Every field is optional;
# omitted values resolve to built-in defaults (1B fuel, 64 MiB memory).
# Per-module overrides land in 0.3.
[limits]
# fuel_per_event = 1_000_000_000
# memory_bytes   = 67_108_864

# 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

# 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 per chain the engine should be able to talk
# to. Chain ids are EVM decimal. Drop any entry whose env var you
# haven't exported - `${VAR}` substitution fails fast with the exact
# missing variable named.
#
# Optional per-chain field:
#   request_timeout_secs = 30   # per-request JSON-RPC timeout (default: 30)

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

[chains.100]                                 # Gnosis Chain
rpc_url = "${GNOSIS_RPC_URL}"

[chains.11155111]                            # Sepolia
rpc_url = "${SEPOLIA_RPC_URL}"

[chains.42161]                               # Arbitrum One
rpc_url = "${ARBITRUM_RPC_URL}"

[chains.8453]                                # Base
rpc_url = "${BASE_RPC_URL}"