@mysten-incubation/hashi 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mysten-incubation/hashi
 
+## 0.4.0
+
+### Minor Changes
+
+- 874ec08: feat: add a `client.hashi.guardian.*` namespace (`info`, `limiterStatus`, `canWithdraw`) that reads the guardian's rate-limiter headroom from its read-only `/info` endpoint, resolving the guardian URL from `guardianUrl`, a `guardianInfoProvider`, or the on-chain `guardian_url` config
+
+### Patch Changes
+
+- 8f7606f: Track the redeployed devnet contracts: regenerate bindings against hashi's `testnet` tip (`0e67b619`) (`config_value::Value` gained `U128`/`U256`, shifting the BCS tags the SDK decodes the on-chain config with), follow the `DepositRequested`/`WithdrawalRequested` event renames and request-object field renames, and point `NETWORK_CONFIG.devnet` at the new package and Hashi object.
+
+## 0.3.1
+
+### Patch Changes
+
+- 0af8dfa: Derive Bitcoin deposit addresses with Hashi's delayed MPC recovery taproot leaf.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -45,7 +45,7 @@ await client.hashi.deposit({
 });
 ```
 
-End-user actions only: **deposit**, **request withdrawal**, **cancel withdrawal**.
+End-user actions only: **deposit**, **request withdrawal**, **cancel withdrawal**. An optional `client.hashi.guardian.*` namespace reads the guardian's rate-limiter headroom (`limiterStatus`, `canWithdraw`) — see the root README.
 
 ## Documentation
 

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

@@ -1,5 +1,5 @@
 import { RawTransactionArgument } from "./contracts/utils/index.mjs";
-import { BitcoinNetwork, CancelWithdrawalParams, DepositFees, DepositInfo, DepositParams, GovernanceConfig, HashiClientOptions, HbtcBalance, SuiNetwork, TransactionHistoryItem, UtxoId, UtxoLookupResult, UtxoUsageResult, WaitOptions, WithdrawalFees, WithdrawalInfo, WithdrawalParams } from "./types.mjs";
+import { BitcoinNetwork, CancelWithdrawalParams, DepositFees, DepositInfo, DepositParams, GovernanceConfig, GuardianInfoProvider, GuardianLimiterSnapshot, GuardianWithdrawCheck, HashiClientOptions, HbtcBalance, RawGuardianInfo, SuiNetwork, TransactionHistoryItem, UtxoId, UtxoLookupResult, UtxoUsageResult, WaitOptions, WithdrawalFees, WithdrawalInfo, WithdrawalParams } from "./types.mjs";
 import * as _mysten_sui_transactions0 from "@mysten/sui/transactions";
 import { Transaction } from "@mysten/sui/transactions";
 import { ClientWithCoreApi, SuiClientTypes } from "@mysten/sui/client";
@@ -37,7 +37,9 @@ declare class HashiClient {
     packageId,
     bitcoinNetwork,
     btcRpcUrl,
-    graphqlUrl
+    graphqlUrl,
+    guardianUrl,
+    guardianInfoProvider
   }: {
     client: ClientWithCoreApi;
     network: SuiNetwork;
@@ -46,16 +48,18 @@ declare class HashiClient {
     bitcoinNetwork?: BitcoinNetwork;
     btcRpcUrl?: string;
     graphqlUrl?: string;
+    guardianUrl?: string;
+    guardianInfoProvider?: GuardianInfoProvider;
   });
   /**
    * Generates a unique Bitcoin P2TR deposit address for a Sui 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.
+   * 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
@@ -85,7 +89,7 @@ declare class HashiClient {
    * into a single Sui PTB. Signs with `signer` and submits, returning the
    * execution result (`$kind: "Transaction" | "FailedTransaction"`). The
    * result includes `effects` and `events` so callers can confirm
-   * `DepositRequestedEvent` without an extra round-trip.
+   * `DepositRequested` without an extra round-trip.
    *
    * The method runs three preflight stages before signing:
    *
@@ -124,7 +128,7 @@ declare class HashiClient {
    * from the signer's balance and enqueues a request for the committee to
    * send `amountSats` to `bitcoinAddress` on the Bitcoin network. Signs
    * with `signer` and submits, returning the execution result including
-   * `effects` and `events` (`WithdrawalRequestedEvent`).
+   * `effects` and `events` (`WithdrawalRequested`).
    *
    * The method runs three preflight stages before signing:
    *
@@ -331,7 +335,7 @@ declare class HashiClient {
     /**
      * Get the status and details of a deposit by its Sui transaction digest.
      *
-     * Fetches the `DepositRequestedEvent` from the transaction, extracts the
+     * Fetches the `DepositRequested` event from the transaction, extracts the
      * request ID, then probes on-chain state to determine whether the deposit
      * is pending (still in `requests` ObjectBag), confirmed (object exists
      * but not in requests), or expired (object destroyed).
@@ -340,7 +344,7 @@ declare class HashiClient {
     /**
      * Get the status and details of a withdrawal by its Sui transaction digest.
      *
-     * Fetches the `WithdrawalRequestedEvent` from the transaction, extracts the
+     * Fetches the `WithdrawalRequested` event from the transaction, extracts the
      * request ID, then reads the `WithdrawalRequest` object to determine the
      * current lifecycle state. If a `WithdrawalTransaction` is linked, its
      * Bitcoin txid is populated.
@@ -361,7 +365,7 @@ declare class HashiClient {
      * Fetch the unified transaction history (deposits + withdrawals) for
      * a Sui address. Confirmed requests come from the on-chain
      * `user_requests` index; in-flight deposits are discovered via
-     * GraphQL `DepositRequestedEvent` queries (indexed by sender).
+     * GraphQL `DepositRequested` event queries (indexed by sender).
      */
     transactionHistory: (suiAddress: string) => Promise<TransactionHistoryItem[]>;
   };
@@ -396,6 +400,28 @@ declare class HashiClient {
      */
     confirmations: (txid: string) => Promise<number>;
   };
+  guardian: {
+    /**
+     * Fetch the guardian's curated `/info` (identity + limiter). `limiter`
+     * is `null` when the guardian is not yet provisioned/activated; this
+     * method never throws for that state, so it can detect an uninitialized
+     * guardian without a try/catch.
+     */
+    info: () => Promise<RawGuardianInfo>;
+    /**
+     * Fetch the limiter and compute derived fields: capacity projected to
+     * now, bucket fill percentage, and the refill-to-full ETA. Throws
+     * `HashiGuardianError` (`code: "not-initialized"`) if the guardian has
+     * no limiter yet.
+     */
+    limiterStatus: () => Promise<GuardianLimiterSnapshot>;
+    /**
+     * Check whether the guardian can sign a withdrawal of `amountSats` right
+     * now, with an estimated wait if not. Throws `HashiGuardianError`
+     * (`code: "not-initialized"`) if the guardian has no limiter yet.
+     */
+    canWithdraw: (amountSats: bigint) => Promise<GuardianWithdrawCheck>;
+  };
 }
 //#endregion
 export { HashiClient, hashi };

package/dist/client.mjs

@@ -7,9 +7,10 @@ import { BitcoinState, BitcoinStateKey } from "./contracts/hashi/bitcoin_state.m
 import { deposit } from "./contracts/hashi/deposit.mjs";
 import { cancelWithdrawal, requestWithdrawal } from "./contracts/hashi/withdraw.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 { AmountBelowMinimumError, HashiConfigError, HashiFetchError, HashiGuardianError, HashiPausedError, InvalidParamsError } from "./errors.mjs";
 import { arkworksToSec1Compressed, bitcoinAddressToWitnessProgram, generateDepositAddress } from "./bitcoin.mjs";
 import { getTxConfirmations, lookupAllVouts, lookupVout } from "./btc-rpc.mjs";
+import { estimateWaitSecs, fetchGuardianInfo, projectCapacity } from "./guardian.mjs";
 import { assertHex32, configBytes, entry, reverseTxidBytes } from "./util.mjs";
 import { TypeTagSerializer, bcs } from "@mysten/sui/bcs";
 import { deriveDynamicFieldID, fromHex, normalizeSuiAddress } from "@mysten/sui/utils";
@@ -90,7 +91,10 @@ var HashiClient = class {
 	#bitcoinNetwork;
 	#btcRpcUrl;
 	#graphqlUrl;
-	constructor({ client, network, hashiObjectId, packageId, bitcoinNetwork, btcRpcUrl, graphqlUrl }) {
+	#guardianUrl;
+	#guardianInfoProvider;
+	#resolvedGuardianUrl;
+	constructor({ client, network, hashiObjectId, packageId, bitcoinNetwork, btcRpcUrl, graphqlUrl, guardianUrl, guardianInfoProvider }) {
 		this.tx = {
 			deposit: (params) => {
 				const tx = new Transaction();
@@ -252,7 +256,7 @@ var HashiClient = class {
 				});
 				const txData = txResult.Transaction ?? txResult.FailedTransaction;
 				if (!txData?.events) return null;
-				const depositEvent = txData.events.find((e) => e.eventType.includes("::deposit::DepositRequestedEvent"));
+				const depositEvent = txData.events.find((e) => e.eventType.includes("::deposit::DepositRequested"));
 				if (!depositEvent?.json) return null;
 				const parsed = depositEvent.json;
 				let status = "unknown";
@@ -263,7 +267,7 @@ var HashiClient = class {
 						client: this.#client,
 						objectId: parsed.request_id
 					});
-					if (reqObj.json.approval_timestamp_ms != null) approvalTimestampMs = BigInt(reqObj.json.approval_timestamp_ms);
+					if (reqObj.json.approved_timestamp_ms != null) approvalTimestampMs = BigInt(reqObj.json.approved_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;
@@ -298,7 +302,7 @@ var HashiClient = class {
 				});
 				const txData = txResult.Transaction ?? txResult.FailedTransaction;
 				if (!txData?.events) return null;
-				const withdrawEvent = txData.events.find((e) => e.eventType.includes("::withdrawal_queue::WithdrawalRequestedEvent"));
+				const withdrawEvent = txData.events.find((e) => e.eventType.includes("::withdrawal_queue::WithdrawalRequested"));
 				if (!withdrawEvent?.json) return null;
 				const parsed = withdrawEvent.json;
 				let status = "Requested";
@@ -402,7 +406,7 @@ var HashiClient = class {
 					}
 				}
 				try {
-					const depositEventType = `${this.#packageId}::deposit::DepositRequestedEvent`;
+					const depositEventType = `${this.#packageId}::deposit::DepositRequested`;
 					const pendingIds = (await this.#queryEventRequestIds(suiAddress, depositEventType)).filter((id) => !confirmedIds.has(id));
 					if (pendingIds.length > 0) {
 						const objects = await this.#batchGetObjects(pendingIds, { content: true });
@@ -428,6 +432,38 @@ var HashiClient = class {
 				return getTxConfirmations(this.#btcRpcUrl, txid);
 			}
 		};
+		this.guardian = {
+			info: async () => {
+				return (await this.#resolveGuardianProvider())();
+			},
+			limiterStatus: async () => {
+				const { state, config: config$1 } = this.#requireLimiter(await this.guardian.info());
+				const nowSecs = BigInt(Math.floor(Date.now() / 1e3));
+				const availableNowSats = projectCapacity(config$1, state, nowSecs);
+				const max = config$1.maxBucketCapacitySats;
+				const bucketFillPercent = max > 0n ? Number(availableNowSats) / Number(max) * 100 : 0;
+				let fullAtSecs = null;
+				if (availableNowSats < max && config$1.refillRateSatsPerSec > 0n) fullAtSecs = nowSecs + (max - availableNowSats + config$1.refillRateSatsPerSec - 1n) / config$1.refillRateSatsPerSec;
+				return {
+					state,
+					config: config$1,
+					availableNowSats,
+					bucketFillPercent,
+					fullAtSecs
+				};
+			},
+			canWithdraw: async (amountSats) => {
+				const { state, config: config$1 } = this.#requireLimiter(await this.guardian.info());
+				const nowSecs = BigInt(Math.floor(Date.now() / 1e3));
+				const availableNowSats = projectCapacity(config$1, state, nowSecs);
+				const estimatedWaitSecs = estimateWaitSecs(config$1, state, amountSats, nowSecs);
+				return {
+					allowed: availableNowSats >= amountSats,
+					availableNowSats,
+					estimatedWaitSecs
+				};
+			}
+		};
 		const config = NETWORK_CONFIG[network];
 		const resolvedObjectId = hashiObjectId ?? config?.hashiObjectId;
 		const resolvedPackageId = packageId ?? config?.packageId;
@@ -438,16 +474,18 @@ var HashiClient = class {
 		this.#bitcoinNetwork = bitcoinNetwork ?? config?.bitcoinNetwork ?? "testnet";
 		this.#btcRpcUrl = btcRpcUrl;
 		this.#graphqlUrl = graphqlUrl ?? defaultGraphqlUrl(network);
+		this.#guardianUrl = guardianUrl;
+		this.#guardianInfoProvider = guardianInfoProvider;
 	}
 	/**
 	* Generates a unique Bitcoin P2TR deposit address for a Sui 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.
+	* 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
@@ -479,7 +517,7 @@ var HashiClient = class {
 	* into a single Sui PTB. Signs with `signer` and submits, returning the
 	* execution result (`$kind: "Transaction" | "FailedTransaction"`). The
 	* result includes `effects` and `events` so callers can confirm
-	* `DepositRequestedEvent` without an extra round-trip.
+	* `DepositRequested` without an extra round-trip.
 	*
 	* The method runs three preflight stages before signing:
 	*
@@ -530,7 +568,7 @@ var HashiClient = class {
 	* from the signer's balance and enqueues a request for the committee to
 	* send `amountSats` to `bitcoinAddress` on the Bitcoin network. Signs
 	* with `signer` and submits, returning the execution result including
-	* `effects` and `events` (`WithdrawalRequestedEvent`).
+	* `effects` and `events` (`WithdrawalRequested`).
 	*
 	* The method runs three preflight stages before signing:
 	*
@@ -705,6 +743,43 @@ var HashiClient = class {
 	#requireBtcRpc() {
 		if (!this.#btcRpcUrl) throw new Error("btcRpcUrl is required for Bitcoin RPC operations. Pass it in HashiClientOptions.");
 	}
+	#requireLimiter(info) {
+		if (info.limiter === null) throw new HashiGuardianError({
+			message: "Guardian rate limiter is not initialized (limiter is null).",
+			code: "not-initialized"
+		});
+		return info.limiter;
+	}
+	async #resolveGuardianProvider() {
+		if (this.#guardianInfoProvider) return this.#guardianInfoProvider;
+		const url = this.#guardianUrl || await this.#resolveOnChainGuardianUrl();
+		if (!url) throw new HashiGuardianError({
+			message: "Guardian URL is not configured. Pass `guardianUrl` or `guardianInfoProvider` to hashi({...}), or set `guardian_url` in the on-chain config.",
+			code: "not-configured"
+		});
+		return () => fetchGuardianInfo(url);
+	}
+	/**
+	* Resolve the guardian origin from the on-chain `guardian_url`, caching only
+	* a found URL. `guardian_url` is absent until launch (`finish_publish`
+	* publishes it), so a missing value is left uncached and each call re-reads
+	* the chain — a client created before launch starts working once the URL is
+	* published, rather than caching the absence forever (mirrors the node's
+	* lazy `guardian_client()` resolution). Returns `undefined` while unresolved.
+	*/
+	async #resolveOnChainGuardianUrl() {
+		if (this.#resolvedGuardianUrl) return this.#resolvedGuardianUrl;
+		let onChain;
+		try {
+			onChain = (await this.view.all()).guardianUrl;
+		} catch (cause) {
+			throw new HashiGuardianError({
+				message: "Could not read the on-chain guardian_url config. Pass `guardianUrl` or `guardianInfoProvider` to bypass the on-chain read.",
+				code: "not-configured"
+			}, { cause });
+		}
+		return this.#resolvedGuardianUrl = onChain || void 0;
+	}
 	async #estimateGas(tx) {
 		try {
 			const result = await this.#client.core.simulateTransaction({
@@ -913,12 +988,12 @@ function parseMpcPublicKey(raw) {
 }
 function parseDepositHistoryItem(content, timeDelayMs) {
 	const parsed = DepositRequest.parse(content);
-	const approvalTimestampMs = parsed.approval_timestamp_ms === null ? null : BigInt(parsed.approval_timestamp_ms);
+	const approvalTimestampMs = parsed.approved_timestamp_ms === null ? null : BigInt(parsed.approved_timestamp_ms);
 	return {
 		kind: "deposit",
 		requestId: parsed.id,
 		sender: parsed.sender,
-		timestampMs: BigInt(parsed.timestamp_ms),
+		timestampMs: BigInt(parsed.created_timestamp_ms),
 		suiTxDigest: base58.encode(new Uint8Array(parsed.sui_tx_digest)),
 		amountSats: BigInt(parsed.utxo.amount),
 		btcTxid: reverseTxidBytes(parsed.utxo.id.txid),
@@ -936,7 +1011,7 @@ function parseWithdrawalHistoryItem(content) {
 		sender: parsed.sender,
 		btcAmountSats: BigInt(parsed.btc_amount),
 		bitcoinAddress: new Uint8Array(parsed.bitcoin_address),
-		timestampMs: BigInt(parsed.timestamp_ms),
+		timestampMs: BigInt(parsed.created_timestamp_ms),
 		suiTxDigest: base58.encode(new Uint8Array(parsed.sui_tx_digest)),
 		status: parsed.status.$kind,
 		withdrawalTxnId: parsed.withdrawal_txn_id ?? null,

package/dist/constants.mjs

@@ -61,8 +61,8 @@ const GUARDIAN_PUBLIC_KEY_LEN = 32;
 */
 const GUARDIAN_BTC_PUBLIC_KEY_LEN = 32;
 const NETWORK_CONFIG = { devnet: {
-	hashiObjectId: "0x61f1acbf8dd79d284cb312853389747a55a158b1b12a68554afcade05dec5f40",
-	packageId: "0xc377616c626d73556cae080706acf37e862d24d26c690cc7be5a957f53fadf17",
+	hashiObjectId: "0x84081242ebb05eac5e09ab2a930a60b1357d3d8bc6f927380979f72de991ccca",
+	packageId: "0xa877d4d97b6a8bae1da982a84980c502c5ad2ead4b24e6c8e50c57cd6ddc3771",
 	bitcoinNetwork: "signet"
 } };
 

package/dist/contracts/hashi/bitcoin_state.mjs

@@ -9,6 +9,13 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* Per-chain Bitcoin state, attached to the `Hashi` shared object as a dynamic
+* field keyed by `BitcoinStateKey`. Bundles the deposit queue, withdrawal queue,
+* and UTXO pool behind package-only accessors, and maintains a per-user index of
+* request IDs so clients can discover all deposits and withdrawals belonging to an
+* address.
+*/
 const $moduleName = "@local-pkg/hashi::bitcoin_state";
 const BitcoinStateKey = new MoveStruct({
 	name: `${$moduleName}::BitcoinStateKey`,
@@ -17,6 +24,7 @@ const BitcoinStateKey = new MoveStruct({
 const BitcoinState = new MoveStruct({
 	name: `${$moduleName}::BitcoinState`,
 	fields: {
+		id: bcs.Address,
 		deposit_queue: DepositRequestQueue,
 		withdrawal_queue: WithdrawalRequestQueue,
 		utxo_pool: UtxoPool,

package/dist/contracts/hashi/committee.mjs

@@ -1,11 +1,20 @@
 import { MoveStruct } from "../utils/index.mjs";
 import { Element } from "./deps/sui/group_ops.mjs";
+import { Config } from "./config.mjs";
 import { bcs } from "@mysten/sui/bcs";
 
 //#region src/contracts/hashi/committee.ts
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* BLS signing committees and certificate verification. A `Committee` pins an
+* epoch's members (validator addresses, BLS public keys, encryption keys, voting
+* weights) together with the MPC parameters snapshotted at reconfig time.
+* `verify_certificate` checks an aggregate BLS12-381 min-pk signature against a
+* signers bitmap, enforces the stake threshold, and wraps the payload in a
+* `CertifiedMessage` as proof of committee approval.
+*/
 const $moduleName = "@local-pkg/hashi::committee";
 const CommitteeMember = new MoveStruct({
 	name: `${$moduleName}::CommitteeMember`,
@@ -22,9 +31,7 @@ const Committee = new MoveStruct({
 		epoch: bcs.u64(),
 		members: bcs.vector(CommitteeMember),
 		total_weight: bcs.u64(),
-		mpc_threshold_in_basis_points: bcs.u64(),
-		mpc_weight_reduction_allowed_delta: bcs.u64(),
-		mpc_max_faulty_in_basis_points: bcs.u64()
+		config: Config
 	}
 });
 const CommitteeSignature = new MoveStruct({