Add Balancer trades models

[tiagoponciano]

Summary

This PR introduces a complete Balancer trades pipeline in dbt, aligned with the existing Dune spell structure. It covers V1, V2, and V3 swaps across 11 blockchains, plus CoWSwap AMM trades on Ethereum. The implementation uses a layered macro-driven architecture with incremental enrichment, supporting pool swap-fee models required for accurate V2 fee attribution.

Motivation

Balancer trades are a core downstream dependency for protocol analytics (volume, fees, pool activity). This PR ports that logic into dbt so trades can be built incrementally, tested, and composed with other Balancer models in the same project.

Architecture

The pipeline follows a three-tier model structure:

Layer	Naming pattern	Materialization	Role
Base	balancer_v{1,2,3}_{{chain}}_base_trades	Incremental (merge)	Decode raw swap events; attach pool metadata and swap fees
Enriched	balancer_v{1,2,3}_{{chain}}_trades	Incremental (merge)	Join curated pricing data; compute amount_usd and token amounts
Chain union	balancer_{{chain}}_trades	View	Union all protocol versions active on that chain
Global union	balancer_trades	View	Union all chains into a single cross-chain table

Enriched V2/V3 models join the curated dex.trades table for token symbols, amounts, and baseline USD pricing, then merge Balancer-specific fields (pool_id, swap_fee, pool_symbol, pool_type) from the corresponding base model. V1 and CoWSwap AMM models build the full output schema directly from decoded events and price sources.

Macros (balancer_trades_macro.sql)

Macro	Purpose
balancer_compatible_v1_trades	Decode V1 BPool_evt_LOG_SWAP; resolve swap fee from latest setSwapFee call per pool
balancer_compatible_v2_trades	Decode V2 Vault_evt_Swap; join historical swap fees from per-chain pools_fees models
balancer_compatible_v3_trades	Decode V3 Vault_evt_Swap; handle buffer swaps by matching nearest Wrap/Unwrap events; attach V3 pool labels
balancer_v1_enriched_trades	Full V1 enrichment with prices.usd, ERC20 decimals, and V1 pool labels
balancer_v2_enriched_trades	Join dex.trades + base trades; BPT price fallback for amount_usd when spot price is unavailable
balancer_v3_enriched_trades	Join dex.trades + base trades; ERC-4626 price fallback for wrapped-token swaps
balancer_cowswap_amm_trades	CoWSwap AMM trades via GPv2Settlement_evt_Trade, linked to BCoW pools and settlement solver
balancer_trades_union	Standardized UNION ALL across chain or version models
balancer_trades_dev_time_predicate	Dev-target date window (default 3 days) to limit scan cost during local runs

Chain and version coverage

Chain	V1	V2	V3	CoWSwap AMM
Ethereum	✓	✓	✓	✓
Arbitrum		✓	✓
Avalanche C		✓	✓
Base		✓	✓
Gnosis		✓	✓
Optimism		✓
Polygon		✓
zkEVM		✓
Monad			✓
HyperEVM			✓
Plasma			✓

Total: 50+ model files across models/_project/balancer/trades/ and models/_project/balancer_cowswap_amm/.

Output schema

All trade models expose a consistent column set compatible with dex.trades:

blockchain, project, version, block_month, block_date, block_time, block_number, token_bought_symbol, token_sold_symbol, token_pair, token_bought_amount, token_sold_amount, token_bought_amount_raw, token_sold_amount_raw, amount_usd, token_bought_address, token_sold_address, taker, maker, pool_id, swap_fee, project_contract_address, pool_symbol, pool_type, tx_hash, tx_from, tx_to, evt_index

Pool swap fees (supporting models)

V2 trades require historical swap-fee lookups at the time of each swap. This PR adds the supporting pools_fees layer:

• balancer_pools_fees_macro.sql
  • V2: Decodes SwapFeeChanged events from raw chain logs (filtered to registered Balancer pools)
  • V3: Reads Vault_evt_SwapFeePercentageChanged from decoded sources
• Per-chain V2 models for Ethereum, Arbitrum, Avalanche C, Base, Gnosis, Optimism, Polygon, and zkEVM
• Union views: balancer_v2_pools_fees and balancer_pools_fees

CoWSwap AMM trades

• New incremental model balancer_cowswap_amm_ethereum_trades, included in balancer_ethereum_trades
• Sources trades from GPv2Settlement_evt_Trade, resolves pool via BCoWFactory_evt_LOG_NEW_POOL, and enriches with settlement solver, token metadata, and USD pricing
• Schema entry and unique-key tests added in balancer_cowswap_amm/ethereum/_schema.yml

Sources

File	Changes
sources/balancer/ethereum/balancer_ethereum_sources.yml	V1 swap events (BPool_evt_LOG_SWAP, BPool_call_setSwapFee)
sources/gnosis_protocol_v2_sources.yml	New — GPv2Settlement_evt_Trade, GPv2Settlement_evt_Settlement
sources/chain_logs_sources.yml	New — raw logs tables for V2 swap-fee decoding (Ethereum, Arbitrum, Base, Gnosis, Optimism, Polygon, Avalanche C, zkEVM)
sources/balancer/avalanche_c/balancer_avalanche_c_sources.yml	V3 swap events (Vault_evt_Swap, Vault_evt_Wrap, Vault_evt_Unwrap, and related)
sources/balancer/hyperevm/balancer_hyperevm_sources.yml	V3 swap and pool events for HyperEVM
sources/balancer/monad/balancer_monad_sources.yml	V3 swap and pool events for Monad