@chipi-stack/chipi-react 14.3.1 → 14.6.0

package/dist/hooks.d.ts

@@ -1,6 +1,7 @@
-import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, SyncOnChainTransfersParams, SyncOnChainTransfersResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
+import { CreateWalletParams, CreateWalletResponse, GetWalletParams, GetWalletResponse, ChainToken, GetTokenBalanceResponse, WalletType, WalletData, SessionKeyData, SessionDataResponse, CreateSessionKeyParams, SessionConfig, Call as Call$1, SpendingPolicyConfig, SpendingPolicyData, MigrateWalletToPasskeyParams, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, TransferHookInput, ApproveHookInput, GetTransactionListQuery, PaginatedResponse, Transaction, TransactionStatusResponse, SyncOnChainTransfersParams, SyncOnChainTransfersResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, CallAnyContractParams, RecordSendTransactionParams, GetTokenBalanceParams, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, ExecuteWithSessionParams, PaymentRequirement, PaymentPayload } from '@chipi-stack/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { MigrateChipiWalletToShhhParams, MigrationOutcome, Eip191Pubkey, WebAuthnPubkey, JwtAppleSubPubkey, NewOwnerInput, buildProposeAddOwnerCall, TIMELOCK_SECONDS, DEFAULT_OP_EXPIRY_SECONDS, ROLE_OWNER, ROLE_GUARDIAN, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, ShhhSignerKind, MIN_THRESHOLD_OWNERS } from '@chipi-stack/backend';
 
 type CreateWalletInput = {
     params: CreateWalletParams;
@@ -386,7 +387,7 @@ interface UseChipiSessionReturn {
     /** Revoke the current session from the blockchain */
     revokeSession: () => Promise<string>;
     /** Execute calls using the session key (no owner signature needed) */
-    executeWithSession: (calls: Call[]) => Promise<string>;
+    executeWithSession: (calls: Call$1[]) => Promise<string>;
     /** Clear the current session from local state */
     clearSession: () => void;
     /** Refresh the on-chain session status */
@@ -521,6 +522,82 @@ declare function useUpdateWalletEncryption(): {
     reset: () => void;
 };
 
+/**
+ * Input for the migration mutation.
+ *
+ * Drops `client` and `bearerToken` from the SDK-level params (the
+ * hook reads them from context + the input below) and treats the
+ * rest the same as the SDK call. The hook does NOT touch passkey /
+ * PIN orchestration — callers are responsible for handing in the
+ * already-resolved `encryptKey`. For the dashboard flow this means
+ * showing the PIN/passkey prompt yourself and passing the result
+ * here.
+ */
+type MigrateInput = Omit<MigrateChipiWalletToShhhParams, "client" | "bearerToken"> & {
+    bearerToken: string;
+};
+/**
+ * Hook for migrating a CHIPI v29 wallet to SHHH V8.4.
+ *
+ * Wraps the `migrateChipiWalletToShhh` backend SDK function (which
+ * itself composes chipi-back's prepare + execute endpoints with
+ * client-side V8.4 OE signing). The PIN/passkey unwrap step happens
+ * before this hook is called; the migration multicall is signed
+ * locally with the resulting STARK key and the cleartext key never
+ * leaves the device.
+ *
+ * Two terminal outcomes the consumer must handle:
+ *   - `{ kind: "MIGRATED", transactionHash, ... }` — happy path,
+ *     on-chain tx landed and DB row is patched. If `partial: true`,
+ *     the on-chain tx succeeded but the chipi-back DB patch failed;
+ *     the operator runbook's reconciler cron (task #30) will catch
+ *     up automatically. Dashboard should surface "wallet upgraded;
+ *     refresh in a moment" copy in both sub-cases.
+ *   - `{ kind: "ALREADY_MIGRATED", primaryKind, ... }` — chipi-back
+ *     detected the wallet was already SHHH on chain and patched the
+ *     DB row on the way out. No on-chain tx fired. Dashboard should
+ *     surface "this wallet is already on V8.4" and refresh the
+ *     wallet shape.
+ *
+ * Throws (surfaces via `error`) on:
+ *   - STRANDED-state recovery (different signing flow, not in PR A)
+ *   - UNDEPLOYED wallets (caller should redirect to createWallet)
+ *   - DEFERRED legacy versions (v28/v33; not yet supported)
+ *   - Mismatched encryptKey (decryption fails)
+ *   - chipi-back kill switch off (`CHIPI_MIGRATION_ENABLED` not set)
+ *
+ * @example
+ * ```tsx
+ * const { migrateAsync, isLoading, error } = useMigrateWalletToShhh();
+ *
+ * async function onClickMigrate() {
+ *   const encryptKey = await promptForPin();   // or passkey unlock
+ *   const outcome = await migrateAsync({
+ *     walletId: wallet.id,
+ *     externalUserId: user.id,
+ *     wallet: { publicKey: wallet.publicKey, encryptedPrivateKey: wallet.encryptedPrivateKey },
+ *     encryptKey,
+ *     bearerToken,
+ *   });
+ *   if (outcome.kind === "MIGRATED") {
+ *     showToast(`Wallet upgraded — tx ${outcome.transactionHash}`);
+ *   } else {
+ *     showToast(`Wallet was already on V8.4 (${outcome.primaryKind})`);
+ *   }
+ * }
+ * ```
+ */
+declare function useMigrateWalletToShhh(): {
+    migrate: (input: MigrateInput) => void;
+    migrateAsync: (input: MigrateInput) => Promise<MigrationOutcome>;
+    data: MigrationOutcome | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    isSuccess: boolean;
+    reset: () => void;
+};
+
 type TransferInput = {
     params: TransferHookInput;
     bearerToken: string;
@@ -2189,4 +2266,354 @@ interface UseX402PaymentReturn {
  */
 declare function useX402Payment(config: UseX402PaymentConfig): UseX402PaymentReturn;
 
-export { type ChipiWalletData, type SessionState, type SessionWallet, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseTransferConfig, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useMigrateWalletToPasskey, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useSyncOnChainTransfers, useTransfer, useUpdateWalletEncryption, useX402Payment };
+/**
+ * SHHH V8.4 envelope builders surfaced as a single hook for React
+ * integrators. Each helper returns the `signature: felt252[]` span
+ * ready to pass to `paymaster_executeSponsoredRaw.calldata`.
+ *
+ * Most helpers take the OE `messageHash` plus kind-specific inputs.
+ * `signWithMetaMask` is the exception: the `messageHash` is already
+ * baked into the user-signed payload upstream, so it takes only the
+ * 65-byte `personal_sign` signature and the registered pubkey.
+ *
+ * The hook is intentionally a thin facade over the
+ * `@chipi-stack/backend` builders: it adds semantic names that map
+ * to the user-facing wallet (`signWithMetaMask` = EIP-191,
+ * `signWithPhantom` = Ed25519, `signWithPasskey` = WebAuthn P-256)
+ * and stable React refs, but does NOT do browser-glue (no
+ * `window.ethereum`, `window.solana`, or `navigator.credentials.get`
+ * calls). Integrators retain full control of the user-prompt step:
+ *
+ * 1. Integrator calls their wallet adapter to get the raw signature
+ *    (or assertion / id_token).
+ * 2. Integrator passes that into the matching helper to wrap it into
+ *    the V2_SNIP12 envelope.
+ *
+ * Pair with `useGuardianRecovery` or `useThresholdSign` (B6/B7) for
+ * on-chain execution flows that need the recovery/governance builders.
+ */
+interface UseShhhSignerReturn {
+    /**
+     * STARK ECDSA signer (legacy CHIPI v29 keys, fastest path).
+     * Pure-local: no wallet prompt.
+     */
+    signWithStark: (params: {
+        privateKey: bigint | string;
+        messageHash: bigint;
+    }) => bigint[];
+    /**
+     * Phantom-shape Ed25519 signer (Solana users importing to Starknet).
+     * The 32-byte private key is the Solana keypair's secret material;
+     * the public key is recovered inside the builder.
+     */
+    signWithPhantom: (params: {
+        privateKey: Uint8Array;
+        messageHash: bigint;
+    }) => Promise<bigint[]>;
+    /**
+     * MetaMask-shape EIP-191 (`personal_sign`) signer. The signature
+     * MUST come from a `personal_sign` over the 32-byte big-endian
+     * messageHash; the pubkey was registered at wallet creation time.
+     */
+    signWithMetaMask: (params: {
+        signatureHex: string;
+        pubkey: Eip191Pubkey;
+    }) => bigint[];
+    /**
+     * WebAuthn P-256 signer (passkey). Takes a completed
+     * `navigator.credentials.get()` assertion split into its three
+     * fields (authenticatorData, clientDataJSON, signature DER) plus
+     * the pubkey registered at credential creation time.
+     */
+    signWithPasskey: (params: {
+        authenticatorData: Uint8Array;
+        clientDataJSON: Uint8Array;
+        signatureDer: Uint8Array;
+        pubkey: WebAuthnPubkey;
+        messageHash: bigint;
+        yParity?: 0n | 1n;
+    }) => bigint[];
+    /**
+     * Apple Sign In signer (`JWT_ES256_APPLE_SUB`). Takes the
+     * `id_token` from Apple's OAuth response. The nonce claim MUST
+     * encode `messageHash` (see `messageHashToNonceB64url`).
+     */
+    signWithAppleIdToken: (params: {
+        idToken: string;
+        pubkey: JwtAppleSubPubkey;
+        messageHash: bigint;
+    }) => bigint[];
+}
+declare function useShhhSigner(): UseShhhSignerReturn;
+
+type Call = ReturnType<typeof buildProposeAddOwnerCall>;
+/**
+ * SHHH V8.4 multi-owner governance + guardian-recovery builders
+ * surfaced as a single React hook. Each helper returns a Starknet
+ * `Call` object (NOT a signature envelope); callers compose those
+ * calls into an OutsideExecution and submit them via the paymaster
+ * adapter, signing the OE with `useShhhSigner`.
+ *
+ * Two top-level flows are intended:
+ *
+ *   1. ADD DEVICE (user has wallet access, wants a second owner)
+ *      a. `proposeAddOwner` (owner-signed OE)
+ *      b. wait 48h timelock
+ *      c. `executeAddOwner` (owner-signed OE, with the opId from 1a)
+ *
+ *   2. RECOVER VIA GUARDIAN (user lost key)
+ *      a. `initiateRecovery` (guardian-signed OE)
+ *      b. wait 7 days
+ *      c. `finalizeRecovery` (anyone can submit, no signature required
+ *         beyond Cairo-side state checks)
+ *
+ * Read-only timelock helpers (`isReady`, `secondsRemaining`) take a
+ * `validAfter` timestamp pulled from chain state and a clock reading;
+ * they don't query the chain themselves. Pair this hook with whatever
+ * mechanism your app already uses for on-chain state reads
+ * (`useGetWallet`, RPC, multicall, etc.).
+ *
+ * The full controlled-component `<Recover />` route that wires this
+ * hook into a state machine + UI ships as B6.2.
+ */
+interface UseGuardianRecoveryReturn {
+    buildProposeAddOwner: (args: {
+        walletAddress: bigint | string;
+        proposer: number;
+        newOwner: NewOwnerInput;
+    }) => Call;
+    buildExecuteAddOwner: (args: {
+        walletAddress: bigint | string;
+        opId: bigint | string;
+        newOwner: NewOwnerInput;
+    }) => Call;
+    buildProposeRemoveOwner: (args: {
+        walletAddress: bigint | string;
+        proposer: number;
+        ownerId: number;
+    }) => Call;
+    buildExecuteRemoveOwner: (args: {
+        walletAddress: bigint | string;
+        opId: bigint | string;
+        ownerId: number;
+    }) => Call;
+    buildProposeRotateOwner: (args: {
+        walletAddress: bigint | string;
+        proposer: number;
+        ownerId: number;
+        newPubkeyBytes: bigint[];
+    }) => Call;
+    buildExecuteRotateOwner: (args: {
+        walletAddress: bigint | string;
+        opId: bigint | string;
+        ownerId: number;
+        newPubkeyBytes: bigint[];
+    }) => Call;
+    buildProposeSetThreshold: (args: {
+        walletAddress: bigint | string;
+        proposer: number;
+        newThreshold: number;
+    }) => Call;
+    buildExecuteSetThreshold: (args: {
+        walletAddress: bigint | string;
+        opId: bigint | string;
+        newThreshold: number;
+    }) => Call;
+    buildCancelPendingOp: (args: {
+        walletAddress: bigint | string;
+        opId: bigint | string;
+    }) => Call;
+    buildInitiateRecovery: (args: {
+        walletAddress: bigint | string;
+        /** owner_id of the guardian that's signing the initiation OE */
+        proposer: number;
+        newOwner: NewOwnerInput;
+    }) => Call;
+    buildCancelRecovery: (args: {
+        walletAddress: bigint | string;
+        ownerId: number;
+    }) => Call;
+    buildFinalizeRecovery: (args: {
+        walletAddress: bigint | string;
+        newOwner: NewOwnerInput;
+    }) => Call;
+    isReady: (validAfterSecs: number | bigint, nowSecs?: number) => boolean;
+    secondsRemaining: (validAfterSecs: number | bigint, nowSecs?: number) => number;
+    TIMELOCK_SECONDS: typeof TIMELOCK_SECONDS;
+    DEFAULT_OP_EXPIRY_SECONDS: typeof DEFAULT_OP_EXPIRY_SECONDS;
+    ROLE_OWNER: typeof ROLE_OWNER;
+    ROLE_GUARDIAN: typeof ROLE_GUARDIAN;
+    OP_ADD_OWNER: typeof OP_ADD_OWNER;
+    OP_REMOVE_OWNER: typeof OP_REMOVE_OWNER;
+    OP_ROTATE_OWNER: typeof OP_ROTATE_OWNER;
+    OP_SET_THRESHOLD: typeof OP_SET_THRESHOLD;
+}
+declare function useGuardianRecovery(): UseGuardianRecoveryReturn;
+
+/**
+ * SHHH V8.4 N-of-M threshold sign coordinator surfaced as a React
+ * hook. Two complementary surfaces:
+ *
+ *   1. **Stateless helpers** — `assemble`, `parse`, and
+ *      `estimateGasOverhead` are pure facades over the matching
+ *      `@chipi-stack/backend` builders. Use them when you already
+ *      have all the inner envelopes in one render and just want to
+ *      ship the final V2_THRESHOLD span.
+ *
+ *   2. **Stateful collector** — for UI flows where N owners sign
+ *      asynchronously (passkey on phone → MetaMask on laptop, agent
+ *      auto-co-signing while a human reviews, etc.) the hook keeps
+ *      a queue of collected inner envelopes, exposes a "X of N
+ *      signed" state for UI display, validates each new envelope at
+ *      add-time (duplicate owner_id detection, structural shape),
+ *      and assembles the final span once the threshold is met via
+ *      `finalize()`.
+ *
+ * The collector validates each envelope inline using
+ * `assertValidV2Snip12Envelope` from the backend — the same check the
+ * `buildThresholdEnvelope` builder runs at assembly time. That way an
+ * integrator's UI can show "owner 3 envelope rejected: duplicate
+ * owner_id" before submitting the V2_THRESHOLD span on chain, instead
+ * of after the paymaster reverts.
+ *
+ * Threshold governance (`propose_set_threshold` / `execute_set_threshold`)
+ * lives in `useGuardianRecovery` because the multi-owner signing
+ * here and the threshold-change proposals there share the same
+ * Cairo SHHH wallet but are operationally separate flows.
+ */
+interface UseThresholdSignReturn {
+    /**
+     * Assemble an N-of-M V2_THRESHOLD envelope from a pre-collected
+     * list of inner V2_SNIP12 envelopes. Pure; no internal state used.
+     * Throws on duplicate owner_id, structural mismatch, or negative
+     * felts — same validation the on-chain dispatch would apply.
+     */
+    assemble: (args: {
+        innerEnvelopes: bigint[][];
+    }) => bigint[];
+    /**
+     * Inverse of `assemble`. Re-derives the constituent inner envelopes
+     * from a V2_THRESHOLD span. Useful for UI flows showing "owners X,
+     * Y, Z signed" from a stored envelope without re-walking the
+     * collection state.
+     */
+    parse: (args: {
+        envelope: bigint[];
+    }) => {
+        innerEnvelopes: bigint[][];
+    };
+    /**
+     * Sum the per-kind paymaster gas overhead across the owners that
+     * will participate. Use this to surface "this 2-of-3 mixed-kind
+     * tx will cost X l2_gas to verify" copy in a UI.
+     *
+     * Per [services/gasless/signer-kinds#gas-overhead], a STARK +
+     * EIP-191 pair budgets 2M + 10M = 12M l2_gas for verification on
+     * top of the call's own cost.
+     */
+    estimateGasOverhead: (args: {
+        owners: Array<{
+            signerKind: ShhhSignerKind;
+        }>;
+    }) => number;
+    /**
+     * Live state machine. Re-renders the consuming component when an
+     * envelope is added, removed, or the collection is reset.
+     */
+    state: ThresholdSignState;
+    /**
+     * Add one owner's inner V2_SNIP12 envelope to the collection.
+     * Validates structurally + checks duplicate owner_id against
+     * already-collected envelopes.
+     *
+     * Returns `true` on success, `false` on rejection. On rejection
+     * the failure reason lands on `state.error` for inline UI display;
+     * the collection is NOT mutated. A subsequent successful add
+     * clears `state.error`.
+     *
+     * Idempotent in the sense that a second add of an already-rejected
+     * envelope produces the same error; an already-collected envelope
+     * (same owner_id) is treated as a duplicate.
+     */
+    addEnvelope: (envelope: bigint[]) => boolean;
+    /**
+     * Drop a previously-added envelope by its owner_id. Useful when
+     * an owner signs but the integrator's review UI rejects their
+     * specific tx and needs to ask them to re-sign with corrected
+     * payload.
+     */
+    removeEnvelope: (ownerId: bigint) => void;
+    /** Clear the entire collection (cancel + restart the sign flow). */
+    reset: () => void;
+    /**
+     * Assemble the final V2_THRESHOLD envelope from collected inner
+     * envelopes. Throws if fewer than `threshold` have been collected
+     * (with a clear error so the caller's UI knows to keep prompting).
+     */
+    finalize: () => bigint[];
+    MIN_THRESHOLD_OWNERS: typeof MIN_THRESHOLD_OWNERS;
+}
+interface ThresholdSignState {
+    /** Threshold N this flow is collecting toward. */
+    threshold: number;
+    /** Inner envelopes collected so far, in arrival order. */
+    collected: bigint[][];
+    /**
+     * Owner ids that have signed, in arrival order. Pre-derived from
+     * `collected` so the UI doesn't have to re-parse each envelope.
+     */
+    signedOwnerIds: bigint[];
+    /** Has the threshold been met? `collected.length >= threshold`. */
+    isReady: boolean;
+    /**
+     * The most recent validation error from `addEnvelope`, if any.
+     * Cleared on successful add or `reset()`. Use for inline UI error
+     * display ("Owner X already signed", "envelope is malformed").
+     */
+    error: Error | null;
+}
+interface UseThresholdSignOptions {
+    /**
+     * Threshold N this flow targets. Must be at least
+     * `MIN_THRESHOLD_OWNERS` (2). Changes to this value after first
+     * render are honored — `isReady` re-evaluates against the new N
+     * without dropping already-collected envelopes (use `reset` if
+     * you need to start over).
+     */
+    threshold: number;
+}
+/**
+ * SHHH V8.4 threshold sign coordinator.
+ *
+ * @example Pure assembly (all envelopes ready in one render)
+ *
+ * ```tsx
+ * const t = useThresholdSign({ threshold: 2 });
+ * const envelope = t.assemble({
+ *   innerEnvelopes: [starkInner, eip191Inner],
+ * });
+ * await submitThroughPaymaster(envelope);
+ * ```
+ *
+ * @example Async sign flow (owners sign one at a time)
+ *
+ * ```tsx
+ * const t = useThresholdSign({ threshold: 2 });
+ *
+ * // After owner 1 signs:
+ * t.addEnvelope(owner1Envelope);
+ *
+ * // After owner 2 signs:
+ * t.addEnvelope(owner2Envelope);
+ *
+ * // UI shows "Signed by: owner_id_1, owner_id_2" via t.state.signedOwnerIds.
+ * // When t.state.isReady is true, submit:
+ * if (t.state.isReady) {
+ *   const envelope = t.finalize();
+ *   await submitThroughPaymaster(envelope);
+ * }
+ * ```
+ */
+declare function useThresholdSign(opts: UseThresholdSignOptions): UseThresholdSignReturn;
+
+export { type ChipiWalletData, type SessionState, type SessionWallet, type ThresholdSignState, type UseChipiSessionConfig, type UseChipiSessionReturn, type UseChipiWalletConfig, type UseChipiWalletReturn, type UseGuardianRecoveryReturn, type UseShhhSignerReturn, type UseThresholdSignOptions, type UseThresholdSignReturn, type UseTransferConfig, type UseX402PaymentConfig, type UseX402PaymentReturn, useAddSessionKeyToContract, useApprove, useCallAnyContract, useChipiSession, useChipiWallet, useCreateSessionKey, useCreateWallet, useExecuteWithSession, useGetSessionData, useGetSku, useGetSkuList, useGetSkuPurchase, useGetTokenBalance, useGetTransaction, useGetTransactionList, useGetTransactionStatus, useGetWallet, useGuardianRecovery, useMigrateWalletToPasskey, useMigrateWalletToShhh, usePurchaseSku, useRecordSendTransaction, useRevokeSessionKey, useShhhSigner, useSyncOnChainTransfers, useThresholdSign, useTransfer, useUpdateWalletEncryption, useX402Payment };

package/dist/hooks.js

@@ -666,6 +666,25 @@ function useUpdateWalletEncryption() {
     reset: mutation.reset
   };
 }
+function useMigrateWalletToShhh() {
+  const { chipiSDK } = useChipiContext();
+  const mutation = reactQuery.useMutation({
+    mutationFn: async (input) => {
+      const { bearerToken, ...rest } = input;
+      return chipiSDK.wallets.migrateToShhh(rest, bearerToken);
+    }
+  });
+  return {
+    migrate: mutation.mutate,
+    migrateAsync: mutation.mutateAsync,
+    data: mutation.data,
+    isLoading: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    isSuccess: mutation.isSuccess,
+    reset: mutation.reset
+  };
+}
 function useTransfer(config) {
   const { chipiSDK, passkeyAdapter } = useChipiContext();
   const mutation = reactQuery.useMutation({
@@ -1551,6 +1570,145 @@ function useX402Payment(config) {
     paymentCount
   };
 }
+function useShhhSigner() {
+  return react.useMemo(
+    () => ({
+      signWithStark: (params) => backend.buildStarkEnvelope({
+        privateKey: params.privateKey,
+        messageHash: params.messageHash
+      }),
+      signWithPhantom: (params) => backend.buildEd25519Envelope({
+        privateKey: params.privateKey,
+        messageHash: params.messageHash
+      }),
+      signWithMetaMask: (params) => backend.buildEip191EnvelopeFromSignature({
+        signatureHex: params.signatureHex,
+        pubkey: params.pubkey
+      }),
+      signWithPasskey: (params) => backend.buildWebAuthnEnvelopeFromAssertion({
+        authenticatorData: params.authenticatorData,
+        clientDataJSON: params.clientDataJSON,
+        signatureDer: params.signatureDer,
+        pubkey: params.pubkey,
+        messageHash: params.messageHash,
+        yParity: params.yParity ?? 0n
+      }),
+      signWithAppleIdToken: (params) => backend.buildJwtAppleSubEnvelopeFromTokenResponse({
+        idToken: params.idToken,
+        pubkey: params.pubkey,
+        messageHash: params.messageHash
+      })
+    }),
+    []
+  );
+}
+function useGuardianRecovery() {
+  return react.useMemo(
+    () => ({
+      buildProposeAddOwner: (args) => backend.buildProposeAddOwnerCall(args),
+      buildExecuteAddOwner: (args) => backend.buildExecuteAddOwnerCall(args),
+      buildProposeRemoveOwner: (args) => backend.buildProposeRemoveOwnerCall(args),
+      buildExecuteRemoveOwner: (args) => backend.buildExecuteRemoveOwnerCall(args),
+      buildProposeRotateOwner: (args) => backend.buildProposeRotateOwnerCall(args),
+      buildExecuteRotateOwner: (args) => backend.buildExecuteRotateOwnerCall(args),
+      buildProposeSetThreshold: (args) => backend.buildProposeSetThresholdCall(args),
+      buildExecuteSetThreshold: (args) => backend.buildExecuteSetThresholdCall(args),
+      buildCancelPendingOp: (args) => backend.buildCancelPendingOpCall(args),
+      buildInitiateRecovery: (args) => backend.buildInitiateRecoveryCall(args),
+      buildCancelRecovery: (args) => backend.buildCancelRecoveryCall(args),
+      buildFinalizeRecovery: (args) => backend.buildFinalizeRecoveryCall(args),
+      isReady: (validAfterSecs, nowSecs) => backend.isReadyToExecute(validAfterSecs, nowSecs ?? Math.floor(Date.now() / 1e3)),
+      secondsRemaining: (validAfterSecs, nowSecs) => backend.secondsUntilExecutable(validAfterSecs, nowSecs ?? Math.floor(Date.now() / 1e3)),
+      TIMELOCK_SECONDS: backend.TIMELOCK_SECONDS,
+      DEFAULT_OP_EXPIRY_SECONDS: backend.DEFAULT_OP_EXPIRY_SECONDS,
+      ROLE_OWNER: backend.ROLE_OWNER,
+      ROLE_GUARDIAN: backend.ROLE_GUARDIAN,
+      OP_ADD_OWNER: backend.OP_ADD_OWNER,
+      OP_REMOVE_OWNER: backend.OP_REMOVE_OWNER,
+      OP_ROTATE_OWNER: backend.OP_ROTATE_OWNER,
+      OP_SET_THRESHOLD: backend.OP_SET_THRESHOLD
+    }),
+    []
+  );
+}
+function useThresholdSign(opts) {
+  const { threshold } = opts;
+  const [collected, setCollected] = react.useState([]);
+  const [signedOwnerIds, setSignedOwnerIds] = react.useState([]);
+  const [error, setError] = react.useState(null);
+  const signedOwnerIdsRef = react.useRef([]);
+  const addEnvelope = react.useCallback((envelope) => {
+    let ownerId;
+    try {
+      ownerId = backend.assertValidV2Snip12Envelope(envelope);
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      setError(err);
+      return false;
+    }
+    if (signedOwnerIdsRef.current.some((id) => id === ownerId)) {
+      const err = new Error(
+        `THRESH: owner_id 0x${ownerId.toString(16)} has already signed; use removeEnvelope first if you want to replace their envelope.`
+      );
+      setError(err);
+      return false;
+    }
+    signedOwnerIdsRef.current = [...signedOwnerIdsRef.current, ownerId];
+    setCollected((prev) => [...prev, envelope]);
+    setSignedOwnerIds(signedOwnerIdsRef.current);
+    setError(null);
+    return true;
+  }, []);
+  const removeEnvelope = react.useCallback((ownerId) => {
+    const matchIndex = signedOwnerIdsRef.current.findIndex((id) => id === ownerId);
+    if (matchIndex < 0) return;
+    signedOwnerIdsRef.current = signedOwnerIdsRef.current.filter((id) => id !== ownerId);
+    setCollected((prev) => prev.filter((_, i) => i !== matchIndex));
+    setSignedOwnerIds(signedOwnerIdsRef.current);
+    setError(null);
+  }, []);
+  const reset = react.useCallback(() => {
+    signedOwnerIdsRef.current = [];
+    setCollected([]);
+    setSignedOwnerIds([]);
+    setError(null);
+  }, []);
+  const finalize = react.useCallback(() => {
+    if (collected.length < threshold) {
+      throw new Error(
+        `THRESH: cannot finalize \u2014 need ${threshold} envelopes, have ${collected.length}. Wait for more owners to sign.`
+      );
+    }
+    return backend.buildThresholdEnvelope({ innerEnvelopes: collected });
+  }, [collected, threshold]);
+  const state = react.useMemo(
+    () => ({
+      threshold,
+      collected,
+      signedOwnerIds,
+      isReady: collected.length >= threshold,
+      error
+    }),
+    [threshold, collected, signedOwnerIds, error]
+  );
+  const stateless = react.useMemo(
+    () => ({
+      assemble: (args) => backend.buildThresholdEnvelope(args),
+      parse: (args) => backend.parseThresholdEnvelope(args.envelope),
+      estimateGasOverhead: (args) => backend.estimateThresholdGasOverhead(args.owners),
+      MIN_THRESHOLD_OWNERS: backend.MIN_THRESHOLD_OWNERS
+    }),
+    []
+  );
+  return {
+    ...stateless,
+    state,
+    addEnvelope,
+    removeEnvelope,
+    reset,
+    finalize
+  };
+}
 
 exports.useAddSessionKeyToContract = useAddSessionKeyToContract;
 exports.useApprove = useApprove;
@@ -1569,11 +1727,15 @@ exports.useGetTransaction = useGetTransaction;
 exports.useGetTransactionList = useGetTransactionList;
 exports.useGetTransactionStatus = useGetTransactionStatus;
 exports.useGetWallet = useGetWallet;
+exports.useGuardianRecovery = useGuardianRecovery;
 exports.useMigrateWalletToPasskey = useMigrateWalletToPasskey;
+exports.useMigrateWalletToShhh = useMigrateWalletToShhh;
 exports.usePurchaseSku = usePurchaseSku;
 exports.useRecordSendTransaction = useRecordSendTransaction;
 exports.useRevokeSessionKey = useRevokeSessionKey;
+exports.useShhhSigner = useShhhSigner;
 exports.useSyncOnChainTransfers = useSyncOnChainTransfers;
+exports.useThresholdSign = useThresholdSign;
 exports.useTransfer = useTransfer;
 exports.useUpdateWalletEncryption = useUpdateWalletEncryption;
 exports.useX402Payment = useX402Payment;