feat(utxo-staking): add unbonding transaction construction for staking

This PR adds support for converting staking undelegation responses to PSBTs.
The implementation handles covenant signatures properly and verifies them
against the unbonding spend path of a staking descriptor.

Issue: BTC-2143

Co-authored-by: llm-git <[email protected]>

Author: OttoAllmendinger

modules/utxo-staking/package.json

@@ -47,6 +47,7 @@
     "@bitgo/utxo-core": "^1.12.0",
     "@bitgo/utxo-lib": "^11.6.2",
     "@bitgo/wasm-miniscript": "2.0.0-beta.7",
+    "bip174": "npm:@bitgo-forks/[email protected]",
     "bip322-js": "^2.0.0",
     "bitcoinjs-lib": "^6.1.7",
     "fp-ts": "^2.16.2",

modules/utxo-staking/src/babylon/index.ts

@@ -9,3 +9,4 @@ export * from './delegationMessage';
 export * from './descriptor';
 export * from './stakingParams';
 export * from './stakingManager';
+export * from './undelegation';

modules/utxo-staking/src/babylon/parseDescriptor.ts

@@ -5,8 +5,8 @@ import { getUnspendableKey } from './descriptor';
 
 type ParsedStakingDescriptor = {
   slashingMiniscriptNode: ast.MiniscriptNode;
-  unbondingTimelockMiniscriptNode: ast.MiniscriptNode;
   unbondingMiniscriptNode: ast.MiniscriptNode;
+  timelockMiniscriptNode: ast.MiniscriptNode;
 };
 
 /**
@@ -16,10 +16,7 @@ export function parseStakingDescriptor(descriptor: Descriptor | ast.DescriptorNo
   const pattern: Pattern = {
     tr: [
       getUnspendableKey(),
-      [
-        { $var: 'slashingMiniscriptNode' },
-        [{ $var: 'unbondingMiniscriptNode' }, { $var: 'unbondingTimelockMiniscriptNode' }],
-      ],
+      [{ $var: 'slashingMiniscriptNode' }, [{ $var: 'unbondingMiniscriptNode' }, { $var: 'timelockMiniscriptNode' }]],
     ],
   };
 
@@ -33,7 +30,7 @@ export function parseStakingDescriptor(descriptor: Descriptor | ast.DescriptorNo
 
   const slashingNode = result.slashingMiniscriptNode as ast.MiniscriptNode;
   const unbondingNode = result.unbondingMiniscriptNode as ast.MiniscriptNode;
-  const unbondingTimelockNode = result.unbondingTimelockMiniscriptNode as ast.MiniscriptNode;
+  const timelockNode = result.timelockMiniscriptNode as ast.MiniscriptNode;
 
   // Verify slashing node shape: and_v([and_v([pk, pk/multi_a]), multi_a])
   const slashingPattern: Pattern = {
@@ -61,31 +58,31 @@ export function parseStakingDescriptor(descriptor: Descriptor | ast.DescriptorNo
   }
 
   // Verify unbonding timelock node shape: and_v([pk, older])
-  const unbondingTimelockPattern: Pattern = {
+  const timelockPattern: Pattern = {
     and_v: [{ 'v:pk': { $var: 'stakerKey3' } }, { older: { $var: 'unbondingTimeLockValue' } }],
   };
 
-  const unbondingTimelockMatch = matcher.match(unbondingTimelockNode, unbondingTimelockPattern);
-  if (!unbondingTimelockMatch) {
+  const timelockMatch = matcher.match(timelockNode, timelockPattern);
+  if (!timelockMatch) {
     throw new Error('Unbonding timelock node does not match expected pattern');
   }
 
   // Verify all staker keys are the same
   if (
     slashingMatch.stakerKey1 !== unbondingMatch.stakerKey2 ||
-    unbondingMatch.stakerKey2 !== unbondingTimelockMatch.stakerKey3
+    unbondingMatch.stakerKey2 !== timelockMatch.stakerKey3
   ) {
     throw new Error('Staker keys must be identical across all nodes');
   }
 
   // Verify timelock value is a number
-  if (typeof unbondingTimelockMatch.unbondingTimeLockValue !== 'number') {
+  if (typeof timelockMatch.unbondingTimeLockValue !== 'number') {
     throw new Error('Unbonding timelock value must be a number');
   }
 
   return {
     slashingMiniscriptNode: slashingNode,
     unbondingMiniscriptNode: unbondingNode,
-    unbondingTimelockMiniscriptNode: unbondingTimelockNode,
+    timelockMiniscriptNode: timelockNode,
   };
 }

modules/utxo-staking/src/babylon/undelegation/UndelegationResponse.ts

@@ -0,0 +1,26 @@
+import * as t from 'io-ts';
+import { PartialSig } from 'bip174/src/lib/interfaces';
+
+/** As returned by https://babylon.nodes.guru/api#/Query/BTCDelegation */
+export const Signature = t.type({ pk: t.string, sig: t.string }, 'Signature');
+
+/** As returned by https://babylon.nodes.guru/api#/Query/BTCDelegation */
+export const UndelegationResponse = t.type(
+  {
+    /** Network-formatted transaction hex */
+    unbonding_tx_hex: t.string,
+    /** List of signatures for the unbonding covenant */
+    covenant_unbonding_sig_list: t.array(Signature),
+  },
+  'UndelegationResponse'
+);
+
+export type UndelegationResponse = t.TypeOf<typeof UndelegationResponse>;
+
+/** Converts a gRPC signature to a PartialSig as used by bitcoinjs-lib and utxo-lib */
+export function toPartialSig(grpcSig: { pk: string; sig: string }): PartialSig {
+  return {
+    pubkey: Buffer.from(grpcSig.pk, 'hex'),
+    signature: Buffer.from(grpcSig.sig, 'base64'),
+  };
+}

modules/utxo-staking/src/babylon/undelegation/index.ts

@@ -0,0 +1,2 @@
+export * from './unbonding';
+export * from './UndelegationResponse';

modules/utxo-staking/src/babylon/undelegation/unbonding.ts

@@ -0,0 +1,97 @@
+import assert from 'assert';
+
+import * as utxolib from '@bitgo/utxo-lib';
+import { PartialSig, WitnessUtxo } from 'bip174/src/lib/interfaces';
+import { Descriptor, Miniscript, ast } from '@bitgo/wasm-miniscript';
+import { findTapLeafScript, toUtxoPsbt, toWrappedPsbt } from '@bitgo/utxo-core/descriptor';
+
+import { parseStakingDescriptor } from '../parseDescriptor';
+
+/**
+ * Adds covenant signatures to a PSBT input.
+ */
+function addCovenantSignatures(psbt: utxolib.bitgo.UtxoPsbt, inputIndex: number, signatures: PartialSig[]): void {
+  const input = psbt.data.inputs[inputIndex];
+  assert(input.tapLeafScript, 'Input must have tapLeafScript');
+  assert(input.tapLeafScript.length === 1, 'Input must have exactly one tapLeafScript');
+  const [{ controlBlock, script }] = input.tapLeafScript;
+  const leafHash = utxolib.taproot.getTapleafHash(utxolib.ecc, controlBlock, script);
+  psbt.updateInput(inputIndex, { tapScriptSig: signatures.map((s) => ({ ...s, leafHash })) });
+}
+
+/**
+ * Asserts that the provided signatures are valid for the given PSBT input.
+ */
+export function assertValidSignatures(
+  psbt: utxolib.bitgo.UtxoPsbt,
+  inputIndex: number,
+  signatures: PartialSig[]
+): void {
+  signatures.forEach((s) => {
+    assert(
+      psbt.validateTaprootSignaturesOfInput(inputIndex, s.pubkey),
+      `Signature validation failed for ${s.pubkey.toString('hex')}`
+    );
+  });
+}
+
+function getUnbondingScript(stakingDescriptor: Descriptor): Miniscript {
+  const parsedDescriptor = parseStakingDescriptor(stakingDescriptor);
+  assert(parsedDescriptor, 'Invalid staking descriptor');
+  return Miniscript.fromString(ast.formatNode(parsedDescriptor.unbondingMiniscriptNode), 'tap');
+}
+
+/**
+ * @return unsigned PSBT for an unbonding transaction
+ */
+export function toUnbondingPsbt(
+  tx: utxolib.bitgo.UtxoTransaction<bigint>,
+  witnessUtxo: WitnessUtxo,
+  stakingDescriptor: Descriptor,
+  network: utxolib.Network
+): utxolib.bitgo.UtxoPsbt {
+  const unbondingScript = getUnbondingScript(stakingDescriptor);
+  const psbt = new utxolib.Psbt({ network });
+  psbt.setVersion(tx.version);
+  psbt.setLocktime(tx.locktime);
+  psbt.addOutputs(
+    tx.outs.map((output) => ({
+      script: output.script,
+      value: BigInt(output.value),
+    }))
+  );
+  assert(tx.ins.length === 1);
+  const input = tx.ins[0];
+  psbt.addInput({
+    hash: input.hash,
+    index: input.index,
+    sequence: input.sequence,
+    witnessUtxo,
+  });
+  const wrappedPsbt = toWrappedPsbt(psbt);
+  wrappedPsbt.updateInputWithDescriptor(0, stakingDescriptor);
+  const unwrapped = toUtxoPsbt(wrappedPsbt, network);
+  assert(unwrapped.data.inputs.length === 1, 'Unbonding transaction must have exactly one input');
+  const unwrappedInputData = unwrapped.data.inputs[0];
+  assert(unwrappedInputData.tapLeafScript);
+  const unwrappedUnbond = findTapLeafScript(unwrappedInputData.tapLeafScript, unbondingScript);
+  unwrappedInputData.tapLeafScript = [unwrappedUnbond];
+  return unwrapped;
+}
+
+/**
+ * @return PSBT for an unbonding transaction with signatures
+ */
+export function toUnbondingPsbtWithSignatures(
+  tx: utxolib.bitgo.UtxoTransaction<bigint>,
+  witnessUtxo: WitnessUtxo,
+  stakingDescriptor: Descriptor,
+  signatures: PartialSig[],
+  network: utxolib.Network
+): utxolib.bitgo.UtxoPsbt {
+  const psbt = toUnbondingPsbt(tx, witnessUtxo, stakingDescriptor, network);
+  assert(psbt.data.inputs.length === 1, 'Unbonding transaction must have exactly one input');
+  addCovenantSignatures(psbt, 0, signatures);
+  assertValidSignatures(psbt, 0, signatures);
+  return psbt;
+}