feat: support for Stacks 2.1 coinbase-pay-to-alt-recipient txs (#1283)

* feat: support Stacks 2.1 `coinbase-pay-to-alt` tx types

* fix: add a `coinbase-to-alt` tx handling in a few more areas

* chore: fix coinbase in mempool table schema

* chore: update unit tests with new coinbase payload responses

* test: add tests for ingesting new coinbase tx payloads and generating expected API responses

* docs: better description for coinbase alt recipient

Author: zone117x

docs/entities/transactions/transaction-4-coinbase-metadata.schema.json

@@ -17,6 +17,11 @@
         "data": {
           "type": "string",
           "description": "Hex encoded 32-byte scratch space for block leader's use"
+        },
+        "alt_recipient": {
+          "type": "string",
+          "nullable": true,
+          "description": "A principal that will receive the miner rewards for this coinbase transaction. Can be either a standard principal or contract principal. Only specified for `coinbase-to-alt-recipient` transaction types, otherwise null."
         }
       }
     }

docs/generated.d.ts

@@ -1091,6 +1091,10 @@ export interface CoinbaseTransactionMetadata {
      * Hex encoded 32-byte scratch space for block leader's use
      */
     data: string;
+    /**
+     * A principal that will receive the miner rewards for this coinbase transaction. Can be either a standard principal or contract principal. Only specified for `coinbase-to-alt-recipient` transaction types, otherwise null.
+     */
+    alt_recipient?: string;
   };
 }
 /**

src/api/controllers/db-controller.ts

@@ -91,6 +91,7 @@ export function getTxTypeString(typeId: DbTxTypeId): Transaction['tx_type'] {
     case DbTxTypeId.PoisonMicroblock:
       return 'poison_microblock';
     case DbTxTypeId.Coinbase:
+    case DbTxTypeId.CoinbaseToAltRecipient:
       return 'coinbase';
     default:
       throw new Error(`Unexpected DbTxTypeId: ${typeId}`);
@@ -121,7 +122,7 @@ export function getTxTypeId(typeString: Transaction['tx_type']): DbTxTypeId[] {
     case 'poison_microblock':
       return [DbTxTypeId.PoisonMicroblock];
     case 'coinbase':
-      return [DbTxTypeId.Coinbase];
+      return [DbTxTypeId.Coinbase, DbTxTypeId.CoinbaseToAltRecipient];
     default:
       throw new Error(`Unexpected tx type string: ${typeString}`);
   }
@@ -534,7 +535,10 @@ async function getRosettaBlockTxFromDataStore(opts: {
   let minerRewards: DbMinerReward[] = [],
     unlockingEvents: StxUnlockEvent[] = [];
 
-  if (opts.tx.type_id === DbTxTypeId.Coinbase) {
+  if (
+    opts.tx.type_id === DbTxTypeId.Coinbase ||
+    opts.tx.type_id === DbTxTypeId.CoinbaseToAltRecipient
+  ) {
     minerRewards = await opts.db.getMinersRewardsAtHeight({
       blockHeight: opts.block.block_height,
     });
@@ -742,6 +746,20 @@ function parseDbTxTypeMetadata(dbTx: DbTx | DbMempoolTx): TransactionMetadata {
         tx_type: 'coinbase',
         coinbase_payload: {
           data: unwrapOptional(dbTx.coinbase_payload, () => 'Unexpected nullish coinbase_payload'),
+          alt_recipient: null as any,
+        },
+      };
+      return metadata;
+    }
+    case DbTxTypeId.CoinbaseToAltRecipient: {
+      const metadata: CoinbaseTransactionMetadata = {
+        tx_type: 'coinbase',
+        coinbase_payload: {
+          data: unwrapOptional(dbTx.coinbase_payload, () => 'Unexpected nullish coinbase_payload'),
+          alt_recipient: unwrapOptional(
+            dbTx.coinbase_alt_recipient,
+            () => 'Unexpected nullish coinbase_alt_recipient'
+          ),
         },
       };
       return metadata;

src/datastore/common.ts

@@ -180,6 +180,9 @@ export interface DbTx extends BaseTx {
   /** Only valid for `coinbase` tx types. Hex encoded 32-bytes. */
   coinbase_payload?: string;
 
+  /** Only valid for `coinbase-to-alt-recipient` tx types. Either a standard principal or contract principal. */
+  coinbase_alt_recipient?: string;
+
   event_count: number;
 
   execution_cost_read_count: number;
@@ -249,6 +252,9 @@ export interface DbMempoolTx extends BaseTx {
 
   /** Only valid for `coinbase` tx types. Hex encoded 32-bytes. */
   coinbase_payload?: string;
+
+  /** Only valid for `coinbase-to-alt-recipient` tx types. Either a standard principal or contract principal. */
+  coinbase_alt_recipient?: string;
 }
 
 export interface DbSmartContract {
@@ -694,6 +700,9 @@ export interface MempoolTxQueryResult {
   // `coinbase` tx types
   coinbase_payload?: string;
 
+  /** Only valid for `coinbase-to-alt-recipient` tx types. Either a standard principal or contract principal. */
+  coinbase_alt_recipient?: string;
+
   // sending abi in case tx is contract call
   abi: unknown | null;
 }
@@ -752,6 +761,9 @@ export interface TxQueryResult {
   // `coinbase` tx types
   coinbase_payload?: string;
 
+  // `coinbase-to-alt-recipient` tx types
+  coinbase_alt_recipient?: string;
+
   // events count
   event_count: number;
 
@@ -903,6 +915,7 @@ export interface TxInsertValues {
   poison_microblock_header_1: PgBytea | null;
   poison_microblock_header_2: PgBytea | null;
   coinbase_payload: PgBytea | null;
+  coinbase_alt_recipient: string | null;
   raw_result: PgBytea;
   event_count: number;
   execution_cost_read_count: number;
@@ -941,6 +954,7 @@ export interface MempoolTxInsertValues {
   poison_microblock_header_1: PgBytea | null;
   poison_microblock_header_2: PgBytea | null;
   coinbase_payload: PgBytea | null;
+  coinbase_alt_recipient: string | null;
 }
 
 export interface BlockInsertValues {

src/datastore/helpers.ts

@@ -83,6 +83,7 @@ export const TX_COLUMNS = [
   'poison_microblock_header_1',
   'poison_microblock_header_2',
   'coinbase_payload',
+  'coinbase_alt_recipient',
   'raw_result',
   'event_count',
   'execution_cost_read_count',
@@ -121,6 +122,7 @@ export const MEMPOOL_TX_COLUMNS = [
   'poison_microblock_header_1',
   'poison_microblock_header_2',
   'coinbase_payload',
+  'coinbase_alt_recipient',
 ];
 
 export const BLOCK_COLUMNS = [
@@ -313,6 +315,9 @@ function parseTxTypeSpecificQueryResult(
     target.poison_microblock_header_2 = result.poison_microblock_header_2;
   } else if (target.type_id === DbTxTypeId.Coinbase) {
     target.coinbase_payload = result.coinbase_payload;
+  } else if (target.type_id === DbTxTypeId.CoinbaseToAltRecipient) {
+    target.coinbase_payload = result.coinbase_payload;
+    target.coinbase_alt_recipient = result.coinbase_alt_recipient;
   } else {
     throw new Error(`Received unexpected tx type_id from db query: ${target.type_id}`);
   }
@@ -731,6 +736,15 @@ function extractTransactionPayload(txData: DecodedTxResult, dbTx: DbTx | DbMempo
       dbTx.coinbase_payload = txData.payload.payload_buffer;
       break;
     }
+    case TxPayloadTypeID.CoinbaseToAltRecipient: {
+      dbTx.coinbase_payload = txData.payload.payload_buffer;
+      if (txData.payload.recipient.type_id === PrincipalTypeID.Standard) {
+        dbTx.coinbase_alt_recipient = txData.payload.recipient.address;
+      } else {
+        dbTx.coinbase_alt_recipient = `${txData.payload.recipient.address}.${txData.payload.recipient.contract_name}`;
+      }
+      break;
+    }
     default:
       throw new Error(`Unexpected transaction type ID: ${JSON.stringify(txData.payload)}`);
   }

src/datastore/pg-store.ts

@@ -3686,7 +3686,7 @@ export class PgStore {
       SELECT tx_id
       FROM txs
       WHERE microblock_canonical = true AND canonical = true
-      AND block_height = ${block.block_height} AND type_id = ${DbTxTypeId.Coinbase}
+      AND block_height = ${block.block_height} AND (type_id = ${DbTxTypeId.Coinbase} OR type_id = ${DbTxTypeId.CoinbaseToAltRecipient})
       LIMIT 1
     `;
 

src/datastore/pg-write-store.ts

@@ -1164,6 +1164,7 @@ export class PgWriteStore extends PgStore {
       poison_microblock_header_1: tx.poison_microblock_header_1 ?? null,
       poison_microblock_header_2: tx.poison_microblock_header_2 ?? null,
       coinbase_payload: tx.coinbase_payload ?? null,
+      coinbase_alt_recipient: tx.coinbase_alt_recipient ?? null,
       raw_result: tx.raw_result,
       event_count: tx.event_count,
       execution_cost_read_count: tx.execution_cost_read_count,
@@ -1213,6 +1214,7 @@ export class PgWriteStore extends PgStore {
           poison_microblock_header_1: tx.poison_microblock_header_1 ?? null,
           poison_microblock_header_2: tx.poison_microblock_header_2 ?? null,
           coinbase_payload: tx.coinbase_payload ?? null,
+          coinbase_alt_recipient: tx.coinbase_alt_recipient ?? null,
         };
         const result = await sql`
           INSERT INTO mempool_txs ${sql(values)}

src/event-stream/reader.ts

@@ -298,6 +298,18 @@ export function parseMessageTransaction(
       case TxPayloadTypeID.Coinbase: {
         break;
       }
+      case TxPayloadTypeID.CoinbaseToAltRecipient: {
+        if (payload.recipient.type_id === PrincipalTypeID.Standard) {
+          logger.verbose(
+            `Coinbase to alt recipient, standard principal: ${payload.recipient.address}`
+          );
+        } else {
+          logger.verbose(
+            `Coinbase to alt recipient, contract principal: ${payload.recipient.address}.${payload.recipient.contract_name}`
+          );
+        }
+        break;
+      }
       case TxPayloadTypeID.SmartContract: {
         logger.verbose(
           `Smart contract deployed: ${parsedTx.sender_address}.${payload.contract_name}`

src/migrations/1584619633448_txs.ts

@@ -160,6 +160,9 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
 
     // `coinbase` tx types
     coinbase_payload: 'bytea',
+
+    // `coinbase-pay-to-alt` tx types
+    coinbase_alt_recipient: 'string',
   });
 
   pgm.createIndex('txs', 'tx_id', { method: 'hash' });
@@ -170,6 +173,7 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
   pgm.createIndex('txs', 'smart_contract_contract_id', { method: 'hash' });
   pgm.createIndex('txs', 'sponsor_address', { method: 'hash' });
   pgm.createIndex('txs', 'token_transfer_recipient_address', { method: 'hash' });
+  pgm.createIndex('txs', 'coinbase_alt_recipient');
   pgm.createIndex('txs', 'type_id');
   pgm.createIndex('txs', [{ name: 'tx_index', sort: 'DESC' }]);
   pgm.createIndex('txs', [
@@ -203,4 +207,8 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
   pgm.addConstraint('txs', 'valid_coinbase', `CHECK (type_id != 4 OR (
     NOT (coinbase_payload) IS NULL
   ))`);
+
+  pgm.addConstraint('txs', 'valid_coinbase-pay-to-alt', `CHECK (type_id != 5 OR (
+    NOT (coinbase_payload, coinbase_alt_recipient) IS NULL
+  ))`);
 }

src/migrations/1591291822107_mempool_txs.ts

@@ -93,6 +93,9 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
 
     // `coinbase` tx types
     coinbase_payload: 'bytea',
+
+    // `coinbase-pay-to-alt` tx types
+    coinbase_alt_recipient: 'string',
   });
 
   pgm.createIndex('mempool_txs', 'tx_id', { method: 'hash' });
@@ -129,4 +132,8 @@ export async function up(pgm: MigrationBuilder): Promise<void> {
   pgm.addConstraint('mempool_txs', 'valid_coinbase', `CHECK (type_id != 4 OR (
     NOT (coinbase_payload) IS NULL
   ))`);
+
+  pgm.addConstraint('mempool_txs', 'valid_coinbase-pay-to-alt', `CHECK (type_id != 5 OR (
+    NOT (coinbase_payload, coinbase_alt_recipient) IS NULL
+  ))`);
 }