@mysten-incubation/hashi 0.3.0 → 0.4.0

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 };

package/dist/types.d.mts

@@ -20,6 +20,10 @@ interface HashiClientOptions<Name = "HashiClient"> {
   btcRpcUrl?: string;
   /** Override the Sui GraphQL endpoint URL (defaults to `https://fullnode.{network}.sui.io:443/graphql`). */
   graphqlUrl?: string;
+  /** Guardian origin URL (e.g. `https://hashi-guardian-devnet.mystenlabs.com`); the SDK appends `/info`. Takes precedence over the on-chain `guardian_url` config. */
+  guardianUrl?: string;
+  /** Custom guardian-info source. When set, the SDK calls this instead of fetching `/info` — useful for caching, tests, or bespoke transports. */
+  guardianInfoProvider?: GuardianInfoProvider;
 }
 /**
  * Frozen snapshot of every governance-controlled protocol parameter, returned
@@ -53,8 +57,8 @@ interface GovernanceConfig {
   readonly guardianPublicKey: Uint8Array | null;
   /**
    * Guardian's BIP-340 x-only secp256k1 BTC public key (32 bytes), the
-   * `pk1` slot of the on-chain 2-of-2 deposit-address descriptor. `null`
-   * if unset (deposit-address derivation will fail).
+   * `pk1` slot of the immediate 2-of-2 leaf in the on-chain deposit-address
+   * descriptor. `null` if unset (deposit-address derivation will fail).
    */
   readonly guardianBtcPublicKey: Uint8Array | null;
 }
@@ -229,5 +233,62 @@ interface UtxoLookupResult {
   /** Amount in satoshis. */
   readonly amountSats: bigint;
 }
+interface GuardianLimiterState {
+  /** Available tokens in satoshis at the snapshot instant. */
+  readonly numTokensAvailableSats: bigint;
+  /** Unix seconds when the bucket was last updated. */
+  readonly lastUpdatedAtSecs: bigint;
+  /** Next expected withdrawal sequence number. */
+  readonly nextSeq: bigint;
+}
+interface GuardianLimiterConfig {
+  /** Token refill rate in satoshis per second. */
+  readonly refillRateSatsPerSec: bigint;
+  /** Maximum bucket capacity in satoshis. */
+  readonly maxBucketCapacitySats: bigint;
+}
+/** Raw limiter state + config, as returned by the guardian `/info` endpoint. */
+interface GuardianLimiterRaw {
+  readonly state: GuardianLimiterState;
+  readonly config: GuardianLimiterConfig;
+}
+/**
+ * Curated guardian identity + limiter, parsed from `GET {guardianUrl}/info`.
+ * `limiter` is `null` until the guardian is provisioned/activated.
+ */
+interface RawGuardianInfo {
+  readonly limiter: GuardianLimiterRaw | null;
+  /** Guardian build git revision (untrusted, enclave-self-reported). */
+  readonly gitRevision: string;
+  /** Current committee epoch; `null` before the guardian is initialized. */
+  readonly committeeEpoch: bigint | null;
+  /** Guardian x-only 32-byte BTC pubkey (hex); `null` before provisioning. */
+  readonly btcPubkey: string | null;
+  /** Guardian ed25519 32-byte signing pubkey (hex). */
+  readonly signingPubKey: string;
+  /** `GuardianInfo` signing timestamp (ms since epoch); `null` if absent. */
+  readonly signedAtMs: bigint | null;
+}
+/** Pluggable source for {@link RawGuardianInfo}; see `HashiClientOptions.guardianInfoProvider`. */
+type GuardianInfoProvider = () => Promise<RawGuardianInfo>;
+/** Derived limiter view returned by `client.hashi.guardian.limiterStatus()`. */
+interface GuardianLimiterSnapshot {
+  readonly state: GuardianLimiterState;
+  readonly config: GuardianLimiterConfig;
+  /** Projected available tokens (sats), accounting for refill since `lastUpdatedAtSecs`. */
+  readonly availableNowSats: bigint;
+  /** Bucket fill as a percentage in [0, 100]. */
+  readonly bucketFillPercent: number;
+  /** Unix seconds at which the bucket refills to full (assuming no withdrawals). `null` if already full or the refill rate is 0. */
+  readonly fullAtSecs: bigint | null;
+}
+/** Result of `client.hashi.guardian.canWithdraw(amountSats)`. */
+interface GuardianWithdrawCheck {
+  readonly allowed: boolean;
+  /** Current available capacity in sats. */
+  readonly availableNowSats: bigint;
+  /** Seconds until `amountSats` is available; `0n` if available now; `null` if it exceeds max capacity (or the refill rate is 0). */
+  readonly estimatedWaitSecs: bigint | null;
+}
 //#endregion
-export { BitcoinNetwork, CancelWithdrawalParams, DepositFees, DepositHistoryItem, DepositInfo, DepositParams, DepositStatus, GovernanceConfig, HashiClientOptions, HbtcBalance, NetworkConfig, SuiNetwork, TransactionHistoryItem, UtxoId, UtxoLookupResult, UtxoOutput, UtxoUsageResult, WaitOptions, WithdrawalFees, WithdrawalHistoryItem, WithdrawalInfo, WithdrawalParams, WithdrawalStatus };
+export { 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 };

package/package.json

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