simplify: consolidate section helpers, satellite breakdown, comment trims

Post-/simplify review consolidations:

OrdpoolBlocksRepository.ts
  - Collapse 4 nearly-identical section helpers (amountCols, feeCols,
    cat21Cols, runeCols) into one generic sectionCols<Section>(...)
    that takes a colPrefix, aliasPrefix, pick function, and field list.
  - inscriptionSizeCols now reuses sectionCols + the shared
    INSCRIPTION_SIZE_FIELDS constant.
  - Pre-compute ORDPOOL_STATS_INSERT_SQL at module load. The column
    list and placeholder list are constant; only the params array
    needs to materialise per call. Saves 2 .map() passes over a
    90-element array per saveBlockOrdpoolStatsInDatabase invocation.
  - LEFT(?, 20) magic string → MOST_ACTIVE_MINT_TRUNC + TRUNCATED_PLACEHOLDER
    constants. truncated20 → truncatedMostActive (named for the use case).

ordpool-statistics.api.ts
  - Replace getAtomicalOpsBreakdown + getCounterpartyMessagesBreakdown
    (90% identical) with a single getSatelliteBreakdown(table, col, alias).
    Drop ~50 lines of duplicate SQL templating and try/catch boilerplate.

frontend ordpool-stats.component.helper.ts
  - Replace the long stat-type union in getTooltipContent with the
    existing OrdpoolStatisticResponse alias.
  - Drop the matchType JSDoc (says nothing the type system doesn't).
  - Drop the satellite-chart "follow-up backlog" comment.

ordpool-statistics-interface.ts
  - Trim UI prescription from RuneActivityStatistic doc comment;
    interface describes data shape, consumer decides rendering.

Author: hans-crypto

backend/src/api/explorer/_ordpool/ordpool-statistics-interface.ts

@@ -118,9 +118,8 @@ export interface Cat21StatStatistic extends BaseStatistic {
   cat21MaxFeeRate?: number | null;
 }
 
-// Rune block aggregates per period — both overall + non-uncommon variants in
-// the same response. UI shows both lines together (don't hide UNCOMMON•GOODS,
-// it's the truth).
+// Rune block aggregates per period — both overall + non-uncommon variants
+// in the same response so consumers can render both series.
 export interface RuneActivityStatistic extends BaseStatistic {
   uniqueMints?: number;
   uniqueMintsNonUncommon?: number;

backend/src/api/explorer/_ordpool/ordpool-statistics.api.ts

@@ -18,14 +18,15 @@ class OrdpoolStatisticsApi {
     const firstInscriptionHeight = getFirstInscriptionHeight(config.MEMPOOL.NETWORK);
     const sqlInterval = getSqlInterval(interval);
 
-    // Satellite-table-driven charts use their own JOIN target + extra
-    // GROUP BY discriminator (operation / message_type). Build the query
-    // separately rather than overloading the per-time aggregation path.
+    // Satellite-table charts use their own JOIN target + an extra GROUP BY
+    // discriminator (one series per operation / message_type).
     if (type === 'atomical-ops') {
-      return this.getAtomicalOpsBreakdown(firstInscriptionHeight, sqlInterval, aggregation);
+      return this.getSatelliteBreakdown(firstInscriptionHeight, sqlInterval, aggregation,
+        'ordpool_stats_atomical_op', 'sat.operation', 'operation');
     }
     if (type === 'counterparty-messages') {
-      return this.getCounterpartyMessagesBreakdown(firstInscriptionHeight, sqlInterval, aggregation);
+      return this.getSatelliteBreakdown(firstInscriptionHeight, sqlInterval, aggregation,
+        'ordpool_stats_counterparty', 'sat.message_type', 'messageType');
     }
 
     const selectClause = this.getSelectClause(type);
@@ -50,51 +51,13 @@ class OrdpoolStatisticsApi {
     }
   }
 
-  /**
-   * Per-operation breakdown for the atomical-ops chart. Joins
-   * ordpool_stats_atomical_op (one row per atomical mint/update) and groups
-   * by operation type AND time bucket, so the response is one row per
-   * (period, operation) combination.
-   */
-  private async getAtomicalOpsBreakdown(
+  private async getSatelliteBreakdown(
     firstInscriptionHeight: number,
     sqlInterval: string,
-    aggregation: Aggregation
-  ): Promise<OrdpoolStatisticResponse[]> {
-    const groupByTime = this.getGroupByClause(aggregation).replace(/^GROUP BY/, '');
-    const query = `
-      SELECT
-        MIN(b.height) AS minHeight,
-        MAX(b.height) AS maxHeight,
-        MIN(UNIX_TIMESTAMP(b.blockTimestamp)) AS minTime,
-        MAX(UNIX_TIMESTAMP(b.blockTimestamp)) AS maxTime,
-        ao.operation AS operation,
-        COUNT(*) AS count
-      FROM blocks b
-      JOIN ordpool_stats_atomical_op ao ON ao.hash = b.hash
-      WHERE b.height >= ${firstInscriptionHeight}
-        AND b.blockTimestamp >= DATE_SUB(NOW(), INTERVAL ${sqlInterval})
-      GROUP BY ${groupByTime}, ao.operation
-      ORDER BY b.blockTimestamp DESC
-    `;
-    try {
-      const [rows] : any[] = await DB.query(query);
-      return rows;
-    } catch (error) {
-      logger.err(`Error executing atomical-ops query: ${error}`, 'Ordpool');
-      throw error;
-    }
-  }
-
-  /**
-   * Per-message-type breakdown for the counterparty-messages chart.
-   * Same pattern as getAtomicalOpsBreakdown, joining
-   * ordpool_stats_counterparty.
-   */
-  private async getCounterpartyMessagesBreakdown(
-    firstInscriptionHeight: number,
-    sqlInterval: string,
-    aggregation: Aggregation
+    aggregation: Aggregation,
+    satelliteTable: string,
+    discriminatorCol: string,
+    discriminatorAlias: string,
   ): Promise<OrdpoolStatisticResponse[]> {
     const groupByTime = this.getGroupByClause(aggregation).replace(/^GROUP BY/, '');
     const query = `
@@ -103,20 +66,20 @@ class OrdpoolStatisticsApi {
         MAX(b.height) AS maxHeight,
         MIN(UNIX_TIMESTAMP(b.blockTimestamp)) AS minTime,
         MAX(UNIX_TIMESTAMP(b.blockTimestamp)) AS maxTime,
-        cp.message_type AS messageType,
+        ${discriminatorCol} AS ${discriminatorAlias},
         COUNT(*) AS count
       FROM blocks b
-      JOIN ordpool_stats_counterparty cp ON cp.hash = b.hash
+      JOIN ${satelliteTable} sat ON sat.hash = b.hash
       WHERE b.height >= ${firstInscriptionHeight}
         AND b.blockTimestamp >= DATE_SUB(NOW(), INTERVAL ${sqlInterval})
-      GROUP BY ${groupByTime}, cp.message_type
+      GROUP BY ${groupByTime}, ${discriminatorCol}
       ORDER BY b.blockTimestamp DESC
     `;
     try {
       const [rows] : any[] = await DB.query(query);
       return rows;
     } catch (error) {
-      logger.err(`Error executing counterparty-messages query: ${error}`, 'Ordpool');
+      logger.err(`Error executing ${satelliteTable} breakdown query: ${error}`, 'Ordpool');
       throw error;
     }
   }

backend/src/repositories/OrdpoolBlocksRepository.ts

@@ -324,120 +324,105 @@ interface OrdpoolStatColumn {
 }
 
 const camelToSnake = (s: string): string => s.replace(/[A-Z]/g, m => '_' + m.toLowerCase());
-
-// Section helpers: each takes a list of camelCase field names and emits one
-// OrdpoolStatColumn per field with `<section>_<snake>` SQL column, the
-// matching camelCase alias, and typed get/set lambdas. TypeScript checks
-// the field names against the actual OrdpoolStats shape.
-const amountCols = (...fields: (keyof OrdpoolStats['amounts'])[]): OrdpoolStatColumn[] =>
-  fields.map(f => ({
-    col:   'amounts_' + camelToSnake(f as string),
-    alias: 'amounts'  + (f as string).charAt(0).toUpperCase() + (f as string).slice(1),
-    val:   s => s.amounts[f],
-    set:   (t, v) => { (t.amounts as any)[f] = v; },
-  }));
-const feeCols = (...fields: (keyof OrdpoolStats['fees'])[]): OrdpoolStatColumn[] =>
-  fields.map(f => ({
-    col:   'fees_' + camelToSnake(f as string),
-    alias: 'fees'  + (f as string).charAt(0).toUpperCase() + (f as string).slice(1),
-    val:   s => s.fees[f],
-    set:   (t, v) => { (t.fees as any)[f] = v; },
-  }));
-const cat21Cols = (...fields: (keyof OrdpoolStats['cat21'])[]): OrdpoolStatColumn[] =>
+const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+
+const MOST_ACTIVE_MINT_TRUNC = 20;
+const TRUNCATED_PLACEHOLDER = `LEFT(?, ${MOST_ACTIVE_MINT_TRUNC})`;
+
+/** Emit one OrdpoolStatColumn per camelCase field, mapping
+ *  `field` ↔ `${colPrefix}_${snake_field}` (SQL) ↔ `${aliasPrefix}${PascalField}` (camelCase).
+ *  `pick` returns the section object on a stats — typically a top-level key
+ *  (`s => s.amounts`) but can drill deeper (`s => s.inscriptions.image`). */
+const sectionCols = <Section extends object>(
+  colPrefix: string,
+  aliasPrefix: string,
+  pick: (s: OrdpoolStats) => Section,
+  fields: (keyof Section & string)[],
+): OrdpoolStatColumn[] =>
   fields.map(f => ({
-    col:   'cat21_' + camelToSnake(f as string),
-    alias: 'cat21'  + (f as string).charAt(0).toUpperCase() + (f as string).slice(1),
-    val:   s => s.cat21[f],
-    set:   (t, v) => { (t.cat21 as any)[f] = v; },
-  }));
-const runeCols = (...fields: (keyof OrdpoolStats['runes'])[]): OrdpoolStatColumn[] =>
-  fields.map(f => ({
-    col:   'runes_' + camelToSnake(f as string),
-    alias: 'runes'  + (f as string).charAt(0).toUpperCase() + (f as string).slice(1),
-    val:   s => s.runes[f],
-    set:   (t, v) => { (t.runes as any)[f] = v; },
+    col:   `${colPrefix}_${camelToSnake(f)}`,
+    alias: aliasPrefix + cap(f),
+    val:   s => (pick(s) as any)[f],
+    set:   (t, v) => { (pick(t) as any)[f] = v; },
   }));
 
-// All 8 fields of an InscriptionSizeAggregate. Used 4× — once for the global
-// aggregate and once per content-type bucket (image/text/json).
+/** All 8 fields of an InscriptionSizeAggregate. Used 4× — global + per-bucket. */
+const INSCRIPTION_SIZE_FIELDS: (keyof InscriptionSizeAggregate)[] = [
+  'totalEnvelopeSize', 'totalContentSize',
+  'largestEnvelopeSize', 'largestContentSize',
+  'largestEnvelopeInscriptionId', 'largestContentInscriptionId',
+  'averageEnvelopeSize', 'averageContentSize',
+];
+
 const inscriptionSizeCols = (
-  colPrefix: string,                                              // e.g. 'inscriptions_image'
-  aliasPrefix: string,                                            // e.g. 'inscriptionsImage'
+  colPrefix: string,
+  aliasPrefix: string,
   pick: (s: OrdpoolStats) => InscriptionSizeAggregate,
-  pickTarget: (t: OrdpoolStats) => InscriptionSizeAggregate,
-): OrdpoolStatColumn[] => {
-  const fields: (keyof InscriptionSizeAggregate)[] = [
-    'totalEnvelopeSize', 'totalContentSize',
-    'largestEnvelopeSize', 'largestContentSize',
-    'largestEnvelopeInscriptionId', 'largestContentInscriptionId',
-    'averageEnvelopeSize', 'averageContentSize',
-  ];
-  return fields.map(f => ({
-    col:   `${colPrefix}_${camelToSnake(f as string)}`,
-    alias: aliasPrefix + (f as string).charAt(0).toUpperCase() + (f as string).slice(1),
-    val:   s => pick(s)[f],
-    set:   (t, v) => { (pickTarget(t) as any)[f] = v; },
-  }));
-};
+): OrdpoolStatColumn[] =>
+  sectionCols(colPrefix, aliasPrefix, pick, INSCRIPTION_SIZE_FIELDS);
 
-const truncated20 = (
+const truncatedMostActive = (
   col: string,
   alias: string,
   val: (s: OrdpoolStats) => unknown,
   set: (t: OrdpoolStats, v: any) => void,
-): OrdpoolStatColumn => ({ col, alias, placeholder: 'LEFT(?, 20)', val, set });
+): OrdpoolStatColumn => ({ col, alias, placeholder: TRUNCATED_PLACEHOLDER, val, set });
 
 export const ORDPOOL_STATS_COLUMNS: OrdpoolStatColumn[] = [
-  ...amountCols(
+  ...sectionCols('amounts', 'amounts', s => s.amounts, [
     'atomical', 'atomicalMint', 'atomicalUpdate',
     'counterparty', 'stamp', 'src721', 'src101',
     'cat21', 'cat21Mint',
     'inscription', 'inscriptionMint', 'inscriptionImage', 'inscriptionText', 'inscriptionJson',
     'rune', 'runeEtch', 'runeMint', 'runeCenotaph',
     'brc20', 'brc20Deploy', 'brc20Mint', 'brc20Transfer',
     'src20', 'src20Deploy', 'src20Mint', 'src20Transfer',
-  ),
-  ...feeCols(
+  ]),
+  ...sectionCols('fees', 'fees', s => s.fees, [
     'runeMints', 'nonUncommonRuneMints', 'brc20Mints', 'src20Mints',
     'cat21Mints', 'atomicals', 'inscriptionMints',
     'inscriptionImageMints', 'inscriptionTextMints', 'inscriptionJsonMints',
-  ),
-  ...inscriptionSizeCols('inscriptions',       'inscriptions',      s => s.inscriptions,       t => t.inscriptions),
-  ...inscriptionSizeCols('inscriptions_image', 'inscriptionsImage', s => s.inscriptions.image, t => t.inscriptions.image),
-  ...inscriptionSizeCols('inscriptions_text',  'inscriptionsText',  s => s.inscriptions.text,  t => t.inscriptions.text),
-  ...inscriptionSizeCols('inscriptions_json',  'inscriptionsJson',  s => s.inscriptions.json,  t => t.inscriptions.json),
-  {
-    col: 'inscriptions_brotli_count', alias: 'inscriptionsBrotliCount',
-    val: s => s.inscriptions.brotliCount,
-    set: (t, v) => { t.inscriptions.brotliCount = v; },
-  },
-  {
-    col: 'inscriptions_gzip_count', alias: 'inscriptionsGzipCount',
-    val: s => s.inscriptions.gzipCount,
-    set: (t, v) => { t.inscriptions.gzipCount = v; },
-  },
-  {
-    col: 'inscriptions_compressed_envelope_bytes', alias: 'inscriptionsCompressedEnvelopeBytes',
-    val: s => s.inscriptions.compressedEnvelopeBytes,
-    set: (t, v) => { t.inscriptions.compressedEnvelopeBytes = v; },
-  },
-  ...cat21Cols('genesisCount', 'avgFeeRate', 'minFeeRate', 'maxFeeRate'),
-  ...runeCols('uniqueMintsCount', 'uniqueMintsCountNonUncommon', 'topMintCount', 'topMintCountNonUncommon'),
-  truncated20('runes_most_active_mint',              'runesMostActiveMint',
+  ]),
+  ...inscriptionSizeCols('inscriptions',       'inscriptions',      s => s.inscriptions),
+  ...inscriptionSizeCols('inscriptions_image', 'inscriptionsImage', s => s.inscriptions.image),
+  ...inscriptionSizeCols('inscriptions_text',  'inscriptionsText',  s => s.inscriptions.text),
+  ...inscriptionSizeCols('inscriptions_json',  'inscriptionsJson',  s => s.inscriptions.json),
+  ...sectionCols('inscriptions', 'inscriptions', s => s.inscriptions, [
+    'brotliCount', 'gzipCount', 'compressedEnvelopeBytes',
+  ]),
+  ...sectionCols('cat21', 'cat21', s => s.cat21, [
+    'genesisCount', 'avgFeeRate', 'minFeeRate', 'maxFeeRate',
+  ]),
+  ...sectionCols('runes', 'runes', s => s.runes, [
+    'uniqueMintsCount', 'uniqueMintsCountNonUncommon', 'topMintCount', 'topMintCountNonUncommon',
+  ]),
+  truncatedMostActive('runes_most_active_mint',              'runesMostActiveMint',
               s => s.runes.mostActiveMint,              (t, v) => { t.runes.mostActiveMint = v; }),
-  truncated20('runes_most_active_non_uncommon_mint', 'runesMostActiveNonUncommonMint',
+  truncatedMostActive('runes_most_active_non_uncommon_mint', 'runesMostActiveNonUncommonMint',
               s => s.runes.mostActiveNonUncommonMint,   (t, v) => { t.runes.mostActiveNonUncommonMint = v; }),
-  truncated20('brc20_most_active_mint',              'brc20MostActiveMint',
+  truncatedMostActive('brc20_most_active_mint',              'brc20MostActiveMint',
               s => s.brc20.mostActiveMint,              (t, v) => { t.brc20.mostActiveMint = v; }),
-  truncated20('src20_most_active_mint',              'src20MostActiveMint',
+  truncatedMostActive('src20_most_active_mint',              'src20MostActiveMint',
               s => s.src20.mostActiveMint,              (t, v) => { t.src20.mostActiveMint = v; }),
+  // analyser_version doubles as the "is this row populated?" sentinel —
+  // formatDbBlockIntoOrdpoolStats returns undefined when it's 0.
   {
     col: 'analyser_version', alias: 'analyserVersion',
     val: s => s.version,
     set: (t, v) => { t.version = v; },
   },
 ];
 
+// Static parts of the INSERT — column list, placeholder list, and the SQL
+// string itself. Computed once at module load. Per-call work in
+// saveBlockOrdpoolStatsInDatabase is reduced to one .map() over the spec
+// to materialise the param values.
+const ORDPOOL_STATS_INSERT_SQL = (() => {
+  const cols = ['hash', 'height', ...ORDPOOL_STATS_COLUMNS.map(c => c.col)];
+  const phs  = ['?',    '?',     ...ORDPOOL_STATS_COLUMNS.map(c => c.placeholder ?? '?')];
+  return `INSERT INTO ordpool_stats(${cols.join(', ')}) VALUES (${phs.join(', ')})`;
+})();
+
 
 class OrdpoolBlocksRepository {
   /**
@@ -461,16 +446,11 @@ class OrdpoolBlocksRepository {
 
       const stats = block.extras.ordpoolStats;
 
-      // Single source of truth: column list, placeholder list, and params
-      // array all derive from ORDPOOL_STATS_COLUMNS in the same .map() pass,
-      // so positional drift between them is impossible.
-      const cols         = ['hash', 'height', ...ORDPOOL_STATS_COLUMNS.map(c => c.col)];
-      const placeholders = ['?',    '?',     ...ORDPOOL_STATS_COLUMNS.map(c => c.placeholder ?? '?')];
-      const params       = [block.id, block.height, ...ORDPOOL_STATS_COLUMNS.map(c => c.val(stats))];
-
-      const query = `INSERT INTO ordpool_stats(${cols.join(', ')}) VALUES (${placeholders.join(', ')})`;
-
-      await DB.query(query, params, 'silent');
+      // SQL is precomputed at module load; per-call work is just materialising
+      // the param values. Positional alignment is preserved because both
+      // the SQL and the params iterate ORDPOOL_STATS_COLUMNS in the same order.
+      const params = [block.id, block.height, ...ORDPOOL_STATS_COLUMNS.map(c => c.val(stats))];
+      await DB.query(ORDPOOL_STATS_INSERT_SQL, params, 'silent');
 
       logger.debug(`$saveBlockOrdpoolStatsInDatabase() - Block ${block.height} successfully stored!`, 'Ordpool');
 
@@ -508,9 +488,6 @@ class OrdpoolBlocksRepository {
     result.src20.src20MintActivity    = compactToMintActivity(dbBlk.src20MintActivity);
     result.src20.src20DeployAttempts  = compactToSrc20DeployAttempts(dbBlk.src20DeployAttempts);
     result.cat21.minimalCat21MintActivity = compactToMinimalCat21Mints(dbBlk.cat21MintActivity);
-    // Block-detail responses don't carry the atomical_op /
-    // counterparty per-row satellite arrays — chart endpoints
-    // query those tables directly via GROUP BY.
 
     return result;
   }

frontend/src/app/components/_ordpool/ordpool-stats/ordpool-stats.component.helper.ts

@@ -15,6 +15,7 @@ import {
   Interval,
   MintStatistic,
   NewTokenStatistic,
+  OrdpoolStatisticResponse,
   ProtocolStatistic,
   RuneActivityStatistic,
 } from '../../../../../../backend/src/api/explorer/_ordpool/ordpool-statistics-interface';
@@ -36,14 +37,6 @@ type ExtractStatistic<T extends ChartType> =
   T extends 'counterparty-messages' ? CounterpartyMessagesStatistic :
   never;
 
-/**
- * A utility function to map the chart type to its corresponding data handler.
- * Ensures type safety and clear mappings for each chart type.
- * 
- * @param type - The chart type (e.g., 'mints', 'new-tokens', 'fees', 'inscription-sizes').
- * @param cases - A map of chart types to their respective handlers.
- * @returns A callback function for the specified chart type.
- */
 export function matchType<T extends ChartType>(
   type: T,
   cases: { [K in ChartType]: (stats: ExtractStatistic<K>[]) => LineSeriesOption[] }
@@ -143,10 +136,6 @@ export function getSeriesData<T extends ChartType>(
       { name: 'Top mint count',                                  type: 'line', data: stats.map((stat) => [stat.minTime, stat.topMintCount]) },
       { name: 'Top mint count (excluding ⧉ UNCOMMON•GOODS)',     type: 'line', data: stats.map((stat) => [stat.minTime, stat.topMintCountNonUncommon]) },
     ],
-    // atomical-ops + counterparty-messages return one row per (period, op).
-    // Single aggregate line for now; per-op breakdown is a follow-up
-    // (needs grouping the rows by `operation` / `messageType` and emitting
-    // one series per distinct value — depends on the time-series UI design).
     'atomical-ops': (stats: AtomicalOpsStatistic[]) => [
       { name: 'Atomical operations', type: 'line', data: stats.map((stat) => [stat.minTime, stat.count]) },
     ],
@@ -156,17 +145,9 @@ export function getSeriesData<T extends ChartType>(
   })(statistics);
 }
 
-/**
- * Generates tooltip content based on the chart type.
- * @param type - The chart type.
- * @param stat - The statistics object to generate the tooltip content from.
- * @returns Tooltip HTML content as a string.
- */
 export function getTooltipContent(
   type: ChartType,
-  stat: MintStatistic | NewTokenStatistic | FeeStatistic | InscriptionSizeStatistic | ProtocolStatistic | InscriptionTypeStatistic
-       | InscriptionTypeSizeStatistic | InscriptionTypeFeeStatistic | InscriptionCompressionStatistic
-       | Cat21StatStatistic | RuneActivityStatistic | AtomicalOpsStatistic | CounterpartyMessagesStatistic
+  stat: OrdpoolStatisticResponse,
 ): string {
 
   const baseContent = `