---
name: catalyst-foundational-metadata
description: Set up new chain foundational metadata (evms_info, prices, base sources, evms_blockchains_list)
disable-model-invocation: true
---
# catalyst foundational metadata

## overview
sets up foundational metadata for a new chain.

**when to use:** use when adding a new chain's foundational metadata (`evms_info`, native/prices tokens, base sources, and `evms_blockchains_list`).

## parameters
- `<issue_id>`: linear issue id (e.g., CUR2-554)
- `<chain>`: chain name (e.g., kaia, monad)

## usage
```
/catalyst-foundational-metadata CUR2-554 xlayer
```

dune mcp server: `user-dune-mcp`.
for ad-hoc sql, prefer temporary execution if the dune mcp supports it in-session. only create saved/throwaway queries with `createDuneQuery` when temporary execution is not available or when a later step explicitly needs a `query_id`.
fallback sequence when `query_id` is required: create query with `createDuneQuery` (pass sql in `query`) -> run with `executeQueryById` (using returned `query_id`) -> fetch rows with `getExecutionResults` (using returned `execution_id`).

## conventions
- **execution order:** numbered items = execute sequentially. any step that says "run" or "execute" is blocking; complete it before proceeding.
- **code patterns:** use existing chain patterns as reference (e.g. `dbt_subprojects/dex/models/trades/kaia/`, `.../mezo/`). ordering: mimic existing; if unclear, append. swap chain name in: file paths, model names, schema entries, `blockchain` values.
- **contributors:** new files: set git username only. existing files: append git username.

## prep vars
- retrieve chain metadata: run this sql via the ad-hoc sql sequence above: `select * from dune.blockchains where name = '<chain>'` (substitute `<chain>` with the chain name). extract: `chain_id`, `name` (display name), `token_address` (native token).
- retrieve first_block_time: run this sql via the ad-hoc sql sequence above: `select min(time) from <chain>.blocks where number <> 0` (substitute `<chain>`).

## git workflow
1. **verify `main` is up to date:** fetch latest, pull if behind, exit if diverged.
2. **create branch:** name `<issue_id>-<chain>-foundational-metadata`, create off `main`, checkout, warn if exists. don't commit/push anything.

## steps
1. **add evm chain info**
   - edit `dbt_subprojects/daily_spellbook/models/evms/evms_info.sql`
   - append VALUES row: `(chain_id, '<chain>', 'Name', 'Layer 1/2', ...)`
   - use prep vars: `chain_id`, `name`, `first_block_time`, `token_address`
   - find: explorer, wrapped_native_token_address
   - **IMPORTANT:** the `wrapped_native_token_address` column must be the **wrapped** token contract (e.g., WETH, WHBAR), NOT the native/zero address

2. **add native token**
   - find id on: https://api.coinpaprika.com/v1/coins
   - add to `dbt_subprojects/tokens/models/prices/prices_native_tokens.sql`

3. **create prices tokens model**
   - create `dbt_subprojects/tokens/models/prices/<chain>/prices_<chain>_tokens.sql`
   - check chain docs for token addresses & symbols
   - if not found: use dune mcp **executeQueryById** with `query_id: 6293737`, `query_parameters: [{"key":"chain","value":"<chain>","type":"text"}]` (substitute `<chain>`)
   - identify key tokens (wrapped native token, top 5 transferred, stables, WETH)
   - **DO NOT include the native token** — it is already in `prices_native_tokens.sql`. Duplicating creates dupes in `prices.day/hour/minute` pipelines
   - find ids on coinpaprika (`https://api.coinpaprika.com/v1/search?q=<token>&categories=currencies`), add to VALUES
   - **ALL token_ids must exist and be active on CoinPaprika.** CI runs `scripts/check_tokens.py` which validates every ID — missing/inactive IDs fail the build

4. **create schema file**
   - create `dbt_subprojects/tokens/models/prices/<chain>/_schema.yml`

5. **add to prices union**
   - edit `dbt_subprojects/tokens/models/prices/prices_tokens.sql`
   - add `ref('prices_<chain>_tokens')` to `fungible_prices_models`

6. **define raw data sources**
   - create `sources/_base_sources/evm/<chain>_base_sources.yml`
   - create `sources/_base_sources/evm/<chain>_docs_block.md`
   - use existing patterns or `scripts/generate_evm_*.py`

7. **integrate into aggregate EVM models**
   - add `<chain>` to `dbt_subprojects/daily_spellbook/macros/helpers/evms_blockchains_list.sql`

8. **final checks**
   - From repo root: run `uv sync --locked`, then run `uv run dbt compile` in `dbt_subprojects/tokens` and in `dbt_subprojects/daily_spellbook`. Fix any errors.