@mysten-incubation/hashi 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mysten-incubation/hashi
 
+## 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
+
+- 5f9f592: Surface deposit time delay: add `bitcoinDepositTimeDelayMs` to `GovernanceConfig`, `approvalTimestampMs` and `confirmableAtMs` to `DepositInfo`, and `confirmableAtMs` to `DepositHistoryItem`
+
 ## 0.1.1
 
 ### Patch Changes

package/dist/bitcoin.d.mts

@@ -56,61 +56,93 @@ 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 a 2-of-2 P2TR script-path-only address:
+ * `tr(NUMS, multi_a(2, guardian, 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 script the bridge's withdrawal path constructs in
+ * `crates/hashi-types/src/guardian/bitcoin_utils.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 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
+ * leafHash  = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(script) ‖ script)
+ * tweak     = tagged_hash("TapTweak", NUMS ‖ leafHash)
+ * 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
+ * `bitcoin_utils::two_of_two_taproot_script_path_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)))
  * ```
- * 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 +181,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,30 +13,39 @@ 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.
+* 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 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))`
+*    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`.
+*
 * @see https://mystenlabs.github.io/hashi/design/address-scheme.html
 */
 const Point = secp256k1.Point;
@@ -127,38 +136,61 @@ 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 a 2-of-2 P2TR script-path-only address:
+* `tr(NUMS, multi_a(2, guardian, 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`.
+*
+* The leaf script is exactly 70 bytes:
 *
-* 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.
+* ```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
+* ```
 *
-* 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.
+* 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 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
+* leafHash  = tagged_hash("TapLeaf",  0xC0 ‖ compact_size(script) ‖ script)
+* tweak     = tagged_hash("TapTweak", NUMS ‖ leafHash)
+* 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);
+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(pubkey, 1);
+	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 outputKey = NUMS_POINT.add(Point.BASE.multiply(tweakScalar)).toBytes(true).slice(1);
 	const words = [1, ...bech32m.toWords(outputKey)];
@@ -167,32 +199,20 @@ 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
+* `bitcoin_utils::two_of_two_taproot_script_path_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)))
 * ```
-* 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 +312,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 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.
+   *
+   * 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,
@@ -269,12 +256,17 @@ var HashiClient = class {
 				if (!depositEvent?.json) return null;
 				const parsed = depositEvent.json;
 				let status = "unknown";
+				let approvalTimestampMs = null;
+				let confirmableAtMs = null;
 				try {
-					await DepositRequest.get({
+					const reqObj = await DepositRequest.get({
 						client: this.#client,
 						objectId: parsed.request_id
 					});
-					const requestsBagId = (await this.#fetchBitcoinState()).deposit_queue.requests.id;
+					if (reqObj.json.approval_timestamp_ms != null) approvalTimestampMs = BigInt(reqObj.json.approval_timestamp_ms);
+					const [btcState, config$1] = await Promise.all([this.#fetchBitcoinState(), this.view.all().catch(() => null)]);
+					if (approvalTimestampMs !== null && config$1) confirmableAtMs = approvalTimestampMs + config$1.bitcoinDepositTimeDelayMs;
+					const requestsBagId = btcState.deposit_queue.requests.id;
 					status = (await this.#client.core.getDynamicField({
 						parentId: requestsBagId,
 						name: {
@@ -293,6 +285,8 @@ var HashiClient = class {
 					btcTxid: reverseTxidBytes(parsed.utxo_id.txid),
 					btcVout: parsed.utxo_id.vout,
 					timestampMs: BigInt(parsed.timestamp_ms),
+					approvalTimestampMs,
+					confirmableAtMs,
 					status,
 					suiTxDigest
 				};
@@ -393,7 +387,7 @@ var HashiClient = class {
 				};
 			},
 			transactionHistory: async (suiAddress) => {
-				const btcState = await this.#fetchBitcoinState();
+				const [btcState, timeDelayMs] = await Promise.all([this.#fetchBitcoinState(), this.view.all().then((c) => c.bitcoinDepositTimeDelayMs, () => null)]);
 				const confirmedIds = /* @__PURE__ */ new Set();
 				const items = [];
 				const userBagId = await this.#fetchUserRequestsBagId(btcState.user_requests.id, suiAddress);
@@ -401,7 +395,7 @@ var HashiClient = class {
 					const requestIds = await this.#listAllDynamicFieldAddressKeys(userBagId);
 					if (requestIds.length > 0) {
 						const objects = await this.#batchGetObjects(requestIds, { content: true });
-						const classified = this.#classifyRequestObjects(objects);
+						const classified = this.#classifyRequestObjects(objects, timeDelayMs);
 						items.push(...classified.items);
 						await this.#populateWithdrawalBtcTxids(items, classified.withdrawalTxnLookups);
 						for (const id of requestIds) confirmedIds.add(id);
@@ -412,7 +406,7 @@ var HashiClient = class {
 					const pendingIds = (await this.#queryEventRequestIds(suiAddress, depositEventType)).filter((id) => !confirmedIds.has(id));
 					if (pendingIds.length > 0) {
 						const objects = await this.#batchGetObjects(pendingIds, { content: true });
-						const classified = this.#classifyRequestObjects(objects);
+						const classified = this.#classifyRequestObjects(objects, timeDelayMs);
 						items.push(...classified.items);
 					}
 				} catch {}
@@ -448,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 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.
+	*
+	* 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
@@ -459,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
@@ -626,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;
@@ -637,8 +666,12 @@ var HashiClient = class {
 			bitcoinWithdrawalMinimum,
 			bitcoinConfirmationThreshold: u64("bitcoin_confirmation_threshold"),
 			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)
 		};
 	}
 	/**
@@ -688,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`.
@@ -803,14 +861,14 @@ var HashiClient = class {
 	* items plus the indices that need a follow-up `WithdrawalTransaction`
 	* fetch to populate `btcTxid`.
 	*/
-	#classifyRequestObjects(objects) {
+	#classifyRequestObjects(objects, timeDelayMs) {
 		const items = [];
 		const withdrawalTxnLookups = [];
 		const depositRequestType = `${this.#packageId}::deposit_queue::DepositRequest`;
 		const withdrawalRequestType = `${this.#packageId}::withdrawal_queue::WithdrawalRequest`;
 		for (const obj of objects) {
 			if (obj instanceof Error) continue;
-			if (obj.type === depositRequestType) items.push(parseDepositHistoryItem(obj.content));
+			if (obj.type === depositRequestType) items.push(parseDepositHistoryItem(obj.content, timeDelayMs));
 			else if (obj.type === withdrawalRequestType) {
 				const item = parseWithdrawalHistoryItem(obj.content);
 				items.push(item);
@@ -843,8 +901,19 @@ var HashiClient = class {
 		}
 	}
 };
-function parseDepositHistoryItem(content) {
+/**
+* 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);
 	return {
 		kind: "deposit",
 		requestId: parsed.id,
@@ -855,7 +924,8 @@ function parseDepositHistoryItem(content) {
 		btcTxid: reverseTxidBytes(parsed.utxo.id.txid),
 		btcVout: parsed.utxo.id.vout,
 		approved: parsed.approval_cert !== null,
-		approvalTimestampMs: parsed.approval_timestamp_ms === null ? null : BigInt(parsed.approval_timestamp_ms)
+		approvalTimestampMs,
+		confirmableAtMs: approvalTimestampMs !== null && timeDelayMs !== null ? approvalTimestampMs + timeDelayMs : null
 	};
 }
 function parseWithdrawalHistoryItem(content) {

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;
@@ -36,8 +41,22 @@ interface GovernanceConfig {
   readonly bitcoinWithdrawalMinimum: bigint;
   readonly bitcoinConfirmationThreshold: bigint;
   readonly withdrawalCancellationCooldownMs: bigint;
+  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 on-chain 2-of-2 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.
@@ -120,6 +139,8 @@ interface DepositHistoryItem {
   /** `true` once the committee has approved the deposit. */
   readonly approved: boolean;
   readonly approvalTimestampMs: bigint | null;
+  /** Earliest wall-clock time (ms since epoch) at which the deposit can be confirmed. `null` until approved. */
+  readonly confirmableAtMs: bigint | null;
 }
 type WithdrawalStatus = "Requested" | "Approved" | "Processing" | "Signed" | "Confirmed";
 interface WithdrawalHistoryItem {
@@ -157,6 +178,10 @@ interface DepositInfo {
   readonly btcVout: number;
   /** Request timestamp (ms since epoch). */
   readonly timestampMs: bigint;
+  /** Timestamp (ms since epoch) when the committee approved this deposit. `null` if not yet approved. */
+  readonly approvalTimestampMs: bigint | null;
+  /** Earliest wall-clock time (ms since epoch) at which the deposit can be confirmed. `null` until approved or if the config could not be read. */
+  readonly confirmableAtMs: bigint | null;
   /** Current deposit status. */
   readonly status: DepositStatus;
   /** Sui transaction digest that created this request. */

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.1.1",
+  "version": "0.3.0",
   "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}\""
   }
 }