feat: include tenure-height in block responses (#2134)

* feat: include tenure-height in block responses

* feat: add tenure_height to block endpoint responses

* test: fix tests

* test: add tests for tenure-height in block responses

Author: zone117x

migrations/1729520843350_stacks_block_tenure-height.js

@@ -0,0 +1,12 @@
+/* eslint-disable camelcase */
+
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.up = pgm => {
+
+  pgm.addColumn('blocks', {
+    tenure_height: {
+      type: 'integer',
+    }
+  });
+
+};

src/api/controllers/db-controller.ts

@@ -674,6 +674,8 @@ function parseDbBlock(
       dbBlock.block_time > 0
         ? unixEpochToIso(dbBlock.block_time)
         : unixEpochToIso(dbBlock.burn_block_time),
+    // If `tenure_height` is not available, but `signer_bitvec` is set we can safely assume it's same as `block_height` (epoch2.x rules)
+    tenure_height: dbBlock.tenure_height ?? (dbBlock.signer_bitvec ? -1 : dbBlock.block_height),
     index_block_hash: dbBlock.index_block_hash,
     parent_block_hash: dbBlock.parent_block_hash,
     burn_block_time: dbBlock.burn_block_time,

src/api/routes/v2/helpers.ts

@@ -31,6 +31,8 @@ export function parseDbNakamotoBlock(block: DbBlock): NakamotoBlock {
     hash: block.block_hash,
     block_time: block.block_time,
     block_time_iso: unixEpochToIso(block.block_time),
+    // If `tenure_height` is not available, but `signer_bitvec` is set we can safely assume it's same as `block_height` (epoch2.x rules)
+    tenure_height: block.tenure_height ?? (block.signer_bitvec ? -1 : block.block_height),
     index_block_hash: block.index_block_hash,
     parent_block_hash: block.parent_block_hash,
     parent_index_block_hash: block.parent_index_block_hash,

src/api/schemas/entities/block.ts

@@ -17,6 +17,9 @@ export const BlockSchema = Type.Object(
     block_time_iso: Type.String({
       description: 'An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.',
     }),
+    tenure_height: Type.Integer({
+      description: 'The tenure height (AKA coinbase height) of this block',
+    }),
     index_block_hash: Type.String({
       description:
         'The only hash that can uniquely identify an anchored block or an unconfirmed state trie',
@@ -93,6 +96,9 @@ export const NakamotoBlockSchema = Type.Object({
   block_time_iso: Type.String({
     description: 'An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.',
   }),
+  tenure_height: Type.Integer({
+    description: 'The tenure height (AKA coinbase height) of this block',
+  }),
   index_block_hash: Type.String({
     description:
       'The only hash that can uniquely identify an anchored block or an unconfirmed state trie',

src/datastore/common.ts

@@ -26,6 +26,7 @@ export interface DbBlock {
   block_time: number;
   signer_bitvec: string | null;
   signer_signatures: string[] | null;
+  tenure_height: number | null;
 }
 
 /** An interface representing the microblock data that can be constructed _only_ from the /new_microblocks payload */
@@ -863,6 +864,7 @@ export interface BlockQueryResult {
   execution_cost_write_length: string;
   tx_count: number;
   signer_bitvec: string | null;
+  tenure_height: number | null;
 }
 
 export interface MicroblockQueryResult {
@@ -1288,6 +1290,7 @@ export interface BlockInsertValues {
   tx_count: number;
   signer_bitvec: string | null;
   signer_signatures: PgBytea[] | null;
+  tenure_height: number | null;
 }
 
 export interface MicroblockInsertValues {

src/datastore/helpers.ts

@@ -186,6 +186,7 @@ export const BLOCK_COLUMNS = [
   'execution_cost_write_length',
   'tx_count',
   'signer_bitvec',
+  'tenure_height',
 ];
 
 export const MICROBLOCK_COLUMNS = [
@@ -465,7 +466,6 @@ export function parseFaucetRequestQueryResult(result: FaucetRequestQueryResult):
 }
 
 export function parseBlockQueryResult(row: BlockQueryResult): DbBlock {
-  // TODO(mb): is the tx_index preserved between microblocks and committed anchor blocks?
   const block: DbBlock = {
     block_hash: row.block_hash,
     index_block_hash: row.index_block_hash,
@@ -488,6 +488,7 @@ export function parseBlockQueryResult(row: BlockQueryResult): DbBlock {
     tx_count: row.tx_count,
     signer_bitvec: row.signer_bitvec,
     signer_signatures: null, // this field is not queried from db by default due to size constraints
+    tenure_height: row.tenure_height,
   };
   return block;
 }

src/datastore/pg-write-store.ts

@@ -483,6 +483,7 @@ export class PgWriteStore extends PgStore {
       tx_count: block.tx_count,
       signer_bitvec: block.signer_bitvec,
       signer_signatures: block.signer_signatures,
+      tenure_height: block.tenure_height,
     };
     const result = await sql`
       INSERT INTO blocks ${sql(values)}
@@ -3384,6 +3385,7 @@ export class PgWriteStore extends PgStore {
       tx_count: block.tx_count,
       signer_bitvec: block.signer_bitvec,
       signer_signatures: block.signer_signatures,
+      tenure_height: block.tenure_height,
     }));
     await sql`
       INSERT INTO blocks ${sql(values)}

src/event-stream/core-node-message.ts

@@ -308,6 +308,8 @@ export interface CoreNodeBlockMessage {
   pox_v3_unlock_height?: number;
   /** Available starting in epoch3, only included in blocks where the pox cycle rewards are first calculated */
   cycle_number?: number;
+  /** AKA `coinbase_height`. In epoch2.x this is the same as `block_height`. In epoch3 this is used to track tenure heights. Only available starting in stacks-core 3.0.0.0.0-rc6 */
+  tenure_height?: number | null;
   /** Available starting in epoch3, only included in blocks where the pox cycle rewards are first calculated */
   reward_set?: {
     pox_ustx_threshold: string; // "666720000000000"

src/event-stream/event-server.ts

@@ -1020,6 +1020,12 @@ export function parseNewBlockMessage(
       }
     );
 
+  if (typeof msg.tenure_height !== 'number' && msg.signer_bitvec) {
+    logger.warn(
+      `Nakamoto block ${msg.block_height} event payload has no tenure_height. Use stacks-core version 3.0.0.0.0-rc6 or newer!`
+    );
+  }
+
   const dbBlock: DbBlock = {
     canonical: true,
     block_hash: msg.block_hash,
@@ -1042,6 +1048,7 @@ export function parseNewBlockMessage(
     block_time: blockData.block_time,
     signer_bitvec: signerBitvec,
     signer_signatures: signerSignatures,
+    tenure_height: msg.tenure_height ?? null,
   };
 
   logger.debug(`Received block ${msg.block_hash} (${msg.block_height}) from node`, dbBlock);

tests/api/address.test.ts

@@ -80,6 +80,7 @@ describe('address tests', () => {
       parent_microblock_hash: '',
       parent_microblock_sequence: 0,
       block_height: 1,
+      tenure_height: 1,
       block_time: 39486,
       burn_block_time: 39486,
       burn_block_hash: '0x1234',
@@ -1157,6 +1158,7 @@ describe('address tests', () => {
       parent_microblock_hash: '',
       parent_microblock_sequence: 0,
       block_height: 1,
+      tenure_height: 1,
       block_time: 39486,
       burn_block_time: 39486,
       burn_block_hash: '0x1234',
@@ -2375,6 +2377,7 @@ describe('address tests', () => {
       parent_microblock_hash: '',
       parent_microblock_sequence: 0,
       block_height: 1,
+      tenure_height: 1,
       block_time: 1594647995,
       burn_block_time: 1594647995,
       burn_block_hash: '0x1234',