Contracts Module¶

The Contracts module provides protocol-specific decoded event and function call data. Unlike the Execution module which handles raw EVM data, the Contracts module uses ABI decoding to transform opaque log topics and calldata into human-readable, typed columns for specific protocols deployed on Gnosis Chain.

Data Sources¶

The Contracts module draws from two sources:

1. execution database -- Raw logs and traces containing encoded event/function data
2. contracts_whitelist / contracts_abi -- ABI registry that maps contract addresses to their interface definitions, enabling automatic decoding

The ABI decoding system matches log topics and function selectors against known ABIs to produce decoded columns with meaningful names (e.g., sender, amount, pool_id) rather than raw hex data.

ABI Decoding System¶

The decoding pipeline works as follows:

1. Contracts are registered in a whitelist with their addresses, names, and protocol tags
2. ABI JSON is stored and indexed by contract address
3. During dbt model execution, logs and traces are joined with ABI data
4. Event topics and function selectors are matched to decode parameters into typed columns

This approach avoids the need to write custom parsers for each contract -- any contract with a registered ABI is automatically decoded.

Raw Logs (execution.logs)
    |
    +-- JOIN contracts_whitelist (by address)
    +-- JOIN contracts_abi (by address + event signature)
    |
    v
Decoded Events (typed columns: sender, amount, pool_id, ...)
    |
    v
Protocol-Specific Models (int_contracts_balancer_swaps_daily, etc.)

Model Categories¶

Atoken

Announcements

Channels

Cowswapethflow

Decoded... |

Factory

Gpv2Allowlistauthentication

Gpv2Settlement

Marketfactory

Nodesafemigration

Nodesaferegistry

Nodestakefactory

Nonfungiblepositionmanager

Pool

Poolconfigurator

Poolinstance

Tslax

Ticketpriceoracle

Vault

Winningprobabilityoracle

Wrapped1155Factory

Bc3M

Bcoin

Bcspx

Bhigh

Bib01

Bibta

Bmstr

Bnvda

Calls

Events

Feeds

Pool

Registry

V2

Decoded... | | contracts_circles_v2_NameRegistry_calls | CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | | contracts_circles_v2_NameRegistry_events | CONTRACTS | Decoded event logs for the Circles v2 NameRegistry contract. | | contracts_circles_v2_PaymentGatewayFactory_calls | CONTRACTS | Decoded function calls for the Circles v2 PaymentGatewayFactory contract. This model is decoded from execution.trace... | |contracts_circles_v2_PaymentGatewayFactory_events| CONTRACTS | Decoded event logs for the Circles v2 PaymentGatewayFactory contract. | |contracts_circles_v2_PaymentGateway_calls| CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | |contracts_circles_v2_PaymentGateway_events| CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | |contracts_circles_v2_ReferralsModule_calls| CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | |contracts_circles_v2_ReferralsModule_events| CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | |contracts_circles_v2_StandardTreasury_calls| CONTRACTS | DEPRECATED (kept queryable, never deleted) - no downstream consumers. Not built by cron (no production tag). Decoded ... | |contracts_circles_v2_StandardTreasury_events| CONTRACTS | Decoded event logs for the Circles v2 StandardTreasury contract. | |contracts_circles_v2_score_policy_events` | CONTRACTS | Decoded events from the OffchainScoreBasedMintPolicy singleton (0x450d68272e43c4cab7cbc7faa37893a50fae9569): Personal... |

V3

Covered Protocols¶

The following protocols have dedicated decoded models:

DEX Protocols¶

Lending Protocols¶

Other Protocols¶

Using search_models_by_address¶

The MCP server provides a dedicated tool to find dbt models related to a specific contract address:

search_models_by_address("0xba12222222228d8ba445958a75a0704d566bf2c8")

This searches the contracts whitelist, ABI registry, and model SQL to find all models that reference the given address. It is the fastest way to discover what decoded data is available for a specific contract.

Key Models Reference¶

Query Examples¶

Get daily Balancer swap volume:

SELECT dt, pool_name, swap_count, volume_usd
FROM dbt.int_contracts_balancer_swaps_daily
WHERE dt >= today() - 7
ORDER BY dt, volume_usd DESC

Check Circles protocol growth:

SELECT dt, new_signups, total_users
FROM dbt.int_contracts_circles_signups_daily
WHERE dt >= today() - 30
ORDER BY dt

Compare DEX volume across protocols:

SELECT
    protocol,
    sum(volume_usd) AS total_volume,
    sum(swap_count) AS total_swaps
FROM dbt.api_contracts_protocol_activity_daily
WHERE dt >= today() - 30
  AND protocol IN ('Balancer', 'CoW Protocol', 'SushiSwap', 'Curve', 'Uniswap')
GROUP BY protocol
ORDER BY total_volume DESC

Track Gnosis Safe module transactions:

SELECT dt, module_type, tx_count
FROM dbt.int_contracts_safe_module_txs_daily
WHERE dt >= today() - 30
ORDER BY dt

Related Modules¶

• Execution -- Raw logs and traces that serve as input to ABI decoding
• Bridges -- Bridge contracts are a subset of decoded contract data
• Crawlers -- Dune labels provide additional contract name resolution