@mysten-incubation/hashi 0.0.1

package/dist/client.d.mts

@@ -0,0 +1,318 @@
+import { RawTransactionArgument } from "./contracts/utils/index.mjs";
+import { BitcoinNetwork, CancelWithdrawalParams, DepositParams, GovernanceConfig, HashiClientOptions, SuiNetwork, TransactionHistoryItem, UtxoId, UtxoUsageResult, 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";
+import { Signer } from "@mysten/sui/cryptography";
+
+//#region src/client.d.ts
+declare function hashi<const Name = "hashi">({
+  name,
+  ...options
+}: HashiClientOptions<Name>): {
+  name: Name;
+  register: (client: ClientWithCoreApi) => HashiClient;
+};
+/**
+ * User-facing SDK client for the Hashi protocol. Constructed via the
+ * `hashi({...})` factory and attached to any Sui client via `$extend`:
+ *
+ * ```ts
+ * const client = new SuiGrpcClient({ ... }).$extend(hashi({ network: "devnet" }));
+ * const result = await client.hashi.deposit({ signer, ... });
+ * ```
+ *
+ * **Direct methods (`deposit`, `withdraw`) sign and execute transactions** on
+ * behalf of the caller — pass a `Signer` and receive the execution result.
+ * For composable flows (bundling into a larger PTB, sponsored transactions,
+ * dry-run/simulation), use the `tx.*` builders instead; they return unsigned
+ * `Transaction` objects and leave signing to the caller.
+ */
+declare class HashiClient {
+  #private;
+  constructor({
+    client,
+    network,
+    hashiObjectId,
+    packageId,
+    bitcoinNetwork
+  }: {
+    client: ClientWithCoreApi;
+    network: SuiNetwork;
+    hashiObjectId?: string;
+    packageId?: string;
+    bitcoinNetwork?: BitcoinNetwork;
+  });
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const btcAddress = await client.hashi.generateDepositAddress({
+   *   suiAddress: signer.toSuiAddress(),
+   * });
+   * ```
+   */
+  generateDepositAddress({
+    suiAddress,
+    bitcoinNetwork
+  }: {
+    /** The Sui address to generate a deposit address for (hex string with 0x prefix). */suiAddress: string; /** Override the default Bitcoin network for this call. */
+    bitcoinNetwork?: BitcoinNetwork;
+  }): Promise<string>;
+  /**
+   * Submit one or more Bitcoin deposits for committee confirmation, batched
+   * 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.
+   *
+   * The method runs three preflight stages before signing:
+   *
+   *   1. **Structural validation** — `txid` and `recipient` must be
+   *      0x-prefixed 32-byte hex; `utxos` must be non-empty; every `vout`
+   *      must be a non-negative u32 and unique within the call. Violations
+   *      throw `InvalidParamsError` without any chain read.
+   *   2. **Pause check** — reads the governance snapshot via `view.all()`
+   *      and throws `HashiPausedError` if `paused` is `true`. Mirrors the
+   *      Move-side `hashi::assert_unpaused`.
+   *   3. **Minimum check** — every UTXO must have `amountSats ≥
+   *      snap.bitcoinDepositMinimum`. All offenders are collected into one
+   *      `AmountBelowMinimumError`, so callers can fix the batch in one
+   *      round-trip. Mirrors `EBelowMinimumDeposit` in `deposit::deposit`.
+   *
+   * Both chain-reading checks (2, 3) read from the same `view.all()`
+   * snapshot, so validation is internally consistent. Chain state can still
+   * drift between the snapshot and execution — the Move side re-asserts
+   * both invariants, so a genuine race simply aborts the tx.
+   *
+   * For composable flows (sponsored tx, dry-run, or bundling into a larger
+   * PTB), use `tx.deposit(params)` instead — it returns the unsigned
+   * `Transaction` and leaves signing to the caller.
+   */
+  deposit({
+    signer,
+    ...params
+  }: DepositParams & {
+    /** Signs and pays for the resulting transaction. The signer's address becomes the tx sender. */signer: Signer;
+  }): Promise<SuiClientTypes.TransactionResult<{
+    effects: true;
+    events: true;
+  }>>;
+  /**
+   * Submit a BTC withdrawal request for committee processing. Burns `hBTC`
+   * 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`).
+   *
+   * The method runs three preflight stages before signing:
+   *
+   *   1. **Address decoding** — `bitcoinAddress` is decoded as bech32 (v0
+   *      P2WPKH, 20 bytes) or bech32m (v1 P2TR, 32 bytes) via
+   *      `bitcoinAddressToWitnessProgram`. The HRP must match the client's
+   *      configured Bitcoin network. Violations throw
+   *      `InvalidBitcoinAddressError` with a structured `code` so callers
+   *      can distinguish a typo from a wrong-network mistake.
+   *   2. **Pause check** — reads the governance snapshot via `view.all()`
+   *      and throws `HashiPausedError` if `paused` is `true`. Mirrors the
+   *      Move-side `hashi::assert_unpaused` in `request_withdrawal`.
+   *   3. **Minimum check** — `amountSats` must be ≥
+   *      `snap.bitcoinWithdrawalMinimum`. Below-minimum throws
+   *      `AmountBelowMinimumError` with a single violation. Mirrors
+   *      `EBelowMinimumWithdrawal` in `withdraw::request_withdrawal`.
+   *
+   * For composable flows (sponsored tx, dry-run, or bundling into a
+   * larger PTB), use `tx.requestWithdrawal(options)` instead — it returns
+   * the unsigned `Transaction` and leaves signing to the caller.
+   */
+  requestWithdrawal({
+    signer,
+    ...params
+  }: WithdrawalParams & {
+    /** Signs and pays for the resulting transaction. The signer's address becomes the tx sender. */signer: Signer;
+  }): Promise<SuiClientTypes.TransactionResult<{
+    effects: true;
+    events: true;
+  }>>;
+  /**
+   * Cancel a pending withdrawal request and return the locked BTC to the
+   * signer. Signs with `signer` and submits, returning the execution result.
+   *
+   * The only client-side precondition is that `requestId` is 0x-prefixed
+   * 32-byte hex. All other constraints — ownership (only the original
+   * requester can cancel), state window (cancellable only while `Requested`
+   * or `Approved`, not after committee commitment), and the on-chain
+   * `withdrawal_cancellation_cooldown_ms` — are enforced by the Move side
+   * and left to abort at execution. Pre-fetching them would cost an extra
+   * round-trip and still race chain state.
+   *
+   * Unlike `requestWithdrawal`, no pause check is performed: the Move
+   * `cancel_withdrawal` function has no `assert_unpaused`, so users can
+   * always unwind a pending request even when the system is paused.
+   *
+   * For composable flows, use `tx.cancelWithdrawal({ requestId, recipient })`.
+   */
+  cancelWithdrawal({
+    signer,
+    requestId
+  }: CancelWithdrawalParams & {
+    /** Signs and pays for the resulting transaction. The signer's address becomes the tx sender and the recipient of the returned BTC. */signer: Signer;
+  }): Promise<SuiClientTypes.TransactionResult<{
+    effects: true;
+    events: true;
+  }>>;
+  tx: {
+    /**
+     * Build a transaction that submits one or more Bitcoin deposits for
+     * committee confirmation, batched into a single Sui PTB.
+     *
+     * A single Bitcoin funding tx can pay the same deposit address on
+     * multiple outputs (e.g. change + donation, or a coinjoin). Rather
+     * than forcing the user to submit one Sui tx per output, this method
+     * accepts every qualifying output and emits a dedicated Move-call
+     * triple per UTXO:
+     *
+     *     utxo::utxo_id(txid, vout_i)   → UtxoId
+     *     utxo::utxo(utxoId, amount_i, derivationPath = recipient)  → Utxo
+     *     deposit::deposit(hashi, utxo)
+     *
+     * The triples are emitted in `params.utxos` order, so N UTXOs yield
+     * exactly `3 * N` PTB commands.
+     *
+     * Because all triples live in one PTB, execution is atomic: either
+     * every deposit is recorded, or none are (any abort — wrong minimum,
+     * replayed UTXO, paused system — reverts the whole transaction).
+     *
+     * All UTXOs share the `txid` because `DepositParams` has a single
+     * top-level `txid` field, and are credited to the same `recipient`.
+     *
+     * The `txid` is provided in **display byte order** (the form
+     * mempool.space and `bitcoin-cli` show); this method reverses it
+     * to internal byte order before recording on-chain via
+     * `reverseTxidBytes`. The committee verifier reads `Utxo.txid`
+     * as a `bitcoin::Txid`, which expects internal byte order — so
+     * recording display-order bytes leaves the committee searching
+     * for a phantom (byte-reversed) tx and the deposit never confirms.
+     *
+     * @example
+     * ```ts
+     * const tx = client.hashi.tx.deposit({
+     *   txid: `0x${btcTxid}`,
+     *   utxos: [
+     *     { vout: 0, amountSats: 100_000n },
+     *     { vout: 2, amountSats:  50_000n },
+     *   ],
+     *   recipient: signer.toSuiAddress(),
+     * });
+     * await client.signAndExecuteTransaction({ signer, transaction: tx });
+     * ```
+     */
+    deposit: (params: DepositParams) => Transaction;
+    /**
+     * Build a transaction that submits a BTC withdrawal request. Sources the
+     * BTC via `coinWithBalance`, unwraps it into a `Balance<BTC>`, and passes
+     * it to `withdraw::request_withdrawal` along with the target Bitcoin
+     * output address.
+     */
+    requestWithdrawal: (options: {
+      /** Amount in sats to withdraw. Must be ≥ the on-chain withdrawal minimum. */amount: bigint;
+      /**
+       * Target Bitcoin address as raw witness program bytes — 20 bytes for
+       * P2WPKH, 32 bytes for P2TR. Callers decode their own bech32(m)
+       * strings for now; a string-input overload may land in a follow-up.
+       */
+      bitcoinAddress: Uint8Array;
+    }) => Transaction;
+    /**
+     * Build a transaction that cancels a pending withdrawal request and
+     * returns the locked BTC to the user. Consumes the `Balance<BTC>`
+     * hot-potato returned by `withdraw::cancel_withdrawal` by wrapping it
+     * into a `Coin<BTC>` and transferring to `recipient`.
+     */
+    cancelWithdrawal: (options: {
+      /** The withdrawal request ID to cancel. */requestId: string;
+      /**
+       * Sui address that will receive the returned `Coin<BTC>`. Required
+       * because the unsigned `Transaction` does not know its sender at
+       * build time — the caller must pass their own address explicitly.
+       */
+      recipient: string;
+    }) => Transaction;
+  };
+  call: {
+    deposit: (options: {
+      utxo: RawTransactionArgument<string>;
+    }) => (tx: Transaction) => _mysten_sui_transactions0.TransactionResult;
+    requestWithdrawal: (options: {
+      btc: RawTransactionArgument<string>;
+      bitcoinAddress: RawTransactionArgument<number[]>;
+    }) => (tx: Transaction) => _mysten_sui_transactions0.TransactionResult;
+    /**
+     * Cancel a pending withdrawal request. Returns a `Balance<BTC>` hot potato
+     * that must be consumed in the same PTB (e.g. wrapped into a Coin and
+     * transferred back to the sender).
+     */
+    cancelWithdrawal: (options: {
+      requestId: RawTransactionArgument<string>;
+    }) => (tx: Transaction) => _mysten_sui_transactions0.TransactionResult;
+  };
+  view: {
+    /**
+     * Fetches the MPC committee's threshold public key from on-chain.
+     *
+     * This is the 33-byte compressed secp256k1 key stored in `CommitteeSet.mpc_public_key`.
+     * It is set after the committee completes DKG and is updated at epoch boundaries.
+     *
+     * @returns 33-byte compressed secp256k1 public key
+     * @throws If the MPC key is not yet available (DKG not completed)
+     */
+    mpcPublicKey: () => Promise<Uint8Array>;
+    /**
+     * Fetches all governance values in a single round-trip and returns a
+     * consistent snapshot. Prefer this over individual methods when you
+     * need 2+ values — it avoids redundant `Hashi.get` calls and gives
+     * you all fields from the same on-chain state.
+     */
+    all: () => Promise<GovernanceConfig>;
+    paused: () => Promise<boolean>; /** Floored to `DUST_RELAY_MIN_VALUE` if the on-chain value is lower. */
+    bitcoinDepositMinimum: () => Promise<bigint>; /** Floored to `DUST_RELAY_MIN_VALUE + 1` so `worstCaseNetworkFee` is always ≥ 1. */
+    bitcoinWithdrawalMinimum: () => Promise<bigint>;
+    bitcoinConfirmationThreshold: () => Promise<bigint>;
+    withdrawalCancellationCooldownMs: () => Promise<bigint>;
+    bitcoinChainId: () => Promise<string>; /** Alias of `bitcoinDepositMinimum`. */
+    depositMinimum: () => Promise<bigint>;
+    /**
+     * Worst-case Bitcoin miner fee (sats) deducted from a withdrawal.
+     * Derived as `bitcoinWithdrawalMinimum - DUST_RELAY_MIN_VALUE`; always ≥ 1.
+     */
+    worstCaseNetworkFee: () => Promise<bigint>;
+    /**
+     * Check whether one or more Bitcoin UTXOs already exist in the
+     * on-chain `UtxoPool` — either as active (confirmed deposit, not yet
+     * consumed) or spent (consumed by a withdrawal). Callers use this to
+     * detect already-used outputs before submitting a deposit.
+     *
+     * `txid` in each `UtxoId` is **display byte order**; the method
+     * reverses to internal byte order before encoding the on-chain key.
+     */
+    findUsedUtxos: (utxos: readonly UtxoId[]) => Promise<UtxoUsageResult[]>;
+    /**
+     * Fetch the unified transaction history (deposits + withdrawals) for
+     * a Sui address. Reads from `BitcoinState.user_requests` — a Table
+     * that maps each user address to a Bag of request IDs — then batch-
+     * fetches the request objects and dispatches by Move type.
+     *
+     * Deposit items include `btcTxid` / `btcVout` extracted from the
+     * UTXO stored on the `DepositRequest`. Withdrawal items include the
+     * BTC txid from the linked `WithdrawalTransaction` once the committee
+     * has committed one.
+     */
+    transactionHistory: (suiAddress: string) => Promise<TransactionHistoryItem[]>;
+  };
+}
+//#endregion
+export { HashiClient, hashi };