@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/transaction-forwarder-5mAMTjw6.d.ts

@@ -0,0 +1,1155 @@
+import { A as AccountInfoProviderFunction, C as CreateSolanaRpcFunction, G as GetLatestBlockhash, a as GetEpochInfo, I as IUmbraSigner, b as CreateSolanaRpcSubscriptionsFunction, S as SendAndConfirmTransactionFactoryFunction, T as TransactionForwarder } from './client-V4AF6Bz9.js';
+import { KeyPairSigner, Commitment } from '@solana/kit';
+import { Wallet, WalletAccount } from '@wallet-standard/core';
+import { T as TransactionSignature } from './types-CxfTIpN9.js';
+
+/**
+ * RPC Account Info Provider.
+ *
+ * This module provides the factory function {@link getRpcAccountInfoProvider}
+ * that creates an {@link AccountInfoProviderFunction} for fetching raw, encoded
+ * Solana account data via the JSON-RPC API.
+ *
+ * ## Overview
+ *
+ * The provider wraps Solana's `getMultipleAccounts` RPC method, exposed through
+ * `@solana/kit`'s `fetchEncodedAccounts` helper. It returns account data as
+ * `MaybeEncodedAccount` values — discriminated unions that indicate whether
+ * each queried account exists on-chain.
+ *
+ * ## How It Works
+ *
+ * 1. The factory accepts an RPC URL and returns a **function** (not an object).
+ * 2. The function accepts an array of Solana addresses and returns a
+ *    `Map<Address, MaybeEncodedAccount>`.
+ * 3. Input addresses are **deduplicated** before the RPC call to avoid wasting
+ *    bandwidth on redundant `getMultipleAccounts` slots.
+ * 4. The RPC client is created **lazily** on first invocation — no connection
+ *    is established until the function is actually called.
+ * 5. Subsequent calls reuse the same RPC client instance (singleton per factory).
+ *
+ * ## Usage in the SDK
+ *
+ * This provider is wired into the {@link IUmbraClient} at construction time via
+ * `getUmbraClient()`. Service factories (deposit, claim, withdraw, etc.) receive
+ * it through their dependency injection and use it to:
+ *
+ * - Fetch `EncryptedUserAccount` and `EncryptedTokenAccount` PDAs to determine
+ *   instruction variant selection (e.g., new vs. existing account).
+ * - Fetch `ProtocolConfig` to validate program state.
+ * - Fetch `FeeSchedule` and `FeeVault` accounts for fee calculation.
+ * - Fetch mint accounts for Token-2022 transfer fee configuration.
+ *
+ * ## Decoding Accounts
+ *
+ * The returned `MaybeEncodedAccount` values carry raw base64-decoded bytes.
+ * Pass them to Codama-generated decoders to obtain typed program account structs:
+ *
+ * ```typescript
+ * import { decodeEncryptedUserAccount } from "@umbra-privacy/umbra-codama";
+ *
+ * const accountMap = await fetchAccounts([userPda]);
+ * const maybeAccount = accountMap.get(userPda);
+ * if (maybeAccount?.exists) {
+ *   const decoded = decodeEncryptedUserAccount(maybeAccount);
+ *   console.log("User commitment:", decoded.data.userCommitment);
+ * }
+ * ```
+ *
+ * ## Error Handling
+ *
+ * RPC errors (network failures, rate limiting, malformed responses) propagate
+ * as rejected promises. The provider does **not** implement retry logic —
+ * callers are responsible for wrapping calls in their own retry/backoff
+ * strategy if needed.
+ *
+ * ## Testing
+ *
+ * The `AccountInfoProviderFunction` type is a plain async function, making it
+ * trivial to mock in tests without any RPC dependency:
+ *
+ * ```typescript
+ * const mockProvider: AccountInfoProviderFunction = async (addresses) => {
+ *   const map = new Map<Address, MaybeEncodedAccount>();
+ *   for (const addr of addresses) {
+ *     map.set(addr, { exists: false });
+ *   }
+ *   return map;
+ * };
+ * ```
+ *
+ * @see {@link AccountInfoProviderFunction} for the returned function type
+ * @see {@link getRpcAccountInfoProvider} for the factory function
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module solana/account-info-provider
+ */
+
+/**
+ * Configuration for the RPC-based account info provider.
+ *
+ * @since 2.0.0
+ * @public
+ */
+interface RpcBasedAccountInfoProviderConfig {
+    /**
+     * The URL of the Solana RPC endpoint.
+     *
+     * @remarks
+     * Must be an HTTP or HTTPS URL pointing to a Solana JSON-RPC server.
+     * The provider uses `getMultipleAccounts` under the hood via `@solana/kit`'s
+     * `fetchEncodedAccounts` helper.
+     *
+     * Both public RPC endpoints (e.g., `https://api.mainnet-beta.solana.com`)
+     * and private/paid endpoints (e.g., Helius, QuickNode, Triton) are supported.
+     * Private endpoints are recommended for production use to avoid rate limiting.
+     *
+     * @example `"https://api.mainnet-beta.solana.com"`
+     * @example `"https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"`
+     */
+    readonly rpcUrl: string;
+}
+/**
+ * Creates an {@link AccountInfoProviderFunction} that fetches account data
+ * from a Solana RPC endpoint.
+ *
+ * @remarks
+ * The returned function is the **primary account-fetching interface** used
+ * throughout the Umbra SDK. It is designed as a plain async function (not a
+ * class or object with methods) to support the SDK's functional dependency
+ * injection pattern and make mocking trivial.
+ *
+ * ## Lifecycle
+ *
+ * ```
+ * getRpcAccountInfoProvider({ rpcUrl })
+ *   └─► Returns: async (addresses: Address[]) => Map<Address, MaybeEncodedAccount>
+ *         │
+ *         ├─ First call: creates RPC client (lazy singleton)
+ *         ├─ Deduplicates input addresses
+ *         ├─ Calls getMultipleAccounts via fetchEncodedAccounts
+ *         └─ Returns Map<Address, MaybeEncodedAccount>
+ * ```
+ *
+ * ## Commitment Level
+ *
+ * Each call can specify a commitment level via `options.commitment`.
+ * Defaults to `"confirmed"` when not specified. The commitment controls
+ * how finalized the account data must be before it is returned.
+ *
+ * ## Deduplication
+ *
+ * Duplicate entries in the `addresses` array are removed before the RPC call.
+ * Each unique address appears exactly once in the `getMultipleAccounts` request.
+ * The returned `Map` contains one entry per unique input address, in first-seen
+ * order.
+ *
+ * ## Empty Input
+ *
+ * Passing an empty array short-circuits immediately and returns an empty `Map`
+ * without making any RPC call.
+ *
+ * ## Error Propagation
+ *
+ * RPC errors (network failures, endpoint unreachable, rate limiting, malformed
+ * responses) are **not caught** and propagate as rejected promises. Callers
+ * should implement retry logic for production use. Common retryable errors:
+ *
+ * - HTTP 429 (Too Many Requests) — back off and retry
+ * - HTTP 502/503/504 (Server Error) — transient, retry with backoff
+ * - Network timeout — retry with increased timeout
+ *
+ * ## Solana RPC Limits
+ *
+ * `getMultipleAccounts` supports up to **100 addresses** per call. If more
+ * than 100 unique addresses are passed, `@solana/kit` will automatically
+ * batch them into multiple RPC calls. However, this increases latency and
+ * the risk of partial failure.
+ *
+ * @param config - Configuration containing the RPC endpoint URL.
+ * @returns An {@link AccountInfoProviderFunction}: an async function that
+ *   accepts a readonly array of {@link Address} values and resolves to a
+ *   `Map<Address, MaybeEncodedAccount>`. Each map entry corresponds to one
+ *   unique input address, with `{ exists: true, data, ... }` for on-chain
+ *   accounts or `{ exists: false }` for missing accounts.
+ *
+ * @throws The returned function may throw (or reject) with:
+ *   - Network errors if the RPC endpoint is unreachable
+ *   - HTTP errors if the endpoint rate-limits or returns an error status
+ *   - JSON-RPC errors if the request parameters are invalid
+ *
+ * @example
+ * Basic usage — fetching two accounts:
+ * ```typescript
+ * import { getRpcAccountInfoProvider } from "@umbra-privacy/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const fetchAccounts = getRpcAccountInfoProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const addresses = [
+ *   address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"),
+ *   address("11111111111111111111111111111111"),
+ * ];
+ *
+ * const accountMap = await fetchAccounts(addresses);
+ *
+ * for (const [addr, account] of accountMap) {
+ *   if (account.exists) {
+ *     console.log(`${addr}: ${account.data.length} bytes`);
+ *   } else {
+ *     console.log(`${addr}: does not exist`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Decoding a fetched account with a Codama decoder:
+ * ```typescript
+ * import { getRpcAccountInfoProvider } from "@umbra-privacy/sdk";
+ * import { decodeEncryptedUserAccount } from "@umbra-privacy/umbra-codama";
+ *
+ * const fetchAccounts = getRpcAccountInfoProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const accountMap = await fetchAccounts([userAccountPda]);
+ * const maybeAccount = accountMap.get(userAccountPda);
+ *
+ * if (maybeAccount?.exists) {
+ *   const decoded = decodeEncryptedUserAccount(maybeAccount);
+ *   console.log("User commitment registered:", decoded.data.isUserCommitmentRegistered);
+ * } else {
+ *   console.log("User account does not exist — registration required");
+ * }
+ * ```
+ *
+ * @example
+ * Handling duplicate addresses (deduplicated automatically):
+ * ```typescript
+ * const myAddress = address("MyAccount1111111111111111111111111111111111");
+ * const accountMap = await fetchAccounts([myAddress, myAddress, myAddress]);
+ * // Only one RPC slot used; the Map has one entry.
+ * console.log(accountMap.size); // 1
+ * ```
+ *
+ * @example
+ * Using as a mock in tests (no RPC dependency):
+ * ```typescript
+ * import type { AccountInfoProviderFunction } from "@umbra-privacy/sdk/solana";
+ *
+ * const mockFetchAccounts: AccountInfoProviderFunction = async (addresses) => {
+ *   const map = new Map();
+ *   for (const addr of addresses) {
+ *     map.set(addr, { exists: false }); // All accounts "missing"
+ *   }
+ *   return map;
+ * };
+ *
+ * const client = await getUmbraClient(
+ *   { signer, network: "devnet", rpcUrl: "http://localhost:8899" },
+ *   { accountInfoProvider: mockFetchAccounts },
+ * );
+ * ```
+ *
+ * @see {@link AccountInfoProviderFunction} for the returned function type
+ * @see {@link RpcBasedAccountInfoProviderConfig} for the configuration interface
+ * @since 2.0.0
+ * @public
+ */
+declare function getRpcAccountInfoProvider(config: RpcBasedAccountInfoProviderConfig): AccountInfoProviderFunction;
+
+/**
+ * RPC-Based Blockhash Provider Implementation.
+ *
+ * This module provides a factory function for creating a blockhash provider
+ * that fetches the latest blockhash from a Solana RPC endpoint. Blockhashes are
+ * a core component of Solana transaction lifetime management: every transaction
+ * must include a recent blockhash that bounds the window during which it is valid.
+ *
+ * @remarks
+ * The provider created by {@link getRpcBlockhashProvider} is stateless and
+ * performs no caching — every invocation of the returned function issues a fresh
+ * `getLatestBlockhash` RPC call using the `"confirmed"` commitment level (the
+ * default used by `@solana/kit`). Callers that need caching should wrap the
+ * returned function in their own caching layer.
+ *
+ * The returned {@link GetLatestBlockhash} function is designed to be injected into
+ * transaction-building pipelines, enabling straightforward mocking in tests by
+ * substituting a static implementation.
+ *
+ * @see {@link GetLatestBlockhash} for the function type returned by the factory
+ * @see {@link LatestBlockhashResult} for the shape of the fetched data
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module implementation/solana/blockhash-provider
+ */
+
+/**
+ * Configuration for the RPC-based blockhash provider.
+ *
+ * @public
+ */
+interface RpcBasedBlockhashProviderConfig {
+    /**
+     * The URL of the Solana RPC endpoint.
+     *
+     * @remarks
+     * Should be an HTTP or HTTPS URL. WebSocket endpoints are used separately
+     * by the transaction forwarder, not by this provider.
+     *
+     * @example `"https://api.mainnet-beta.solana.com"`
+     * @example `"https://my-rpc.example.com"`
+     */
+    readonly rpcUrl: string;
+}
+/**
+ * Optional dependencies for the RPC-based blockhash provider.
+ *
+ * @remarks
+ * Providing custom dependencies is primarily useful for testing, where a mock
+ * RPC factory can be injected to avoid real network calls. In production, omit
+ * this parameter to use the default `createSolanaRpc` from `@solana/kit`.
+ *
+ * @public
+ */
+interface RpcBasedBlockhashProviderDeps {
+    /**
+     * Optional custom Solana RPC client factory.
+     *
+     * If not provided, uses the default `createSolanaRpc` from `@solana/kit`.
+     * Override this in tests to inject a mock RPC client.
+     *
+     * @defaultValue `createSolanaRpc` from `@solana/kit`
+     */
+    readonly createRpc?: CreateSolanaRpcFunction;
+}
+/**
+ * Creates a blockhash provider that fetches the latest blockhash from a Solana
+ * RPC endpoint.
+ *
+ * The factory constructs a single RPC client from the given URL and closes over
+ * it. Every call to the returned {@link GetLatestBlockhash} function invokes
+ * `rpc.getLatestBlockhash().send()` and extracts `blockhash` and
+ * `lastValidBlockHeight` from the response's `value` field.
+ *
+ * @remarks
+ * **Commitment** — Each call accepts an optional `{ commitment }` parameter
+ * that defaults to `"confirmed"`. Pass `"finalized"` for maximum safety.
+ *
+ * **No caching** — each invocation of the returned function makes an RPC call.
+ * If the same blockhash will be used across many operations in a short window,
+ * callers should fetch it once and reuse the result rather than calling the
+ * provider repeatedly.
+ *
+ *
+ * **Error propagation** — RPC errors (network failures, endpoint unreachable,
+ * rate limiting) are not caught and will propagate as rejections from the
+ * returned promise. Callers are responsible for implementing retry logic if
+ * needed.
+ *
+ * @param config - Configuration containing the RPC endpoint URL.
+ * @param deps - Optional dependencies. Pass a custom `createRpc` for testing.
+ * @returns A {@link GetLatestBlockhash} function. Each call to this function
+ *   issues one `getLatestBlockhash` RPC request and resolves to a
+ *   {@link LatestBlockhashResult}.
+ *
+ * @throws The returned function may throw (or reject) if the RPC endpoint is
+ *   unreachable, returns an unexpected response structure, or rate-limits the
+ *   caller.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { getRpcBlockhashProvider } from "./blockhash-provider";
+ *
+ * const getLatestBlockhash = getRpcBlockhashProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const { blockhash, lastValidBlockHeight } = await getLatestBlockhash();
+ * console.log(`Current blockhash: ${blockhash}`);
+ * console.log(`Valid until block height: ${lastValidBlockHeight}`);
+ * ```
+ *
+ * @example
+ * Using in a transaction-building pipeline:
+ * ```typescript
+ * import { getRpcBlockhashProvider } from "./blockhash-provider";
+ * import {
+ *   createTransactionMessage,
+ *   setTransactionMessageLifetimeUsingBlockhash,
+ *   pipe,
+ * } from "@solana/kit";
+ *
+ * const getLatestBlockhash = getRpcBlockhashProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * async function buildTx() {
+ *   const blockhashResult = await getLatestBlockhash();
+ *   return pipe(
+ *     createTransactionMessage({ version: 0 }),
+ *     (m) => setTransactionMessageLifetimeUsingBlockhash(blockhashResult, m),
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Injecting a mock RPC factory in tests:
+ * ```typescript
+ * import { getRpcBlockhashProvider } from "./blockhash-provider";
+ *
+ * const mockCreateRpc = (_url: string) => ({
+ *   getLatestBlockhash: () => ({
+ *     send: async () => ({
+ *       value: {
+ *         blockhash: "FakeBlockhash1111111111111111111111111111111",
+ *         lastValidBlockHeight: 9999n,
+ *       },
+ *     }),
+ *   }),
+ * });
+ *
+ * const getLatestBlockhash = getRpcBlockhashProvider(
+ *   { rpcUrl: "http://localhost:8899" },
+ *   { createRpc: mockCreateRpc as any },
+ * );
+ *
+ * const result = await getLatestBlockhash();
+ * // result.blockhash === "FakeBlockhash1111111111111111111111111111111"
+ * ```
+ *
+ * @see {@link GetLatestBlockhash} for the returned function type
+ * @see {@link LatestBlockhashResult} for the return value shape
+ * @public
+ */
+declare function getRpcBlockhashProvider(config: RpcBasedBlockhashProviderConfig, deps?: RpcBasedBlockhashProviderDeps): GetLatestBlockhash;
+
+/**
+ * RPC-Based Epoch Info Provider Implementation.
+ *
+ * This module provides a factory function for creating an epoch info provider
+ * that fetches the current epoch information from a Solana RPC endpoint. Epoch
+ * data is used throughout the Umbra SDK primarily to resolve Token-2022 transfer
+ * fee schedules, which can change between epochs.
+ *
+ * @remarks
+ * On Solana mainnet, one epoch spans approximately 432,000 slots (~2–3 days).
+ * The Token-2022 program uses the epoch number to determine which of two
+ * consecutive fee schedules (older vs. newer) is active for a given mint.
+ * Fetching the epoch before constructing a deposit or transfer ensures the SDK
+ * uses the correct fee when computing the amount that will actually land in the
+ * destination account.
+ *
+ * The provider created by {@link getRpcEpochInfoProvider} is stateless and
+ * performs no caching — every invocation of the returned function issues a fresh
+ * `getEpochInfo` RPC call. Because epochs change slowly (every ~2–3 days on
+ * mainnet), short-term caching at the call site is safe and can reduce RPC load.
+ *
+ * @see {@link GetEpochInfo} for the function type returned by the factory
+ * @see {@link EpochInfoResult} for the shape of the fetched data
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module implementation/solana/epoch-info-provider
+ */
+
+/**
+ * Configuration for the RPC-based epoch info provider.
+ *
+ * @public
+ */
+interface RpcBasedEpochInfoProviderConfig {
+    /**
+     * The URL of the Solana RPC endpoint.
+     *
+     * @remarks
+     * Should be an HTTP or HTTPS URL pointing to a Solana JSON-RPC server.
+     *
+     * @example `"https://api.mainnet-beta.solana.com"`
+     * @example `"https://api.devnet.solana.com"`
+     */
+    readonly rpcUrl: string;
+}
+/**
+ * Optional dependencies for the RPC-based epoch info provider.
+ *
+ * @remarks
+ * Providing custom dependencies is primarily useful for testing, where a mock
+ * RPC factory can be injected to return controlled epoch data without real
+ * network calls. In production, omit this parameter to use the default
+ * `createSolanaRpc` from `@solana/kit`.
+ *
+ * @public
+ */
+interface RpcBasedEpochInfoProviderDeps {
+    /**
+     * Optional custom Solana RPC client factory.
+     *
+     * If not provided, uses the default `createSolanaRpc` from `@solana/kit`.
+     * Override in tests to inject a mock RPC client with predetermined responses.
+     *
+     * @defaultValue `createSolanaRpc` from `@solana/kit`
+     */
+    readonly createRpc?: CreateSolanaRpcFunction;
+}
+/**
+ * Creates an epoch info provider that fetches the current epoch information
+ * from a Solana RPC endpoint.
+ *
+ * The factory constructs a single RPC client from the given URL and closes over
+ * it. Every call to the returned {@link GetEpochInfo} function invokes
+ * `rpc.getEpochInfo().send()` and maps the response fields into an
+ * {@link EpochInfoResult}. The `transactionCount` field is conditionally
+ * included only when the RPC node returns a non-null value.
+ *
+ * @remarks
+ * **Commitment** — Each call accepts an optional `{ commitment }` parameter
+ * that defaults to `"confirmed"`. Pass `"finalized"` for maximum safety.
+ *
+ * **No caching** — each invocation of the returned function issues one RPC
+ * call. Epochs change approximately every 2–3 days on mainnet, so callers in
+ * hot paths may safely cache the result for seconds or even minutes without
+ * risk of using a stale epoch.
+ *
+ *
+ * **Token-2022 transfer fees** — The primary consumer of this provider in the
+ * SDK is the transfer-fee calculation logic. Token-2022 mints may define two
+ * consecutive fee schedules. The active schedule is the one whose configured
+ * epoch is less than or equal to `EpochInfoResult.epoch`. Always fetch epoch
+ * info fresh when computing deposit amounts to avoid off-by-one errors at epoch
+ * boundaries.
+ *
+ * **Error propagation** — RPC errors are not caught and will propagate as
+ * rejections from the returned promise. Callers are responsible for implementing
+ * retry logic if needed.
+ *
+ * @param config - Configuration containing the RPC endpoint URL.
+ * @param deps - Optional dependencies. Pass a custom `createRpc` for testing.
+ * @returns A {@link GetEpochInfo} function. Each call to this function issues
+ *   one `getEpochInfo` RPC request and resolves to an {@link EpochInfoResult}.
+ *
+ * @throws The returned function may throw (or reject) if the RPC endpoint is
+ *   unreachable, returns an unexpected response, or rate-limits the caller.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { getRpcEpochInfoProvider } from "./epoch-info-provider";
+ *
+ * const getEpochInfo = getRpcEpochInfoProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const epochInfo = await getEpochInfo();
+ * console.log(`Current epoch: ${epochInfo.epoch}`);
+ * console.log(`Slot ${epochInfo.slotIndex} of ${epochInfo.slotsInEpoch}`);
+ * ```
+ *
+ * @example
+ * Using with Token-2022 transfer fee calculation:
+ * ```typescript
+ * import { getRpcEpochInfoProvider } from "./epoch-info-provider";
+ * import { calculateTransferFee } from "@umbra-privacy/sdk";
+ *
+ * const getEpochInfo = getRpcEpochInfoProvider({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const epochInfo = await getEpochInfo();
+ * const fee = calculateTransferFee(feeConfig, epochInfo.epoch, depositAmount);
+ * // Use (depositAmount + fee) as the transfer amount so the recipient
+ * // lands the exact depositAmount after the protocol deducts the fee.
+ * ```
+ *
+ * @example
+ * Injecting a mock RPC factory in tests:
+ * ```typescript
+ * import { getRpcEpochInfoProvider } from "./epoch-info-provider";
+ *
+ * const mockCreateRpc = (_url: string) => ({
+ *   getEpochInfo: () => ({
+ *     send: async () => ({
+ *       epoch: 500n,
+ *       slotIndex: 100n,
+ *       slotsInEpoch: 432000n,
+ *       absoluteSlot: 216100000n,
+ *       blockHeight: 215800000n,
+ *       transactionCount: null,
+ *     }),
+ *   }),
+ * });
+ *
+ * const getEpochInfo = getRpcEpochInfoProvider(
+ *   { rpcUrl: "http://localhost:8899" },
+ *   { createRpc: mockCreateRpc as any },
+ * );
+ *
+ * const info = await getEpochInfo();
+ * // info.epoch === 500n, info.transactionCount === undefined
+ * ```
+ *
+ * @see {@link GetEpochInfo} for the returned function type
+ * @see {@link EpochInfoResult} for the return value shape
+ * @public
+ */
+declare function getRpcEpochInfoProvider(config: RpcBasedEpochInfoProviderConfig, deps?: RpcBasedEpochInfoProviderDeps): GetEpochInfo;
+
+/**
+ * Signer Helper Functions
+ *
+ * Factory functions and adapters for creating `IUmbraSigner` instances from
+ * common Solana wallet primitives. Covers in-memory keypairs (for testing and
+ * scripting), `@solana/kit` `KeyPairSigner` instances, and browser wallets
+ * that implement the Wallet Standard (`@wallet-standard/core`).
+ *
+ * @since 2.0.0
+ * @module solana/signers
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a new random in-memory keypair signer.
+ *
+ * Generates a fresh Ed25519 keypair using the platform's CSPRNG. The private key
+ * is non-extractable by default (Web Crypto API constraint). Use this for tests,
+ * CI pipelines, and scripts where the wallet lifecycle is managed by your code.
+ *
+ * @example
+ * ```typescript
+ * import { createInMemorySigner, getUmbraClient } from "@umbra-privacy/sdk";
+ *
+ * const signer = await createInMemorySigner();
+ * const client = await getUmbraClient({ signer, network: "devnet", rpcUrl, rpcSubscriptionsUrl });
+ * ```
+ *
+ * @remarks
+ * The keypair exists only in memory. It is lost when the process exits or the page
+ * refreshes. Only use this for testing or scripts where you control the key lifecycle.
+ */
+declare function createInMemorySigner(): Promise<IUmbraSigner>;
+/**
+ * Creates a signer from raw private key bytes.
+ *
+ * Accepts either 64-byte combined key material (private key + public key) or a
+ * 32-byte seed — `@solana/kit` handles both formats via `createKeyPairSignerFromBytes`.
+ *
+ * @param bytes - Raw private key bytes (64-byte keypair or 32-byte seed).
+ *
+ * @example
+ * ```typescript
+ * import { createSignerFromPrivateKeyBytes, getUmbraClient } from "@umbra-privacy/sdk";
+ * import { readFileSync } from "fs";
+ *
+ * // Load from a Solana CLI JSON key file (array of numbers)
+ * const keyFile = JSON.parse(readFileSync("/path/to/keypair.json", "utf8"));
+ * const signer = await createSignerFromPrivateKeyBytes(new Uint8Array(keyFile));
+ * ```
+ */
+declare function createSignerFromPrivateKeyBytes(bytes: Uint8Array): Promise<IUmbraSigner>;
+/**
+ * Adapts an existing `@solana/kit` `KeyPairSigner` to `IUmbraSigner`.
+ *
+ * Use this when you already have a `KeyPairSigner` (e.g., from `generateKeyPairSigner`
+ * or `createKeyPairSignerFromBytes`) and want to pass it to `getUmbraClient`.
+ *
+ * @param kps - A `KeyPairSigner` from `@solana/kit`.
+ *
+ * @example
+ * ```typescript
+ * import { generateKeyPairSigner } from "@solana/kit";
+ * import { createSignerFromKeyPair, getUmbraClient } from "@umbra-privacy/sdk";
+ *
+ * const kps = await generateKeyPairSigner();
+ * const signer = createSignerFromKeyPair(kps);
+ * const client = await getUmbraClient({ signer, network: "devnet", rpcUrl, rpcSubscriptionsUrl });
+ * ```
+ */
+declare function createSignerFromKeyPair(kps: KeyPairSigner): IUmbraSigner;
+/**
+ * Creates an `IUmbraSigner` from a Wallet Standard `WalletAccount`.
+ *
+ * This is the primary adapter for browser wallets (Phantom, Backpack, Solflare, etc.)
+ * that implement the Wallet Standard. Obtain `wallet` and `account` via
+ * `@wallet-standard/react`'s `useWallets()` hook or `@solana/react`.
+ *
+ * Both `"solana:signTransaction"` and `"solana:signMessage"` must be present in
+ * `wallet.features` — an error is thrown immediately if either is missing.
+ *
+ * @param wallet - The Wallet Standard `Wallet` object (provides feature implementations).
+ * @param account - The specific `WalletAccount` to sign with.
+ *
+ * @example
+ * ```typescript
+ * import { useWallet } from "@solana/react"; // or @wallet-standard/react
+ * import { createSignerFromWalletAccount, getUmbraClient } from "@umbra-privacy/sdk";
+ *
+ * function useUmbraClient(rpcUrl: string, rpcSubscriptionsUrl: string) {
+ *   const { wallet, account } = useWallet();
+ *   const signer = createSignerFromWalletAccount(wallet, account);
+ *   return await getUmbraClient({ signer, network: "mainnet-beta", rpcUrl, rpcSubscriptionsUrl });
+ * }
+ * ```
+ */
+declare function createSignerFromWalletAccount(wallet: Wallet, account: WalletAccount): IUmbraSigner;
+
+/**
+ * RPC-Based Transaction Forwarder Implementations.
+ *
+ * This module provides two factory functions that produce {@link TransactionForwarder}
+ * implementations with different confirmation strategies:
+ *
+ * - **{@link getWebsocketTransactionForwarder}** — Uses
+ *   `sendAndConfirmTransaction` from `@solana/kit`, which subscribes to
+ *   transaction signature notifications via WebSocket for low-latency
+ *   confirmation. Requires access to a WebSocket RPC endpoint.
+ *
+ * - **{@link getPollingTransactionForwarder}** — Sends transactions via
+ *   HTTP and polls `getSignatureStatuses` on a configurable interval to detect
+ *   confirmation. Suitable for environments that block WebSocket connections
+ *   (e.g., certain CI systems, restricted networks). Supports configurable
+ *   timeouts, retry counts, and a per-transaction confirmation callback.
+ *
+ * Both factories implement the {@link TransactionForwarder} interface, exposing
+ * `forwardSequentially` (ordered, one-at-a-time) and `forwardInParallel`
+ * (concurrent submission) methods.
+ *
+ * @remarks
+ * **Choosing a strategy:**
+ * - Use the WebSocket forwarder in browser and server environments where
+ *   WebSocket access is available — it produces lower confirmation latency by
+ *   receiving push notifications instead of polling.
+ * - Use the polling forwarder in environments without WebSocket support or when
+ *   you need fine-grained control over timeout and retry behavior.
+ *
+ * **Error handling:**
+ * - Both forwarders propagate RPC errors as rejections. Callers are responsible
+ *   for wrapping the returned promises in their own retry/error-boundary logic.
+ * - The polling forwarder includes internal send-level retries with exponential
+ *   backoff; the WebSocket forwarder relies on `@solana/kit`'s built-in
+ *   confirmation timeout.
+ * - Confirmation timeout in the polling forwarder throws a plain `Error` with
+ *   a human-readable timeout message.
+ *
+ * **Wire format:**
+ * - Both forwarders serialize transactions using `getBase64EncodedWireTransaction`
+ *   from `@solana/kit` and submit them via `sendTransaction` with
+ *   `encoding: "base64"`.
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module implementation/solana/transaction-forwarder
+ */
+
+/**
+ * Configuration for the websocket-based transaction forwarder.
+ *
+ * @public
+ */
+interface WebsocketBasedTransactionForwarderConfig {
+    /**
+     * The HTTP or HTTPS URL of the Solana JSON-RPC endpoint.
+     *
+     * @remarks
+     * Used for `sendTransaction` calls and the `sendAndConfirmTransaction`
+     * factory. Must be an HTTP/HTTPS URL, not a WebSocket URL.
+     *
+     * @example `"https://api.mainnet-beta.solana.com"`
+     */
+    readonly rpcUrl: string;
+    /**
+     * The WebSocket URL of the Solana RPC subscriptions endpoint.
+     *
+     * @remarks
+     * Used to subscribe to signature notifications for real-time confirmation
+     * detection. Must be a WebSocket URL (`ws://` or `wss://`).
+     *
+     * @example `"wss://api.mainnet-beta.solana.com"`
+     */
+    readonly rpcSubscriptionsUrl: string;
+}
+/**
+ * Optional dependencies for the websocket-based transaction forwarder.
+ *
+ * @remarks
+ * All three dependency slots default to the corresponding `@solana/kit`
+ * implementations. Override any or all of them in tests to avoid real network
+ * I/O.
+ *
+ * @public
+ */
+interface WebsocketBasedTransactionForwarderDeps {
+    /**
+     * Optional custom Solana RPC client factory.
+     *
+     * If not provided, uses the default `createSolanaRpc` from `@solana/kit`.
+     *
+     * @defaultValue `createSolanaRpc` from `@solana/kit`
+     */
+    readonly createRpc?: CreateSolanaRpcFunction;
+    /**
+     * Optional custom Solana RPC subscriptions client factory.
+     *
+     * If not provided, uses the default `createSolanaRpcSubscriptions` from
+     * `@solana/kit`.
+     *
+     * @defaultValue `createSolanaRpcSubscriptions` from `@solana/kit`
+     */
+    readonly createRpcSubscriptions?: CreateSolanaRpcSubscriptionsFunction;
+    /**
+     * Optional custom `sendAndConfirmTransaction` factory.
+     *
+     * If not provided, uses the default `sendAndConfirmTransactionFactory` from
+     * `@solana/kit`.
+     *
+     * @defaultValue `sendAndConfirmTransactionFactory` from `@solana/kit`
+     */
+    readonly sendAndConfirmTransactionFactory?: SendAndConfirmTransactionFactoryFunction;
+}
+/**
+ * Common options shared by both forwarder strategies for a forwarding operation.
+ *
+ * @public
+ */
+interface TransactionForwardOptions {
+    /**
+     * The commitment level to use for transaction confirmation.
+     *
+     * @remarks
+     * - `"processed"` — confirmed by the local RPC node (weakest, fastest)
+     * - `"confirmed"` — confirmed by a supermajority of the cluster (recommended)
+     * - `"finalized"` — confirmed by a full supermajority and rooted (slowest, strongest)
+     *
+     * @defaultValue `"confirmed"`
+     */
+    readonly commitment?: Commitment;
+}
+/**
+ * Configuration for the polling-based transaction forwarder.
+ *
+ * @public
+ */
+interface PollingBasedTransactionForwarderConfig {
+    /**
+     * The HTTP or HTTPS URL of the Solana JSON-RPC endpoint.
+     *
+     * @example `"https://api.mainnet-beta.solana.com"`
+     */
+    readonly rpcUrl: string;
+}
+/**
+ * Optional dependencies for the polling-based transaction forwarder.
+ *
+ * @remarks
+ * Override `createRpc` in tests to inject a mock RPC client with controlled
+ * responses.
+ *
+ * @public
+ */
+interface PollingBasedTransactionForwarderDeps {
+    /**
+     * Optional custom Solana RPC client factory.
+     *
+     * If not provided, uses the default `createSolanaRpc` from `@solana/kit`.
+     *
+     * @defaultValue `createSolanaRpc` from `@solana/kit`
+     */
+    readonly createRpc?: CreateSolanaRpcFunction;
+}
+/**
+ * Options specific to the polling-based transaction forwarder, extending the
+ * base {@link TransactionForwardOptions}.
+ *
+ * @public
+ */
+interface PollingTransactionForwardOptions extends TransactionForwardOptions {
+    /**
+     * Maximum time in milliseconds to wait for a transaction to reach the
+     * desired commitment level before throwing a timeout error.
+     *
+     * @remarks
+     * The polling loop checks elapsed time against this value. If `timeoutMs` is
+     * exceeded, the forwarder throws `Error("Transaction confirmation timed out
+     * after Xms")`. The transaction may still land on-chain after the timeout —
+     * callers should query `getSignatureStatus` if they need to determine the
+     * final outcome.
+     *
+     * @defaultValue `60000` (60 seconds)
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Time in milliseconds between successive `getSignatureStatuses` polling
+     * attempts.
+     *
+     * @remarks
+     * Lower values reduce confirmation latency at the cost of more RPC calls.
+     * On mainnet, slots are ~400ms and blocks ~500ms, so polling more frequently
+     * than every 500ms typically yields no benefit.
+     *
+     * @defaultValue `1000` (1 second)
+     */
+    readonly pollingIntervalMs?: number;
+    /**
+     * Maximum number of `sendTransaction` attempts before giving up.
+     *
+     * @remarks
+     * Each retry is preceded by an exponential backoff delay:
+     * - Attempt 1 → no delay before send
+     * - Retry 1 → 1 second delay
+     * - Retry 2 → 2 seconds delay
+     * - ...
+     *
+     * Only `sendTransaction` failures trigger retries. Confirmation timeouts
+     * are not retried — they throw immediately after `timeoutMs`.
+     *
+     * @defaultValue `3`
+     */
+    readonly maxRetries?: number;
+    /**
+     * Callback invoked after each transaction is confirmed in sequential mode.
+     *
+     * @remarks
+     * Only called by `forwardSequentially` — not by `forwardInParallel`.
+     * Useful for updating progress indicators in a UI while a multi-transaction
+     * sequence is in flight.
+     *
+     * The callback is `await`-ed before the next transaction is submitted, so
+     * async UI updates are safe.
+     */
+    readonly onTransactionConfirmed?: OnTransactionConfirmed;
+}
+/**
+ * Metadata passed to the {@link OnTransactionConfirmed} callback after each
+ * transaction is confirmed in a sequential forwarding sequence.
+ *
+ * @public
+ */
+interface TransactionConfirmedInfo {
+    /**
+     * The base58-encoded signature of the confirmed transaction.
+     */
+    readonly signature: TransactionSignature;
+    /**
+     * The zero-based index of this transaction within the input array.
+     *
+     * @remarks
+     * Use `index + 1` and `totalCount` to display `"Transaction X of Y confirmed"`.
+     */
+    readonly index: number;
+    /**
+     * The total number of transactions being forwarded in this sequence.
+     */
+    readonly totalCount: number;
+}
+/**
+ * Async callback function type invoked after each transaction is confirmed
+ * during sequential forwarding.
+ *
+ * @remarks
+ * The callback is `await`-ed before the next transaction in the sequence is
+ * submitted. This guarantees that UI updates or other async side effects
+ * complete before the next round-trip begins.
+ *
+ * @param info - Metadata about the confirmed transaction.
+ * @returns A `Promise<void>`. The returned promise is awaited before proceeding.
+ *
+ * @example
+ * ```typescript
+ * const onTransactionConfirmed: OnTransactionConfirmed = async ({ signature, index, totalCount }) => {
+ *   setProgress(Math.round(((index + 1) / totalCount) * 100));
+ *   console.log(`[${index + 1}/${totalCount}] confirmed: ${signature}`);
+ * };
+ * ```
+ *
+ * @see {@link PollingTransactionForwardOptions.onTransactionConfirmed}
+ * @public
+ */
+type OnTransactionConfirmed = (info: TransactionConfirmedInfo) => Promise<void>;
+/**
+ * Creates a {@link TransactionForwarder} that uses WebSocket subscriptions for
+ * transaction confirmation.
+ *
+ * The forwarder establishes an RPC client and a subscriptions client from the
+ * provided URLs, then uses `@solana/kit`'s `sendAndConfirmTransactionFactory`
+ * to produce a `sendAndConfirmTransaction` function. This function:
+ *
+ * 1. Serializes the transaction to base64 wire format using
+ *    `getBase64EncodedWireTransaction`.
+ * 2. Submits it via `rpc.sendTransaction` to obtain the signature.
+ * 3. Waits for confirmation by subscribing to the signature via WebSocket
+ *    through `sendAndConfirm`.
+ *
+ * @remarks
+ * **WebSocket requirement** — This forwarder requires a WebSocket-capable RPC
+ * endpoint. If the environment blocks WebSocket connections (e.g., some CI
+ * runners, corporate proxies), use {@link getPollingTransactionForwarder}
+ * instead.
+ *
+ * **Sequential behavior** — `forwardSequentially` submits and confirms
+ * transactions one at a time in order. If any transaction fails, the method
+ * rejects and subsequent transactions are not submitted.
+ *
+ * **Parallel behavior** — `forwardInParallel` maps all transactions through
+ * `sendAndConfirmTransaction` and races them with `Promise.all`. Individual
+ * failures propagate immediately through the `Promise.all` rejection.
+ *
+ * **Commitment** — Defaults to `"confirmed"`. Pass `{ commitment: "finalized" }`
+ * in options for stronger guarantees at the cost of additional latency.
+ *
+ * **Error propagation** — RPC errors and confirmation failures are not caught
+ * internally; they propagate as rejected promises.
+ *
+ * @param config - Configuration containing the HTTP RPC URL and the WebSocket
+ *   subscriptions URL.
+ * @param deps - Optional dependency overrides for testing. All three slots
+ *   default to `@solana/kit` implementations.
+ * @returns A {@link TransactionForwarder} with `forwardSequentially` and
+ *   `forwardInParallel` methods.
+ *
+ * @throws The returned methods may reject if the RPC endpoint is unreachable,
+ *   the WebSocket subscription cannot be established, or the transaction is
+ *   rejected on-chain.
+ *
+ * @example
+ * Basic sequential forwarding:
+ * ```typescript
+ * import { getWebsocketTransactionForwarder } from "./transaction-forwarder";
+ *
+ * const forwarder = getWebsocketTransactionForwarder({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ *   rpcSubscriptionsUrl: "wss://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const [sig1, sig2] = await forwarder.forwardSequentially([initTx, depositTx], {
+ *   commitment: "confirmed",
+ * });
+ * console.log("Init:", sig1);
+ * console.log("Deposit:", sig2);
+ * ```
+ *
+ * @example
+ * Parallel forwarding of independent transactions:
+ * ```typescript
+ * const signatures = await forwarder.forwardInParallel(transferTxs, {
+ *   commitment: "confirmed",
+ * });
+ * ```
+ *
+ * @example
+ * Injecting mock dependencies in tests:
+ * ```typescript
+ * const forwarder = getWebsocketTransactionForwarder(
+ *   { rpcUrl: "http://localhost:8899", rpcSubscriptionsUrl: "ws://localhost:8900" },
+ *   {
+ *     createRpc: mockCreateRpc,
+ *     createRpcSubscriptions: mockCreateRpcSubscriptions,
+ *     sendAndConfirmTransactionFactory: mockSendAndConfirmFactory,
+ *   },
+ * );
+ * ```
+ *
+ * @see {@link getPollingTransactionForwarder} for the polling alternative
+ * @see {@link TransactionForwarder} for the returned interface
+ * @public
+ */
+declare function getWebsocketTransactionForwarder(config: WebsocketBasedTransactionForwarderConfig, deps?: WebsocketBasedTransactionForwarderDeps): TransactionForwarder;
+/**
+ * Creates a {@link TransactionForwarder} that uses periodic polling of
+ * `getSignatureStatuses` for transaction confirmation.
+ *
+ * The polling forwarder works as follows:
+ * 1. Serialize the transaction and submit via `rpc.sendTransaction`.
+ * 2. Begin polling `rpc.getSignatureStatuses` at `pollingIntervalMs` intervals.
+ * 3. Compare `confirmationStatus` against the requested commitment level.
+ * 4. Resolve when the status matches, or throw after `timeoutMs` elapses.
+ *
+ * Send failures are retried up to `maxRetries` times with exponential backoff.
+ *
+ * @remarks
+ * **Environment compatibility** — This forwarder requires only HTTP/HTTPS
+ * access and is suitable for environments that block WebSocket connections.
+ *
+ * **Commitment mapping** — The confirmation check maps `confirmationStatus`
+ * from the RPC response as follows:
+ * - `"processed"` commitment: any non-null `confirmationStatus` satisfies it.
+ * - `"confirmed"` commitment: `confirmationStatus` must be `"confirmed"` or
+ *   `"finalized"`.
+ * - `"finalized"` commitment: `confirmationStatus` must be `"finalized"`.
+ *
+ * **On-chain errors** — If `status.err` is non-null, the forwarder immediately
+ * throws `Error("Transaction failed: <err JSON>")`. This distinguishes an
+ * on-chain execution failure from a network/timeout failure.
+ *
+ * **Sequential callback** — The `onTransactionConfirmed` callback in
+ * {@link PollingTransactionForwardOptions} is invoked (and awaited) after each
+ * transaction in a `forwardSequentially` call. It is NOT invoked during
+ * `forwardInParallel`.
+ *
+ * **Parallel behavior** — `forwardInParallel` first sends all transactions
+ * (with retries), then waits for all confirmations concurrently via
+ * `Promise.all`.
+ *
+ * **Retry backoff** — Send retries use linear backoff: attempt N waits
+ * `N * 1000ms` before retrying (attempt 1: 1s, attempt 2: 2s, etc.).
+ *
+ * @param config - Configuration containing the HTTP RPC endpoint URL.
+ * @param deps - Optional dependency overrides for testing.
+ * @returns A {@link TransactionForwarder} with `forwardSequentially` and
+ *   `forwardInParallel` methods. Both methods accept
+ *   {@link PollingTransactionForwardOptions} for polling-specific settings.
+ *
+ * @throws The returned methods may reject if:
+ *   - The transaction cannot be sent after `maxRetries` attempts.
+ *   - The confirmation timeout (`timeoutMs`) is exceeded.
+ *   - The transaction is rejected on-chain (`status.err !== null`).
+ *
+ * @example
+ * Basic usage with progress callback:
+ * ```typescript
+ * import { getPollingTransactionForwarder } from "./transaction-forwarder";
+ *
+ * const forwarder = getPollingTransactionForwarder({
+ *   rpcUrl: "https://api.mainnet-beta.solana.com",
+ * });
+ *
+ * const signatures = await forwarder.forwardSequentially(transactions, {
+ *   commitment: "confirmed",
+ *   timeoutMs: 30_000,
+ *   pollingIntervalMs: 500,
+ *   maxRetries: 5,
+ *   onTransactionConfirmed: async ({ signature, index, totalCount }) => {
+ *     console.log(`[${index + 1}/${totalCount}] confirmed: ${signature}`);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * Parallel forwarding without a callback:
+ * ```typescript
+ * const signatures = await forwarder.forwardInParallel(transferTxs, {
+ *   commitment: "confirmed",
+ *   timeoutMs: 60_000,
+ * });
+ * ```
+ *
+ * @example
+ * Injecting a mock RPC for tests:
+ * ```typescript
+ * const forwarder = getPollingTransactionForwarder(
+ *   { rpcUrl: "http://localhost:8899" },
+ *   { createRpc: mockCreateRpc },
+ * );
+ * ```
+ *
+ * @see {@link getWebsocketTransactionForwarder} for the WebSocket alternative
+ * @see {@link TransactionForwarder} for the returned interface
+ * @see {@link PollingTransactionForwardOptions} for the full options reference
+ * @public
+ */
+declare function getPollingTransactionForwarder(config: PollingBasedTransactionForwarderConfig, deps?: PollingBasedTransactionForwarderDeps): TransactionForwarder;
+
+export { type OnTransactionConfirmed as O, type PollingBasedTransactionForwarderConfig as P, type RpcBasedAccountInfoProviderConfig as R, type TransactionConfirmedInfo as T, type WebsocketBasedTransactionForwarderConfig as W, type PollingBasedTransactionForwarderDeps as a, type PollingTransactionForwardOptions as b, type RpcBasedBlockhashProviderConfig as c, type RpcBasedBlockhashProviderDeps as d, type RpcBasedEpochInfoProviderConfig as e, type RpcBasedEpochInfoProviderDeps as f, type TransactionForwardOptions as g, type WebsocketBasedTransactionForwarderDeps as h, createInMemorySigner as i, createSignerFromKeyPair as j, createSignerFromPrivateKeyBytes as k, createSignerFromWalletAccount as l, getPollingTransactionForwarder as m, getRpcAccountInfoProvider as n, getRpcBlockhashProvider as o, getRpcEpochInfoProvider as p, getWebsocketTransactionForwarder as q };