feat(utxo-staking): rename and document descriptor methods

Renames getTimelockMiniscriptNode to getStakingTimelockMiniscriptNode for clarity.
Also renames getSlashingDescriptor to getUnbondingTimelockDescriptor to better
reflect its purpose. Added JSDoc comments to descriptor methods to improve
understanding of the different spend paths.

Issue: BTC-2143

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

Author: OttoAllmendinger

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

@@ -55,14 +55,22 @@ export class BabylonDescriptorBuilder {
     );
   }
 
-  getTimelockMiniscriptNode(): ast.MiniscriptNode {
+  /** Spend path with the staker key and the staking timelock */
+  getStakingTimelockMiniscriptNode(): ast.MiniscriptNode {
     return { and_v: [pk(this.stakerKey), { older: this.stakingTimeLock }] };
   }
 
+  /** Spend path with the staker key and the unbonding timelock */
+  getUnbondingTimelockMiniscriptNode(): ast.MiniscriptNode {
+    return { and_v: [pk(this.stakerKey), { older: this.unbondingTimeLock }] };
+  }
+
+  /** Spend path with the staker key and the covenant keys */
   getUnbondingMiniscriptNode(): ast.MiniscriptNode {
     return { and_v: [pk(this.stakerKey), { multi_a: multiArgs(this.covenantThreshold, this.covenantKeys) }] };
   }
 
+  /** Spend path with the finality provider keys and the covenant keys */
   getSlashingMiniscriptNode(): ast.MiniscriptNode {
     return {
       and_v: [
@@ -79,21 +87,31 @@ export class BabylonDescriptorBuilder {
     };
   }
 
-  getUnbondingTimelockMiniscriptNode(): ast.MiniscriptNode {
-    return { and_v: [pk(this.stakerKey), { older: this.unbondingTimeLock }] };
-  }
-
+  /**
+   * Creates a descriptor for a staking output.
+   *
+   * Three spend paths:
+   * - the slashing script,
+   * - the unbonding script,
+   * - the timelocked unstaking script.
+   */
   getStakingDescriptor(): Descriptor {
     return taprootScriptOnlyFromAst([
       this.getSlashingMiniscriptNode(),
-      [this.getUnbondingMiniscriptNode(), this.getTimelockMiniscriptNode()],
+      [this.getUnbondingMiniscriptNode(), this.getStakingTimelockMiniscriptNode()],
     ]);
   }
 
-  getSlashingDescriptor(): Descriptor {
+  /**
+   * Creates a descriptor for the timelocked unbonding script.
+   */
+  getUnbondingTimelockDescriptor(): Descriptor {
     return taprootScriptOnlyFromAst(this.getUnbondingTimelockMiniscriptNode());
   }
 
+  /**
+   * Creates a descriptor with two script paths: the slashing script and the timelocked unbonding script.
+   */
   getUnbondingDescriptor(): Descriptor {
     return taprootScriptOnlyFromAst([this.getSlashingMiniscriptNode(), this.getUnbondingTimelockMiniscriptNode()]);
   }

modules/utxo-staking/test/unit/babylon/transactions.ts

@@ -132,7 +132,7 @@ function spendStakingOutput(
   const selectTapLeafScript = Miniscript.fromString(
     ast.formatNode(
       type === 'unstaking'
-        ? descriptorBuilder.getTimelockMiniscriptNode()
+        ? descriptorBuilder.getStakingTimelockMiniscriptNode()
         : descriptorBuilder.getUnbondingMiniscriptNode()
     ),
     'tap'
@@ -223,7 +223,7 @@ function assertEqualScripts(descriptorBuilder: BabylonDescriptorBuilder, builder
   for (const [key, script] of Object.entries(builder) as [keyof vendor.StakingScripts, Buffer][]) {
     switch (key) {
       case 'timelockScript':
-        assertEqualsMiniscript(script, descriptorBuilder.getTimelockMiniscriptNode());
+        assertEqualsMiniscript(script, descriptorBuilder.getStakingTimelockMiniscriptNode());
         break;
       case 'unbondingScript':
         assertEqualsMiniscript(script, descriptorBuilder.getUnbondingMiniscriptNode());
@@ -292,8 +292,9 @@ function describeWithKeys(
         descriptorBuilder.getStakingDescriptor()
       );
       assertEqualOutputScript(
+        /* I don't know why this is called deriveSlashingOutput */
         vendor.deriveSlashingOutput(vendorBuilder.buildScripts(), bitcoinjslib.networks.bitcoin),
-        descriptorBuilder.getSlashingDescriptor()
+        descriptorBuilder.getUnbondingTimelockDescriptor()
       );
       assertEqualOutputScript(
         vendor.deriveUnbondingOutputInfo(vendorBuilder.buildScripts(), bitcoinjslib.networks.bitcoin),
@@ -308,7 +309,7 @@ function describeWithKeys(
       assert(parsed);
       assert.deepStrictEqual(parsed.slashingMiniscriptNode, descriptorBuilder.getSlashingMiniscriptNode());
       assert.deepStrictEqual(parsed.unbondingMiniscriptNode, descriptorBuilder.getUnbondingMiniscriptNode());
-      assert.deepStrictEqual(parsed.timelockMiniscriptNode, descriptorBuilder.getTimelockMiniscriptNode());
+      assert.deepStrictEqual(parsed.timelockMiniscriptNode, descriptorBuilder.getStakingTimelockMiniscriptNode());
     });
 
     describe('Transaction Sets', async function () {