@unlink-xyz/react 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# @unlink-xyz/react
+
+React hooks for building private transaction applications with Unlink.
+
+## Overview
+
+Provides wallet management, account handling, private transfers, and withdrawals with automatic state synchronization via React hooks and context. Wraps `@unlink-xyz/core` for React 18/19 applications.
+
+> **Documentation:** [React guide](../../docs/sdk/react.mdx) | [API reference](../../docs/sdk/api-reference.mdx)

package/dist/index.d.ts

@@ -0,0 +1,552 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { BrowserWalletOptions, Environment, UnlinkWallet, AccountInfo, Account, NoteRecord, HistoryStatus, TransferResult, TransferPlanResult, DepositRelayResult, WithdrawalInput, WithdrawResult, WithdrawPlanResult, RelayState, HistoryEntry } from '@unlink-xyz/core';
+export { Account, AccountInfo, Chain, HistoryEntry, NoteRecord, ParsedZkAddress, TransferPlanResult, TransferResult, TxStatusChangedEvent, UnlinkWallet, WalletSDKEvent, WithdrawPlanResult, WithdrawResult, computeBalances, decodeAddress, encodeAddress, formatAmount, normalizeAddress, parseAmount, parseZkAddress, randomHex, shortenHex } from '@unlink-xyz/core';
+
+/**
+ * Wallet note with value as bigint for convenience.
+ */
+type WalletNote = Omit<NoteRecord, "value"> & {
+    value: bigint;
+};
+/** Shared fields for all pending job types. */
+type PendingJobBase = {
+    txId: string;
+    status: HistoryStatus;
+    chainId: number;
+    token: string;
+    amount: bigint;
+    startedAt: number;
+    txHash?: string;
+    confirmedAt?: number;
+};
+type PendingDepositJob = PendingJobBase & {
+    commitment?: string;
+};
+type PendingTransferJob = PendingJobBase & {
+    recipient: string;
+};
+type PendingWithdrawJob = PendingJobBase & {
+    recipient: string;
+};
+/**
+ * Base configuration shared by all UnlinkProvider variants.
+ */
+type UnlinkConfigBase = {
+    /** Chain ID for the target blockchain */
+    chainId: number;
+    /** Auto-sync interval in milliseconds (default: 5000) */
+    syncInterval?: number;
+    /** Whether to start auto-sync on mount (default: true) */
+    autoSync?: boolean;
+    /** Optional prover/artifact source override */
+    prover?: BrowserWalletOptions["prover"];
+};
+/**
+ * Configuration for the UnlinkProvider.
+ * Either provide explicit gatewayUrl + poolAddress, or environment to auto-resolve.
+ */
+type UnlinkConfig = UnlinkConfigBase & ({
+    /** Explicit gateway URL - requires poolAddress */
+    gatewayUrl: string;
+    poolAddress: string;
+    environment?: never;
+} | {
+    /** Environment to use from the config file */
+    environment: Environment;
+    /** Pool contract address - optional, defaults to environment config */
+    poolAddress?: string;
+    gatewayUrl?: never;
+});
+/**
+ * State exposed by the useUnlink hook.
+ */
+type UnlinkState = {
+    /** The underlying wallet instance */
+    wallet: UnlinkWallet | null;
+    /** Whether a wallet (mnemonic) exists */
+    walletExists: boolean;
+    /** All derived accounts */
+    accounts: AccountInfo[];
+    /** Current active account (null if not created yet) */
+    activeAccount: Account | null;
+    /** Current active account index (null if none) */
+    activeAccountIndex: number | null;
+    /** Chain ID configured for this provider */
+    chainId: number;
+    /** User's notes with value as bigint */
+    notes: WalletNote[];
+    /** Token balances by address */
+    balances: Record<string, bigint>;
+    /** Pending deposit jobs */
+    pendingDeposits: PendingDepositJob[];
+    /** Pending transfer jobs */
+    pendingTransfers: PendingTransferJob[];
+    /** Pending withdraw jobs */
+    pendingWithdrawals: PendingWithdrawJob[];
+    /** Whether the SDK is initialized and ready */
+    ready: boolean;
+    /** Whether an operation is in progress */
+    busy: boolean;
+    /** Current status message */
+    status: string;
+    /** Last sync error message, or null if sync is healthy */
+    syncError: string | null;
+    /** Current error state (null if no error) */
+    error: UnlinkError | null;
+};
+/**
+ * Transfer parameters for useUnlink.send()
+ */
+type TransferInput = {
+    token: string;
+    /** Unlink address (0zk1... bech32m) */
+    recipient: string;
+    amount: bigint;
+};
+/**
+ * Deposit parameters for useUnlink.deposit()
+ */
+type DepositInput = {
+    token: string;
+    amount: bigint;
+    /** On-chain depositor address */
+    depositor: string;
+};
+/**
+ * Withdraw parameters for useUnlink.requestWithdraw()
+ */
+type WithdrawInput = WithdrawalInput;
+/**
+ * Actions exposed by the useUnlink hook.
+ */
+type UnlinkActions = {
+    /** Create a new wallet. Returns mnemonic for backup. */
+    createWallet(): Promise<{
+        mnemonic: string;
+    }>;
+    /** Import an existing mnemonic */
+    importWallet(mnemonic: string): Promise<void>;
+    /** Export the stored mnemonic for backup */
+    exportMnemonic(): Promise<string>;
+    /** Clear all wallet data (destructive) */
+    clearWallet(): Promise<void>;
+    /** Create a new account at the specified or next available index */
+    createAccount(index?: number): Promise<Account>;
+    /** Switch to a different account by index */
+    switchAccount(index: number): Promise<void>;
+    /**
+     * High-level send (1 or more transfers).
+     * Multiple transfers are processed atomically.
+     *
+     * @param params - Array of transfers (token + amount + recipient)
+     * @returns TransferResult with array of plans
+     */
+    send(params: TransferInput[]): Promise<TransferResult>;
+    /**
+     * Get a transfer plan without executing (for preview).
+     * Validates balances and returns plans for each transfer.
+     *
+     * @param params - Array of transfers (token + amount + recipient)
+     * @returns Array of TransactionPlan
+     */
+    planTransfer(params: TransferInput[]): Promise<TransferPlanResult>;
+    /** Execute a pre-built transfer plan */
+    executeTransfer(plans: TransferPlanResult): Promise<TransferResult>;
+    /**
+     * Request a deposit (1 or more tokens).
+     * Returns calldata that the user must submit on-chain via their EOA.
+     * Use the returned `to` and `calldata` fields to construct the transaction.
+     *
+     * @param params - Array of deposits (token + amount + depositor)
+     * @returns DepositRelayResult with array of commitments
+     */
+    requestDeposit(params: DepositInput[]): Promise<DepositRelayResult>;
+    /**
+     * High-level withdraw (1 or more tokens).
+     * Specify recipient EOA + amount for each withdrawal.
+     * Multiple withdrawals are processed atomically.
+     *
+     * @param params - Array of withdrawals (token + amount + recipient)
+     * @returns WithdrawResult with array of plans
+     */
+    requestWithdraw(params: WithdrawInput[]): Promise<WithdrawResult>;
+    /**
+     * Get a withdrawal plan without executing (for preview).
+     * Validates balances and returns plans for each withdrawal.
+     *
+     * @param params - Array of withdrawals (token + amount + recipient)
+     * @returns Array of WithdrawalPlan
+     */
+    planWithdraw(params: WithdrawInput[]): Promise<WithdrawPlanResult>;
+    /** Execute a pre-built withdrawal plan */
+    executeWithdraw(plans: WithdrawPlanResult): Promise<WithdrawResult>;
+    /** Refresh notes and balances */
+    refresh(): Promise<void>;
+    /** Force full resync from chain */
+    forceResync(): Promise<void>;
+    /** Clear the current error state */
+    clearError(): void;
+    /**
+     * Get the current status of a transaction.
+     *
+     * @param txId - The transaction ID returned from deposit, transfer, or withdraw operations
+     * @returns The current status of the transaction
+     */
+    getTxStatus(txId: string): Promise<TxStatus>;
+    /**
+     * Wait for a transaction to reach a terminal state.
+     * Resolves when state is 'succeeded', throws on 'reverted'/'failed'/'dead' or timeout.
+     *
+     * @param txId - The transaction ID returned from deposit, transfer, or withdraw operations
+     * @param options - Optional configuration (timeout)
+     * @returns The final transaction status on success
+     * @throws TimeoutError if timeout exceeded
+     * @throws TransactionFailedError if transaction fails
+     */
+    waitForConfirmation(txId: string, options?: WaitForConfirmationOptions): Promise<TxStatus>;
+};
+/**
+ * Complete value returned by useUnlink hook.
+ */
+type UnlinkContextValue = UnlinkState & UnlinkActions;
+type TxState = RelayState;
+/** Terminal states that indicate a transaction has finished processing */
+declare const TERMINAL_TX_STATES: readonly TxState[];
+/** Default timeout for waitForConfirmation (5 minutes) */
+declare const DEFAULT_CONFIRMATION_TIMEOUT_MS: number;
+/** Poll interval for waitForConfirmation (2 seconds) */
+declare const CONFIRMATION_POLL_INTERVAL_MS = 2000;
+/**
+ * Status information for a transaction.
+ */
+type TxStatus = {
+    txId: string;
+    state: TxState;
+    txHash?: string;
+    blockNumber?: number;
+    error?: string;
+};
+/**
+ * Result from the useTxStatus hook.
+ */
+type UseTxStatusResult = {
+    state: TxState | null;
+    txHash: string | null;
+    blockNumber: number | null;
+    error: string | null;
+    isLoading: boolean;
+    refresh: () => Promise<void>;
+};
+/**
+ * Options for waitForConfirmation.
+ */
+type WaitForConfirmationOptions = {
+    /** Timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeout?: number;
+};
+/**
+ * Error thrown when a transaction times out.
+ */
+declare class TimeoutError extends Error {
+    readonly txId: string;
+    readonly timeout: number;
+    constructor(txId: string, timeout: number);
+}
+/**
+ * Error thrown when a transaction fails.
+ */
+declare class TransactionFailedError extends Error {
+    readonly txId: string;
+    readonly state: TxState;
+    readonly reason?: string;
+    constructor(txId: string, state: TxState, reason?: string);
+}
+/**
+ * Error codes for categorizing errors in the Unlink context.
+ */
+type UnlinkErrorCode = "UNKNOWN" | "SDK_NOT_INITIALIZED" | "NETWORK_ERROR" | "VALIDATION_ERROR" | "PROOF_ERROR" | "TIMEOUT" | "TRANSACTION_FAILED";
+/**
+ * Operations that can trigger an error in the Unlink context.
+ */
+type UnlinkErrorOperation = "init" | "createWallet" | "importWallet" | "clearWallet" | "createAccount" | "switchAccount" | "send" | "executeTransfer" | "requestDeposit" | "requestWithdraw" | "executeWithdraw" | "refresh" | "forceResync";
+/**
+ * Structured error type for the Unlink context.
+ */
+type UnlinkError = {
+    code: UnlinkErrorCode;
+    message: string;
+    operation: UnlinkErrorOperation;
+    timestamp: number;
+    details?: unknown;
+};
+
+type UnlinkProviderProps = UnlinkConfig & {
+    children: ReactNode;
+};
+declare function UnlinkProvider({ children, chainId, poolAddress, syncInterval, autoSync, gatewayUrl, environment, prover, }: UnlinkProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Hook to access the Unlink wallet SDK.
+ *
+ * Must be used within an UnlinkProvider.
+ *
+ * @example
+ * ```tsx
+ * function SendButton() {
+ *   const { send, balances, ready, busy } = useUnlink();
+ *
+ *   const handleSend = async () => {
+ *     await send({
+ *       token: "0x...",
+ *       recipient: "0x...",
+ *       amount: 100n,
+ *     });
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSend} disabled={!ready || busy}>
+ *       Send
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useUnlink(): UnlinkContextValue;
+
+type UseUnlinkHistoryOptions = {
+    /** Include self-sends in history (transfers to own address) */
+    includeSelfSends?: boolean;
+};
+type UseUnlinkHistoryResult = {
+    history: HistoryEntry[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Hook to get transaction history for the wallet.
+ *
+ * Uses the SDK's history service which provides properly categorized
+ * transaction entries (Deposit, Receive, Send, SelfSend, Withdraw).
+ *
+ * @example
+ * ```tsx
+ * function History() {
+ *   const { history, loading } = useUnlinkHistory();
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {history.map((entry) => (
+ *         <li key={entry.id}>
+ *           {entry.kind}: {entry.amounts[0]?.delta}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useUnlinkHistory(options?: UseUnlinkHistoryOptions): UseUnlinkHistoryResult;
+
+type UseUnlinkBalanceResult = {
+    /** Balance for the token (0n if not found) */
+    balance: bigint;
+    /** Whether the SDK is ready */
+    ready: boolean;
+    /** Whether data is loading */
+    loading: boolean;
+};
+/**
+ * Hook to get the balance for a specific token.
+ *
+ * @param token - Token address to get balance for
+ *
+ * @example
+ * ```tsx
+ * function TokenBalance({ token }: { token: string }) {
+ *   const { balance, ready } = useUnlinkBalance(token);
+ *
+ *   if (!ready) return <div>Loading...</div>;
+ *
+ *   return <div>Balance: {balance.toString()}</div>;
+ * }
+ * ```
+ */
+declare function useUnlinkBalance(token: string): UseUnlinkBalanceResult;
+/**
+ * Hook to get all token balances.
+ *
+ * @example
+ * ```tsx
+ * function AllBalances() {
+ *   const { balances, ready } = useUnlinkBalances();
+ *
+ *   if (!ready) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {Object.entries(balances).map(([token, balance]) => (
+ *         <li key={token}>
+ *           {token}: {balance.toString()}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useUnlinkBalances(): {
+    balances: Record<string, bigint>;
+    ready: boolean;
+    loading: boolean;
+};
+
+/**
+ * Hook to track the status of a transaction.
+ *
+ * Subscribes to 'tx-status-changed' events from the wallet for real-time updates.
+ * The SDK automatically polls the broadcaster for tracked transactions.
+ * Once the transaction reaches a terminal state (succeeded, reverted, failed, dead),
+ * tracking automatically stops to avoid unnecessary API calls.
+ *
+ * Also provides a `refresh()` method for manual updates.
+ *
+ * @param txId - The transaction ID to track, or null to disable tracking
+ * @returns The current transaction status with loading state and refresh method
+ *
+ * @remarks
+ * **Error handling:** On fetch error, `state` retains its previous value while
+ * `error` is set. Always check `error` first when rendering status.
+ *
+ * @example
+ * ```tsx
+ * function TransactionStatus({ txId }: { txId: string }) {
+ *   const { state, txHash, isLoading, error } = useTxStatus(txId);
+ *
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Error: {error}</span>;
+ *   if (state === 'succeeded') return <span>Confirmed! TX: {txHash}</span>;
+ *
+ *   return <span>Status: {state}</span>;
+ * }
+ * ```
+ */
+declare function useTxStatus(txId: string | null): UseTxStatusResult;
+
+type UseOperationMutationResult<TInput, TOutput> = {
+    /** Execute the mutation */
+    mutate: (input: TInput) => Promise<TOutput>;
+    /** Last successful result */
+    data: TOutput | null;
+    /** Whether the mutation is currently running */
+    isPending: boolean;
+    /** Whether the last mutation succeeded */
+    isSuccess: boolean;
+    /** Whether the last mutation failed */
+    isError: boolean;
+    /** Error from the last failed mutation */
+    error: Error | null;
+    /** Reset state back to idle */
+    reset: () => void;
+};
+/**
+ * Generic async mutation state machine for wallet operations.
+ *
+ * Tracks loading, success, error, and data states.
+ * Prevents concurrent mutations (throws while a mutation is pending).
+ *
+ * @example
+ * ```tsx
+ * function DepositButton() {
+ *   const { requestDeposit } = useUnlink();
+ *   const { mutate, isPending, error } = useOperationMutation(requestDeposit);
+ *
+ *   return (
+ *     <button onClick={() => mutate(params)} disabled={isPending}>
+ *       {isPending ? "Depositing..." : "Deposit"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useOperationMutation<TInput, TOutput>(operation: (input: TInput) => Promise<TOutput>): UseOperationMutationResult<TInput, TOutput>;
+
+/**
+ * Hook for requesting deposits with loading/error state.
+ *
+ * @example
+ * ```tsx
+ * function DepositForm() {
+ *   const { mutate: deposit, isPending, error } = useDeposit();
+ *
+ *   const handleDeposit = async () => {
+ *     const result = await deposit([
+ *       { token: "0x...", amount: 1000n, depositor: "0x..." },
+ *     ]);
+ *     // result.calldata — submit this on-chain
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleDeposit} disabled={isPending}>
+ *       {isPending ? "Preparing..." : "Deposit"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useDeposit(): UseOperationMutationResult<DepositInput[], DepositRelayResult>;
+
+/**
+ * Hook for sending private transfers with loading/error state.
+ *
+ * @example
+ * ```tsx
+ * function SendForm() {
+ *   const { mutate: send, isPending, error } = useTransfer();
+ *
+ *   const handleSend = async () => {
+ *     const result = await send([
+ *       { token: "0x...", recipient: "0zk1...", amount: 100n },
+ *     ]);
+ *     console.log("Relay ID:", result.relayId);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSend} disabled={isPending}>
+ *       {isPending ? "Sending..." : "Send"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useTransfer(): UseOperationMutationResult<TransferInput[], TransferResult>;
+
+/**
+ * Hook for requesting withdrawals with loading/error state.
+ *
+ * @example
+ * ```tsx
+ * function WithdrawForm() {
+ *   const { mutate: withdraw, isPending, error } = useWithdraw();
+ *
+ *   const handleWithdraw = async () => {
+ *     const result = await withdraw([
+ *       { token: "0x...", amount: 50n, recipient: "0x..." },
+ *     ]);
+ *     console.log("Relay ID:", result.relayId);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleWithdraw} disabled={isPending}>
+ *       {isPending ? "Withdrawing..." : "Withdraw"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useWithdraw(): UseOperationMutationResult<WithdrawInput[], WithdrawResult>;
+
+export { CONFIRMATION_POLL_INTERVAL_MS, DEFAULT_CONFIRMATION_TIMEOUT_MS, type DepositInput, type PendingDepositJob, type PendingTransferJob, type PendingWithdrawJob, TERMINAL_TX_STATES, TimeoutError, TransactionFailedError, type TransferInput, type TxState, type TxStatus, type UnlinkActions, type UnlinkConfig, type UnlinkContextValue, type UnlinkError, type UnlinkErrorCode, type UnlinkErrorOperation, UnlinkProvider, type UnlinkProviderProps, type UnlinkState, type UseOperationMutationResult, type UseTxStatusResult, type UseUnlinkBalanceResult, type UseUnlinkHistoryOptions, type UseUnlinkHistoryResult, type WaitForConfirmationOptions, type WalletNote, type WithdrawInput, useDeposit, useOperationMutation, useTransfer, useTxStatus, useUnlink, useUnlinkBalance, useUnlinkBalances, useUnlinkHistory, useWithdraw };