feat: ingestion for TenureChange and NakamotoCoinbase tx types

.vscode/launch.json

@@ -48,6 +48,26 @@
       },
       "killBehavior": "polite",
     },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Launch: w/ postgres",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "runtimeArgs": ["-r", "ts-node/register/transpile-only", "-r", "tsconfig-paths/register"],
+      "args": ["${workspaceFolder}/src/index.ts"],
+      "outputCapture": "std",
+      "internalConsoleOptions": "openOnSessionStart",
+      "preLaunchTask": "deploy:pg",
+      "postDebugTask": "stop:pg",
+      "env": {
+        "STACKS_CHAIN_ID": "0x80000000",
+        "NODE_ENV": "development",
+        "TS_NODE_SKIP_IGNORE": "true"
+      },
+      "killBehavior": "polite",
+    },
     {
       "type": "node",
       "request": "launch",

.vscode/tasks.json

@@ -44,6 +44,29 @@
       },
       "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "dedicated", "clear": false }
     },
+    {
+      "label": "deploy:pg",
+      "type": "shell",
+      "command": "docker compose -f docker/docker-compose.dev.postgres.yml up --force-recreate -V",
+      "isBackground": true,
+      "problemMatcher": [{
+        "pattern": [{ "regexp": ".", "file": 1, "location": 2, "message": 3 }],
+        "background": { "activeOnStart": true, "beginsPattern": ".", "endsPattern": "." }
+      }],
+      "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "dedicated", "clear": false }
+    },
+    {
+      "label": "stop:pg",
+      "type": "shell",
+      "command": "docker compose -f docker/docker-compose.dev.postgres.yml down -v -t 0",
+      "presentation": {
+        "echo": true,
+        "reveal": "silent",
+        "focus": false,
+        "panel": "shared",
+        "clear": false
+      }
+    },
     {
       "label": "deploy:subnets",
       "type": "shell",

docs/entities/mempool-transactions/transaction-7-tenure-change.schema.json

@@ -0,0 +1,13 @@
+{
+  "type": "object",
+  "title": "MempoolTenureChangeTransaction",
+  "description": "Describes representation of a Type 7 Stacks transaction: Tenure Change",
+  "allOf": [
+    {
+      "$ref": "./abstract-transaction.schema.json"
+    },
+    {
+      "$ref": "../transactions/transaction-7-tenure-change-metadata.schema.json"
+    }
+  ]
+}

docs/entities/mempool-transactions/transaction.schema.json

@@ -17,6 +17,9 @@
     },
     {
       "$ref": "./transaction-4-coinbase.schema.json"
+    },
+    {
+      "$ref": "./transaction-7-tenure-change.schema.json"
     }
   ]
 }

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

@@ -22,6 +22,11 @@
           "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."
+        },
+        "vrf_proof": {
+          "type": "string",
+          "nullable": true,
+          "description": "Hex encoded 80-byte VRF proof"
         }
       }
     }

docs/entities/transactions/transaction-7-tenure-change-metadata.schema.json

@@ -0,0 +1,45 @@
+{
+  "type": "object",
+  "title": "TenureChangeTransactionMetadata",
+  "description": "Describes representation of a Type 7 Stacks transaction: Tenure Change",
+  "required": ["tx_type"],
+  "additionalProperties": false,
+  "properties": {
+    "tx_type": {
+      "type": "string",
+      "enum": ["tenure_change"]
+    },
+    "tenure_change_payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["previous_tenure_end", "previous_tenure_blocks", "cause", "pubkey_hash", "signature", "signers"],
+      "properties": {
+        "previous_tenure_end": {
+          "type": "string",
+          "description": "(Hex string) Stacks Block hash"
+        },
+        "previous_tenure_blocks": {
+          "type": "number",
+          "description": "The number of blocks produced in the previous tenure."
+        },
+        "cause": {
+          "type": "string",
+          "enum": ["block_found", "no_block_found", "null_miner"],
+          "description": "Cause of change in mining tenure. Depending on cause, tenure can be ended or extended."
+        },
+        "pubkey_hash": {
+          "type": "string",
+          "description": "(Hex string) The ECDSA public key hash of the current tenure."
+        },
+        "signature": {
+          "type": "string",
+          "description": "(Hex string) A Schnorr signature from the Stackers."
+        },
+        "signers": {
+          "type": "string",
+          "description": "(Hex string) A bitmap of which Stackers signed."
+        }
+      }
+    }
+  }
+}

docs/entities/transactions/transaction-7-tenure-change.example.json

@@ -0,0 +1,25 @@
+{
+  "tx_id": "0x5e9f3933e358df6a73fec0d47ce3e1062c20812c129f5294e6f37a8d27c051d9",
+  "tx_status": "success",
+  "tx_type": "coinbase",
+  "fee_rate": "0",
+  "sender_address": "ST3WCQ6S0DFT7YHF53M8JPKGDS1N1GSSR91677XF1",
+  "sponsored": false,
+  "post_condition_mode": "deny",
+  "is_unanchored": false,
+  "microblock_hash": "",
+  "microblock_sequence": 2147483647,
+  "microblock_canonical": true,
+  "block_hash": "0x58412b50266debd0c35b1a20348ad9c0f17e5525fb155a97033256c83c9e2491",
+  "block_height": 3231,
+  "burn_block_time": 1594230455,
+  "canonical": true,
+  "tx_index": 0,
+  "tx_result": {
+    "hex": "0x03",
+    "repr": "true"
+  },
+  "coinbase_payload": {
+    "data": "0x0000000000000000000000000000000000000000000000000000000000000000"
+  }
+}

docs/entities/transactions/transaction-7-tenure-change.schema.json

@@ -0,0 +1,13 @@
+{
+  "type": "object",
+  "title": "TenureChangeTransaction",
+  "description": "Describes representation of a Type 7 Stacks transaction: Tenure Change",
+  "allOf": [
+    {
+      "$ref": "./abstract-transaction.schema.json"
+    },
+    {
+      "$ref": "./transaction-7-tenure-change-metadata.schema.json"
+    }
+  ]
+}

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

@@ -16,6 +16,9 @@
     },
     {
       "$ref": "./transaction-4-coinbase-metadata.schema.json"
+    },
+    {
+      "$ref": "./transaction-7-tenure-change-metadata.schema.json"
     }
   ]
 }

docs/entities/transactions/transaction-type.schema.json

@@ -2,5 +2,5 @@
   "title": "TransactionType",
   "description": "String literal of all Stacks 2.0 transaction types",
   "type": "string",
-  "enum": ["token_transfer", "smart_contract", "contract_call", "poison_microblock", "coinbase"]
+  "enum": ["token_transfer", "smart_contract", "contract_call", "poison_microblock", "coinbase", "tenure_change"]
 }

docs/entities/transactions/transaction.schema.json

@@ -17,6 +17,9 @@
     },
     {
       "$ref": "./transaction-4-coinbase.schema.json"
+    },
+    {
+      "$ref": "./transaction-7-tenure-change.schema.json"
     }
   ]
 }

docs/generated.d.ts

@@ -127,6 +127,7 @@ export type SchemaMergeRootStub =
   | MempoolContractCallTransaction
   | MempoolPoisonMicroblockTransaction
   | MempoolCoinbaseTransaction
+  | MempoolTenureChangeTransaction
   | MempoolTransactionStatus
   | MempoolTransaction
   | Microblock
@@ -209,6 +210,8 @@ export type SchemaMergeRootStub =
   | PoisonMicroblockTransaction
   | CoinbaseTransactionMetadata
   | CoinbaseTransaction
+  | TenureChangeTransactionMetadata
+  | TenureChangeTransaction
   | TransactionFound
   | TransactionList
   | TransactionMetadata
@@ -324,7 +327,8 @@ export type Transaction =
   | SmartContractTransaction
   | ContractCallTransaction
   | PoisonMicroblockTransaction
-  | CoinbaseTransaction;
+  | CoinbaseTransaction
+  | TenureChangeTransaction;
 /**
  * Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset
  */
@@ -526,6 +530,10 @@ export type PoisonMicroblockTransaction = AbstractTransaction & PoisonMicroblock
  * Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock
  */
 export type CoinbaseTransaction = AbstractTransaction & CoinbaseTransactionMetadata;
+/**
+ * Describes representation of a Type 7 Stacks transaction: Tenure Change
+ */
+export type TenureChangeTransaction = AbstractTransaction & TenureChangeTransactionMetadata;
 /**
  * Describes all transaction types on Stacks 2.0 blockchain
  */
@@ -534,7 +542,8 @@ export type MempoolTransaction =
   | MempoolSmartContractTransaction
   | MempoolContractCallTransaction
   | MempoolPoisonMicroblockTransaction
-  | MempoolCoinbaseTransaction;
+  | MempoolCoinbaseTransaction
+  | MempoolTenureChangeTransaction;
 /**
  * Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset
  */
@@ -578,6 +587,10 @@ export type MempoolPoisonMicroblockTransaction = AbstractMempoolTransaction & Po
  * Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock
  */
 export type MempoolCoinbaseTransaction = AbstractMempoolTransaction & CoinbaseTransactionMetadata;
+/**
+ * Describes representation of a Type 7 Stacks transaction: Tenure Change
+ */
+export type MempoolTenureChangeTransaction = AbstractMempoolTransaction & TenureChangeTransactionMetadata;
 /**
  * Fetch a user's raw zone file. This only works for RFC-compliant zone files. This method returns an error for names that have non-standard zone files.
  */
@@ -705,11 +718,18 @@ export type TransactionMetadata =
   | SmartContractTransactionMetadata
   | ContractCallTransactionMetadata
   | PoisonMicroblockTransactionMetadata
-  | CoinbaseTransactionMetadata;
+  | CoinbaseTransactionMetadata
+  | TenureChangeTransactionMetadata;
 /**
  * String literal of all Stacks 2.0 transaction types
  */
-export type TransactionType = "token_transfer" | "smart_contract" | "contract_call" | "poison_microblock" | "coinbase";
+export type TransactionType =
+  | "token_transfer"
+  | "smart_contract"
+  | "contract_call"
+  | "poison_microblock"
+  | "coinbase"
+  | "tenure_change";
 export type RpcAddressBalanceNotificationParams = {
   address: string;
 } & AddressStxBalanceResponse;
@@ -1098,6 +1118,42 @@ export interface CoinbaseTransactionMetadata {
      * 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;
+    /**
+     * Hex encoded 80-byte VRF proof
+     */
+    vrf_proof?: string;
+  };
+}
+/**
+ * Describes representation of a Type 7 Stacks transaction: Tenure Change
+ */
+export interface TenureChangeTransactionMetadata {
+  tx_type: "tenure_change";
+  tenure_change_payload?: {
+    /**
+     * (Hex string) Stacks Block hash
+     */
+    previous_tenure_end: string;
+    /**
+     * The number of blocks produced in the previous tenure.
+     */
+    previous_tenure_blocks: number;
+    /**
+     * Cause of change in mining tenure. Depending on cause, tenure can be ended or extended.
+     */
+    cause: "block_found" | "no_block_found" | "null_miner";
+    /**
+     * (Hex string) The ECDSA public key hash of the current tenure.
+     */
+    pubkey_hash: string;
+    /**
+     * (Hex string) A Schnorr signature from the Stackers.
+     */
+    signature: string;
+    /**
+     * (Hex string) A bitmap of which Stackers signed.
+     */
+    signers: string;
   };
 }
 /**

docs/openapi.yaml

@@ -228,7 +228,7 @@ paths:
             example: coinbase
             items:
               type: string
-              enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock]
+              enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock, tenure_change]
         - name: unanchored
           in: query
           description: Include transaction data from unanchored (i.e. unconfirmed) microblocks

migrations/1701368149776_nakamoto-txs.js

@@ -0,0 +1,44 @@
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.up = pgm => {
+  pgm.addColumns('txs', {
+    // `nakamoto-coinbase` tx types
+    coinbase_vrf_proof: 'bytea',
+
+    // `tenure-change` tx types
+    tenure_change_previous_tenure_end: 'bytea',
+    tenure_change_previous_tenure_blocks: 'integer',
+    tenure_change_cause: 'smallint',
+    tenure_change_pubkey_hash: 'bytea',
+    tenure_change_signature: 'bytea',
+    tenure_change_signers: 'bytea',
+  });
+
+  pgm.addColumns('mempool_txs', {
+    // `nakamoto-coinbase` tx  types
+    coinbase_vrf_proof: 'bytea',
+
+    // `tenure-change` tx types
+    tenure_change_previous_tenure_end: 'bytea',
+    tenure_change_previous_tenure_blocks: 'integer',
+    tenure_change_cause: 'smallint',
+    tenure_change_pubkey_hash: 'bytea',
+    tenure_change_signature: 'bytea',
+    tenure_change_signers: 'bytea',
+  });
+
+  pgm.addConstraint('txs', 'valid_tenure-change', `CHECK (type_id != 7 OR (
+    NOT (tenure_change_previous_tenure_end, tenure_change_previous_tenure_blocks, tenure_change_cause, tenure_change_pubkey_hash, tenure_change_signature, tenure_change_signers) IS NULL
+  ))`);
+
+  pgm.addConstraint('txs', 'valid_nakamoto-coinbase', `CHECK (type_id != 8 OR (
+    NOT (coinbase_payload, coinbase_vrf_proof) IS NULL
+  ))`);
+
+  pgm.addConstraint('mempool_txs', 'valid_tenure-change', `CHECK (type_id != 7 OR (
+    NOT (tenure_change_previous_tenure_end, tenure_change_previous_tenure_blocks, tenure_change_cause, tenure_change_pubkey_hash, tenure_change_signature, tenure_change_signers) IS NULL
+  ))`);
+
+  pgm.addConstraint('mempool_txs', 'valid_nakamoto-coinbase', `CHECK (type_id != 8 OR (
+    NOT (coinbase_payload, coinbase_vrf_proof) IS NULL
+  ))`);
+};