@unlink-xyz/react 0.1.5 → 0.1.7-canary.252b8ea

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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';
+import { BrowserWalletOptions, SupportedChain, Unlink, AccountInfo, Account, NoteRecord, BurnerAccount, HistoryStatus, SignerOverride, SendResult, SendPlanResult, DepositRelayResult, WithdrawalInput, WithdrawResult, WithdrawPlanResult, BurnerSendParams, SimpleBurnerFundParams, SimpleBurnerSweepToPoolParams, SimpleInteractParams, InteractResult, RelayState, HistoryEntry } from '@unlink-xyz/core';
+export { Account, AccountInfo, AdapterExecutionCall, BurnerAccount, BurnerSendParams, Chain, HistoryEntry, InputTokenSpec, InteractResult, NoteRecord, ParsedZkAddress, ReceiveInput, ReshieldInput, SendPlanResult, SendResult, SignerOverride, SimpleBurnerFundParams, SimpleBurnerSweepToPoolParams, SimpleInteractParams, SpendInput, SupportedChain, TransactionLike, TxStatusChangedEvent, Unlink, UnlinkEvent, UnlinkWallet, WalletSDKEvent, WithdrawPlanResult, WithdrawResult, approve, buildApproveCall, computeBalances, contract, decodeAddress, encodeAddress, formatAmount, normalizeAddress, parseAmount, parseZkAddress, randomHex, shortenHex, toCall } from '@unlink-xyz/core';
 
 /**
  * Wallet note with value as bigint for convenience.
@@ -23,7 +23,7 @@ type PendingJobBase = {
 type PendingDepositJob = PendingJobBase & {
     commitment?: string;
 };
-type PendingTransferJob = PendingJobBase & {
+type PendingSendJob = PendingJobBase & {
     recipient: string;
 };
 type PendingWithdrawJob = PendingJobBase & {
@@ -33,8 +33,6 @@ type PendingWithdrawJob = PendingJobBase & {
  * 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) */
@@ -44,26 +42,29 @@ type UnlinkConfigBase = {
 };
 /**
  * Configuration for the UnlinkProvider.
- * Either provide explicit gatewayUrl + poolAddress, or environment to auto-resolve.
+ * Either provide a chain name to auto-resolve, or explicit gatewayUrl + poolAddress.
  */
 type UnlinkConfig = UnlinkConfigBase & ({
+    /** Supported chain name — resolves chainId, gateway, pool, artifacts */
+    chain: SupportedChain;
+    /** Override pool address from chain config */
+    poolAddress?: string;
+    chainId?: never;
+    gatewayUrl?: never;
+} | {
+    /** Chain ID for the target blockchain */
+    chainId: number;
     /** 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;
+    chain?: never;
 });
 /**
  * State exposed by the useUnlink hook.
  */
 type UnlinkState = {
-    /** The underlying wallet instance */
-    wallet: UnlinkWallet | null;
+    /** The underlying Unlink instance */
+    unlink: Unlink | null;
     /** Whether a wallet (mnemonic) exists */
     walletExists: boolean;
     /** All derived accounts */
@@ -72,16 +73,18 @@ type UnlinkState = {
     activeAccount: Account | null;
     /** Current active account index (null if none) */
     activeAccountIndex: number | null;
-    /** Chain ID configured for this provider */
-    chainId: number;
+    /** Chain ID (resolved from chain config or provided explicitly, null before init) */
+    chainId: number | null;
     /** User's notes with value as bigint */
     notes: WalletNote[];
     /** Token balances by address */
     balances: Record<string, bigint>;
+    /** Tracked burner accounts */
+    burners: BurnerAccount[];
     /** Pending deposit jobs */
     pendingDeposits: PendingDepositJob[];
-    /** Pending transfer jobs */
-    pendingTransfers: PendingTransferJob[];
+    /** Pending send jobs */
+    pendingSends: PendingSendJob[];
     /** Pending withdraw jobs */
     pendingWithdrawals: PendingWithdrawJob[];
     /** Whether the SDK is initialized and ready */
@@ -96,11 +99,11 @@ type UnlinkState = {
     error: UnlinkError | null;
 };
 /**
- * Transfer parameters for useUnlink.send()
+ * Send parameters for useUnlink.send()
  */
-type TransferInput = {
+type SendInput = {
     token: string;
-    /** Unlink address (0zk1... bech32m) */
+    /** Unlink address (unlink1... bech32m) */
     recipient: string;
     amount: bigint;
 };
@@ -114,7 +117,7 @@ type DepositInput = {
     depositor: string;
 };
 /**
- * Withdraw parameters for useUnlink.requestWithdraw()
+ * Withdraw parameters for useUnlink.withdraw()
  */
 type WithdrawInput = WithdrawalInput;
 /**
@@ -140,28 +143,28 @@ type UnlinkActions = {
      * Multiple transfers are processed atomically.
      *
      * @param params - Array of transfers (token + amount + recipient)
-     * @returns TransferResult with array of plans
+     * @returns SendResult with array of plans
      */
-    send(params: TransferInput[]): Promise<TransferResult>;
+    send(params: SendInput[], overrides?: SignerOverride): Promise<SendResult>;
     /**
-     * Get a transfer plan without executing (for preview).
+     * Get a send 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>;
+    planSend(params: SendInput[]): Promise<SendPlanResult>;
+    /** Execute a pre-built send plan */
+    executeSend(plans: SendPlanResult, overrides?: SignerOverride): Promise<SendResult>;
     /**
-     * Request a deposit (1 or more tokens).
+     * 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>;
+    deposit(params: DepositInput[]): Promise<DepositRelayResult>;
     /**
      * High-level withdraw (1 or more tokens).
      * Specify recipient EOA + amount for each withdrawal.
@@ -170,7 +173,7 @@ type UnlinkActions = {
      * @param params - Array of withdrawals (token + amount + recipient)
      * @returns WithdrawResult with array of plans
      */
-    requestWithdraw(params: WithdrawInput[]): Promise<WithdrawResult>;
+    withdraw(params: WithdrawInput[], overrides?: SignerOverride): Promise<WithdrawResult>;
     /**
      * Get a withdrawal plan without executing (for preview).
      * Validates balances and returns plans for each withdrawal.
@@ -180,7 +183,29 @@ type UnlinkActions = {
      */
     planWithdraw(params: WithdrawInput[]): Promise<WithdrawPlanResult>;
     /** Execute a pre-built withdrawal plan */
-    executeWithdraw(plans: WithdrawPlanResult): Promise<WithdrawResult>;
+    executeWithdraw(plans: WithdrawPlanResult, overrides?: SignerOverride): Promise<WithdrawResult>;
+    /** Derive and track burner account at index */
+    createBurner(index: number): Promise<BurnerAccount>;
+    /** Remove tracked burner account (client-side only) */
+    removeBurner(index: number): void;
+    /** Send transaction from burner account */
+    burnerSend(index: number, tx: BurnerSendParams): Promise<{
+        txHash: string;
+    }>;
+    /** Fund burner from shielded pool */
+    burnerFund(index: number, params: SimpleBurnerFundParams): Promise<WithdrawResult>;
+    /** Sweep burner funds back to shielded pool */
+    burnerSweepToPool(index: number, params: SimpleBurnerSweepToPoolParams): Promise<{
+        txHash: string;
+    }>;
+    /** Get ERC-20 token balance for address */
+    burnerGetTokenBalance(address: string, token: string): Promise<bigint>;
+    /** Get native balance for address */
+    burnerGetBalance(address: string): Promise<bigint>;
+    /**
+     * Execute an atomic private DeFi flow (unshield -> calls -> reshield).
+     */
+    interact(params: SimpleInteractParams): Promise<InteractResult>;
     /** Refresh notes and balances */
     refresh(): Promise<void>;
     /** Force full resync from chain */
@@ -269,7 +294,7 @@ type UnlinkErrorCode = "UNKNOWN" | "SDK_NOT_INITIALIZED" | "NETWORK_ERROR" | "VA
 /**
  * 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";
+type UnlinkErrorOperation = "init" | "createWallet" | "importWallet" | "clearWallet" | "createAccount" | "switchAccount" | "send" | "executeSend" | "deposit" | "withdraw" | "interact" | "executeWithdraw" | "createBurner" | "burnerSend" | "burnerFund" | "burnerSweepToPool" | "refresh" | "forceResync";
 /**
  * Structured error type for the Unlink context.
  */
@@ -284,7 +309,7 @@ type UnlinkError = {
 type UnlinkProviderProps = UnlinkConfig & {
     children: ReactNode;
 };
-declare function UnlinkProvider({ children, chainId, poolAddress, syncInterval, autoSync, gatewayUrl, environment, prover, }: UnlinkProviderProps): react_jsx_runtime.JSX.Element;
+declare function UnlinkProvider({ children, poolAddress, syncInterval, autoSync, prover, ...configProps }: UnlinkProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook to access the Unlink wallet SDK.
@@ -325,7 +350,7 @@ type UseUnlinkHistoryResult = {
     refresh: () => Promise<void>;
 };
 /**
- * Hook to get transaction history for the wallet.
+ * Hook to get transaction history for the Unlink instance.
  *
  * Uses the SDK's history service which provides properly categorized
  * transaction entries (Deposit, Receive, Send, SelfSend, Withdraw).
@@ -437,8 +462,8 @@ declare function useUnlinkBalances(): {
 declare function useTxStatus(txId: string | null): UseTxStatusResult;
 
 type UseOperationMutationResult<TInput, TOutput> = {
-    /** Execute the mutation */
-    mutate: (input: TInput) => Promise<TOutput>;
+    /** Execute the operation */
+    execute: (input: TInput) => Promise<TOutput>;
     /** Last successful result */
     data: TOutput | null;
     /** Whether the mutation is currently running */
@@ -452,6 +477,13 @@ type UseOperationMutationResult<TInput, TOutput> = {
     /** Reset state back to idle */
     reset: () => void;
 };
+/**
+ * `UseOperationMutationResult` with `execute` replaced by a semantic action name.
+ * Used by operation-specific hooks (useSend, useDeposit, etc.).
+ */
+type NamedMutationResult<TAction extends string, TInput, TOutput> = Omit<UseOperationMutationResult<TInput, TOutput>, "execute"> & {
+    [K in TAction]: (input: TInput) => Promise<TOutput>;
+};
 /**
  * Generic async mutation state machine for wallet operations.
  *
@@ -461,11 +493,11 @@ type UseOperationMutationResult<TInput, TOutput> = {
  * @example
  * ```tsx
  * function DepositButton() {
- *   const { requestDeposit } = useUnlink();
- *   const { mutate, isPending, error } = useOperationMutation(requestDeposit);
+ *   const { deposit } = useUnlink();
+ *   const { execute, isPending, error } = useOperationMutation(deposit);
  *
  *   return (
- *     <button onClick={() => mutate(params)} disabled={isPending}>
+ *     <button onClick={() => execute(params)} disabled={isPending}>
  *       {isPending ? "Depositing..." : "Deposit"}
  *     </button>
  *   );
@@ -474,13 +506,14 @@ type UseOperationMutationResult<TInput, TOutput> = {
  */
 declare function useOperationMutation<TInput, TOutput>(operation: (input: TInput) => Promise<TOutput>): UseOperationMutationResult<TInput, TOutput>;
 
+type UseDepositResult = NamedMutationResult<"deposit", DepositInput[], DepositRelayResult>;
 /**
  * Hook for requesting deposits with loading/error state.
  *
  * @example
  * ```tsx
  * function DepositForm() {
- *   const { mutate: deposit, isPending, error } = useDeposit();
+ *   const { deposit, isPending, error } = useDeposit();
  *
  *   const handleDeposit = async () => {
  *     const result = await deposit([
@@ -497,19 +530,22 @@ declare function useOperationMutation<TInput, TOutput>(operation: (input: TInput
  * }
  * ```
  */
-declare function useDeposit(): UseOperationMutationResult<DepositInput[], DepositRelayResult>;
+declare function useDeposit(): UseDepositResult;
 
+type UseSendResult = NamedMutationResult<"send", SendInput[], SendResult>;
 /**
  * Hook for sending private transfers with loading/error state.
  *
+ * @param overrides - Optional signer override for multisig transactions
+ *
  * @example
  * ```tsx
  * function SendForm() {
- *   const { mutate: send, isPending, error } = useTransfer();
+ *   const { send, isPending, error } = useSend();
  *
  *   const handleSend = async () => {
  *     const result = await send([
- *       { token: "0x...", recipient: "0zk1...", amount: 100n },
+ *       { token: "0x...", recipient: "unlink1...", amount: 100n },
  *     ]);
  *     console.log("Relay ID:", result.relayId);
  *   };
@@ -522,15 +558,18 @@ declare function useDeposit(): UseOperationMutationResult<DepositInput[], Deposi
  * }
  * ```
  */
-declare function useTransfer(): UseOperationMutationResult<TransferInput[], TransferResult>;
+declare function useSend(overrides?: SignerOverride): UseSendResult;
 
+type UseWithdrawResult = NamedMutationResult<"withdraw", WithdrawInput[], WithdrawResult>;
 /**
  * Hook for requesting withdrawals with loading/error state.
  *
+ * @param overrides - Optional signer override for multisig transactions
+ *
  * @example
  * ```tsx
  * function WithdrawForm() {
- *   const { mutate: withdraw, isPending, error } = useWithdraw();
+ *   const { withdraw, isPending, error } = useWithdraw();
  *
  *   const handleWithdraw = async () => {
  *     const result = await withdraw([
@@ -547,6 +586,70 @@ declare function useTransfer(): UseOperationMutationResult<TransferInput[], Tran
  * }
  * ```
  */
-declare function useWithdraw(): UseOperationMutationResult<WithdrawInput[], WithdrawResult>;
+declare function useWithdraw(overrides?: SignerOverride): UseWithdrawResult;
+
+type UseInteractResult = NamedMutationResult<"interact", SimpleInteractParams, InteractResult>;
+/**
+ * Hook for executing private DeFi interactions with loading/error state.
+ *
+ * Performs atomic unshield → DeFi call(s) → reshield flows through an adapter contract.
+ *
+ * @example
+ * ```tsx
+ * function SwapButton() {
+ *   const { interact, isPending, error } = useInteract();
+ *
+ *   const handleSwap = async () => {
+ *     const result = await interact({
+ *       spend: [{ token: "0x...", amount: 1000n }],
+ *       calls: [approveCall, swapCall],
+ *       receive: [{ token: "0x...", minAmount: 500n }],
+ *     });
+ *     console.log("Relay ID:", result.relayId);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSwap} disabled={isPending}>
+ *       {isPending ? "Executing..." : "Swap"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useInteract(): UseInteractResult;
+
+type BurnerSendInput = {
+    index: number;
+    tx: BurnerSendParams;
+};
+type BurnerFundInput = {
+    index: number;
+    params: SimpleBurnerFundParams;
+};
+type BurnerSweepInput = {
+    index: number;
+    params: SimpleBurnerSweepToPoolParams;
+};
+type UseBurnerResult = {
+    burners: BurnerAccount[];
+    createBurner: (index: number) => Promise<BurnerAccount>;
+    removeBurner: (index: number) => void;
+    send: UseOperationMutationResult<BurnerSendInput, {
+        txHash: string;
+    }>;
+    fund: UseOperationMutationResult<BurnerFundInput, WithdrawResult>;
+    sweepToPool: UseOperationMutationResult<BurnerSweepInput, {
+        txHash: string;
+    }>;
+    getTokenBalance: (address: string, token: string) => Promise<bigint>;
+    getBalance: (address: string) => Promise<bigint>;
+};
+/**
+ * Hook for burner account operations.
+ *
+ * `exportKey` is intentionally excluded here and can be accessed via
+ * `useUnlink().unlink?.burner.exportKey(index)`.
+ */
+declare function useBurner(): UseBurnerResult;
 
-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 };
+export { type BurnerFundInput, type BurnerSendInput, type BurnerSweepInput, CONFIRMATION_POLL_INTERVAL_MS, DEFAULT_CONFIRMATION_TIMEOUT_MS, type DepositInput, type NamedMutationResult, type PendingDepositJob, type PendingSendJob, type PendingWithdrawJob, type SendInput, TERMINAL_TX_STATES, TimeoutError, TransactionFailedError, type TxState, type TxStatus, type UnlinkActions, type UnlinkConfig, type UnlinkContextValue, type UnlinkError, type UnlinkErrorCode, type UnlinkErrorOperation, UnlinkProvider, type UnlinkProviderProps, type UnlinkState, type UseBurnerResult, type UseDepositResult, type UseInteractResult, type UseOperationMutationResult, type UseSendResult, type UseTxStatusResult, type UseUnlinkBalanceResult, type UseUnlinkHistoryOptions, type UseUnlinkHistoryResult, type UseWithdrawResult, type WaitForConfirmationOptions, type WalletNote, type WithdrawInput, useBurner, useDeposit, useInteract, useOperationMutation, useSend, useTxStatus, useUnlink, useUnlinkBalance, useUnlinkBalances, useUnlinkHistory, useWithdraw };