feat(jobs): derive artist coin stats on-chain (shadow of Birdeye CoinStatsJob)

database/seed.go

@@ -524,6 +524,50 @@ var (
 			"created_at": time.Now(),
 			"updated_at": time.Now(),
 		},
+		"artist_coin_stats_onchain": {
+			"mint":       nil,
+			"created_at": time.Now(),
+			"updated_at": time.Now(),
+		},
+		"artist_coin_price_history": {
+			"mint":      nil,
+			"timestamp": nil,
+			"price":     0.0,
+		},
+		"artist_coin_volume_accumulator": {
+			"mint":                nil,
+			"last_processed_slot": 0,
+			"total_volume":        0.0,
+			"total_volume_usd":    0.0,
+		},
+		"sol_meteora_dbc_pools": {
+			"account":                       nil,
+			"slot":                          1,
+			"config":                        "config-placeholder",
+			"creator":                       "creator-placeholder",
+			"base_mint":                     nil,
+			"base_vault":                    "base-vault-placeholder",
+			"quote_vault":                   "quote-vault-placeholder",
+			"base_reserve":                  0,
+			"quote_reserve":                 0,
+			"protocol_base_fee":             0,
+			"protocol_quote_fee":            0,
+			"partner_base_fee":              0,
+			"partner_quote_fee":             0,
+			"sqrt_price":                    0,
+			"activation_point":              0,
+			"pool_type":                     0,
+			"is_migrated":                   0,
+			"is_partner_withdraw_surplus":   0,
+			"is_protocol_withdraw_surplus":  0,
+			"migration_progress":            0,
+			"is_withdraw_leftover":          0,
+			"is_creator_withdraw_surplus":   0,
+			"migration_fee_withdraw_status": 0,
+			"finish_curve_timestamp":        0,
+			"creator_base_fee":              0,
+			"creator_quote_fee":             0,
+		},
 		"sol_token_account_balances": {
 			"account": nil,
 			"owner":   "owner-acc",

ddl/migrations/0229_artist_coin_stats_onchain.sql

@@ -0,0 +1,14 @@
+-- Shadow table for the on-chain-derived replacement of CoinStatsJob.
+-- Mirrors artist_coin_stats exactly so the on-chain job can be validated against
+-- the Birdeye-populated table before cutover (and so cutover is a repoint/rename
+-- with no consumer-struct changes). Populated by CoinStatsOnchainJob.
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS artist_coin_stats_onchain (
+    LIKE artist_coin_stats INCLUDING ALL
+);
+
+COMMENT ON TABLE artist_coin_stats_onchain IS
+    'On-chain-derived shadow of artist_coin_stats, written by CoinStatsOnchainJob. Used to validate against the Birdeye-populated artist_coin_stats before replacing it.';
+
+COMMIT;

ddl/migrations/0230_artist_coin_price_history.sql

@@ -0,0 +1,20 @@
+-- Hourly USD price snapshots per artist coin, used to compute the 24h price change
+-- (history_24h_price / price_change_24h_percent) on-chain, replacing Birdeye.
+-- Written by CoinStatsOnchainJob; kept small via hourly binning + 7-day retention.
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS artist_coin_price_history (
+    mint       TEXT NOT NULL,
+    timestamp  TIMESTAMP NOT NULL,
+    price      DOUBLE PRECISION NOT NULL,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (mint, timestamp)
+);
+
+CREATE INDEX IF NOT EXISTS artist_coin_price_history_mint_ts_idx
+    ON artist_coin_price_history (mint, timestamp DESC);
+
+COMMENT ON TABLE artist_coin_price_history IS
+    'Hourly USD price snapshots per artist coin, used to compute 24h price change.';
+
+COMMIT;

ddl/migrations/0231_artist_coin_volume_accumulator.sql

@@ -0,0 +1,18 @@
+-- Running all-time trading-volume accumulator per artist coin, replacing Birdeye's
+-- all-time stats. Each CoinStatsOnchainJob run adds only trades in new slots
+-- (slot > last_processed_slot), valued in USD at that interval's AUDIO price, so
+-- historical USD isn't repriced at today's rate. total_volume is AUDIO-denominated.
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS artist_coin_volume_accumulator (
+    mint                 TEXT PRIMARY KEY,
+    last_processed_slot  BIGINT NOT NULL DEFAULT 0,
+    total_volume         DOUBLE PRECISION NOT NULL DEFAULT 0,
+    total_volume_usd     DOUBLE PRECISION NOT NULL DEFAULT 0,
+    updated_at           TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON TABLE artist_coin_volume_accumulator IS
+    'Running per-coin trading volume (AUDIO + USD) accumulated from pool quote-vault balance changes, watermarked by last_processed_slot. Written by CoinStatsOnchainJob.';
+
+COMMIT;

ddl/views/artist_coin_stats_comparison.sql

@@ -0,0 +1,42 @@
+-- Side-by-side comparison of the Birdeye-populated artist_coin_stats against the
+-- on-chain-derived artist_coin_stats_onchain, for validating CoinStatsOnchainJob
+-- before cutover. `*_pct_diff` = (onchain - birdeye) / birdeye * 100.
+-- A large diff (or NULL onchain where birdeye has a value) flags a missed pool,
+-- external market, or migration lag to investigate.
+DROP VIEW IF EXISTS artist_coin_stats_comparison;
+CREATE VIEW artist_coin_stats_comparison AS
+    SELECT
+        ac.mint,
+        ac.ticker,
+
+        b.price            AS birdeye_price,
+        o.price            AS onchain_price,
+        ROUND((((o.price - b.price) / NULLIF(b.price, 0)) * 100)::numeric, 2)                     AS price_pct_diff,
+
+        b.market_cap       AS birdeye_market_cap,
+        o.market_cap       AS onchain_market_cap,
+        ROUND((((o.market_cap - b.market_cap) / NULLIF(b.market_cap, 0)) * 100)::numeric, 2)       AS market_cap_pct_diff,
+
+        b.holder           AS birdeye_holder,
+        o.holder           AS onchain_holder,
+        (o.holder - b.holder)                                                                      AS holder_diff,
+
+        b.liquidity        AS birdeye_liquidity,
+        o.liquidity        AS onchain_liquidity,
+        ROUND((((o.liquidity - b.liquidity) / NULLIF(b.liquidity, 0)) * 100)::numeric, 2)          AS liquidity_pct_diff,
+
+        b.total_volume_usd AS birdeye_total_volume_usd,
+        o.total_volume_usd AS onchain_total_volume_usd,
+        ROUND((((o.total_volume_usd - b.total_volume_usd) / NULLIF(b.total_volume_usd, 0)) * 100)::numeric, 2) AS total_volume_usd_pct_diff,
+
+        b.price_change_24h_percent AS birdeye_price_change_24h_percent,
+        o.price_change_24h_percent AS onchain_price_change_24h_percent,
+
+        o.updated_at       AS onchain_updated_at,
+        b.updated_at       AS birdeye_updated_at
+    FROM artist_coins ac
+    LEFT JOIN artist_coin_stats b          ON b.mint = ac.mint
+    LEFT JOIN artist_coin_stats_onchain o  ON o.mint = ac.mint;
+
+COMMENT ON VIEW artist_coin_stats_comparison IS
+    'Compares Birdeye artist_coin_stats vs on-chain artist_coin_stats_onchain per coin (values + % diff) to validate CoinStatsOnchainJob before cutover.';