feat: rosetta pox4 stacking support (#1928)

* feat: rosetta pox4 support

* fix: optional fields in `/preprocess`

* chore: update rosetta pox-4 checks (#1929)

Co-authored-by: janniks <[email protected]>

* feat: optional pox-max-amount (default to stx amount)

* fix: handle signer signature logic only in the rosetta /construction/metadata endpoint

* fix: repair stacking w/ Rosetta in `/extended/v1/debug/broadcast/stack`

* fix: repair stacking w/o Rosetta in `/extended/v1/debug/broadcast/stack`

* fix: rosetta offline tests

* fix: rosetta construction tests

* fix: progress on fixing pox-4-rosetta tests

* test: skip rosetta stacking auto-unlock tests (feature removed in pox-4)

* fix: stack for 2 cycles in `rosetta-btc-addr-types` to reduce test flake

* docs: update Rosetta schema/docs

---------

Co-authored-by: janniks <[email protected]>
Co-authored-by: janniks <[email protected]>

Author: zone117x

docs/entities/rosetta/rosetta-construction-options.schema.json

@@ -76,6 +76,10 @@
       "type": "integer",
       "description": "Set the burnchain (BTC) block for stacking lock to start."
     },
+    "reward_cycle_id": {
+      "type": "integer",
+      "description": "The reward cycle ID for stacking transaction."
+    },
     "delegate_to": {
       "type": "string",
       "description": "Delegator address for when calling `delegate-stacking`."
@@ -87,6 +91,22 @@
     "signer_key": {
       "type": "string",
       "description": "The hex-encoded signer key (buff 33) for PoX."
+    },
+    "signer_private_key": {
+      "type": "string",
+      "description": "The hex-encoded signer private key for PoX. Specify either this or `signer_signature`, otherwise the PoX transaction requires allow-listing from the signer."
+    },
+    "signer_signature": {
+      "type": "string",
+      "description": "The hex-encoded signer signature for PoX. Specify either this or `signer_private_key`, otherwise the PoX transaction requires allow-listing from the signer."
+    },
+    "pox_max_amount": {
+      "type": "string",
+      "description": "The maximum amount of STX to stack for PoX. If not specified, the `amount` will be used as the `max-amount` for the PoX transaction."
+    },
+    "pox_auth_id": {
+      "type": "string",
+      "description": "The auth ID for the PoX transaction. If not specified, a random value will be generated."
     }
   }
 }

docs/generated.d.ts

@@ -2678,6 +2678,10 @@ export interface RosettaOptions {
    * Set the burnchain (BTC) block for stacking lock to start.
    */
   burn_block_height?: number;
+  /**
+   * The reward cycle ID for stacking transaction.
+   */
+  reward_cycle_id?: number;
   /**
    * Delegator address for when calling `delegate-stacking`.
    */
@@ -2690,6 +2694,22 @@ export interface RosettaOptions {
    * The hex-encoded signer key (buff 33) for PoX.
    */
   signer_key?: string;
+  /**
+   * The hex-encoded signer private key for PoX. Specify either this or `signer_signature`, otherwise the PoX transaction requires allow-listing from the signer.
+   */
+  signer_private_key?: string;
+  /**
+   * The hex-encoded signer signature for PoX. Specify either this or `signer_private_key`, otherwise the PoX transaction requires allow-listing from the signer.
+   */
+  signer_signature?: string;
+  /**
+   * The maximum amount of STX to stack for PoX. If not specified, the `amount` will be used as the `max-amount` for the PoX transaction.
+   */
+  pox_max_amount?: string;
+  /**
+   * The auth ID for the PoX transaction. If not specified, a random value will be generated.
+   */
+  pox_auth_id?: string;
 }
 /**
  * The ConstructionMetadataResponse returns network-specific metadata used for transaction construction. Optionally, the implementer can return the suggested fee associated with the transaction being constructed. The caller may use this info to adjust the intent of the transaction or to create a transaction with a different account that can pay the suggested fee. Suggested fee is an array in case fee payment must occur in multiple currencies.

src/api/routes/debug.ts

@@ -30,6 +30,9 @@ import {
   bufferCV,
   AnchorMode,
   deserializeTransaction,
+  makeRandomPrivKey,
+  privateKeyToString,
+  someCV,
 } from '@stacks/transactions';
 import { StacksTestnet } from '@stacks/network';
 import { SampleContracts } from '../../sample-data/broadcast-contract-default';
@@ -54,7 +57,10 @@ import {
   RosettaOperation,
 } from '@stacks/stacks-blockchain-api-types';
 import { getRosettaNetworkName, RosettaConstants } from '../rosetta-constants';
-import { decodeBtcAddress } from '@stacks/stacking';
+import { StackingClient, decodeBtcAddress, poxAddressToTuple } from '@stacks/stacking';
+import { getPublicKeyFromPrivate } from '@stacks/encryption';
+import { randomBytes } from 'node:crypto';
+import { hexToBytes } from '@stacks/common';
 
 const testnetAccounts = [
   {
@@ -587,6 +593,9 @@ export function createDebugRouter(db: PgStore): express.Router {
     btcAddr: string,
     cycleCount: number
   ): Promise<{ txId: string; burnBlockHeight: number }> {
+    const signerPrivKey = privateKeyToString(makeRandomPrivKey());
+    const signerPubKey = getPublicKeyFromPrivate(signerPrivKey);
+
     const stackingOperations: RosettaOperation[] = [
       {
         operation_identifier: {
@@ -607,6 +616,8 @@ export function createDebugRouter(db: PgStore): express.Router {
         metadata: {
           number_of_cycles: cycleCount,
           pox_addr: btcAddr,
+          signer_key: signerPubKey,
+          signer_private_key: signerPrivKey,
         },
       },
       {
@@ -723,21 +734,38 @@ export function createDebugRouter(db: PgStore): express.Router {
         ));
       } else {
         const [contractAddress, contractName] = poxInfo.contract_id.split('.');
-        const decodedBtcAddr = decodeBtcAddress(recipient_address);
+        const poxAddrTuple = poxAddressToTuple(recipient_address);
         burnBlockHeight = poxInfo.current_burnchain_block_height as number;
+
+        const stackingRpc = new StackingClient('', stacksNetwork);
+        const signerPrivKey = makeRandomPrivKey();
+        const signerPubKey = getPublicKeyFromPrivate(signerPrivKey.data);
+        const authId = `0x${randomBytes(16).toString('hex')}`;
+
+        const signerSig = stackingRpc.signPoxSignature({
+          topic: 'stack-stx',
+          poxAddress: recipient_address,
+          rewardCycle: poxInfo.current_cycle.id,
+          period: cycles,
+          signerPrivateKey: signerPrivKey,
+          maxAmount: ustxAmount,
+          authId: authId,
+        });
+
         const txOptions: SignedContractCallOptions = {
           senderKey: sender.secretKey,
           contractAddress,
           contractName,
           functionName: 'stack-stx',
           functionArgs: [
-            uintCV(ustxAmount.toString()),
-            tupleCV({
-              hashbytes: bufferCV(decodedBtcAddr.data),
-              version: bufferCV(Buffer.from([decodedBtcAddr.version])),
-            }),
-            uintCV(burnBlockHeight),
-            uintCV(cycles),
+            uintCV(ustxAmount), // amount-ustx
+            poxAddrTuple, // pox-addr
+            uintCV(burnBlockHeight), // start-burn-ht
+            uintCV(cycles), // lock-period
+            someCV(bufferCV(hexToBytes(signerSig))), // signer-sig
+            bufferCV(hexToBytes(signerPubKey)), // signer-key
+            uintCV(ustxAmount), // max-amount
+            uintCV(authId), // auth-id
           ],
           network: stacksNetwork,
           anchorMode: AnchorMode.Any,