Merge pull request #5642 from BitGo/BTC-1826.utxo-core-feature-parity

OttoAllmendinger · web-flow · commit 774028bd1e61 · 2025-02-26T20:33:29.000+01:00
feat(utxo-core): enhance descriptor and PSBT functionality
diff --git a/modules/abstract-utxo/src/transaction/descriptor/explainPsbt.ts b/modules/abstract-utxo/src/transaction/descriptor/explainPsbt.ts
@@ -5,7 +5,7 @@ import * as coreDescriptors from '@bitgo/utxo-core/descriptor';
 import { toExtendedAddressFormat } from '../recipient';
 import { TransactionExplanation } from '../../abstractUtxoCoin';
 
-function toRecipient(output: coreDescriptors.psbt.ParsedOutput, network: utxolib.Network): ITransactionRecipient {
+function toRecipient(output: coreDescriptors.ParsedOutput, network: utxolib.Network): ITransactionRecipient {
   return {
     address: toExtendedAddressFormat(output.script, network),
     amount: output.value.toString(),
diff --git a/modules/abstract-utxo/src/transaction/descriptor/parse.ts b/modules/abstract-utxo/src/transaction/descriptor/parse.ts
@@ -15,7 +15,7 @@ import { IDescriptorWallet } from '../../descriptor/descriptorWallet';
 import { fromExtendedAddressFormatToScript, toExtendedAddressFormat } from '../recipient';
 import { outputDifferencesWithExpected, OutputDifferenceWithExpected } from '../outputDifference';
 
-type ParsedOutput = coreDescriptors.psbt.ParsedOutput;
+type ParsedOutput = coreDescriptors.ParsedOutput;
 
 export type RecipientOutput = Omit<ParsedOutput, 'value'> & {
   value: bigint | 'max';
diff --git a/modules/abstract-utxo/src/transaction/descriptor/signPsbt.ts b/modules/abstract-utxo/src/transaction/descriptor/signPsbt.ts
@@ -1,5 +1,5 @@
 import * as utxolib from '@bitgo/utxo-lib';
-import { DescriptorMap, psbt } from '@bitgo/utxo-core/descriptor';
+import { DescriptorMap, findDescriptorForInput } from '@bitgo/utxo-core/descriptor';
 
 export class ErrorUnknownInput extends Error {
   constructor(public vin: number) {
@@ -31,7 +31,7 @@ export function signPsbt(
   }
 ): void {
   for (const [vin, input] of tx.data.inputs.entries()) {
-    if (!psbt.findDescriptorForInput(input, descriptorMap)) {
+    if (!findDescriptorForInput(input, descriptorMap)) {
       switch (params.onUnknownInput) {
         case 'skip':
           continue;
diff --git a/modules/utxo-core/src/bip65/index.ts b/modules/utxo-core/src/bip65/index.ts
@@ -0,0 +1 @@
+export * from './locktime';
diff --git a/modules/utxo-core/src/bip65/locktime.ts b/modules/utxo-core/src/bip65/locktime.ts
@@ -0,0 +1,40 @@
+/*
+
+Modified version of https://github.com/bitcoinjs/bip65/blob/master/index.js
+
+BIP0065: https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki
+
+*/
+
+// https://github.com/bitcoin/bitcoin/blob/v28.0/src/script/script.h#L44-L46
+const LOCKTIME_THRESHOLD = 500_000_000;
+
+/**
+ * @param obj
+ * @return number
+ */
+export function encodeLocktime(obj: Date | { blocks: number }): number {
+  if (obj instanceof Date) {
+    if (!Number.isFinite(obj.getTime())) {
+      throw new Error('invalid date');
+    }
+    const seconds = Math.floor(obj.getTime() / 1000);
+    if (seconds < LOCKTIME_THRESHOLD) {
+      throw new TypeError('Expected Number utc >= ' + LOCKTIME_THRESHOLD);
+    }
+
+    return seconds;
+  }
+
+  const { blocks } = obj;
+
+  if (!Number.isFinite(blocks) || !Number.isInteger(blocks)) {
+    throw new TypeError('Expected Number blocks');
+  }
+
+  if (blocks >= LOCKTIME_THRESHOLD) {
+    throw new TypeError('Expected Number blocks < ' + LOCKTIME_THRESHOLD);
+  }
+
+  return blocks;
+}
diff --git a/modules/utxo-core/src/descriptor/VirtualSize.ts b/modules/utxo-core/src/descriptor/VirtualSize.ts
@@ -1,7 +1,9 @@
+import * as utxolib from '@bitgo/utxo-lib';
 import { Dimensions, VirtualSizes } from '@bitgo/unspents';
 import { Descriptor } from '@bitgo/wasm-miniscript';
 
 import { DescriptorMap } from './DescriptorMap';
+import { findDescriptorForInput } from './psbt';
 
 function getScriptPubKeyLength(descType: string): number {
   // See https://bitcoinops.org/en/tools/calc-size/
@@ -105,3 +107,15 @@ export function getVirtualSize(
   // we will just assume that we have at least one segwit input
   return inputVSize + outputVSize + VirtualSizes.txSegOverheadVSize;
 }
+
+export function getVirtualSizeEstimateForPsbt(psbt: utxolib.Psbt, descriptorMap: DescriptorMap): number {
+  const inputs = psbt.data.inputs.map((i) => {
+    const result = findDescriptorForInput(i, descriptorMap);
+    if (!result) {
+      throw new Error('Could not find descriptor for input');
+    }
+    return result.descriptor;
+  });
+  const outputs = psbt.txOutputs.map((o) => ({ script: o.script }));
+  return getVirtualSize({ inputs, outputs });
+}
diff --git a/modules/utxo-core/src/descriptor/index.ts b/modules/utxo-core/src/descriptor/index.ts
@@ -1,9 +1,4 @@
-export type { Output, DescriptorWalletOutput, WithDescriptor, WithOptDescriptor } from './Output';
-export type { DescriptorMap } from './DescriptorMap';
-export * as psbt from './psbt';
-export type { PsbtParams } from './psbt';
-
-export { createAddressFromDescriptor, createScriptPubKeyFromDescriptor } from './address';
-export { createPsbt, finalizePsbt, parse } from './psbt';
-export { toDescriptorMap } from './DescriptorMap';
-export { toDerivedDescriptorWalletOutput } from './Output';
+export * from './psbt';
+export * from './address';
+export * from './DescriptorMap';
+export * from './Output';
diff --git a/modules/utxo-core/src/dustThreshold.ts b/modules/utxo-core/src/dustThreshold.ts
@@ -0,0 +1,157 @@
+import * as utxolib from '@bitgo/utxo-lib';
+
+/**
+ * Checks if the output script is a witness script or not
+ * @param script
+ * @returns true if the script is a witness script
+ */
+function isWitnessOutputScript(script: Buffer): boolean {
+  /**
+   * Source: https://github.com/bitcoin/bitcoin/blob/v28.1/src/script/script.cpp#L241-L257
+   * A witness program is any valid CScript that consists of a 1-byte push opcode
+   * followed by a data push between 2 and 40 bytes.
+   */
+  if (script.length < 4 || script.length > 42) {
+    return false;
+  }
+  if (script[0] !== utxolib.opcodes.OP_0 && (script[0] < utxolib.opcodes.OP_1 || script[0] > utxolib.opcodes.OP_16)) {
+    return false;
+  }
+  return script[1] + 2 === script.length;
+}
+
+/*
+
+The dust threshold for most UTXO coins is dependent on multiple factors:
+
+(1) spendability of the output (OP_RETURNs are allowed to be 0 sized)
+(2) whether it is a witness or non-witness output
+(3) a particular fee rate (GetDiscardRate())
+
+I will do the analysis mostly for bitcoin here and then generalize.
+
+On the indexer we use `sendrawtransaction`, which calls `IsStandardTx` like this
+
+https://github.com/bitcoin/bitcoin/blob/v28.0/src/kernel/mempool_options.h#L47
+
+```
+if (
+  m_pool.m_opts.require_standard &&
+   !IsStandardTx(tx,
+   m_pool.m_opts.max_datacarrier_bytes,
+   m_pool.m_opts.permit_bare_multisig,
+   m_pool.m_opts.dust_relay_feerate, reason))
+```
+
+The `dust_relay_feerate` in this context is a hardcoded constant:
+https://github.com/bitcoin/bitcoin/blob/v28.0/src/policy/policy.h#L50-L55
+
+(that can actually be overridden with a hidden command
+line parameter: https://bitcoin.stackexchange.com/a/41082/137601)
+
+There we call `IsDust`
+
+https://github.com/bitcoin/bitcoin/blob/v28.0/src/policy/policy.cpp#L144-L146
+
+```
+if (IsDust(txout, dust_relay_fee)) {
+    reason = "dust";
+    return false;
+}
+```
+
+Which calls `GetDustThreshold`,
+
+https://github.com/bitcoin/bitcoin/blob/v28.0/src/policy/policy.cpp#L67
+
+The implementation of `GetDustThreshold` computes the minimal transaction size that can spend the output, and computes
+a minimum fee for that transaction size based on the `dust_relay_fee` (FeeRate) parameter.
+
+The different utxo implementations differ in these ways:
+
+- some have a fixed, satoshi amount dust limit (doge, zec)
+- some have a different dust_relay_fee
+
+*/
+
+type DustLimit = { feeRateSatKB: number } | { satAmount: number };
+
+function getDustRelayLimit(network: utxolib.Network): DustLimit {
+  network = utxolib.getMainnet(network);
+  switch (network) {
+    case utxolib.networks.bitcoin:
+    case utxolib.networks.bitcoingold:
+    case utxolib.networks.dash:
+      // btc:  https://github.com/bitcoin/bitcoin/blob/v28.0/src/policy/policy.h#L50-L55
+      // btg:  https://github.com/BTCGPU/BTCGPU/blob/v0.17.3/src/policy/policy.h#L48
+      // dash: https://github.com/dashpay/dash/blob/v22.0.0-beta.1/src/policy/policy.h#L41-L46
+      return { feeRateSatKB: 3000 };
+    case utxolib.networks.bitcoincash:
+      // https://github.com/bitcoin-cash-node/bitcoin-cash-node/blob/v27.1.0/src/policy/policy.h#L76-L83
+      // I actually haven't looked at BSV and am depressed that I still need to handle the case here
+      return { feeRateSatKB: 1000 };
+    case utxolib.networks.dogecoin:
+      // https://github.com/dogecoin/dogecoin/blob/v1.14.8/src/policy/policy.h#L65-L81
+      // (COIN / 100) / 10;
+      return { satAmount: 1_000_000 };
+    case utxolib.networks.litecoin:
+      //  https://github.com/litecoin-project/litecoin/blob/master/src/policy/policy.h#L47-L52
+      return { feeRateSatKB: 30_000 };
+    case utxolib.networks.zcash:
+      // https://github.com/zcash/zcash/blob/master/src/primitives/transaction.h#L396-L399
+      // https://github.com/zcash/zcash/blob/v6.0.0/src/policy/policy.h#L43-L89 (I don't quite get it)
+      return { satAmount: 300 };
+    case utxolib.networks.bitcoinsv:
+      throw new Error('deprecated coin');
+    default:
+      throw new Error('unsupported network');
+  }
+}
+
+function getSpendSize(network: utxolib.Network, outputSize: number, isWitness: boolean): number {
+  network = utxolib.getMainnet(network);
+  switch (network) {
+    case utxolib.networks.bitcoin:
+    case utxolib.networks.bitcoincash:
+    case utxolib.networks.bitcoingold:
+    case utxolib.networks.litecoin:
+      /*
+        btc:  https://github.com/bitcoin/bitcoin/blob/v28.0/src/policy/policy.cpp#L26-L68
+        bch:  https://github.com/bitcoin-cash-node/bitcoin-cash-node/blob/v27.1.0/src/policy/policy.cpp#L18-L36 (btc-ish)
+        btg:  https://github.com/BTCGPU/BTCGPU/blob/v0.17.3/src/policy/policy.cpp#L18-L50 (btc-ish)
+        ltc:  https://github.com/litecoin-project/litecoin/blob/v0.21.4/src/policy/policy.cpp#L15-L47 (btc-ish)
+
+        The fixed component here is 69.75 for isWitness=true and 150 for isWitness=false.
+       */
+      return outputSize + 32 + 4 + 1 + 107 / (isWitness ? 4 : 1) + 4;
+    case utxolib.networks.dash:
+      // dash: https://github.com/dashpay/dash/blob/v21.1.1/src/policy/policy.cpp#L14-L30 (btc-ish)
+      // how did they end up with 148? I don't know
+      return outputSize + 148;
+    case utxolib.networks.dogecoin:
+    case utxolib.networks.zcash:
+      // doge: https://github.com/dogecoin/dogecoin/blob/v1.14.8/src/policy/policy.h#L65-L81 (hardcoded)
+      // zec:  https://github.com/zcash/zcash/blob/v6.0.0/src/policy/policy.h#L43-L89 (some weird other thing, doge-ish)
+      throw new Error('dust limit is size-independent');
+    case utxolib.networks.bitcoinsv:
+      throw new Error('deprecated coin');
+    default:
+      throw new Error('unsupported network');
+  }
+}
+
+export function getDustThresholdSat(network: utxolib.Network, outputSize: number, isWitness: boolean): number {
+  const dustLimit = getDustRelayLimit(network);
+  if ('satAmount' in dustLimit) {
+    return dustLimit.satAmount;
+  }
+  if ('feeRateSatKB' in dustLimit) {
+    const spendSize = getSpendSize(network, outputSize, isWitness);
+    return Math.ceil((dustLimit.feeRateSatKB * spendSize) / 1000);
+  }
+  throw new Error('unexpected dustLimit');
+}
+
+export function getDustThresholdSatForOutputScript(network: utxolib.Network, script: Buffer): number {
+  return getDustThresholdSat(network, script.length, isWitnessOutputScript(script));
+}
diff --git a/modules/utxo-core/src/index.ts b/modules/utxo-core/src/index.ts
@@ -1,2 +1,3 @@
+export * as bip65 from './bip65';
 export * as descriptor from './descriptor';
 export * as testutil from './testutil';
diff --git a/modules/utxo-core/src/testutil/descriptor/psbt.utils.ts b/modules/utxo-core/src/testutil/descriptor/psbt.utils.ts
@@ -1,6 +1,6 @@
 import * as utxolib from '@bitgo/utxo-lib';
 
-import { matchPath, PathElement, toPlainObject } from '../../../src/testutil/toPlainObject.utils';
+import { matchPath, PathElement, toPlainObject } from '../../../src/testutil';
 
 export function toPlainObjectFromPsbt(v: utxolib.Psbt): unknown {
   return toPlainObject(
diff --git a/modules/utxo-core/test/bip65/locktime.ts b/modules/utxo-core/test/bip65/locktime.ts
@@ -0,0 +1,18 @@
+import assert from 'assert';
+
+import { encodeLocktime } from '../../src/bip65/locktime';
+
+describe('locktime', function () {
+  it('encodes relative and absolute locktimes', function () {
+    assert.strictEqual(encodeLocktime({ blocks: 1 }), 1);
+    assert.strictEqual(encodeLocktime({ blocks: 500_000_000 - 1 }), 500_000_000 - 1);
+    assert.strictEqual(encodeLocktime(new Date('1985-11-05T00:53:20Z')), 500_000_000);
+    assert.strictEqual(encodeLocktime(new Date('2033-05-18T03:33:20.000Z')), 2_000_000_000);
+    assert.throws(() => {
+      encodeLocktime({ blocks: 500_000_000 });
+    });
+    assert.throws(() => {
+      encodeLocktime(new Date('1985-11-05T00:53:19Z'));
+    });
+  });
+});
diff --git a/modules/utxo-core/test/descriptor/Output.ts b/modules/utxo-core/test/descriptor/Output.ts
@@ -10,7 +10,7 @@ import {
   toFixedOutputs,
   isInternalOutput,
   isExternalOutput,
-} from '../../src/descriptor/Output';
+} from '../../src/descriptor';
 
 describe('Output', function () {
   const oBigInt = { value: 1n };
diff --git a/modules/utxo-core/test/descriptor/psbt/VirtualSize.ts b/modules/utxo-core/test/descriptor/psbt/VirtualSize.ts
@@ -4,8 +4,17 @@ import {
   getChangeOutputVSizesForDescriptor,
   getInputVSizesForDescriptors,
   getVirtualSize,
+  getVirtualSizeEstimateForPsbt,
 } from '../../../src/descriptor/VirtualSize';
-import { DescriptorTemplate, getDescriptor, getDescriptorMap } from '../../../src/testutil/descriptor/descriptors';
+import {
+  DescriptorTemplate,
+  getDefaultXPubs,
+  getDescriptor,
+  getDescriptorMap,
+  mockPsbtDefault,
+} from '../../../src/testutil/descriptor';
+import { getKeyTriple } from '../../../src/testutil';
+import { finalizePsbt } from '../../../src/descriptor';
 
 describe('VirtualSize', function () {
   describe('getInputVSizesForDescriptorWallet', function () {
@@ -45,11 +54,11 @@ describe('VirtualSize', function () {
           getVirtualSize(
             {
               inputs: [{ descriptorName: 'internal' }],
-              outputs: [{ script: Buffer.alloc(32) }],
+              outputs: [{ script: Buffer.alloc(34) }],
             },
             getDescriptorMap(t)
           ),
-          outputSize
+          inputSize + outputSize + 11
         );
 
         const descriptor = getDescriptor(t);
@@ -65,8 +74,28 @@ describe('VirtualSize', function () {
         );
       });
     });
+
+    describe(`getVirtualSizeForPsbt ${t}`, function () {
+      const keys = getKeyTriple('a');
+      const descriptorSelf = getDescriptor(
+        t,
+        keys.map((k) => k.neutered().toBase58())
+      );
+      const descriptorOther = getDescriptor(t, getDefaultXPubs('b'));
+      it('returns expected virtual size', function () {
+        const psbt = mockPsbtDefault({ descriptorSelf, descriptorOther });
+        const descriptorMap = new Map([['internal', descriptorSelf]]);
+        const expectedVirtualSize = inputSize * 2 + outputSize * 2 + 11;
+        assert.deepStrictEqual(getVirtualSizeEstimateForPsbt(psbt, descriptorMap), expectedVirtualSize);
+        psbt.signAllInputsHD(keys[0]);
+        psbt.signAllInputsHD(keys[1]);
+        finalizePsbt(psbt);
+        // TODO(BTC-1797): figure out why we overestimate by 1
+        assert.strictEqual(psbt.extractTransaction().virtualSize(), expectedVirtualSize - 1);
+      });
+    });
   }
 
-  describeWithTemplate('Wsh2Of3', 105, 157);
-  describeWithTemplate('Tr2Of3-NoKeyPath', 109, 161);
+  describeWithTemplate('Wsh2Of3', 105, 43);
+  describeWithTemplate('Tr2Of3-NoKeyPath', 109, 43);
 });
diff --git a/modules/utxo-core/test/descriptor/psbt/assertSatisfiable.ts b/modules/utxo-core/test/descriptor/psbt/assertSatisfiable.ts
@@ -2,8 +2,8 @@ import * as assert from 'assert';
 
 import { Descriptor } from '@bitgo/wasm-miniscript';
 
-import { getDefaultXPubs } from '../../../src/testutil/descriptor/descriptors';
-import { getRequiredLocktime } from '../../../src/descriptor/psbt/assertSatisfiable';
+import { getDefaultXPubs } from '../../../src/testutil/descriptor';
+import { getRequiredLocktime } from '../../../src/descriptor';
 
 function d(s: string): Descriptor {
   return Descriptor.fromString(s, 'derivable');
diff --git a/modules/utxo-core/test/descriptor/psbt/findDescriptors.ts b/modules/utxo-core/test/descriptor/psbt/findDescriptors.ts
diff --git a/modules/utxo-core/test/descriptor/psbt/psbt.ts b/modules/utxo-core/test/descriptor/psbt/psbt.ts
diff --git a/modules/utxo-core/test/dustThreshold.ts b/modules/utxo-core/test/dustThreshold.ts
diff --git a/modules/utxo-staking/test/unit/babylon/transactions.ts b/modules/utxo-staking/test/unit/babylon/transactions.ts

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
	`1`	`+export * as bip65 from './bip65';`
`1`	`2`	`export * as descriptor from './descriptor';`
`2`	`3`	`export * as testutil from './testutil';`