feat(utxo-staking): extract key details from parsed staking descriptors

Extract key information from descriptor nodes including staker key,
finality provider keys, covenant keys, and timelock values. This allows
for better programmatic access to descriptor components.

Issue: BTC-2319

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

Author: OttoAllmendinger

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

@@ -3,12 +3,31 @@ import { PatternMatcher, Pattern } from '@bitgo/utxo-core/descriptor';
 
 import { getUnspendableKey } from './descriptor';
 
-type ParsedStakingDescriptor = {
+export type ParsedStakingDescriptor = {
+  stakerKey: Buffer;
+  finalityProviderKeys: Buffer[];
+  covenantKeys: Buffer[];
+  covenantThreshold: number;
+  stakingTimeLock: number;
   slashingMiniscriptNode: ast.MiniscriptNode;
   unbondingMiniscriptNode: ast.MiniscriptNode;
   timelockMiniscriptNode: ast.MiniscriptNode;
 };
 
+function parseMulti(multi: unknown): [number, string[]] {
+  if (!Array.isArray(multi) || multi.length < 1) {
+    throw new Error('Invalid multi structure: not an array or empty');
+  }
+  const [threshold, ...keys] = multi;
+  if (typeof threshold !== 'number') {
+    throw new Error('Invalid multi structure: threshold is not a number');
+  }
+  if (!keys.every((k) => typeof k === 'string')) {
+    throw new Error('Invalid multi structure: not all keys are strings');
+  }
+  return [threshold, keys];
+}
+
 /**
  * @return parsed staking descriptor components or null if the descriptor does not match the expected staking pattern.
  */
@@ -59,7 +78,7 @@ export function parseStakingDescriptor(descriptor: Descriptor | ast.DescriptorNo
 
   // Verify unbonding timelock node shape: and_v([pk, older])
   const timelockPattern: Pattern = {
-    and_v: [{ 'v:pk': { $var: 'stakerKey3' } }, { older: { $var: 'unbondingTimeLockValue' } }],
+    and_v: [{ 'v:pk': { $var: 'stakerKey3' } }, { older: { $var: 'stakingTimeLock' } }],
   };
 
   const timelockMatch = matcher.match(timelockNode, timelockPattern);
@@ -76,11 +95,36 @@ export function parseStakingDescriptor(descriptor: Descriptor | ast.DescriptorNo
   }
 
   // Verify timelock value is a number
-  if (typeof timelockMatch.unbondingTimeLockValue !== 'number') {
+  if (typeof timelockMatch.stakingTimeLock !== 'number') {
     throw new Error('Unbonding timelock value must be a number');
   }
 
+  const stakerKey = Buffer.from(slashingMatch.stakerKey1 as string, 'hex');
+  const stakingTimeLock = timelockMatch.stakingTimeLock as number;
+
+  const [covenantThreshold, covenantKeyStrings] = parseMulti(slashingMatch.covenantMulti);
+  const covenantKeys = covenantKeyStrings.map((k) => Buffer.from(k, 'hex'));
+
+  let finalityProviderKeys: Buffer[];
+  const fpKeyOrMulti = slashingMatch.finalityProviderKeyOrMulti as ast.MiniscriptNode;
+  if ('v:pk' in fpKeyOrMulti) {
+    finalityProviderKeys = [Buffer.from(fpKeyOrMulti['v:pk'], 'hex')];
+  } else if ('v:multi_a' in fpKeyOrMulti) {
+    const [threshold, keyStrings] = parseMulti(fpKeyOrMulti['v:multi_a']);
+    if (threshold !== 1) {
+      throw new Error('Finality provider multi threshold must be 1');
+    }
+    finalityProviderKeys = keyStrings.map((k) => Buffer.from(k, 'hex'));
+  } else {
+    throw new Error('Invalid finality provider key structure');
+  }
+
   return {
+    stakerKey,
+    finalityProviderKeys,
+    covenantKeys,
+    covenantThreshold,
+    stakingTimeLock,
     slashingMiniscriptNode: slashingNode,
     unbondingMiniscriptNode: unbondingNode,
     timelockMiniscriptNode: timelockNode,