feat: [Stacks 2.1] delegate-stx Bitcoin-op parsing (#1527)

* feat: initial event parsing for `delegate-stx` pox2 event

* feat: create synthetic tx from parsing DelegateStx pox2 event data

* feat: parsing of optional `pox-addr` arg of `delegate-stx` event

* feat: parsing of optional `until-burn-ht` arg of `delegate-stx` event

* test: validate pox2 event for `delegate-stx` Stacks-chain op

* chore: remove accidentally committed code

* chore: bump to Stacks node `v2.1.0.0.0-rc4`

* ci: do not fail-fast on 2.1 test matrix

* test: temp disable tests that are flaking with stacks-node 2.1-RC4

* test: try waiting for next pox cycle in btc-address-format stacking tests

* test: try waiting for next pox cycle in btc-address-format stacking tests, attempt 2

Author: zone117x

.github/workflows/ci.yml

@@ -403,6 +403,7 @@ jobs:
 
   test-2_1:
     strategy:
+      fail-fast: false
       matrix:
         suite: [
           block-zero-handling,
@@ -478,6 +479,7 @@ jobs:
 
   test-2_1-transition:
     strategy:
+      fail-fast: false
       matrix:
         suite:
           [

docker/docker-compose.dev.stacks-krypton-2.1-transition.yml

@@ -1,7 +1,7 @@
 version: '3.7'
 services:
   stacks-blockchain:
-    image: "zone117x/stacks-api-e2e:stacks2.1-transition-7e78d0a"
+    image: "zone117x/stacks-api-e2e:stacks2.1-transition-38c5623"
     ports:
       - "18443:18443" # bitcoin regtest JSON-RPC interface
       - "18444:18444" # bitcoin regtest p2p

docker/docker-compose.dev.stacks-krypton.yml

@@ -1,7 +1,7 @@
 version: '3.7'
 services:
   stacks-blockchain:
-    image: "zone117x/stacks-api-e2e:stacks2.1-7e78d0a"
+    image: "zone117x/stacks-api-e2e:stacks2.1-38c5623"
     ports:
       - "18443:18443" # bitcoin regtest JSON-RPC interface
       - "18444:18444" # bitcoin regtest p2p

migrations/1666703991492_pox_events.js

@@ -96,6 +96,9 @@ exports.up = pgm => {
     first_unlocked_cycle: { // unique to handle-unlock
       type: 'numeric',
     },
+    delegate_to: { // unique to delegate-stx
+      type: 'string',
+    },
     lock_period: { // unique to stack-stx, delegate-stack-stx
       type: 'numeric'
     },
@@ -105,7 +108,7 @@ exports.up = pgm => {
     start_burn_height: { // unique to stack-stx, delegate-stack-stx
       type: 'numeric',
     },
-    unlock_burn_height: { // unique to stack-stx, stack-extend, delegate-stack-stx, delegate-stack-extend
+    unlock_burn_height: { // unique to stack-stx, stack-extend, delegate-stack-stx, delegate-stack-extend, delegate-stx
       type: 'numeric',
     },
     delegator: { // unique to delegate-stack-stx, delegate-stack-increase, delegate-stack-extend
@@ -123,7 +126,7 @@ exports.up = pgm => {
     reward_cycle: { // unique to stack-aggregation-*
       type: 'numeric',
     },
-    amount_ustx: { // unique to stack-aggregation-*
+    amount_ustx: { // unique to stack-aggregation-*, delegate-stx
       type: 'numeric',
     },
   });
@@ -144,6 +147,9 @@ exports.up = pgm => {
       WHEN 'stack-extend' THEN
         extend_count IS NOT NULL AND 
         unlock_burn_height IS NOT NULL
+      WHEN 'delegate-stx' THEN
+        amount_ustx IS NOT NULL AND 
+        delegate_to IS NOT NULL
       WHEN 'delegate-stack-stx' THEN
         lock_period IS NOT NULL AND 
         lock_amount IS NOT NULL AND 

src/api/controllers/db-controller.ts

@@ -255,6 +255,16 @@ export function parsePox2Event(poxEvent: DbPox2Event) {
         },
       };
     }
+    case Pox2EventName.DelegateStx: {
+      return {
+        ...baseInfo,
+        data: {
+          amount_ustx: poxEvent.data.amount_ustx.toString(),
+          delegate_to: poxEvent.data.delegate_to,
+          unlock_burn_height: poxEvent.data.unlock_burn_height?.toString(),
+        },
+      };
+    }
     case Pox2EventName.DelegateStackStx: {
       return {
         ...baseInfo,

src/datastore/common.ts

@@ -348,6 +348,15 @@ export interface DbPox2StackExtendEvent extends DbPox2BaseEventData {
   };
 }
 
+export interface DbPox2DelegateStxEvent extends DbPox2BaseEventData {
+  name: Pox2EventName.DelegateStx;
+  data: {
+    amount_ustx: bigint;
+    delegate_to: string;
+    unlock_burn_height: bigint | null;
+  };
+}
+
 export interface DbPox2DelegateStackStxEvent extends DbPox2BaseEventData {
   name: Pox2EventName.DelegateStackStx;
   data: {
@@ -406,6 +415,7 @@ export type DbPox2EventData =
   | DbPox2StackStxEvent
   | DbPox2StackIncreaseEvent
   | DbPox2StackExtendEvent
+  | DbPox2DelegateStxEvent
   | DbPox2DelegateStackStxEvent
   | DbPox2DelegateStackIncreaseEvent
   | DbPox2DelegateStackExtendEvent
@@ -1227,12 +1237,15 @@ export interface Pox2EventQueryResult {
   // unique to stack-stx, delegate-stack-stx
   start_burn_height: string | null;
 
-  // unique to stack-stx, stack-extend, delegate-stack-stx, delegate-stack-extend
+  // unique to stack-stx, stack-extend, delegate-stack-stx, delegate-stack-extend, delegate-stx
   unlock_burn_height: string | null;
 
   // unique to delegate-stack-stx, delegate-stack-increase, delegate-stack-extend
   delegator: string | null;
 
+  // unique to delegate-stx
+  delegate_to: string | null;
+
   // unique to stack-increase, delegate-stack-increase
   increase_by: string | null;
 
@@ -1245,7 +1258,7 @@ export interface Pox2EventQueryResult {
   // unique to stack-aggregation-commit
   reward_cycle: string | null;
 
-  // unique to stack-aggregation-commit
+  // unique to stack-aggregation-commit, delegate-stx
   amount_ustx: string | null;
 }
 
@@ -1274,6 +1287,9 @@ export interface Pox2EventInsertValues {
   // unique to handle-unlock
   first_unlocked_cycle: PgNumeric | null;
 
+  // unique to delegate-stx
+  delegate_to: string | null;
+
   // unique to stack-stx, delegate-stack-stx
   lock_period: PgNumeric | null;
 
@@ -1300,7 +1316,7 @@ export interface Pox2EventInsertValues {
   // unique to stack-aggregation-commit
   reward_cycle: PgNumeric | null;
 
-  // unique to stack-aggregation-commit
+  // unique to stack-aggregation-commit, delegate-stx
   amount_ustx: PgNumeric | null;
 }
 

src/datastore/helpers.ts

@@ -18,6 +18,7 @@ import {
   DbPox2DelegateStackExtendEvent,
   DbPox2DelegateStackIncreaseEvent,
   DbPox2DelegateStackStxEvent,
+  DbPox2DelegateStxEvent,
   DbPox2Event,
   DbPox2HandleUnlockEvent,
   DbPox2StackAggregationCommitEvent,
@@ -216,6 +217,7 @@ export const POX2_EVENT_COLUMNS = [
   'start_burn_height',
   'unlock_burn_height',
   'delegator',
+  'delegate_to',
   'increase_by',
   'total_locked',
   'extend_count',
@@ -693,6 +695,23 @@ export function parseDbPox2Event(row: Pox2EventQueryResult): DbPox2Event {
         ...eventData,
       };
     }
+    case Pox2EventName.DelegateStx: {
+      const eventData: DbPox2DelegateStxEvent = {
+        ...basePox2Event,
+        name: rowName,
+        data: {
+          amount_ustx: BigInt(unwrapOptionalProp(row, 'amount_ustx')),
+          delegate_to: unwrapOptionalProp(row, 'delegate_to'),
+          unlock_burn_height: row.unlock_burn_height
+            ? BigInt(unwrapOptionalProp(row, 'unlock_burn_height'))
+            : null,
+        },
+      };
+      return {
+        ...baseEvent,
+        ...eventData,
+      };
+    }
     case Pox2EventName.DelegateStackStx: {
       const eventData: DbPox2DelegateStackStxEvent = {
         ...basePox2Event,

src/datastore/pg-write-store.ts

@@ -819,6 +819,7 @@ export class PgWriteStore extends PgStore {
       pox_addr_raw: event.pox_addr_raw,
       first_cycle_locked: null,
       first_unlocked_cycle: null,
+      delegate_to: null,
       lock_period: null,
       lock_amount: null,
       start_burn_height: null,
@@ -854,6 +855,12 @@ export class PgWriteStore extends PgStore {
         values.unlock_burn_height = event.data.unlock_burn_height.toString();
         break;
       }
+      case Pox2EventName.DelegateStx: {
+        values.amount_ustx = event.data.amount_ustx.toString();
+        values.delegate_to = event.data.delegate_to;
+        values.unlock_burn_height = event.data.unlock_burn_height?.toString() ?? null;
+        break;
+      }
       case Pox2EventName.DelegateStackStx: {
         values.lock_period = event.data.lock_period.toString();
         values.lock_amount = event.data.lock_amount.toString();

src/ec-helpers.ts

@@ -216,7 +216,7 @@ export interface VerboseKeyOutput {
   publicKey: Buffer;
 }
 
-type BitcoinAddressFormat =
+export type BitcoinAddressFormat =
   | 'p2pkh'
   | 'p2sh'
   | 'p2sh-p2wpkh'

src/event-stream/pox2-event-parsing.ts

@@ -3,6 +3,7 @@ import {
   DbPox2DelegateStackExtendEvent,
   DbPox2DelegateStackIncreaseEvent,
   DbPox2DelegateStackStxEvent,
+  DbPox2DelegateStxEvent,
   DbPox2EventData,
   DbPox2HandleUnlockEvent,
   DbPox2StackAggregationCommitEvent,
@@ -19,6 +20,8 @@ import {
   ClarityValue,
   ClarityValueAbstract,
   ClarityValueBuffer,
+  ClarityValueOptionalNone,
+  ClarityValueOptionalSome,
   ClarityValuePrincipalContract,
   ClarityValuePrincipalStandard,
   ClarityValueResponse,
@@ -31,10 +34,19 @@ import { poxAddressToBtcAddress } from '@stacks/stacking';
 import { Pox2EventName } from '../pox-helpers';
 
 function tryClarityPoxAddressToBtcAddress(
-  poxAddr: Pox2Addr,
+  poxAddr: Pox2Addr | ClarityValueOptionalSome<Pox2Addr> | ClarityValueOptionalNone,
   network: 'mainnet' | 'testnet' | 'regtest'
 ): { btcAddr: string | null; raw: Buffer } {
   let btcAddr: string | null = null;
+  if (poxAddr.type_id === ClarityTypeID.OptionalNone) {
+    return {
+      btcAddr,
+      raw: Buffer.alloc(0),
+    };
+  }
+  if (poxAddr.type_id === ClarityTypeID.OptionalSome) {
+    poxAddr = poxAddr.value;
+  }
   try {
     btcAddr = poxAddressToBtcAddress(
       coerceToBuffer(poxAddr.data.version.buffer)[0],
@@ -91,6 +103,12 @@ interface Pox2PrintEventTypes {
     'unlock-burn-height': ClarityValueUInt;
     'pox-addr': Pox2Addr;
   };
+  [Pox2EventName.DelegateStx]: {
+    'amount-ustx': ClarityValueUInt;
+    'delegate-to': ClarityValuePrincipalStandard | ClarityValuePrincipalContract;
+    'unlock-burn-height': ClarityValueOptionalSome<ClarityValueUInt> | ClarityValueOptionalNone;
+    'pox-addr': Pox2Addr | ClarityValueOptionalNone;
+  };
   [Pox2EventName.DelegateStackStx]: {
     'lock-amount': ClarityValueUInt;
     'unlock-burn-height': ClarityValueUInt;
@@ -191,7 +209,10 @@ export function decodePox2PrintEvent(
   }
 
   if ('pox-addr' in eventData) {
-    const eventPoxAddr = eventData['pox-addr'] as Pox2Addr;
+    const eventPoxAddr = eventData['pox-addr'] as
+      | Pox2Addr
+      | ClarityValueOptionalSome<Pox2Addr>
+      | ClarityValueOptionalNone;
     const encodedArr = tryClarityPoxAddressToBtcAddress(eventPoxAddr, network);
     baseEventData.pox_addr = encodedArr.btcAddr;
     baseEventData.pox_addr_raw = bufferToHexPrefixString(encodedArr.raw);
@@ -264,6 +285,27 @@ export function decodePox2PrintEvent(
       }
       return parsedData;
     }
+    case Pox2EventName.DelegateStx: {
+      const d = eventData as Pox2PrintEventTypes[typeof eventName];
+      const parsedData: DbPox2DelegateStxEvent = {
+        ...baseEventData,
+        name: eventName,
+        data: {
+          amount_ustx: BigInt(d['amount-ustx'].value),
+          delegate_to: clarityPrincipalToFullAddress(d['delegate-to']),
+          unlock_burn_height:
+            d['unlock-burn-height'].type_id === ClarityTypeID.OptionalSome
+              ? BigInt(d['unlock-burn-height'].value.value)
+              : null,
+        },
+      };
+      if (PATCH_EVENT_BALANCES) {
+        if (parsedData.data.unlock_burn_height) {
+          parsedData.burnchain_unlock_height = parsedData.data.unlock_burn_height;
+        }
+      }
+      return parsedData;
+    }
     case Pox2EventName.DelegateStackStx: {
       const d = eventData as Pox2PrintEventTypes[typeof eventName];
       const parsedData: DbPox2DelegateStackStxEvent = {