@mysten-incubation/hashi 0.3.1 → 0.5.0

package/dist/contracts/hashi/hashi.mjs

@@ -1,7 +1,8 @@
 import { MoveStruct } from "../utils/index.mjs";
+import { Config } from "./config.mjs";
 import { Bag } from "./deps/sui/bag.mjs";
 import { CommitteeSet } from "./committee_set.mjs";
-import { Config } from "./config.mjs";
+import { Versioning } from "./versioning.mjs";
 import { Treasury } from "./treasury.mjs";
 import { Proposals } from "./proposals.mjs";
 import { bcs } from "@mysten/sui/bcs";
@@ -10,7 +11,15 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
-/** Module: hashi */
+/**
+* The root shared object of the bridge. `Hashi` aggregates every subsystem —
+* committee set, config, versioning, treasury, governance proposals, and TOB
+* certificate storage — and hangs per-chain state (e.g. `BitcoinState`) off its
+* `UID` as dynamic fields. It also provides the package-wide guards (pause,
+* reconfig, committee-signature verification) that entry functions in other
+* modules call through, and the one-time `finish_publish` launch switch that hands
+* the package `UpgradeCap` into on-chain custody.
+*/
 const $moduleName = "@local-pkg/hashi::hashi";
 const Hashi = new MoveStruct({
 	name: `${$moduleName}::Hashi`,
@@ -18,6 +27,7 @@ const Hashi = new MoveStruct({
 		id: bcs.Address,
 		committee_set: CommitteeSet,
 		config: Config,
+		versioning: Versioning,
 		treasury: Treasury,
 		proposals: Proposals,
 		tob: Bag,

package/dist/contracts/hashi/mpc_signing.mjs

@@ -0,0 +1,56 @@
+import { MoveEnum, MoveStruct } from "../utils/index.mjs";
+import { bcs } from "@mysten/sui/bcs";
+
+//#region src/contracts/hashi/mpc_signing.ts
+/**************************************************************
+* THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+**************************************************************/
+/**
+* Durable, out-of-order accumulator for a withdrawal's per-input threshold Schnorr
+* signatures. This is the MPC-protocol side of incremental signing: the dangerous
+* presignature / nonce bookkeeping lives here, behind a module boundary, and is
+* embedded (field-private) inside the BTC `WithdrawalTransaction` rather than
+* stored as a separate object.
+*
+* Each input occupies one slot that is either:
+*
+* - `Pending(presig_index)` — awaiting its signature; carries the presignature
+*   index it will consume (valid within `epoch`), or
+* - `Signed(bytes)` — the completed per-input MPC signature.
+*
+* Signatures are filled in any order (`record`), survive leader timeouts /
+* rotation / restart because they live on chain, and survive committee
+* reconfiguration: on an epoch change only the still-`Pending` slots are
+* reassigned fresh presignatures (`reallocate`); `Signed` slots are final and
+* epoch-independent (the committee group key is stable across rotation).
+*
+* NONCE SAFETY (a violation leaks the group secret share):
+*
+* - every `Pending` index is unique within (batch, epoch) — `new` / `reallocate`
+*   assign distinct offsets from a freshly allocated block;
+* - indices are globally disjoint within an epoch — the allocator is monotonic
+*   (see `hashi::allocate_presigs`);
+* - a stale-epoch index is never used after a reconfig — `reallocate` overwrites
+*   EVERY `Pending` slot before any signing happens in the new epoch, and the
+*   caller must `reallocate` whenever `epoch` is stale;
+* - a `Signed` slot holds no index, so there is nothing stale to reuse.
+*/
+const $moduleName = "@local-pkg/hashi::mpc_signing";
+/** Per-input signing slot. */
+const MpcSig = new MoveEnum({
+	name: `${$moduleName}::MpcSig`,
+	fields: {
+		Pending: bcs.u64(),
+		Signed: bcs.vector(bcs.u8())
+	}
+});
+const SigningBatch = new MoveStruct({
+	name: `${$moduleName}::SigningBatch`,
+	fields: {
+		signatures: bcs.vector(MpcSig),
+		epoch: bcs.u64()
+	}
+});
+
+//#endregion
+export { SigningBatch };

package/dist/contracts/hashi/proposals.mjs

@@ -5,6 +5,12 @@ import { ObjectBag } from "./deps/sui/object_bag.mjs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* Container for the package's governance proposals, hung off `Hashi`. Active and
+* executed proposals live in two separate object bags so that each set can be
+* enumerated directly, and executed proposals are archived indefinitely to keep
+* historical governance actions inspectable.
+*/
 const $moduleName = "@local-pkg/hashi::proposals";
 const Proposals = new MoveStruct({
 	name: `${$moduleName}::Proposals`,

package/dist/contracts/hashi/treasury.mjs

@@ -6,6 +6,12 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* Custody of the coin capabilities for bridge-issued assets. `Treasury` holds the
+* `TreasuryCap` and `MetadataCap` of each registered coin type in an `ObjectBag`
+* keyed by cap type, and exposes package-only mint/burn that emit
+* `Minted`/`Burned` events for off-chain watchers.
+*/
 const $moduleName = "@local-pkg/hashi::treasury";
 const Treasury = new MoveStruct({
 	name: `${$moduleName}::Treasury`,
@@ -15,12 +21,12 @@ const Key = new MoveStruct({
 	name: `${$moduleName}::Key<phantom T>`,
 	fields: { dummy_field: bcs.bool() }
 });
-const MintEvent = new MoveStruct({
-	name: `${$moduleName}::MintEvent<phantom T>`,
+const Minted = new MoveStruct({
+	name: `${$moduleName}::Minted<phantom T>`,
 	fields: { amount: bcs.u64() }
 });
-const BurnEvent = new MoveStruct({
-	name: `${$moduleName}::BurnEvent<phantom T>`,
+const Burned = new MoveStruct({
+	name: `${$moduleName}::Burned<phantom T>`,
 	fields: { amount: bcs.u64() }
 });
 

package/dist/contracts/hashi/utxo.mjs

@@ -5,6 +5,13 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* Bitcoin UTXO value types shared by the deposit and withdrawal flows. A `UtxoId`
+* identifies an outpoint (txid:vout) and a `Utxo` pairs it with its satoshi amount
+* and an optional derivation path (the Sui address a deposit mints to). The
+* constructors are `public` so PTBs can assemble UTXOs when calling into the
+* bridge; everything else is package-only.
+*/
 const $moduleName = "@local-pkg/hashi::utxo";
 const UtxoId = new MoveStruct({
 	name: `${$moduleName}::UtxoId`,

package/dist/contracts/hashi/utxo_pool.mjs

@@ -7,6 +7,13 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* On-chain bookkeeping for the bridge's Bitcoin UTXO set. Confirmed deposit
+* outputs and unconfirmed withdrawal change outputs live in `utxo_records` from
+* insertion until the withdrawal that spends them confirms on Bitcoin, after which
+* their IDs move to `spent_utxos` — kept permanently as replay protection so an
+* already-spent outpoint can never be re-inserted.
+*/
 const $moduleName = "@local-pkg/hashi::utxo_pool";
 const UtxoPool = new MoveStruct({
 	name: `${$moduleName}::UtxoPool`,
@@ -20,12 +27,12 @@ const UtxoRecord = new MoveStruct({
 	fields: {
 		utxo: Utxo,
 		produced_by: bcs.option(bcs.Address),
-		locked_by: bcs.option(bcs.Address),
+		spent_by: bcs.option(bcs.Address),
 		spent_epoch: bcs.option(bcs.u64())
 	}
 });
-const UtxoSpentEvent = new MoveStruct({
-	name: `${$moduleName}::UtxoSpentEvent`,
+const UtxoSpent = new MoveStruct({
+	name: `${$moduleName}::UtxoSpent`,
 	fields: {
 		utxo_id: UtxoId,
 		spent_epoch: bcs.u64()

package/dist/contracts/hashi/versioning.mjs

@@ -0,0 +1,28 @@
+import { MoveStruct } from "../utils/index.mjs";
+import { VecSet } from "./deps/sui/vec_set.mjs";
+import { UpgradeCap } from "./deps/sui/package.mjs";
+import { bcs } from "@mysten/sui/bcs";
+
+//#region src/contracts/hashi/versioning.ts
+/**************************************************************
+* THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+**************************************************************/
+/**
+* Package version gating and upgrade authority.
+*
+* Holds the set of package versions allowed to run and custodies the package
+* `UpgradeCap`. The two live together because they are one lifecycle: committing
+* an upgrade through the cap auto-enables the new version. Every entry function
+* gates on `assert_version_enabled` so a disabled version cannot be executed.
+*/
+const $moduleName = "@local-pkg/hashi::versioning";
+const Versioning = new MoveStruct({
+	name: `${$moduleName}::Versioning`,
+	fields: {
+		enabled_versions: VecSet(bcs.u64()),
+		upgrade_cap: bcs.option(UpgradeCap)
+	}
+});
+
+//#endregion
+export { Versioning };

package/dist/contracts/hashi/withdraw.mjs

@@ -7,7 +7,15 @@ import { bcs } from "@mysten/sui/bcs";
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
-/** Module: withdraw */
+/**
+* User-facing Bitcoin withdrawal flow. A user escrows hBTC against a target
+* Bitcoin address; the committee approves the request, batches one or more
+* requests into a withdrawal transaction (burning the hBTC and locking the input
+* UTXOs), accumulates per-input MPC signatures incrementally, finalizes with the
+* one-shot guardian signatures, and confirms once the transaction lands on
+* Bitcoin. A not-yet-committed request can be cancelled by its requester after a
+* cooldown, refunding the hBTC.
+*/
 const $moduleName = "@local-pkg/hashi::withdraw";
 const RequestApprovalMessage = new MoveStruct({
 	name: `${$moduleName}::RequestApprovalMessage`,
@@ -31,6 +39,14 @@ const WithdrawalSignedMessage = new MoveStruct({
 		guardian_signatures: bcs.vector(bcs.vector(bcs.u8()))
 	}
 });
+const MpcInputSignaturesMessage = new MoveStruct({
+	name: `${$moduleName}::MpcInputSignaturesMessage`,
+	fields: {
+		withdrawal_id: bcs.Address,
+		indices: bcs.vector(bcs.u64()),
+		signatures: bcs.vector(bcs.vector(bcs.u8()))
+	}
+});
 const WithdrawalConfirmationMessage = new MoveStruct({
 	name: `${$moduleName}::WithdrawalConfirmationMessage`,
 	fields: { withdrawal_id: bcs.Address }

package/dist/contracts/hashi/withdrawal_queue.mjs

@@ -1,13 +1,23 @@
 import { MoveEnum, MoveStruct } from "../utils/index.mjs";
+import { CommitteeSignature } from "./committee.mjs";
 import { ObjectBag } from "./deps/sui/object_bag.mjs";
 import { Utxo, UtxoId } from "./utxo.mjs";
 import { Balance } from "./deps/sui/balance.mjs";
+import { SigningBatch } from "./mpc_signing.mjs";
 import { bcs } from "@mysten/sui/bcs";
 
 //#region src/contracts/hashi/withdrawal_queue.ts
 /**************************************************************
 * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
 **************************************************************/
+/**
+* Storage and state machine for Bitcoin withdrawals. Holds `WithdrawalRequest`
+* objects as they move from Requested through Approved, Processing, Signed, and
+* Confirmed, plus the `WithdrawalTransaction` objects that batch them: each
+* transaction tracks its input UTXOs, withdrawal and change outputs, and the
+* incrementally collected MPC and guardian signatures. Certificate verification
+* and funds movement are driven by `hashi::withdraw`.
+*/
 const $moduleName = "@local-pkg/hashi::withdrawal_queue";
 const WithdrawalRequestQueue = new MoveStruct({
 	name: `${$moduleName}::WithdrawalRequestQueue`,
@@ -42,8 +52,10 @@ const WithdrawalRequest = new MoveStruct({
 		sender: bcs.Address,
 		btc_amount: bcs.u64(),
 		bitcoin_address: bcs.vector(bcs.u8()),
-		timestamp_ms: bcs.u64(),
+		created_timestamp_ms: bcs.u64(),
 		status: WithdrawalStatus,
+		approval_cert: bcs.option(CommitteeSignature),
+		approved_timestamp_ms: bcs.option(bcs.u64()),
 		withdrawal_txn_id: bcs.option(bcs.Address),
 		sui_tx_digest: bcs.vector(bcs.u8()),
 		btc: Balance
@@ -57,13 +69,13 @@ const WithdrawalTransaction = new MoveStruct({
 		request_ids: bcs.vector(bcs.Address),
 		inputs: bcs.vector(Utxo),
 		withdrawal_outputs: bcs.vector(OutputUtxo),
-		change_output: bcs.option(OutputUtxo),
-		timestamp_ms: bcs.u64(),
+		change_outputs: bcs.vector(OutputUtxo),
+		created_timestamp_ms: bcs.u64(),
+		signed_timestamp_ms: bcs.option(bcs.u64()),
+		confirmed_timestamp_ms: bcs.option(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()
+		signing: SigningBatch,
+		guardian_signatures: bcs.option(bcs.vector(bcs.vector(bcs.u8())))
 	}
 });
 const CommittedRequestInfo = new MoveStruct({
@@ -73,8 +85,8 @@ const CommittedRequestInfo = new MoveStruct({
 		bitcoin_address: bcs.vector(bcs.u8())
 	}
 });
-const WithdrawalRequestedEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalRequestedEvent`,
+const WithdrawalRequested = new MoveStruct({
+	name: `${$moduleName}::WithdrawalRequested`,
 	fields: {
 		request_id: bcs.Address,
 		btc_amount: bcs.u64(),
@@ -84,25 +96,33 @@ const WithdrawalRequestedEvent = new MoveStruct({
 		sui_tx_digest: bcs.vector(bcs.u8())
 	}
 });
-const WithdrawalApprovedEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalApprovedEvent`,
+const WithdrawalApproved = new MoveStruct({
+	name: `${$moduleName}::WithdrawalApproved`,
 	fields: { request_id: bcs.Address }
 });
-const WithdrawalPickedForProcessingEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalPickedForProcessingEvent`,
+const WithdrawalPickedForProcessing = new MoveStruct({
+	name: `${$moduleName}::WithdrawalPickedForProcessing`,
 	fields: {
 		withdrawal_txn_id: bcs.Address,
 		txid: bcs.Address,
 		request_ids: bcs.vector(bcs.Address),
 		inputs: bcs.vector(Utxo),
 		withdrawal_outputs: bcs.vector(OutputUtxo),
-		change_output: bcs.option(OutputUtxo),
+		change_outputs: bcs.vector(OutputUtxo),
 		timestamp_ms: bcs.u64(),
 		randomness: bcs.vector(bcs.u8())
 	}
 });
-const WithdrawalSignedEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalSignedEvent`,
+const WithdrawalInputsSigned = new MoveStruct({
+	name: `${$moduleName}::WithdrawalInputsSigned`,
+	fields: {
+		withdrawal_txn_id: bcs.Address,
+		signed_count: bcs.u64(),
+		num_inputs: bcs.u64()
+	}
+});
+const WithdrawalSigned = new MoveStruct({
+	name: `${$moduleName}::WithdrawalSigned`,
 	fields: {
 		withdrawal_txn_id: bcs.Address,
 		request_ids: bcs.vector(bcs.Address),
@@ -110,26 +130,26 @@ const WithdrawalSignedEvent = new MoveStruct({
 		guardian_signatures: bcs.vector(bcs.vector(bcs.u8()))
 	}
 });
-const WithdrawalPresigsReassignedEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalPresigsReassignedEvent`,
+const WithdrawalPresigsReassigned = new MoveStruct({
+	name: `${$moduleName}::WithdrawalPresigsReassigned`,
 	fields: {
 		withdrawal_txn_id: bcs.Address,
 		epoch: bcs.u64(),
 		presig_start_index: bcs.u64()
 	}
 });
-const WithdrawalConfirmedEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalConfirmedEvent`,
+const WithdrawalConfirmed = new MoveStruct({
+	name: `${$moduleName}::WithdrawalConfirmed`,
 	fields: {
 		withdrawal_txn_id: bcs.Address,
 		txid: bcs.Address,
-		change_utxo_id: bcs.option(UtxoId),
+		change_utxo_ids: bcs.vector(UtxoId),
 		request_ids: bcs.vector(bcs.Address),
-		change_utxo_amount: bcs.option(bcs.u64())
+		change_utxo_amounts: bcs.vector(bcs.u64())
 	}
 });
-const WithdrawalCancelledEvent = new MoveStruct({
-	name: `${$moduleName}::WithdrawalCancelledEvent`,
+const WithdrawalCancelled = new MoveStruct({
+	name: `${$moduleName}::WithdrawalCancelled`,
 	fields: {
 		request_id: bcs.Address,
 		requester_address: bcs.Address,

package/dist/errors.d.mts

@@ -36,6 +36,33 @@ declare class HashiFetchError extends Error {
     cause?: unknown;
   });
 }
+/**
+ * Stable discriminator for `HashiGuardianError`, so callers can `switch` on
+ * `code` rather than string-parse the message: `not-configured` (no guardian URL
+ * resolvable), `unreachable` (`fetch` threw), `http-error` (non-2xx),
+ * `malformed-response` (bad JSON or limiter field), `not-initialized` (no limiter yet).
+ */
+type GuardianErrorCode = "not-configured" | "unreachable" | "http-error" | "malformed-response" | "not-initialized";
+/**
+ * Thrown by the `client.hashi.guardian.*` methods when the guardian `/info`
+ * endpoint can't be resolved, reached, parsed, or is not yet initialized.
+ * `code` is a stable discriminator for programmatic handling; `url` is the
+ * `/info` endpoint that failed (`null` for `not-configured`); `status` carries
+ * the HTTP status for `http-error`.
+ */
+declare class HashiGuardianError extends Error {
+  readonly code: GuardianErrorCode;
+  readonly url: string | null;
+  readonly status?: number;
+  constructor(details: {
+    message: string;
+    code: GuardianErrorCode;
+    url?: string | null;
+    status?: number;
+  }, options?: {
+    cause?: unknown;
+  });
+}
 /**
  * One amount that failed a client-side minimum check. `vout` is present for
  * deposit-UTXO violations (so callers can map each offender back to a Bitcoin
@@ -115,4 +142,4 @@ declare class InvalidBitcoinAddressError extends Error {
   });
 }
 //#endregion
-export { AmountBelowMinimumError, AmountViolation, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError };
+export { AmountBelowMinimumError, AmountViolation, GuardianErrorCode, HashiConfigError, HashiFetchError, HashiGuardianError, HashiPausedError, InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError };

package/dist/errors.mjs

@@ -52,6 +52,22 @@ var HashiFetchError = class extends Error {
 	}
 };
 /**
+* Thrown by the `client.hashi.guardian.*` methods when the guardian `/info`
+* endpoint can't be resolved, reached, parsed, or is not yet initialized.
+* `code` is a stable discriminator for programmatic handling; `url` is the
+* `/info` endpoint that failed (`null` for `not-configured`); `status` carries
+* the HTTP status for `http-error`.
+*/
+var HashiGuardianError = class extends Error {
+	constructor(details, options) {
+		super(details.message, options);
+		this.name = "HashiGuardianError";
+		this.code = details.code;
+		this.url = details.url ?? null;
+		this.status = details.status;
+	}
+};
+/**
 * Thrown by `HashiClient.deposit()` and `HashiClient.requestWithdrawal()` when
 * one or more amounts are below the live on-chain minimum. Deposits may carry
 * multiple violations (one per offending UTXO) so callers can fix the whole
@@ -115,4 +131,4 @@ var InvalidBitcoinAddressError = class extends Error {
 };
 
 //#endregion
-export { AmountBelowMinimumError, HashiConfigError, HashiFetchError, HashiPausedError, InvalidBitcoinAddressError, InvalidParamsError };
+export { AmountBelowMinimumError, HashiConfigError, HashiFetchError, HashiGuardianError, HashiPausedError, InvalidBitcoinAddressError, InvalidParamsError };

package/dist/guardian.d.mts

@@ -0,0 +1,26 @@
+import { GuardianLimiterConfig, GuardianLimiterState, RawGuardianInfo } from "./types.mjs";
+
+//#region src/guardian.d.ts
+/**
+ * Project the token-bucket capacity (sats) forward to `timestampSecs`, mirroring
+ * the guardian's Rust limiter: `min(available + elapsed * refillRate, max)`.
+ * Timestamps are unix seconds; one at or before `lastUpdatedAtSecs` yields the
+ * stored balance.
+ */
+declare function projectCapacity(config: GuardianLimiterConfig, state: GuardianLimiterState, timestampSecs: bigint): bigint;
+/**
+ * Estimate the seconds until `amountSats` of capacity is available given the
+ * current bucket. Returns `0n` if it is available now, or `null` if it can
+ * never be satisfied in a single withdrawal — either the amount exceeds the
+ * bucket's maximum capacity, or the refill rate is `0` and a deficit remains.
+ */
+declare function estimateWaitSecs(config: GuardianLimiterConfig, state: GuardianLimiterState, amountSats: bigint, nowSecs: bigint): bigint | null;
+/**
+ * Fetch and parse the guardian's read-only `/info` JSON. `origin` is the base
+ * URL (no path — e.g. the on-chain `guardian_url`); `/info` is appended here.
+ * `u64` strings are parsed to `bigint`, and `limiter` is `null` for an
+ * unprovisioned guardian. Failures are wrapped in {@link HashiGuardianError}.
+ */
+declare function fetchGuardianInfo(origin: string): Promise<RawGuardianInfo>;
+//#endregion
+export { estimateWaitSecs, fetchGuardianInfo, projectCapacity };

package/dist/guardian.mjs

@@ -0,0 +1,101 @@
+import { HashiGuardianError } from "./errors.mjs";
+
+//#region src/guardian.ts
+/**
+* Project the token-bucket capacity (sats) forward to `timestampSecs`, mirroring
+* the guardian's Rust limiter: `min(available + elapsed * refillRate, max)`.
+* Timestamps are unix seconds; one at or before `lastUpdatedAtSecs` yields the
+* stored balance.
+*/
+function projectCapacity(config, state, timestampSecs) {
+	const refilled = (timestampSecs > state.lastUpdatedAtSecs ? timestampSecs - state.lastUpdatedAtSecs : 0n) * config.refillRateSatsPerSec;
+	const projected = state.numTokensAvailableSats + refilled;
+	return projected < config.maxBucketCapacitySats ? projected : config.maxBucketCapacitySats;
+}
+/**
+* Estimate the seconds until `amountSats` of capacity is available given the
+* current bucket. Returns `0n` if it is available now, or `null` if it can
+* never be satisfied in a single withdrawal — either the amount exceeds the
+* bucket's maximum capacity, or the refill rate is `0` and a deficit remains.
+*/
+function estimateWaitSecs(config, state, amountSats, nowSecs) {
+	if (amountSats > config.maxBucketCapacitySats) return null;
+	const available = projectCapacity(config, state, nowSecs);
+	if (available >= amountSats) return 0n;
+	const deficit = amountSats - available;
+	if (config.refillRateSatsPerSec === 0n) return null;
+	return (deficit + config.refillRateSatsPerSec - 1n) / config.refillRateSatsPerSec;
+}
+/**
+* Fetch and parse the guardian's read-only `/info` JSON. `origin` is the base
+* URL (no path — e.g. the on-chain `guardian_url`); `/info` is appended here.
+* `u64` strings are parsed to `bigint`, and `limiter` is `null` for an
+* unprovisioned guardian. Failures are wrapped in {@link HashiGuardianError}.
+*/
+async function fetchGuardianInfo(origin) {
+	const endpoint = `${origin.replace(/\/+$/, "")}/info`;
+	let res;
+	try {
+		res = await fetch(endpoint, { headers: { Accept: "application/json" } });
+	} catch (cause) {
+		throw new HashiGuardianError({
+			message: `Guardian endpoint unreachable: ${endpoint}`,
+			code: "unreachable",
+			url: endpoint
+		}, { cause });
+	}
+	if (!res.ok) throw new HashiGuardianError({
+		message: `Guardian /info returned HTTP ${res.status}`,
+		code: "http-error",
+		url: endpoint,
+		status: res.status
+	});
+	let body;
+	try {
+		body = await res.json();
+	} catch (cause) {
+		throw new HashiGuardianError({
+			message: "Guardian /info returned a non-JSON body",
+			code: "malformed-response",
+			url: endpoint
+		}, { cause });
+	}
+	const u64 = (value, field) => {
+		if (typeof value !== "string") throw new HashiGuardianError({
+			message: `Guardian /info field \`${field}\` must be a string, got ${typeof value}`,
+			code: "malformed-response",
+			url: endpoint
+		});
+		try {
+			return BigInt(value);
+		} catch (cause) {
+			throw new HashiGuardianError({
+				message: `Guardian /info field \`${field}\` is not an integer: ${JSON.stringify(value)}`,
+				code: "malformed-response",
+				url: endpoint
+			}, { cause });
+		}
+	};
+	const rawLimiter = body.limiter;
+	return {
+		limiter: rawLimiter == null ? null : {
+			state: {
+				numTokensAvailableSats: u64(rawLimiter.state?.numTokensAvailableSats, "limiter.state.numTokensAvailableSats"),
+				lastUpdatedAtSecs: u64(rawLimiter.state?.lastUpdatedAtSecs, "limiter.state.lastUpdatedAtSecs"),
+				nextSeq: u64(rawLimiter.state?.nextSeq, "limiter.state.nextSeq")
+			},
+			config: {
+				refillRateSatsPerSec: u64(rawLimiter.config?.refillRateSatsPerSec, "limiter.config.refillRateSatsPerSec"),
+				maxBucketCapacitySats: u64(rawLimiter.config?.maxBucketCapacitySats, "limiter.config.maxBucketCapacitySats")
+			}
+		},
+		gitRevision: body.gitRevision ?? "",
+		committeeEpoch: body.committeeEpoch == null ? null : u64(body.committeeEpoch, "committeeEpoch"),
+		btcPubkey: body.btcPubkey ?? null,
+		signingPubKey: body.signingPubKey ?? "",
+		signedAtMs: body.signedAtMs == null ? null : u64(body.signedAtMs, "signedAtMs")
+	};
+}
+
+//#endregion
+export { estimateWaitSecs, fetchGuardianInfo, projectCapacity };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-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 { BitcoinNetwork, CancelWithdrawalParams, DepositFees, DepositHistoryItem, DepositInfo, DepositParams, DepositStatus, GovernanceConfig, GuardianInfoProvider, GuardianLimiterConfig, GuardianLimiterRaw, GuardianLimiterSnapshot, GuardianLimiterState, GuardianWithdrawCheck, HashiClientOptions, HbtcBalance, NetworkConfig, RawGuardianInfo, 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 { AmountBelowMinimumError, AmountViolation, GuardianErrorCode, HashiConfigError, HashiFetchError, HashiGuardianError, HashiPausedError, InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError } from "./errors.mjs";
 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 };
+import { estimateWaitSecs, fetchGuardianInfo, projectCapacity } from "./guardian.mjs";
+export { AmountBelowMinimumError, type AmountViolation, type BitcoinNetwork, type CancelWithdrawalParams, type DepositAddressInputs, type DepositFees, type DepositHistoryItem, type DepositInfo, type DepositParams, type DepositStatus, type GovernanceConfig, type GuardianErrorCode, type GuardianInfoProvider, type GuardianLimiterConfig, type GuardianLimiterRaw, type GuardianLimiterSnapshot, type GuardianLimiterState, type GuardianWithdrawCheck, HashiClient, type HashiClientOptions, HashiConfigError, HashiFetchError, HashiGuardianError, HashiPausedError, type HbtcBalance, type InvalidBitcoinAddressCode, InvalidBitcoinAddressError, InvalidParamsError, type NetworkConfig, type RawGuardianInfo, 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, estimateWaitSecs, fetchGuardianInfo, generateDepositAddress, hashi, projectCapacity, twoOfTwoTaprootScriptPathAddress, witnessProgramToAddress };

package/dist/index.mjs

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