Merge pull request #6266 from BitGo/BTC-2183.outputProprietaryKeyVals-functions

feat(utxo-lib): Added util functions to add proprietary key vals to output of PSBT

Author: christopher-fong

modules/utxo-lib/src/bitgo/Musig2.ts

@@ -12,12 +12,8 @@ import { Tuple } from './types';
 import { calculateTapTweak, tapTweakPubkey } from '../taproot';
 import { Transaction } from '../index';
 import { PsbtInput } from 'bip174/src/lib/interfaces';
-import {
-  getPsbtInputProprietaryKeyVals,
-  ProprietaryKeySubtype,
-  ProprietaryKeyValue,
-  PSBT_PROPRIETARY_IDENTIFIER,
-} from './PsbtUtil';
+import { getPsbtInputProprietaryKeyVals, ProprietaryKeySubtype, PSBT_PROPRIETARY_IDENTIFIER } from './PsbtUtil';
+import { ProprietaryKeyValue } from './ProprietaryKeyValUtils';
 
 /**
  *  Participant key value object.

modules/utxo-lib/src/bitgo/ProprietaryKeyValUtils.ts

@@ -0,0 +1,112 @@
+import { PsbtInput, PsbtOutput } from 'bip174/src/lib/interfaces';
+import { decodeProprietaryKey, encodeProprietaryKey, ProprietaryKey } from 'bip174/src/lib/proprietaryKeyVal';
+import { UtxoPsbt } from './UtxoPsbt';
+
+/**
+ * Psbt proprietary keydata object search fields.
+ * <compact size uint identifier length> <bytes identifier> <compact size uint subtype> <bytes subkeydata>
+ */
+export interface ProprietaryKeySearch {
+  identifier: string;
+  subtype?: number;
+  keydata?: Buffer;
+  identifierEncoding?: BufferEncoding;
+}
+/**
+ * Psbt proprietary keydata object.
+ * <compact size uint identifier length> <bytes identifier> <compact size uint subtype> <bytes subkeydata>
+ * => <bytes valuedata>
+ */
+export interface ProprietaryKeyValue {
+  key: ProprietaryKey;
+  value: Buffer;
+}
+
+export function getProprietaryKeyValuesFromUnknownKeyValues(
+  psbtField: PsbtInput | PsbtOutput,
+  keySearch?: ProprietaryKeySearch
+): ProprietaryKeyValue[] {
+  if (!psbtField.unknownKeyVals?.length) {
+    return [];
+  }
+
+  if (keySearch && keySearch.subtype === undefined && Buffer.isBuffer(keySearch.keydata)) {
+    throw new Error('invalid proprietary key search filter combination. subtype is required');
+  }
+  const keyVals = psbtField.unknownKeyVals.map(({ key, value }, i) => {
+    return { key: decodeProprietaryKey(key), value };
+  });
+  return keyVals.filter((keyVal) => {
+    return (
+      keySearch === undefined ||
+      (keySearch.identifier === keyVal.key.identifier &&
+        (keySearch.subtype === undefined ||
+          (keySearch.subtype === keyVal.key.subtype &&
+            (!Buffer.isBuffer(keySearch.keydata) || keySearch.keydata.equals(keyVal.key.keydata)))))
+    );
+  });
+}
+
+export function deleteProprietaryKeyValuesFromUnknownKeyValues(
+  psbtField: PsbtInput | PsbtOutput,
+  keysToDelete?: ProprietaryKeySearch
+): void {
+  if (!psbtField.unknownKeyVals?.length) {
+    return;
+  }
+
+  if (keysToDelete && keysToDelete.subtype === undefined && Buffer.isBuffer(keysToDelete.keydata)) {
+    throw new Error('invalid proprietary key search filter combination. subtype is required');
+  }
+  psbtField.unknownKeyVals = psbtField.unknownKeyVals.filter((keyValue, i) => {
+    const key = decodeProprietaryKey(keyValue.key);
+    return !(
+      keysToDelete === undefined ||
+      (keysToDelete.identifier === key.identifier &&
+        (keysToDelete.subtype === undefined ||
+          (keysToDelete.subtype === key.subtype &&
+            (!Buffer.isBuffer(keysToDelete.keydata) || keysToDelete.keydata.equals(key.keydata)))))
+    );
+  });
+}
+
+export function updateProprietaryKeyValuesFromUnknownKeyValues(
+  keyValueData: ProprietaryKeyValue,
+  psbtField: PsbtInput | PsbtOutput
+): void {
+  if (!psbtField.unknownKeyVals?.length) {
+    return;
+  }
+
+  const key = encodeProprietaryKey(keyValueData.key);
+  const { value } = keyValueData;
+  const ukvIndex = psbtField.unknownKeyVals.findIndex((ukv) => ukv.key.equals(key));
+  if (ukvIndex <= -1) {
+    throw new Error(`The Key-Value pair does not exist within the PSBT.`);
+  }
+  psbtField.unknownKeyVals[ukvIndex] = { key, value };
+}
+
+export function addProprietaryKeyValuesFromUnknownKeyValues(
+  psbt: UtxoPsbt,
+  entry: string,
+  index: number,
+  keyValueData: ProprietaryKeyValue
+): void {
+  if (index < 0) {
+    throw new Error('Not a valid index within the PSBT to add proprietary key value.');
+  }
+  if (entry === 'input') {
+    psbt.addUnknownKeyValToInput(index, {
+      key: encodeProprietaryKey(keyValueData.key),
+      value: keyValueData.value,
+    });
+  } else if (entry === 'output') {
+    psbt.addUnknownKeyValToOutput(index, {
+      key: encodeProprietaryKey(keyValueData.key),
+      value: keyValueData.value,
+    });
+  } else {
+    throw new Error("Not a valid PSBT entry, only valid for 'input' or 'output'.");
+  }
+}

modules/utxo-lib/src/bitgo/PsbtUtil.ts

@@ -1,7 +1,12 @@
-import { decodeProprietaryKey, ProprietaryKey } from 'bip174/src/lib/proprietaryKeyVal';
-import { PsbtInput } from 'bip174/src/lib/interfaces';
+import { PsbtInput, PsbtOutput } from 'bip174/src/lib/interfaces';
 import { Psbt } from 'bitcoinjs-lib/src/psbt';
 
+import {
+  getProprietaryKeyValuesFromUnknownKeyValues,
+  ProprietaryKeySearch,
+  ProprietaryKeyValue,
+} from './ProprietaryKeyValUtils';
+
 /**
  * bitgo proprietary key identifier
  */
@@ -17,27 +22,6 @@ export enum ProprietaryKeySubtype {
   MUSIG2_PARTIAL_SIG = 0x03,
 }
 
-/**
- * Psbt proprietary keydata object.
- * <compact size uint identifier length> <bytes identifier> <compact size uint subtype> <bytes subkeydata>
- * => <bytes valuedata>
- */
-export interface ProprietaryKeyValue {
-  key: ProprietaryKey;
-  value: Buffer;
-}
-
-/**
- * Psbt proprietary keydata object search fields.
- * <compact size uint identifier length> <bytes identifier> <compact size uint subtype> <bytes subkeydata>
- */
-export interface ProprietaryKeySearch {
-  identifier: string;
-  subtype?: number;
-  keydata?: Buffer;
-  identifierEncoding?: BufferEncoding;
-}
-
 /**
  * Search any data from psbt proprietary key value against keydata.
  * Default identifierEncoding is utf-8 for identifier.
@@ -49,21 +33,17 @@ export function getPsbtInputProprietaryKeyVals(
   if (!input.unknownKeyVals?.length) {
     return [];
   }
-  if (keySearch && keySearch.subtype === undefined && Buffer.isBuffer(keySearch.keydata)) {
-    throw new Error('invalid proprietary key search filter combination. subtype is required');
+  return getProprietaryKeyValuesFromUnknownKeyValues(input, keySearch);
+}
+
+export function getPsbtOutputProprietaryKeyVals(
+  output: PsbtOutput,
+  keySearch?: ProprietaryKeySearch
+): ProprietaryKeyValue[] {
+  if (!output.unknownKeyVals?.length) {
+    return [];
   }
-  const keyVals = input.unknownKeyVals.map(({ key, value }, i) => {
-    return { key: decodeProprietaryKey(key), value };
-  });
-  return keyVals.filter((keyVal) => {
-    return (
-      keySearch === undefined ||
-      (keySearch.identifier === keyVal.key.identifier &&
-        (keySearch.subtype === undefined ||
-          (keySearch.subtype === keyVal.key.subtype &&
-            (!Buffer.isBuffer(keySearch.keydata) || keySearch.keydata.equals(keyVal.key.keydata)))))
-    );
-  });
+  return getProprietaryKeyValuesFromUnknownKeyValues(output, keySearch);
 }
 
 /**

modules/utxo-lib/src/bitgo/UtxoPsbt.ts

@@ -57,11 +57,10 @@ import { getTaprootOutputKey } from '../taproot';
 import {
   getPsbtInputProprietaryKeyVals,
   getPsbtInputSignatureCount,
-  ProprietaryKeySearch,
   ProprietaryKeySubtype,
-  ProprietaryKeyValue,
   PSBT_PROPRIETARY_IDENTIFIER,
 } from './PsbtUtil';
+import { ProprietaryKeySearch, ProprietaryKeyValue } from './ProprietaryKeyValUtils';
 
 type SignatureParams = {
   /** When true, and add the second (last) nonce and signature for a taproot key
@@ -1076,6 +1075,8 @@ export class UtxoPsbt<Tx extends UtxoTransaction<bigint> = UtxoTransaction<bigin
   }
 
   /**
+   * @deprecated Please use the new method addProprietaryKeyVals(psbt, entry, index, keyValueData)
+   *
    * Adds proprietary key value pair to PSBT input.
    * Default identifierEncoding is utf-8 for identifier.
    */
@@ -1087,6 +1088,9 @@ export class UtxoPsbt<Tx extends UtxoTransaction<bigint> = UtxoTransaction<bigin
   }
 
   /**
+   * @deprecated Please use the new method addProprietaryKeyValuesToUnknownKeyValues(psbt, entry, index, keyValueData)
+   *  or updateProprietaryKeyValuesToUnknownKeyValues(keyValueData)
+   *
    * Adds or updates (if exists) proprietary key value pair to PSBT input.
    * Default identifierEncoding is utf-8 for identifier.
    */
@@ -1109,7 +1113,10 @@ export class UtxoPsbt<Tx extends UtxoTransaction<bigint> = UtxoTransaction<bigin
   }
 
   /**
-   * To search any data from proprietary key value against keydata.
+   * @deprecated Please use getProprietaryKeyValuesFromUnknownKeyValues(psbtField, keySearch). The new method
+   * allows for the retrieval of either input or output proprietary key values.
+   *
+   * To search any data from proprietary key value against keydata in the inputs.
    * Default identifierEncoding is utf-8 for identifier.
    */
   getProprietaryKeyVals(inputIndex: number, keySearch?: ProprietaryKeySearch): ProprietaryKeyValue[] {
@@ -1118,7 +1125,10 @@ export class UtxoPsbt<Tx extends UtxoTransaction<bigint> = UtxoTransaction<bigin
   }
 
   /**
-   * To delete any data from proprietary key value.
+   * @deprecated Please use deleteProprietaryKeyValues(type, index, keysToDelete?). The new method
+   * allows for the deletion of either input or output proprietary key values.
+   *
+   * To delete any data from proprietary key value in PSBT input.
    * Default identifierEncoding is utf-8 for identifier.
    */
   deleteProprietaryKeyVals(inputIndex: number, keysToDelete?: ProprietaryKeySearch): this {

modules/utxo-lib/src/bitgo/index.ts

@@ -21,6 +21,7 @@ export * from './zcash';
 export * from './tnumber';
 export * from './litecoin';
 export * from './PsbtUtil';
+export * from './ProprietaryKeyValUtils';
 
 import { PsbtInput } from 'bip174/src/lib/interfaces';
 /**

modules/utxo-lib/test/bitgo/psbt/ProprietaryKeyVals.ts

@@ -0,0 +1,118 @@
+import * as assert from 'assert';
+import { constructPsbt } from '../../../src/testutil';
+import { bip32, BIP32Interface, networks, testutil } from '../../../src';
+import { RootWalletKeys, PSBT_PROPRIETARY_IDENTIFIER } from '../../../src/bitgo';
+import { checkForInput, checkForOutput } from 'bip174/src/lib/utils';
+import {
+  addProprietaryKeyValuesFromUnknownKeyValues,
+  deleteProprietaryKeyValuesFromUnknownKeyValues,
+  getProprietaryKeyValuesFromUnknownKeyValues,
+  updateProprietaryKeyValuesFromUnknownKeyValues,
+} from '../../../src/bitgo/ProprietaryKeyValUtils';
+
+const network = networks.bitcoin;
+const keys = [1, 2, 3].map((v) => bip32.fromSeed(Buffer.alloc(16, `test/2/${v}`), network)) as BIP32Interface[];
+const rootWalletKeys = new RootWalletKeys([keys[0], keys[1], keys[2]]);
+const dummyKey1 = rootWalletKeys.deriveForChainAndIndex(50, 200);
+const dummyTapOutputKey = dummyKey1.user.publicKey.subarray(1, 33);
+const dummyTapInternalKey = dummyKey1.bitgo.publicKey.subarray(1, 33);
+
+const invalidTapOutputKey = Buffer.alloc(1);
+const psbtInputs = testutil.inputScriptTypes.map((scriptType) => ({
+  scriptType,
+  value: BigInt(1000),
+}));
+const psbtOutputs = testutil.outputScriptTypes.map((scriptType) => ({
+  scriptType,
+  value: BigInt(900),
+}));
+
+describe('Proprietary key value helper functions', () => {
+  it('addProprietaryKeyValues to PSBT input unknown key vals', function () {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const input = checkForInput(psbt.data.inputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'input', 0, { key, value: dummyTapInternalKey });
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(input);
+    assert.strictEqual(keyVal[0].key.identifier, 'DUMMY');
+  });
+
+  it('addProprietaryKeyValues to PSBT output unknown key vals', function () {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const output = checkForOutput(psbt.data.outputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'output', 0, { key, value: dummyTapInternalKey });
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(output);
+    assert.strictEqual(keyVal[0].key.identifier, 'DUMMY');
+  });
+
+  it('addOrUpdateProprietaryKeyValues to PSBT input unknown key vals', () => {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const input = checkForInput(psbt.data.inputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'input', 0, { key, value: dummyTapInternalKey });
+    updateProprietaryKeyValuesFromUnknownKeyValues({ key, value: invalidTapOutputKey }, input);
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(input);
+    assert.strictEqual(keyVal[0].value, invalidTapOutputKey);
+  });
+
+  it('addOrUpdateProprietaryKeyValues to PSBT output unknown key vals', () => {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const output = checkForOutput(psbt.data.outputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'output', 0, { key, value: dummyTapInternalKey });
+    updateProprietaryKeyValuesFromUnknownKeyValues({ key, value: invalidTapOutputKey }, output);
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(output);
+    assert.strictEqual(keyVal[0].value, invalidTapOutputKey);
+  });
+
+  it('deleteProprietaryKeyValues in PSBT input unknown key vals', () => {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const input = checkForInput(psbt.data.inputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'input', 0, { key, value: dummyTapInternalKey });
+    deleteProprietaryKeyValuesFromUnknownKeyValues(input, { identifier: PSBT_PROPRIETARY_IDENTIFIER });
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(input);
+    assert.strictEqual(keyVal[0].key.identifier, 'DUMMY');
+  });
+
+  it('deleteProprietaryKeyValues in PSBT output unknown key vals', () => {
+    const psbt = constructPsbt(psbtInputs, psbtOutputs, network, rootWalletKeys, 'unsigned');
+    const key = {
+      identifier: 'DUMMY',
+      subtype: 100,
+      keydata: dummyTapOutputKey,
+    };
+    const key2 = {
+      identifier: 'OTHER_DUMMY',
+      subtype: 200,
+      keydata: dummyTapOutputKey,
+    };
+    const output = checkForOutput(psbt.data.outputs, 0);
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'output', 0, { key, value: dummyTapInternalKey });
+    addProprietaryKeyValuesFromUnknownKeyValues(psbt, 'output', 0, { key: key2, value: dummyTapInternalKey });
+    deleteProprietaryKeyValuesFromUnknownKeyValues(output, { identifier: 'DUMMY' });
+    const keyVal = getProprietaryKeyValuesFromUnknownKeyValues(output);
+    assert.strictEqual(keyVal[0].key.identifier, 'OTHER_DUMMY');
+  });
+});