@sodax/wallet-sdk-core 1.5.7-beta → 2.0.0-rc.10

package/dist/index.d.ts

@@ -1,25 +1,111 @@
+import { EvmRawTransaction, EvmChainKey, IEvmWalletProvider, EvmRawTransactionReceipt, ISuiWalletProvider, SuiTransaction, SuiExecutionResult, SuiPaginatedCoins, IIconWalletProvider, IcxCallTransaction, IconTransactionResult, InjectiveCoin, IInjectiveWalletProvider, JsonObject, InjectiveRawTransaction, InjectiveEoaAddress, InjectiveExecuteResponse, ISolanaWalletProvider, SolanaRpcResponseAndContext, SolanaSignatureResult, TransactionSignature, SolanaRawTransactionInstruction, SolanaSerializedTransaction, SolanaBase58PublicKey, XDR, Hex as Hex$1, IStellarWalletProvider, StellarRawTransactionReceipt, IStacksWalletProvider, StacksTransactionParams, INearWalletProvider, CallContractParams, NearRawTransaction, BtcAddressType, IBitcoinWalletProvider } from '@sodax/types';
 import * as viem from 'viem';
-import { Chain, PublicClient, WalletClient, Transport, Account, Hash as Hash$1, Address } from 'viem';
-import { ChainId, IEvmWalletProvider, EvmRawTransaction, EvmRawTransactionReceipt, ISuiWalletProvider, SuiTransaction, SuiExecutionResult, SuiPaginatedCoins, IIconWalletProvider, IcxCallTransaction, IconTransactionResult, IInjectiveWalletProvider, JsonObject, InjectiveRawTransaction, InjectiveEoaAddress, InjectiveCoin, InjectiveExecuteResponse, ISolanaWalletProvider, SolanaRpcResponseAndContext, SolanaSignatureResult, TransactionSignature, SolanaRawTransactionInstruction, SolanaSerializedTransaction, SolanaBase58PublicKey, Hex as Hex$1, XDR, IStellarWalletProvider, StellarRawTransactionReceipt, IStacksWalletProvider, StacksTransactionParams, AddressType, IBitcoinWalletProvider, INearWalletProvider, CallContractParams, NearRawTransaction } from '@sodax/types';
-import { SuiClient } from '@mysten/sui/client';
+import { WalletClient, Transport, Chain, Account, PublicClient, PublicClientConfig, WalletClientConfig, HttpTransportConfig, SendTransactionParameters, WaitForTransactionReceiptParameters, Address, Hash as Hash$1 } from 'viem';
+export { Account, Address, Chain, HttpTransportConfig, PublicClient, PublicClientConfig, SendTransactionParameters, TransactionReceipt, Transport, WaitForTransactionReceiptParameters, WalletClient, WalletClientConfig } from 'viem';
+import { SuiClient, SuiTransactionBlockResponseOptions } from '@mysten/sui/client';
+export { SuiTransactionBlockResponseOptions } from '@mysten/sui/client';
 import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
-import { Transaction } from '@mysten/sui/transactions';
 import { WalletWithFeatures, SuiWalletFeatures, WalletAccount } from '@mysten/wallet-standard';
-import { IconService, Wallet } from 'icon-sdk-js';
+export { SuiWalletFeatures, WalletAccount, WalletWithFeatures } from '@mysten/wallet-standard';
+import { Transaction } from '@mysten/sui/transactions';
+export { Transaction, TransactionArgument } from '@mysten/sui/transactions';
+import { Wallet, IconService } from 'icon-sdk-js';
 import { Network } from '@injectivelabs/networks';
-import { MsgBroadcaster } from '@injectivelabs/wallet-core';
+export { Network } from '@injectivelabs/networks';
 import { MsgBroadcasterWithPk } from '@injectivelabs/sdk-ts';
-import { ChainId as ChainId$1, EvmChainId } from '@injectivelabs/ts-types';
-import { PublicKey, Connection, Commitment, RpcResponseAndContext, TokenAmount } from '@solana/web3.js';
+import { ChainId, EvmChainId } from '@injectivelabs/ts-types';
+export { ChainId, EvmChainId } from '@injectivelabs/ts-types';
+import { MsgBroadcaster } from '@injectivelabs/wallet-core';
+export { MsgBroadcaster } from '@injectivelabs/wallet-core';
+import { PublicKey, Commitment, ConnectionConfig, SendOptions, Connection, RpcResponseAndContext, TokenAmount } from '@solana/web3.js';
+export { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
 import { SignerWalletAdapterProps } from '@solana/wallet-adapter-base';
 import { Keypair } from '@stellar/stellar-sdk';
-import { ClarityValue } from '@stacks/transactions';
-import { StacksProvider } from '@stacks/connect';
-import * as bitcoin from 'bitcoinjs-lib';
-import { ECPairInterface } from 'ecpair';
-import { Account as Account$1, JsonRpcProvider } from 'near-api-js';
+export { Networks } from '@stellar/stellar-sdk';
+import { PostConditionMode, ClarityValue } from '@sodax/libs/stacks/core';
+export { ClarityValue, PostConditionMode, PostConditionModeName, StacksNetwork } from '@sodax/libs/stacks/core';
+import { StacksProvider } from '@sodax/libs/stacks/connect';
+export { StacksProvider } from '@sodax/libs/stacks/connect';
 import { NearConnector } from '@hot-labs/near-connect';
+export { NearConnector } from '@hot-labs/near-connect';
+import { Account as Account$1, JsonRpcProvider } from 'near-api-js';
+export { KeyPairString } from 'near-api-js';
+import { ECPairInterface } from 'ecpair';
+import * as bitcoin from 'bitcoinjs-lib';
+export { Network as BitcoinJsNetwork } from 'bitcoinjs-lib/src/networks.js';
+
+/**
+ * Common base for all wallet providers in this package.
+ * Holds the `defaults` config and exposes `mergePolicy` for per-call option merging.
+ *
+ * Subclasses are responsible for:
+ *   - declaring `chainType` literal
+ *   - validating their own config variants
+ *   - implementing the chain-specific provider interface
+ *
+ * NOTE: All fields of `TDefaults` (and any nested per-method shape it groups)
+ * MUST be declared optional. The constructor falls back to `{}` when no defaults
+ * are supplied — required fields would silently arrive as `undefined` at runtime
+ * without TypeScript flagging it (the cast erases that constraint).
+ */
+declare abstract class BaseWalletProvider<TDefaults extends object> {
+    protected readonly defaults: TDefaults;
+    constructor(defaults: TDefaults | undefined);
+    /**
+     * Return the connected wallet address as a string. Subclasses may narrow the
+     * return type to a chain-specific brand (e.g. `Address`, `IconEoaAddress`).
+     */
+    abstract getWalletAddress(): Promise<string>;
+    /**
+     * Merge per-call options over a slice of `defaults` keyed by `key`.
+     * Use when defaults are grouped per-method (e.g. `defaults.sendTransaction`).
+     */
+    protected mergePolicy<K extends keyof TDefaults>(key: K, options?: TDefaults[K] extends infer V ? (V extends object ? V : never) : never): TDefaults[K] extends infer V ? (V extends object ? V : never) : never;
+    /**
+     * Merge per-call options over the entire `defaults` object.
+     * Use when defaults are flat (single-level fields).
+     */
+    protected mergeDefaults(options?: Partial<TDefaults>): TDefaults;
+}
 
+/** Send-tx execution params (gas/nonce/fees). Disjoint from EvmRawTransaction by type — no field collision possible. */
+type EvmSendTransactionPolicy = Omit<Partial<SendTransactionParameters>, keyof EvmRawTransaction>;
+/** Wait-for-receipt params (confirmations/polling/timeout). `hash` is positional, not part of the policy. */
+type EvmWaitForTransactionReceiptPolicy = Partial<Omit<WaitForTransactionReceiptParameters, 'hash'>>;
+/**
+ * Defaults applied to every call. Per-call options shallow-merge over these.
+ * `publicClient`/`walletClient`/`transport` only apply in private-key mode
+ * (consumer brings clients in browser-extension mode).
+ */
+type EvmWalletDefaults = {
+    publicClient?: Partial<Omit<PublicClientConfig, 'transport' | 'chain'>>;
+    walletClient?: Partial<Omit<WalletClientConfig, 'transport' | 'chain' | 'account'>>;
+    transport?: HttpTransportConfig;
+    sendTransaction?: EvmSendTransactionPolicy;
+    waitForTransactionReceipt?: EvmWaitForTransactionReceiptPolicy;
+};
+/** Configuration for constructing an `EvmWalletProvider` backed by a raw private key. */
+type PrivateKeyEvmWalletConfig = {
+    privateKey: `0x${string}`;
+    chainId: EvmChainKey;
+    rpcUrl?: `http${string}`;
+    defaults?: EvmWalletDefaults;
+};
+/** Configuration for constructing an `EvmWalletProvider` backed by a browser-extension wallet (viem clients). */
+type BrowserExtensionEvmWalletConfig = {
+    walletClient: WalletClient<Transport, Chain, Account>;
+    publicClient: PublicClient;
+    defaults?: EvmWalletDefaults;
+};
+type EvmWalletConfig = PrivateKeyEvmWalletConfig | BrowserExtensionEvmWalletConfig;
+
+/**
+ * Manually defined viem chain config for HyperEVM.
+ *
+ * HyperEVM is absent from the `viem/chains` package, so the chain is defined
+ * here using `defineChain` with the canonical RPC, block-explorer, and Multicall3
+ * contract address.
+ */
 declare const hyper: {
     blockExplorers: {
         readonly default: {
@@ -53,42 +139,80 @@ declare const hyper: {
     formatters?: undefined;
     serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
 };
-declare function getEvmViemChain(id: ChainId): Chain;
-declare class EvmWalletProvider implements IEvmWalletProvider {
-    private readonly walletClient;
+/**
+ * Returns the viem `Chain` config for the given EVM chain key.
+ *
+ * @param key - An `EvmChainKey` constant (e.g. `ChainKeys.SONIC_MAINNET`).
+ * @returns The corresponding viem chain object.
+ * @throws {Error} If `key` is not a recognised EVM chain key.
+ */
+declare function getEvmViemChain(key: EvmChainKey): Chain;
+/** Returns `true` when `config` carries a hex private key (server-side / script usage). */
+declare function isPrivateKeyEvmWalletConfig(config: EvmWalletConfig): config is PrivateKeyEvmWalletConfig;
+/** Returns `true` when `config` carries pre-built viem wallet and public clients (browser extension / dApp usage). */
+declare function isBrowserExtensionEvmWalletConfig(config: EvmWalletConfig): config is BrowserExtensionEvmWalletConfig;
+/**
+ * EVM wallet provider backed by [viem](https://viem.sh).
+ *
+ * Supports two modes selected by config shape:
+ * - **Private-key** (`PrivateKeyEvmWalletConfig`): creates its own viem wallet and public
+ *   clients from the supplied private key, chain ID, and optional RPC URL. Intended for
+ *   Node scripts and server-side testing.
+ * - **Browser-extension** (`BrowserExtensionEvmWalletConfig`): accepts pre-built viem clients
+ *   injected by the dApp's wallet adapter (e.g. wagmi). Transport/client defaults are ignored
+ *   in this mode.
+ *
+ * All 12 supported EVM chains are covered via {@link getEvmViemChain}; HyperEVM is defined
+ * locally as {@link hyper} because it is absent from `viem/chains`.
+ */
+declare class EvmWalletProvider extends BaseWalletProvider<EvmWalletDefaults> implements IEvmWalletProvider {
+    readonly chainType: "EVM";
     readonly publicClient: PublicClient;
+    private readonly walletClient;
     constructor(config: EvmWalletConfig);
-    sendTransaction(evmRawTx: EvmRawTransaction): Promise<Hash$1>;
-    waitForTransactionReceipt(txHash: Hash$1): Promise<EvmRawTransactionReceipt>;
     getWalletAddress(): Promise<Address>;
+    /** Submits a signed transaction to the network and returns the transaction hash. */
+    sendTransaction(txData: EvmRawTransaction, options?: EvmSendTransactionPolicy): Promise<Hash$1>;
+    /**
+     * Polls until the transaction is included in a block and returns the serialised receipt.
+     * All `bigint` fields are converted to strings to allow safe JSON serialisation.
+     */
+    waitForTransactionReceipt(txHash: Hash$1, options?: EvmWaitForTransactionReceiptPolicy): Promise<EvmRawTransactionReceipt>;
+    private static serializeReceipt;
 }
+
 /**
- * EVM Wallet Configuration Types
+ * signAndExecuteTxn behavior. Pre-flight dry-run is enabled by default — disable only when
+ * paying gas for a doomed tx is acceptable. `response` options forward to the underlying
+ * SuiClient call (signAndExecuteTransaction in PK mode, executeTransactionBlock in browser-ext).
  */
-type PrivateKeyEvmWalletConfig = {
-    privateKey: `0x${string}`;
-    chainId: ChainId;
-    rpcUrl?: `http${string}`;
+type SuiSignAndExecutePolicy = {
+    dryRun?: {
+        enabled?: boolean;
+    };
+    response?: SuiTransactionBlockResponseOptions;
 };
-type BrowserExtensionEvmWalletConfig = {
-    walletClient: WalletClient<Transport, Chain, Account>;
-    publicClient: PublicClient;
+/** getCoins pagination policy. */
+type SuiGetCoinsPolicy = {
+    limit?: number;
 };
-type EvmWalletConfig = PrivateKeyEvmWalletConfig | BrowserExtensionEvmWalletConfig;
-/**
- * EVM Type Guards
- */
-declare function isPrivateKeyEvmWalletConfig(config: EvmWalletConfig): config is PrivateKeyEvmWalletConfig;
-declare function isBrowserExtensionEvmWalletConfig(config: EvmWalletConfig): config is BrowserExtensionEvmWalletConfig;
-
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type SuiWalletDefaults = {
+    signAndExecuteTxn?: SuiSignAndExecutePolicy;
+    getCoins?: SuiGetCoinsPolicy;
+};
+/** Configuration for constructing a `SuiWalletProvider` backed by a mnemonic-derived private key. */
 type PrivateKeySuiWalletConfig = {
     rpcUrl: string;
     mnemonics: string;
+    defaults?: SuiWalletDefaults;
 };
+/** Configuration for constructing a `SuiWalletProvider` backed by a browser-extension wallet. */
 type BrowserExtensionSuiWalletConfig = {
     client: SuiClient;
     wallet: WalletWithFeatures<Partial<SuiWalletFeatures>>;
     account: WalletAccount;
+    defaults?: SuiWalletDefaults;
 };
 type SuiWalletConfig = PrivateKeySuiWalletConfig | BrowserExtensionSuiWalletConfig;
 type PkSuiWallet = {
@@ -99,43 +223,51 @@ type BrowserExtensionSuiWallet = {
     account: WalletAccount;
 };
 type SuiWallet = PkSuiWallet | BrowserExtensionSuiWallet;
+
 declare function isPkSuiWallet(wallet: SuiWallet): wallet is PkSuiWallet;
 declare function isBrowserExtensionSuiWallet(wallet: SuiWallet): wallet is BrowserExtensionSuiWallet;
-declare function isSuiWallet(wallet: SuiWallet): wallet is SuiWallet;
-declare class SuiWalletProvider implements ISuiWalletProvider {
+declare class SuiWalletProvider extends BaseWalletProvider<SuiWalletDefaults> implements ISuiWalletProvider {
+    readonly chainType: "SUI";
     private readonly client;
     private readonly wallet;
     constructor(walletConfig: SuiWalletConfig);
-    signAndExecuteTxn(txn: SuiTransaction): Promise<string>;
+    getWalletAddress(): Promise<string>;
+    signAndExecuteTxn(txn: SuiTransaction, options?: SuiSignAndExecutePolicy): Promise<string>;
     viewContract(tx: Transaction, packageId: string, module: string, functionName: string, args: unknown[], typeArgs?: string[]): Promise<SuiExecutionResult>;
-    getCoins(address: string, token: string): Promise<SuiPaginatedCoins>;
+    getCoins(address: string, token: string, options?: SuiGetCoinsPolicy): Promise<SuiPaginatedCoins>;
+    private buildAndDryRunOrThrow;
+    private buildOnly;
+    private assertEffectsSuccess;
     private getSuiAddress;
-    getWalletAddress(): Promise<string>;
 }
 
-declare class IconWalletProvider implements IIconWalletProvider {
-    private readonly wallet;
-    readonly iconService: IconService;
-    constructor(wallet: IconWalletConfig);
-    sendTransaction(tx: IcxCallTransaction): Promise<Hash>;
-    waitForTransactionReceipt(txHash: Hash): Promise<IconTransactionResult>;
-    getWalletAddress(): Promise<IconEoaAddress>;
-}
-/**
- * Icon Types
- */
 type IconJsonRpcVersion = '2.0';
 type Hex = `0x${string}`;
 type Hash = `0x${string}`;
 type IconAddress = `hx${string}` | `cx${string}`;
 type IconEoaAddress = `hx${string}`;
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type IconWalletDefaults = {
+    /** Step limit (gas) for transactions. Default `3_000_000`. */
+    stepLimit?: number;
+    /** Transaction version. Default `'0x3'`. */
+    version?: string;
+    /** Timestamp generator (microseconds). Default `() => Date.now() * 1000`. */
+    timestampProvider?: () => number;
+    /** Event ID for `requestJsonRpc` (browser-extension path). Default `99999`. */
+    jsonRpcId?: number;
+};
+/** Configuration for constructing an `IconWalletProvider` backed by a raw private key. */
 type PrivateKeyIconWalletConfig = {
     privateKey: `0x${string}`;
     rpcUrl: `http${string}`;
+    defaults?: IconWalletDefaults;
 };
+/** Configuration for constructing an `IconWalletProvider` backed by a browser-extension wallet (Hana Wallet). */
 type BrowserExtensionIconWalletConfig = {
     walletAddress?: IconEoaAddress;
     rpcUrl: `http${string}`;
+    defaults?: IconWalletDefaults;
 };
 type IconWalletConfig = PrivateKeyIconWalletConfig | BrowserExtensionIconWalletConfig;
 type IconPkWallet = {
@@ -177,6 +309,16 @@ type JsonRpcPayloadResponse = {
     id: number;
     result: string;
 };
+
+declare class IconWalletProvider extends BaseWalletProvider<IconWalletDefaults> implements IIconWalletProvider {
+    readonly chainType: "ICON";
+    readonly iconService: IconService;
+    private readonly wallet;
+    constructor(wallet: IconWalletConfig);
+    sendTransaction(tx: IcxCallTransaction, options?: IconWalletDefaults): Promise<Hash>;
+    waitForTransactionReceipt(txHash: Hash): Promise<IconTransactionResult>;
+    getWalletAddress(): Promise<IconEoaAddress>;
+}
 /**
  * Icon Type Guards
  */
@@ -201,79 +343,134 @@ declare function requestJsonRpc(rawTransaction: unknown, id?: number): Promise<J
 declare function BigNumberToBigInt(bigNumber: BigNumber): bigint;
 
 /**
- * Injective Wallet Configuration Types
+ * Defaults applied to every call. Per-call options shallow-merge over these.
+ * `msgBroadcaster` options apply at construction time only (private-key path) —
+ * the upstream MsgBroadcasterWithPk doesn't support post-construction reconfig.
  */
+type InjectiveWalletDefaults = {
+    /** Coins attached to `getRawTransaction`/`execute` if caller doesn't supply funds. */
+    defaultFunds?: InjectiveCoin[];
+    /** Default memo on transactions. */
+    defaultMemo?: string;
+    /** Sequence override for `createTransaction`. Default 0. */
+    sequence?: number;
+    /** Account number override for `createTransaction`. Default 0. */
+    accountNumber?: number;
+};
 type BrowserExtensionInjectiveWalletConfig = {
     msgBroadcaster: MsgBroadcaster;
+    defaults?: InjectiveWalletDefaults;
 };
+/**
+ * Server-side / private-key Injective wallet configuration.
+ *
+ * Unlike most providers that accept a top-level `privateKey`, Injective nests
+ * credentials under `secret` to accommodate both a raw private key and a BIP-39
+ * mnemonic phrase as first-class alternatives:
+ *
+ * ```ts
+ * // Private-key variant
+ * { secret: { privateKey: '0x…' }, chainId, network }
+ *
+ * // Mnemonic variant
+ * { secret: { mnemonics: 'word1 word2 …' }, chainId, network }
+ * ```
+ *
+ * This mirrors the `PrivateKey.fromPrivateKey` / `PrivateKey.fromMnemonic` split
+ * in `@injectivelabs/sdk-ts` and avoids a union at the config root.
+ */
 type SecretInjectiveWalletConfig = {
     secret: {
         privateKey: string;
     } | {
         mnemonics: string;
     };
-    chainId: ChainId$1;
+    chainId: ChainId;
     network: Network;
+    /**
+     * Reserved for future EVM-sidecar support on Injective.
+     *
+     * @remarks Currently unused — `InjectiveWalletProvider` does not read this
+     * field. It is declared here to keep the config shape stable while EVM
+     * compatibility is under development.
+     */
     evmOptions?: {
         evmChainId: EvmChainId;
         rpcUrl: `http${string}`;
     };
+    defaults?: InjectiveWalletDefaults;
 };
 type InjectiveWalletConfig = BrowserExtensionInjectiveWalletConfig | SecretInjectiveWalletConfig;
-/**
- * Injective Type Guards
- */
-declare function isBrowserExtensionInjectiveWalletConfig(config: InjectiveWalletConfig): config is BrowserExtensionInjectiveWalletConfig;
-declare function isSecretInjectiveWalletConfig(config: InjectiveWalletConfig): config is SecretInjectiveWalletConfig;
 type InjectiveWallet = {
     msgBroadcaster: MsgBroadcaster | MsgBroadcasterWithPk;
 };
-declare class InjectiveWalletProvider implements IInjectiveWalletProvider {
+
+declare function isBrowserExtensionInjectiveWalletConfig(config: InjectiveWalletConfig): config is BrowserExtensionInjectiveWalletConfig;
+declare function isSecretInjectiveWalletConfig(config: InjectiveWalletConfig): config is SecretInjectiveWalletConfig;
+declare class InjectiveWalletProvider extends BaseWalletProvider<InjectiveWalletDefaults> implements IInjectiveWalletProvider {
+    readonly chainType: "INJECTIVE";
     wallet: InjectiveWallet;
     constructor(config: InjectiveWalletConfig);
-    getRawTransaction(chainId: string, _: string, senderAddress: string, contractAddress: string, msg: JsonObject, memo?: string): Promise<InjectiveRawTransaction>;
+    /**
+     * Builds a signed-but-unbroadcast Injective transaction for a CosmWasm contract call.
+     *
+     * @param chainId - Injective chain ID (e.g. `"injective-1"`).
+     * @param _ - Unused positional parameter retained for interface-compat with other spoke
+     *   providers that accept a signer public key at this position. Injective derives the
+     *   public key internally via {@link getWalletPubKey}; pass an empty string `""` here.
+     * @param senderAddress - Bech32 address of the transaction sender.
+     * @param contractAddress - CosmWasm contract address to call.
+     * @param msg - JSON execute message sent to the contract.
+     * @param memo - Optional transaction memo; falls back to `defaults.defaultMemo` then `""`.
+     * @param options - Per-call overrides for defaults (funds, memo, sequence, accountNumber).
+     */
+    getRawTransaction(chainId: string, _: string, senderAddress: string, contractAddress: string, msg: JsonObject, memo?: string, options?: InjectiveWalletDefaults): Promise<InjectiveRawTransaction>;
     getWalletAddress(): Promise<InjectiveEoaAddress>;
     getWalletPubKey(): Promise<string>;
-    execute(senderAddress: string, contractAddress: string, msg: JsonObject, funds?: InjectiveCoin[]): Promise<InjectiveExecuteResponse>;
+    execute(senderAddress: string, contractAddress: string, msg: JsonObject, funds?: InjectiveCoin[], options?: InjectiveWalletDefaults): Promise<InjectiveExecuteResponse>;
 }
 
 interface WalletContextState {
     publicKey: PublicKey | null;
     signTransaction: SignerWalletAdapterProps['signTransaction'] | undefined;
 }
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type SolanaWalletDefaults = {
+    /** Commitment for `Connection`. Default `'confirmed'`. */
+    connectionCommitment?: Commitment;
+    /** Full ConnectionConfig (overrides `connectionCommitment` if present). */
+    connectionConfig?: ConnectionConfig;
+    /** Default `SendOptions` for `sendRawTransaction`. */
+    sendOptions?: SendOptions;
+    /** Commitment for confirmation polling. Default `'finalized'`. */
+    confirmCommitment?: Commitment;
+};
+/** Configuration for constructing a `SolanaWalletProvider` backed by a raw private key. */
 type PrivateKeySolanaWalletConfig = {
     privateKey: Uint8Array;
     endpoint: string;
+    defaults?: SolanaWalletDefaults;
 };
+/** Configuration for constructing a `SolanaWalletProvider` backed by a browser-extension wallet adapter. */
 type BrowserExtensionSolanaWalletConfig = {
     wallet: WalletContextState;
     endpoint: string;
+    defaults?: SolanaWalletDefaults;
 };
 type SolanaWalletConfig = PrivateKeySolanaWalletConfig | BrowserExtensionSolanaWalletConfig;
-declare class SolanaWalletProvider implements ISolanaWalletProvider {
-    private readonly wallet;
+
+declare class SolanaWalletProvider extends BaseWalletProvider<SolanaWalletDefaults> implements ISolanaWalletProvider {
+    readonly chainType: "SOLANA";
     readonly connection: Connection;
+    private readonly wallet;
     private readonly isAdapterMode;
     constructor(walletConfig: SolanaWalletConfig);
     waitForConfirmation(signature: string, commitment?: Commitment): Promise<SolanaRpcResponseAndContext<SolanaSignatureResult>>;
-    /**
-     * Send a raw transaction to the Solana network.
-     * @param rawTransaction - The raw transaction to send.
-     * @returns The transaction signature.
-     */
-    sendTransaction(rawTransaction: Uint8Array | Array<number>): Promise<TransactionSignature>;
-    /**
-     * Send a raw transaction to the Solana network and wait for confirmation.
-     * @param rawTransaction - The raw transaction to send.
-     * @param commitment - The commitment level to use. Defaults to 'finalized'.
-     * @returns The transaction signature.
-     */
-    sendTransactionWithConfirmation(rawTransaction: Uint8Array | Array<number>, commitment?: Commitment): Promise<TransactionSignature>;
-    /**
-     * Build a v0 versioned transaction.
-     * @param instructions - The instructions to include in the transaction.
-     * @returns The v0 transaction.
-     */
+    sendTransaction(rawTransaction: Uint8Array | Array<number>, options?: SendOptions): Promise<TransactionSignature>;
+    sendTransactionWithConfirmation(rawTransaction: Uint8Array | Array<number>, optionsOrCommitment?: Commitment | {
+        send?: SendOptions;
+        commitment?: Commitment;
+    }): Promise<TransactionSignature>;
     buildV0Txn(rawInstructions: SolanaRawTransactionInstruction[]): Promise<SolanaSerializedTransaction>;
     private buildV0TxnWithAdapter;
     private buildV0TxnWithKeypair;
@@ -296,26 +493,31 @@ interface StellarWalletsKit {
     }>;
 }
 type StellarNetwork = 'TESTNET' | 'PUBLIC';
-declare const STELLAR_ERROR_CODES: {
-    readonly INVALID_CONFIG: "INVALID_CONFIG";
-    readonly SIGN_TX_ERROR: "SIGN_TX_ERROR";
-    readonly TX_RECEIPT_TIMEOUT: "TX_RECEIPT_TIMEOUT";
-    readonly SEND_TX_ERROR: "SEND_TX_ERROR";
-    readonly INVALID_NETWORK: "INVALID_NETWORK";
-    readonly INVALID_PRIVATE_KEY: "INVALID_PRIVATE_KEY";
-};
 type StellarAddress = string;
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type StellarWalletDefaults = {
+    /** Polling interval (ms) for `waitForTransactionReceipt`. Default `2000`. */
+    pollInterval?: number;
+    /** Total wait (ms) before timeout. Default `60_000`. Recommended floor `30_000` on mainnet. */
+    pollTimeout?: number;
+    /** Custom network passphrase (use for FUTURENET / private networks). */
+    networkPassphrase?: string;
+};
+/** Configuration for constructing a `StellarWalletProvider` backed by a raw private key. */
 type PrivateKeyStellarWalletConfig = {
     type: 'PRIVATE_KEY';
     privateKey: Hex$1;
     network: StellarNetwork;
     rpcUrl?: string;
+    defaults?: StellarWalletDefaults;
 };
+/** Configuration for constructing a `StellarWalletProvider` backed by a browser-extension wallet. */
 type BrowserExtensionStellarWalletConfig = {
     type: 'BROWSER_EXTENSION';
     walletsKit: StellarWalletsKit;
     network: StellarNetwork;
     rpcUrl?: string;
+    defaults?: StellarWalletDefaults;
 };
 type StellarWalletConfig = PrivateKeyStellarWalletConfig | BrowserExtensionStellarWalletConfig;
 type StellarPkWallet = {
@@ -327,6 +529,15 @@ type StellarBrowserExtensionWallet = {
     walletsKit: StellarWalletsKit;
 };
 type StellarWallet = StellarPkWallet | StellarBrowserExtensionWallet;
+
+declare const STELLAR_ERROR_CODES: {
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly SIGN_TX_ERROR: "SIGN_TX_ERROR";
+    readonly TX_RECEIPT_TIMEOUT: "TX_RECEIPT_TIMEOUT";
+    readonly SEND_TX_ERROR: "SEND_TX_ERROR";
+    readonly INVALID_NETWORK: "INVALID_NETWORK";
+    readonly INVALID_PRIVATE_KEY: "INVALID_PRIVATE_KEY";
+};
 declare class StellarWalletError extends Error {
     readonly code: keyof typeof STELLAR_ERROR_CODES;
     constructor(message: string, code: keyof typeof STELLAR_ERROR_CODES);
@@ -337,40 +548,117 @@ declare function isStellarPkWallet(wallet: StellarWallet): wallet is StellarPkWa
 declare function isStellarBrowserExtensionWallet(wallet: StellarWallet): wallet is StellarBrowserExtensionWallet;
 declare function isValidStellarNetwork(network: string): network is StellarNetwork;
 declare function isValidStellarPrivateKey(privateKey: string): boolean;
-declare class StellarWalletProvider implements IStellarWalletProvider {
+declare class StellarWalletProvider extends BaseWalletProvider<StellarWalletDefaults> implements IStellarWalletProvider {
+    readonly chainType: "STELLAR";
     private readonly wallet;
     private readonly server;
     private readonly networkPassphrase;
     constructor(config: StellarWalletConfig);
     getWalletAddress(): Promise<string>;
+    /**
+     * Signs the given XDR-encoded transaction and returns the signed XDR.
+     * @throws {StellarWalletError} with code `SIGN_TX_ERROR` if signing fails.
+     */
     signTransaction(tx: XDR): Promise<XDR>;
-    waitForTransactionReceipt(txHash: string): Promise<StellarRawTransactionReceipt>;
+    /**
+     * Polls the Horizon server until the transaction is confirmed or the timeout is reached.
+     * @throws {StellarWalletError} with code `TX_RECEIPT_TIMEOUT` if the transaction is not found within `pollTimeout` ms.
+     */
+    waitForTransactionReceipt(txHash: string, options?: Pick<StellarWalletDefaults, 'pollInterval' | 'pollTimeout'>): Promise<StellarRawTransactionReceipt>;
 }
 
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type StacksWalletDefaults = {
+    /** Network selector. Default `'mainnet'`. */
+    network?: 'mainnet' | 'testnet';
+    /** Default post-condition mode if not present in tx params. */
+    postConditionMode?: PostConditionMode;
+};
+/** Configuration for constructing a `StacksWalletProvider` backed by a raw private key. */
 type PrivateKeyStacksWalletConfig = {
     privateKey: string;
     endpoint?: string;
+    defaults?: StacksWalletDefaults;
 };
+/** Configuration for constructing a `StacksWalletProvider` backed by a browser-extension wallet. */
 type BrowserExtensionStacksWalletConfig = {
     address: string;
     endpoint?: string;
     provider?: StacksProvider;
+    defaults?: StacksWalletDefaults;
 };
 type StacksWalletConfig = PrivateKeyStacksWalletConfig | BrowserExtensionStacksWalletConfig;
+type StacksPkWallet = {
+    type: 'PRIVATE_KEY';
+    privateKey: string;
+};
+type StacksBrowserExtensionWallet = {
+    type: 'BROWSER_EXTENSION';
+    address: string;
+    provider?: StacksProvider;
+};
+type StacksWallet = StacksPkWallet | StacksBrowserExtensionWallet;
+
 declare function isPrivateKeyStacksWalletConfig(config: StacksWalletConfig): config is PrivateKeyStacksWalletConfig;
 declare function isBrowserExtensionStacksWalletConfig(config: StacksWalletConfig): config is BrowserExtensionStacksWalletConfig;
-declare class StacksWalletProvider implements IStacksWalletProvider {
+declare class StacksWalletProvider extends BaseWalletProvider<StacksWalletDefaults> implements IStacksWalletProvider {
+    readonly chainType: "STACKS";
     private readonly network;
     private readonly wallet;
     constructor(config: StacksWalletConfig);
-    sendTransaction(txParams: StacksTransactionParams): Promise<string>;
+    sendTransaction(txParams: StacksTransactionParams, options?: Pick<StacksWalletDefaults, 'postConditionMode'>): Promise<string>;
     private sendTransactionWithPrivateKey;
     private sendTransactionWithAdapter;
     readContract(txParams: StacksTransactionParams): Promise<ClarityValue>;
     getWalletAddress(): Promise<string>;
+    getPublicKey(): Promise<string>;
+    /**
+     * Returns the STX balance for the given address in micro-STX.
+     * @warning Network and fetch errors are silently swallowed — `0n` is returned on failure.
+     * Callers cannot distinguish "zero balance" from "fetch failed"; treat `0n` accordingly.
+     */
     getBalance(address: string): Promise<bigint>;
 }
 
+type NearTxExecutionStatus = 'NONE' | 'INCLUDED' | 'EXECUTED_OPTIMISTIC' | 'INCLUDED_FINAL' | 'EXECUTED' | 'FINAL';
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type NearWalletDefaults = {
+    /** Throw on failure flag for `signAndSendTransaction` (PK path). Default `true`. */
+    throwOnFailure?: boolean;
+    /** Wait-until status for confirmation. Default `'FINAL'`. */
+    waitUntil?: NearTxExecutionStatus;
+    /** Default gas if tx omits. */
+    gasDefault?: bigint;
+    /** Default deposit if tx omits. */
+    depositDefault?: bigint;
+};
+/** Configuration for constructing a `NearWalletProvider` backed by a raw private key. */
+type PrivateKeyNearWalletConfig = {
+    rpcUrl: string;
+    accountId: string;
+    privateKey: string;
+    defaults?: NearWalletDefaults;
+};
+/** Configuration for constructing a `NearWalletProvider` backed by a browser-extension wallet. */
+type BrowserExtensionNearWalletConfig = {
+    wallet: NearConnector;
+    defaults?: NearWalletDefaults;
+};
+type NearWalletConfig = PrivateKeyNearWalletConfig | BrowserExtensionNearWalletConfig;
+
+declare function isPrivateKeyNearWalletConfig(config: NearWalletConfig): config is PrivateKeyNearWalletConfig;
+declare function isBrowserExtensionNearWalletConfig(config: NearWalletConfig): config is BrowserExtensionNearWalletConfig;
+declare class NearWalletProvider extends BaseWalletProvider<NearWalletDefaults> implements INearWalletProvider {
+    readonly chainType: "NEAR";
+    readonly account?: Account$1;
+    readonly rpcProvider?: JsonRpcProvider;
+    private readonly wallet?;
+    constructor(config: NearWalletConfig);
+    getWalletAddress(): Promise<string>;
+    getRawTransaction(params: CallContractParams): Promise<NearRawTransaction>;
+    signAndSubmitTxn(transaction: NearRawTransaction, options?: NearWalletDefaults): Promise<string>;
+}
+
 type BitcoinNetwork = 'TESTNET' | 'MAINNET';
 interface BitcoinWalletsKit {
     getAccounts(): Promise<string[]>;
@@ -383,71 +671,69 @@ interface BitcoinWalletsKit {
     getPublicKey(): Promise<string>;
     sendBitcoin?(toAddress: string, satoshis: number): Promise<string>;
 }
+/** Defaults applied to every call. Per-call options shallow-merge over these. */
+type BitcoinWalletDefaults = {
+    /** Default `finalize` flag for `signTransaction`. Default `true`. */
+    defaultFinalize?: boolean;
+};
+/** Configuration for constructing a `BitcoinWalletProvider` backed by a raw private key. */
 type PrivateKeyBitcoinWalletConfig = {
     type: 'PRIVATE_KEY';
     privateKey: Hex$1;
     network: BitcoinNetwork;
-    addressType?: AddressType;
+    addressType?: BtcAddressType;
+    defaults?: BitcoinWalletDefaults;
 };
+/** Configuration for constructing a `BitcoinWalletProvider` backed by a browser-extension wallet. */
 type BrowserExtensionBitcoinWalletConfig = {
     type: 'BROWSER_EXTENSION';
     walletsKit: BitcoinWalletsKit;
     network: BitcoinNetwork;
+    defaults?: BitcoinWalletDefaults;
 };
 type BitcoinWalletConfig = PrivateKeyBitcoinWalletConfig | BrowserExtensionBitcoinWalletConfig;
+type BitcoinPkWallet = {
+    type: 'PRIVATE_KEY';
+    keyPair: ECPairInterface;
+    addressType: BtcAddressType;
+};
+type BitcoinBrowserWallet = {
+    type: 'BROWSER_EXTENSION';
+    walletsKit: BitcoinWalletsKit;
+};
+type BitcoinWallet = BitcoinPkWallet | BitcoinBrowserWallet;
+
 declare class BitcoinWalletError extends Error {
     constructor(message: string);
 }
-declare class BitcoinWalletProvider implements IBitcoinWalletProvider {
+declare class BitcoinWalletProvider extends BaseWalletProvider<BitcoinWalletDefaults> implements IBitcoinWalletProvider {
+    readonly chainType: "BITCOIN";
     private readonly wallet;
     private readonly network;
     constructor(config: BitcoinWalletConfig);
     getWalletAddress(): Promise<string>;
+    /**
+     * Returns the public key as a hex string.
+     * Private-key mode: returns the 32-byte x-only pubkey for P2TR addresses, or the full
+     * 33-byte compressed pubkey for all other address types.
+     * Browser-extension mode: delegates to the wallet kit's `getPublicKey()`.
+     */
     getPublicKey(): Promise<string>;
-    getAddressType(address: string): Promise<AddressType>;
+    getAddressType(address: string): Promise<BtcAddressType>;
     /**
      * Sign PSBT and return fully signed transaction hex
      */
     signTransaction(psbtBase64: string, finalize?: boolean): Promise<string>;
+    private doSignTransaction;
     /**
-     * Sign arbitrary message using ECDSA
-     * Used for withdrawals
+     * Sign arbitrary message using ECDSA over keccak256(message).
+     * Note: uses keccak256 (Ethereum-style) rather than Bitcoin's double-SHA256 standard,
+     * making this non-standard for typical Bitcoin message signing. Used for cross-chain withdrawals.
      */
     signEcdsaMessage(message: string): Promise<string>;
     signBip322Message(message: string): Promise<string>;
-    getPayment(keyPair: ECPairInterface, addressType: AddressType): bitcoin.Payment;
+    getPayment(keyPair: ECPairInterface, addressType: BtcAddressType): bitcoin.Payment;
     sendBitcoin(toAddress: string, satoshis: bigint): Promise<string>;
 }
 
-/**
- * Near Wallet Configuration Types
- */
-type PrivateKeyNearWalletConfig = {
-    rpcUrl: string;
-    accountId: string;
-    privateKey: string;
-};
-type BrowserExtensionNearWalletConfig = {
-    wallet: NearConnector;
-};
-type NearWalletConfig = PrivateKeyNearWalletConfig | BrowserExtensionNearWalletConfig;
-/**
- * Near Type Guards
- */
-declare function isPrivateKeyNearWalletConfig(config: NearWalletConfig): config is PrivateKeyNearWalletConfig;
-declare function isBrowserExtensionNearWalletConfig(config: NearWalletConfig): config is BrowserExtensionNearWalletConfig;
-/**
- * NearWalletProvider implements INearWalletProvider
- * Supports both private key and browser extension wallet configurations
- */
-declare class NearWalletProvider implements INearWalletProvider {
-    readonly account?: Account$1;
-    readonly rpcProvider?: JsonRpcProvider;
-    private readonly wallet?;
-    constructor(config: NearWalletConfig);
-    getWalletAddress(): Promise<string>;
-    getRawTransaction(params: CallContractParams): Promise<NearRawTransaction>;
-    signAndSubmitTxn(transaction: NearRawTransaction): Promise<string>;
-}
-
-export { BigNumberToBigInt, type BitcoinNetwork, type BitcoinWalletConfig, BitcoinWalletError, BitcoinWalletProvider, type BitcoinWalletsKit, type BrowserExtensionBitcoinWalletConfig, type BrowserExtensionEvmWalletConfig, type BrowserExtensionIconWalletConfig, type BrowserExtensionInjectiveWalletConfig, type BrowserExtensionNearWalletConfig, type BrowserExtensionSolanaWalletConfig, type BrowserExtensionStacksWalletConfig, type BrowserExtensionStellarWalletConfig, type BrowserExtensionSuiWallet, type BrowserExtensionSuiWalletConfig, type EvmWalletConfig, EvmWalletProvider, type HanaWalletRequestEvent, type HanaWalletResponseEvent, type Hash, type Hex, type IconAddress, type IconBrowserExtensionWallet, type IconEoaAddress, type IconJsonRpcVersion, type IconPkWallet, type IconWallet, type IconWalletConfig, IconWalletProvider, type InjectiveWallet, type InjectiveWalletConfig, InjectiveWalletProvider, type JsonRpcPayloadResponse, type NearWalletConfig, NearWalletProvider, type PkSuiWallet, type PrivateKeyBitcoinWalletConfig, type PrivateKeyEvmWalletConfig, type PrivateKeyIconWalletConfig, type PrivateKeyNearWalletConfig, type PrivateKeySolanaWalletConfig, type PrivateKeyStacksWalletConfig, type PrivateKeyStellarWalletConfig, type PrivateKeySuiWalletConfig, type RelayRequestDetail, type RelayRequestSigning, type ResponseAddressType, type ResponseSigningType, type SecretInjectiveWalletConfig, type SolanaWalletConfig, SolanaWalletProvider, type StacksWalletConfig, StacksWalletProvider, type StellarAddress, type StellarBrowserExtensionWallet, type StellarNetwork, type StellarPkWallet, type StellarWallet, type StellarWalletConfig, StellarWalletError, StellarWalletProvider, type SuiWallet, type SuiWalletConfig, SuiWalletProvider, getEvmViemChain, hyper, isBrowserExtensionEvmWalletConfig, isBrowserExtensionIconWalletConfig, isBrowserExtensionInjectiveWalletConfig, isBrowserExtensionNearWalletConfig, isBrowserExtensionStacksWalletConfig, isBrowserExtensionStellarWalletConfig, isBrowserExtensionSuiWallet, isIconAddress, isIconBrowserExtensionWallet, isIconEoaAddress, isIconPkWallet, isJsonRpcPayloadResponse, isPkSuiWallet, isPrivateKeyEvmWalletConfig, isPrivateKeyIconWalletConfig, isPrivateKeyNearWalletConfig, isPrivateKeyStacksWalletConfig, isPrivateKeyStellarWalletConfig, isResponseAddressType, isResponseSigningType, isSecretInjectiveWalletConfig, isStellarBrowserExtensionWallet, isStellarPkWallet, isSuiWallet, isValidStellarNetwork, isValidStellarPrivateKey, requestAddress, requestJsonRpc, requestSigning };
+export { BaseWalletProvider, BigNumberToBigInt, type BitcoinBrowserWallet, type BitcoinNetwork, type BitcoinPkWallet, type BitcoinWallet, type BitcoinWalletConfig, type BitcoinWalletDefaults, BitcoinWalletError, BitcoinWalletProvider, type BitcoinWalletsKit, type BrowserExtensionBitcoinWalletConfig, type BrowserExtensionEvmWalletConfig, type BrowserExtensionIconWalletConfig, type BrowserExtensionInjectiveWalletConfig, type BrowserExtensionNearWalletConfig, type BrowserExtensionSolanaWalletConfig, type BrowserExtensionStacksWalletConfig, type BrowserExtensionStellarWalletConfig, type BrowserExtensionSuiWallet, type BrowserExtensionSuiWalletConfig, type EvmSendTransactionPolicy, type EvmWaitForTransactionReceiptPolicy, type EvmWalletConfig, type EvmWalletDefaults, EvmWalletProvider, type HanaWalletRequestEvent, type HanaWalletResponseEvent, type Hash, type Hex, type IconAddress, type IconBrowserExtensionWallet, type IconEoaAddress, type IconJsonRpcVersion, type IconPkWallet, type IconWallet, type IconWalletConfig, type IconWalletDefaults, IconWalletProvider, type InjectiveWallet, type InjectiveWalletConfig, type InjectiveWalletDefaults, InjectiveWalletProvider, type JsonRpcPayloadResponse, type NearTxExecutionStatus, type NearWalletConfig, type NearWalletDefaults, NearWalletProvider, type PkSuiWallet, type PrivateKeyBitcoinWalletConfig, type PrivateKeyEvmWalletConfig, type PrivateKeyIconWalletConfig, type PrivateKeyNearWalletConfig, type PrivateKeySolanaWalletConfig, type PrivateKeyStacksWalletConfig, type PrivateKeyStellarWalletConfig, type PrivateKeySuiWalletConfig, type RelayRequestDetail, type RelayRequestSigning, type ResponseAddressType, type ResponseSigningType, type SecretInjectiveWalletConfig, type SolanaWalletConfig, type SolanaWalletDefaults, SolanaWalletProvider, type StacksBrowserExtensionWallet, type StacksPkWallet, type StacksWallet, type StacksWalletConfig, type StacksWalletDefaults, StacksWalletProvider, type StellarAddress, type StellarBrowserExtensionWallet, type StellarNetwork, type StellarPkWallet, type StellarWallet, type StellarWalletConfig, type StellarWalletDefaults, StellarWalletError, StellarWalletProvider, type StellarWalletsKit, type SuiGetCoinsPolicy, type SuiSignAndExecutePolicy, type SuiWallet, type SuiWalletConfig, type SuiWalletDefaults, SuiWalletProvider, type WalletContextState, getEvmViemChain, hyper, isBrowserExtensionEvmWalletConfig, isBrowserExtensionIconWalletConfig, isBrowserExtensionInjectiveWalletConfig, isBrowserExtensionNearWalletConfig, isBrowserExtensionStacksWalletConfig, isBrowserExtensionStellarWalletConfig, isBrowserExtensionSuiWallet, isIconAddress, isIconBrowserExtensionWallet, isIconEoaAddress, isIconPkWallet, isJsonRpcPayloadResponse, isPkSuiWallet, isPrivateKeyEvmWalletConfig, isPrivateKeyIconWalletConfig, isPrivateKeyNearWalletConfig, isPrivateKeyStacksWalletConfig, isPrivateKeyStellarWalletConfig, isResponseAddressType, isResponseSigningType, isSecretInjectiveWalletConfig, isStellarBrowserExtensionWallet, isStellarPkWallet, isValidStellarNetwork, isValidStellarPrivateKey, requestAddress, requestJsonRpc, requestSigning };