feat(utxo-descriptors): add sBTC taproot descriptors

veetragjain · veetragjain · commit 90bd98934658 · 2026-05-07T11:26:04.000+05:30
Ticket: CSHLD-744
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -1,12 +1,15 @@
 # BitGoJS code owners and first officers will automatically be requested for review whenever a pull request touches the files they own.
+
 # Each line is a file pattern followed by one or more owners.
 
 # These owners and first officers will be the default owners for everything in the repo.
-*   @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
+
+- @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
 
 # Order is important. The last matching pattern has the most precedence.
 
 # UTXO coin modules
+
 /modules/abstract-utxo/ @BitGo/btc-team
 /modules/bitgo/test/v2/unit/coins/utxo/ @BitGo/btc-team
 /modules/bitgo/test/v2/unit/lightning.ts @BitGo/btc-team
@@ -27,15 +30,18 @@
 /modules/utxo-lib/ @BitGo/btc-team
 /modules/utxo-ord/ @BitGo/btc-team
 /modules/utxo-staking/ @BitGo/btc-team
+/modules/utxo-descriptors/ @BitGo/btc-team @BitGo/ethalt-team
 /modules/babylonlabs-io-btc-staking-ts @BitGo/btc-team
 /modules/bitgo/test/v2/unit/coins/abstractUtxoCoin.ts @BitGo/btc-team
 /modules/bitgo/test/v2/unit/coins/payGoPSBTHexFixture/psbtHexProof.ts @BitGo/btc-team
 
 # Lightning coin modules
+
 /modules/abstract-lightning/ @BitGo/btc-team
 /modules/sdk-coin-lnbtc/ @BitGo/btc-team
 
 # Eth
+
 /modules/account-lib/ @BitGo/ethalt-team
 /modules/sdk-coin-celo/ @BitGo/ethalt-team
 /modules/sdk-coin-etc/ @BitGo/ethalt-team
@@ -46,6 +52,7 @@
 /modules/bitgo/test/v2/unit/coins/token.ts @BitGo/ethalt-team
 
 # All other coins
+
 /modules/abstract-cosmos/ @BitGo/ethalt-team
 /modules/abstract-substrate/ @BitGo/ethalt-team
 /modules/sdk-coin-ada/ @BitGo/ethalt-team
@@ -106,15 +113,18 @@
 /modules/sdk-coin-hash/ @BitGo/ethalt-team
 
 # Examples
+
 /examples/ @BitGo/ethalt-team
 /examples/ts/btc/ @BitGo/btc-team
 /examples/ts/stablecoin @Bitgo/stablecoins
 
 # Trade
+
 /modules/sdk-core/src/bitgo/address-book/ @BitGo/prime
 /modules/sdk-core/src/bitgo/trading/ @BitGo/prime
 
 # Core Modules
+
 /modules/bitgo/ @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
 /modules/bitgo/test/v2/unit/lightning/ @BitGo/btc-team
 /modules/blake2b-wasm/ @BitGo/wallet-core @BitGo/wallet-core-india
@@ -144,6 +154,7 @@
 /webpack/ @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
 
 # Asset Metadata Service
+
 /modules/statics/src/coins/botTokens.ts @BitGo/ams
 /modules/statics/src/coins/botOfcTokens.ts @BitGo/ams
 
@@ -156,7 +167,7 @@
 /Dockerfile @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
 /lerna.json @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india @BitGo/devops
 /package.json @BitGo/sdk-reviewers
-**/package.json @BitGo/sdk-reviewers
+\*\*/package.json @BitGo/sdk-reviewers
 /tsconfig.json @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india @BitGo/devops
 /tsconfig.packages.json @BitGo/coins @BitGo/wallet-core @BitGo/wallet-core-india
 /yarn.lock @BitGo/sdk-reviewers
diff --git a/modules/utxo-descriptors/.eslintignore b/modules/utxo-descriptors/.eslintignore
@@ -0,0 +1,2 @@
+dist
+node_modules
diff --git a/modules/utxo-descriptors/.eslintrc.js b/modules/utxo-descriptors/.eslintrc.js
@@ -0,0 +1,7 @@
+module.exports = {
+  extends: ['../../.eslintrc.json'],
+  rules: {
+    'import/order': ['error', { 'newlines-between': 'always' }],
+    'import/no-internal-modules': 'off',
+  },
+};
diff --git a/modules/utxo-descriptors/.gitignore b/modules/utxo-descriptors/.gitignore
@@ -0,0 +1,3 @@
+/dist
+/node_modules
+/.nyc_output
diff --git a/modules/utxo-descriptors/.mocharc.js b/modules/utxo-descriptors/.mocharc.js
@@ -0,0 +1,4 @@
+module.exports = {
+  require: 'tsx',
+  extension: ['.js', '.ts'],
+};
diff --git a/modules/utxo-descriptors/.npmignore b/modules/utxo-descriptors/.npmignore
@@ -0,0 +1,10 @@
+**/*.ts
+!**/*.d.ts
+src
+test
+tsconfig.json
+tslint.json
+.gitignore
+.eslintignore
+.mocharc.yml
+.prettierignore
diff --git a/modules/utxo-descriptors/.prettierignore b/modules/utxo-descriptors/.prettierignore
@@ -0,0 +1,4 @@
+.nyc_output/
+dist
+node_modules
+test/fixtures
diff --git a/modules/utxo-descriptors/.prettierrc.yml b/modules/utxo-descriptors/.prettierrc.yml
@@ -0,0 +1,3 @@
+printWidth: 120
+singleQuote: true
+trailingComma: es5
diff --git a/modules/utxo-descriptors/README.md b/modules/utxo-descriptors/README.md
@@ -0,0 +1 @@
+# BitGo UTXO descriptors
diff --git a/modules/utxo-descriptors/package.json b/modules/utxo-descriptors/package.json
@@ -0,0 +1,66 @@
+{
+  "name": "@bitgo/utxo-descriptors",
+  "version": "1.39.1",
+  "description": "BitGo SDK for building UTXO descriptors",
+  "main": "./dist/cjs/src/index.js",
+  "module": "./dist/esm/index.js",
+  "browser": "./dist/esm/index.js",
+  "types": "./dist/cjs/src/index.d.ts",
+  "files": [
+    "dist/cjs",
+    "dist/esm"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/src/index.d.ts",
+        "default": "./dist/cjs/src/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "yarn tsc --build --incremental --verbose .",
+    "build:esm": "yarn tsc --project tsconfig.esm.json",
+    "fmt": "prettier --write .",
+    "check-fmt": "prettier --check '**/*.{ts,js,json}'",
+    "clean": "rm -r ./dist",
+    "lint": "eslint --quiet .",
+    "prepare": "npm run build",
+    "coverage": "nyc -- npm run unit-test",
+    "unit-test": "mocha --recursive \"test/**/*.ts\""
+  },
+  "author": "BitGo SDK Team <sdkteam@bitgo.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BitGo/BitGoJS.git",
+    "directory": "modules/utxo-descriptors"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "yarn prettier --write",
+      "yarn eslint --fix"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "nyc": {
+    "extension": [
+      ".ts"
+    ]
+  },
+  "dependencies": {
+    "@bitgo/utxo-core": "^1.37.1",
+    "@bitgo/utxo-lib": "^11.22.1",
+    "@bitgo/wasm-utxo": "^4.11.0"
+  }
+}
diff --git a/modules/utxo-descriptors/src/index.ts b/modules/utxo-descriptors/src/index.ts
@@ -0,0 +1 @@
+export * as sbtc from './sbtc';
diff --git a/modules/utxo-descriptors/src/sbtc/constants.ts b/modules/utxo-descriptors/src/sbtc/constants.ts
@@ -0,0 +1,31 @@
+/**
+ * Well-known unspendable Taproot internal key.
+ *
+ * Nothing-up-my-sleeve point on secp256k1 with no known private key. Using it
+ * as a Taproot internal key guarantees the output cannot be spent via the
+ * key path — only via one of the script-path leaves.
+ */
+export const UNSPENDABLE_INTERNAL_KEY = '50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0';
+
+/**
+ * Default reclaim relative timelock — number of Bitcoin blocks the depositor
+ * must wait before they can reclaim their BTC if the sBTC signers fail to
+ * process the deposit.
+ */
+export const DEFAULT_RECLAIM_LOCK_TIME = 950;
+
+/**
+ * Default max signer fee in satoshis. Encoded as a big-endian u64 (8 bytes)
+ * inside the deposit-leaf metadata payload.
+ */
+export const DEFAULT_MAX_SIGNER_FEE = 80_000;
+
+/** Length of the encoded sBTC max-fee field, in bytes. */
+export const MAX_FEE_BYTE_LENGTH = 8;
+
+/**
+ * Length of the Stacks recipient field inside the deposit payload.
+ *
+ * 1-byte address version + 21-byte hash160 of the Stacks principal = 22 bytes.
+ */
+export const STACKS_RECIPIENT_BYTE_LENGTH = 22;
diff --git a/modules/utxo-descriptors/src/sbtc/depositAddress.ts b/modules/utxo-descriptors/src/sbtc/depositAddress.ts
@@ -0,0 +1,41 @@
+import { BIP32Interface } from '@bitgo/utxo-lib';
+import { Descriptor } from '@bitgo/wasm-utxo';
+
+import { createSbtcDepositDescriptor, SbtcDepositDescriptorParams } from './descriptor';
+
+/**
+ * Compile the sBTC deposit Taproot scriptPubKey.
+ *
+ * If `params.walletKeys` contains BIP32 xpubs, the descriptor is derivable and
+ * `derivationIndex` selects which child keys go into the reclaim leaf. If
+ * `params.walletKeys` contains raw 32-byte x-only Buffers, the descriptor is
+ * definite and `derivationIndex` is ignored.
+ */
+export function createSbtcDepositScriptPubKey(params: SbtcDepositDescriptorParams, derivationIndex = 0): Buffer {
+  const descString = createSbtcDepositDescriptor(params);
+  if (descString.includes('/*')) {
+    const desc = Descriptor.fromString(descString, 'derivable');
+    return Buffer.from(desc.atDerivationIndex(derivationIndex).scriptPubkey());
+  }
+  const desc = Descriptor.fromString(descString, 'definite');
+  return Buffer.from(desc.scriptPubkey());
+}
+
+/**
+ * Derive the three concrete x-only reclaim pubkeys at the given derivation
+ * index from a triple of BIP32 xpubs.
+ *
+ * The descriptor library performs this derivation internally when computing
+ * `scriptPubkey()`; this helper exposes the same derivation for callers that
+ * need the keys directly (e.g., constructing a witness for the reclaim leaf).
+ */
+export function deriveReclaimKeys(
+  walletKeys: [BIP32Interface, BIP32Interface, BIP32Interface],
+  index: number
+): [Buffer, Buffer, Buffer] {
+  const [k1, k2, k3] = walletKeys.map((k) => {
+    const child = k.derive(index);
+    return Buffer.from(child.publicKey.subarray(1));
+  });
+  return [k1, k2, k3];
+}
diff --git a/modules/utxo-descriptors/src/sbtc/descriptor.ts b/modules/utxo-descriptors/src/sbtc/descriptor.ts
@@ -0,0 +1,115 @@
+import { BIP32Interface } from '@bitgo/utxo-lib';
+import { ast } from '@bitgo/wasm-utxo';
+
+import { MAX_FEE_BYTE_LENGTH, STACKS_RECIPIENT_BYTE_LENGTH, UNSPENDABLE_INTERNAL_KEY } from './constants';
+
+/**
+ * A reclaim key entry — either a BIP32 xpub/xprv (derivable) or a concrete
+ * 32-byte x-only public key (definite).
+ */
+export type SbtcReclaimKey = BIP32Interface | Buffer;
+
+export type SbtcDepositDescriptorParams = {
+  /**
+   * The three reclaim keys (user, backup, bitgo). Used in the reclaim leaf as
+   * a 2-of-3 Tapscript multisig (`multi_a`). If a key is a `BIP32Interface`,
+   * it is rendered as `<xpub>/*` and the descriptor is derivable. If a key is
+   * a 32-byte `Buffer`, it is rendered as a concrete x-only hex key and the
+   * descriptor is definite.
+   */
+  walletKeys: [SbtcReclaimKey, SbtcReclaimKey, SbtcReclaimKey];
+  /**
+   * Number of Bitcoin blocks the depositor must wait (relative timelock) before
+   * the reclaim leaf becomes spendable.
+   */
+  lockTime: number;
+  /** Max satoshis the sBTC signers may take. Encoded big-endian u64 (8 bytes). */
+  maxFee: number | bigint;
+  /**
+   * Stacks recipient bytes — 22 bytes:
+   *   byte 0     = Stacks address version
+   *   bytes 1-21 = hash160 of the Stacks principal
+   */
+  stacksRecipient: Buffer;
+  /** 32-byte x-only sBTC signers' aggregate pubkey. */
+  signersAggregateKey: Buffer;
+};
+
+function asDescriptorKey(key: SbtcReclaimKey, neutered: boolean): string {
+  if (Buffer.isBuffer(key)) {
+    if (key.length !== 32) {
+      throw new Error(`reclaim key buffer must be 32 bytes x-only (got ${key.length})`);
+    }
+    return key.toString('hex');
+  }
+  return (neutered ? key.neutered() : key).toBase58() + '/*';
+}
+
+/**
+ * Encode the deposit-leaf metadata that the sBTC signers parse from the
+ * witness: max-fee (u64 big-endian, 8 bytes) followed by the 22-byte
+ * Stacks recipient. Total: 30 bytes.
+ *
+ * The result is the single `payload_drop` argument inside the deposit leaf.
+ */
+export function encodeDepositPayload(maxFee: number | bigint, stacksRecipient: Buffer): Buffer {
+  if (stacksRecipient.length !== STACKS_RECIPIENT_BYTE_LENGTH) {
+    throw new Error(`stacksRecipient must be ${STACKS_RECIPIENT_BYTE_LENGTH} bytes (got ${stacksRecipient.length})`);
+  }
+  const fee = typeof maxFee === 'bigint' ? maxFee : BigInt(maxFee);
+  if (fee < 0n || fee > 0xffffffffffffffffn) {
+    throw new Error(`maxFee (${maxFee}) does not fit in unsigned 64 bits`);
+  }
+  const feeBuf = Buffer.alloc(MAX_FEE_BYTE_LENGTH);
+  feeBuf.writeBigUInt64BE(fee);
+  return Buffer.concat([feeBuf, stacksRecipient]);
+}
+
+/**
+ * Build the sBTC peg-in deposit Taproot descriptor as a single all-miniscript
+ * `tr()` with two leaves:
+ *
+ *   tr(<UNSPENDABLE>,
+ *     {
+ *       c:and_v(payload_drop(<feeBE||recipient>), pk_k(<signersKey>)),
+ *       and_v(r:older(<lockTime>), multi_a(2, xpub1/*, xpub2/*, xpub3/*))
+ *     }
+ *   )
+ *
+ * - Deposit leaf compiles to: `<30B-payload> OP_DROP <signersKey> OP_CHECKSIG`
+ * - Reclaim leaf compiles to: `<lockTime> OP_CSV OP_DROP <k1> OP_CHECKSIG <k2> OP_CHECKSIGADD <k3> OP_CHECKSIGADD OP_2 OP_NUMEQUAL`
+ *
+ * Both fragments are valid Bitcoin miniscript via the `payload_drop` and
+ * `r:older` extensions added in `@bitgo/wasm-utxo` 4.11.0
+ * (BitGoWASM PR #272).
+ *
+ * The descriptor is derivable: the reclaim xpubs use `/*` and the descriptor
+ * library resolves them to concrete x-only keys at each derivation index.
+ *
+ * @returns descriptor string (without checksum)
+ */
+export function createSbtcDepositDescriptor(params: SbtcDepositDescriptorParams, neutered = true): string {
+  if (params.lockTime <= 0) {
+    throw new Error(`lockTime (${params.lockTime}) must be greater than 0`);
+  }
+  if (params.signersAggregateKey.length !== 32) {
+    throw new Error(`signersAggregateKey must be 32 bytes x-only (got ${params.signersAggregateKey.length})`);
+  }
+
+  const payloadHex = encodeDepositPayload(params.maxFee, params.stacksRecipient).toString('hex');
+  const reclaimKeys = params.walletKeys.map((k) => asDescriptorKey(k, neutered));
+
+  // `payload_drop` is not yet in the public MiniscriptNode TS union, so cast
+  // the deposit leaf — the formatter is generic and renders it correctly.
+  const depositLeaf = {
+    'c:and_v': [{ payload_drop: payloadHex }, { pk_k: params.signersAggregateKey.toString('hex') }],
+  } as unknown as ast.MiniscriptNode;
+
+  const reclaimLeaf: ast.MiniscriptNode = {
+    and_v: [{ 'r:older': params.lockTime }, { multi_a: [2, ...reclaimKeys] }],
+  };
+
+  return ast.formatNode({
+    tr: [UNSPENDABLE_INTERNAL_KEY, [depositLeaf, reclaimLeaf]],
+  });
+}
diff --git a/modules/utxo-descriptors/src/sbtc/index.ts b/modules/utxo-descriptors/src/sbtc/index.ts
@@ -0,0 +1,3 @@
+export * from './constants';
+export * from './descriptor';
+export * from './depositAddress';
diff --git a/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-ast.json b/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-ast.json
diff --git a/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-spk.hex b/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-spk.hex
diff --git a/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-string.txt b/modules/utxo-descriptors/test/fixtures/sbtc/descriptor/default-string.txt
diff --git a/modules/utxo-descriptors/test/unit/sbtc/descriptor.ts b/modules/utxo-descriptors/test/unit/sbtc/descriptor.ts
diff --git a/modules/utxo-descriptors/tsconfig.esm.json b/modules/utxo-descriptors/tsconfig.esm.json
diff --git a/modules/utxo-descriptors/tsconfig.json b/modules/utxo-descriptors/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+/dist`
	`2`	`+/node_modules`
	`3`	`+/.nyc_output`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+printWidth: 120`
	`2`	`+singleQuote: true`
	`3`	`+trailingComma: es5`