add custom renderer support and renderer test sends

Author: apexearth

package.json

@@ -38,7 +38,7 @@
     "dotenv": "^16.1.4",
     "esbuild": "^0.19.5",
     "ethers": "^6.5.1",
-    "graphql": "^16.11.0",
+    "graphql": "^15.10.1",
     "graphql-request": "^6",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",

pnpm-lock.yaml

@@ -38,6 +38,7 @@ deploy:
     - LOKI_URL
     - LOKI_USER
     - LOKI_API_KEY
+    - SQUID_TEST_RENDER_TOKEN
   processor:
     - name: mainnet-processor
       cmd: ['sqd', 'process:prod']

squid.yaml

@@ -1,16 +1,15 @@
-import fs from 'node:fs'
-import path from 'node:path'
 // @ts-expect-error pg has no type declarations in this project
 import pg from 'pg'
 
 import type { Severity, Topic } from '@notify/const'
 
-import type { AlertRule, FilterExpression } from './types'
+import type { AlertRule, FilterExpression, RendererRecord } from './types'
 
-const { Client, Pool } = pg
+const { Pool } = pg
 
 let pool: InstanceType<typeof Pool> | null = null
 let cachedRules: AlertRule[] = []
+let cachedRenderers: RendererRecord[] = []
 let lastRuleRefresh = 0
 
 const REFRESH_INTERVAL_MS = 5 * 60 * 1000 // 5 minutes
@@ -24,77 +23,6 @@ const getPool = (): InstanceType<typeof Pool> => {
   return pool
 }
 
-function readSqlFile(filename: string): string {
-  const localPath = path.resolve(__dirname, filename)
-  if (fs.existsSync(localPath)) return fs.readFileSync(localPath, 'utf-8')
-  return fs.readFileSync(path.resolve(__dirname, '..', '..', 'src', 'alert-config', filename), 'utf-8')
-}
-
-function splitStatements(sql: string): string[] {
-  return sql
-    .split(';\n')
-    .map((s) =>
-      s
-        .split('\n')
-        .filter((line) => !line.trimStart().startsWith('--'))
-        .join('\n')
-        .trim(),
-    )
-    .filter((s) => s.length > 0)
-}
-
-/**
- * Initialize the alert config database.
- * Creates the database if needed, runs migration, and seeds data.
- * Call once at startup before using any other alert-config functions.
- * Only runs when ALERT_CONFIG_DB_MIGRATION=true.
- */
-export const initAlertConfigDb = async (): Promise<void> => {
-  if (process.env.ALERT_CONFIG_DB_MIGRATION !== 'true') return
-
-  const url = process.env.ALERT_CONFIG_DB_URL
-  if (!url) return
-
-  // Parse the DB name from the URL to create it if needed
-  const parsed = new URL(url)
-  const dbName = parsed.pathname.slice(1) // remove leading /
-  const adminUrl = `${parsed.protocol}//${parsed.username}:${parsed.password}@${parsed.host}/postgres`
-
-  // Create database if it doesn't exist
-  const adminClient = new Client({ connectionString: adminUrl })
-  try {
-    await adminClient.connect()
-    const { rows } = await adminClient.query('SELECT 1 FROM pg_database WHERE datname = $1', [dbName])
-    if (rows.length === 0) {
-      await adminClient.query(`CREATE DATABASE "${dbName}"`)
-      console.log(`Alert config: created database "${dbName}"`)
-    }
-  } finally {
-    await adminClient.end()
-  }
-
-  // Check if schema already exists
-  const p = getPool()
-  const { rows } = await p.query("SELECT 1 FROM information_schema.tables WHERE table_name = 'alert_rule'")
-  if (rows.length > 0) return // Already migrated
-
-  // Run migration
-  await p.query(readSqlFile('migration.sql'))
-  console.log('Alert config: migration complete')
-
-  // Seed rules
-  for (const stmt of splitStatements(readSqlFile('seed-rules.sql'))) {
-    await p.query(stmt)
-  }
-  console.log('Alert config: seed rules loaded')
-
-  // Seed ABIs
-  for (const stmt of splitStatements(readSqlFile('seed-abis.sql'))) {
-    await p.query(stmt)
-  }
-  console.log('Alert config: ABI seed loaded')
-}
-
 const loadRules = async (): Promise<AlertRule[]> => {
   const { rows } = await getPool().query('SELECT * FROM alert_rule WHERE enabled = true')
   return rows.map(
@@ -125,6 +53,26 @@ const loadRules = async (): Promise<AlertRule[]> => {
   )
 }
 
+const loadRenderers = async (): Promise<RendererRecord[]> => {
+  const tableCheck = await getPool().query("SELECT 1 FROM information_schema.tables WHERE table_name = 'renderer'")
+  if (tableCheck.rows.length === 0) return []
+  const { rows } = await getPool().query('SELECT * FROM renderer ORDER BY name ASC')
+  return rows.map(
+    (row: any): RendererRecord => ({
+      id: row.id,
+      name: row.name,
+      mode: row.mode,
+      chainId: row.chain_id,
+      matchType: row.match_type,
+      abiNames: row.abi_names,
+      contractAddresses: row.contract_addresses,
+      topic0: row.topic0,
+      sighash: row.sighash,
+      configJson: row.config_json ?? {},
+    }),
+  )
+}
+
 /**
  * Get all enabled alert rules. Refreshes every 5 minutes.
  */
@@ -134,6 +82,20 @@ export const getAlertRules = async (): Promise<AlertRule[]> => {
   return cachedRules
 }
 
+export const getRenderers = async (): Promise<RendererRecord[]> => {
+  if (!process.env.ALERT_CONFIG_DB_URL) return []
+  await refreshRulesIfStale()
+  return cachedRenderers
+}
+
+export const refreshAlertConfig = async (): Promise<void> => {
+  if (!process.env.ALERT_CONFIG_DB_URL) return
+  cachedRules = await loadRules()
+  cachedRenderers = await loadRenderers()
+  lastRuleRefresh = Date.now()
+  console.log(`Alert config: force refreshed ${cachedRules.length} rules and ${cachedRenderers.length} renderers`)
+}
+
 /**
  * Refresh alert rules periodically. Changes take effect without redeploy.
  * First load must succeed or the process exits — we can't run without rules.
@@ -144,8 +106,9 @@ const refreshRulesIfStale = async (): Promise<void> => {
   const isFirstLoad = lastRuleRefresh === 0
   try {
     cachedRules = await loadRules()
+    cachedRenderers = await loadRenderers()
     lastRuleRefresh = Date.now()
-    console.log(`Alert config: loaded ${cachedRules.length} rules`)
+    console.log(`Alert config: loaded ${cachedRules.length} rules and ${cachedRenderers.length} renderers`)
   } catch (err) {
     if (isFirstLoad) {
       console.error('FATAL: Failed to load alert rules on startup:', err)
@@ -155,6 +118,47 @@ const refreshRulesIfStale = async (): Promise<void> => {
   }
 }
 
+export const findMatchingRenderer = (params: {
+  chainId: number
+  matchType: 'event' | 'trace'
+  contractAddress?: string | null
+  topic0?: string | null
+  sighash?: string | null
+}): RendererRecord | null => {
+  const contractAddress = params.contractAddress?.toLowerCase() ?? null
+  const topic0 = params.topic0?.toLowerCase() ?? null
+  const sighash = params.sighash?.toLowerCase() ?? null
+
+  const candidates = cachedRenderers.filter((renderer) => {
+    if (renderer.matchType !== params.matchType) return false
+    if (renderer.chainId != null && renderer.chainId !== params.chainId) return false
+
+    if (renderer.contractAddresses?.length) {
+      if (!contractAddress) return false
+      if (!renderer.contractAddresses.some((value) => value.toLowerCase() === contractAddress)) return false
+    }
+
+    if (params.matchType === 'event' && renderer.topic0) {
+      if (!topic0 || renderer.topic0.toLowerCase() !== topic0) return false
+    }
+
+    if (params.matchType === 'trace' && renderer.sighash) {
+      if (!sighash || renderer.sighash.toLowerCase() !== sighash) return false
+    }
+
+    return true
+  })
+
+  if (candidates.length === 0) return null
+
+  const score = (renderer: RendererRecord) =>
+    (renderer.chainId != null ? 4 : 0) +
+    (renderer.contractAddresses?.length ? 2 : 0) +
+    (renderer.topic0 || renderer.sighash ? 1 : 0)
+
+  return candidates.sort((a, b) => score(b) - score(a) || a.name.localeCompare(b.name))[0] ?? null
+}
+
 /**
  * Find all rules matching an event record.
  */

src/alert-config/config-loader.ts

@@ -1,3 +1,21 @@
 export { evaluateFilter } from './evaluate-filter'
-export { initAlertConfigDb, findMatchingEventRules, findMatchingTraceRules, getAlertRules } from './config-loader'
-export type { AlertRule, ComparisonOp, FieldCondition, FilterExpression, GroupCondition } from './types'
+export {
+  findMatchingEventRules,
+  findMatchingTraceRules,
+  findMatchingRenderer,
+  getAlertRules,
+  getRenderers,
+  refreshAlertConfig,
+} from './config-loader'
+export { initAlertConfigDb } from './migration'
+export type {
+  AlertRule,
+  ComparisonOp,
+  FieldCondition,
+  FilterExpression,
+  GroupCondition,
+  RendererRecord,
+  TemplateFieldFormat,
+  TemplateRendererConfig,
+  TemplateRendererField,
+} from './types'

src/alert-config/index.ts

@@ -12,6 +12,7 @@ INSERT INTO chain VALUES (1, 'mainnet'), (8453, 'base'), (146, 'sonic');
 -- Valid notification topics (maps to Discord webhooks)
 CREATE TYPE severity_level AS ENUM ('low', 'medium', 'high', 'critical', 'broken', 'highlight');
 CREATE TYPE match_type AS ENUM ('event', 'trace');
+CREATE TYPE renderer_type AS ENUM ('default', 'template');
 
 -- Valid topics — add rows here as new products launch
 CREATE TABLE topic (
@@ -134,6 +135,33 @@ CREATE TABLE abi (
   created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
 );
 
+-- ─── Renderer ────────────────────────────────────────────────────────────────
+-- Additive template renderer overrides for specific contract + selector matches.
+
+CREATE TABLE renderer (
+  id                TEXT PRIMARY KEY CHECK (is_slug(id)),
+  name              TEXT NOT NULL,
+  mode              renderer_type NOT NULL DEFAULT 'template',
+  chain_id          INTEGER REFERENCES chain(id),
+  match_type        match_type NOT NULL,
+  contract_addresses TEXT[] CHECK (array_all_match(contract_addresses, 'address')),
+  topic0            TEXT CHECK (topic0 IS NULL OR is_topic_hash(topic0)),
+  sighash           TEXT CHECK (sighash IS NULL OR is_sighash(sighash)),
+  config_json       JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  CONSTRAINT renderer_selector_fields CHECK (
+    (match_type = 'event' AND sighash IS NULL) OR
+    (match_type = 'trace' AND topic0 IS NULL)
+  )
+);
+
+CREATE INDEX idx_renderer_chain_id ON renderer (chain_id);
+CREATE INDEX idx_renderer_match_type ON renderer (match_type);
+CREATE INDEX idx_renderer_topic0 ON renderer (topic0);
+CREATE INDEX idx_renderer_sighash ON renderer (sighash);
+
 -- ─── Alert Rule ───────────────────────────────────────────────────────────────
 
 CREATE TABLE alert_rule (
@@ -206,3 +234,6 @@ CREATE TRIGGER alert_rule_updated_at
   BEFORE UPDATE ON alert_rule
   FOR EACH ROW EXECUTE FUNCTION update_updated_at();
 
+CREATE TRIGGER renderer_updated_at
+  BEFORE UPDATE ON renderer
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();