OpenParable
Skip to content
← Back to skills

Catalyst Foundational Metadata

Development
catalyst-foundational-metadata

Catalyst Foundational Metadata is an Agent Skill for development published in the duneanalytics/spellbook repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Set up new chain foundational metadata (evms_info, prices, base sources, evms_blockchains_list)

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/duneanalytics/spellbook/blob/HEAD/.claude/skills/catalyst-foundational-metadata/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/catalyst-foundational-metadata, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  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.