Contracts & Events

The core of every Sieve config. Define what contracts and events to index.

Contract definition

sieve.toml

[[contracts]]
name = "USDC"
address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
abi = "abis/erc20.json"
start_block = 21_000_000
include_receipts = true

name · required

Identifier for this contract. Lowercase alphanumeric and underscores.

address · required

Contract address (hex). Omit only for factory contracts.

abi · required

Path to ABI JSON file, relative to the config file.

start_block · optional

Block number to start indexing from. Defaults to 0.

include_receipts · optional · default: false

Adds tx_gas_used, tx_nonce, cumulative_gas_used, and tx_status columns to all event and call tables for this contract.

Event definition

sieve.toml

[[contracts.events]]
name = "Transfer"
table = "usdc_transfers"
context = ["block_timestamp", "tx_from"]

name · required

Event name, must match the ABI exactly.

table · required

PostgreSQL table name. Lowercase alphanumeric and underscores. Must be unique across all contracts.

context · optional

Array of metadata columns to add. See context fields below.

Columns are auto-generated from the ABI. Solidity camelCase is converted to snake_case automatically (_troveId → trove_id, amount0Out → amount0_out). If a converted name collides with a reserved column, it gets a param_ prefix.

Context fields

Block and transaction metadata you can add to any event, call, or transfer table. The last four are receipt fields, automatically added when include_receipts = true.

Field	Type	Description
block_timestamp	BIGINT	Block timestamp (seconds since epoch)
block_hash	BYTEA	Block hash
tx_from	TEXT	Transaction sender
tx_to	TEXT	Transaction recipient (NULL for contract creation)
tx_value	NUMERIC	Transaction value in wei
tx_gas_price	BIGINT	Effective gas price
tx_gas_used	BIGINT	Per-transaction gas used (receipt)
tx_nonce	BIGINT	Transaction nonce (receipt)
cumulative_gas_used	BIGINT	Cumulative gas used in block (receipt)
tx_status	BOOLEAN	Receipt success (always true)

You can add individual receipt fields without the flag: context = ["tx_gas_used", "tx_nonce"]

Column overrides

Override auto-generated column names or types. Omit columns entirely to use ABI defaults.

sieve.toml

[[contracts.events]]
name = "Transfer"
table = "usdc_transfers"
columns = [
  { param = "from",  name = "sender",   type = "text" },
  { param = "to",    name = "receiver", type = "text" },
  { param = "value", name = "amount",   type = "numeric" },
]

param · required ABI parameter name

name · optional PostgreSQL column name (defaults to snake_case of param)

type · optional PostgreSQL type (auto-mapped from Solidity if omitted)

Indexed parameter filters

Filter events by indexed parameter values at sync time. Only matching events are stored. This uses Ethereum log topics (topic1–topic3), which means only indexed parameters can be filtered before insertion.

sieve.toml

[[contracts.events]]
name = "Approval"
table = "usdc_approvals"

[contracts.events.filter]
spender = ["0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD"]

Non-indexed parameters are decoded and stored, but can only be filtered after insertion via SQL or the GraphQL API.

Next steps

▸ Function Calls index transaction calldata

▸ Factory Contracts dynamically discover child contracts