@mysten-incubation/hashi 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mysten-incubation/hashi
 
+## 0.3.1
+
+### Patch Changes
+
+- 0af8dfa: Derive Bitcoin deposit addresses with Hashi's delayed MPC recovery taproot leaf.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/bitcoin.d.mts

@@ -56,14 +56,14 @@ declare function arkworksToSec1Compressed(ark: Uint8Array): Uint8Array;
  */
 declare function deriveChildPubkey(mpcKeyCompressed: Uint8Array, suiAddress: Uint8Array): Uint8Array;
 /**
- * Builds a 2-of-2 P2TR script-path-only address:
- * `tr(NUMS, multi_a(2, guardian, derived_mpc))`.
+ * Builds Hashi's P2TR script-path-only deposit address:
+ * `tr(NUMS, {multi_a(2, guardian, derived_mpc), and_v(v:older(delay), pk(derived_mpc))})`.
  *
  * The leaf script is a BIP-342 `multi_a` 2-of-2 — both Schnorr signatures must
  * be present to spend, ordered so that the witness stack is
  * `[derived_mpc_sig, guardian_sig, leaf_script, control_block]` (LIFO). This
- * is the exact script the bridge's withdrawal path constructs in
- * `crates/hashi-types/src/guardian/bitcoin_utils.rs`'s `compute_taproot_descriptor`.
+ * is the exact immediate-spend script the bridge's withdrawal path constructs
+ * in `crates/hashi-types/src/bitcoin/taproot.rs`'s `compute_taproot_descriptor`.
  *
  * The leaf script is exactly 70 bytes:
  *
@@ -80,11 +80,17 @@ declare function deriveChildPubkey(mpcKeyCompressed: Uint8Array, suiAddress: Uin
  * codegen routes through `Builder::push_int(2)` which emits the small-num
  * opcode. A literal pushdata would change the leaf hash and the address.
  *
+ * The recovery leaf script is a BIP-342 `and_v(v:older(delay), pk(derived_mpc))`:
+ * after Hashi's 60-day BIP-68 relative timelock, the MPC child key alone can
+ * spend the output if the guardian key is unavailable.
+ *
  * The taproot output key is computed per BIP-341:
  *
  * ```text
- * leafHash  = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(script) ‖ script)
- * tweak     = tagged_hash("TapTweak", NUMS ‖ leafHash)
+ * leaf1     = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(two_of_two_script) ‖ two_of_two_script)
+ * leaf2     = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(recovery_script) ‖ recovery_script)
+ * root      = tagged_hash("TapBranch", min(leaf1, leaf2) ‖ max(leaf1, leaf2))
+ * tweak     = tagged_hash("TapTweak", NUMS ‖ root)
  * outputKey = NUMS + tweak × G
  * ```
  *
@@ -128,11 +134,12 @@ interface DepositAddressInputs {
  * Main entry point for the address derivation pipeline. Combines
  * {@link deriveChildPubkey} and {@link twoOfTwoTaprootScriptPathAddress} into
  * a single call. The produced address matches the Rust node's
- * `bitcoin_utils::two_of_two_taproot_script_path_address` byte-for-byte.
+ * `hashi_types::bitcoin::taproot::taproot_address` byte-for-byte.
  *
  * The address scheme is:
  * ```text
- * tr(NUMS, multi_a(2, guardian, derive(mpc_master, sui_address)))
+ * tr(NUMS, {multi_a(2, guardian, derive(mpc_master, sui_address)),
+ *           and_v(v:older(delay), pk(derive(mpc_master, sui_address)))})
  * ```
  *
  * @returns bech32m-encoded P2TR deposit address (e.g. `tb1p…` for signet)

package/dist/bitcoin.mjs

@@ -16,10 +16,10 @@ import { concatBytes } from "@noble/hashes/utils.js";
 * and the Hashi guardian co-sign the withdrawal that spends it, and the bridge
 * mints equivalent tokens on Sui.
 *
-* The deposit address is a 2-of-2 Pay-to-Taproot (P2TR / BIP-341) script-path
-* address whose spending condition is `multi_a(2, guardian_btc_pubkey,
-* derive(mpc_master, sui_address))` — both the guardian enclave's BIP-340 key
-* and the MPC-derived child key must produce a Schnorr signature to spend.
+* The deposit address is a Pay-to-Taproot (P2TR / BIP-341) script-path address
+* with two leaves: an immediate `multi_a(2, guardian_btc_pubkey,
+* derive(mpc_master, sui_address))` spend, and a delayed MPC-only recovery
+* spend after Hashi's BIP-68 relative timelock.
 *
 * The full derivation pipeline is:
 *
@@ -34,23 +34,24 @@ import { concatBytes } from "@noble/hashes/utils.js";
 *    (see {@link deriveChildPubkey}). This replicates the Rust function
 *    `fastcrypto_tbls::threshold_schnorr::key_derivation::derive_verifying_key`.
 *
-* 3. **Build** the taproot address: `tr(NUMS, multi_a(2, guardian, child))`
+* 3. **Build** the taproot address:
+*    `tr(NUMS, {multi_a(2, guardian, child), and_v(v:older(delay), pk(child))})`
 *    where NUMS is a Nothing-Up-My-Sleeve point with no known private key,
 *    forcing all spends through the script path (see
 *    {@link twoOfTwoTaprootScriptPathAddress}).
 *
 * The end-to-end helper {@link generateDepositAddress} combines steps 2–3.
 *
-* Mirrors `two_of_two_taproot_script_path_address` in
-* `crates/hashi-types/src/guardian/bitcoin_utils.rs`. Cross-language test
-* vectors live in both this file's unit tests and the matching Rust unit test
-* `cross_lang_2of2_test_vectors`.
+* Mirrors `taproot_address` in `crates/hashi-types/src/bitcoin/taproot.rs`.
+* Cross-language test vectors live in both this file's unit tests and the
+* matching Rust unit test `cross_lang_2of2_test_vectors`.
 *
 * @see https://mystenlabs.github.io/hashi/design/address-scheme.html
 */
 const Point = secp256k1.Point;
 const CURVE_ORDER = Point.CURVE().n;
 const NUMS_POINT = Point.fromBytes(concatBytes(new Uint8Array([2]), NUMS_KEY));
+const HASHI_MPC_RECOVERY_DELAY_SEQUENCE = 1 << 22 | Math.ceil(1440 * 60 * 60 / 512);
 /** BIP-340 tagged hash: SHA256(SHA256(tag) ‖ SHA256(tag) ‖ msg) */
 function taggedHash(tag, ...msgs) {
 	const tagHash = sha256(new TextEncoder().encode(tag));
@@ -62,6 +63,37 @@ function bytesToNumberBE(bytes) {
 	for (const byte of bytes) n = n << 8n | BigInt(byte);
 	return n;
 }
+/** CompactSize for scripts small enough to fit in one byte. */
+function compactSize(len) {
+	if (len >= 253) throw new Error(`Unsupported script length ${len}`);
+	return new Uint8Array([len]);
+}
+function scriptNum(n) {
+	if (n === 0) return new Uint8Array();
+	const bytes = [];
+	let value = n;
+	while (value > 0) {
+		bytes.push(value & 255);
+		value >>= 8;
+	}
+	if ((bytes[bytes.length - 1] & 128) !== 0) bytes.push(0);
+	return new Uint8Array(bytes);
+}
+function pushBytes(bytes) {
+	if (bytes.length >= 76) throw new Error(`Unsupported push length ${bytes.length}`);
+	return concatBytes(new Uint8Array([bytes.length]), bytes);
+}
+function lexicographicCompare(a, b) {
+	const len = Math.min(a.length, b.length);
+	for (let i = 0; i < len; i++) if (a[i] !== b[i]) return a[i] - b[i];
+	return a.length - b.length;
+}
+function tapLeafHash(script) {
+	return taggedHash("TapLeaf", new Uint8Array([192]), compactSize(script.length), script);
+}
+function tapBranchHash(a, b) {
+	return lexicographicCompare(a, b) <= 0 ? taggedHash("TapBranch", a, b) : taggedHash("TapBranch", b, a);
+}
 /**
 * Converts a 33-byte arkworks-compressed secp256k1 point to 33-byte SEC1 compressed format.
 *
@@ -136,14 +168,14 @@ function deriveChildPubkey(mpcKeyCompressed, suiAddress) {
 	return parentPoint.add(Point.BASE.multiply(tweakScalar)).toBytes(true).slice(1);
 }
 /**
-* Builds a 2-of-2 P2TR script-path-only address:
-* `tr(NUMS, multi_a(2, guardian, derived_mpc))`.
+* Builds Hashi's P2TR script-path-only deposit address:
+* `tr(NUMS, {multi_a(2, guardian, derived_mpc), and_v(v:older(delay), pk(derived_mpc))})`.
 *
 * The leaf script is a BIP-342 `multi_a` 2-of-2 — both Schnorr signatures must
 * be present to spend, ordered so that the witness stack is
 * `[derived_mpc_sig, guardian_sig, leaf_script, control_block]` (LIFO). This
-* is the exact script the bridge's withdrawal path constructs in
-* `crates/hashi-types/src/guardian/bitcoin_utils.rs`'s `compute_taproot_descriptor`.
+* is the exact immediate-spend script the bridge's withdrawal path constructs
+* in `crates/hashi-types/src/bitcoin/taproot.rs`'s `compute_taproot_descriptor`.
 *
 * The leaf script is exactly 70 bytes:
 *
@@ -160,11 +192,17 @@ function deriveChildPubkey(mpcKeyCompressed, suiAddress) {
 * codegen routes through `Builder::push_int(2)` which emits the small-num
 * opcode. A literal pushdata would change the leaf hash and the address.
 *
+* The recovery leaf script is a BIP-342 `and_v(v:older(delay), pk(derived_mpc))`:
+* after Hashi's 60-day BIP-68 relative timelock, the MPC child key alone can
+* spend the output if the guardian key is unavailable.
+*
 * The taproot output key is computed per BIP-341:
 *
 * ```text
-* leafHash  = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(script) ‖ script)
-* tweak     = tagged_hash("TapTweak", NUMS ‖ leafHash)
+* leaf1     = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(two_of_two_script) ‖ two_of_two_script)
+* leaf2     = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(recovery_script) ‖ recovery_script)
+* root      = tagged_hash("TapBranch", min(leaf1, leaf2) ‖ max(leaf1, leaf2))
+* tweak     = tagged_hash("TapTweak", NUMS ‖ root)
 * outputKey = NUMS + tweak × G
 * ```
 *
@@ -182,16 +220,21 @@ function deriveChildPubkey(mpcKeyCompressed, suiAddress) {
 function twoOfTwoTaprootScriptPathAddress(guardianBtcXOnly, derivedMpcXOnly, network) {
 	if (guardianBtcXOnly.length !== 32) throw new Error(`Expected 32-byte x-only guardian pubkey, got ${guardianBtcXOnly.length}`);
 	if (derivedMpcXOnly.length !== 32) throw new Error(`Expected 32-byte x-only derived MPC pubkey, got ${derivedMpcXOnly.length}`);
-	const tapscript = new Uint8Array(70);
-	tapscript[0] = 32;
-	tapscript.set(guardianBtcXOnly, 1);
-	tapscript[33] = 172;
-	tapscript[34] = 32;
-	tapscript.set(derivedMpcXOnly, 35);
-	tapscript[67] = 186;
-	tapscript[68] = 82;
-	tapscript[69] = 156;
-	const tweakScalar = bytesToNumberBE(taggedHash("TapTweak", NUMS_KEY, taggedHash("TapLeaf", new Uint8Array([192, tapscript.length]), tapscript))) % CURVE_ORDER;
+	const twoOfTwoScript = new Uint8Array(70);
+	twoOfTwoScript[0] = 32;
+	twoOfTwoScript.set(guardianBtcXOnly, 1);
+	twoOfTwoScript[33] = 172;
+	twoOfTwoScript[34] = 32;
+	twoOfTwoScript.set(derivedMpcXOnly, 35);
+	twoOfTwoScript[67] = 186;
+	twoOfTwoScript[68] = 82;
+	twoOfTwoScript[69] = 156;
+	const recoveryScript = concatBytes(pushBytes(scriptNum(HASHI_MPC_RECOVERY_DELAY_SEQUENCE)), new Uint8Array([
+		178,
+		105,
+		32
+	]), derivedMpcXOnly, new Uint8Array([172]));
+	const tweakScalar = bytesToNumberBE(taggedHash("TapTweak", NUMS_KEY, tapBranchHash(tapLeafHash(twoOfTwoScript), tapLeafHash(recoveryScript)))) % CURVE_ORDER;
 	const outputKey = NUMS_POINT.add(Point.BASE.multiply(tweakScalar)).toBytes(true).slice(1);
 	const words = [1, ...bech32m.toWords(outputKey)];
 	return bech32m.encode(NETWORK_HRP[network], words);
@@ -202,11 +245,12 @@ function twoOfTwoTaprootScriptPathAddress(guardianBtcXOnly, derivedMpcXOnly, net
 * Main entry point for the address derivation pipeline. Combines
 * {@link deriveChildPubkey} and {@link twoOfTwoTaprootScriptPathAddress} into
 * a single call. The produced address matches the Rust node's
-* `bitcoin_utils::two_of_two_taproot_script_path_address` byte-for-byte.
+* `hashi_types::bitcoin::taproot::taproot_address` byte-for-byte.
 *
 * The address scheme is:
 * ```text
-* tr(NUMS, multi_a(2, guardian, derive(mpc_master, sui_address)))
+* tr(NUMS, {multi_a(2, guardian, derive(mpc_master, sui_address)),
+*           and_v(v:older(delay), pk(derive(mpc_master, sui_address)))})
 * ```
 *
 * @returns bech32m-encoded P2TR deposit address (e.g. `tb1p…` for signet)

package/dist/client.d.mts

@@ -52,10 +52,10 @@ declare class HashiClient {
    *
    * Fetches the MPC committee public key and the guardian's BTC public key
    * from on-chain, derives an MPC child key against the Sui address, and
-   * builds a 2-of-2 taproot script-path address
-   * (`tr(NUMS, multi_a(2, guardian, derived_mpc))`). The address matches
-   * the bridge's on-chain `validate_deposit_request_derivation_path` check
-   * byte-for-byte.
+   * builds the Hashi taproot script tree: an immediate 2-of-2 leaf
+   * (`multi_a(2, guardian, derived_mpc)`) plus a delayed MPC-only recovery
+   * leaf. The address matches the bridge's on-chain
+   * `validate_deposit_request_derivation_path` check byte-for-byte.
    *
    * The MPC key (`committee_set.mpc_public_key`) and the guardian key
    * (`guardian_btc_public_key` config) come from a single fetch of the

package/dist/client.mjs

@@ -444,10 +444,10 @@ var HashiClient = class {
 	*
 	* Fetches the MPC committee public key and the guardian's BTC public key
 	* from on-chain, derives an MPC child key against the Sui address, and
-	* builds a 2-of-2 taproot script-path address
-	* (`tr(NUMS, multi_a(2, guardian, derived_mpc))`). The address matches
-	* the bridge's on-chain `validate_deposit_request_derivation_path` check
-	* byte-for-byte.
+	* builds the Hashi taproot script tree: an immediate 2-of-2 leaf
+	* (`multi_a(2, guardian, derived_mpc)`) plus a delayed MPC-only recovery
+	* leaf. The address matches the bridge's on-chain
+	* `validate_deposit_request_derivation_path` check byte-for-byte.
 	*
 	* The MPC key (`committee_set.mpc_public_key`) and the guardian key
 	* (`guardian_btc_public_key` config) come from a single fetch of the

package/dist/types.d.mts

@@ -53,8 +53,8 @@ interface GovernanceConfig {
   readonly guardianPublicKey: Uint8Array | null;
   /**
    * Guardian's BIP-340 x-only secp256k1 BTC public key (32 bytes), the
-   * `pk1` slot of the on-chain 2-of-2 deposit-address descriptor. `null`
-   * if unset (deposit-address derivation will fail).
+   * `pk1` slot of the immediate 2-of-2 leaf in the on-chain deposit-address
+   * descriptor. `null` if unset (deposit-address derivation will fail).
    */
   readonly guardianBtcPublicKey: Uint8Array | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten-incubation/hashi",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "TypeScript SDK for the Hashi Sui Move smart contracts",
   "license": "Apache-2.0",
   "author": "Mysten Labs <build@mystenlabs.com>",