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

package/dist/es/browser/state/types.d.ts

@@ -0,0 +1,449 @@
+import BN from 'bn.js';
+import { PublicKey } from '@solana/web3.js';
+import { Buffer } from 'buffer';
+import { NewAddressParamsPacked } from '../utils';
+import { PackedCompressedAccountWithMerkleContext } from './compressed-account';
+export 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
+}
+/**
+ * @deprecated Use {@link TreeInfo} instead.
+ *
+ * A bundle of active trees for a given tree type.
+ */
+export type ActiveTreeBundle = {
+    /**
+     * Tree.
+     */
+    tree: PublicKey;
+    /**
+     * Queue.
+     */
+    queue: PublicKey | null;
+    /**
+     * CPI context.
+     */
+    cpiContext: PublicKey | null;
+    /**
+     * Tree type.
+     */
+    treeType: TreeType;
+};
+/**
+ * @deprecated Use {@link TreeInfo} instead.
+ *
+ * State tree info, versioned via {@link TreeType}. The protocol
+ * stores compressed accounts in state trees.
+ */
+export type StateTreeInfo = TreeInfo;
+/**
+ * Tree info, versioned via {@link TreeType}. The protocol
+ * stores compressed accounts in state trees, and PDAs in address trees.
+ *
+ * Onchain Accounts are subject to Solana's write-lock limits.
+ *
+ * To load balance transactions, use {@link selectStateTreeInfo} to
+ * randomly select a tree from a range of active trees.
+ *
+ * Example:
+ * ```typescript
+ * const infos = await rpc.getStateTreeInfos();
+ * const info = selectStateTreeInfo(infos);
+ * const ix = await CompressedTokenProgram.compress({
+ *     // ...
+ *     outputStateTreeInfo: info
+ * });
+ * ```
+ */
+export type TreeInfo = {
+    /**
+     * Pubkey of the tree account.
+     */
+    tree: PublicKey;
+    /**
+     * Pubkey of the queue account associated with the tree.
+     */
+    queue: PublicKey;
+    /**
+     * The type of tree. One of {@link TreeType}.
+     */
+    treeType: TreeType;
+    /**
+     * Optional compressed cpi context account.
+     */
+    cpiContext?: PublicKey;
+    /**
+     * Next tree info. Is `some` if the next tree should be used for the next
+     * state transition.
+     */
+    nextTreeInfo: TreeInfo | null;
+};
+/**
+ * @deprecated Use {@link TreeInfo} instead.
+ *
+ * Address tree info, versioned via {@link TreeType}. The protocol
+ * stores PDAs in address trees.
+ */
+export type AddressTreeInfo = Omit<StateTreeInfo, 'cpiContext' | 'nextTreeInfo'> & {
+    /**
+     * Next tree info.
+     */
+    nextTreeInfo: AddressTreeInfo | null;
+};
+/**
+ * Packed merkle context.
+ */
+export interface PackedMerkleContextLegacy {
+    /**
+     * Merkle tree pubkey index.
+     */
+    merkleTreePubkeyIndex: number;
+    /**
+     * Queue pubkey index in remaining accounts.
+     */
+    queuePubkeyIndex: number;
+    /**
+     * Leaf index.
+     */
+    leafIndex: number;
+    /**
+     * Whether to prove by index or validity proof.
+     */
+    proveByIndex: boolean;
+}
+/**
+ * @deprecated Use {@link CompressedAccount} instead.
+ *
+ * Describe the generic compressed account details applicable to every
+ * compressed account.
+ *
+ * */
+export interface CompressedAccountLegacy {
+    /**
+     * Public key of program or user owning the account.
+     */
+    owner: PublicKey;
+    /**
+     * Lamports attached to the account.
+     */
+    lamports: BN;
+    /**
+     * Optional unique account ID that is persistent across transactions.
+     */
+    address: number[] | null;
+    /**
+     * Optional data attached to the account.
+     */
+    data: CompressedAccountData | null;
+}
+/**
+ * @deprecated Use {@link CompressedAccountMeta} instead.
+ *
+ * Describe the generic compressed account details applicable to every
+ * compressed account.
+ */
+export interface OutputCompressedAccountWithPackedContext {
+    compressedAccount: CompressedAccountLegacy;
+    merkleTreeIndex: number;
+}
+/**
+ * Compressed account-related proof metadata.
+ */
+export type AccountProofInput = {
+    hash: BN;
+    treeInfo: TreeInfo;
+    leafIndex: number;
+    rootIndex: number;
+    proveByIndex: boolean;
+};
+/**
+ * New address proof metadata.
+ */
+export type NewAddressProofInput = {
+    treeInfo: TreeInfo;
+    address: number[];
+    rootIndex: number;
+    root: BN;
+};
+/**
+ * Describes compressed account data.
+ */
+export interface CompressedAccountData {
+    /**
+     * 8 bytes.
+     */
+    discriminator: number[];
+    /**
+     * Data.
+     */
+    data: Buffer;
+    /**
+     * 32 bytes.
+     */
+    dataHash: number[];
+}
+/**
+ * Merkle tree sequence number.
+ */
+export interface MerkleTreeSequenceNumber {
+    /**
+     * Public key.
+     */
+    pubkey: PublicKey;
+    /**
+     * Sequence number.
+     */
+    seq: BN;
+}
+/**
+ * Public transaction event.
+ */
+export interface PublicTransactionEvent {
+    /**
+     * Input compressed account hashes.
+     */
+    inputCompressedAccountHashes: number[][];
+    /**
+     * Output compressed account hashes.
+     */
+    outputCompressedAccountHashes: number[][];
+    /**
+     * Output compressed accounts.
+     */
+    outputCompressedAccounts: OutputCompressedAccountWithPackedContext[];
+    /**
+     * Output leaf indices.
+     */
+    outputLeafIndices: number[];
+    /**
+     * Sequence numbers.
+     */
+    sequenceNumbers: MerkleTreeSequenceNumber[];
+    /**
+     * Relay fee. Default is null.
+     */
+    relayFee: BN | null;
+    /**
+     * Whether it's a compress or decompress instruction.
+     */
+    isCompress: boolean;
+    /**
+     * If some, it's either a compress or decompress instruction.
+     */
+    compressOrDecompressLamports: BN | null;
+    /**
+     * Public keys.
+     */
+    pubkeyArray: PublicKey[];
+    /**
+     * Message. Default is null.
+     */
+    message: Uint8Array | null;
+}
+/**
+ * Instruction data for invoke.
+ */
+export interface InstructionDataInvoke {
+    /**
+     * Validity proof.
+     */
+    proof: ValidityProof | null;
+    /**
+     * Input compressed accounts with merkle context.
+     */
+    inputCompressedAccountsWithMerkleContext: PackedCompressedAccountWithMerkleContext[];
+    /**
+     * Output compressed accounts.
+     */
+    outputCompressedAccounts: OutputCompressedAccountWithPackedContext[];
+    /**
+     * Relay fee. Default is null.
+     */
+    relayFee: BN | null;
+    /**
+     * Params for creating new addresses.
+     */
+    newAddressParams: NewAddressParamsPacked[];
+    /**
+     * If some, it's either a compress or decompress instruction.
+     */
+    compressOrDecompressLamports: BN | null;
+    /**
+     * Whether it's a compress or decompress instruction.
+     */
+    isCompress: boolean;
+}
+/**
+ * Instruction data for invoking a CPI.
+ */
+export interface InstructionDataInvokeCpi {
+    /**
+     * Validity proof.
+     */
+    proof: ValidityProof | null;
+    /**
+     * Input compressed accounts with merkle context.
+     */
+    inputCompressedAccountsWithMerkleContext: PackedCompressedAccountWithMerkleContext[];
+    /**
+     * Output compressed accounts.
+     */
+    outputCompressedAccounts: OutputCompressedAccountWithPackedContext[];
+    /**
+     * Relay fee. Default is null.
+     */
+    relayFee: BN | null;
+    /**
+     * Params for creating new addresses.
+     */
+    newAddressParams: NewAddressParamsPacked[];
+    /**
+     * If some, it's either a compress or decompress instruction.
+     */
+    compressOrDecompressLamports: BN | null;
+    /**
+     * If `compressOrDecompressLamports` is some, whether it's a compress or
+     * decompress instruction.
+     */
+    isCompress: boolean;
+    /**
+     * Optional compressed CPI context.
+     */
+    compressedCpiContext: CompressedCpiContext | null;
+}
+/**
+ * Compressed CPI context.
+ *
+ * Use if you want to use a single {@link ValidityProof} to update two
+ * compressed accounts owned by separate programs.
+ */
+export interface CompressedCpiContext {
+    /**
+     * Is set by the program that is invoking the CPI to signal that it should
+     * set the cpi context.
+     */
+    setContext: boolean;
+    /**
+     * Is set to wipe the cpi context since someone could have set it before
+     * with unrelated data.
+     */
+    firstSetContext: boolean;
+    /**
+     * Index of cpi context account in remaining accounts.
+     */
+    cpiContextAccountIndex: number;
+}
+/**
+ * @deprecated Use {@link ValidityProof} instead.
+ */
+export interface CompressedProof {
+    /**
+     * 32 bytes.
+     */
+    a: number[];
+    /**
+     * 64 bytes.
+     */
+    b: number[];
+    /**
+     * 32 bytes.
+     */
+    c: number[];
+}
+/**
+ * Validity proof.
+ *
+ * You can request proofs via `rpc.getValidityProof` or
+ * `rpc.getValidityProofV0`.
+ *
+ * One proof can prove the existence of N compressed accounts or the uniqueness
+ * of N PDAs.
+ */
+export interface ValidityProof {
+    /**
+     * 32 bytes.
+     */
+    a: number[];
+    /**
+     * 64 bytes.
+     */
+    b: number[];
+    /**
+     * 32 bytes.
+     */
+    c: number[];
+}
+/**
+ * Packed token data for input compressed accounts.
+ */
+export interface InputTokenDataWithContext {
+    /**
+     * Amount of tokens.
+     */
+    amount: BN;
+    /**
+     * Delegate index.
+     */
+    delegateIndex: number | null;
+    /**
+     * Merkle context.
+     */
+    merkleContext: PackedMerkleContextLegacy;
+    /**
+     * Root index.
+     */
+    rootIndex: number;
+    /**
+     * Lamports.
+     */
+    lamports: BN | null;
+    /**
+     * Tlv.
+     */
+    tlv: Buffer | null;
+}
+/**
+ * Token data.
+ */
+export type TokenData = {
+    /**
+     * The mint associated with this account.
+     */
+    mint: PublicKey;
+    /**
+     * The owner of this account.
+     */
+    owner: PublicKey;
+    /**
+     * The amount of tokens this account holds.
+     */
+    amount: BN;
+    /**
+     * If `delegate` is `Some` then `delegated_amount` represents the amount
+     * authorized by the delegate.
+     */
+    delegate: PublicKey | null;
+    /**
+     * The account's state.
+     */
+    state: number;
+    /**
+     * Token extension tlv.
+     */
+    tlv: Buffer | null;
+};

package/dist/es/browser/test-helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './merkle-tree';
+export * from './test-rpc';
+export * from './test-utils';

package/dist/es/browser/test-helpers/merkle-tree/index.d.ts

@@ -0,0 +1,2 @@
+export * from './indexed-array';
+export * from './merkle-tree';

package/dist/es/browser/test-helpers/merkle-tree/indexed-array.d.ts

@@ -0,0 +1,85 @@
+import { LightWasm } from '../test-rpc/test-rpc';
+import BN from 'bn.js';
+export declare class IndexedElement {
+    index: number;
+    value: BN;
+    nextIndex: number;
+    constructor(index: number, value: BN, nextIndex: number);
+    equals(other: IndexedElement): boolean;
+    compareTo(other: IndexedElement): number;
+    hash(lightWasm: LightWasm, nextValue: BN): Uint8Array;
+}
+export declare class IndexedElementBundle {
+    newLowElement: IndexedElement;
+    newElement: IndexedElement;
+    newElementNextValue: BN;
+    constructor(newLowElement: IndexedElement, newElement: IndexedElement, newElementNextValue: BN);
+}
+/**
+ * This indexed array implementation mirrors the rust implementation of the
+ * indexed merkle tree. It stores the elements of the indexed merkle tree.
+ */
+export declare class IndexedArray {
+    elements: Array<IndexedElement>;
+    currentNodeIndex: number;
+    highestElementIndex: number;
+    constructor(elements: Array<IndexedElement>, currentNodeIndex: number, highestElementIndex: number);
+    static default(): IndexedArray;
+    get(index: number): IndexedElement | undefined;
+    length(): number;
+    isEmpty(): boolean;
+    findElement(value: BN): IndexedElement | undefined;
+    init(): IndexedElementBundle;
+    /**
+     * Finds the index of the low element for the given `value` which should not be part of the array.
+     * Low element is the greatest element which still has a lower value than the provided one.
+     * Low elements are used in non-membership proofs.
+     */
+    findLowElementIndex(value: BN): number | undefined;
+    /**
+     * Returns the low element for the given value and the next value for that low element.
+     * Low element is the greatest element which still has lower value than the provided one.
+     * Low elements are used in non-membership proofs.
+     */
+    findLowElement(value: BN): [IndexedElement | undefined, BN | undefined];
+    /**
+     * Returns the hash of the given element. That hash consists of:
+     * - The value of the given element.
+     * - The `nextIndex` of the given element.
+     * - The value of the element pointed by `nextIndex`.
+     */
+    hashElement(lightWasm: LightWasm, index: number): Uint8Array | undefined;
+    /**
+     * Appends a new element with the given value to the indexed array.
+     * It finds the low element index and uses it to append the new element correctly.
+     * @param value The value of the new element to append.
+     * @returns The new element and its low element after insertion.
+     */
+    append(value: BN): IndexedElementBundle;
+    /**
+     * Appends a new element with the given value to the indexed array using a specific low element index.
+     * This method ensures the new element is placed correctly relative to the low element.
+     * @param lowElementIndex The index of the low element.
+     * @param value The value of the new element to append.
+     * @returns The new element and its updated low element.
+     */
+    appendWithLowElementIndex(lowElementIndex: number, value: BN): IndexedElementBundle;
+    /**
+     * Finds the lowest element in the array.
+     * @returns The lowest element or undefined if the array is empty.
+     */
+    lowest(): IndexedElement | undefined;
+    /**
+     * Creates a new element with the specified value and updates the low element index accordingly.
+     * @param lowElementIndex The index of the low element.
+     * @param value The value for the new element.
+     * @returns A bundle containing the new element, the updated low element, and the value of the next element.
+     */
+    newElementWithLowElementIndex(lowElementIndex: number, value: BN): IndexedElementBundle;
+    /**
+     * Creates a new element with the specified value by first finding the appropriate low element index.
+     * @param value The value for the new element.
+     * @returns A bundle containing the new element, the updated low element, and the value of the next element.
+     */
+    newElement(value: BN): IndexedElementBundle;
+}

package/dist/es/browser/test-helpers/merkle-tree/merkle-tree.d.ts

@@ -0,0 +1,92 @@
+import { LightWasm } from '../test-rpc/test-rpc';
+export declare const DEFAULT_ZERO = "0";
+/**
+ * @callback hashFunction
+ * @param left Left leaf
+ * @param right Right leaf
+ */
+/**
+ * Merkle tree
+ */
+export declare class MerkleTree {
+    /**
+     * Constructor
+     * @param {number} levels Number of levels in the tree
+     * @param {Array} [elements] Initial elements
+     * @param {Object} options
+     * @param {hashFunction} [options.hashFunction] Function used to hash 2 leaves
+     * @param [options.zeroElement] Value for non-existent leaves
+     */
+    levels: number;
+    capacity: number;
+    zeroElement: string;
+    _zeros: string[];
+    _layers: string[][];
+    _lightWasm: LightWasm;
+    constructor(levels: number, lightWasm: LightWasm, elements?: string[], { zeroElement }?: {
+        zeroElement?: string | undefined;
+    });
+    _rebuild(): void;
+    /**
+     * Get tree root
+     * @returns {*}
+     */
+    root(): string;
+    /**
+     * Insert new element into the tree
+     * @param element Element to insert
+     */
+    insert(element: string): void;
+    /**
+     * Insert multiple elements into the tree. Tree will be fully rebuilt during this operation.
+     * @param {Array} elements Elements to insert
+     */
+    bulkInsert(elements: string[]): void;
+    /**
+     * Change an element in the tree
+     * @param {number} index Index of element to change
+     * @param element Updated element value
+     */
+    update(index: number, element: string): void;
+    /**
+     * Get merkle path to a leaf
+     * @param {number} index Leaf index to generate path for
+     * @returns {{pathElements: number[], pathIndex: number[]}} An object containing adjacent elements and left-right index
+     */
+    path(index: number): {
+        pathElements: string[];
+        pathIndices: number[];
+    };
+    /**
+     * Find an element in the tree
+     * @param element An element to find
+     * @param comparator A function that checks leaf value equality
+     * @returns {number} Index if element is found, otherwise -1
+     */
+    indexOf(element: string, comparator?: ((element: string, el: string) => boolean) | null): number;
+    /**
+     * Returns a copy of non-zero tree elements
+     * @returns {Object[]}
+     */
+    elements(): string[];
+    /**
+     * Serialize entire tree state including intermediate layers into a plain object
+     * Deserializing it back will not require to recompute any hashes
+     * Elements are not converted to a plain type, this is responsibility of the caller
+     */
+    serialize(): {
+        levels: number;
+        _zeros: string[];
+        _layers: string[][];
+    };
+    /**
+     * Deserialize data into a MerkleTree instance
+     * Make sure to provide the same hashFunction as was used in the source tree,
+     * otherwise the tree state will be invalid
+     *
+     * @param data
+     * @param hashFunction
+     * @returns {MerkleTree}
+     */
+    static deserialize(data: any, hashFunction: (left: string, right: string) => string): any;
+}

package/dist/es/browser/test-helpers/test-rpc/get-compressed-accounts.d.ts

@@ -0,0 +1,7 @@
+import { PublicKey } from '@solana/web3.js';
+import BN from 'bn.js';
+import { Rpc } from '../../rpc';
+import { CompressedAccountWithMerkleContext } from '../../state';
+export declare function getCompressedAccountsByOwnerTest(rpc: Rpc, owner: PublicKey): Promise<CompressedAccountWithMerkleContext[]>;
+export declare function getCompressedAccountByHashTest(rpc: Rpc, hash: BN): Promise<CompressedAccountWithMerkleContext | undefined>;
+export declare function getMultipleCompressedAccountsByHashTest(rpc: Rpc, hashes: BN[]): Promise<CompressedAccountWithMerkleContext[]>;

package/dist/es/browser/test-helpers/test-rpc/get-compressed-token-accounts.d.ts

@@ -0,0 +1,40 @@
+import { PublicKey } from '@solana/web3.js';
+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;
+    amount: BN;
+    delegate: PublicKey | null;
+    state: number;
+    tlv: Buffer | null;
+};
+export declare const TokenDataLayout: Layout<TokenData>;
+export type EventWithParsedTokenTlvData = {
+    inputCompressedAccountHashes: number[][];
+    outputCompressedAccounts: ParsedTokenAccount[];
+};
+/**
+ * Manually parse the compressed token layout for a given compressed account.
+ * @param compressedAccount - The compressed account
+ * @returns The parsed token data
+ */
+export declare function parseTokenLayoutWithIdl(compressedAccount: CompressedAccountLegacy, programId?: PublicKey): TokenData | null;
+/**
+ * Retrieves all compressed token accounts for a given mint and owner.
+ *
+ * Note: This function is intended for testing purposes only. For production, use rpc.getCompressedTokenAccounts.
+ *
+ * @param events    Public transaction events
+ * @param owner     PublicKey of the token owner
+ * @param mint      PublicKey of the token mint
+ */
+export declare function getCompressedTokenAccounts(events: PublicTransactionEvent[], rpc: Rpc): Promise<ParsedTokenAccount[]>;
+/** @internal */
+export declare function getCompressedTokenAccountsByOwnerTest(rpc: Rpc, owner: PublicKey, mint: PublicKey): Promise<WithCursor<ParsedTokenAccount[]>>;
+export declare function getCompressedTokenAccountsByDelegateTest(rpc: Rpc, delegate: PublicKey, mint: PublicKey): Promise<WithCursor<ParsedTokenAccount[]>>;
+export declare function getCompressedTokenAccountByHashTest(rpc: Rpc, hash: BN): Promise<ParsedTokenAccount>;
+export {};

package/dist/es/browser/test-helpers/test-rpc/get-parsed-events.d.ts

@@ -0,0 +1,15 @@
+import { ParsedTransactionWithMeta, PublicKey } from '@solana/web3.js';
+import { Rpc } from '../../rpc';
+import { PublicTransactionEvent } from '../../state';
+import { Buffer } from 'buffer';
+type Deserializer<T> = (data: Buffer, tx: ParsedTransactionWithMeta) => T;
+/**
+ * @internal
+ * Returns newest first.
+ *
+ * */
+export declare function getParsedEvents(rpc: Rpc): Promise<PublicTransactionEvent[]>;
+export declare const parseEvents: <T>(indexerEventsTransactions: (ParsedTransactionWithMeta | null)[], deserializeFn: Deserializer<T>) => NonNullable<T>[];
+export declare const parsePublicTransactionEventWithIdl: (data: Buffer) => PublicTransactionEvent | null;
+export declare function parseLightTransaction(dataVec: Uint8Array[], accountKeys: PublicKey[][]): PublicTransactionEvent | null | undefined;
+export {};

package/dist/es/browser/test-helpers/test-rpc/index.d.ts

@@ -0,0 +1,3 @@
+export * from './test-rpc';
+export * from './get-parsed-events';
+export * from './get-compressed-token-accounts';