feat(dex): integrate Agra DEX (ethereum, hyperevm)

[cxheng315]

Thank you for contributing to Spellbook 🪄

Description

Integrates Agra, a Seaport-fork order-settlement (direct) DEX, into the DEX sector for ethereum and hyperevm.

What's included

• New source agra_multichain (sources/_sector/dex/trades/ethereum/_sources.yml), with settlement_evt_orderfulfilled and settlement_evt_ordersmatched. A single multichain source serves both chains (the decoded table is multichain).
• Platform base trades for both chains, generated from a shared agra_base_trades(blockchain, start_date) macro — each chain model is config + a one-line macro call.
• Registered agra in dex_ethereum_base_trades / dex_hyperevm_base_trades and in dex_info.
• Schema tests (unique_combination_of_columns, check_dex_base_trades_seed) + seeds per chain.
• Branded agra.trades project view via dex_project_trades('agra') — inherits amount_usd from the sector enrichment.

Notes

• Decodes Seaport OrderFulfilled (offer → token_bought, consideration → token_sold) and dedupes the aggregate taker leg of matchOrders settlements.
• volume_usd comes from the standard sector enrichment in dex.trades; the project view just filters the enriched per-chain trades.
• Start date: 2026-03-01.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bbfd7a2670

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve item identity when joining Seaport legs

When an Agra OrderFulfilled contains more than one ERC20 offer or consideration item, offer_side and consideration_side each produce one row per token, but this join only uses tx_hash and evt_index. A single event then expands into every offer-token × consideration-token combination while the model is keyed and tested only by tx_hash, evt_index, so multi-asset fills will either fail the unique test/merge or be arbitrarily de-duped downstream in dex_base_trades_macro.

Useful? React with 👍 / 👎.

[cxheng315]

This shouldn't happen for Agra. It's a CLOB — every order matches exactly one ERC20 against the quote token (a/b or c/b). A single order paying two tokens for one (a + c / b) isn't a valid trade; it could only come from a contract failure. Confirmed across all production data so far (247 events: 235 ethereum, 12 hyperevm) — every OrderFulfilled has exactly one distinct ERC20 per side.

And even if it did occur, a multi-asset fill isn't representable in dex.trades anyway (one token_bought_address / one token_sold_address per row, and no prices at the base layer to split a leg), so it's intentionally out of scope — consistent with the rest of the base-trades sector.

That said, I added a deterministic guard so a malformed order can never silently break the (tx_hash, evt_index) unique key or the incremental merge: each side collapses to one row per event via row_number() (QUALIFY isn't supported in DuneSQL/Trino). It's a verified no-op on all current data — old-vs-new output is byte-identical (209 = 209 rows, empty symmetric difference) — and the unique key stays the tripwire if an anomalous order ever appears.

[cxheng315]

Closing as superseded by #9881, which was merged in 62ee319.

#9881 carries everything from this PR plus the work that came out of review:

• monad support — agra_monad_base_trades + seed, registered in dex_monad_base_trades
• payment-leg selection — picks the consideration item by recipient = offerer instead of by raw amount, which fixes multi-token consideration orders
• self-matched fills filtered — offerer <> recipient (the Agra team confirmed these are test fills); that filter strictly subsumes the old matchOrders dedup, so the matched_hashes CTE and the settlement_evt_ordersmatched source were removed
• test/seed hardening — not_null + descriptions on tx_hash/evt_index, refreshed seeds on all three chains

The 14 files touched here are a subset of the 18 in #9881, so nothing from this PR is left behind.