@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/common/pda/index.d.cts

@@ -0,0 +1,1250 @@
+import { Address } from '@solana/kit';
+import { R as RcEncryptionNonce } from '../../cryptography-D6tPDh-Y.cjs';
+import { U as U128 } from '../../types-C_V_CaKK.cjs';
+
+/**
+ * User PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for user-related accounts in the Umbra protocol.
+ *
+ * @remarks
+ * Umbra users have two distinct on-chain account types, both stored as
+ * Arcium-encrypted accounts so their contents are opaque to on-chain
+ * observers:
+ *
+ * - **`EncryptedUserAccount`** — stores the user's protocol-level state,
+ *   including their registered X25519 public key and account generation index.
+ *   Created once per user wallet via `RegisterUser`. Referenced by all
+ *   confidential and compliance instructions that need to look up the user's
+ *   encryption key.
+ *
+ * - **`EncryptedTokenAccount`** — stores the user's encrypted SPL token
+ *   balance for a specific mint. Created once per `(user, mint)` pair via
+ *   `InitialiseUserTokenAccount`. Modified by deposit, withdrawal, transfer,
+ *   and claim instructions.
+ *
+ * Both PDAs are keyed under the Umbra program address (not the Arcium program)
+ * because the Umbra program owns and manages these accounts through its
+ * instruction handlers and Arcium callbacks.
+ *
+ * @see {@link findEncryptedUserAccountPda}
+ * @see {@link findEncryptedTokenAccountPda}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/user
+ */
+
+/**
+ * Derives the Program Derived Address for an encrypted user account.
+ * Seeds: [EncryptedUserAccount::SEED, user_pubkey]
+ *
+ * The `EncryptedUserAccount` is the user's top-level protocol identity
+ * within Umbra. It is a singleton per user wallet and stores the user's
+ * registered X25519 public key and account generation index.
+ *
+ * @param userPubkey - The user's wallet public key (Solana Ed25519 address).
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findEncryptedUserAccountPda } from "@umbra-privacy/sdk";
+ *
+ * const userAccountPda = await findEncryptedUserAccountPda(
+ *   userWalletAddress,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findEncryptedTokenAccountPda} for per-mint encrypted balance accounts
+ *
+ * @public
+ */
+declare function findEncryptedUserAccountPda(userPubkey: Address, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an encrypted token account.
+ * Seeds: [EncryptedTokenAccount::SEED, user_pubkey, mint_pubkey]
+ *
+ * The `EncryptedTokenAccount` holds the user's encrypted SPL token
+ * balance for a specific mint. A separate account exists for each
+ * `(user, mint)` pair.
+ *
+ * @param userPubkey - The user's wallet public key (Solana Ed25519 address).
+ * @param mintPubkey - The SPL token mint address.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findEncryptedTokenAccountPda } from "@umbra-privacy/sdk";
+ *
+ * const tokenAccountPda = await findEncryptedTokenAccountPda(
+ *   userWalletAddress,
+ *   usdcMint,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findEncryptedUserAccountPda} for the top-level user identity account
+ * @see {@link findTokenPoolPda} for the per-mint pool configuration that governs this account's features
+ *
+ * @public
+ */
+declare function findEncryptedTokenAccountPda(userPubkey: Address, mintPubkey: Address, umbraProgram: Address): Promise<Address>;
+
+/**
+ * Arcium PDA (Program Derived Address) Generator Utilities
+ *
+ * This module provides functions for deriving Arcium protocol account addresses.
+ * These PDAs are used to locate various Arcium accounts on-chain, including
+ * MXE accounts, computation accounts, and cluster accounts.
+ *
+ * @see {@link findArciumMxePda}
+ * @see {@link findArciumMempoolPda}
+ * @see {@link findArciumExecutingPoolPda}
+ * @see {@link findArciumComputationPda}
+ * @see {@link findArciumCompDefPda}
+ * @see {@link findArciumClusterPda}
+ * @see {@link findArciumInfrastructurePdas}
+ * @see {@link computeCompDefOffset}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/arcium
+ */
+
+/**
+ * Computes the computation definition offset from an Arcium instruction name.
+ *
+ * The comp-def offset uniquely identifies which comp-def account corresponds
+ * to a given Umbra instruction. It is derived deterministically by taking the
+ * SHA-256 hash of the instruction name and interpreting the first four bytes
+ * as a little-endian u32.
+ *
+ * @param instructionName - The Arcium instruction name in snake_case format
+ *   (e.g. `"register_user"`, `"deposit_into_existing_mxe_v3"`).
+ * @returns The computation definition offset as an unsigned 32-bit integer.
+ *
+ * @example
+ * ```typescript
+ * import { computeCompDefOffset } from "@umbra-privacy/sdk";
+ *
+ * const offset = computeCompDefOffset("register_user");
+ *
+ * const compDefPda = await findArciumCompDefPda(
+ *   networkConfig.programId,
+ *   networkConfig.arciumProgramAddress,
+ *   offset,
+ * );
+ * ```
+ *
+ * @see {@link findArciumCompDefPda} for deriving the full comp-def PDA
+ * @see {@link findArciumInfrastructurePdas} for deriving all Arcium accounts at once
+ *
+ * @public
+ */
+declare function computeCompDefOffset(instructionName: string): number;
+/**
+ * Derives the Program Derived Address for the Arcium MXE registration account.
+ * Seeds: [ARCIUM_MXE_ACCOUNT_SEED, umbra_program_pubkey] (against Arcium program)
+ *
+ * The MXE account is the Arcium protocol's main registration account for a
+ * guest program (Umbra). Required as a read-only account on every
+ * Arcium-integrated instruction.
+ *
+ * @param umbraProgram - The Umbra program address.
+ * @param arciumProgram - The Arcium program address.
+ * @returns A Promise resolving to the derived MXE account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumMxePda } from "@umbra-privacy/sdk";
+ *
+ * const mxeAccount = await findArciumMxePda(
+ *   networkConfig.programId,
+ *   networkConfig.arciumProgramAddress,
+ * );
+ * ```
+ *
+ * @see {@link findArciumInfrastructurePdas} for deriving all Arcium accounts at once
+ *
+ * @public
+ */
+declare function findArciumMxePda(umbraProgram: Address, arciumProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an Arcium cluster mempool account.
+ * Seeds: [ARCIUM_MEMPOOL_SEED, cluster_offset_u32_le] (against Arcium program)
+ *
+ * The mempool account is a queue that holds pending computation requests
+ * waiting to be picked up by cluster nodes.
+ *
+ * @param arciumProgram - The Arcium program address.
+ * @param clusterOffset - The cluster offset (u32).
+ * @returns A Promise resolving to the derived mempool account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumMempoolPda } from "@umbra-privacy/sdk";
+ *
+ * const mempoolAccount = await findArciumMempoolPda(
+ *   networkConfig.arciumProgramAddress,
+ *   networkConfig.clusterOffset,
+ * );
+ * ```
+ *
+ * @see {@link findArciumClusterPda} for the parent cluster account
+ *
+ * @public
+ */
+declare function findArciumMempoolPda(arciumProgram: Address, clusterOffset: number): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an Arcium cluster executing pool account.
+ * Seeds: [ARCIUM_EXEC_POOL_SEED, cluster_offset_u32_le] (against Arcium program)
+ *
+ * The executing pool account tracks computations currently being processed
+ * by cluster nodes.
+ *
+ * @param arciumProgram - The Arcium program address.
+ * @param clusterOffset - The cluster offset (u32).
+ * @returns A Promise resolving to the derived executing pool account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumExecutingPoolPda } from "@umbra-privacy/sdk";
+ *
+ * const execPoolAccount = await findArciumExecutingPoolPda(
+ *   networkConfig.arciumProgramAddress,
+ *   networkConfig.clusterOffset,
+ * );
+ * ```
+ *
+ * @see {@link findArciumMempoolPda} for the pending computation queue
+ * @see {@link findArciumClusterPda} for the parent cluster account
+ *
+ * @public
+ */
+declare function findArciumExecutingPoolPda(arciumProgram: Address, clusterOffset: number): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an individual Arcium computation account.
+ * Seeds: [ARCIUM_COMPUTATION_SEED, cluster_offset_u32_le, computation_offset_u64_le] (against Arcium program)
+ *
+ * Each computation request gets its own account that stores the computation's
+ * state. Created by `queue_computation` and closed when the callback executes.
+ *
+ * @param arciumProgram - The Arcium program address.
+ * @param clusterOffset - The cluster offset (u32).
+ * @param computationOffset - The computation offset (u64).
+ * @returns A Promise resolving to the derived computation account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumComputationPda } from "@umbra-privacy/sdk";
+ *
+ * const computationAccount = await findArciumComputationPda(
+ *   networkConfig.arciumProgramAddress,
+ *   networkConfig.clusterOffset,
+ *   computationOffset,
+ * );
+ * ```
+ *
+ * @see {@link findArciumInfrastructurePdas} for deriving all required accounts at once
+ * @see {@link findArciumCompDefPda} for the computation definition account
+ *
+ * @public
+ */
+declare function findArciumComputationPda(arciumProgram: Address, clusterOffset: number, computationOffset: bigint): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an Arcium computation definition account.
+ * Seeds: [ARCIUM_COMP_DEF_SEED, umbra_program_pubkey, comp_def_offset_u32_le] (against Arcium program)
+ *
+ * A computation definition account stores the encrypted circuit program that
+ * cluster nodes execute for a specific Arcium instruction. One comp-def
+ * account exists per Umbra instruction that uses Arcium MPC.
+ *
+ * @param umbraProgram - The Umbra program address.
+ * @param arciumProgram - The Arcium program address.
+ * @param compDefOffset - The computation definition offset, derived via
+ *   `computeCompDefOffset(instructionName)`.
+ * @returns A Promise resolving to the derived comp-def account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { computeCompDefOffset, findArciumCompDefPda } from "@umbra-privacy/sdk";
+ *
+ * const offset = computeCompDefOffset("deposit_into_existing_mxe_v3");
+ * const compDefAccount = await findArciumCompDefPda(
+ *   networkConfig.programId,
+ *   networkConfig.arciumProgramAddress,
+ *   offset,
+ * );
+ * ```
+ *
+ * @see {@link computeCompDefOffset} for computing the offset from an instruction name
+ * @see {@link findArciumInfrastructurePdas} for deriving all required accounts at once
+ *
+ * @public
+ */
+declare function findArciumCompDefPda(umbraProgram: Address, arciumProgram: Address, compDefOffset: number): Promise<Address>;
+/**
+ * Derives the Program Derived Address for an Arcium cluster account.
+ * Seeds: [ARCIUM_CLUSTER_SEED, cluster_offset_u32_le] (against Arcium program)
+ *
+ * A cluster account represents a group of Arcium MXE nodes that jointly
+ * process computations using multi-party computation (MPC).
+ *
+ * @param arciumProgram - The Arcium program address.
+ * @param clusterOffset - The cluster offset (u32).
+ * @returns A Promise resolving to the derived cluster account `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumClusterPda } from "@umbra-privacy/sdk";
+ *
+ * const clusterAccount = await findArciumClusterPda(
+ *   networkConfig.arciumProgramAddress,
+ *   networkConfig.clusterOffset,
+ * );
+ * ```
+ *
+ * @see {@link findArciumMempoolPda} for the cluster's pending computation queue
+ * @see {@link findArciumExecutingPoolPda} for the cluster's active computation pool
+ *
+ * @public
+ */
+declare function findArciumClusterPda(arciumProgram: Address, clusterOffset: number): Promise<Address>;
+/**
+ * Collection of all Arcium infrastructure account addresses needed to submit
+ * a computation to the Arcium MPC network.
+ *
+ * @see {@link findArciumInfrastructurePdas} for the function that produces this object
+ *
+ * @public
+ */
+interface ArciumInfrastructurePdas {
+    /** The MXE protocol account address for the Umbra program. @readonly */
+    readonly mxeAccount: Address;
+    /** The mempool account address for the cluster. @readonly */
+    readonly mempoolAccount: Address;
+    /** The executing pool account address for the cluster. @readonly */
+    readonly executingPoolAccount: Address;
+    /** The computation account address for this specific computation request. @readonly */
+    readonly computationAccount: Address;
+    /** The computation definition account address for the target instruction. @readonly */
+    readonly compDefAccount: Address;
+    /** The cluster account address. @readonly */
+    readonly clusterAccount: Address;
+}
+/**
+ * Derives all Arcium infrastructure account addresses required for a single
+ * computation request.
+ *
+ * This is a convenience function that computes all six required Arcium PDAs in
+ * parallel and returns them as an {@link ArciumInfrastructurePdas} object.
+ *
+ * @param umbraProgram - The Umbra program address.
+ * @param arciumProgram - The Arcium program address.
+ * @param clusterOffset - The cluster offset identifying which Arcium cluster to use.
+ * @param computationOffset - The unique u64 offset for this specific computation.
+ * @param instructionName - The snake_case Arcium instruction name used to derive
+ *   the comp-def offset.
+ * @returns A Promise resolving to an {@link ArciumInfrastructurePdas} object.
+ *
+ * @example
+ * ```typescript
+ * import { findArciumInfrastructurePdas } from "@umbra-privacy/sdk";
+ *
+ * const arciumAccounts = await findArciumInfrastructurePdas(
+ *   networkConfig.programId,
+ *   networkConfig.arciumProgramAddress,
+ *   networkConfig.clusterOffset,
+ *   computationOffset,
+ *   "deposit_into_existing_mxe_v3",
+ * );
+ * ```
+ *
+ * @see {@link computeCompDefOffset} for the comp-def offset derivation
+ * @see {@link ArciumInfrastructurePdas} for the return type shape
+ *
+ * @public
+ */
+declare function findArciumInfrastructurePdas(umbraProgram: Address, arciumProgram: Address, clusterOffset: number, computationOffset: bigint, instructionName: string): Promise<ArciumInfrastructurePdas>;
+
+/**
+ * Compliance Grant PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for compliance grant accounts in the Umbra protocol.
+ *
+ * @remarks
+ * Umbra implements a master viewing key system that allows authorised parties
+ * to decrypt encrypted user data without gaining control over funds. Three
+ * grant variants exist, each modelling a different trust relationship:
+ *
+ * - **Network grant** — the Arcium MXE network itself can decrypt the
+ *   user's data; the granter is implicitly the network. Used for regulatory
+ *   or protocol-level compliance.
+ * - **Shared grant** — the user explicitly shares a re-encrypted view
+ *   key with the network for a specific receiver, scoped to a nonce to
+ *   prevent replay.
+ * - **User grant** — the user directly grants a named receiver (e.g. an
+ *   auditor) the ability to read their encrypted data by re-encrypting the
+ *   view key under the receiver's X25519 public key.
+ *
+ * All three grant PDAs share a common prefix (`VIEWING_GRANT_SEED`)
+ * and are disambiguated by a variant seed (`USER_GRANT_VARIANT_SEED`, etc.).
+ * The nonce component prevents one grant from accidentally overwriting another.
+ *
+ * @see {@link findUserComplianceGrantPda}
+ * @see {@link findNetworkComplianceGrantPda}
+ * @see {@link findSharedComplianceGrantPda}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/compliance
+ */
+
+/**
+ * Derives the Program Derived Address for a user-granted compliance grant.
+ * Seeds: [ViewingGrant::SEED, UserGrant::VARIANT, granter_x25519, nonce, receiver_x25519]
+ *
+ * A user-granted compliance grant stores a re-encrypted view of the granter's
+ * private data under the receiver's X25519 public key, enabling a specific
+ * party (e.g. an auditor) to decrypt the granter's encrypted balances.
+ *
+ * @param granterX25519 - The 32-byte X25519 public key of the granter.
+ * @param nonce - A `RcEncryptionNonce` (u128) uniquely identifying this grant issuance.
+ * @param receiverX25519 - The 32-byte X25519 public key of the receiver.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findUserComplianceGrantPda } from "@umbra-privacy/sdk";
+ *
+ * const grantPda = await findUserComplianceGrantPda(
+ *   granterX25519PublicKey,
+ *   nonce,
+ *   auditorX25519PublicKey,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findNetworkComplianceGrantPda} for network-level MXE grants
+ * @see {@link findSharedComplianceGrantPda} for network shared grants
+ *
+ * @public
+ */
+declare function findUserComplianceGrantPda(granterX25519: Uint8Array, nonce: RcEncryptionNonce, receiverX25519: Uint8Array, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a network (MXE) compliance grant.
+ * Seeds: [ViewingGrant::SEED, NetworkMxeGrant::VARIANT, nonce, receiver_x25519]
+ *
+ * A network compliance grant allows the Arcium MXE network itself to
+ * decrypt a user's encrypted data. There is no explicit granter key in the
+ * seeds -- the granter is implicitly the network.
+ *
+ * @param nonce - A `RcEncryptionNonce` (u128) uniquely identifying this grant issuance.
+ * @param receiverX25519 - The 32-byte X25519 public key of the receiver.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findNetworkComplianceGrantPda } from "@umbra-privacy/sdk";
+ *
+ * const grantPda = await findNetworkComplianceGrantPda(
+ *   nonce,
+ *   networkX25519PublicKey,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findUserComplianceGrantPda} for user-to-auditor grants
+ * @see {@link findSharedComplianceGrantPda} for network shared grants
+ *
+ * @public
+ */
+declare function findNetworkComplianceGrantPda(nonce: RcEncryptionNonce, receiverX25519: Uint8Array, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a shared (network-shared) compliance grant.
+ * Seeds: [ViewingGrant::SEED, NetworkSharedGrant::VARIANT, granter_x25519, nonce, receiver_x25519]
+ *
+ * A shared compliance grant is issued by a specific user to share a
+ * re-encrypted view key with a named receiver via the Arcium network.
+ * Unlike the network compliance grant, this variant includes the granter's
+ * key so multiple users can each issue independent shared grants.
+ *
+ * @param granterX25519 - The 32-byte X25519 public key of the granter.
+ * @param nonce - A `RcEncryptionNonce` (u128) uniquely identifying this grant issuance.
+ * @param receiverX25519 - The 32-byte X25519 public key of the receiver.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findSharedComplianceGrantPda } from "@umbra-privacy/sdk";
+ *
+ * const grantPda = await findSharedComplianceGrantPda(
+ *   granterX25519PublicKey,
+ *   nonce,
+ *   receiverX25519PublicKey,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findUserComplianceGrantPda} for direct user-to-auditor grants
+ * @see {@link findNetworkComplianceGrantPda} for implicit network-level grants
+ *
+ * @public
+ */
+declare function findSharedComplianceGrantPda(granterX25519: Uint8Array, nonce: RcEncryptionNonce, receiverX25519: Uint8Array, umbraProgram: Address): Promise<Address>;
+
+/**
+ * Umbra PDA (Program Derived Address) Generator Utilities
+ *
+ * This module provides functions for deriving Umbra protocol account addresses,
+ * specifically for mixer tree accounts used in the privacy-preserving UTXO system.
+ *
+ * @remarks
+ * ## Mixer Tree Overview
+ *
+ * The mixer tree is an Indexed Merkle Tree (IMT) that stores Poseidon H2 hash
+ * commitments to UTXOs. Multiple mixer trees can exist, with each tree indexed
+ * sequentially (0, 1, 2, ...). When a tree reaches capacity, a new tree is
+ * created and becomes the active tree. Old trees remain readable for proof
+ * generation and claiming.
+ *
+ * ## Nullifier Set Overview
+ *
+ * Each mixer tree has five associated nullifier set accounts (variants 0-4). These
+ * accounts form an Indexed Merkle Tree of nullifiers and serve as the primary
+ * double-spend prevention mechanism: before a UTXO can be claimed its
+ * nullifier is checked against -- and then inserted into -- the nullifier set.
+ *
+ * ## UTXO Burner Accounts
+ *
+ * Confidential and public UTXO burner accounts act as temporary storage for
+ * nullifiers during relayer-submitted claim transactions. They are scoped to
+ * a `(relayer, receiver_address, offset)` triple and are created and closed
+ * within the same transaction.
+ *
+ * ## Utility Functions
+ *
+ * `computeStructSeed` is re-exported from this module because every other PDA module
+ * depends on it to compute seed constants.
+ *
+ * @see {@link findStealthPoolPda}
+ * @see {@link findActiveStealthPoolPda}
+ * @see {@link findNullifierSetPdas}
+ * @see {@link findConfidentialNullifierBufferPda}
+ * @see {@link findPublicNullifierBufferPda}
+ * @see {@link computeStructSeed}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/umbra
+ */
+
+/**
+ * Computes the SHA-256 hash of a struct/seed name string and returns the
+ * result as a 32-byte `Uint8Array`.
+ *
+ * This mirrors the `sha256_seed!` macro and the `#[umbra_account]` macro used
+ * in the Rust smart contract. Every PDA seed constant in the Umbra program is
+ * derived as `SHA-256(struct_name_utf8)`.
+ *
+ * This function is also exported from the barrel (`index.ts`) for callers that
+ * need to compute arbitrary struct seeds outside the SDK, for example when
+ * verifying a PDA derivation manually or in tests.
+ *
+ * @param name - The struct or domain name to hash (UTF-8 string, e.g. `"TokenPool"`).
+ * @returns A 32-byte `Uint8Array` containing the SHA-256 digest.
+ *
+ * @example
+ * ```typescript
+ * import { computeStructSeed } from "@umbra-privacy/sdk";
+ *
+ * const poolSeed = computeStructSeed("TokenPool");
+ * // poolSeed is SHA-256("TokenPool") as a 32-byte Uint8Array
+ * ```
+ *
+ * @public
+ */
+declare function computeStructSeed(name: string): Uint8Array;
+/**
+ * Derives the Program Derived Address for a stealth pool (mixer tree) at the given index.
+ * Seeds: [StealthPool::SEED, index_u128_le]
+ *
+ * The mixer tree is an Indexed Merkle Tree (IMT) that stores Poseidon H2 hash
+ * commitments for UTXOs. Multiple trees can exist simultaneously, each
+ * identified by a sequential integer index.
+ *
+ * @param index - The mixer tree index, starting from `0n`.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findStealthPoolPda } from "@umbra-privacy/sdk";
+ *
+ * const mixerTree0 = await findStealthPoolPda(0n as U128, networkConfig.programId);
+ * ```
+ *
+ * @see {@link findActiveStealthPoolPda} for the convenience wrapper that always returns tree index 0
+ * @see {@link findNullifierSetPdas} for the nullifier storage accounts associated with each tree
+ * @see {@link findProtocolConfigPda} for the global account that stores the active tree index
+ *
+ * @public
+ */
+declare function findStealthPoolPda(index: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for the currently active stealth pool (tree index 0).
+ * Seeds: [StealthPool::SEED, 0_u128_le]
+ *
+ * This is a convenience wrapper around `findStealthPoolPda(0n)` for the
+ * common case where a caller needs the genesis tree address.
+ *
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the PDA `Address` of tree index 0.
+ *
+ * @example
+ * ```typescript
+ * import { findActiveStealthPoolPda } from "@umbra-privacy/sdk";
+ *
+ * const activeMixer = await findActiveStealthPoolPda(networkConfig.programId);
+ * ```
+ *
+ * @see {@link findStealthPoolPda} for arbitrary tree index derivation
+ * @see {@link findProtocolConfigPda} for the account that tracks the true active index
+ *
+ * @public
+ */
+declare function findActiveStealthPoolPda(umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a confidential nullifier buffer account.
+ * Seeds: [ConfidentialNullifierLinkerBuffer::SEED, relayer_pubkey, receiver_address, offset_u128_le]
+ *
+ * Confidential nullifier buffer accounts are temporary storage PDAs that hold
+ * the nullifier set for a batch of confidential UTXOs being claimed in a
+ * single relayer-submitted transaction.
+ *
+ * @param relayerAddress - The relayer's public key.
+ * @param receiverAddress - The receiver's public key (claim destination address).
+ * @param burnerAccountOffset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findConfidentialNullifierBufferPda } from "@umbra-privacy/sdk";
+ *
+ * const burnerPda = await findConfidentialNullifierBufferPda(
+ *   relayerAddress,
+ *   receiverAddress,
+ *   0n as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findPublicNullifierBufferPda} for the public-balance variant
+ * @see {@link findNullifierSetPdas} for the nullifier storage accounts the burner writes into
+ *
+ * @public
+ */
+declare function findConfidentialNullifierBufferPda(relayerAddress: Address, receiverAddress: Address, burnerAccountOffset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a public nullifier buffer account.
+ * Seeds: [PublicNullifierLinkerBuffer::SEED, relayer_pubkey, receiver_address, offset_u128_le]
+ *
+ * Public nullifier buffer accounts serve the same purpose as confidential
+ * nullifier buffer accounts but for claims that deposit into a public ATA
+ * rather than an encrypted balance.
+ *
+ * @param relayerAddress - The relayer's public key.
+ * @param receiverAddress - The receiver's public key (claim destination address).
+ * @param burnerAccountOffset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findPublicNullifierBufferPda } from "@umbra-privacy/sdk";
+ *
+ * const burnerPda = await findPublicNullifierBufferPda(
+ *   relayerAddress,
+ *   receiverAddress,
+ *   0n as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findConfidentialNullifierBufferPda} for the confidential-balance variant
+ * @see {@link findNullifierSetPdas} for the nullifier storage accounts the burner writes into
+ *
+ * @public
+ */
+declare function findPublicNullifierBufferPda(relayerAddress: Address, receiverAddress: Address, burnerAccountOffset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Return type for `findNullifierSetPdas` containing all five nullifier set
+ * account addresses for a given mixer tree index.
+ *
+ * @remarks
+ * Each mixer tree has exactly five associated nullifier set accounts (variants 0-4).
+ * Together they form the Indexed Merkle Tree of nullifiers that prevents
+ * double-spending. All five accounts must be passed to claim instructions
+ * so the program can update the correct nullifier set node.
+ *
+ * @see {@link findNullifierSetPdas}
+ *
+ * @public
+ */
+interface NullifierSetPdas {
+    /** Nullifier set account variant 0 (first segment of the nullifier IMT). @readonly */
+    readonly treap0: Address;
+    /** Nullifier set account variant 1 (second segment of the nullifier IMT). @readonly */
+    readonly treap1: Address;
+    /** Nullifier set account variant 2 (third segment of the nullifier IMT). @readonly */
+    readonly treap2: Address;
+    /** Nullifier set account variant 3 (fourth segment of the nullifier IMT). @readonly */
+    readonly treap3: Address;
+    /** Nullifier set account variant 4 (fifth segment of the nullifier IMT). @readonly */
+    readonly treap4: Address;
+}
+/**
+ * Derives all five nullifier set PDAs for a given mixer tree index.
+ * Seeds (per variant): [Treap::SEED, stealth_pool_index_u128_le, variant_byte]
+ *
+ * Nullifier set accounts implement the Indexed Merkle Tree (IMT) of nullifiers
+ * used to prevent double-spending of UTXOs. There are exactly five accounts
+ * per mixer tree, addressed by variant byte 0-4.
+ *
+ * @param stealthPoolIndex - The mixer tree index whose nullifier set PDAs to derive.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to a {@link NullifierSetPdas} object containing all
+ *   five nullifier set account addresses (`treap0` through `treap4`).
+ *
+ * @example
+ * ```typescript
+ * import { findNullifierSetPdas } from "@umbra-privacy/sdk";
+ *
+ * const nullifierSetPdas = await findNullifierSetPdas(0n as U128, networkConfig.programId);
+ * console.log(nullifierSetPdas.treap0, nullifierSetPdas.treap1, nullifierSetPdas.treap2);
+ * ```
+ *
+ * @see {@link findStealthPoolPda} for the Merkle commitment tree PDAs
+ * @see {@link NullifierSetPdas} for the return type shape
+ *
+ * @public
+ */
+declare function findNullifierSetPdas(stealthPoolIndex: U128, umbraProgram: Address): Promise<NullifierSetPdas>;
+
+/**
+ * Global PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for singleton program-level accounts in the Umbra protocol.
+ *
+ * Mirrors the smart contract's `state/global/` module, which holds
+ * `ProtocolConfig` — a singleton account storing protocol-wide state.
+ *
+ * @remarks
+ * There is exactly one `ProtocolConfig` account per Umbra program
+ * deployment. It acts as the canonical source of truth for cross-instruction
+ * protocol state: the index of the currently active mixer tree, global
+ * feature activation flags, and the program upgrade authority. Most
+ * instructions pass it as a read-only account for validation.
+ *
+ * @see {@link findProtocolConfigPda} for the derivation function
+ * @see {@link findTokenPoolPda} for per-mint pool configuration
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/global
+ */
+
+/**
+ * Derives the Program Derived Address for the singleton protocol configuration account.
+ * Seeds: [ProtocolConfig::SEED]
+ *
+ * The `ProtocolConfig` account stores global configuration state including
+ * the active mixer tree index, feature flags, and the upgrade authority.
+ *
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findProtocolConfigPda } from "@umbra-privacy/sdk";
+ *
+ * const protocolConfig = await findProtocolConfigPda(networkConfig.programId);
+ * ```
+ *
+ * @see {@link findTokenPoolPda} for per-mint pool configuration
+ * @see {@link findStealthPoolPda} for per-index mixer tree accounts
+ *
+ * @public
+ */
+declare function findProtocolConfigPda(umbraProgram: Address): Promise<Address>;
+
+/**
+ * Pool PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for pool-related accounts in the Umbra protocol.
+ *
+ * Mirrors the smart contract's `state/pool/` module, which holds the `Pool`
+ * account — a per-mint configuration account that enables confidentiality and
+ * mixer features for a specific SPL token.
+ *
+ * @remarks
+ * The `Pool` account is a singleton per SPL token mint. It is created by the
+ * protocol administrator and acts as the root configuration object for all
+ * privacy operations involving that mint. Instructions that add or remove
+ * privacy features (confidentiality, mixer) modify this account.
+ *
+ * @see {@link findTokenPoolPda} for the derivation function
+ * @see {@link findProtocolConfigPda} for the global singleton that tracks active tree index
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/pool
+ */
+
+/**
+ * SHA-256 of the string `"TokenPool"`, stored as a 32-byte `Uint8Array`.
+ *
+ * Matches `Pool::SEED` as generated by the `#[umbra_account]` macro
+ * in `state/pool/pool.rs`. Used as the first seed when deriving Pool PDAs.
+ *
+ * Also re-exported from the barrel (`index.ts`) as `TOKEN_POOL_SEED` for callers
+ * that need the raw bytes — for example, to verify a PDA server-side without
+ * calling `findTokenPoolPda`.
+ *
+ * @internal
+ */
+declare const TOKEN_POOL_SEED: Uint8Array<ArrayBufferLike>;
+/**
+ * Derives the Program Derived Address for a token pool configuration account.
+ * Seeds: [TokenPool::SEED, mint_pubkey]
+ *
+ * The `Pool` account is a per-mint singleton that stores whether
+ * confidentiality and mixer features are activated for a specific SPL token.
+ *
+ * @param mintAddress - The SPL token mint address for this pool.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findTokenPoolPda } from "@umbra-privacy/sdk";
+ *
+ * const pool = await findTokenPoolPda(mintAddress, networkConfig.programId);
+ * ```
+ *
+ * @see {@link TOKEN_POOL_SEED} for the raw seed bytes
+ * @see {@link findProtocolConfigPda} for the global singleton account
+ *
+ * @public
+ */
+declare function findTokenPoolPda(mintAddress: Address, umbraProgram: Address): Promise<Address>;
+
+/**
+ * Relayer PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for relayer-related accounts in the Umbra protocol.
+ *
+ * Mirrors the smart contract's `state/relayer/` module, which holds:
+ * - `Relayer` — a per-relayer, per-mint account that stores the
+ *   relayer's registration state and fee configuration references.
+ *
+ * @remarks
+ * Relayers are permissioned transaction forwarders in the Umbra privacy
+ * protocol. They submit user-generated proofs and encrypted payloads
+ * on-chain, collecting a commission fee for the service. Each relayer must
+ * register a `Relayer` for every SPL token mint they wish to support.
+ *
+ * The `Relayer` PDA is scoped to a `(relayer, mint)` pair so that a
+ * single relayer wallet can independently manage fee configurations for
+ * multiple mints without conflicting accounts.
+ *
+ * @see {@link findRelayerPda} for the derivation function
+ * @see {@link findRelayerFeeVaultPda} for the associated fee pool derivation
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/relayer
+ */
+
+/**
+ * Derives the Program Derived Address for a relayer registration account.
+ * Seeds: [Relayer::SEED, relayer_pubkey, mint_pubkey]
+ *
+ * The `Relayer` stores a relayer's registration data and fee
+ * configuration for a specific SPL token mint. A unique account exists per
+ * `(relayer, mint)` pair.
+ *
+ * @param relayerAddress - The relayer's wallet public key.
+ * @param mintAddress - The SPL token mint address that this relayer supports.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findRelayerPda } from "@umbra-privacy/sdk";
+ *
+ * const relayerAccount = await findRelayerPda(
+ *   relayerPublicKey,
+ *   mintAddress,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findRelayerFeeVaultPda} for the associated unified fee pool
+ * @see {@link findFeeSchedulePda} for the fee rate configuration account
+ *
+ * @public
+ */
+declare function findRelayerPda(relayerAddress: Address, mintAddress: Address, umbraProgram: Address): Promise<Address>;
+
+/**
+ * Fees PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for protocol and relayer fee accounts in the Umbra protocol.
+ *
+ * Mirrors the smart contract's `state/fees/` module, which holds:
+ * - `FeeVault` — a single account storing both protocol and relayer fees,
+ *   partitioned by a domain seed into two variants:
+ *   - Protocol-only pools (deposits, withdrawals, public UTXO creation)
+ *   - Relayer pools (transfers, confidential/public claims)
+ * - `FeeSchedule` — admin-managed fee rate config per mint
+ *
+ * @remarks
+ * Umbra separates fee collection from fee disbursement by accumulating fees in
+ * dedicated PDA accounts (`FeeVault`) that can be swept by the protocol
+ * treasury or relayer at any time. The fee amount charged per instruction is
+ * governed by the `FeeSchedule` account for that instruction + mint
+ * pair.
+ *
+ * Both `FeeVault` variants and `FeeSchedule` include an
+ * `offset` seed, following the canonical seed pattern:
+ *
+ * `SEED -> domain_seed (for fees pool) -> instructionSeed -> entity_key -> mint -> offset`
+ *
+ * The `offset` allows the protocol to create multiple fee pool or config
+ * accounts for the same instruction + mint combination if needed in future.
+ * Currently `offset` is always `0n` for `FeeSchedule` and an
+ * instruction-specific constant for `FeeVault`.
+ *
+ * @see {@link findProtocolFeeVaultPda}
+ * @see {@link findRelayerFeeVaultPda}
+ * @see {@link findFeeSchedulePda}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/fees
+ */
+
+/**
+ * Derives the Program Derived Address for a protocol-only fee vault account.
+ * Seeds: [FeeVault::SEED, ProtocolFees::DOMAIN, instruction_seed, mint_pubkey, offset]
+ *
+ * Protocol-only fee pools accumulate the protocol's share of fees for
+ * instructions that have no relayer commission component (deposits,
+ * withdrawals, and public UTXO creation).
+ *
+ * @param instructionSeed - The instruction-specific U128 seed constant.
+ * @param mintAddress - The SPL token mint address for this pool.
+ * @param offset - The account offset discriminator (U128).
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the `[pda, bump]` tuple.
+ *
+ * @example
+ * ```typescript
+ * import { findProtocolFeeVaultPda } from "@umbra-privacy/sdk";
+ *
+ * const [feesPoolPda] = await findProtocolFeeVaultPda(
+ *   instructionSeed as U128,
+ *   mintAddress,
+ *   PROTOCOL_FEES_POOL_OFFSET as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findRelayerFeeVaultPda} for the relayer commission pool variant
+ * @see {@link findFeeSchedulePda} for the fee rate configuration account
+ *
+ * @public
+ */
+declare function findProtocolFeeVaultPda(instructionSeed: U128, mintAddress: Address, offset: U128, umbraProgram: Address): Promise<readonly [Address, number]>;
+/**
+ * Derives the Program Derived Address for a relayer fee vault account.
+ * Seeds: [FeeVault::SEED, ProtocolRelayerFees::DOMAIN, instruction_seed, relayer_pubkey, mint_pubkey, offset]
+ *
+ * Relayer fee pools accumulate both the protocol's share and the relayer's
+ * commission for instructions that involve a relayer (claims and transfers).
+ *
+ * @param instructionSeed - The instruction-specific U128 seed constant.
+ * @param relayerAddress - The relayer's wallet public key.
+ * @param mintAddress - The SPL token mint address for this pool.
+ * @param offset - The account offset discriminator (U128).
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the `[pda, bump]` tuple.
+ *
+ * @example
+ * ```typescript
+ * import { findRelayerFeeVaultPda } from "@umbra-privacy/sdk";
+ *
+ * const [unifiedFeesPoolPda] = await findRelayerFeeVaultPda(
+ *   instructionSeed as U128,
+ *   relayerPublicKey,
+ *   mintAddress,
+ *   PROTOCOL_FEES_POOL_OFFSET as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findProtocolFeeVaultPda} for the protocol-only pool variant
+ * @see {@link findRelayerPda} for the relayer registration account
+ *
+ * @public
+ */
+declare function findRelayerFeeVaultPda(instructionSeed: U128, relayerAddress: Address, mintAddress: Address, offset: U128, umbraProgram: Address): Promise<readonly [Address, number]>;
+/**
+ * Derives the Program Derived Address for a protocol fee schedule account.
+ * Seeds: [FeeSchedule::SEED, instruction_seed, mint_pubkey, offset]
+ *
+ * The `FeeSchedule` account defines the fee rates for a specific instruction
+ * variant and SPL token mint. Consulted during instruction validation to
+ * calculate how much the user must pay.
+ *
+ * @param instructionSeed - The instruction-specific U128 seed constant.
+ * @param mintAddress - The SPL token mint address for this fee configuration.
+ * @param offset - The account offset discriminator (U128).
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the `[pda, bump]` tuple.
+ *
+ * @example
+ * ```typescript
+ * import { findFeeSchedulePda } from "@umbra-privacy/sdk";
+ *
+ * const [feeConfigPda] = await findFeeSchedulePda(
+ *   instructionSeed as U128,
+ *   mintAddress,
+ *   0n as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findProtocolFeeVaultPda} for the corresponding fee collection account
+ * @see {@link findRelayerFeeVaultPda} for the relayer fee collection account
+ *
+ * @public
+ */
+declare function findFeeSchedulePda(instructionSeed: U128, mintAddress: Address, offset: U128, umbraProgram: Address): Promise<readonly [Address, number]>;
+/**
+ * Derives the Program Derived Address for a relayer fee schedule account.
+ * Seeds: [RelayerFeeSchedule::SEED, instruction_seed, relayer_pubkey, mint_pubkey, offset]
+ *
+ * The `RelayerFeeSchedule` account defines the fee rates a specific relayer
+ * charges for a given instruction variant and SPL token mint.
+ *
+ * @param instructionSeed - The instruction-specific U128 seed constant.
+ * @param relayerAddress - The relayer's wallet public key.
+ * @param mintAddress - The SPL token mint address for this fee configuration.
+ * @param offset - The account offset discriminator (U128).
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the `[pda, bump]` tuple.
+ *
+ * @public
+ */
+declare function findRelayerFeeSchedulePda(instructionSeed: U128, relayerAddress: Address, mintAddress: Address, offset: U128, umbraProgram: Address): Promise<readonly [Address, number]>;
+
+/**
+ * ZK and MPC Callback PDA Utilities
+ *
+ * This module provides functions to derive Program Derived Addresses (PDAs)
+ * for zero-knowledge proof accounts and MPC callback data accounts in the
+ * Umbra protocol.
+ *
+ * @see {@link findVerifyingKeyPda}
+ * @see {@link findClaimInputBufferPda}
+ * @see {@link findUtxoInputBufferPda}
+ * @see {@link findPublicClaimInputBufferPda}
+ * @see {@link findPublicClaimComputationDataPda}
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module utils/pda/zk
+ */
+
+/**
+ * Derives the Program Derived Address for a Groth16 verifying key account.
+ * Seeds: [Groth16VerifyingKey::SEED, instruction_seed]
+ *
+ * Stores the on-chain Groth16 verifying key for a specific proof circuit
+ * variant. Set up by the protocol administrator and read as immutable input
+ * in claim and UTXO instructions.
+ *
+ * @param instructionSeed - The U128 seed identifying the specific verifying key.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findVerifyingKeyPda } from "@umbra-privacy/sdk";
+ *
+ * const zkVerifyingKeyAccount = await findVerifyingKeyPda(
+ *   zkSeed as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findClaimInputBufferPda} for the proof buffer read alongside this account
+ *
+ * @public
+ */
+declare function findVerifyingKeyPda(instructionSeed: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a confidential claim input buffer account.
+ * Seeds: [ConfidentialClaimProofAccount::SEED, payer_pubkey, offset]
+ *
+ * An ephemeral buffer account that holds the Groth16 proof bytes and encrypted
+ * public inputs required for a confidential claim instruction. Created by the
+ * relayer, consumed by the claim instruction, and closed in the MPC callback.
+ *
+ * @param payerAddress - The relayer's public key (proof account creator).
+ * @param offset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findClaimInputBufferPda } from "@umbra-privacy/sdk";
+ *
+ * const proofAccountPda = await findClaimInputBufferPda(
+ *   relayerPublicKey,
+ *   proofAccountOffset as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findVerifyingKeyPda} for the verifying key used to check this proof
+ * @see {@link findPublicClaimInputBufferPda} for the public-balance claim variant
+ *
+ * @public
+ */
+declare function findClaimInputBufferPda(payerAddress: Address, offset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a confidential UTXO input buffer account.
+ * Seeds: [ConfidentialUtxoProofAccount::SEED, depositor_pubkey, offset]
+ *
+ * An ephemeral buffer account that holds the Groth16 proof data required to
+ * create a new confidential UTXO from an existing encrypted MXE balance.
+ *
+ * @param depositorAddress - The depositor's public key (account creator).
+ * @param offset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findUtxoInputBufferPda } from "@umbra-privacy/sdk";
+ *
+ * const proofAccountPda = await findUtxoInputBufferPda(
+ *   client.signer.address,
+ *   offset as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findVerifyingKeyPda} for the verifying key used to check this proof
+ * @see {@link findClaimInputBufferPda} for the claim-side proof buffer
+ *
+ * @public
+ */
+declare function findUtxoInputBufferPda(depositorAddress: Address, offset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a public UTXO input buffer account.
+ * Seeds: [PublicUtxoProofAccount::SEED, depositor_pubkey, offset]
+ *
+ * An ephemeral buffer account that holds cryptographic proof data for the
+ * `create_deposit_into_mixer_tree_from_public_balance` instruction.
+ *
+ * @param depositorAddress - The depositor's public key (account creator).
+ * @param offset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @public
+ */
+declare function findPublicUtxoInputBufferPda(depositorAddress: Address, offset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a public claim input buffer account.
+ * Seeds: [PublicClaimProofAccount::SEED, relayer_pubkey, offset]
+ *
+ * An ephemeral buffer account that holds the Groth16 proof data for a
+ * public-balance claim instruction (claiming UTXOs into a standard SPL
+ * token ATA).
+ *
+ * @param relayerAddress - The relayer's public key (proof account creator).
+ * @param offset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the derived PDA `Address`.
+ *
+ * @example
+ * ```typescript
+ * import { findPublicClaimInputBufferPda } from "@umbra-privacy/sdk";
+ *
+ * const proofAccountPda = await findPublicClaimInputBufferPda(
+ *   relayerPublicKey,
+ *   proofAccountOffset as U128,
+ *   networkConfig.programId,
+ * );
+ * ```
+ *
+ * @see {@link findVerifyingKeyPda} for the verifying key used to check this proof
+ * @see {@link findClaimInputBufferPda} for the confidential-balance claim variant
+ * @see {@link findPublicClaimComputationDataPda} for the companion MPC callback data account
+ *
+ * @public
+ */
+declare function findPublicClaimInputBufferPda(relayerAddress: Address, offset: U128, umbraProgram: Address): Promise<Address>;
+/**
+ * Derives the Program Derived Address for a public claim MPC computation data account.
+ * Seeds: [PublicClaimMxeMpcCallbackData::SEED, relayer_pubkey, offset]
+ *
+ * Stores all data needed by the Arcium MPC callback handler for a public
+ * claim instruction. Initialised in the handler and closed when the callback
+ * executes.
+ *
+ * Returns the full `[address, bump]` tuple because the canonical bump must be
+ * passed as the `mpcCallbackDataCanonicalBump` instruction argument.
+ *
+ * @param relayerAddress - The relayer's public key.
+ * @param offset - The U128 offset discriminator.
+ * @param umbraProgram - The Umbra program address.
+ * @returns A Promise resolving to the `[pda, bump]` tuple.
+ *
+ * @example
+ * ```typescript
+ * import { findPublicClaimComputationDataPda } from "@umbra-privacy/sdk";
+ *
+ * const [callbackDataPda, mpcCallbackDataCanonicalBump] =
+ *   await findPublicClaimComputationDataPda(
+ *     relayerPublicKey,
+ *     0n as U128,
+ *     networkConfig.programId,
+ *   );
+ * ```
+ *
+ * @see {@link findPublicClaimInputBufferPda} for the companion proof buffer account
+ *
+ * @public
+ */
+declare function findPublicClaimComputationDataPda(relayerAddress: Address, offset: U128, umbraProgram: Address): Promise<readonly [Address, number]>;
+
+export { type ArciumInfrastructurePdas, type NullifierSetPdas, TOKEN_POOL_SEED, computeCompDefOffset, computeStructSeed, findActiveStealthPoolPda, findArciumClusterPda, findArciumCompDefPda, findArciumComputationPda, findArciumExecutingPoolPda, findArciumInfrastructurePdas, findArciumMempoolPda, findArciumMxePda, findClaimInputBufferPda, findConfidentialNullifierBufferPda, findEncryptedTokenAccountPda, findEncryptedUserAccountPda, findFeeSchedulePda, findNetworkComplianceGrantPda, findNullifierSetPdas, findProtocolConfigPda, findProtocolFeeVaultPda, findPublicClaimComputationDataPda, findPublicClaimInputBufferPda, findPublicNullifierBufferPda, findPublicUtxoInputBufferPda, findRelayerFeeSchedulePda, findRelayerFeeVaultPda, findRelayerPda, findSharedComplianceGrantPda, findStealthPoolPda, findTokenPoolPda, findUserComplianceGrantPda, findUtxoInputBufferPda, findVerifyingKeyPda };