Merge pull request #6455 from BitGo/BTC-2143.delegation-message-sample

feat(utxo-staking): add basic Babylon unbonding support

Author: OttoAllmendinger

modules/utxo-core/src/descriptor/index.ts

@@ -5,6 +5,7 @@ export * from './derive';
 export * from './Output';
 export * from './VirtualSize';
 export * from './fromFixedScriptWallet';
+export * from './parse/PatternMatcher';
 
 /** @deprecated - import from @bitgo/utxo-core directly instead */
 export * from '../Output';

modules/utxo-core/src/descriptor/parse/PatternMatcher.ts

@@ -0,0 +1,73 @@
+// Pattern matching types
+export type PatternVar = { $var: string };
+export type Pattern = PatternVar | string | number | { [key: string]: Pattern | Pattern[] } | Pattern[];
+
+export type ExtractedVars = Record<string, unknown>;
+
+export class PatternMatcher {
+  match(node: unknown, pattern: Pattern): ExtractedVars | null {
+    const vars: ExtractedVars = {};
+    return this.matchNode(node, pattern, vars) ? vars : null;
+  }
+
+  private matchNode(node: unknown, pattern: Pattern, vars: ExtractedVars): boolean {
+    // Variable placeholder
+    if (this.isPatternVar(pattern)) {
+      const varName = pattern.$var;
+      if (varName in vars) {
+        return this.deepEqual(vars[varName], node);
+      }
+      vars[varName] = node;
+      return true;
+    }
+
+    // Primitive values
+    if (typeof node !== typeof pattern) return false;
+    if (typeof node === 'string' || typeof node === 'number') {
+      return node === pattern;
+    }
+
+    // Arrays
+    if (Array.isArray(node) && Array.isArray(pattern)) {
+      return node.length === pattern.length && node.every((item, i) => this.matchNode(item, pattern[i], vars));
+    }
+
+    // Objects
+    if (typeof node === 'object' && typeof pattern === 'object' && node !== null && pattern !== null) {
+      const nodeKeys = Object.keys(node);
+      const patternKeys = Object.keys(pattern);
+
+      return (
+        nodeKeys.length === patternKeys.length &&
+        nodeKeys.every(
+          (key) =>
+            patternKeys.includes(key) &&
+            this.matchNode((node as Record<string, unknown>)[key], (pattern as Record<string, Pattern>)[key], vars)
+        )
+      );
+    }
+
+    return false;
+  }
+
+  private isPatternVar(value: unknown): value is PatternVar {
+    return value !== null && typeof value === 'object' && '$var' in value;
+  }
+
+  private deepEqual(a: unknown, b: unknown): boolean {
+    if (a === b) return true;
+    if (typeof a !== typeof b) return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+      return a.length === b.length && a.every((item, i) => this.deepEqual(item, b[i]));
+    }
+    if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+      const keysA = Object.keys(a);
+      const keysB = Object.keys(b);
+      return (
+        keysA.length === keysB.length &&
+        keysA.every((key) => this.deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]))
+      );
+    }
+    return false;
+  }
+}

modules/utxo-core/test/descriptor/parse/PatternMatcher.ts

@@ -0,0 +1,148 @@
+import assert from 'assert';
+
+import { Descriptor, ast } from '@bitgo/wasm-miniscript';
+
+import { getKey } from '../../../src/testutil';
+import { toXOnlyPublicKey } from '../../../src';
+import { PatternMatcher, Pattern } from '../../../src/descriptor/parse/PatternMatcher';
+
+function key32(seed: string): Buffer {
+  // return x-only public key from seed
+  return toXOnlyPublicKey(getKey(seed).publicKey);
+}
+
+function getUnspendableKey(): string {
+  return '50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0';
+}
+
+function pk(b: Buffer): ast.MiniscriptNode {
+  return { 'v:pk': b.toString('hex') };
+}
+
+function sortedKeys(keys: Buffer[]): Buffer[] {
+  return [...keys].sort((a, b) => a.compare(b));
+}
+
+function multiArgs(threshold: number, keys: Buffer[]): [number, ...string[]] {
+  return [threshold, ...sortedKeys(keys).map((k) => k.toString('hex'))];
+}
+
+function taprootScriptOnlyFromAst(n: ast.TapTreeNode): Descriptor {
+  return Descriptor.fromString(ast.formatNode({ tr: [getUnspendableKey(), n] }), 'definite');
+}
+
+class StakingDescriptorBuilder {
+  constructor(
+    public userKey: Buffer,
+    public providerKeys: Buffer[],
+    public guardianKeys: Buffer[],
+    public guardianThreshold: number,
+    public stakingTimeLock: number
+  ) {}
+
+  getTimelockMiniscriptNode(): ast.MiniscriptNode {
+    return { and_v: [pk(this.userKey), { older: this.stakingTimeLock }] };
+  }
+
+  getWithdrawalMiniscriptNode(): ast.MiniscriptNode {
+    return { and_v: [pk(this.userKey), { multi_a: multiArgs(this.guardianThreshold, this.guardianKeys) }] };
+  }
+
+  getPenaltyMiniscriptNode(): ast.MiniscriptNode {
+    return {
+      and_v: [
+        {
+          and_v: [
+            pk(this.userKey),
+            this.providerKeys.length === 1
+              ? { 'v:pk': this.providerKeys[0].toString('hex') }
+              : { 'v:multi_a': multiArgs(1, this.providerKeys) },
+          ],
+        },
+        { multi_a: multiArgs(this.guardianThreshold, this.guardianKeys) },
+      ],
+    };
+  }
+
+  getStakingDescriptor(): Descriptor {
+    return taprootScriptOnlyFromAst([
+      this.getPenaltyMiniscriptNode(),
+      [this.getWithdrawalMiniscriptNode(), this.getTimelockMiniscriptNode()],
+    ]);
+  }
+}
+
+// Inverse function to parse the descriptor
+function parseStakingDescriptor(descriptor: Descriptor): {
+  penaltyNode: ast.MiniscriptNode;
+  withdrawalNode: ast.MiniscriptNode;
+  timelockNode: ast.MiniscriptNode;
+} | null {
+  const pattern: Pattern = {
+    tr: [getUnspendableKey(), [{ $var: 'penaltyNode' }, [{ $var: 'withdrawalNode' }, { $var: 'timelockNode' }]]],
+  };
+
+  const matcher = new PatternMatcher();
+  const descriptorNode = ast.fromDescriptor(descriptor);
+  const result = matcher.match(descriptorNode, pattern);
+
+  if (!result) {
+    return null;
+  }
+
+  return {
+    penaltyNode: result.penaltyNode as ast.MiniscriptNode,
+    withdrawalNode: result.withdrawalNode as ast.MiniscriptNode,
+    timelockNode: result.timelockNode as ast.MiniscriptNode,
+  };
+}
+
+describe('PatternMatcher', function () {
+  it('should match basic object', function () {
+    const pattern = { a: { $var: 'x' }, b: 'hello' };
+    const node = { a: 123, b: 'hello' };
+    const vars = new PatternMatcher().match(node, pattern);
+    assert.deepStrictEqual(vars, { x: 123 });
+  });
+
+  it('should fail on non-matching object', function () {
+    const pattern = { a: { $var: 'x' }, b: 'world' };
+    const node = { a: 123, b: 'hello' };
+    const vars = new PatternMatcher().match(node, pattern);
+    assert.strictEqual(vars, null);
+  });
+
+  it('should match with repeated var', function () {
+    const pattern = { a: { $var: 'x' }, b: { $var: 'x' } };
+    const node = { a: 123, b: 123 };
+    const vars = new PatternMatcher().match(node, pattern);
+    assert.deepStrictEqual(vars, { x: 123 });
+  });
+
+  it('should fail with non-matching repeated var', function () {
+    const pattern = { a: { $var: 'x' }, b: { $var: 'x' } };
+    const node = { a: 123, b: 456 };
+    const vars = new PatternMatcher().match(node, pattern);
+    assert.strictEqual(vars, null);
+  });
+
+  it('should parse staking descriptor', function () {
+    const builder = new StakingDescriptorBuilder(
+      key32('user'),
+      [key32('provider1')],
+      [key32('guardian1'), key32('guardian2')],
+      2,
+      100
+    );
+
+    const descriptor = builder.getStakingDescriptor();
+    const parsed = parseStakingDescriptor(descriptor);
+
+    assert.notStrictEqual(parsed, null);
+    if (parsed) {
+      assert.deepStrictEqual(parsed.penaltyNode, builder.getPenaltyMiniscriptNode());
+      assert.deepStrictEqual(parsed.withdrawalNode, builder.getWithdrawalMiniscriptNode());
+      assert.deepStrictEqual(parsed.timelockNode, builder.getTimelockMiniscriptNode());
+    }
+  });
+});

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/scripts/babylon-params.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert';
+import * as fs from 'fs/promises';
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+function getBaseUrl(network: 'mainnet' | 'testnet') {
+  if (network === 'mainnet') {
+    return 'https://babylon.nodes.guru/api';
+  }
+  return 'https://babylon-testnet-api.nodes.guru';
+}
+
+function unwrapJson(r: Response): Promise<unknown> {
+  if (r.ok) {
+    return r.json();
+  }
+  return r.text().then((text) => {
+    throw new Error(`Fetch failed: ${r.status} ${r.statusText} - ${text}`);
+  });
+}
+
+type BabylonNetwork = 'mainnet' | 'testnet';
+
+async function getAllParams(network: BabylonNetwork): Promise<unknown[]> {
+  const url = `${getBaseUrl(network)}/babylon/btcstaking/v1/params_versions`;
+  const result = await unwrapJson(await fetch(url));
+  assert(result && typeof result === 'object', `Invalid response from ${url}`);
+  assert('params' in result, `Response from ${url} does not contain 'params'`);
+  assert(Array.isArray(result.params), `Response from ${url} 'params' is not an array`);
+  return result.params;
+}
+
+async function syncParams(network: BabylonNetwork | undefined): Promise<void> {
+  if (network === undefined) {
+    await syncParams('testnet');
+    await syncParams('mainnet');
+    return;
+  }
+
+  const allParams = await getAllParams(network);
+  const filename = __dirname + `/../src/babylon/params.${network}.json`;
+  await fs.writeFile(filename, JSON.stringify(allParams, null, 2) + '\n');
+  console.log(`Wrote ${allParams.length} params to ${filename}`);
+}
+
+async function syncDelegationResponse(network: BabylonNetwork | undefined, txid: string | undefined): Promise<void> {
+  if (network === undefined && txid === undefined) {
+    console.log('Syncing delegation with default params');
+    return syncDelegationResponse('testnet', '5d277e1b29e5589074aea95ac8c8230fd911c2ec3c58774aafdef915619b772c');
+  }
+
+  if (network === undefined || txid === undefined) {
+    throw new Error('Network must be specified when syncing delegation response');
+  }
+
+  const url = `${getBaseUrl(network)}/babylon/btcstaking/v1/btc_delegation/${txid}`;
+  const result = await unwrapJson(await fetch(url));
+  assert(result && typeof result === 'object', `Invalid response from ${url}`);
+
+  const filename = __dirname + `/../test/fixtures/babylon/rpc/btc_delegation/${network}.${txid}.json`;
+  await fs.writeFile(filename, JSON.stringify(result, null, 2) + '\n');
+  console.log(`Wrote delegation response to ${filename}`);
+}
+
+yargs(hideBin(process.argv))
+  .command({
+    command: 'sync-babylon-params',
+    describe: 'Sync Babylon params',
+    builder(b) {
+      return b.option('network', {
+        choices: ['mainnet', 'testnet'] as const,
+        description: 'Network',
+      });
+    },
+    async handler(argv) {
+      await syncParams(argv.network);
+    },
+  })
+  .command({
+    command: 'sync-btc-delegation',
+    describe: 'Sync BTC delegation messages',
+    builder(b) {
+      return b
+        .option('network', {
+          choices: ['mainnet', 'testnet'] as const,
+          description: 'Network',
+        })
+        .option('txid', {
+          type: 'string',
+          description: 'Transaction ID of the delegation message to sync',
+        });
+    },
+    async handler(argv) {
+      await syncDelegationResponse(argv.network, argv.txid);
+    },
+  })
+  .demandCommand()
+  .help()
+  .strict().argv;