@cascade-fyi/compression-kit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1033 @@
+import { AccountMeta, Address } from "@solana/kit";
+
+//#region src/state/types.d.ts
+
+/**
+ * Tree type enum matching the on-chain representation.
+ */
+declare enum TreeType {
+  /** v1 state merkle tree */
+  StateV1 = 1,
+  /** v1 address merkle tree */
+  AddressV1 = 2,
+  /** v2 state merkle tree */
+  StateV2 = 3,
+  /** v2 address merkle tree */
+  AddressV2 = 4,
+}
+/**
+ * Tree info - metadata about a state or address tree.
+ *
+ * Used for:
+ * - State trees: store compressed accounts
+ * - Address trees: store PDAs
+ */
+interface TreeInfo {
+  /** Pubkey of the tree account */
+  tree: Address;
+  /** Pubkey of the queue account associated with the tree */
+  queue: Address;
+  /** The type of tree */
+  treeType: TreeType;
+  /** Optional compressed CPI context account */
+  cpiContext?: Address;
+  /** Next tree info if this tree is full/rolled over */
+  nextTreeInfo: TreeInfo | null;
+}
+/**
+ * @deprecated Use TreeInfo instead.
+ */
+type StateTreeInfo = TreeInfo;
+/**
+ * @deprecated Use TreeInfo instead.
+ */
+type AddressTreeInfo = Omit<TreeInfo, "cpiContext" | "nextTreeInfo"> & {
+  nextTreeInfo: AddressTreeInfo | null;
+};
+/**
+ * Packed merkle context for instruction data.
+ */
+interface PackedMerkleContext {
+  /** Merkle tree pubkey index in remaining accounts */
+  merkleTreePubkeyIndex: number;
+  /** Queue pubkey index in remaining accounts */
+  queuePubkeyIndex: number;
+  /** Leaf index in the tree */
+  leafIndex: number;
+  /** Whether to prove by index or validity proof */
+  proveByIndex: boolean;
+}
+/**
+ * Packed state tree info for compressed accounts.
+ */
+interface PackedStateTreeInfo {
+  /** Recent valid root index */
+  rootIndex: number;
+  /** Whether the account can be proven by index */
+  proveByIndex: boolean;
+  /** Index of the merkle tree in remaining accounts */
+  merkleTreePubkeyIndex: number;
+  /** Index of the queue in remaining accounts */
+  queuePubkeyIndex: number;
+  /** Index of the leaf in the state tree */
+  leafIndex: number;
+}
+/**
+ * Packed address tree info for new PDAs.
+ */
+interface PackedAddressTreeInfo {
+  /** Index of the address tree in remaining accounts */
+  addressMerkleTreePubkeyIndex: number;
+  /** Index of the address queue in remaining accounts */
+  addressQueuePubkeyIndex: number;
+  /** Recent valid root index */
+  rootIndex: number;
+}
+/**
+ * Data attached to a compressed account.
+ */
+interface CompressedAccountData {
+  /** 8-byte discriminator */
+  discriminator: Uint8Array;
+  /** Account data */
+  data: Uint8Array;
+  /** 32-byte hash of the data */
+  dataHash: Uint8Array;
+}
+/**
+ * Merkle context for a compressed account.
+ */
+interface MerkleContext {
+  /** Tree info */
+  treeInfo: TreeInfo;
+  /** Poseidon hash of the account (stored as leaf) */
+  hash: bigint;
+  /** Position in the state tree */
+  leafIndex: number;
+  /** Whether the account can be proven by index */
+  proveByIndex: boolean;
+}
+/**
+ * Merkle context with full merkle proof.
+ */
+interface MerkleContextWithProof extends MerkleContext {
+  /** Merkle proof path */
+  merkleProof: bigint[];
+  /** Root index the proof is valid for */
+  rootIndex: number;
+  /** Current root */
+  root: bigint;
+}
+/**
+ * Compressed account with merkle context.
+ */
+interface CompressedAccount extends MerkleContext {
+  /** Owner program or user */
+  owner: Address;
+  /** Lamports attached to the account */
+  lamports: bigint;
+  /** Optional persistent address */
+  address: Uint8Array | null;
+  /** Optional account data */
+  data: CompressedAccountData | null;
+  /** Whether this account is read-only in the transaction */
+  readOnly: boolean;
+}
+/**
+ * Compressed account meta for instruction data.
+ */
+interface CompressedAccountMeta {
+  /** Packed tree info */
+  treeInfo: PackedStateTreeInfo;
+  /** Address (32 bytes or null) */
+  address: Uint8Array | null;
+  /** Lamports or null */
+  lamports: bigint | null;
+  /** Output state tree index */
+  outputStateTreeIndex: number;
+}
+/**
+ * Validity proof for compressed accounts.
+ *
+ * Proves existence of N compressed accounts or uniqueness of N PDAs.
+ */
+interface ValidityProof {
+  /** 32 bytes - G1 point x */
+  a: Uint8Array;
+  /** 64 bytes - G2 point */
+  b: Uint8Array;
+  /** 32 bytes - G1 point y */
+  c: Uint8Array;
+}
+/**
+ * Validity proof with context information.
+ */
+interface ValidityProofWithContext {
+  /** The proof (null if prove-by-index for all accounts) */
+  compressedProof: ValidityProof | null;
+  /** State roots */
+  roots: bigint[];
+  /** Root indices */
+  rootIndices: number[];
+  /** Leaf indices */
+  leafIndices: number[];
+  /** Leaf hashes */
+  leaves: bigint[];
+  /** Tree infos */
+  treeInfos: TreeInfo[];
+  /** Whether to prove by index for each account */
+  proveByIndices: boolean[];
+}
+/**
+ * Account proof input for validity proof request.
+ */
+interface AccountProofInput {
+  /** Account hash */
+  hash: bigint;
+  /** Tree info */
+  treeInfo: TreeInfo;
+  /** Leaf index */
+  leafIndex: number;
+  /** Root index */
+  rootIndex: number;
+  /** Whether to prove by index */
+  proveByIndex: boolean;
+}
+/**
+ * New address proof input for validity proof request.
+ */
+interface NewAddressProofInput {
+  /** Tree info */
+  treeInfo: TreeInfo;
+  /** Address bytes (32) */
+  address: Uint8Array;
+  /** Root index */
+  rootIndex: number;
+  /** Current root */
+  root: bigint;
+}
+/**
+ * Compressed token data.
+ */
+interface TokenData {
+  /** Token mint */
+  mint: Address;
+  /** Token owner */
+  owner: Address;
+  /** Token amount */
+  amount: bigint;
+  /** Delegate (if any) */
+  delegate: Address | null;
+  /** Account state (0=uninitialized, 1=initialized, 2=frozen) */
+  state: number;
+  /** Token extension TLV data */
+  tlv: Uint8Array | null;
+}
+/**
+ * Parsed token account combining compressed account and token data.
+ */
+interface ParsedTokenAccount {
+  /** Compressed account */
+  compressedAccount: CompressedAccount;
+  /** Parsed token data */
+  parsed: TokenData;
+}
+/**
+ * Compressed CPI context for multi-program transactions.
+ */
+interface CompressedCpiContext {
+  /** Whether to set the CPI context */
+  setContext: boolean;
+  /** Whether this is the first context set (wipes previous) */
+  firstSetContext: boolean;
+  /** Index of CPI context account in remaining accounts */
+  cpiContextAccountIndex: number;
+}
+/**
+ * New address parameters for creating PDAs.
+ */
+interface NewAddressParams {
+  /** Seed for address derivation */
+  seed: Uint8Array;
+  /** Root index for address tree */
+  addressMerkleTreeRootIndex: number;
+  /** Address tree pubkey */
+  addressMerkleTreePubkey: Address;
+  /** Address queue pubkey */
+  addressQueuePubkey: Address;
+}
+/**
+ * Packed new address parameters for instruction data.
+ */
+interface NewAddressParamsPacked {
+  /** Seed bytes */
+  seed: Uint8Array;
+  /** Address tree root index */
+  addressMerkleTreeRootIndex: number;
+  /** Index of address tree in remaining accounts */
+  addressMerkleTreeAccountIndex: number;
+  /** Index of address queue in remaining accounts */
+  addressQueueAccountIndex: number;
+}
+//#endregion
+//#region src/state/bn254.d.ts
+/**
+ * BN254 field element utilities using native bigint.
+ *
+ * BN254 is the elliptic curve used by Light Protocol's ZK proofs.
+ * All hashes must be less than the field modulus (~2^254) for circuit compatibility.
+ *
+ * This module replaces BN.js with native bigint for:
+ * - Better performance
+ * - No Node.js Buffer dependency
+ * - Edge/browser compatibility
+ */
+/**
+ * BN254 field element type.
+ *
+ * This is a bigint that is guaranteed to be less than the BN254 field modulus.
+ * While we can't enforce this at the type level with branded types (since bigint
+ * operations return plain bigint), we validate at creation time.
+ */
+type BN254 = bigint;
+/**
+ * Check if a bigint is within the BN254 field.
+ */
+declare function isBN254(value: bigint): boolean;
+/**
+ * Assert that a bigint is within the BN254 field.
+ * @throws BN254Error if value is out of range
+ */
+declare function assertIsBN254(value: bigint): asserts value is BN254;
+/**
+ * Create a BN254 field element from various input types.
+ *
+ * @param input - Number, string, bigint, or byte array
+ * @param base - Optional base for string parsing: 10, 16, 'hex', or 'base58'
+ * @returns BN254 field element
+ * @throws BN254Error if value exceeds field size
+ */
+declare function createBN254(input: string | number | bigint | Uint8Array | number[], base?: number | "hex" | "base58"): BN254;
+/**
+ * Create a BN254 from a 32-byte array (big-endian).
+ */
+declare function bn254FromBytes(bytes: Uint8Array): BN254;
+/**
+ * Convert a BN254 field element to a base58 string.
+ */
+declare function encodeBN254toBase58(value: BN254): string;
+/**
+ * Convert a BN254 field element to a hex string (with 0x prefix).
+ */
+declare function encodeBN254toHex(value: BN254): string;
+/**
+ * Convert a BN254 field element to a 32-byte array (big-endian).
+ */
+declare function bn254ToBytes(value: BN254): Uint8Array;
+/**
+ * Convert a BN254 field element to a decimal string.
+ */
+declare function bn254ToDecimalString(value: BN254): string;
+/**
+ * Convert bytes to bigint (big-endian).
+ */
+declare function bytesToBigIntBE(bytes: Uint8Array): bigint;
+/**
+ * Convert bytes to bigint (little-endian).
+ */
+declare function bytesToBigIntLE(bytes: Uint8Array): bigint;
+/**
+ * Convert bigint to bytes (big-endian).
+ */
+declare function bigIntToBytesBE(value: bigint, length: number): Uint8Array;
+/**
+ * Convert bigint to bytes (little-endian).
+ */
+declare function bigIntToBytesLE(value: bigint, length: number): Uint8Array;
+/**
+ * Add two BN254 values with modular reduction.
+ */
+declare function bn254Add(a: BN254, b: BN254): BN254;
+/**
+ * Subtract two BN254 values with modular reduction.
+ */
+declare function bn254Sub(a: BN254, b: BN254): BN254;
+/**
+ * Multiply two BN254 values with modular reduction.
+ */
+declare function bn254Mul(a: BN254, b: BN254): BN254;
+/**
+ * Check if a value is smaller than the BN254 field size (big-endian bytes).
+ */
+declare function isSmallerThanFieldSize(bytes: Uint8Array): boolean;
+//#endregion
+//#region src/constants.d.ts
+declare enum VERSION {
+  V1 = "V1",
+  V2 = "V2",
+}
+/**
+ * Feature flags for protocol versioning.
+ * @internal
+ */
+declare const featureFlags: {
+  version: VERSION;
+  isV2: () => boolean;
+};
+/**
+ * Returns versioned endpoint name.
+ * @example versionedEndpoint('getCompressedAccount') -> 'getCompressedAccountV2' (if V2)
+ */
+declare const versionedEndpoint: (base: string) => string;
+/**
+ * BN254 prime field size.
+ * All hashes must be less than this value for ZK circuit compatibility.
+ */
+declare const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * Highest address plus one (used for address validation).
+ */
+declare const HIGHEST_ADDRESS_PLUS_ONE = 452312848583266388373324160190187140051835877600158453279131187530910662655n;
+/** Light System Program ID */
+declare const LIGHT_SYSTEM_PROGRAM: Address<"SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">;
+/** Account Compression Program ID */
+declare const ACCOUNT_COMPRESSION_PROGRAM: Address<"compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">;
+/** Noop Program ID (for logging) */
+declare const NOOP_PROGRAM: Address<"noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV">;
+/** Compressed Token Program ID */
+declare const COMPRESSED_TOKEN_PROGRAM: Address<"cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m">;
+/** Registered Program PDA (constant) */
+declare const REGISTERED_PROGRAM_PDA: Address<"35hkDgaAKwMCaxRz2ocSZ6NaUrtKkyNqU6c4RV3tYJRh">;
+declare const INVOKE_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+declare const INVOKE_CPI_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+declare const INVOKE_CPI_WITH_READ_ONLY_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+declare const INVOKE_CPI_WITH_ACCOUNT_INFO_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+declare const INSERT_INTO_QUEUES_DISCRIMINATOR: Uint8Array<ArrayBuffer>;
+declare const COMPUTE_BUDGET_PATTERN: Uint8Array<ArrayBuffer>;
+/** Mainnet state tree lookup table */
+declare const STATE_TREE_LOOKUP_TABLE_MAINNET: Address<"7i86eQs3GSqHjN47WdWLTCGMW6gde1q96G2EVnUyK2st">;
+/** Mainnet nullified state tree lookup table */
+declare const NULLIFIED_STATE_TREE_LOOKUP_TABLE_MAINNET: Address<"H9QD4u1fG7KmkAzn2tDXhheushxFe1EcrjGGyEFXeMqT">;
+/** Devnet state tree lookup table */
+declare const STATE_TREE_LOOKUP_TABLE_DEVNET: Address<"Dk9mNkbiZXJZ4By8DfSP6HEE4ojZzRvucwpawLeuwq8q">;
+/** Devnet nullified state tree lookup table */
+declare const NULLIFIED_STATE_TREE_LOOKUP_TABLE_DEVNET: Address<"AXbHzp1NgjLvpfnD6JRTTovXZ7APUCdtWZFCRr5tCxse">;
+interface StateTreeLUTPair {
+  stateTreeLookupTable: Address;
+  nullifyLookupTable: Address;
+}
+/**
+ * Returns default state tree lookup tables for each network.
+ */
+declare function defaultStateTreeLookupTables(): {
+  mainnet: StateTreeLUTPair[];
+  devnet: StateTreeLUTPair[];
+};
+declare const MERKLE_TREE_PUBKEY: Address<"smt1NamzXdq4AMqS2fS2F1i5KTYPZRhoHgWx38d8WsT">;
+declare const NULLIFIER_QUEUE_PUBKEY: Address<"nfq1NvQDJ2GEgnS8zt9prAe8rjjpAW1zFkrvZoBR148">;
+declare const CPI_CONTEXT_PUBKEY: Address<"cpi1uHzrEhBG733DoEJNgHCyRS3XmmyVNZx5fonubE4">;
+declare const MERKLE_TREE_2_PUBKEY: Address<"smt2rJAFdyJJupwMKAqTNAJwvjhmiZ4JYGZmbVRw1Ho">;
+declare const NULLIFIER_QUEUE_2_PUBKEY: Address<"nfq2hgS7NYemXsFaFUCe3EMXSDSfnZnAe27jC6aPP1X">;
+declare const CPI_CONTEXT_2_PUBKEY: Address<"cpi2cdhkH5roePvcudTgUL8ppEBfTay1desGh8G8QxK">;
+declare const ADDRESS_TREE: Address<"amt1Ayt45jfbdw5YSo7iz6WZxUmnZsQTYXy82hVwyC2">;
+declare const ADDRESS_QUEUE: Address<"aq1S9z4reTSQAdgWHGD2zDaS39sjGrAxbR31vxJ2F4F">;
+declare const BATCH_MERKLE_TREE_1: Address<"bmt1LryLZUMmF7ZtqESaw7wifBXLfXHQYoE4GAmrahU">;
+declare const BATCH_QUEUE_1: Address<"oq1na8gojfdUhsfCpyjNt6h4JaDWtHf1yQj4koBWfto">;
+declare const BATCH_CPI_CONTEXT_1: Address<"cpi15BoVPKgEPw5o8wc2T816GE7b378nMXnhH3Xbq4y">;
+declare const BATCH_MERKLE_TREE_2: Address<"bmt2UxoBxB9xWev4BkLvkGdapsz6sZGkzViPNph7VFi">;
+declare const BATCH_QUEUE_2: Address<"oq2UkeMsJLfXt2QHzim242SUi3nvjJs8Pn7Eac9H9vg">;
+declare const BATCH_CPI_CONTEXT_2: Address<"cpi2yGapXUR3As5SjnHBAVvmApNiLsbeZpF3euWnW6B">;
+declare const BATCH_ADDRESS_TREE: Address<"amt2kaJA14v3urZbZvnc5v2np8jqvc4Z8zDep5wbtzx">;
+declare const TEST_BATCH_ADDRESS_TREE: Address<"EzKE84aVTkCUhDHLELqyJaq1Y7UVVmqxXqZjVHwHY3rK">;
+declare const DEFAULT_MERKLE_TREE_HEIGHT = 26;
+declare const DEFAULT_MERKLE_TREE_ROOTS = 2800;
+/** Threshold for UTXO merging (per asset) */
+declare const UTXO_MERGE_THRESHOLD = 20;
+declare const UTXO_MERGE_MAXIMUM = 10;
+/** Tree rollover threshold (95% capacity) */
+declare const TRANSACTION_MERKLE_TREE_ROLLOVER_THRESHOLD: bigint;
+/** Fee per output compressed account (for tree rollover) */
+declare const STATE_MERKLE_TREE_ROLLOVER_FEE: bigint;
+/** Fee per new address (for address tree rollover) */
+declare const ADDRESS_QUEUE_ROLLOVER_FEE = 392n;
+/** Network fee for nullifying compressed accounts */
+declare const STATE_MERKLE_TREE_NETWORK_FEE = 5000n;
+/** V1 network fee per new address */
+declare const ADDRESS_TREE_NETWORK_FEE_V1 = 5000n;
+/** V2 network fee per new address */
+declare const ADDRESS_TREE_NETWORK_FEE_V2 = 10000n;
+/**
+ * Derives the account compression authority PDA.
+ */
+declare function getAccountCompressionAuthority(): Promise<Address>;
+/**
+ * Returns static accounts needed for Light System Program calls.
+ */
+declare function defaultStaticAccounts(): Promise<Address[]>;
+/**
+ * Check if URL is localhost/localnet.
+ * @internal
+ */
+declare function isLocalTest(url: string): boolean;
+/**
+ * Returns default test state tree accounts for localnet.
+ */
+declare function defaultTestStateTreeAccounts(): {
+  nullifierQueue: Address;
+  merkleTree: Address;
+  merkleTreeHeight: number;
+  addressTree: Address;
+  addressQueue: Address;
+};
+/**
+ * Returns active state tree infos for localnet testing.
+ * @internal
+ */
+declare function localTestActiveStateTreeInfos(): TreeInfo[];
+/**
+ * Returns default address tree info.
+ */
+declare function getDefaultAddressTreeInfo(): TreeInfo;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error types for Light Protocol stateless operations.
+ */
+declare enum UtxoErrorCode {
+  NEGATIVE_LAMPORTS = "NEGATIVE_LAMPORTS",
+  NOT_U64 = "NOT_U64",
+  BLINDING_EXCEEDS_FIELD_SIZE = "BLINDING_EXCEEDS_FIELD_SIZE",
+}
+declare enum SelectInUtxosErrorCode {
+  FAILED_TO_FIND_UTXO_COMBINATION = "FAILED_TO_FIND_UTXO_COMBINATION",
+  INVALID_NUMBER_OF_IN_UTXOS = "INVALID_NUMBER_OF_IN_UTXOS",
+}
+declare enum CreateUtxoErrorCode {
+  OWNER_UNDEFINED = "OWNER_UNDEFINED",
+  INVALID_OUTPUT_UTXO_LENGTH = "INVALID_OUTPUT_UTXO_LENGTH",
+  UTXO_DATA_UNDEFINED = "UTXO_DATA_UNDEFINED",
+}
+declare enum RpcErrorCode {
+  CONNECTION_UNDEFINED = "CONNECTION_UNDEFINED",
+  RPC_PUBKEY_UNDEFINED = "RPC_PUBKEY_UNDEFINED",
+  RPC_METHOD_NOT_IMPLEMENTED = "RPC_METHOD_NOT_IMPLEMENTED",
+  RPC_INVALID = "RPC_INVALID",
+}
+declare enum LookupTableErrorCode {
+  LOOK_UP_TABLE_UNDEFINED = "LOOK_UP_TABLE_UNDEFINED",
+  LOOK_UP_TABLE_NOT_INITIALIZED = "LOOK_UP_TABLE_NOT_INITIALIZED",
+}
+declare enum HashErrorCode {
+  NO_POSEIDON_HASHER_PROVIDED = "NO_POSEIDON_HASHER_PROVIDED",
+}
+declare enum ProofErrorCode {
+  INVALID_PROOF = "INVALID_PROOF",
+  PROOF_INPUT_UNDEFINED = "PROOF_INPUT_UNDEFINED",
+  PROOF_GENERATION_FAILED = "PROOF_GENERATION_FAILED",
+}
+declare enum MerkleTreeErrorCode {
+  MERKLE_TREE_NOT_INITIALIZED = "MERKLE_TREE_NOT_INITIALIZED",
+  SOL_MERKLE_TREE_UNDEFINED = "SOL_MERKLE_TREE_UNDEFINED",
+  MERKLE_TREE_UNDEFINED = "MERKLE_TREE_UNDEFINED",
+  INPUT_UTXO_NOT_INSERTED_IN_MERKLE_TREE = "INPUT_UTXO_NOT_INSERTED_IN_MERKLE_TREE",
+  MERKLE_TREE_INDEX_UNDEFINED = "MERKLE_TREE_INDEX_UNDEFINED",
+  MERKLE_TREE_SET_SPACE_UNDEFINED = "MERKLE_TREE_SET_SPACE_UNDEFINED",
+}
+declare enum UtilsErrorCode {
+  ACCOUNT_NAME_UNDEFINED_IN_IDL = "ACCOUNT_NAME_UNDEFINED_IN_IDL",
+  PROPERTY_UNDEFINED = "PROPERTY_UNDEFINED",
+  LOOK_UP_TABLE_CREATION_FAILED = "LOOK_UP_TABLE_CREATION_FAILED",
+  UNSUPPORTED_ARCHITECTURE = "UNSUPPORTED_ARCHITECTURE",
+  UNSUPPORTED_PLATFORM = "UNSUPPORTED_PLATFORM",
+  ACCOUNTS_UNDEFINED = "ACCOUNTS_UNDEFINED",
+  INVALID_NUMBER = "INVALID_NUMBER",
+}
+declare enum BN254ErrorCode {
+  VALUE_TOO_LARGE = "VALUE_TOO_LARGE",
+  INVALID_BASE58 = "INVALID_BASE58",
+}
+/**
+ * Base error class for Light Protocol errors.
+ */
+declare class LightError extends Error {
+  readonly code: string;
+  readonly functionName: string;
+  readonly codeMessage?: string;
+  constructor(code: string, functionName: string, codeMessage?: string);
+}
+declare class UtxoError extends LightError {}
+declare class SelectInUtxosError extends LightError {}
+declare class CreateUtxoError extends LightError {}
+declare class RpcError extends LightError {}
+declare class LookupTableError extends LightError {}
+declare class HashError extends LightError {}
+declare class ProofError extends LightError {}
+declare class MerkleTreeError extends LightError {}
+declare class UtilsError extends LightError {}
+declare class BN254Error extends LightError {}
+declare function createUtxoError(code: UtxoErrorCode, functionName: string, message?: string): UtxoError;
+declare function createRpcError(code: RpcErrorCode, functionName: string, message?: string): RpcError;
+declare function createProofError(code: ProofErrorCode, functionName: string, message?: string): ProofError;
+declare function createBN254Error(code: BN254ErrorCode, functionName: string, message?: string): BN254Error;
+//#endregion
+//#region src/utils/conversion.d.ts
+/**
+ * Conversion and hashing utilities for Light Protocol.
+ *
+ * Uses @noble/hashes for Keccak256 - pure JS, works in all environments.
+ */
+/**
+ * Hash multiple byte arrays with Keccak256 and truncate to BN254 field size.
+ *
+ * This is the primary hash function used by Light Protocol. It:
+ * 1. Concatenates all input arrays
+ * 2. Hashes with Keccak256
+ * 3. Sets the first byte to 0 to ensure the result fits in BN254 field
+ *
+ * @param inputs - Array of byte arrays to hash
+ * @returns 32-byte hash that fits in BN254 field
+ */
+declare function hashvToBn254FieldSizeBe(inputs: Uint8Array[]): Uint8Array;
+/**
+ * Hash multiple byte arrays with Keccak256, appending 0xFF bump seed.
+ *
+ * This variant appends a 255 bump seed before hashing, matching the
+ * on-chain behavior for certain hash derivations.
+ *
+ * @param inputs - Array of byte arrays to hash
+ * @returns 32-byte hash that fits in BN254 field
+ */
+declare function hashvToBn254FieldSizeBeWithBump(inputs: Uint8Array[]): Uint8Array;
+/**
+ * Hash bytes with Keccak256 and find a valid bump seed.
+ *
+ * @deprecated Use hashvToBn254FieldSizeBe instead.
+ *
+ * This function iterates through bump seeds (255 down to 0) to find one
+ * that produces a hash smaller than the BN254 field size. This is the
+ * legacy approach - the simpler truncation method is now preferred.
+ *
+ * @param bytes - Bytes to hash
+ * @returns Tuple of [hash, bumpSeed] or null if no valid bump found
+ */
+declare function hashToBn254FieldSizeBe(bytes: Uint8Array): [Uint8Array, number] | null;
+/**
+ * Convert hex string to bytes.
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert bytes to hex string (no 0x prefix).
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Convert bigint to hex string with 0x prefix.
+ */
+declare function toHex(value: bigint): string;
+/**
+ * Ensure value is an array.
+ */
+declare function toArray<T>(value: T | T[]): T[];
+/**
+ * Merge bytes arrays into one.
+ */
+declare function mergeBytes(arrays: Uint8Array[]): Uint8Array;
+/**
+ * Compare two byte arrays for equality.
+ */
+declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Pad bytes to a fixed length (right-pad with zeros).
+ */
+declare function padBytes(bytes: Uint8Array, length: number): Uint8Array;
+/**
+ * Push unique items to an array.
+ * Mutates the array in place.
+ */
+declare function pushUniqueItems<T>(items: T[], target: T[]): void;
+/**
+ * Convert bytes to decimal string (for ZK circuit compatibility).
+ */
+declare function bytesToDecimalString(bytes: Uint8Array): string;
+/**
+ * Validate that a hash value is within BN254 field size.
+ */
+declare function validateBN254Hash(hash: Uint8Array): boolean;
+/**
+ * Assert hash is valid BN254 field element.
+ */
+declare function assertValidBN254Hash(hash: Uint8Array): void;
+//#endregion
+//#region src/utils/address.d.ts
+/**
+ * Derive an address seed from seeds and program ID.
+ *
+ * This combines the program ID with user-provided seeds and hashes
+ * them to produce a 32-byte seed suitable for address derivation.
+ *
+ * @param seeds - User-provided seed bytes
+ * @param programId - The program ID that "owns" this address
+ * @returns 32-byte address seed
+ */
+declare function deriveAddressSeed(seeds: Uint8Array[], programId: Address): Uint8Array;
+/**
+ * Derive a compressed account address from a seed and address tree.
+ *
+ * @param seed - 32-byte seed (typically from deriveAddressSeed)
+ * @param addressMerkleTreePubkey - The address tree to derive from
+ * @returns Derived address as a Solana Address
+ *
+ * @example
+ * ```typescript
+ * import { deriveAddressSeed, deriveAddress } from '@cascade-fyi/compression-kit';
+ * import { address } from '@solana/kit';
+ *
+ * const programId = address('YourProgramId...');
+ * const seed = deriveAddressSeed([new TextEncoder().encode('my-seed')], programId);
+ * const compressedAddress = deriveAddress(seed);
+ * ```
+ */
+declare function deriveAddress(seed: Uint8Array, addressMerkleTreePubkey?: Address): Address;
+/**
+ * Derive address seed using V2 method (no program ID in combined seeds).
+ *
+ * @param seeds - Seeds to hash together
+ * @returns 32-byte address seed
+ */
+declare function deriveAddressSeedV2(seeds: Uint8Array[]): Uint8Array;
+/**
+ * Derive address using V2 method (matches Rust derive_address_from_seed).
+ *
+ * @param addressSeed - 32-byte address seed
+ * @param addressMerkleTreePubkey - Address tree pubkey
+ * @param programId - Program ID
+ * @returns Derived address
+ */
+declare function deriveAddressV2(addressSeed: Uint8Array, addressMerkleTreePubkey: Address, programId: Address): Address;
+/**
+ * Get the index of an address in an array, adding it if not present.
+ */
+declare function getIndexOrAdd(accounts: Address[], pubkey: Address): number;
+/**
+ * Pack new address params for instruction data.
+ *
+ * Converts NewAddressParams to NewAddressParamsPacked by replacing
+ * pubkeys with their indices in the remaining accounts array.
+ *
+ * @param newAddressParams - Array of new address parameters
+ * @param remainingAccounts - Existing remaining accounts (will be modified)
+ * @returns Packed params and updated remaining accounts
+ */
+declare function packNewAddressParams(newAddressParams: NewAddressParams[], remainingAccounts: Address[]): {
+  newAddressParamsPacked: NewAddressParamsPacked[];
+  remainingAccounts: Address[];
+};
+/**
+ * Convert an address to bytes.
+ */
+declare function addressToBytes(addr: Address): Uint8Array;
+/**
+ * Convert bytes to an address.
+ *
+ * Note: This performs base58 encoding on the bytes. The bytes should
+ * be a valid 32-byte representation of an address.
+ */
+declare function bytesToAddress(bytes: Uint8Array): Address;
+//#endregion
+//#region src/utils/instruction.d.ts
+/**
+ * Configuration for Light System Program account metas.
+ */
+interface SystemAccountMetaConfig {
+  /** The program making the CPI call */
+  selfProgram: Address;
+  /** Optional CPI context account */
+  cpiContext?: Address;
+  /** Optional SOL compression recipient */
+  solCompressionRecipient?: Address;
+  /** Optional SOL pool PDA */
+  solPoolPda?: Address;
+}
+/**
+ * Create a basic system account config.
+ */
+declare function createSystemAccountConfig(selfProgram: Address): SystemAccountMetaConfig;
+/**
+ * Create a system account config with CPI context.
+ */
+declare function createSystemAccountConfigWithCpi(selfProgram: Address, cpiContext: Address): SystemAccountMetaConfig;
+/**
+ * Derive the CPI signer PDA for a program.
+ */
+declare function getCpiSignerPda(selfProgram: Address): Promise<Address>;
+/**
+ * Derive the account compression authority PDA.
+ */
+declare function getAccountCompressionAuthority$1(): Promise<Address>;
+/**
+ * Get the system program address.
+ */
+declare function getSystemProgram(): Address;
+/**
+ * Build Light System account metas (V1 layout).
+ *
+ * @param config - System account configuration
+ * @returns Array of account metas for Light System Program
+ *
+ * @example
+ * ```typescript
+ * import { getLightSystemAccountMetas, createSystemAccountConfig } from '@cascade-fyi/compression-kit';
+ * import { address } from '@solana/kit';
+ *
+ * const programId = address('YourProgramId...');
+ * const config = createSystemAccountConfig(programId);
+ * const metas = await getLightSystemAccountMetas(config);
+ * ```
+ */
+declare function getLightSystemAccountMetas(config: SystemAccountMetaConfig): Promise<AccountMeta[]>;
+/**
+ * Build Light System account metas (V2 layout - no noop program).
+ */
+declare function getLightSystemAccountMetasV2(config: SystemAccountMetaConfig): Promise<AccountMeta[]>;
+/**
+ * Helper class for building remaining accounts for Light Protocol instructions.
+ *
+ * Manages three categories of accounts:
+ * 1. Pre-accounts: Signers and other accounts that come first
+ * 2. System accounts: Light System Program static accounts
+ * 3. Packed accounts: Dynamic accounts indexed by pubkey
+ */
+declare class PackedAccounts {
+  private preAccounts;
+  private systemAccounts;
+  private nextIndex;
+  private accountMap;
+  /**
+   * Create a new PackedAccounts with system accounts (V1 layout).
+   */
+  static newWithSystemAccounts(config: SystemAccountMetaConfig): Promise<PackedAccounts>;
+  /**
+   * Create a new PackedAccounts with system accounts (V2 layout).
+   */
+  static newWithSystemAccountsV2(config: SystemAccountMetaConfig): Promise<PackedAccounts>;
+  /**
+   * Add a signer to pre-accounts (readonly).
+   */
+  addPreAccountsSigner(pubkey: Address): void;
+  /**
+   * Add a writable signer to pre-accounts.
+   */
+  addPreAccountsSignerMut(pubkey: Address): void;
+  /**
+   * Add an account meta to pre-accounts.
+   */
+  addPreAccountsMeta(accountMeta: AccountMeta): void;
+  /**
+   * Add system accounts (V1 layout).
+   */
+  addSystemAccounts(config: SystemAccountMetaConfig): Promise<void>;
+  /**
+   * Add system accounts (V2 layout).
+   */
+  addSystemAccountsV2(config: SystemAccountMetaConfig): Promise<void>;
+  /**
+   * Insert or get index for a writable account.
+   */
+  insertOrGet(pubkey: Address): number;
+  /**
+   * Insert or get index for a readonly account.
+   */
+  insertOrGetReadOnly(pubkey: Address): number;
+  /**
+   * Insert or get index with full configuration.
+   */
+  insertOrGetConfig(pubkey: Address, isSigner: boolean, isWritable: boolean): number;
+  /**
+   * Get packed accounts sorted by insertion order.
+   */
+  private getPackedAccountMetas;
+  /**
+   * Get offsets for system and packed accounts.
+   */
+  private getOffsets;
+  /**
+   * Build final remaining accounts array with offsets.
+   */
+  toAccountMetas(): {
+    remainingAccounts: AccountMeta[];
+    systemStart: number;
+    packedStart: number;
+  };
+}
+//#endregion
+//#region src/rpc.d.ts
+/**
+ * Context wrapper for RPC responses.
+ */
+interface WithContext<T> {
+  context: {
+    slot: number;
+  };
+  value: T;
+}
+/**
+ * Cursor-based pagination wrapper.
+ */
+interface WithCursor<T> {
+  cursor: string | null;
+  items: T;
+}
+/**
+ * Options for paginated requests.
+ */
+interface PaginatedOptions {
+  cursor?: string;
+  limit?: number;
+}
+/**
+ * Options for getCompressedAccountsByOwner.
+ */
+interface GetCompressedAccountsByOwnerConfig {
+  cursor?: string;
+  limit?: number;
+}
+/**
+ * Options for getCompressedTokenAccountsByOwner.
+ */
+interface GetCompressedTokenAccountsConfig {
+  mint?: Address;
+  cursor?: string;
+  limit?: number;
+}
+/**
+ * Hash with tree info for proof requests.
+ */
+interface HashWithTreeInfo {
+  hash: BN254;
+  stateTreeInfo: TreeInfo;
+}
+/**
+ * Address with tree info for proof requests.
+ */
+interface AddressWithTreeInfo {
+  address: BN254;
+  addressTreeInfo: TreeInfo;
+}
+/**
+ * Signature metadata from compression indexer.
+ */
+interface SignatureWithMetadata {
+  blockTime: number;
+  signature: string;
+  slot: number;
+}
+/**
+ * Token balance info.
+ */
+interface TokenBalance {
+  balance: bigint;
+  mint: Address;
+}
+/**
+ * Light Protocol Photon RPC client.
+ *
+ * Provides methods for querying compressed accounts, requesting validity proofs,
+ * and other indexer operations.
+ */
+declare class PhotonRpc {
+  readonly endpoint: string;
+  private readonly headers;
+  constructor(endpoint: string, headers?: Record<string, string>);
+  /**
+   * Make a JSON-RPC request to the Photon indexer.
+   */
+  private request;
+  /**
+   * Request with context wrapper.
+   */
+  private requestWithContext;
+  /**
+   * Get indexer health status.
+   */
+  getIndexerHealth(): Promise<string>;
+  /**
+   * Get current indexer slot.
+   */
+  getIndexerSlot(): Promise<number>;
+  /**
+   * Get a single compressed account by address or hash.
+   */
+  getCompressedAccount(addressOrHash: {
+    address?: Address;
+    hash?: BN254;
+  }): Promise<CompressedAccount | null>;
+  /**
+   * Get multiple compressed accounts by hashes.
+   */
+  getMultipleCompressedAccounts(hashes: BN254[]): Promise<CompressedAccount[]>;
+  /**
+   * Get compressed accounts by owner.
+   */
+  getCompressedAccountsByOwner(owner: Address, config?: GetCompressedAccountsByOwnerConfig): Promise<WithCursor<CompressedAccount[]>>;
+  /**
+   * Get compressed SOL balance by owner.
+   */
+  getCompressedBalanceByOwner(owner: Address): Promise<bigint>;
+  /**
+   * Get merkle proof for a compressed account.
+   */
+  getCompressedAccountProof(hash: BN254): Promise<MerkleContextWithProof>;
+  /**
+   * Get merkle proofs for multiple compressed accounts.
+   */
+  getMultipleCompressedAccountProofs(hashes: BN254[]): Promise<MerkleContextWithProof[]>;
+  /**
+   * Get validity proof for compressed accounts and/or new addresses.
+   *
+   * This is the main method for obtaining ZK proofs needed to use
+   * compressed accounts in transactions.
+   */
+  getValidityProof(hashes: HashWithTreeInfo[], newAddresses: AddressWithTreeInfo[]): Promise<ValidityProofWithContext>;
+  /**
+   * Get compressed token accounts by owner.
+   */
+  getCompressedTokenAccountsByOwner(owner: Address, config?: GetCompressedTokenAccountsConfig): Promise<WithCursor<ParsedTokenAccount[]>>;
+  /**
+   * Get compressed token balances by owner.
+   */
+  getCompressedTokenBalancesByOwner(owner: Address, config?: GetCompressedTokenAccountsConfig): Promise<WithCursor<TokenBalance[]>>;
+  /**
+   * Get compression signatures for an account hash.
+   */
+  getCompressionSignaturesForAccount(hash: BN254): Promise<SignatureWithMetadata[]>;
+  /**
+   * Get compression signatures for an address.
+   */
+  getCompressionSignaturesForAddress(addr: Address, options?: PaginatedOptions): Promise<WithCursor<SignatureWithMetadata[]>>;
+  /**
+   * Get compression signatures for an owner.
+   */
+  getCompressionSignaturesForOwner(owner: Address, options?: PaginatedOptions): Promise<WithCursor<SignatureWithMetadata[]>>;
+  /**
+   * Get latest non-voting signatures (compression transactions).
+   */
+  getLatestCompressionSignatures(cursor?: string, limit?: number): Promise<WithCursor<SignatureWithMetadata[]>>;
+}
+/**
+ * Create a Photon RPC client.
+ *
+ * @param endpoint - Photon indexer URL (e.g., "https://zk-testnet.helius.dev:8784")
+ * @param headers - Optional additional headers
+ * @returns PhotonRpc instance
+ *
+ * @example
+ * ```typescript
+ * import { createPhotonRpc } from '@cascade-fyi/compression-kit';
+ *
+ * const rpc = createPhotonRpc('https://mainnet.helius-rpc.com/?api-key=YOUR_KEY');
+ * const accounts = await rpc.getCompressedAccountsByOwner(ownerAddress);
+ * ```
+ */
+declare function createPhotonRpc(endpoint: string, headers?: Record<string, string>): PhotonRpc;
+//#endregion
+export { ACCOUNT_COMPRESSION_PROGRAM, ADDRESS_QUEUE, ADDRESS_QUEUE_ROLLOVER_FEE, ADDRESS_TREE, ADDRESS_TREE_NETWORK_FEE_V1, ADDRESS_TREE_NETWORK_FEE_V2, type AccountProofInput, type AddressTreeInfo, type AddressWithTreeInfo, BATCH_ADDRESS_TREE, BATCH_CPI_CONTEXT_1, BATCH_CPI_CONTEXT_2, BATCH_MERKLE_TREE_1, BATCH_MERKLE_TREE_2, BATCH_QUEUE_1, BATCH_QUEUE_2, type BN254, BN254Error, BN254ErrorCode, COMPRESSED_TOKEN_PROGRAM, COMPUTE_BUDGET_PATTERN, CPI_CONTEXT_2_PUBKEY, CPI_CONTEXT_PUBKEY, type CompressedAccount, type CompressedAccountData, type CompressedAccountMeta, type CompressedCpiContext, CreateUtxoError, CreateUtxoErrorCode, DEFAULT_MERKLE_TREE_HEIGHT, DEFAULT_MERKLE_TREE_ROOTS, FIELD_SIZE, type GetCompressedAccountsByOwnerConfig, type GetCompressedTokenAccountsConfig, HIGHEST_ADDRESS_PLUS_ONE, HashError, HashErrorCode, type HashWithTreeInfo, INSERT_INTO_QUEUES_DISCRIMINATOR, INVOKE_CPI_DISCRIMINATOR, INVOKE_CPI_WITH_ACCOUNT_INFO_DISCRIMINATOR, INVOKE_CPI_WITH_READ_ONLY_DISCRIMINATOR, INVOKE_DISCRIMINATOR, LIGHT_SYSTEM_PROGRAM, LookupTableError, LookupTableErrorCode, MERKLE_TREE_2_PUBKEY, MERKLE_TREE_PUBKEY, type MerkleContext, type MerkleContextWithProof, MerkleTreeError, MerkleTreeErrorCode, NOOP_PROGRAM, NULLIFIED_STATE_TREE_LOOKUP_TABLE_DEVNET, NULLIFIED_STATE_TREE_LOOKUP_TABLE_MAINNET, NULLIFIER_QUEUE_2_PUBKEY, NULLIFIER_QUEUE_PUBKEY, type NewAddressParams, type NewAddressParamsPacked, type NewAddressProofInput, PackedAccounts, type PackedAddressTreeInfo, type PackedMerkleContext, type PackedStateTreeInfo, type PaginatedOptions, type ParsedTokenAccount, PhotonRpc, ProofError, ProofErrorCode, REGISTERED_PROGRAM_PDA, RpcError, RpcErrorCode, STATE_MERKLE_TREE_NETWORK_FEE, STATE_MERKLE_TREE_ROLLOVER_FEE, STATE_TREE_LOOKUP_TABLE_DEVNET, STATE_TREE_LOOKUP_TABLE_MAINNET, SelectInUtxosError, SelectInUtxosErrorCode, type SignatureWithMetadata, type StateTreeInfo, type StateTreeLUTPair, type SystemAccountMetaConfig, TEST_BATCH_ADDRESS_TREE, TRANSACTION_MERKLE_TREE_ROLLOVER_THRESHOLD, type TokenBalance, type TokenData, type TreeInfo, TreeType, UTXO_MERGE_MAXIMUM, UTXO_MERGE_THRESHOLD, UtilsError, UtilsErrorCode, UtxoError, UtxoErrorCode, VERSION, type ValidityProof, type ValidityProofWithContext, type WithContext, type WithCursor, addressToBytes, assertIsBN254, assertValidBN254Hash, bigIntToBytesBE, bigIntToBytesLE, bn254Add, bn254FromBytes, bn254Mul, bn254Sub, bn254ToBytes, bn254ToDecimalString, bytesEqual, bytesToAddress, bytesToBigIntBE, bytesToBigIntLE, bytesToDecimalString, bytesToHex, createBN254, createBN254Error, createPhotonRpc, createProofError, createRpcError, createSystemAccountConfig, createSystemAccountConfigWithCpi, createUtxoError, defaultStateTreeLookupTables, defaultStaticAccounts, defaultTestStateTreeAccounts, deriveAddress, deriveAddressSeed, deriveAddressSeedV2, deriveAddressV2, encodeBN254toBase58, encodeBN254toHex, featureFlags, getAccountCompressionAuthority, getAccountCompressionAuthority$1 as getCompressionAuthority, getCpiSignerPda, getDefaultAddressTreeInfo, getIndexOrAdd, getLightSystemAccountMetas, getLightSystemAccountMetasV2, getSystemProgram, hashToBn254FieldSizeBe, hashvToBn254FieldSizeBe, hashvToBn254FieldSizeBeWithBump, hexToBytes, isBN254, isLocalTest, isSmallerThanFieldSize, localTestActiveStateTreeInfos, mergeBytes, packNewAddressParams, padBytes, pushUniqueItems, toArray, toHex, validateBN254Hash, versionedEndpoint };
+//# sourceMappingURL=index.d.cts.map