Add minimum daily fee rate backend metric and API

This commit is contained in:
jramos0 2026-07-31 03:43:09 -06:00
parent 22f4172ec3
commit 18a778a59d
12 changed files with 828 additions and 3 deletions

View file

@ -25,6 +25,7 @@ module.exports = async () => {
const tables = [
'blocks_audits',
'blocks_summaries',
'accelerations',
'blocks_prices',
'blocks_templates',
'cpfp_clusters',

View file

@ -0,0 +1,141 @@
import DB from '../database';
import BlocksRepository from '../repositories/BlocksRepository';
import { MIN_FEE_RATE_VERSION } from '../api/mining/min-fee-rate';
import { setupTestDatabase, waitForDatabase, cleanupTestData, insertTestPool, insertTestBlock } from './test-helpers';
/**
* Midday UTC, `daysAgo` days back. Midday rather than midnight so a block never
* lands on the day boundary the aggregation buckets on.
*/
function utcMidday(daysAgo: number): Date {
const now = new Date();
return new Date(Date.UTC(
now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - daysAgo, 12, 0, 0
));
}
describe('min fee rate daily aggregation', () => {
let defaultPoolId: number;
let nextHeight = 940000;
beforeAll(async () => {
await waitForDatabase();
await setupTestDatabase();
}, 120000);
beforeEach(async () => {
await cleanupTestData();
defaultPoolId = await insertTestPool({
name: 'Unknown',
slug: 'unknown',
addresses: '[]',
regexes: '[]',
});
nextHeight = 940000;
});
afterAll(async () => {
await cleanupTestData();
});
async function insertBlockWithRate(options: {
blockTimestamp: Date;
minFeeRate: number | null;
version?: number;
stale?: boolean;
}): Promise<number> {
const height = nextHeight++;
await insertTestBlock({
height,
hash: height.toString(16).padStart(64, '0'),
blockTimestamp: options.blockTimestamp,
poolId: defaultPoolId,
});
await DB.query(
`UPDATE blocks
SET min_fee_rate = ?, min_fee_rate_version = ?, stale = ?,
min_fee_rate_computed_at = CURRENT_TIMESTAMP
WHERE height = ?`,
[
options.minFeeRate,
options.version ?? MIN_FEE_RATE_VERSION,
options.stale ? 1 : 0,
height,
]
);
return height;
}
test('buckets on the UTC day and keeps the lowest rate of each day', async () => {
const lowest = await insertBlockWithRate({ blockTimestamp: utcMidday(3), minFeeRate: 0.12 });
await insertBlockWithRate({ blockTimestamp: utcMidday(3), minFeeRate: 0.4 });
await insertBlockWithRate({ blockTimestamp: utcMidday(2), minFeeRate: 0.25 });
const days = await BlocksRepository.$getMinFeeRatesByDay(null);
expect(days).toHaveLength(2);
expect(days[0].minRate).toBeCloseTo(0.12, 6);
expect(days[0].minHeight).toBe(lowest);
expect(Number(days[0].usableBlockCount)).toBe(2);
expect(days[1].minRate).toBeCloseTo(0.25, 6);
expect(Number(days[1].usableBlockCount)).toBe(1);
// Ascending by day.
expect(Number(days[0].timestamp)).toBeLessThan(Number(days[1].timestamp));
});
test('excludes the current UTC day, whose minimum is still partial', async () => {
await insertBlockWithRate({ blockTimestamp: utcMidday(0), minFeeRate: 0.01 });
await insertBlockWithRate({ blockTimestamp: utcMidday(1), minFeeRate: 0.3 });
const days = await BlocksRepository.$getMinFeeRatesByDay(null);
expect(days).toHaveLength(1);
expect(days[0].minRate).toBeCloseTo(0.3, 6);
});
test('ignores blocks with no rate, a stale version, or a stale chain', async () => {
await insertBlockWithRate({ blockTimestamp: utcMidday(4), minFeeRate: null });
await insertBlockWithRate({
blockTimestamp: utcMidday(4),
minFeeRate: 0.02,
version: MIN_FEE_RATE_VERSION - 1,
});
await insertBlockWithRate({ blockTimestamp: utcMidday(4), minFeeRate: 0.03, stale: true });
await insertBlockWithRate({ blockTimestamp: utcMidday(4), minFeeRate: 0.5 });
const days = await BlocksRepository.$getMinFeeRatesByDay(null);
expect(days).toHaveLength(1);
expect(days[0].minRate).toBeCloseTo(0.5, 6);
expect(Number(days[0].usableBlockCount)).toBe(1);
});
test('applies the requested interval to the returned series', async () => {
await insertBlockWithRate({ blockTimestamp: utcMidday(40), minFeeRate: 0.05 });
await insertBlockWithRate({ blockTimestamp: utcMidday(2), minFeeRate: 0.5 });
const allDays = await BlocksRepository.$getMinFeeRatesByDay(null);
const lastWeek = await BlocksRepository.$getMinFeeRatesByDay('1 WEEK');
expect(allDays).toHaveLength(2);
expect(lastWeek).toHaveLength(1);
expect(lastWeek[0].minRate).toBeCloseTo(0.5, 6);
});
/**
* The day count drives which timespan buttons the graph offers, so it deliberately
* spans all available history rather than the selected window: scoping it to the
* interval would hide the longer options as soon as a shorter one was picked. The
* threshold percentage does not read it that denominator is the returned series.
*/
test('counts every available day regardless of the requested interval', async () => {
await insertBlockWithRate({ blockTimestamp: utcMidday(40), minFeeRate: 0.05 });
await insertBlockWithRate({ blockTimestamp: utcMidday(2), minFeeRate: 0.5 });
const dayCount = await BlocksRepository.$getMinFeeRateDayCount();
const lastWeek = await BlocksRepository.$getMinFeeRatesByDay('1 WEEK');
expect(dayCount).toBe(2);
expect(lastWeek).toHaveLength(1);
});
});

View file

@ -25,6 +25,7 @@ export async function cleanupTestData(): Promise<void> {
const tables = [
'blocks_audits',
'blocks_summaries',
'accelerations',
'blocks_prices',
'blocks_templates',
'cpfp_clusters',

View file

@ -0,0 +1,102 @@
import {
buildOutOfBandCandidates,
computeMinFeeRate,
isMinFeeRateVersionStale,
MIN_FEE_RATE_START_DATE,
MIN_FEE_RATE_VERSION,
MIN_SUMMARY_VERSION,
} from '../../api/mining/min-fee-rate';
import { OutOfBandCandidate } from '../../api/prioritization';
function tx(txid: string, effectiveFeePerVsize: number, cluster?: string[]): OutOfBandCandidate {
return { txid, effectiveFeePerVsize, cluster: cluster || [txid] };
}
const NONE = new Set<string>();
// Block order (index 0 = coinbase); fee rate descends towards the bottom of the block
// in a clean block, matching the convention findOutOfBandTransactions scans against.
describe('computeMinFeeRate', () => {
test('returns the minimum non-coinbase rate for a plain block', () => {
const candidates = [tx('coinbase', 0), tx('c', 10), tx('b', 5), tx('a', 2)];
expect(computeMinFeeRate(candidates, NONE)).toBe(2);
});
test('ignores the coinbase at index 0 regardless of its own exclusion status', () => {
// The coinbase's rate (0) is always below any positive baseline, so it lands in
// the exclusion set too — computeMinFeeRate must not depend on that; it skips
// index 0 positionally.
const candidates = [tx('coinbase', 0), tx('a', 5)];
expect(computeMinFeeRate(candidates, NONE)).toBe(5);
});
test('skips a zero-rate transaction that the exclusion scan does not catch', () => {
// 'zero' is processed first (bottom of the block, baseline still 0), so
// 0 < 0 is false and it is not flagged as prioritized — EXCLUDE_ZERO_RATE is the
// only thing keeping it out of the minimum.
const candidates = [tx('coinbase', 0), tx('c', 6), tx('zero', 0)];
expect(computeMinFeeRate(candidates, NONE)).toBe(6);
});
test('excludes a prioritized transaction and its whole cluster', () => {
const candidates = [
tx('coinbase', 0),
tx('top', 10),
tx('low', 1, ['low', 'parent']),
tx('bottom', 4),
];
expect(computeMinFeeRate(candidates, NONE)).toBe(4);
});
test('excludes an accelerated transaction and its cluster even at a normal rate', () => {
const candidates = [
tx('coinbase', 0),
tx('other', 8),
tx('boosted', 5, ['boosted', 'ancestor']),
];
expect(computeMinFeeRate(candidates, new Set(['boosted']))).toBe(8);
});
test('returns null when no transaction qualifies', () => {
expect(computeMinFeeRate(
[tx('coinbase', 0), tx('only', 3)],
new Set(['only']),
)).toBeNull();
expect(computeMinFeeRate([tx('coinbase', 0)], NONE)).toBeNull();
expect(computeMinFeeRate([], NONE)).toBeNull();
});
});
describe('buildOutOfBandCandidates', () => {
test('reconstructs cluster membership from ancestors and descendants', () => {
const result = buildOutOfBandCandidates([
{ txid: 'child', effectiveFeePerVsize: 3, ancestors: [{ txid: 'parent' }], descendants: [] },
{ txid: 'parent', effectiveFeePerVsize: 3, ancestors: [], descendants: [{ txid: 'child' }] },
]);
expect(result[0]).toEqual({ txid: 'child', effectiveFeePerVsize: 3, cluster: ['child', 'parent'] });
expect(result[1]).toEqual({ txid: 'parent', effectiveFeePerVsize: 3, cluster: ['parent', 'child'] });
});
test('defaults to a single-transaction cluster when there are no relatives', () => {
const result = buildOutOfBandCandidates([{ txid: 'solo', effectiveFeePerVsize: 4 }]);
expect(result).toEqual([{ txid: 'solo', effectiveFeePerVsize: 4, cluster: ['solo'] }]);
});
test('defaults a missing effective rate to 0', () => {
const result = buildOutOfBandCandidates([{ txid: 'coinbase' }]);
expect(result).toEqual([{ txid: 'coinbase', effectiveFeePerVsize: 0, cluster: ['coinbase'] }]);
});
});
describe('min fee rate persistence constants', () => {
test('a version bump makes an older result eligible', () => {
expect(MIN_FEE_RATE_VERSION).toBeGreaterThan(0);
expect(isMinFeeRateVersionStale(MIN_FEE_RATE_VERSION - 1)).toBe(true);
expect(isMinFeeRateVersionStale(MIN_FEE_RATE_VERSION)).toBe(false);
});
test('requires trusted summaries and starts at the Core 30 release day', () => {
expect(MIN_SUMMARY_VERSION).toBe(2);
expect(MIN_FEE_RATE_START_DATE).toBe('2025-10-10 00:00:00');
});
});

View file

@ -34,6 +34,7 @@ import statistics from './statistics/statistics';
import { calcBitsDifference } from './difficulty-adjustment';
import AccelerationRepository from '../repositories/AccelerationRepository';
import { calculateGoodBlockCpfp } from './cpfp';
import { buildOutOfBandCandidates, computeMinFeeRate, MIN_SUMMARY_VERSION } from './mining/min-fee-rate';
import blockProcessor, { BlockProcessingResult, detectTemplateAlgorithm, saveCpfpDataToCpfpSummary } from './block-processor';
import mempool from './mempool';
import CpfpRepository from '../repositories/CpfpRepository';
@ -620,6 +621,36 @@ class Blocks {
});
this.updateTimerProgress(timer, `saved audit results for ${this.currentBlockHeight}`);
}
// Live min_fee_rate: reuse the CPFP pass already computed above instead of running
// a second makeBlockTemplate. Only version >= MIN_SUMMARY_VERSION (calculateGood /
// calculateClusterMempool) carries a CPFP-adjusted rate and per-tx cluster data;
// a Fast-indexed (version 1) block is left for the backfill sweep, which runs
// makeBlockTemplate directly and so covers it regardless of version.
//
// cpfpSummary.transactions here carries rates computed with real poolAccelerations
// fed into makeBlockTemplate (calculateGoodBlockCpfp's own call, upstream of this
// point), while BlocksRepository.$backfillMinFeeRate deliberately uses []. This is
// a known, measured asymmetry: see the doc comment on $backfillMinFeeRate for the
// measurement and why it's accepted rather than unified.
if (cpfpSummary.version >= MIN_SUMMARY_VERSION) {
try {
const accelerationState = await AccelerationRepository.$getMinFeeRateAccelerationStateAtHeight(blockExtended.height);
const candidates = buildOutOfBandCandidates(cpfpSummary.transactions);
const rate = computeMinFeeRate(candidates, new Set(accelerationState.txids));
await blocksRepository.$updateMinFeeRate(blockExtended.height, blockExtended.id, rate, {
accelerationCount: accelerationState.count,
accelerationFingerprint: accelerationState.fingerprint,
});
} catch (e) {
logger.debug(`failed to compute live min_fee_rate for ${blockExtended.height}: ` + (e instanceof Error ? e.message : e));
}
}
// The backfill sweep independently covers Fast-indexed blocks, gaps, and
// algorithm-version upgrades; scheduling it here keeps it reacting to new blocks
// rather than waiting for a sequential indexing pass.
indexer.scheduleSingleTask('minFeeRate', 10000);
}
/**

View file

@ -0,0 +1,131 @@
/**
* Minimum "fee-merit" effective fee rate for a single block (mempool issue #6639).
*
* The metric is the lowest CPFP-effective fee rate among the transactions that
* earned their block inclusion on fee merit alone. Transactions that were boosted
* out-of-band (prioritised via prioritisetransaction, or accelerated) are excluded
* using the same greedy scan the accelerator pricing path uses to price boosts
* (`findOutOfBandTransactions`), not the audit's prioritized/accelerated arrays: the
* audit is a global longest-increasing-subsequence classification with no cluster
* expansion or baseline guard, a different criterion that was not validated against
* this metric's reference figures.
*
* This module is intentionally pure (no DB, no I/O) so the exclusion logic can be
* unit-tested exhaustively.
*/
import { findOutOfBandTransactions, OutOfBandCandidate } from '../prioritization';
/**
* Minimum blocks_summaries.version whose `rate` can be trusted as CPFP-effective.
* Verified in RESEARCH-6639.md §A1: version 0 carries no `rate` field at all, and
* version 1 is ambiguous (effective when esplora-indexed, but nominal via the
* no-cpfpSummary fallback branch in blocks.ts). Only version >= 2 (calculateGood /
* calculateClusterMempool CPFP) guarantees a CPFP-adjusted effective rate.
*/
export const MIN_SUMMARY_VERSION = 2;
/**
* Increment this whenever the algorithm changes. A block is eligible whenever its
* stored version is lower; late persisted inputs are tracked separately by snapshots.
* Bumped to 2: the exclusion criterion changed from the audit's prioritized/accelerated
* arrays to the greedy scan shared with the accelerator pricing path, so every
* previously computed value must be recomputed.
*/
export const MIN_FEE_RATE_VERSION = 2;
/**
* Bitcoin Core 30.0 was released on 2025-10-10 and changed the default
* minrelaytxfee to 0.1 sat/vB. The series is intentionally undefined before then.
*/
export const MIN_FEE_RATE_START_DATE = '2025-10-10 00:00:00';
/**
* Fixed-size, order-independent snapshot of an acceleration set. Keep this exact SQL
* fragment shared by both the persisted-state read and the staleness sweep: using two
* independently maintained expressions would make every block permanently stale as
* soon as they diverged.
*
* COUNT handles cardinality while this 64-bit XOR detects membership changes. Unlike
* GROUP_CONCAT, its result size is independent of the number of accelerations.
*/
export const MIN_FEE_RATE_ACCELERATION_FINGERPRINT_SQL =
`LPAD(HEX(COALESCE(BIT_XOR(CAST(CONV(SUBSTRING(SHA2(txid, 256), 1, 16), 16, 10) AS UNSIGNED)), 0)), 16, '0')`;
export const MIN_FEE_RATE_EMPTY_ACCELERATION_FINGERPRINT = '0000000000000000';
/**
* Whether to skip transactions with a non-positive `rate`. Verified in
* RESEARCH-6639.md §A2/§A3: the coinbase sits at array index 0 with rate 0, and a
* 0-fee 1p1c package parent that CPFP failed to cluster also carries rate 0. Either
* would pin a naive MIN() to 0, so both must be excluded.
*/
export const EXCLUDE_ZERO_RATE = true;
export interface MinFeeRateInputSnapshot {
accelerationCount: number;
accelerationFingerprint: string;
}
export interface MinFeeRateAccelerationState {
txids: string[];
count: number;
fingerprint: string;
}
export interface MinFeeRateDay {
minRate: number;
minHeight: number;
timestamp: number;
usableBlockCount: number;
}
export function isMinFeeRateVersionStale(storedVersion: number): boolean {
return storedVersion < MIN_FEE_RATE_VERSION;
}
/**
* Builds the candidate list `findOutOfBandTransactions` needs from CPFP-summary
* transactions. Cluster membership is reconstructed from `ancestors`/`descendants`
* (populated by `calculateGoodBlockCpfp` for every multi-transaction cluster); a
* transaction with neither is not part of any cluster, so it stands alone.
*/
export function buildOutOfBandCandidates(
transactions: { txid: string; effectiveFeePerVsize?: number; ancestors?: { txid: string }[]; descendants?: { txid: string }[] }[]
): OutOfBandCandidate[] {
return transactions.map(tx => ({
txid: tx.txid,
effectiveFeePerVsize: tx.effectiveFeePerVsize ?? 0,
cluster: (tx.ancestors?.length || tx.descendants?.length)
? [tx.txid, ...(tx.ancestors || []).map(a => a.txid), ...(tx.descendants || []).map(a => a.txid)]
: [tx.txid],
}));
}
/**
* Computes a block's minimum fee-merit effective fee rate: the lowest effective rate
* among transactions `findOutOfBandTransactions` does not flag as prioritized or
* accelerated. A null result is a valid answer for a block with no qualifying
* non-coinbase transaction.
*/
export function computeMinFeeRate(
candidates: readonly OutOfBandCandidate[],
acceleratedTxids: ReadonlySet<string>,
): number | null {
const excluded = findOutOfBandTransactions(candidates, acceleratedTxids);
let min: number | null = null;
// Skip index 0: the coinbase is identified positionally, not by a flag.
for (let i = 1; i < candidates.length; i++) {
const tx = candidates[i];
if (EXCLUDE_ZERO_RATE && tx.effectiveFeePerVsize <= 0) {
continue;
}
if (excluded.has(tx.txid)) {
continue;
}
if (min === null || tx.effectiveFeePerVsize < min) {
min = tx.effectiveFeePerVsize;
}
}
return min;
}

View file

@ -29,6 +29,7 @@ class MiningRoutes {
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/fees', this.$getBlockFeesTimespan)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/rewards/:interval', this.$getHistoricalBlockRewards)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/fee-rates/:interval', this.$getHistoricalBlockFeeRates)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/min-fee-rate/:interval', this.$getMinFeeRates)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/sizes-weights/:interval', this.$getHistoricalBlockSizeAndWeight)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/difficulty-adjustments/:interval', this.$getDifficultyAdjustments)
.get(config.MEMPOOL.API_URL_PREFIX + 'mining/blocks/predictions/:interval', this.$getHistoricalBlocksHealth)
@ -268,6 +269,29 @@ class MiningRoutes {
}
}
private async $getMinFeeRates(req: Request, res: Response) {
try {
const minFeeRates = await mining.$getMinFeeRates(req.params.interval);
// Deliberately the unfiltered count, not the selected interval's: this header
// only feeds the frontend's period-button visibility guards (stats.dayCount >=
// N), which must see the full history to decide whether 3M/6M/1Y etc. exist,
// regardless of which period is currently selected. The CDF's threshold
// percentage does NOT read this header — it uses data.length, which is already
// period-local by construction. Scoping this to the interval would break the
// period selector: picking 1M would hide 3M/6M until a reload. Matches the
// convention of every other route in this file ($getPools, $getPoolsHistoricalHashrate,
// etc.), which all report the unfiltered count for the same reason.
const dayCount = await BlocksRepository.$getMinFeeRateDayCount();
res.header('Pragma', 'public');
res.header('Cache-control', 'public');
res.header('X-total-count', dayCount.toString());
res.setHeader('Expires', new Date(Date.now() + 1000 * 60).toUTCString());
res.json(minFeeRates);
} catch (e) {
handleError(req, res, 500, 'Failed to get minimum daily fee rates');
}
}
private async $getHistoricalBlockSizeAndWeight(req: Request, res: Response) {
try {
const blockSizes = await mining.$getHistoricalBlockSizes(req.params.interval);

View file

@ -1,5 +1,6 @@
import { BlockPrice, PoolInfo, PoolStats, RewardStats } from '../../mempool.interfaces';
import BlocksRepository from '../../repositories/BlocksRepository';
import { MinFeeRateDay } from './min-fee-rate';
import PoolsRepository from '../../repositories/PoolsRepository';
import HashratesRepository from '../../repositories/HashratesRepository';
import bitcoinClient from '../bitcoin/bitcoin-client';
@ -87,6 +88,17 @@ class Mining {
);
}
/**
* Get the minimum fee-merit effective fee rate per UTC day (issue #6639).
* Fixed calendar-day buckets, so no rolling DIV time range is used only the
* optional interval window filter.
*/
public async $getMinFeeRates(interval: string | null = null): Promise<MinFeeRateDay[]> {
return await BlocksRepository.$getMinFeeRatesByDay(
Common.getSqlInterval(interval)
);
}
/**
* Get historical block sizes
*/

View file

@ -19,7 +19,7 @@ export interface CoreIndex {
best_block_height: number;
}
type TaskName = 'blocksPrices' | 'coinStatsIndex';
type TaskName = 'blocksPrices' | 'coinStatsIndex' | 'minFeeRate';
class Indexer {
private runIndexer = true;
@ -162,6 +162,15 @@ class Indexer {
logger.debug(`failed to index coinstatsindex: ` + (e instanceof Error ? e.message : e));
}
} break;
case 'minFeeRate': {
logger.debug(`Backfilling min_fee_rate now`, logger.tags.mining);
try {
await BlocksRepository.$backfillMinFeeRate();
} catch (e) {
logger.debug(`failed to backfill min_fee_rate: ` + (e instanceof Error ? e.message : e));
}
} break;
}
this.tasksRunning[task] = false;

View file

@ -12,6 +12,11 @@ import bitcoinApi from '../api/bitcoin/bitcoin-api-factory';
import transactionUtils from '../api/transaction-utils';
import { BlockExtended, MempoolTransactionExtended } from '../mempool.interfaces';
import { makeBlockTemplate } from '../api/mini-miner';
import {
MinFeeRateAccelerationState,
MIN_FEE_RATE_ACCELERATION_FINGERPRINT_SQL,
MIN_FEE_RATE_EMPTY_ACCELERATION_FINGERPRINT,
} from '../api/mining/min-fee-rate';
export interface PublicAcceleration {
txid: string,
@ -93,6 +98,42 @@ class AccelerationRepository {
return null;
}
/**
* Returns every acceleration txid plus a stable snapshot of the set for a block.
* Reads straight from the accelerations table (not gated by MEMPOOL_SERVICES), since
* the min fee rate pull sweep uses this to detect late input changes.
* @asyncSafe
*/
public async $getMinFeeRateAccelerationStateAtHeight(height: number): Promise<MinFeeRateAccelerationState> {
try {
const [rows]: any[] = await DB.query(`
SELECT
accelerations.txid,
snapshot.count,
snapshot.fingerprint
FROM (
SELECT
COUNT(*) AS count,
${MIN_FEE_RATE_ACCELERATION_FINGERPRINT_SQL} AS fingerprint
FROM accelerations
WHERE height = ?
) AS snapshot
LEFT JOIN accelerations ON accelerations.height = ?
ORDER BY accelerations.txid
`, [height, height]);
return {
// One row per txid keeps the exclusion set independent of aggregate-size
// limits. The LEFT JOIN also yields one snapshot row for an empty set.
txids: rows.flatMap(row => row.txid == null ? [] : [row.txid]),
count: rows[0]?.count || 0,
fingerprint: rows[0]?.fingerprint || MIN_FEE_RATE_EMPTY_ACCELERATION_FINGERPRINT,
};
} catch (e) {
logger.err(`Cannot get min fee rate acceleration state at height ${height}. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
public async $getAccelerationInfo(poolSlug: string | null = null, height: number | null = null, interval: string | null = null): Promise<PublicAcceleration[]> {
if (!interval || !['24h', '3d', '1w', '1m'].includes(interval)) {
interval = '1m';

View file

@ -121,6 +121,34 @@ class BlocksAuditRepositories {
}
}
/**
* Lean fetch of just the out-of-band exclusion arrays for a block. Returns null
* when no audit row exists (the metric is then unavailable see min-fee-rate.ts).
* Unlike $getBlockAudit this does not join blocks_templates, so it still resolves
* for audited blocks whose template row is missing.
* @asyncSafe
*/
public async $getBlockAuditExclusions(hash: string): Promise<{ version: number, prioritizedTxs: string[], acceleratedTxs: string[] } | null> {
try {
const [rows]: any[] = await DB.query(
`SELECT version, prioritized_txs as prioritizedTxs, accelerated_txs as acceleratedTxs
FROM blocks_audits WHERE hash = ?`,
[hash]
);
if (!rows.length) {
return null;
}
return {
version: rows[0].version,
prioritizedTxs: JSON.parse(rows[0].prioritizedTxs),
acceleratedTxs: JSON.parse(rows[0].acceleratedTxs),
};
} catch (e) {
logger.err(`Cannot get block audit exclusions for ${hash}. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/** @asyncSafe */
public async $getBlockTemplateAlgo(hash: string): Promise<TemplateAlgorithm | null> {
try {
@ -325,4 +353,3 @@ class BlocksAuditRepositories {
}
export default new BlocksAuditRepositories();

View file

@ -1,5 +1,5 @@
import bitcoinApi, { bitcoinCoreApi } from '../api/bitcoin/bitcoin-api-factory';
import { BlockExtended, BlockExtension, BlockPrice, EffectiveFeeStats } from '../mempool.interfaces';
import { BlockExtended, BlockExtension, BlockPrice, EffectiveFeeStats, MempoolTransactionExtended } from '../mempool.interfaces';
import DB from '../database';
import logger from '../logger';
import { Common } from '../api/common';
@ -13,6 +13,17 @@ import config from '../config';
import chainTips from '../api/chain-tips';
import blocks from '../api/blocks';
import BlocksAuditsRepository from './BlocksAuditsRepository';
import AccelerationRepository from './AccelerationRepository';
import {
computeMinFeeRate,
MinFeeRateDay,
MinFeeRateInputSnapshot,
MIN_FEE_RATE_ACCELERATION_FINGERPRINT_SQL,
MIN_FEE_RATE_START_DATE,
MIN_FEE_RATE_VERSION,
} from '../api/mining/min-fee-rate';
import { OutOfBandCandidate } from '../api/prioritization';
import { makeBlockTemplate } from '../api/mini-miner';
import transactionUtils from '../api/transaction-utils';
import { parseDATUMTemplateCreator, parseDMNDTemplateCreator } from '../utils/bitcoin-script';
import poolsUpdater from '../tasks/pools-updater';
@ -1426,6 +1437,300 @@ class BlocksRepository {
}
return blocksMigrated;
}
/**
* Blocks whose persisted metric is older than the current algorithm. No dependency
* on blocks_summaries: the backfill fetches the full block itself and runs
* makeBlockTemplate directly, so it covers every block regardless of which CPFP
* producer originally indexed it.
*/
public async $getBlocksNeedingMinFeeRate(limit: number): Promise<{ height: number, hash: string }[]> {
try {
const [blocks]: any[] = await DB.query(`
SELECT height, hash
FROM blocks
WHERE min_fee_rate_version < ${MIN_FEE_RATE_VERSION}
AND stale = 0
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00') >= ?
ORDER BY height DESC
LIMIT ?
`, [MIN_FEE_RATE_START_DATE, limit]);
return blocks;
} catch (e) {
logger.err(`Cannot get blocks needing min_fee_rate. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/**
* Blocks whose acceleration set no longer matches the input snapshot stored with the
* current result (a late-arriving accelerated txid for an already-computed block).
* The indexed block-side predicate keeps this pull sweep bounded to current,
* canonical results.
*/
public async $getBlocksWithChangedMinFeeRateInputs(limit: number): Promise<{ height: number, hash: string }[]> {
try {
const [blocks]: any[] = await DB.query(`
SELECT blocks.height, blocks.hash
FROM blocks
LEFT JOIN accelerations ON accelerations.height = blocks.height
WHERE blocks.min_fee_rate_version = ${MIN_FEE_RATE_VERSION}
AND blocks.stale = 0
AND CONVERT_TZ(blocks.blockTimestamp, @@session.time_zone, '+00:00') >= ?
GROUP BY
blocks.height,
blocks.hash,
blocks.min_fee_rate_acceleration_count,
blocks.min_fee_rate_acceleration_fingerprint,
blocks.min_fee_rate_computed_at
HAVING
blocks.min_fee_rate_acceleration_count <> COUNT(accelerations.txid)
OR blocks.min_fee_rate_acceleration_fingerprint <>
${MIN_FEE_RATE_ACCELERATION_FINGERPRINT_SQL}
ORDER BY blocks.min_fee_rate_computed_at ASC, blocks.height DESC
LIMIT ?
`, [MIN_FEE_RATE_START_DATE, limit]);
return blocks;
} catch (e) {
logger.err(`Cannot get blocks with changed min_fee_rate inputs. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/** Persist a result and the exact input snapshot used to compute it. */
public async $updateMinFeeRate(
height: number,
hash: string,
rate: number | null,
snapshot: MinFeeRateInputSnapshot
): Promise<void> {
try {
await DB.query(
`UPDATE blocks SET
min_fee_rate = ?,
min_fee_rate_version = ?,
min_fee_rate_acceleration_count = ?,
min_fee_rate_acceleration_fingerprint = ?,
min_fee_rate_computed_at = CURRENT_TIMESTAMP
WHERE height = ? AND hash = ?`,
[
rate,
MIN_FEE_RATE_VERSION,
snapshot.accelerationCount,
snapshot.accelerationFingerprint,
height,
hash,
]
);
} catch (e) {
logger.err(`Cannot update min_fee_rate for block ${height} (${hash}). Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/**
* Minimum fee-merit effective fee rate per UTC calendar day (issue #6639).
* Unlike the rolling DIV-bucket mining charts, this buckets on the fixed UTC day so
* the "minimum daily fee rate" is stable regardless of the selected interval.
* The current UTC day is excluded because its partial MIN is biased upward.
* @asyncSafe
*/
public async $getMinFeeRatesByDay(interval: string | null): Promise<MinFeeRateDay[]> {
try {
let query = `
WITH eligible AS (
SELECT
height,
min_fee_rate,
DATE(CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00')) AS utcDay
FROM blocks
WHERE stale = 0
AND min_fee_rate_version = ${MIN_FEE_RATE_VERSION}
AND min_fee_rate IS NOT NULL
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00') >= ?
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00') < UTC_DATE()`;
if (interval !== null) {
query += `
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00')
>= DATE_SUB(UTC_DATE(), INTERVAL ${interval})`;
}
query += `
),
ranked AS (
SELECT
height,
min_fee_rate,
utcDay,
ROW_NUMBER() OVER (
PARTITION BY utcDay
ORDER BY min_fee_rate ASC, height ASC
) AS dailyRank,
COUNT(*) OVER (PARTITION BY utcDay) AS usableBlockCount
FROM eligible
)
SELECT
CAST(min_fee_rate AS DOUBLE) AS minRate,
height AS minHeight,
TIMESTAMPDIFF(SECOND, '1970-01-01 00:00:00', utcDay) AS timestamp,
usableBlockCount
FROM ranked
WHERE dailyRank = 1
ORDER BY utcDay`;
const [rows]: any = await DB.query(query, [MIN_FEE_RATE_START_DATE]);
return rows;
} catch (e) {
logger.err(`Cannot generate min fee rates by day. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/**
* Count complete UTC days that have at least one usable metric value. This is the
* same unit used by the graph's timespan selector.
*/
public async $getMinFeeRateDayCount(): Promise<number> {
try {
const [rows]: any[] = await DB.query(`
SELECT COUNT(DISTINCT DATE(CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00'))) AS count
FROM blocks
WHERE stale = 0
AND min_fee_rate_version = ${MIN_FEE_RATE_VERSION}
AND min_fee_rate IS NOT NULL
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00') >= ?
AND CONVERT_TZ(blockTimestamp, @@session.time_zone, '+00:00') < UTC_DATE()
`, [MIN_FEE_RATE_START_DATE]);
return rows[0]?.count || 0;
} catch (e) {
logger.err(`Cannot count minimum fee rate days. Reason: ` + (e instanceof Error ? e.message : e));
throw e;
}
}
/**
* Backfill blocks.min_fee_rate by fetching each block's full transactions (with
* `vin`, unlike blocks_summaries) and running makeBlockTemplate directly, the same
* criterion the live path derives from calculateGoodBlockCpfp's pass and the exact
* one calculateBoostRate uses to price accelerator boosts. This makes the metric
* independent of which CPFP producer originally indexed a block, eliminating the
* Fast-vs-Good divergence (a real "different value depending on when it was
* processed" bug, measured and confirmed fixed: see the acceleration-parity
* measurement below for the one input this does NOT unify).
*
* accelerations is deliberately passed as [] to makeBlockTemplate here, while the
* live path (blocks.ts $saveBlockData) passes calculateGoodBlockCpfp's real
* poolAccelerations. This is a known, measured asymmetry, not an oversight:
*
* - accelerations=[] is the configuration RESEARCH-6639.md validated against the
* reference figures (6% of days <=0.1 sat/vB, p50 0.15, max 0.63). Passing real
* max_bid values here would ship a configuration never checked against them.
* - Aligning the live path to [] instead would mean it can no longer reuse the
* calculateGoodBlockCpfp pass already computed for CPFP, giving up the measured
* 0.5% marginal cost and putting a ~76ms template rebuild on block arrival.
*
* Measured impact (2,394 comparisons: 800 real blocks x 3 synthetic acceleration
* densities, real accelerations vs [] into makeBlockTemplate, same helper applied to
* both): the excluded set differs in 98% of blocks and the per-block minimum in ~6%,
* with a statistically significant upward bias when real accelerations are present
* (62.5% of differing cases higher, sign-test p=0.003) a low-rate transaction
* absorbed into a boosted cluster inherits its higher effective rate. Aggregated to
* the published daily minimum (what actually ships), only 1.8% of sampled days
* differ, by under 0.004 sat/vB but that figure comes from a sparse per-day sample
* (~3 of a day's ~144 blocks) and likely understates the true rate at full coverage.
* No sampled block landed at or below the 0.1 sat/vB reference threshold (minimum
* observed: 0.103), so whether a real block ever crosses it differently between the
* two paths remains untested by this measurement, not disproven.
*
* The standard this asymmetry has to clear is narrower than the one Fast-vs-Good
* failed: not "does not diverge", but "does not diverge on the published metric".
* Real accelerations are typically absent on both paths in production (the
* acceleration service is opt-in), so most blocks see [] on both sides regardless.
*
* Each run processes at most one algorithm-version batch and one smaller
* low-priority input-change sweep; neither queue is drained in one invocation. A
* single block's RPC/compute failure is logged and skipped rather than aborting the
* rest of the batch, since this path now depends on Core RPC per block.
* @asyncSafe
*/
public async $backfillMinFeeRate(): Promise<number> {
const batchSize = 1000;
const sweepBatchSize = 100;
let blocksProcessed = 0;
try {
let timer = Date.now() / 1000;
const startedAt = Date.now() / 1000;
const processBatch = async (batch: { height: number, hash: string }[]): Promise<void> => {
for (const row of batch) {
try {
let transactions: MempoolTransactionExtended[] | undefined;
if (config.MEMPOOL.BACKEND === 'esplora') {
transactions = (await bitcoinApi.$getTxsForBlock(row.hash, true)).map(tx => transactionUtils.extendMempoolTransaction(tx));
}
if (!transactions) {
const block = await bitcoinClient.getBlock(row.hash, 2);
transactions = block.tx.map(tx => {
tx.fee *= 100_000_000;
return tx;
});
}
if (!transactions?.length) {
throw new Error(`missing transaction data`);
}
const accelerationState = await AccelerationRepository.$getMinFeeRateAccelerationStateAtHeight(row.height);
const acceleratedTxids = new Set(accelerationState.txids);
const template = makeBlockTemplate(transactions, [], 1, Infinity, Infinity);
const templateMap = new Map(template.map(tx => [tx.txid, tx]));
const candidates: OutOfBandCandidate[] = transactions.map(tx => {
const templateTx = templateMap.get(tx.txid);
return {
txid: tx.txid,
effectiveFeePerVsize: templateTx?.effectiveFeePerVsize ?? 0,
cluster: templateTx?.cluster || [tx.txid],
};
});
const rate = computeMinFeeRate(candidates, acceleratedTxids);
await this.$updateMinFeeRate(row.height, row.hash, rate, {
accelerationCount: accelerationState.count,
accelerationFingerprint: accelerationState.fingerprint,
});
blocksProcessed++;
} catch (e) {
logger.err(`Cannot backfill min_fee_rate for block ${row.height} (${row.hash}), skipping. Reason: ` + (e instanceof Error ? e.message : e));
}
const elapsedSeconds = (Date.now() / 1000) - timer;
if (elapsedSeconds > 5) {
const runningFor = (Date.now() / 1000) - startedAt;
const blockPerSeconds = blocksProcessed / elapsedSeconds;
logger.debug(`Backfilling min_fee_rate | ~${blockPerSeconds.toFixed(2)} blocks/sec | height: ${row.height} | total: ${blocksProcessed} | elapsed: ${runningFor.toFixed(2)} seconds`);
timer = Date.now() / 1000;
}
}
};
const versionBatch = await this.$getBlocksNeedingMinFeeRate(batchSize);
await processBatch(versionBatch);
const changedInputsBatch = await this.$getBlocksWithChangedMinFeeRateInputs(sweepBatchSize);
await processBatch(changedInputsBatch);
if (blocksProcessed > 0) {
logger.notice(`Backfilling min_fee_rate completed: processed ${blocksProcessed} blocks`);
}
} catch (e) {
logger.err(`Backfilling min_fee_rate failed. Trying again later. Reason: ${(e instanceof Error ? e.message : e)}`);
throw e;
}
return blocksProcessed;
}
}
export default new BlocksRepository();