@lightprotocol/stateless.js 0.22.1-alpha.1 → 0.22.1-alpha.3

package/dist/cjs/node/rpc-interface.d.ts

@@ -1,6 +1,6 @@
-import { PublicKey, MemcmpFilter, DataSlice } from '@solana/web3.js';
+import { PublicKey, MemcmpFilter, DataSlice, Commitment, GetAccountInfoConfig, AccountInfo, ConfirmedSignatureInfo, SignaturesForAddressOptions, TokenAmount } from '@solana/web3.js';
 import { Struct } from 'superstruct';
-import { BN254, ValidityProof, CompressedAccountWithMerkleContext, MerkleContextWithMerkleProof, TokenData, TreeInfo, AddressTreeInfo, CompressedProof } from './state';
+import { BN254, ValidityProof, CompressedAccountWithMerkleContext, MerkleContextWithMerkleProof, TokenData, TreeInfo, AddressTreeInfo, CompressedProof, MerkleContext } from './state';
 import BN from 'bn.js';
 export interface LatestNonVotingSignatures {
     context: {
@@ -83,6 +83,14 @@ export interface AddressWithTreeInfo {
     address: BN254;
     treeInfo: AddressTreeInfo;
 }
+export interface AddressWithTreeInfoV2 {
+    address: Uint8Array;
+    treeInfo: TreeInfo;
+}
+export declare enum DerivationMode {
+    compressible = "compressible",
+    standard = "standard"
+}
 export interface CompressedTransaction {
     compressionInfo: {
         closedAccounts: {
@@ -2761,6 +2769,15 @@ export interface CompressionApiInterface {
     getLatestCompressionSignatures(cursor?: string, limit?: number): Promise<LatestNonVotingSignaturesPaginated>;
     getIndexerHealth(): Promise<string>;
     getIndexerSlot(): Promise<number>;
+    getAccountInfoInterface(address: PublicKey, programId: PublicKey, commitmentOrConfig?: Commitment | GetAccountInfoConfig, addressSpace?: TreeInfo): Promise<{
+        accountInfo: AccountInfo<Buffer>;
+        isCold: boolean;
+        loadContext?: MerkleContext;
+    } | null>;
+    getSignaturesForAddressInterface(address: PublicKey, options?: SignaturesForAddressOptions, compressedOptions?: PaginatedOptions): Promise<SignaturesForAddressInterfaceResult>;
+    getSignaturesForOwnerInterface(owner: PublicKey, options?: SignaturesForAddressOptions, compressedOptions?: PaginatedOptions): Promise<SignaturesForAddressInterfaceResult>;
+    getTokenAccountBalanceInterface(address: PublicKey, owner: PublicKey, mint: PublicKey, commitment?: Commitment): Promise<UnifiedTokenBalance>;
+    getBalanceInterface(address: PublicKey, commitment?: Commitment): Promise<UnifiedBalance>;
 }
 export type RpcResultSuccess<T> = {
     jsonrpc: '2.0';
@@ -2777,3 +2794,80 @@ export type RpcResultError = {
     };
 };
 export type RpcResult<T> = RpcResultSuccess<T> | RpcResultError;
+/**
+ * Source type for signature data.
+ */
+export declare const SignatureSource: {
+    /** From standard Solana RPC (getSignaturesForAddress) */
+    readonly Solana: "solana";
+    /** From compression indexer (getCompressionSignaturesFor*) */
+    readonly Compressed: "compressed";
+};
+export type SignatureSourceType = (typeof SignatureSource)[keyof typeof SignatureSource];
+/**
+ * Unified signature info combining data from both Solana RPC and compression indexer.
+ *
+ * Design rationale:
+ * - `sources` array indicates where this signature was found (can be both!)
+ * - Primary data comes from Solana RPC when available (richer: err, memo, confirmationStatus)
+ * - Compression-only signatures still included for complete transaction history
+ */
+export interface UnifiedSignatureInfo {
+    /** Transaction signature (base58) */
+    signature: string;
+    /** Slot when the transaction was processed */
+    slot: number;
+    /** Block time (unix timestamp), null if not available */
+    blockTime: number | null;
+    /** Transaction error, null if successful. Only from Solana RPC. */
+    err: any | null;
+    /** Memo data. Only from Solana RPC. */
+    memo: string | null;
+    /** Confirmation status. Only from Solana RPC. */
+    confirmationStatus?: string;
+    /**
+     * Sources where this signature was found.
+     * - ['solana'] = only in Solana RPC
+     * - ['compressed'] = only in compression indexer
+     * - ['solana', 'compressed'] = found in both (compression tx indexed by both)
+     */
+    sources: SignatureSourceType[];
+}
+/**
+ * Result of getSignaturesForAddressInterface / getSignaturesForOwnerInterface.
+ *
+ * Design rationale:
+ * - `signatures`: Unified view, merged and deduplicated, sorted by slot desc
+ * - `solana` / `compressed`: Raw responses preserved for clients that need source-specific data
+ * - Allows callers to use the unified view OR drill into specific sources
+ */
+export interface SignaturesForAddressInterfaceResult {
+    /** Merged signatures from all sources, sorted by slot (descending) */
+    signatures: UnifiedSignatureInfo[];
+    /** Raw signatures from Solana RPC */
+    solana: ConfirmedSignatureInfo[];
+    /** Raw signatures from compression indexer */
+    compressed: SignatureWithMetadata[];
+}
+/**
+ * Unified token balance combining hot and cold token balances.
+ */
+export interface UnifiedTokenBalance {
+    /** Total balance (hot + cold) */
+    amount: BN;
+    /** True if any cold balance exists - call load() before usage */
+    hasColdBalance: boolean;
+    /** Token decimals (from on-chain mint or 0 if unknown) */
+    decimals: number;
+    /** Raw Solana RPC TokenAmount response, null if no on-chain account */
+    solana: TokenAmount | null;
+}
+/**
+ * Unified SOL balance combining hot and cold SOL balances.
+ */
+export interface UnifiedBalance {
+    /** Total balance (hot + cold) in lamports */
+    total: BN;
+    /** True if any cold balance exists - call load() before usage */
+    hasColdBalance: boolean;
+}

package/dist/cjs/node/rpc.d.ts

@@ -1,8 +1,9 @@
-import { Connection, ConnectionConfig, PublicKey } from '@solana/web3.js';
+import { AccountInfo, Commitment, Connection, ConnectionConfig, GetAccountInfoConfig, PublicKey, SignaturesForAddressOptions } from '@solana/web3.js';
 import { Buffer } from 'buffer';
-import { ValidityProofWithContext, CompressedTransaction, CompressionApiInterface, GetCompressedTokenAccountsByOwnerOrDelegateOptions, HexInputsForProver, ParsedTokenAccount, SignatureWithMetadata, LatestNonVotingSignatures, LatestNonVotingSignaturesPaginated, WithContext, GetCompressedAccountsByOwnerConfig, WithCursor, AddressWithTree, HashWithTree, CompressedMintTokenHolders, TokenBalance, PaginatedOptions } from './rpc-interface';
-import { MerkleContextWithMerkleProof, BN254, CompressedAccountWithMerkleContext, ValidityProof, AddressTreeInfo } from './state';
+import { ValidityProofWithContext, CompressedTransaction, CompressionApiInterface, GetCompressedTokenAccountsByOwnerOrDelegateOptions, HexInputsForProver, ParsedTokenAccount, SignatureWithMetadata, LatestNonVotingSignatures, LatestNonVotingSignaturesPaginated, WithContext, GetCompressedAccountsByOwnerConfig, WithCursor, AddressWithTree, HashWithTree, CompressedMintTokenHolders, TokenBalance, PaginatedOptions, DerivationMode, AddressWithTreeInfoV2, SignaturesForAddressInterfaceResult, UnifiedSignatureInfo, UnifiedTokenBalance, UnifiedBalance } from './rpc-interface';
+import { MerkleContextWithMerkleProof, BN254, CompressedAccountWithMerkleContext, ValidityProof, AddressTreeInfo, MerkleContext } from './state';
 import BN from 'bn.js';
+import { ConfirmedSignatureInfo } from '@solana/web3.js';
 import { LightWasm } from './test-helpers';
 import { TreeInfo } from './state/types';
 /** @internal */
@@ -72,6 +73,12 @@ export interface NullifierMetadata {
     nullifier: BN254;
     txHash: BN254;
 }
+/**
+ * Merge signatures from Solana RPC and compression indexer.
+ * Deduplicates by signature, tracking sources in the `sources` array.
+ * When a signature exists in both, uses Solana data (richer) but marks both sources.
+ */
+export declare function mergeSignatures(solanaSignatures: ConfirmedSignatureInfo[], compressedSignatures: SignatureWithMetadata[]): UnifiedSignatureInfo[];
 /**
  *
  */
@@ -94,6 +101,7 @@ export declare class Rpc extends Connection implements CompressionApiInterface {
     /**
      * Get a list of all state tree infos. If not already cached, fetches from
      * the cluster.
+     * if featureFlags.isV2(), returns v2 trees too.
      */
     getStateTreeInfos(): Promise<TreeInfo[]>;
     /**
@@ -264,6 +272,17 @@ export declare class Rpc extends Connection implements CompressionApiInterface {
      * @returns             validity proof with context
      */
     getValidityProofV0(hashes?: HashWithTree[], newAddresses?: AddressWithTree[]): Promise<ValidityProofWithContext>;
+    /**
+     * Fetch the latest validity proof for (1) compressed accounts specified by
+     * an array of account Merkle contexts, and (2) new unique addresses specified by
+     * an array of address objects with tree info.
+     *
+     * Validity proofs prove the presence of compressed accounts in state trees
+     * and the non-existence of addresses in address trees, respectively. They
+     * enable verification without recomputing the merkle proof path, thus
+     * lowering verification and data costs.
+     */
+    getValidityProofV2(accountMerkleContexts?: (MerkleContext | undefined)[], newAddresses?: AddressWithTreeInfoV2[], derivationMode?: DerivationMode): Promise<ValidityProofWithContext>;
     /**
      * Fetch the latest validity proof for (1) compressed accounts specified by
      * an array of account hashes. (2) new unique addresses specified by an
@@ -281,4 +300,63 @@ export declare class Rpc extends Connection implements CompressionApiInterface {
      * @returns             validity proof with context
      */
     getValidityProofAndRpcContext(hashes?: HashWithTree[], newAddresses?: AddressWithTree[]): Promise<WithContext<ValidityProofWithContext>>;
+    /**
+     * Fetch the account info for the specified public key. Returns metadata
+     * to load in case the account is cold.
+     * @param address               The account address to fetch.
+     * @param programId             The owner program ID.
+     * @param commitmentOrConfig    Optional. The commitment or config to use
+     *                              for the onchain account fetch.
+     * @param addressSpace          Optional. The address space info that was
+     *                              used at init.
+     *
+     * @returns                     Account info with load info, or null if
+     *                              account doesn't exist. LoadContext is always
+     *                              some if the account is compressible. isCold
+     *                              indicates the current state of the account,
+     *                              if true the account must referenced in a
+     *                              load instruction before use.
+     */
+    getAccountInfoInterface(address: PublicKey, programId: PublicKey, commitmentOrConfig?: Commitment | GetAccountInfoConfig, addressSpace?: TreeInfo): Promise<{
+        accountInfo: AccountInfo<Buffer>;
+        isCold: boolean;
+        loadContext?: MerkleContext;
+    } | null>;
+    /**
+     * Get signatures for an address from both Solana and compression indexer.
+     *
+     * @param address               Address to fetch signatures for.
+     * @param options               Options for the Solana getSignaturesForAddress call.
+     * @param compressedOptions     Options for the compression getCompressionSignaturesForAddress call.
+     * @returns                     Unified signatures from both sources.
+     */
+    getSignaturesForAddressInterface(address: PublicKey, options?: SignaturesForAddressOptions, compressedOptions?: PaginatedOptions): Promise<SignaturesForAddressInterfaceResult>;
+    /**
+     * Get signatures for an owner from both Solana and compression indexer.
+     *
+     * @param owner                 Owner address to fetch signatures for.
+     * @param options               Options for the Solana getSignaturesForAddress call.
+     * @param compressedOptions     Options for the compression getCompressionSignaturesForOwner call.
+     * @returns                     Unified signatures from both sources.
+     */
+    getSignaturesForOwnerInterface(owner: PublicKey, options?: SignaturesForAddressOptions, compressedOptions?: PaginatedOptions): Promise<SignaturesForAddressInterfaceResult>;
+    /**
+     * Get token account balance for an address, regardless of whether the token
+     * account is hot or cold.
+     *
+     * @param address       Token account address.
+     * @param owner         Owner public key.
+     * @param mint          Mint public key.
+     * @param commitment    Commitment level for on-chain query.
+     * @returns             Unified token balance from both sources.
+     */
+    getTokenAccountBalanceInterface(address: PublicKey, owner: PublicKey, mint: PublicKey, commitment?: Commitment): Promise<UnifiedTokenBalance>;
+    /**
+     * Get SOL balance for an address, regardless of whether the account is hot or cold.
+     *
+     * @param address       Address to fetch balance for.
+     * @param commitment    Commitment level for on-chain query.
+     * @returns             Unified SOL balance.
+     */
+    getBalanceInterface(address: PublicKey, commitment?: Commitment): Promise<UnifiedBalance>;
 }

package/dist/cjs/node/test-helpers/test-rpc/get-compressed-token-accounts.d.ts

@@ -3,7 +3,6 @@ import BN from 'bn.js';
 import { Rpc } from '../../rpc';
 import { ParsedTokenAccount, WithCursor } from '../../rpc-interface';
 import { PublicTransactionEvent, CompressedAccountLegacy } from '../../state';
-import { Layout } from '@coral-xyz/borsh';
 type TokenData = {
     mint: PublicKey;
     owner: PublicKey;
@@ -12,7 +11,6 @@ type TokenData = {
     state: number;
     tlv: Buffer | null;
 };
-export declare const TokenDataLayout: Layout<TokenData>;
 export type EventWithParsedTokenTlvData = {
     inputCompressedAccountHashes: number[][];
     outputCompressedAccounts: ParsedTokenAccount[];

package/dist/cjs/node/test-helpers/test-rpc/test-rpc.d.ts

@@ -236,4 +236,10 @@ export declare class TestRpc extends Connection implements CompressionApiInterfa
      */
     getValidityProof(hashes?: BN254[], newAddresses?: BN254[]): Promise<ValidityProofWithContext>;
     getValidityProofV0(hashes?: HashWithTree[], newAddresses?: AddressWithTree[]): Promise<ValidityProofWithContext>;
+    getValidityProofV2(accountMerkleContexts?: any[], newAddresses?: any[], derivationMode?: any): Promise<ValidityProofWithContext>;
+    getAccountInfoInterface(_address: PublicKey, _programId: PublicKey, _addressSpaceInfo: any): Promise<any>;
+    getSignaturesForAddressInterface(_address: PublicKey, _options?: any, _compressedOptions?: PaginatedOptions): Promise<any>;
+    getSignaturesForOwnerInterface(_owner: PublicKey, _options?: any, _compressedOptions?: PaginatedOptions): Promise<any>;
+    getTokenAccountBalanceInterface(_address: PublicKey, _owner: PublicKey, _mint: PublicKey, _commitment?: any): Promise<any>;
+    getBalanceInterface(_address: PublicKey, _commitment?: any): Promise<any>;
 }

package/dist/cjs/node/utils/get-state-tree-infos.d.ts

@@ -1,6 +1,21 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { TreeInfo, TreeType } from '../state/types';
+import { MerkleContext } from '../state/compressed-account';
 import { StateTreeLUTPair } from '../constants';
+/**
+ * Get the currently active output queue from a merkle context.
+ *
+ * @param merkleContext The merkle context to get the output queue from
+ * @returns The output queue public key
+ */
+export declare function getOutputQueue(merkleContext: MerkleContext): PublicKey;
+/**
+ * Get the currently active output tree info from a merkle context.
+ *
+ * @param merkleContext The merkle context to get the output tree info from
+ * @returns The output tree info
+ */
+export declare function getOutputTreeInfo(merkleContext: MerkleContext): TreeInfo;
 /**
  * @deprecated use {@link getTreeInfoByPubkey} instead
  */

package/dist/cjs/node/utils/index.d.ts

@@ -11,3 +11,4 @@ export * from './sleep';
 export * from './validation';
 export * from './state-tree-lookup-table';
 export * from './get-state-tree-infos';
+export * from './pack-decompress';

package/dist/cjs/node/utils/pack-decompress.d.ts

@@ -0,0 +1,31 @@
+import { PublicKey, AccountMeta } from '@solana/web3.js';
+import { ValidityProof } from '../state';
+import { TreeInfo } from '../state/types';
+export interface AccountDataWithTreeInfo {
+    key: string;
+    data: any;
+    treeInfo: TreeInfo;
+}
+export interface PackedDecompressResult {
+    proofOption: {
+        0: ValidityProof | null;
+    };
+    compressedAccounts: any[];
+    systemAccountsOffset: number;
+    remainingAccounts: AccountMeta[];
+}
+/**
+ * Pack accounts and proof for decompressAccountsIdempotent instruction.
+ * This function prepares compressed account data, validity proof, and remaining accounts
+ * for idempotent decompression operations.
+ *
+ * @param programId - The program ID
+ * @param proof - The validity proof with context
+ * @param accountsData - Array of account data with tree info
+ * @param addresses - Array of account addresses
+ * @returns Packed instruction parameters
+ */
+export declare function packDecompressAccountsIdempotent(programId: PublicKey, proof: {
+    compressedProof: ValidityProof | null;
+    treeInfos: TreeInfo[];
+}, accountsData: AccountDataWithTreeInfo[], addresses: PublicKey[]): Promise<PackedDecompressResult>;

package/dist/es/browser/constants.d.ts

@@ -57,14 +57,24 @@ export declare const defaultStateTreeLookupTables: () => {
  * @internal
  */
 export declare const isLocalTest: (url: string) => boolean;
-/**
- * @internal
- */
-export declare const localTestActiveStateTreeInfos: () => TreeInfo[];
+export declare const getDefaultAddressSpace: () => {
+    tree: PublicKey;
+    queue: PublicKey;
+    cpiContext: undefined;
+    treeType: TreeType;
+    nextTreeInfo: null;
+};
 export declare const getDefaultAddressTreeInfo: () => {
     tree: PublicKey;
     queue: PublicKey;
-    cpiContext: null;
+    cpiContext: undefined;
+    treeType: TreeType;
+    nextTreeInfo: null;
+};
+export declare const getBatchAddressTreeInfo: () => {
+    tree: PublicKey;
+    queue: PublicKey;
+    cpiContext: undefined;
     treeType: TreeType;
     nextTreeInfo: null;
 };
@@ -89,6 +99,7 @@ export declare const defaultTestStateTreeAccounts2: () => {
     merkleTree2: PublicKey;
 };
 export declare const COMPRESSED_TOKEN_PROGRAM_ID: PublicKey;
+export declare const CTOKEN_PROGRAM_ID: PublicKey;
 export declare const stateTreeLookupTableMainnet = "7i86eQs3GSqHjN47WdWLTCGMW6gde1q96G2EVnUyK2st";
 export declare const nullifiedStateTreeLookupTableMainnet = "H9QD4u1fG7KmkAzn2tDXhheushxFe1EcrjGGyEFXeMqT";
 export declare const stateTreeLookupTableDevnet = "Dk9mNkbiZXJZ4By8DfSP6HEE4ojZzRvucwpawLeuwq8q";
@@ -117,9 +128,15 @@ export declare const batchMerkleTree5 = "bmt5yU97jC88YXTuSukYHa8Z5Bi2ZDUtmzfkDTA
 export declare const batchQueue5 = "oq5oh5ZR3yGomuQgFduNDzjtGvVWfDRGLuDVjv9a96P";
 export declare const batchCpiContext5 = "cpi5ZTjdgYpZ1Xr7B1cMLLUE81oTtJbNNAyKary2nV6";
 export declare const batchAddressTree = "amt2kaJA14v3urZbZvnc5v2np8jqvc4Z8zDep5wbtzx";
-export declare const testBatchAddressTree = "EzKE84aVTkCUhDHLELqyJaq1Y7UVVmqxXqZjVHwHY3rK";
 export declare const batchMerkleTree = "bmt1LryLZUMmF7ZtqESaw7wifBXLfXHQYoE4GAmrahU";
 export declare const batchQueue = "oq1na8gojfdUhsfCpyjNt6h4JaDWtHf1yQj4koBWfto";
+/**
+ * @internal
+ * Returns local test tree infos.
+ * V1: 2 state trees (smt/nfq/cpi pairs)
+ * V2: 5 batched state trees (bmt/oq/cpi triplets) + 1 address tree (amt2)
+ */
+export declare const localTestActiveStateTreeInfos: () => TreeInfo[];
 export declare const confirmConfig: ConfirmOptions;
 export declare const DEFAULT_MERKLE_TREE_HEIGHT = 26;
 export declare const DEFAULT_MERKLE_TREE_ROOTS = 2800;
@@ -152,6 +169,10 @@ export declare const ADDRESS_QUEUE_ROLLOVER_FEE: BN;
  */
 export declare const STATE_MERKLE_TREE_NETWORK_FEE: BN;
 /**
- * Is charged if the transaction creates at least one address.
+ * Is charged per address the transaction creates.
+ */
+export declare const ADDRESS_TREE_NETWORK_FEE_V1: BN;
+/**
+ * Is charged per address the transaction creates.
  */
-export declare const ADDRESS_TREE_NETWORK_FEE: BN;
+export declare const ADDRESS_TREE_NETWORK_FEE_V2: BN;