chore: PoX-2 integration testing for segwit addresses (#1372)

* feat: functions for generating Bitcoin addresses in all formats supported by Stacks 2.1

* test: segwit PoX-2 integration tests

* test: e2e tests for PoX-2 segwit (P2WPKH) support

* chore: test PoX rewards against bitcoin json-rpc results

* test: e2e tests for PoX-2 rewards address formats p2pkh, p2sh, p2wpkh, p2wsh

* test: use more robust bitcoin `listtransactions` RPC method for validating PoX-2 rewards

* chore: update plain P2SH address generation to create a more standard P2SH(P2PKH) rather than 1-of-1 multisig address

* chore: temp skip segwit tests until `feat/native-segwit` stacks-blockchain branch is merged

* chore: Revert "temp skip segwit tests until `feat/native-segwit` stacks-blockchain branch is merged" -- too many other dependent changes

* chore: filter bitcoin rpc `listtransactions` result for only the address being tested

Author: zone117x

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-8fb8b77"
+    image: "zone117x/stacks-api-e2e:stacks2.1-transition-feat-segwit-dcae03a"
     ports:
       - "18443:18443" # bitcoin regtest JSON-RPC interface
       - "18444:18444" # bitcoin regtest p2p

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

@@ -1,14 +1,14 @@
 version: '3.7'
 services:
   stacks-blockchain:
-    image: "zone117x/stacks-api-e2e:stacks2.1-8fb8b77"
+    image: "zone117x/stacks-api-e2e:stacks2.1-feat-segwit-dcae03a"
     ports:
       - "18443:18443" # bitcoin regtest JSON-RPC interface
       - "18444:18444" # bitcoin regtest p2p
       - "20443:20443" # stacks-node RPC interface
       - "20444:20444" # stacks-node p2p
     environment:
-      MINE_INTERVAL: 2s
+      MINE_INTERVAL: 1.2s
       STACKS_EVENT_OBSERVER: host.docker.internal:3700
       # STACKS_LOG_TRACE: 1
       # STACKS_LOG_DEBUG: 1

src/ec-helpers.ts

@@ -1,8 +1,9 @@
 import * as bitcoin from 'bitcoinjs-lib';
 import * as ecc from 'tiny-secp256k1';
-import { ECPairAPI, ECPairFactory } from 'ecpair';
+import { ECPairAPI, ECPairFactory, ECPairInterface } from 'ecpair';
+import { coerceToBuffer } from './helpers';
 
-export { ECPairInterface } from 'ecpair';
+export { ECPairInterface };
 
 export const ECPair: ECPairAPI = ECPairFactory(ecc);
 
@@ -16,27 +17,190 @@ const BITCOIN_NETWORKS = {
   regtest: bitcoin.networks.regtest,
 } as const;
 
+type KeyInputArgs = { network: keyof typeof BITCOIN_NETWORKS } & (
+  | { privateKey: Buffer | string }
+  | { publicKey: Buffer | string }
+);
+
+interface KeyOutput {
+  address: string;
+  ecPair: ECPairInterface;
+}
+
+function ecPairFromKeyInputArgs(args: KeyInputArgs, allowXOnlyPubkey = false): ECPairInterface {
+  const network = BITCOIN_NETWORKS[args.network];
+  if ('privateKey' in args) {
+    let keyBuff = coerceToBuffer(args.privateKey);
+    if (keyBuff.length === 33 && keyBuff[32] === 0x01) {
+      keyBuff = keyBuff.slice(0, 32); // Drop the compression byte suffix
+    }
+    return ECPair.fromPrivateKey(keyBuff, { compressed: true, network });
+  } else {
+    let keyBuff = coerceToBuffer(args.publicKey);
+    if (allowXOnlyPubkey && keyBuff.length === 32) {
+      // Allow x-only pubkeys, defined in BIP340 (no y parity byte prefix)
+      const X_ONLY_PUB_KEY_TIE_BREAKER = 0x02;
+      keyBuff = Buffer.concat([Buffer.from([X_ONLY_PUB_KEY_TIE_BREAKER]), keyBuff]);
+    }
+    return ECPair.fromPublicKey(keyBuff, { compressed: true, network });
+  }
+}
+
 /**
- * Function for creating a tweaked p2tr key-spend only address (this is recommended by BIP341)
- * @see https://github.com/bitcoinjs/bitcoinjs-lib/blob/424abf2376772bb57b7668bc35b29ed18879fa0a/test/integration/taproot.md
+ * Creates a P2PKH "Pay To Public Key Hash" address.
+ * `hashbytes` is the 20-byte hash160 of a single public key.
+ * Encoded as base58.
+ */
+function p2pkhAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  const p2pkhhResult = bitcoin.payments.p2pkh({ pubkey: ecPair.publicKey, network });
+  if (!p2pkhhResult.address) {
+    throw new Error(
+      `Could not create P2PKH address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
+  }
+  return { ecPair, address: p2pkhhResult.address };
+}
+
+/**
+ * Creates a P2SH "Pay To Script Hash" address.
+ * Typically used to generate multi-signature wallets, however, this function creates a P2PKH wrapped in P2SH address.
+ * `hashbytes` is the 20-byte hash160 of a redeemScript script.
+ * Encoded as base58.
+ */
+function p2shAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  // P2SH(P2PKH) address example '3D4sXNTgnVbEWaU58pDgBD82zDkthVWazv' from https://matheo.uliege.be/bitstream/2268.2/11236/4/Master_Thesis.pdf
+  const p2sh_p2pkh_Result = bitcoin.payments.p2sh({
+    redeem: bitcoin.payments.p2pkh({ pubkey: ecPair.publicKey, network }),
+    network,
+  });
+
+  // P2SH(P2PK) address example '3EuJgd52Tme58nZewZa39svoDtSUgL4Mgn' from https://matheo.uliege.be/bitstream/2268.2/11236/4/Master_Thesis.pdf
+  // const p2sh_p2pk_Result = bitcoin.payments.p2sh({
+  //   redeem: bitcoin.payments.p2pk({ pubkey: ecPair.publicKey, network }),
+  //   network,
+  // });
+
+  // 1-of-1 multisig, not sure if valid ...
+  // const p2shResult1 = bitcoin.payments.p2sh({
+  //   redeem: bitcoin.payments.p2ms({ pubkeys: [ecPair.publicKey], m: 1, network }),
+  //   network,
+  // });
+
+  if (!p2sh_p2pkh_Result.address) {
+    throw new Error(
+      `Could not create P2SH address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
+  }
+  return { ecPair, address: p2sh_p2pkh_Result.address };
+}
+
+/**
+ * Creates a P2SH-P2WPHK "Pay To Witness Public Key Hash Wrapped In P2SH" address.
+ * Used to generate a segwit P2WPKH address nested in a legacy legacy P2SH address.
+ * Allows non-SegWit wallets to generate a SegWit transaction, and allows non-SegWit client accept SegWit transaction.
+ * `hashbytes` is the 20-byte hash160 of a p2wpkh witness script
+ * Encoded as base58.
+ */
+function p2shp2wpkhAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  const p2shResult = bitcoin.payments.p2sh({
+    redeem: bitcoin.payments.p2wpkh({ pubkey: ecPair.publicKey, network }),
+    network,
+  });
+  if (!p2shResult.address) {
+    throw new Error(
+      `Could not create P2SH-P2WPHK address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
+  }
+  return { ecPair, address: p2shResult.address };
+}
+
+/**
+ * Creates a P2SH-P2WSH "Pay To Witness Script Hash Wrapped In P2SH" address.
+ * Used to generate a segwit P2WSH address nested in a legacy legacy P2SH address.
+ * Typically used for multi-signature wallets, however, this function creates a 1-of-1 "multisig" address.
+ * Allows non-SegWit wallets to generate a SegWit transaction, and allows non-SegWit client accept SegWit transaction.
  */
-export function p2trAddressFromPublicKey(
-  publicKey: Buffer,
-  network: keyof typeof BITCOIN_NETWORKS
-): string {
-  if (publicKey.length === 32) {
-    // Defined in BIP340
-    const X_ONLY_PUB_KEY_TIE_BREAKER = 0x02;
-    publicKey = Buffer.concat([Buffer.from([X_ONLY_PUB_KEY_TIE_BREAKER]), publicKey]);
+function p2shp2wshAddressFromKeys(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  const p2shResult = bitcoin.payments.p2sh({
+    redeem: bitcoin.payments.p2wsh({
+      redeem: bitcoin.payments.p2ms({ m: 1, pubkeys: [ecPair.publicKey], network }),
+      network,
+    }),
+    network,
+  });
+  if (!p2shResult.address) {
+    throw new Error(
+      `Could not create P2SH-P2WPHK address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
   }
-  const ecPair = ECPair.fromPublicKey(publicKey, { compressed: true });
-  const pubKeyBuffer = ecPair.publicKey;
-  if (!pubKeyBuffer) {
-    throw new Error(`Could not get public key`);
+  return { ecPair, address: p2shResult.address };
+}
+
+/**
+ * Creates a P2WPKH "Pay To Witness Public Key Hash" address.
+ * Used to generated standard segwit addresses.
+ * `hashbytes` is the 20-byte hash160 of the witness script.
+ * Encoded as SEGWIT_V0 / bech32.
+ */
+function p2wpkhAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  const p2wpkhResult = bitcoin.payments.p2wpkh({ pubkey: ecPair.publicKey, network });
+  if (!p2wpkhResult.address) {
+    throw new Error(
+      `Could not create p2wpkh address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
   }
+  return { ecPair, address: p2wpkhResult.address };
+}
+
+/**
+ * Creates a P2WSH "Pay To Witness Script Hash" address.
+ * Typically used to generate multi-signature segwit wallets, however, this function creates a 1-of-1 "multisig" address.
+ * `hashbytes` is the 32-byte sha256 of the witness script.
+ * Encoded as SEGWIT_V0 / bech32.
+ */
+function p2wshAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
+
+  const p2wshResult = bitcoin.payments.p2wsh({
+    redeem: bitcoin.payments.p2ms({ m: 1, pubkeys: [ecPair.publicKey], network }),
+    network,
+  });
+  if (!p2wshResult.address) {
+    throw new Error(
+      `Could not create p2wpkh address from pubkey ${ecPair.publicKey.toString('hex')}`
+    );
+  }
+  return { ecPair, address: p2wshResult.address };
+}
+
+/**
+ * Creates a P2TR "Pay To Taproot" address.
+ * Uses the tweaked p2tr key-spend only address encoding recommended by BIP341.
+ * Encoded as SEGWIT_V1 / bech32m.
+ * @see https://github.com/bitcoinjs/bitcoinjs-lib/blob/424abf2376772bb57b7668bc35b29ed18879fa0a/test/integration/taproot.md
+ */
+function p2trAddressFromKey(args: KeyInputArgs): KeyOutput {
+  const network = BITCOIN_NETWORKS[args.network];
+  const ecPair = ecPairFromKeyInputArgs(args, true);
 
   // x-only pubkey (remove 1 byte y parity)
-  const myXOnlyPubkey = pubKeyBuffer.slice(1, 33);
+  const myXOnlyPubkey = ecPair.publicKey.slice(1, 33);
   const commitHash = bitcoin.crypto.taggedHash('TapTweak', myXOnlyPubkey);
   const tweakResult = ecc.xOnlyPointAddTweak(myXOnlyPubkey, commitHash);
   if (tweakResult === null) {
@@ -50,30 +214,57 @@ export function p2trAddressFromPublicKey(
     tweaked,
   ]);
 
-  const address = bitcoin.address.fromOutputScript(scriptPubkey, BITCOIN_NETWORKS[network]);
-  return address;
+  const address = bitcoin.address.fromOutputScript(scriptPubkey, network);
+  return { ecPair, address };
 }
 
-export function p2trAddressFromPrivateKey(
-  privateKey: Buffer,
-  network: keyof typeof BITCOIN_NETWORKS
-): string {
-  const ecPair = ECPair.fromPrivateKey(privateKey, { compressed: true });
-  if (!ecPair.publicKey) {
-    throw new Error(`Could not get public key`);
+export interface VerboseKeyOutput {
+  address: string;
+  wif: string;
+  privateKey: Buffer;
+  publicKey: Buffer;
+}
+
+export function getBitcoinAddressFromKey<TVerbose extends boolean = false>(
+  args: KeyInputArgs & {
+    addressFormat: 'p2pkh' | 'p2sh' | 'p2sh-p2wpkh' | 'p2sh-p2wsh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+    verbose?: TVerbose;
+  }
+): TVerbose extends true ? VerboseKeyOutput : string {
+  const keyOutput: KeyOutput = (() => {
+    switch (args.addressFormat) {
+      case 'p2pkh':
+        return p2pkhAddressFromKey(args);
+      case 'p2sh':
+        return p2shAddressFromKey(args);
+      case 'p2sh-p2wpkh':
+        return p2shp2wpkhAddressFromKey(args);
+      case 'p2sh-p2wsh':
+        return p2shp2wshAddressFromKeys(args);
+      case 'p2wpkh':
+        return p2wpkhAddressFromKey(args);
+      case 'p2wsh':
+        return p2wshAddressFromKey(args);
+      case 'p2tr':
+        return p2trAddressFromKey(args);
+    }
+    throw new Error(`Unexpected address format: ${args.addressFormat}`);
+  })();
+
+  if (args.verbose) {
+    const output: VerboseKeyOutput = {
+      address: keyOutput.address,
+      wif: keyOutput.ecPair.toWIF(),
+      privateKey: keyOutput.ecPair.privateKey as Buffer,
+      publicKey: keyOutput.ecPair.publicKey,
+    };
+    return output as TVerbose extends true ? VerboseKeyOutput : string;
+  } else {
+    return keyOutput.address as TVerbose extends true ? VerboseKeyOutput : string;
   }
-  return p2trAddressFromPublicKey(ecPair.publicKey, network);
 }
 
-export function generateRandomP2TRAccount(
-  network: keyof typeof BITCOIN_NETWORKS
-): {
-  address: string;
-  privateKey: Buffer;
-} {
-  const ecPair = ECPair.makeRandom({ compressed: true });
-  return {
-    address: p2trAddressFromPublicKey(ecPair.publicKey, network),
-    privateKey: ecPair.privateKey as Buffer,
-  };
+export function privateToPublicKey(privateKey: string | Buffer): Buffer {
+  const ecPair = ecPairFromKeyInputArgs({ privateKey, network: 'mainnet' });
+  return ecPair.publicKey;
 }

src/helpers.ts

@@ -25,6 +25,7 @@ import {
 } from 'winston/lib/winston/config';
 import { DbEventTypeId, DbStxEvent, DbTx } from './datastore/common';
 import { StacksCoreRpcClient } from './core-rpc/client';
+import { isArrayBufferView } from 'node:util/types';
 
 export const isDevEnv = process.env.NODE_ENV === 'development';
 export const isTestEnv = process.env.NODE_ENV === 'test';
@@ -525,6 +526,31 @@ export function hexToBuffer(hex: string): Buffer {
   return Buffer.from(hex.substring(2), 'hex');
 }
 
+/**
+ * Decodes a hex string to a Buffer, trims the 0x-prefix if exists.
+ * If already a buffer, returns the input immediately.
+ */
+export function coerceToBuffer(hex: string | Buffer | ArrayBufferView): Buffer {
+  if (typeof hex === 'string') {
+    if (hex.startsWith('0x')) {
+      hex = hex.substring(2);
+    }
+    if (hex.length % 2 !== 0) {
+      throw new Error(`Hex string is an odd number of characters: ${hex}`);
+    }
+    if (!/^[0-9a-fA-F]*$/.test(hex)) {
+      throw new Error(`Hex string contains non-hexadecimal characters: ${hex}`);
+    }
+    return Buffer.from(hex, 'hex');
+  } else if (Buffer.isBuffer(hex)) {
+    return hex;
+  } else if (isArrayBufferView(hex)) {
+    return Buffer.from(hex.buffer, hex.byteOffset, hex.byteLength);
+  } else {
+    throw new Error(`Cannot convert to Buffer, unexpected type: ${hex.constructor.name}`);
+  }
+}
+
 export function hexToUtf8String(hex: string): string {
   const buffer = hexToBuffer(hex);
   return buffer.toString('utf8');