chore(utxo-core): add error classes for util func

christopher-fong · christopher-fong · commit e933da1f747c · 2025-06-20T02:54:12.000-04:00
TICKET: BTC-2047 chore(utxo-core): renamed functions consistent and error prototypes TICKET: BTC-2047 chore(utxo-core): bip32utils to sign and verify message TICKET: BTC-2047 chore(utxo-core): added bitcoinjs-message back to package.json TICKET: BTC-2047 chore(utxo-core): refactored functions and debug tests TICKET: BTC-2047 chore(utxo-core): update verify function TICKET: BTC-2047 chore(utxo-core): updated test and verify TICKET: BTC-2047 chore(utxo-core): clean up rebase conflicts TICKET: BTC-2047 chore(utxo-core): added helper function to create attestation TICKET: BTC-2047
diff --git a/modules/utxo-core/src/paygo/psbt/Errors.ts b/modules/utxo-core/src/paygo/psbt/Errors.ts
@@ -0,0 +1,29 @@
+export class ErrorNoPayGoProof extends Error {
+  constructor(public outputIndex: number) {
+    super(`There is no paygo address proof encoded in the PSBT at output ${outputIndex}.`);
+  }
+}
+
+export class ErrorMultiplePayGoProof extends Error {
+  constructor() {
+    super('There are multiple paygo address proofs encoded in the PSBT. Something went wrong.');
+  }
+}
+
+export class ErrorPayGoAddressProofFailedVerification extends Error {
+  constructor() {
+    super('Cannot verify the paygo address signature with the provided pubkey.');
+  }
+}
+
+export class ErrorOutputIndexOutOfBounds extends Error {
+  constructor(public outputIndex: number) {
+    super(`Output index ${outputIndex} is out of bounds for PSBT outputs.`);
+  }
+}
+
+export class ErrorMultiplePayGoProofAtPsbtIndex extends Error {
+  constructor(public outputIndex: number) {
+    super(`There are multiple PayGo addresses in the PSBT output ${outputIndex}.`);
+  }
+}
diff --git a/modules/utxo-core/src/paygo/psbt/PayGoUtils.ts b/modules/utxo-core/src/paygo/psbt/PayGoUtils.ts
@@ -1,98 +1,84 @@
 import * as utxolib from '@bitgo/utxo-lib';
-import * as bitcoinMessage from 'bitcoinjs-message';
 import { checkForOutput } from 'bip174/src/lib/utils';
 
-import { extractAddressBufferFromPayGoAttestationProof } from '../ExtractAddressPayGoAttestation';
+import { verifyMessage } from '../../bip32utils';
 
-/** The function consumes the signature as a parameter and adds the PayGo address to the
- * PSBT output at the output index where the signature is of the format:
- * 0x18Bitcoin Signed Message:\n<varint_length><ENTROPY><ADDRESS><UUID> signed by
- * the HSM beforehand.
+import {
+  ErrorMultiplePayGoProof,
+  ErrorMultiplePayGoProofAtPsbtIndex,
+  ErrorNoPayGoProof,
+  ErrorOutputIndexOutOfBounds,
+  ErrorPayGoAddressProofFailedVerification,
+} from './Errors';
+
+const NILLUUID = '00000000-0000-0000-0000-000000000000';
+
+/** This function adds the entropy and signature into the PSBT output unknown key vals.
+ * We store the entropy so that we reconstruct the message <ENTROPY><ADDRESS><UUID>
+ * to later verify.
  *
  * @param psbt - PSBT that we need to encode our paygo address into
  * @param outputIndex - the index of the address in our output
  * @param sig - the signature that we want to encode
  */
-export function addPaygoAddressProof(
+export function addPayGoAddressProof(
   psbt: utxolib.bitgo.UtxoPsbt,
   outputIndex: number,
   sig: Buffer,
-  pub: Buffer
+  entropy: Buffer
 ): void {
   utxolib.bitgo.addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'output', outputIndex, {
     key: {
       identifier: utxolib.bitgo.PSBT_PROPRIETARY_IDENTIFIER,
       subtype: utxolib.bitgo.ProprietaryKeySubtype.PAYGO_ADDRESS_ATTESTATION_PROOF,
-      keydata: pub,
+      keydata: entropy,
     },
     value: sig,
   });
 }
 
-/** Verify the paygo address signature is valid using BitGoJs statics
+/** Verify the paygo address signature is valid using verification pub key.
  *
  * @param psbt - PSBT we want to verify that the paygo address is in
  * @param outputIndex - we have the output index that address is in
- * @param pub - The public key that we want to verify the proof with
- * @param message - The message we want to verify corresponding to sig
+ * @param uuid
  * @returns
  */
-export function verifyPaygoAddressProof(
+export function verifyPayGoAddressProof(
   psbt: utxolib.bitgo.UtxoPsbt,
   outputIndex: number,
-  message: Buffer,
-  attestationPubKey: Buffer
+  verificationPubkey: Buffer
 ): void {
   const psbtOutputs = checkForOutput(psbt.data.outputs, outputIndex);
   const stored = utxolib.bitgo.getProprietaryKeyValuesFromUnknownKeyValues(psbtOutputs, {
     identifier: utxolib.bitgo.PSBT_PROPRIETARY_IDENTIFIER,
     subtype: utxolib.bitgo.ProprietaryKeySubtype.PAYGO_ADDRESS_ATTESTATION_PROOF,
   });
-  if (!stored) {
-    throw new Error(`No address proof.`);
-  }
 
   // assert stored length is 0 or 1
   if (stored.length === 0) {
-    throw new Error(`There is no paygo address proof encoded in the PSBT at output ${outputIndex}.`);
+    throw new ErrorNoPayGoProof(outputIndex);
   } else if (stored.length > 1) {
-    throw new Error('There are multiple paygo address proofs encoded in the PSBT. Something went wrong.');
+    throw new ErrorMultiplePayGoProof();
   }
 
+  // We get the signature and entropy from our PSBT unknown key vals
   const signature = stored[0].value;
-  const pub = stored[0].key.keydata;
-
-  // Check that the keydata pubkey is the same as the one we are verifying against
-  if (Buffer.compare(pub, attestationPubKey) !== 0) {
-    throw new Error('The public key in the PSBT does not match the provided public key.');
-  }
-
-  // It doesn't matter that this is bitcoin or not, we just need to convert the public key buffer into an address format
-  // for the verification
-  const messageToVerify = utxolib.address.toBase58Check(
-    utxolib.crypto.hash160(pub),
-    utxolib.networks.bitcoin.pubKeyHash,
-    utxolib.networks.bitcoin
-  );
-
-  if (!bitcoinMessage.verify(message, messageToVerify, signature, utxolib.networks.bitcoin.messagePrefix)) {
-    throw new Error('Cannot verify the paygo address signature with the provided pubkey.');
-  }
-  // We should be verifying the address that was encoded into our message.
-  const addressFromProof = extractAddressBufferFromPayGoAttestationProof(message).toString();
+  const entropy = stored[0].key.keydata;
 
-  // Check that the address from the proof matches what is in the PSBT
+  // Get the the PayGo address from the txOutputs
   const txOutputs = psbt.txOutputs;
   if (outputIndex >= txOutputs.length) {
-    throw new Error(`Output index ${outputIndex} is out of bounds for PSBT outputs.`);
+    throw new ErrorOutputIndexOutOfBounds(outputIndex);
   }
   const output = txOutputs[outputIndex];
   const addressFromOutput = utxolib.address.fromOutputScript(output.script, psbt.network);
 
-  if (addressFromProof !== addressFromOutput) {
-    throw new Error(
-      `The address from the output (${addressFromOutput}) does not match the address that is in the proof (${addressFromProof}).`
-    );
+  // We construct our message <ENTROPY><ADDRESS><UUID>
+  const message = createPayGoAttestationBuffer(addressFromOutput, entropy);
+
+  if (!verifyMessage(message.toString(), verificationPubkey, signature, utxolib.networks.bitcoin)) {
+    throw new ErrorPayGoAddressProofFailedVerification();
   }
 }
 
@@ -103,15 +89,15 @@ export function verifyPaygoAddressProof(
  * @param psbt
  * @returns number - the index of the output address
  */
-export function getPaygoAddressProofOutputIndex(psbt: utxolib.bitgo.UtxoPsbt): number | undefined {
+export function getPayGoAddressProofOutputIndex(psbt: utxolib.bitgo.UtxoPsbt): number | undefined {
   const res = psbt.data.outputs.flatMap((output, outputIndex) => {
     const proprietaryKeyVals = utxolib.bitgo.getPsbtOutputProprietaryKeyVals(output, {
       identifier: utxolib.bitgo.PSBT_PROPRIETARY_IDENTIFIER,
       subtype: utxolib.bitgo.ProprietaryKeySubtype.PAYGO_ADDRESS_ATTESTATION_PROOF,
     });
 
     if (proprietaryKeyVals.length > 1) {
-      throw new Error(`There are multiple PayGo addresses in the PSBT output ${outputIndex}.`);
+      throw new ErrorMultiplePayGoProofAtPsbtIndex(outputIndex);
     }
 
     return proprietaryKeyVals.length === 0 ? [] : [outputIndex];
@@ -121,5 +107,17 @@ export function getPaygoAddressProofOutputIndex(psbt: utxolib.bitgo.UtxoPsbt): n
 }
 
 export function psbtOutputIncludesPaygoAddressProof(psbt: utxolib.bitgo.UtxoPsbt): boolean {
-  return getPaygoAddressProofOutputIndex(psbt) !== undefined;
+  return getPayGoAddressProofOutputIndex(psbt) !== undefined;
+}
+
+/** This function reconstructs the proof <ENTROPY><ADDRESS><UUID>
+ * given the address and entropy.
+ *
+ * @param address
+ * @param entropy
+ * @returns
+ */
+export function createPayGoAttestationBuffer(address: string, entropy: Buffer): Buffer {
+  const addressBuffer = Buffer.from(address);
+  return Buffer.concat([entropy, addressBuffer, Buffer.from(NILLUUID)]);
 }
diff --git a/modules/utxo-core/src/testutil/index.ts b/modules/utxo-core/src/testutil/index.ts
@@ -2,3 +2,4 @@ export * from './fixtures.utils';
 export * from './key.utils';
 export * from './toPlainObject.utils';
 export * from './generatePayGoAttestationProof.utils';
+export * from './parseVaspProof';
diff --git a/modules/utxo-core/src/testutil/parseVaspProof.ts b/modules/utxo-core/src/testutil/parseVaspProof.ts
@@ -0,0 +1,25 @@
+import * as utxolib from '@bitgo/utxo-lib';
+
+/** We receive a proof in the form:
+ * 0x18Bitcoin Signed Message:\n<varint_length><ENTROPY><ADDRESS><UUID>
+ * and when verifying our message in our PayGo utils we want to only verify
+ * the message portion of our proof. This helps to pare our proof in that format,
+ * and returns a Buffer.
+ *
+ * @param proof
+ * @returns
+ */
+export function parseVaspProof(proof: Buffer): Buffer {
+  const prefix = '\u0018Bitcoin Signed Message:\n';
+  if (proof.toString().startsWith(prefix)) {
+    proof = proof.slice(Buffer.from(prefix).length);
+    utxolib.bufferutils.varuint.decode(proof, 0);
+    // Determines how many bytes were consumed during our last varuint.decode(Buffer, offset)
+    // So if varuint.decode(0xfd) then varuint.decode.bytes = 3
+    // varuint.decode(0xfe) then varuint.decode.bytes = 5, etc.
+    const varintBytesLength = utxolib.bufferutils.varuint.decode.bytes;
+
+    proof.slice(varintBytesLength);
+  }
+  return proof;
+}
diff --git a/modules/utxo-core/test/paygo/psbt/PayGoUtils.ts b/modules/utxo-core/test/paygo/psbt/PayGoUtils.ts
@@ -1,18 +1,21 @@
 import assert from 'assert';
+import crypto from 'crypto';
 
 import * as utxolib from '@bitgo/utxo-lib';
-import * as bitcoinMessage from 'bitcoinjs-message';
 import { decodeProprietaryKey } from 'bip174/src/lib/proprietaryKeyVal';
 import { KeyValue } from 'bip174/src/lib/interfaces';
 import { checkForOutput } from 'bip174/src/lib/utils';
 
 import {
-  addPaygoAddressProof,
-  getPaygoAddressProofOutputIndex,
+  addPayGoAddressProof,
+  createPayGoAttestationBuffer,
+  getPayGoAddressProofOutputIndex,
   psbtOutputIncludesPaygoAddressProof,
-  verifyPaygoAddressProof,
+  verifyPayGoAddressProof,
 } from '../../../src/paygo/psbt/PayGoUtils';
 import { generatePayGoAttestationProof } from '../../../src/testutil/generatePayGoAttestationProof.utils';
+import { parseVaspProof } from '../../../src/testutil/parseVaspProof';
+import { signMessage } from '../../../src/bip32utils';
 
 // To construct our PSBTs
 const network = utxolib.networks.bitcoin;
@@ -35,7 +38,7 @@ const attestationPubKey = dummyPub1.user.publicKey;
 const attestationPrvKey = dummyPub1.user.privateKey!;
 
 // UUID structure
-const nilUUID = '00000000-0000-0000-0000-000000000000';
+const nillUUID = '00000000-0000-0000-0000-000000000000';
 
 // our xpub converted to base58 address
 const addressToVerify = utxolib.address.toBase58Check(
@@ -45,9 +48,13 @@ const addressToVerify = utxolib.address.toBase58Check(
 );
 
 // this should be retuning a Buffer
-const addressProofBuffer = generatePayGoAttestationProof(nilUUID, Buffer.from(addressToVerify));
+const addressProofBuffer = generatePayGoAttestationProof(nillUUID, Buffer.from(addressToVerify));
+const addressProofMsgBuffer = parseVaspProof(addressProofBuffer);
+// We know that that the entropy is a set 64 bytes.
+const addressProofEntropy = addressProofMsgBuffer.subarray(0, 65);
+
 // signature with the given msg addressProofBuffer
-const sig = bitcoinMessage.sign(addressProofBuffer, attestationPrvKey!, true, network.messagePrefix);
+const sig = signMessage(addressProofMsgBuffer.toString(), attestationPrvKey!, network);
 
 function getTestPsbt() {
   return utxolib.testutil.constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
@@ -67,38 +74,25 @@ describe('addPaygoAddressProof and verifyPaygoAddressProof', () => {
       });
   }
 
-  it("should fail a proof verification if the proof isn't valid", () => {
-    const outputIndex = 0;
-    const psbt = getTestPsbt();
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
-    const output = checkForOutput(psbt.data.outputs, outputIndex);
-    const proofInPsbt = getPaygoProprietaryKey(output.unknownKeyVals!);
-    assert(proofInPsbt.length === 1);
-    assert.throws(
-      () => verifyPaygoAddressProof(psbt, 0, Buffer.from('Random Signed Message'), attestationPubKey),
-      (e: any) => e.message === 'Cannot verify the paygo address signature with the provided pubkey.'
-    );
-  });
-
   it('should add and verify a valid paygo address proof on the PSBT', () => {
     const psbt = getTestPsbt();
     psbt.addOutput({ script: utxolib.address.toOutputScript(addressToVerify, network), value: BigInt(10000) });
     const outputIndex = psbt.data.outputs.length - 1;
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
-    verifyPaygoAddressProof(psbt, outputIndex, Buffer.from(addressProofBuffer), attestationPubKey);
+    addPayGoAddressProof(psbt, outputIndex, sig, addressProofEntropy);
+    verifyPayGoAddressProof(psbt, outputIndex, attestationPubKey);
   });
 
   it('should throw an error if there are multiple PayGo proprietary keys in the PSBT', () => {
     const outputIndex = 0;
     const psbt = getTestPsbt();
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
-    addPaygoAddressProof(psbt, outputIndex, Buffer.from('signature2'), Buffer.from('fakepubkey2s'));
+    addPayGoAddressProof(psbt, outputIndex, sig, addressProofEntropy);
+    addPayGoAddressProof(psbt, outputIndex, Buffer.from('signature2'), crypto.randomBytes(64));
     const output = checkForOutput(psbt.data.outputs, outputIndex);
     const proofInPsbt = getPaygoProprietaryKey(output.unknownKeyVals!);
     assert(proofInPsbt.length !== 0);
     assert(proofInPsbt.length > 1);
     assert.throws(
-      () => verifyPaygoAddressProof(psbt, outputIndex, addressProofBuffer, attestationPubKey),
+      () => verifyPayGoAddressProof(psbt, outputIndex, attestationPubKey),
       (e: any) => e.message === 'There are multiple paygo address proofs encoded in the PSBT. Something went wrong.'
     );
   });
@@ -108,7 +102,7 @@ describe('verifyPaygoAddressProof', () => {
   it('should throw an error if there is no PayGo address in PSBT', () => {
     const psbt = getTestPsbt();
     assert.throws(
-      () => verifyPaygoAddressProof(psbt, 0, addressProofBuffer, attestationPubKey),
+      () => verifyPayGoAddressProof(psbt, 0, attestationPubKey),
       (e: any) => e.message === 'There is no paygo address proof encoded in the PSBT at output 0.'
     );
   });
@@ -118,25 +112,43 @@ describe('getPaygoAddressProofIndex', () => {
   it('should get PayGo address proof index from PSBT if there is one', () => {
     const psbt = getTestPsbt();
     const outputIndex = 0;
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
+    addPayGoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
     assert(psbtOutputIncludesPaygoAddressProof(psbt));
-    assert(getPaygoAddressProofOutputIndex(psbt) === 0);
+    assert(getPayGoAddressProofOutputIndex(psbt) === 0);
   });
 
   it('should return undefined if there is no PayGo address proof in PSBT', () => {
     const psbt = getTestPsbt();
-    assert(getPaygoAddressProofOutputIndex(psbt) === undefined);
+    assert(getPayGoAddressProofOutputIndex(psbt) === undefined);
     assert(!psbtOutputIncludesPaygoAddressProof(psbt));
   });
 
   it('should return an error and fail if we have multiple PayGo address in the PSBT in the same output index', () => {
     const psbt = getTestPsbt();
     const outputIndex = 0;
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from(attestationPubKey));
-    addPaygoAddressProof(psbt, outputIndex, sig, Buffer.from('xpub12345abcdef29a028510d3b2d4'));
+    addPayGoAddressProof(psbt, outputIndex, sig, addressProofEntropy);
+    addPayGoAddressProof(psbt, outputIndex, sig, crypto.randomBytes(64));
     assert.throws(
-      () => getPaygoAddressProofOutputIndex(psbt),
+      () => getPayGoAddressProofOutputIndex(psbt),
       (e: any) => e.message === 'There are multiple PayGo addresses in the PSBT output 0.'
     );
   });
 });
+
+describe('createPayGoAttestationBuffer', () => {
+  it('should create a PayGo Attestation proof matching with original proof', () => {
+    const payGoAttestationProof = createPayGoAttestationBuffer(addressToVerify, addressProofEntropy);
+    assert.strictEqual(payGoAttestationProof.toString(), addressProofMsgBuffer.toString());
+    assert(Buffer.compare(payGoAttestationProof, addressProofMsgBuffer) === 0);
+  });
+
+  it('should create a PayGo Attestation proof that does not match with different uuid', () => {
+    const addressProofBufferDiffUuid = generatePayGoAttestationProof(
+      '00000000-0000-0000-0000-000000000001',
+      Buffer.from(addressToVerify)
+    );
+    const payGoAttestationProof = createPayGoAttestationBuffer(addressToVerify, addressProofEntropy);
+    assert.notStrictEqual(payGoAttestationProof.toString(), addressProofBufferDiffUuid.toString());
+    assert(Buffer.compare(payGoAttestationProof, addressProofBufferDiffUuid) !== 0);
+  });
+});
diff --git a/modules/utxo-lib/src/bitgo/UtxoPsbt.ts b/modules/utxo-lib/src/bitgo/UtxoPsbt.ts
