@mysten-incubation/hashi 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- ced85d2: Derive deposit addresses as 2-of-2 (guardian, MPC-child) taproot to match the on-chain bridge (hashi#609). `generateDepositAddress` (pure helper) now takes a named-args object including `guardianBtcXOnly`; `HashiClient.generateDepositAddress` reads the guardian key from on-chain and fails fast with `HashiConfigError` when the deployment is not guardian-provisioned. `GovernanceConfig` gains `guardianUrl`, `guardianPublicKey`, `guardianBtcPublicKey`. Adds `twoOfTwoTaprootScriptPathAddress` as a public primitive and removes the single-key `taprootScriptPathAddress` helper, which the bridge no longer accepts.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/bitcoin.d.mts

@@ -56,61 +56,100 @@ declare function arkworksToSec1Compressed(ark: Uint8Array): Uint8Array;
  */
 declare function deriveChildPubkey(mpcKeyCompressed: Uint8Array, suiAddress: Uint8Array): Uint8Array;
 /**
- * Builds a P2TR script-path-only address: `tr(NUMS, pk(pubkey))`.
+ * 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))})`.
  *
- * A BIP-341 taproot output has two spending paths: the *key path* (spend with
- * the internal key) and the *script path* (reveal and satisfy a script in the
- * Merkle tree). By using the NUMS (Nothing-Up-My-Sleeve) point as the internal
- * key — a point with no known discrete logarithm — the key path is provably
- * unspendable, forcing every spend through the script path.
+ * 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 immediate-spend script the bridge's withdrawal path constructs
+ * in `crates/hashi-types/src/bitcoin/taproot.rs`'s `compute_taproot_descriptor`.
  *
- * The script tree contains a single leaf: `<pubkey> OP_CHECKSIG`, meaning the
- * MPC committee must produce a valid Schnorr signature for `pubkey` to spend
- * the output. This is how the committee authorises withdrawals.
+ * The leaf script is exactly 70 bytes:
+ *
+ * ```text
+ * 0x20 ‖ guardian   (32)   // OP_PUSHBYTES_32 <pk1>
+ * 0xAC                     // OP_CHECKSIG
+ * 0x20 ‖ derived_mpc(32)   // OP_PUSHBYTES_32 <pk2>
+ * 0xBA                     // OP_CHECKSIGADD
+ * 0x52                     // OP_2 (push small int 2)
+ * 0x9C                     // OP_NUMEQUAL
+ * ```
+ *
+ * Note `0x52` (OP_2) — not `0x01 0x02` — because `rust-miniscript`'s `multi_a`
+ * 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)
- * outputKey  = NUMS + tweak × G
+ * 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
  * ```
  *
- * The resulting output key is encoded as a SegWit v1 witness program in a
- * bech32m address.
+ * **Argument ordering is load-bearing.** Guardian first, derived-MPC second.
+ * Swapping them produces a different (but real-looking) `tb1p…` whose
+ * withdrawals the bridge cannot spend.
  *
- * @param pubkey - 32-byte x-only public key for the script leaf
+ * @param guardianBtcXOnly - 32-byte BIP-340 x-only guardian BTC public key
+ *   (from the on-chain `guardian_btc_public_key` config)
+ * @param derivedMpcXOnly - 32-byte x-only public key for the MPC-derived child
+ *   (output of {@link deriveChildPubkey})
  * @param network - Bitcoin network for the bech32m human-readable prefix
  * @returns bech32m-encoded P2TR address (e.g. `bc1p…`, `tb1p…`, `bcrt1p…`)
  */
-declare function taprootScriptPathAddress(pubkey: Uint8Array, network: BitcoinNetwork): string;
+declare function twoOfTwoTaprootScriptPathAddress(guardianBtcXOnly: Uint8Array, derivedMpcXOnly: Uint8Array, network: BitcoinNetwork): string;
+/**
+ * Named-args input bundle for {@link generateDepositAddress}. Using named args
+ * avoids the foot-gun of two 32-byte `Uint8Array`s in adjacent positions —
+ * swapping `guardianBtcXOnly` and `suiAddress` would silently produce a valid
+ * but wrong address.
+ */
+interface DepositAddressInputs {
+  /**
+   * 33-byte SEC1-compressed secp256k1 MPC master key (post-arkworks
+   * conversion). See {@link arkworksToSec1Compressed}.
+   */
+  readonly mpcMasterCompressed: Uint8Array;
+  /**
+   * 32-byte BIP-340 x-only guardian BTC public key (from the on-chain
+   * `guardian_btc_public_key` config).
+   */
+  readonly guardianBtcXOnly: Uint8Array;
+  /** 32-byte Sui address used as the derivation path. */
+  readonly suiAddress: Uint8Array;
+  /** Bitcoin network (determines the bech32m address prefix). */
+  readonly network: BitcoinNetwork;
+}
 /**
  * Generates a Bitcoin P2TR deposit address for a Sui address.
  *
- * This is the main entry point for the address derivation pipeline. Given the
- * MPC master key and a Sui address, it produces the unique Bitcoin deposit
- * address where a user should send BTC in order to receive bridged tokens on
- * Sui.
- *
- * Combines {@link deriveChildPubkey} (child key derivation) and
- * {@link taprootScriptPathAddress} (taproot address construction) into a
- * single call.
+ * 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
+ * `hashi_types::bitcoin::taproot::taproot_address` byte-for-byte.
  *
- * The current devnet address scheme uses a single-key script path:
+ * The address scheme is:
  * ```text
- * tr(NUMS, pk(derive(H, d)))
+ * tr(NUMS, {multi_a(2, guardian, derive(mpc_master, sui_address)),
+ *           and_v(v:older(delay), pk(derive(mpc_master, sui_address)))})
  * ```
- * where `H` is the MPC master key and `d` is the depositor's Sui address.
  *
- * For mainnet the descriptor will include the guardian key:
- * `tr(NUMS, multi_a(2, guardian, derive(H, d)))` — not yet implemented here.
- *
- * @param mpcKeyCompressed - 33-byte SEC1 compressed secp256k1 MPC public key
- *   (the MPC master key, after arkworks-to-SEC1 conversion)
- * @param suiAddress - 32-byte Sui address
- * @param network - Bitcoin network (determines the bech32m address prefix)
  * @returns bech32m-encoded P2TR deposit address (e.g. `tb1p…` for signet)
  */
-declare function generateDepositAddress(mpcKeyCompressed: Uint8Array, suiAddress: Uint8Array, network: BitcoinNetwork): string;
+declare function generateDepositAddress({
+  mpcMasterCompressed,
+  guardianBtcXOnly,
+  suiAddress,
+  network
+}: DepositAddressInputs): string;
 /**
  * Decodes a bech32/bech32m SegWit Bitcoin address into a witness program.
  *
@@ -149,4 +188,4 @@ declare function bitcoinAddressToWitnessProgram(address: string, network: Bitcoi
  */
 declare function witnessProgramToAddress(program: Uint8Array, network: BitcoinNetwork): string;
 //#endregion
-export { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, taprootScriptPathAddress, witnessProgramToAddress };
+export { DepositAddressInputs, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress };

package/dist/bitcoin.mjs

@@ -13,35 +13,45 @@ import { concatBytes } from "@noble/hashes/utils.js";
 *
 * Hashi bridges Bitcoin and Sui by assigning each Sui address a unique Bitcoin
 * deposit address. When BTC is sent to that address, the Hashi MPC committee
-* detects the deposit and mints equivalent tokens on Sui.
+* and the Hashi guardian co-sign the withdrawal that spends it, and the bridge
+* mints equivalent tokens on Sui.
 *
 * The deposit address is a Pay-to-Taproot (P2TR / BIP-341) script-path address
-* whose spending condition is a single `OP_CHECKSIG` against a child public key
-* derived from the MPC committee's master key and the depositor's Sui 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:
 *
-* 1. **Fetch** the MPC master key from on-chain (`CommitteeSet.mpc_public_key`).
-*    The on-chain bytes use the arkworks compressed format (little-endian x +
-*    flag byte), so they must first be converted to SEC1 via
-*    {@link arkworksToSec1Compressed} — this is done automatically by the
-*    client's `view.mpcPublicKey()` method.
+* 1. **Fetch** the MPC master key from on-chain (`CommitteeSet.mpc_public_key`)
+*    and the guardian's BTC public key from the on-chain config
+*    (`guardian_btc_public_key`). The MPC bytes use the arkworks compressed
+*    format and must first be converted to SEC1 via
+*    {@link arkworksToSec1Compressed} — done automatically by the client's
+*    `view.mpcPublicKey()`. The guardian key is already in BIP-340 x-only form.
 *
-* 2. **Derive** a child key: `child = masterKey + HKDF-SHA3-256(x ‖ suiAddr) × G`
+* 2. **Derive** a child MPC key: `child = masterKey + HKDF-SHA3-256(x ‖ suiAddr) × G`
 *    (see {@link deriveChildPubkey}). This replicates the Rust function
 *    `fastcrypto_tbls::threshold_schnorr::key_derivation::derive_verifying_key`.
 *
-* 3. **Build** the taproot address: `tr(NUMS, 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 taprootScriptPathAddress}).
+* 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 `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));
@@ -53,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.
 *
@@ -127,39 +168,73 @@ function deriveChildPubkey(mpcKeyCompressed, suiAddress) {
 	return parentPoint.add(Point.BASE.multiply(tweakScalar)).toBytes(true).slice(1);
 }
 /**
-* Builds a P2TR script-path-only address: `tr(NUMS, pk(pubkey))`.
+* 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))})`.
 *
-* A BIP-341 taproot output has two spending paths: the *key path* (spend with
-* the internal key) and the *script path* (reveal and satisfy a script in the
-* Merkle tree). By using the NUMS (Nothing-Up-My-Sleeve) point as the internal
-* key — a point with no known discrete logarithm — the key path is provably
-* unspendable, forcing every spend through the script path.
+* 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 immediate-spend script the bridge's withdrawal path constructs
+* in `crates/hashi-types/src/bitcoin/taproot.rs`'s `compute_taproot_descriptor`.
 *
-* The script tree contains a single leaf: `<pubkey> OP_CHECKSIG`, meaning the
-* MPC committee must produce a valid Schnorr signature for `pubkey` to spend
-* the output. This is how the committee authorises withdrawals.
+* The leaf script is exactly 70 bytes:
+*
+* ```text
+* 0x20 ‖ guardian   (32)   // OP_PUSHBYTES_32 <pk1>
+* 0xAC                     // OP_CHECKSIG
+* 0x20 ‖ derived_mpc(32)   // OP_PUSHBYTES_32 <pk2>
+* 0xBA                     // OP_CHECKSIGADD
+* 0x52                     // OP_2 (push small int 2)
+* 0x9C                     // OP_NUMEQUAL
+* ```
+*
+* Note `0x52` (OP_2) — not `0x01 0x02` — because `rust-miniscript`'s `multi_a`
+* 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)
-* outputKey  = NUMS + tweak × G
+* 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
 * ```
 *
-* The resulting output key is encoded as a SegWit v1 witness program in a
-* bech32m address.
+* **Argument ordering is load-bearing.** Guardian first, derived-MPC second.
+* Swapping them produces a different (but real-looking) `tb1p…` whose
+* withdrawals the bridge cannot spend.
 *
-* @param pubkey - 32-byte x-only public key for the script leaf
+* @param guardianBtcXOnly - 32-byte BIP-340 x-only guardian BTC public key
+*   (from the on-chain `guardian_btc_public_key` config)
+* @param derivedMpcXOnly - 32-byte x-only public key for the MPC-derived child
+*   (output of {@link deriveChildPubkey})
 * @param network - Bitcoin network for the bech32m human-readable prefix
 * @returns bech32m-encoded P2TR address (e.g. `bc1p…`, `tb1p…`, `bcrt1p…`)
 */
-function taprootScriptPathAddress(pubkey, network) {
-	if (pubkey.length !== 32) throw new Error(`Expected 32-byte x-only pubkey, got ${pubkey.length}`);
-	const tapscript = new Uint8Array(34);
-	tapscript[0] = 32;
-	tapscript.set(pubkey, 1);
-	tapscript[33] = 172;
-	const tweakScalar = bytesToNumberBE(taggedHash("TapTweak", NUMS_KEY, taggedHash("TapLeaf", new Uint8Array([192, tapscript.length]), tapscript))) % CURVE_ORDER;
+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 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);
@@ -167,32 +242,21 @@ function taprootScriptPathAddress(pubkey, network) {
 /**
 * Generates a Bitcoin P2TR deposit address for a Sui address.
 *
-* This is the main entry point for the address derivation pipeline. Given the
-* MPC master key and a Sui address, it produces the unique Bitcoin deposit
-* address where a user should send BTC in order to receive bridged tokens on
-* Sui.
-*
-* Combines {@link deriveChildPubkey} (child key derivation) and
-* {@link taprootScriptPathAddress} (taproot address construction) into a
-* single call.
+* 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
+* `hashi_types::bitcoin::taproot::taproot_address` byte-for-byte.
 *
-* The current devnet address scheme uses a single-key script path:
+* The address scheme is:
 * ```text
-* tr(NUMS, pk(derive(H, d)))
+* tr(NUMS, {multi_a(2, guardian, derive(mpc_master, sui_address)),
+*           and_v(v:older(delay), pk(derive(mpc_master, sui_address)))})
 * ```
-* where `H` is the MPC master key and `d` is the depositor's Sui address.
 *
-* For mainnet the descriptor will include the guardian key:
-* `tr(NUMS, multi_a(2, guardian, derive(H, d)))` — not yet implemented here.
-*
-* @param mpcKeyCompressed - 33-byte SEC1 compressed secp256k1 MPC public key
-*   (the MPC master key, after arkworks-to-SEC1 conversion)
-* @param suiAddress - 32-byte Sui address
-* @param network - Bitcoin network (determines the bech32m address prefix)
 * @returns bech32m-encoded P2TR deposit address (e.g. `tb1p…` for signet)
 */
-function generateDepositAddress(mpcKeyCompressed, suiAddress, network) {
-	return taprootScriptPathAddress(deriveChildPubkey(mpcKeyCompressed, suiAddress), network);
+function generateDepositAddress({ mpcMasterCompressed, guardianBtcXOnly, suiAddress, network }) {
+	return twoOfTwoTaprootScriptPathAddress(guardianBtcXOnly, deriveChildPubkey(mpcMasterCompressed, suiAddress), network);
 }
 /**
 * Decodes a bech32/bech32m SegWit Bitcoin address into a witness program.
@@ -292,4 +356,4 @@ function witnessProgramToAddress(program, network) {
 }
 
 //#endregion
-export { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, taprootScriptPathAddress, witnessProgramToAddress };
+export { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress };

package/dist/client.d.mts

@@ -50,8 +50,21 @@ declare class HashiClient {
   /**
    * Generates a unique Bitcoin P2TR deposit address for a Sui address.
    *
-   * Fetches the MPC committee public key from on-chain, derives a child key
-   * using the Sui address, and builds a taproot script-path address.
+   * 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 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
+   * Hashi object, and only those two fields are parsed — an unrelated
+   * malformed config entry can't block deposit-address generation.
+   *
+   * Throws `HashiConfigError` if the deployment isn't guardian-provisioned
+   * yet (no `guardian_btc_public_key` on chain). The SDK refuses to fall
+   * back to a single-key address because the bridge validator rejects it.
    *
    * @example
    * ```ts

package/dist/client.mjs

@@ -6,13 +6,13 @@ import { WithdrawalRequest, WithdrawalTransaction } from "./contracts/hashi/with
 import { BitcoinState, BitcoinStateKey } from "./contracts/hashi/bitcoin_state.mjs";
 import { deposit } from "./contracts/hashi/deposit.mjs";
 import { cancelWithdrawal, requestWithdrawal } from "./contracts/hashi/withdraw.mjs";
-import { DUST_RELAY_MIN_VALUE, NETWORK_CONFIG } from "./constants.mjs";
+import { DUST_RELAY_MIN_VALUE, GUARDIAN_BTC_PUBLIC_KEY_LEN, GUARDIAN_PUBLIC_KEY_LEN, NETWORK_CONFIG } from "./constants.mjs";
 import { AmountBelowMinimumError, HashiConfigError, HashiFetchError, HashiPausedError, InvalidParamsError } from "./errors.mjs";
 import { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, generateDepositAddress } from "./bitcoin.mjs";
 import { getTxConfirmations, lookupAllVouts, lookupVout } from "./btc-rpc.mjs";
-import { assertHex32, entry, reverseTxidBytes } from "./util.mjs";
+import { assertHex32, configBytes, entry, reverseTxidBytes } from "./util.mjs";
 import { TypeTagSerializer, bcs } from "@mysten/sui/bcs";
-import { deriveDynamicFieldID, fromHex } from "@mysten/sui/utils";
+import { deriveDynamicFieldID, fromHex, normalizeSuiAddress } from "@mysten/sui/utils";
 import { base58 } from "@scure/base";
 import { Transaction, coinWithBalance } from "@mysten/sui/transactions";
 
@@ -176,26 +176,13 @@ var HashiClient = class {
 		};
 		this.view = {
 			mpcPublicKey: async () => {
-				const result = await Hashi.get({
+				return parseMpcPublicKey((await Hashi.get({
 					client: this.#client,
 					objectId: this.#hashiObjectId
-				});
-				const mpcKey = new Uint8Array(result.json.committee_set.mpc_public_key);
-				if (mpcKey.length === 0) throw new Error("MPC public key not available on-chain. Has the committee completed DKG?");
-				return arkworksToSec1Compressed(mpcKey);
+				})).json.committee_set.mpc_public_key);
 			},
 			all: async () => {
-				let result;
-				try {
-					result = await Hashi.get({
-						client: this.#client,
-						objectId: this.#hashiObjectId
-					});
-				} catch (cause) {
-					throw new HashiFetchError(`Failed to fetch Hashi shared object ${this.#hashiObjectId}.`, this.#hashiObjectId, { cause });
-				}
-				const contents = result.json?.config?.config?.contents;
-				if (!Array.isArray(contents)) throw new HashiFetchError(`Hashi object ${this.#hashiObjectId} returned an unexpected shape: config.config.contents is not an array.`, this.#hashiObjectId);
+				const { contents } = await this.#fetchHashiObject();
 				return this.#parseConfig(contents);
 			},
 			paused: async () => (await this.view.all()).paused,
@@ -455,8 +442,21 @@ var HashiClient = class {
 	/**
 	* Generates a unique Bitcoin P2TR deposit address for a Sui address.
 	*
-	* Fetches the MPC committee public key from on-chain, derives a child key
-	* using the Sui address, and builds a taproot script-path address.
+	* 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 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
+	* Hashi object, and only those two fields are parsed — an unrelated
+	* malformed config entry can't block deposit-address generation.
+	*
+	* Throws `HashiConfigError` if the deployment isn't guardian-provisioned
+	* yet (no `guardian_btc_public_key` on chain). The SDK refuses to fall
+	* back to a single-key address because the bridge validator rejects it.
 	*
 	* @example
 	* ```ts
@@ -466,7 +466,13 @@ var HashiClient = class {
 	* ```
 	*/
 	async generateDepositAddress({ suiAddress, bitcoinNetwork = this.#bitcoinNetwork }) {
-		return generateDepositAddress(await this.view.mpcPublicKey(), fromHex(suiAddress), bitcoinNetwork);
+		const { json, contents } = await this.#fetchHashiObject();
+		return generateDepositAddress({
+			mpcMasterCompressed: parseMpcPublicKey(json.committee_set.mpc_public_key),
+			guardianBtcXOnly: configBytes(contents, "guardian_btc_public_key", GUARDIAN_BTC_PUBLIC_KEY_LEN),
+			suiAddress: fromHex(normalizeSuiAddress(suiAddress)),
+			network: bitcoinNetwork
+		});
 	}
 	/**
 	* Submit one or more Bitcoin deposits for committee confirmation, batched
@@ -633,6 +639,22 @@ var HashiClient = class {
 		};
 		const bool = (key) => entry(contents, key, "Bool").Bool;
 		const addr = (key) => entry(contents, key, "Address").Address;
+		const optionalString = (key) => {
+			try {
+				return entry(contents, key, "String").String;
+			} catch (e) {
+				if (e instanceof HashiConfigError && e.actualVariant === void 0) return null;
+				throw e;
+			}
+		};
+		const optionalBytes = (key, expectedLen) => {
+			try {
+				return configBytes(contents, key, expectedLen);
+			} catch (e) {
+				if (e instanceof HashiConfigError && e.actualVariant === void 0) return null;
+				throw e;
+			}
+		};
 		const rawDepositMin = u64("bitcoin_deposit_minimum");
 		const rawWithdrawalMin = u64("bitcoin_withdrawal_minimum");
 		const bitcoinDepositMinimum = rawDepositMin < DUST_RELAY_MIN_VALUE ? DUST_RELAY_MIN_VALUE : rawDepositMin;
@@ -646,7 +668,10 @@ var HashiClient = class {
 			withdrawalCancellationCooldownMs: u64("withdrawal_cancellation_cooldown_ms"),
 			bitcoinDepositTimeDelayMs: u64("bitcoin_deposit_time_delay_ms"),
 			depositMinimum: bitcoinDepositMinimum,
-			worstCaseNetworkFee: bitcoinWithdrawalMinimum - DUST_RELAY_MIN_VALUE
+			worstCaseNetworkFee: bitcoinWithdrawalMinimum - DUST_RELAY_MIN_VALUE,
+			guardianUrl: optionalString("guardian_url"),
+			guardianPublicKey: optionalBytes("guardian_public_key", GUARDIAN_PUBLIC_KEY_LEN),
+			guardianBtcPublicKey: optionalBytes("guardian_btc_public_key", GUARDIAN_BTC_PUBLIC_KEY_LEN)
 		};
 	}
 	/**
@@ -696,6 +721,31 @@ var HashiClient = class {
 		return 0n;
 	}
 	/**
+	* Fetches the Hashi shared object once and returns its decoded `json`
+	* alongside the validated governance-config `contents` array. Wraps
+	* transport failures and unexpected shapes in `HashiFetchError`. Shared by
+	* `view.all()` and `generateDepositAddress` so a single round-trip serves
+	* both the committee key (from `json`) and the config reads (from
+	* `contents`).
+	*/
+	async #fetchHashiObject() {
+		let result;
+		try {
+			result = await Hashi.get({
+				client: this.#client,
+				objectId: this.#hashiObjectId
+			});
+		} catch (cause) {
+			throw new HashiFetchError(`Failed to fetch Hashi shared object ${this.#hashiObjectId}.`, this.#hashiObjectId, { cause });
+		}
+		const contents = result.json?.config?.config?.contents;
+		if (!Array.isArray(contents)) throw new HashiFetchError(`Hashi object ${this.#hashiObjectId} returned an unexpected shape: config.config.contents is not an array.`, this.#hashiObjectId);
+		return {
+			json: result.json,
+			contents
+		};
+	}
+	/**
 	* Fetches the `BitcoinState` dynamic field from the Hashi shared object.
 	* Returns the BCS-parsed struct whose nested Bag/Table IDs are used by
 	* `findUsedUtxos` and `transactionHistory`.
@@ -851,6 +901,16 @@ var HashiClient = class {
 		}
 	}
 };
+/**
+* Convert the on-chain `committee_set.mpc_public_key` (arkworks-compressed)
+* into a 33-byte SEC1 key. Throws `HashiConfigError` if DKG hasn't populated
+* it yet (empty vector).
+*/
+function parseMpcPublicKey(raw) {
+	const mpcKey = new Uint8Array(raw);
+	if (mpcKey.length === 0) throw HashiConfigError.missing("committee_set.mpc_public_key", "Bytes");
+	return arkworksToSec1Compressed(mpcKey);
+}
 function parseDepositHistoryItem(content, timeDelayMs) {
 	const parsed = DepositRequest.parse(content);
 	const approvalTimestampMs = parsed.approval_timestamp_ms === null ? null : BigInt(parsed.approval_timestamp_ms);

package/dist/constants.mjs

@@ -50,6 +50,16 @@ const NUMS_KEY = new Uint8Array([
 * `hashi::btc_config`.
 */
 const DUST_RELAY_MIN_VALUE = 546n;
+/**
+* Length of the Guardian's Ed25519 attestation public key, in bytes. Matches
+* `GUARDIAN_PUBLIC_KEY_LEN` in `hashi::config`.
+*/
+const GUARDIAN_PUBLIC_KEY_LEN = 32;
+/**
+* Length of the Guardian's BIP-340 x-only BTC public key, in bytes. Matches
+* `GUARDIAN_BTC_PUBLIC_KEY_LEN` in `hashi::config`.
+*/
+const GUARDIAN_BTC_PUBLIC_KEY_LEN = 32;
 const NETWORK_CONFIG = { devnet: {
 	hashiObjectId: "0x61f1acbf8dd79d284cb312853389747a55a158b1b12a68554afcade05dec5f40",
 	packageId: "0xc377616c626d73556cae080706acf37e862d24d26c690cc7be5a957f53fadf17",
@@ -57,4 +67,4 @@ const NETWORK_CONFIG = { devnet: {
 } };
 
 //#endregion
-export { DUST_RELAY_MIN_VALUE, NETWORK_CONFIG, NETWORK_HRP, NUMS_KEY };
+export { DUST_RELAY_MIN_VALUE, GUARDIAN_BTC_PUBLIC_KEY_LEN, GUARDIAN_PUBLIC_KEY_LEN, NETWORK_CONFIG, NETWORK_HRP, NUMS_KEY };

package/dist/contracts/hashi/utxo_pool.mjs

@@ -20,7 +20,8 @@ const UtxoRecord = new MoveStruct({
 	fields: {
 		utxo: Utxo,
 		produced_by: bcs.option(bcs.Address),
-		locked_by: bcs.option(bcs.Address)
+		locked_by: bcs.option(bcs.Address),
+		spent_epoch: bcs.option(bcs.u64())
 	}
 });
 const UtxoSpentEvent = new MoveStruct({

package/dist/contracts/hashi/withdraw.mjs

@@ -27,7 +27,8 @@ const WithdrawalSignedMessage = new MoveStruct({
 	fields: {
 		withdrawal_id: bcs.Address,
 		request_ids: bcs.vector(bcs.Address),
-		signatures: bcs.vector(bcs.vector(bcs.u8()))
+		signatures: bcs.vector(bcs.vector(bcs.u8())),
+		guardian_signatures: bcs.vector(bcs.vector(bcs.u8()))
 	}
 });
 const WithdrawalConfirmationMessage = new MoveStruct({

package/dist/contracts/hashi/withdrawal_queue.mjs

@@ -61,6 +61,7 @@ const WithdrawalTransaction = new MoveStruct({
 		timestamp_ms: bcs.u64(),
 		randomness: bcs.vector(bcs.u8()),
 		signatures: bcs.option(bcs.vector(bcs.vector(bcs.u8()))),
+		guardian_signatures: bcs.option(bcs.vector(bcs.vector(bcs.u8()))),
 		presig_start_index: bcs.u64(),
 		epoch: bcs.u64()
 	}
@@ -105,7 +106,16 @@ const WithdrawalSignedEvent = new MoveStruct({
 	fields: {
 		withdrawal_txn_id: bcs.Address,
 		request_ids: bcs.vector(bcs.Address),
-		signatures: bcs.vector(bcs.vector(bcs.u8()))
+		signatures: bcs.vector(bcs.vector(bcs.u8())),
+		guardian_signatures: bcs.vector(bcs.vector(bcs.u8()))
+	}
+});
+const WithdrawalPresigsReassignedEvent = new MoveStruct({
+	name: `${$moduleName}::WithdrawalPresigsReassignedEvent`,
+	fields: {
+		withdrawal_txn_id: bcs.Address,
+		epoch: bcs.u64(),
+		presig_start_index: bcs.u64()
 	}
 });
 const WithdrawalConfirmedEvent = new MoveStruct({

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { BitcoinNetwork, CancelWithdrawalParams, DepositFees, DepositHistoryItem, DepositInfo, DepositParams, DepositStatus, GovernanceConfig, HashiClientOptions, HbtcBalance, NetworkConfig, SuiNetwork, TransactionHistoryItem, UtxoId, UtxoLookupResult, UtxoOutput, UtxoUsageResult, WaitOptions, WithdrawalFees, WithdrawalHistoryItem, WithdrawalInfo, WithdrawalParams, WithdrawalStatus } from "./types.mjs";
 import { HashiClient, hashi } from "./client.mjs";
 import { AmountBelowMinimumError, AmountViolation, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError } from "./errors.mjs";
-import { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, taprootScriptPathAddress, witnessProgramToAddress } from "./bitcoin.mjs";
-export { AmountBelowMinimumError, type AmountViolation, type BitcoinNetwork, type CancelWithdrawalParams, type DepositFees, type DepositHistoryItem, type DepositInfo, type DepositParams, type DepositStatus, type GovernanceConfig, HashiClient, type HashiClientOptions, HashiConfigError, HashiFetchError, HashiPausedError, type HbtcBalance, type InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError, type NetworkConfig, type SuiNetwork, type TransactionHistoryItem, type UtxoId, type UtxoLookupResult, type UtxoOutput, type UtxoUsageResult, type WaitOptions, type WithdrawalFees, type WithdrawalHistoryItem, type WithdrawalInfo, type WithdrawalParams, type WithdrawalStatus, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, hashi, taprootScriptPathAddress, witnessProgramToAddress };
+import { DepositAddressInputs, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress } from "./bitcoin.mjs";
+export { AmountBelowMinimumError, type AmountViolation, type BitcoinNetwork, type CancelWithdrawalParams, type DepositAddressInputs, type DepositFees, type DepositHistoryItem, type DepositInfo, type DepositParams, type DepositStatus, type GovernanceConfig, HashiClient, type HashiClientOptions, HashiConfigError, HashiFetchError, HashiPausedError, type HbtcBalance, type InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError, type NetworkConfig, type SuiNetwork, type TransactionHistoryItem, type UtxoId, type UtxoLookupResult, type UtxoOutput, type UtxoUsageResult, type WaitOptions, type WithdrawalFees, type WithdrawalHistoryItem, type WithdrawalInfo, type WithdrawalParams, type WithdrawalStatus, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, hashi, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { AmountBelowMinimumError, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressError, InvalidParamsError } from "./errors.mjs";
-import { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, taprootScriptPathAddress, witnessProgramToAddress } from "./bitcoin.mjs";
+import { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress } from "./bitcoin.mjs";
 import { HashiClient, hashi } from "./client.mjs";
 
-export { AmountBelowMinimumError, HashiClient, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressError, InvalidParamsError, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, hashi, taprootScriptPathAddress, witnessProgramToAddress };
+export { AmountBelowMinimumError, HashiClient, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressError, InvalidParamsError, arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, deriveChildPubkey, generateDepositAddress, hashi, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress };

package/dist/types.d.mts

@@ -28,6 +28,11 @@ interface HashiClientOptions<Name = "HashiClient"> {
  * state. `depositMinimum` is a Move-side alias of `bitcoinDepositMinimum`;
  * `worstCaseNetworkFee` is derived as `bitcoinWithdrawalMinimum - 546` (the
  * dust relay floor) and is always ≥ 1.
+ *
+ * The three `guardian*` fields are `null` on deployments where the guardian
+ * config hasn't been written yet (pre-feature chains or in-flight rollouts).
+ * `guardianBtcPublicKey` is required for {@link HashiClient.generateDepositAddress}
+ * to succeed.
  */
 interface GovernanceConfig {
   readonly paused: boolean;
@@ -39,6 +44,19 @@ interface GovernanceConfig {
   readonly bitcoinDepositTimeDelayMs: bigint;
   readonly depositMinimum: bigint;
   readonly worstCaseNetworkFee: bigint;
+  /** Guardian gRPC/HTTP endpoint from on-chain config. `null` if unset. */
+  readonly guardianUrl: string | null;
+  /**
+   * Guardian's Ed25519 attestation key (32 bytes), used to verify signed
+   * `GetGuardianInfo` responses. `null` if unset.
+   */
+  readonly guardianPublicKey: Uint8Array | null;
+  /**
+   * Guardian's BIP-340 x-only secp256k1 BTC public key (32 bytes), the
+   * `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;
 }
 /**
  * A single UTXO output within a Bitcoin transaction used to fund a deposit.

package/dist/util.mjs

@@ -45,6 +45,16 @@ function entry(contents, key, expectedVariant) {
 	if (e.value.$kind !== expectedVariant) throw HashiConfigError.wrongVariant(key, expectedVariant, e.value.$kind);
 	return e.value;
 }
+/**
+* Read a `Bytes` config entry and assert its byte length. Throws
+* `HashiConfigError` if the key is missing, holds a non-`Bytes` variant, or
+* has the wrong length.
+*/
+function configBytes(contents, key, expectedLen) {
+	const v = entry(contents, key, "Bytes");
+	if (v.Bytes.length !== expectedLen) throw HashiConfigError.malformedPayload(key, "Bytes", `expected ${expectedLen} bytes, got ${v.Bytes.length}`);
+	return new Uint8Array(v.Bytes);
+}
 
 //#endregion
-export { assertHex32, entry, reverseTxidBytes };
+export { assertHex32, configBytes, entry, reverseTxidBytes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten-incubation/hashi",
-  "version": "0.2.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>",
@@ -59,7 +59,7 @@
     "test": "vitest --project=unit",
     "test:integration": "vitest run --project=integration",
     "coverage": "vitest run --project=unit --coverage",
-    "codegen": "sui-ts-codegen generate",
+    "codegen": "sui-ts-codegen generate && prettier --ignore-path /dev/null --tab-width 4 --print-width 100 --write 'src/contracts/**/*.ts'",
     "format": "prettier --write \"**/*.{ts,json,md}\""
   }
 }