nuthatch
Documentation nuthatch.toml

A nest has exactly one config file: nuthatch.toml. init generates it from a contract address; you edit it to add contracts, events, factories, and the optional compliance and webhook stages. Everything else in a nest (schema.json, llms.txt) is derived from it - regenerate with nuthatch schema.

The shape

[nest]
name = "usdc"
chain = "mainnet"
chain_id = 1
rpc_urls = ["https://your-rpc", "https://a-fallback-rpc"]

[[contracts]]
alias = "usdc"
address = "0xA0b86991c6218b36c1D19D4a2e9Eb0cE3606eB48"
start_block = 6082465            # auto-detected at init
abi = "abis/usdc.json"
events = ["Transfer", "Approval"]  # empty = index every event the ABI defines

[nest]

FieldMeaning
nameThe nest’s name (used for the served surface and logs).
chainThe chain name, e.g. mainnet, arbitrum-one, base.
chain_idThe chain id, e.g. 1, 42161, 8453.
rpc_urlsRPC endpoints, tried in order with round-robin failover. Point at your own node.

[[contracts]]

One block per contract. Repeat it to index many contracts in one nest.

FieldMeaning
aliasShort name - the table prefix ({alias}__{event}).
addressThe contract address.
start_blockDeployment block (auto-detected at init); omit to backfill from a recent tip offset.
abiPath to the vendored ABI, relative to the nest dir.
eventsOptional allowlist of event names to decode. Empty indexes every event the ABI defines.

The events allowlist is how a nest indexing e.g. a token keeps only Transfer instead of millions of irrelevant rows. An event name here that the ABI doesn’t define is a config error, caught when the decode registry is built.

Optional stages

nuthatch.toml also carries the optional layers, each documented on its own page:

  • [[templates]] + [[factories]] - index dynamically discovered children. See Factories.
  • [screening] + [flags] + [[alerts]] - the compliance pack. See Compliance pack.
  • [[webhooks]] - POST sealed rows to a URL. See Webhooks.

Absent stages cost nothing - a nest with none of them is a plain, fast log indexer.

Next