@satoshai/kit 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -3,35 +3,163 @@ import { ClarityValue, TupleCV, PostCondition, PostConditionMode } from '@stacks
 import { ClarityAbi, ExtractAbiFunctionNames, Pretty, ExtractAbiFunction, ClarityAbiArgToPrimitiveTypeValue } from 'clarity-abitype';
 export { ClarityAbi } from 'clarity-abitype';
 
+/** Discriminated type for narrowing caught errors to `BaseError`. */
+type BaseErrorType = BaseError & {
+    name: 'StacksKitError';
+};
+/**
+ * Base error class for all `@satoshai/kit` errors.
+ *
+ * All errors thrown by hooks extend this class, so you can catch them with
+ * `error instanceof BaseError` and use {@link BaseError.walk | walk()} to
+ * traverse the cause chain.
+ *
+ * @example
+ * ```ts
+ * import { BaseError } from '@satoshai/kit';
+ *
+ * try {
+ *   await signMessageAsync({ message: 'hello' });
+ * } catch (err) {
+ *   if (err instanceof BaseError) {
+ *     console.log(err.shortMessage); // human-readable summary
+ *     console.log(err.walk());       // root cause
+ *   }
+ * }
+ * ```
+ */
+declare class BaseError extends Error {
+    name: string;
+    /** Short, human-readable error summary without details or cause chain. */
+    shortMessage: string;
+    constructor(shortMessage: string, options?: {
+        cause?: Error;
+        details?: string;
+    });
+    /**
+     * Walk the error cause chain. If `fn` is provided, returns the first error
+     * where `fn` returns `true`; otherwise returns the root cause.
+     */
+    walk(fn?: (err: unknown) => boolean): unknown;
+}
+/** Discriminated type for narrowing to `WalletNotConnectedError`. */
+type WalletNotConnectedErrorType = WalletNotConnectedError & {
+    name: 'WalletNotConnectedError';
+};
+/** Thrown when a mutation hook is called before a wallet is connected. */
+declare class WalletNotConnectedError extends BaseError {
+    name: string;
+    constructor();
+}
+/** Discriminated type for narrowing to `WalletNotFoundError`. */
+type WalletNotFoundErrorType = WalletNotFoundError & {
+    name: 'WalletNotFoundError';
+};
+/** Thrown when a wallet's browser extension is not installed (e.g. OKX). */
+declare class WalletNotFoundError extends BaseError {
+    name: string;
+    /** The wallet ID that was not found. */
+    wallet: string;
+    constructor({ wallet }: {
+        wallet: string;
+    });
+}
+/** Discriminated type for narrowing to `UnsupportedMethodError`. */
+type UnsupportedMethodErrorType = UnsupportedMethodError & {
+    name: 'UnsupportedMethodError';
+};
+/** Thrown when a wallet does not support the requested RPC method (e.g. OKX + `stx_signStructuredMessage`). */
+declare class UnsupportedMethodError extends BaseError {
+    name: string;
+    /** The SIP-030 method name that is not supported. */
+    method: string;
+    /** The wallet that does not support the method. */
+    wallet: string;
+    constructor({ method, wallet }: {
+        method: string;
+        wallet: string;
+    });
+}
+/** Discriminated type for narrowing to `WalletRequestError`. */
+type WalletRequestErrorType = WalletRequestError & {
+    name: 'WalletRequestError';
+};
+/** Thrown when a wallet RPC request fails (user rejection, timeout, etc.). The original error is attached as `cause`. */
+declare class WalletRequestError extends BaseError {
+    name: string;
+    /** The SIP-030 method name that failed. */
+    method: string;
+    /** The wallet that returned the error. */
+    wallet: string;
+    constructor({ method, wallet, cause }: {
+        method: string;
+        wallet: string;
+        cause: Error;
+    });
+}
+
+/** All wallet IDs supported by `@satoshai/kit`. */
 declare const SUPPORTED_STACKS_WALLETS: readonly ["xverse", "leather", "asigna", "fordefi", "wallet-connect", "okx"];
+/** Union of supported wallet identifiers. */
 type SupportedStacksWallet = (typeof SUPPORTED_STACKS_WALLETS)[number];
 
+/** Stacks network identifier. */
 type StacksChain = 'mainnet' | 'testnet';
+/** Status of a mutation hook (`useConnect`, `useSignMessage`, etc.). */
 type MutationStatus = 'idle' | 'pending' | 'error' | 'success';
+/** Metadata passed to the WalletConnect relay for dApp identification. */
 interface WalletConnectMetadata {
     name: string;
     description: string;
     url: string;
     icons: string[];
 }
+/** Optional callbacks for {@link useConnect}. */
 interface ConnectOptions {
+    /** Called with the connected address and wallet ID on success. */
     onSuccess?: (address: string, provider: SupportedStacksWallet) => void;
+    /** Called when the connection fails or is rejected. */
     onError?: (error: Error) => void;
 }
+/** Props for the {@link StacksWalletProvider} component. */
 interface StacksWalletProviderProps {
     children: React.ReactNode;
+    /**
+     * Wallets to enable. Defaults to all supported wallets.
+     *
+     * **Tip:** Define this array outside your component or memoize it to keep
+     * the reference stable across renders.
+     */
     wallets?: SupportedStacksWallet[];
     /** Show @stacks/connect's built-in wallet selection modal when `connect()` is called without a `providerId`. Defaults to `true`. Set to `false` to manage wallet selection yourself (headless). */
     connectModal?: boolean;
+    /**
+     * WalletConnect configuration. Required when `wallets` includes `'wallet-connect'`.
+     *
+     * **Tip:** Define this object outside your component or memoize it to keep
+     * the reference stable across renders.
+     */
     walletConnect?: {
+        /** WalletConnect Cloud project ID from https://cloud.walletconnect.com. */
         projectId: string;
+        /** Override default dApp metadata shown in the wallet. */
         metadata?: Partial<WalletConnectMetadata>;
+        /** Stacks chains to request. Defaults to `['mainnet']`. */
         chains?: StacksChain[];
     };
+    /** Called after a wallet successfully connects. */
     onConnect?: (provider: SupportedStacksWallet, address: string) => void;
+    /** Called when the connected account changes (e.g. Xverse account switch, WalletConnect account change). */
     onAddressChange?: (newAddress: string) => void;
+    /** Called when the wallet disconnects (user-initiated or session expiry). */
     onDisconnect?: () => void;
 }
+/**
+ * Discriminated union representing the wallet connection state.
+ *
+ * When `status` is `'connected'`, `address` and `provider` are guaranteed
+ * to be defined.
+ */
 type WalletState = {
     status: 'disconnected';
     address: undefined;
@@ -45,20 +173,54 @@ type WalletState = {
     address: string;
     provider: SupportedStacksWallet;
 };
+/** Metadata for a single wallet returned by {@link useWallets}. */
 interface WalletInfo {
+    /** Wallet identifier used with `connect(id)`. */
     id: SupportedStacksWallet;
+    /** Human-readable wallet name. */
     name: string;
+    /** Wallet icon as a data URI. */
     icon: string;
+    /** URL to download/install the wallet extension. */
     webUrl: string;
+    /** `true` when the wallet extension is detected or WalletConnect is configured. */
     available: boolean;
 }
+/** Full context value exposed by `StacksWalletProvider`. Extends {@link WalletState} with actions and wallet list. */
 type WalletContextValue = WalletState & {
+    /** Connect to a wallet. Pass a wallet ID to bypass the modal, or call with no args to show the `@stacks/connect` modal. */
     connect: (providerId?: SupportedStacksWallet, options?: ConnectOptions) => Promise<void>;
+    /** Disconnect the current wallet and clear persisted state. */
     disconnect: (callback?: () => void) => void;
+    /** Reset a stuck connecting state back to idle. */
     reset: () => void;
+    /** All configured wallets with availability status. */
     wallets: WalletInfo[];
 };
 
+/**
+ * React context provider that manages wallet connection state for all `@satoshai/kit` hooks.
+ *
+ * Wrap your app (or the subtree that needs wallet access) with this provider.
+ * All hooks (`useConnect`, `useAddress`, `useWriteContract`, etc.) must be
+ * rendered inside this provider.
+ *
+ * @example
+ * ```tsx
+ * import { StacksWalletProvider } from '@satoshai/kit';
+ *
+ * const wallets = ['xverse', 'leather', 'wallet-connect'] as const;
+ * const wc = { projectId: 'YOUR_PROJECT_ID' };
+ *
+ * function App() {
+ *   return (
+ *     <StacksWalletProvider wallets={[...wallets]} walletConnect={wc}>
+ *       <YourApp />
+ *     </StacksWalletProvider>
+ *   );
+ * }
+ * ```
+ */
 declare const StacksWalletProvider: ({ children, wallets, connectModal, walletConnect, onConnect, onAddressChange, onDisconnect, }: StacksWalletProviderProps) => react_jsx_runtime.JSX.Element;
 
 type UseAddressReturn = {
@@ -74,8 +236,48 @@ type UseAddressReturn = {
     isDisconnected: false;
     provider: SupportedStacksWallet;
 };
+/**
+ * Read the connected wallet's address and connection status.
+ *
+ * Returns a discriminated union — when `isConnected` is `true`, `address`
+ * and `provider` are guaranteed to be defined (no null checks needed).
+ *
+ * @example
+ * ```ts
+ * const { address, isConnected, provider } = useAddress();
+ *
+ * if (isConnected) {
+ *   console.log(address);  // 'SP...' — narrowed to string
+ *   console.log(provider); // 'xverse' | 'leather' | ...
+ * }
+ * ```
+ */
 declare const useAddress: () => UseAddressReturn;
 
+/**
+ * Connect to a Stacks wallet.
+ *
+ * Returns a mutation-style object with `connect`, `reset`, and status flags.
+ * Call `connect()` with no args to open the `@stacks/connect` wallet modal,
+ * or pass a specific wallet ID (e.g. `connect('xverse')`) to connect directly.
+ *
+ * @example
+ * ```ts
+ * const { connect, reset, isPending, isSuccess, error } = useConnect();
+ *
+ * // Modal mode (default)
+ * await connect();
+ *
+ * // Direct mode
+ * await connect('leather', {
+ *   onSuccess: (address, provider) => console.log(address),
+ *   onError: (err) => console.error(err),
+ * });
+ *
+ * // Cancel a stuck connection (e.g. OKX popup dismissed)
+ * reset();
+ * ```
+ */
 declare const useConnect: () => {
     connect: (providerId?: SupportedStacksWallet, options?: ConnectOptions) => Promise<void>;
     reset: () => void;
@@ -87,6 +289,20 @@ declare const useConnect: () => {
     status: MutationStatus;
 };
 
+/**
+ * Disconnect the currently connected wallet.
+ *
+ * Clears wallet state, removes the persisted session from localStorage,
+ * and resets the provider context back to `disconnected`.
+ *
+ * @example
+ * ```ts
+ * const { disconnect, isSuccess } = useDisconnect();
+ *
+ * disconnect();
+ * disconnect(() => navigate('/'));
+ * ```
+ */
 declare const useDisconnect: () => {
     disconnect: (callback?: () => void) => void;
     reset: () => void;
@@ -98,25 +314,51 @@ declare const useDisconnect: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignMessage}. */
 interface SignMessageVariables {
+    /** The plaintext message to sign. */
     message: string;
+    /** Optional public key hint for wallets that manage multiple keys. */
     publicKey?: string;
 }
+/** Successful result from {@link useSignMessage}. */
 interface SignMessageData {
+    /** The public key that produced the signature. */
     publicKey: string;
+    /** The hex-encoded signature. */
     signature: string;
 }
+/** Callback options for the fire-and-forget `signMessage()` variant. */
 interface SignMessageOptions {
     onSuccess?: (data: SignMessageData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignMessageData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign an arbitrary plaintext message with the connected wallet.
+ *
+ * Provides both a callback-style `signMessage()` and a promise-based
+ * `signMessageAsync()`, plus mutation status flags.
+ *
+ * @example
+ * ```ts
+ * const { signMessageAsync, isPending } = useSignMessage();
+ *
+ * const { publicKey, signature } = await signMessageAsync({
+ *   message: 'Hello Stacks',
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignMessage: () => {
     signMessage: (variables: SignMessageVariables, options?: SignMessageOptions) => void;
     signMessageAsync: (variables: SignMessageVariables) => Promise<SignMessageData>;
     reset: () => void;
     data: SignMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -124,25 +366,52 @@ declare const useSignMessage: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignStructuredMessage}. */
 interface SignStructuredMessageVariables {
+    /** The structured Clarity value to sign. */
     message: ClarityValue;
+    /** SIP-018 domain tuple (name, version, chain-id). */
     domain: TupleCV;
 }
+/** Successful result from {@link useSignStructuredMessage}. */
 interface SignStructuredMessageData {
     publicKey: string;
     signature: string;
 }
+/** Callback options for the fire-and-forget `signStructuredMessage()` variant. */
 interface SignStructuredMessageOptions {
     onSuccess?: (data: SignStructuredMessageData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignStructuredMessageData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign SIP-018 structured data with the connected wallet.
+ *
+ * Structured messages include a typed domain separator and a Clarity value
+ * body, enabling verifiable off-chain signatures that are replay-safe.
+ *
+ * @example
+ * ```ts
+ * import { tupleCV, stringAsciiCV, uintCV } from '@stacks/transactions';
+ *
+ * const { signStructuredMessageAsync } = useSignStructuredMessage();
+ *
+ * const { signature } = await signStructuredMessageAsync({
+ *   domain: tupleCV({ name: stringAsciiCV('MyApp'), version: stringAsciiCV('1.0'), 'chain-id': uintCV(1) }),
+ *   message: tupleCV({ action: stringAsciiCV('authorize') }),
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {UnsupportedMethodError} If the wallet does not support structured signing (OKX).
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignStructuredMessage: () => {
     signStructuredMessage: (variables: SignStructuredMessageVariables, options?: SignStructuredMessageOptions) => void;
     signStructuredMessageAsync: (variables: SignStructuredMessageVariables) => Promise<SignStructuredMessageData>;
     reset: () => void;
     data: SignStructuredMessageData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -150,25 +419,52 @@ declare const useSignStructuredMessage: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useSignTransaction}. */
 interface SignTransactionVariables {
+    /** Hex-encoded serialized transaction to sign. */
     transaction: string;
+    /** Whether to broadcast the signed transaction. Defaults to the wallet's behavior. */
     broadcast?: boolean;
 }
+/** Successful result from {@link useSignTransaction}. */
 interface SignTransactionData {
+    /** The signed, hex-encoded transaction. */
     transaction: string;
+    /** Transaction ID, present when the wallet broadcasts it. */
     txid?: string;
 }
+/** Callback options for the fire-and-forget `signTransaction()` variant. */
 interface SignTransactionOptions {
     onSuccess?: (data: SignTransactionData) => void;
     onError?: (error: Error) => void;
     onSettled?: (data: SignTransactionData | undefined, error: Error | null) => void;
 }
+/**
+ * Sign a serialized Stacks transaction without automatic broadcast.
+ *
+ * Useful for sponsored transaction flows where a separate service pays the
+ * fee and broadcasts the transaction.
+ *
+ * @example
+ * ```ts
+ * const { signTransactionAsync } = useSignTransaction();
+ *
+ * const { transaction } = await signTransactionAsync({
+ *   transaction: '0x0100...',
+ *   broadcast: false,
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {UnsupportedMethodError} If the wallet does not support raw signing (OKX).
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useSignTransaction: () => {
     signTransaction: (variables: SignTransactionVariables, options?: SignTransactionOptions) => void;
     signTransactionAsync: (variables: SignTransactionVariables) => Promise<SignTransactionData>;
     reset: () => void;
     data: SignTransactionData | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -176,24 +472,52 @@ declare const useSignTransaction: () => {
     status: MutationStatus;
 };
 
+/** Variables for {@link useTransferSTX}. */
 interface TransferSTXVariables {
+    /** Recipient Stacks address (`SP...` or `ST...`). */
     recipient: string;
+    /** Amount in microSTX. Accepts `bigint`, `number`, or numeric `string`. */
     amount: bigint | number | string;
+    /** Optional memo string attached to the transfer. */
     memo?: string;
+    /** Custom fee in microSTX. Omit to let the wallet estimate. */
     fee?: bigint | number | string;
+    /** Custom nonce. Omit to let the wallet manage. */
     nonce?: bigint | number | string;
 }
+/** Callback options for the fire-and-forget `transferSTX()` variant. */
 interface TransferSTXOptions {
     onSuccess?: (txid: string) => void;
     onError?: (error: Error) => void;
     onSettled?: (txid: string | undefined, error: Error | null) => void;
 }
+/**
+ * Transfer native STX tokens to a recipient address.
+ *
+ * Returns the broadcast transaction ID on success. Supports all 6 wallets
+ * (OKX uses its proprietary API internally).
+ *
+ * @example
+ * ```ts
+ * const { transferSTXAsync, isPending } = useTransferSTX();
+ *
+ * const txid = await transferSTXAsync({
+ *   recipient: 'SP2...',
+ *   amount: 1_000_000n, // 1 STX
+ *   memo: 'coffee',
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useTransferSTX: () => {
     transferSTX: (variables: TransferSTXVariables, options?: TransferSTXOptions) => void;
     transferSTXAsync: (variables: TransferSTXVariables) => Promise<string>;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -210,8 +534,11 @@ type PublicFunctionArgs<TAbi extends ClarityAbi, TFn extends ExtractAbiFunctionN
     [K in ExtractAbiFunction<TAbi, TFn, 'public'>['args'][number] as K['name']]: ClarityAbiArgToPrimitiveTypeValue<K>;
 }>;
 
+/** Post-condition configuration for contract calls and STX transfers. */
 interface PostConditionConfig {
+    /** Array of post-conditions that must be satisfied for the transaction to succeed. */
     postConditions: PostCondition[];
+    /** Whether to allow or deny any asset transfers not covered by `postConditions`. */
     mode: PostConditionMode;
 }
 /** Typed mode: ABI present, args is a named object with autocomplete. */
@@ -233,6 +560,7 @@ interface UntypedWriteContractVariables {
 }
 /** Backward-compatible alias for the untyped variant. */
 type WriteContractVariables = UntypedWriteContractVariables;
+/** Callback options for the fire-and-forget `writeContract()` variant. */
 interface WriteContractOptions {
     onSuccess?: (txHash: string) => void;
     onError?: (error: Error) => void;
@@ -249,12 +577,52 @@ interface WriteContractFn {
     (variables: UntypedWriteContractVariables, options?: WriteContractOptions): void;
 }
 
+/**
+ * Call a public function on a Clarity smart contract.
+ *
+ * Supports two modes:
+ * - **Typed** (with ABI) — pass an ABI object for autocomplete on `functionName` and `args`.
+ * - **Untyped** — pass `ClarityValue[]` directly as `args`.
+ *
+ * @example
+ * ```ts
+ * import { Pc, PostConditionMode } from '@stacks/transactions';
+ *
+ * const { writeContractAsync } = useWriteContract();
+ *
+ * // Untyped mode
+ * const txid = await writeContractAsync({
+ *   address: 'SP...',
+ *   contract: 'my-contract',
+ *   functionName: 'transfer',
+ *   args: [uintCV(100)],
+ *   pc: {
+ *     postConditions: [Pc.principal('SP...').willSendLte(100n).ustx()],
+ *     mode: PostConditionMode.Deny,
+ *   },
+ * });
+ *
+ * // Typed mode (with ABI — enables autocomplete)
+ * const txid = await writeContractAsync({
+ *   abi: myContractAbi,
+ *   address: 'SP...',
+ *   contract: 'my-contract',
+ *   functionName: 'transfer', // autocompleted from ABI
+ *   args: { amount: 100n },   // named args, type-checked
+ *   pc: { postConditions: [], mode: PostConditionMode.Deny },
+ * });
+ * ```
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected.
+ * @throws {WalletNotFoundError} If OKX extension is not installed.
+ * @throws {WalletRequestError} If the wallet rejects or fails the request.
+ */
 declare const useWriteContract: () => {
     writeContract: WriteContractFn;
     writeContractAsync: WriteContractAsyncFn;
     reset: () => void;
     data: string | undefined;
-    error: Error | null;
+    error: BaseError | null;
     isError: boolean;
     isIdle: boolean;
     isPending: boolean;
@@ -262,29 +630,100 @@ declare const useWriteContract: () => {
     status: MutationStatus;
 };
 
+/**
+ * Resolve a BNS v2 primary name for a Stacks address.
+ *
+ * Returns `null` when no name is registered or the address is undefined.
+ * Automatically detects mainnet/testnet from the address prefix.
+ *
+ * @param address - Stacks address to resolve (`SP...` or `ST...`).
+ *
+ * @example
+ * ```ts
+ * const { bnsName, isLoading } = useBnsName('SP2...');
+ * // bnsName = 'satoshi.btc' | null
+ * ```
+ */
 declare const useBnsName: (address?: string) => {
     bnsName: string | null;
     isLoading: boolean;
 };
 
+/**
+ * List all configured wallets with availability status.
+ *
+ * Each wallet includes its `id`, display `name`, `icon` (data URI), `webUrl`
+ * (install link), and whether it's `available` (extension detected or
+ * WalletConnect configured).
+ *
+ * @example
+ * ```ts
+ * const { wallets } = useWallets();
+ *
+ * wallets.map(({ id, name, icon, available }) => (
+ *   <button key={id} onClick={() => connect(id)} disabled={!available}>
+ *     <img src={icon} alt={name} width={20} /> {name}
+ *   </button>
+ * ));
+ * ```
+ */
 declare const useWallets: () => {
     wallets: WalletInfo[];
 };
 
+/**
+ * Infer the Stacks network from an address prefix.
+ *
+ * @param address - A Stacks address starting with `SP`/`SM` (mainnet) or `ST`/`SN` (testnet).
+ * @returns `'mainnet'` or `'testnet'`.
+ * @throws If the address doesn't start with a known prefix.
+ */
 declare const getNetworkFromAddress: (address: string) => "mainnet" | "testnet";
 
+/**
+ * Read the persisted wallet session from localStorage.
+ *
+ * Returns `null` on the server, when no session is stored, or when the
+ * stored provider is not in the supported wallets list.
+ */
 declare const getLocalStorageWallet: () => {
     address: string;
     provider: SupportedStacksWallet;
 } | null;
 
+/** Result of {@link getStacksWallets}. */
 interface StacksWallets {
+    /** All wallets supported by `@satoshai/kit`. */
     supported: SupportedStacksWallet[];
+    /** Subset of `supported` whose browser extension is currently detected. */
     installed: SupportedStacksWallet[];
 }
+/**
+ * Detect which Stacks wallets are supported and installed.
+ *
+ * Safe to call on the server — `installed` will contain only `'wallet-connect'`
+ * when `window` is undefined.
+ */
 declare const getStacksWallets: () => StacksWallets;
 
-/** Pre-bind ABI + address + contract for reuse with useWriteContract. */
+/**
+ * Pre-bind ABI, address, and contract name for reuse with `useWriteContract`.
+ *
+ * Returns the config object as-is but preserves the `const` ABI type, enabling
+ * autocomplete on `functionName` and type-checked `args` when spread into
+ * `writeContract()`.
+ *
+ * @example
+ * ```ts
+ * const pool = createContractConfig({
+ *   abi: poolAbi,
+ *   address: 'SP...',
+ *   contract: 'pool-v1',
+ * });
+ *
+ * writeContract({ ...pool, functionName: 'deposit', args: { amount: 100n }, pc });
+ * ```
+ */
 declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
     abi: TAbi;
     address: string;
@@ -295,4 +734,4 @@ declare function createContractConfig<const TAbi extends ClarityAbi>(config: {
     contract: string;
 };
 
-export { type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };
+export { BaseError, type BaseErrorType, type ConnectOptions, type MutationStatus, type PostConditionConfig, type PublicFunctionArgs, type PublicFunctionName, SUPPORTED_STACKS_WALLETS, type SignMessageData, type SignMessageOptions, type SignMessageVariables, type SignStructuredMessageData, type SignStructuredMessageOptions, type SignStructuredMessageVariables, type SignTransactionData, type SignTransactionOptions, type SignTransactionVariables, type StacksChain, StacksWalletProvider, type StacksWallets, type SupportedStacksWallet, type TraitReference, type TransferSTXOptions, type TransferSTXVariables, type TypedWriteContractVariables, UnsupportedMethodError, type UnsupportedMethodErrorType, type UntypedWriteContractVariables, type WalletConnectMetadata, type WalletContextValue, type WalletInfo, WalletNotConnectedError, type WalletNotConnectedErrorType, WalletNotFoundError, type WalletNotFoundErrorType, WalletRequestError, type WalletRequestErrorType, type WalletState, type WriteContractOptions, type WriteContractVariables, createContractConfig, getLocalStorageWallet, getNetworkFromAddress, getStacksWallets, useAddress, useBnsName, useConnect, useDisconnect, useSignMessage, useSignStructuredMessage, useSignTransaction, useTransferSTX, useWallets, useWriteContract };