@lightprotocol/stateless.js 0.22.1-alpha.7 → 0.23.0-beta.1

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

@@ -1,16 +1,47 @@
 import { PublicKey } from '@solana/web3.js';
-export declare function deriveAddressSeed(seeds: Uint8Array[], programId: PublicKey): Uint8Array;
-export declare function deriveAddress(seed: Uint8Array, addressMerkleTreePubkey?: PublicKey): PublicKey;
+/**
+ * @deprecated Use deriveAddressSeed (no programId param) for V2.
+ * V1 seed derivation includes programId in hash.
+ */
+export declare function deriveAddressSeedLegacy(seeds: Uint8Array[], programId: PublicKey): Uint8Array;
+/**
+ * @deprecated Use deriveAddress with programId param for V2.
+ * V1 address derivation doesn't include programId.
+ */
+export declare function deriveAddressLegacy(seed: Uint8Array, addressMerkleTreePubkey?: PublicKey): PublicKey;
+/**
+ * Explicit V2 address seed derivation - always uses V2 behavior regardless of feature flag.
+ * Use this when you explicitly want V2 derivation (e.g., in tests).
+ */
 export declare function deriveAddressSeedV2(seeds: Uint8Array[]): Uint8Array;
 /**
- * Derives an address from a seed using the v2 method (matching Rust's derive_address_from_seed)
+ * Derive an address seed from multiple seed components.
  *
- * @param addressSeed              The address seed (32 bytes)
- * @param addressMerkleTreePubkey  Merkle tree public key
- * @param programId                Program ID
- * @returns                        Derived address
+ * V2 mode: Does NOT include programId in seed hash. Do not pass programId.
+ * V1 mode: Includes programId in seed hash. Must pass programId.
+ *
+ * @param seeds     Array of seed bytes to combine
+ * @param programId (V1 only) Program ID - required in V1 mode, must be omitted in V2 mode
+ * @returns 32-byte address seed
+ */
+export declare function deriveAddressSeed(seeds: Uint8Array[], programId?: PublicKey): Uint8Array;
+/**
+ * Explicit V2 address derivation - always uses V2 behavior regardless of feature flag.
+ * Use this when you explicitly want V2 derivation (e.g., in tests).
  */
 export declare function deriveAddressV2(addressSeed: Uint8Array, addressMerkleTreePubkey: PublicKey, programId: PublicKey): PublicKey;
+/**
+ * Derive an address for a compressed account.
+ *
+ * V2 mode: Requires programId, includes it in final hash.
+ * V1 mode: Must not pass programId, uses legacy derivation.
+ *
+ * @param addressSeed              The address seed (32 bytes) from deriveAddressSeed
+ * @param addressMerkleTreePubkey  Address tree public key
+ * @param programId                (V2 only) Program ID - required in V2 mode, must be omitted in V1 mode
+ * @returns                        Derived address
+ */
+export declare function deriveAddress(addressSeed: Uint8Array, addressMerkleTreePubkey: PublicKey, programId?: PublicKey): PublicKey;
 export interface NewAddressParams {
     /**
      * Seed for the compressed account. Must be seed used to derive

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

@@ -4,12 +4,25 @@ export declare class PackedAccounts {
     private systemAccounts;
     private nextIndex;
     private map;
+    /**
+     * Create PackedAccounts with system accounts pre-added.
+     * Auto-selects V1 or V2 account layout based on featureFlags.
+     */
     static newWithSystemAccounts(config: SystemAccountMetaConfig): PackedAccounts;
+    /**
+     * @deprecated Use newWithSystemAccounts - it auto-selects V2 when appropriate.
+     */
     static newWithSystemAccountsV2(config: SystemAccountMetaConfig): PackedAccounts;
     addPreAccountsSigner(pubkey: PublicKey): void;
     addPreAccountsSignerMut(pubkey: PublicKey): void;
     addPreAccountsMeta(accountMeta: AccountMeta): void;
+    /**
+     * Add Light system accounts. Auto-selects V1 or V2 layout based on featureFlags.
+     */
     addSystemAccounts(config: SystemAccountMetaConfig): void;
+    /**
+     * @deprecated Use addSystemAccounts - it auto-selects V2 when appropriate.
+     */
     addSystemAccountsV2(config: SystemAccountMetaConfig): void;
     insertOrGet(pubkey: PublicKey): number;
     insertOrGetReadOnly(pubkey: PublicKey): number;
@@ -31,5 +44,12 @@ export declare class SystemAccountMetaConfig {
     static new(selfProgram: PublicKey): SystemAccountMetaConfig;
     static newWithCpiContext(selfProgram: PublicKey, cpiContext: PublicKey): SystemAccountMetaConfig;
 }
+/**
+ * @deprecated V1 system account layout. Use getLightSystemAccountMetas which auto-selects.
+ */
+export declare function getLightSystemAccountMetasLegacy(config: SystemAccountMetaConfig): AccountMeta[];
+/**
+ * Get Light system account metas. Auto-selects V1 or V2 layout based on featureFlags.
+ */
 export declare function getLightSystemAccountMetas(config: SystemAccountMetaConfig): AccountMeta[];
 export declare function getLightSystemAccountMetasV2(config: SystemAccountMetaConfig): AccountMeta[];

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

@@ -14,7 +14,23 @@ export declare enum VERSION {
 export declare const featureFlags: {
     version: VERSION;
     isV2: () => boolean;
+    /**
+     * Beta flag for interface methods (not yet deployed on mainnet).
+     * Runtime only - check LIGHT_PROTOCOL_BETA env var.
+     */
+    isBeta: () => boolean;
 };
+/**
+ * Error message for beta-gated interface methods.
+ */
+export declare const BETA_REQUIRED_ERROR: string;
+/**
+ * Assert that beta features are enabled.
+ * Throws if V2 is not enabled OR if beta is not enabled.
+ *
+ * Use this at the entry point of all interface methods.
+ */
+export declare function assertBetaEnabled(): void;
 /**
  * Returns the correct endpoint name for the current API version. E.g.
  * versionedEndpoint('getCompressedAccount') -> 'getCompressedAccount' (V1)