@velumdotcash/sdk 2.0.0

package/dist/utils/encryption.d.ts

@@ -0,0 +1,152 @@
+import { Keypair } from '@solana/web3.js';
+import { Utxo } from '../models/utxo.js';
+/**
+ * Represents a UTXO with minimal required fields
+ */
+export interface UtxoData {
+    amount: string;
+    blinding: string;
+    index: number | string;
+    [key: string]: any;
+}
+export interface EncryptionKey {
+    v1: Uint8Array;
+    v2: Uint8Array;
+}
+/**
+ * Service for handling encryption and decryption of UTXO data
+ */
+export declare class EncryptionService {
+    static readonly ENCRYPTION_VERSION_V2: Buffer<ArrayBuffer>;
+    static readonly ENCRYPTION_VERSION_V3: Buffer<ArrayBuffer>;
+    static readonly SIGNATURE_SCHEMA_VERSION: Buffer<ArrayBuffer>;
+    static readonly RECIPIENT_ID_LENGTH = 8;
+    private encryptionKeyV1;
+    private encryptionKeyV2;
+    private asymmetricSecretKey;
+    private utxoPrivateKeyV1;
+    private utxoPrivateKeyV2;
+    private walletAddress;
+    /**
+   * Generate an encryption key from a signature
+   * @param signature The user's signature
+   * @param walletAddress Optional wallet address for logging/verification
+   * @returns The generated encryption key
+   */
+    deriveEncryptionKeyFromSignature(signature: Uint8Array, walletAddress?: string): EncryptionKey;
+    /**
+     * Generate an encryption key from a wallet keypair (V2 format)
+     * @param keypair The Solana keypair to derive the encryption key from
+     * @returns The generated encryption key
+     */
+    deriveEncryptionKeyFromWallet(keypair: Keypair): EncryptionKey;
+    /**
+     * Get the Asymmetric Public Key (X25519) derived from the encryption key
+     */
+    getAsymmetricPublicKey(): Uint8Array;
+    /**
+     * Derive recipient ID hash from X25519 public key
+     * Used for O(1) early termination during UTXO decryption
+     * @param publicKey Optional X25519 public key. If not provided, uses own public key.
+     * @returns First 8 bytes of SHA256(publicKey)
+     */
+    deriveRecipientIdHash(publicKey?: Uint8Array): Buffer;
+    /**
+     * Check if encrypted data is for this wallet (O(1) operation)
+     * Enables early termination without attempting expensive crypto decryption
+     * @param encryptedBuffer The encrypted data buffer
+     * @returns true if we should attempt decryption, false to skip
+     */
+    private shouldAttemptDecryption;
+    /**
+     * Encrypt data with the stored encryption key
+     * @param data The data to encrypt
+     * @returns The encrypted data as a Buffer
+     * @throws Error if the encryption key has not been generated
+     */
+    encrypt(data: Buffer | string): Buffer;
+    encryptDecryptedDoNotUse(data: Buffer | string): Buffer;
+    /**
+     * Decrypt data with the stored encryption key
+     * @param encryptedData The encrypted data to decrypt
+     * @returns The decrypted data as a Buffer, or null if legacy format (no schema version byte)
+     * @throws Error if the encryption key has not been generated or if the wrong key is used
+     */
+    decrypt(encryptedData: Buffer): Buffer | null;
+    /**
+     * Decrypt data using the old V1 format (120-bit HMAC with SHA256)
+     * @param encryptedData The encrypted data to decrypt
+     * @param keypair Optional keypair to derive V1 key for backward compatibility
+     * @returns The decrypted data as a Buffer
+     */
+    private decryptV1;
+    private timingSafeEqual;
+    /**
+     * Encrypt data using Asymmetric Encryption (X25519 + XSalsa20-Poly1305)
+     * @param data The data to encrypt
+     * @param recipientPublicKey The recipient's X25519 Public Key
+     */
+    encryptAsymmetric(data: Buffer | string, recipientPublicKey: Uint8Array): Buffer;
+    /**
+     * Decrypt data using Asymmetric Encryption
+     * @returns Buffer on success, null if legacy format (no schema version byte) - these are skipped
+     */
+    private decryptV3;
+    /**
+     * Decrypt data using the new V2 format (256-bit Keccak HMAC)
+     * @param encryptedData The encrypted data to decrypt
+     * @returns The decrypted data as a Buffer, or null if legacy format (no schema version byte) - these are skipped
+     */
+    private decryptV2;
+    /**
+     * Reset the encryption keys (mainly for testing purposes)
+     */
+    resetEncryptionKey(): void;
+    /**
+     * Encrypt a UTXO using a compact pipe-delimited format
+     * Always uses V2 encryption format. The UTXO's version property is used only for key derivation.
+     * @param utxo The UTXO to encrypt (includes version property)
+     * @param recipientEncryptionKey Optional recipient X25519 public key for asymmetric encryption
+     * @returns The encrypted UTXO data as a Buffer
+     * @throws Error if the V2 encryption key has not been set
+     */
+    encryptUtxo(utxo: Utxo, recipientEncryptionKey?: Uint8Array): Buffer;
+    encryptUtxoDecryptedDoNotUse(utxo: Utxo): Buffer;
+    getEncryptionKeyVersion(encryptedData: Buffer | string): 'v1' | 'v2' | 'v3';
+    /**
+     * Check if the schema version at byte 9 matches the expected version.
+     * Returns null if schema version matches or data is legacy format (no schema version).
+     * Returns the found schema version if it doesn't match (for early termination).
+     * @param encryptedBuffer The encrypted data buffer
+     * @param encryptionVersion The encryption version (v1, v2, v3)
+     * @returns null if schema version matches or is legacy, otherwise the mismatched version byte
+     */
+    private checkSchemaVersionMismatch;
+    /**
+     * Decrypt an encrypted UTXO and parse it to a Utxo instance
+     * Automatically detects the UTXO version based on the encryption format
+     * @param encryptedData The encrypted UTXO data
+     * @param keypair The UTXO keypair to use for the decrypted UTXO
+     * @param lightWasm Optional LightWasm instance. If not provided, a new one will be created
+     * @param walletKeypair Optional wallet keypair for V1 backward compatibility
+     * @returns Promise resolving to the decrypted Utxo instance, or null if schema version mismatch
+     * @throws Error if the encryption key has not been set or if decryption fails
+     */
+    decryptUtxo(encryptedData: Buffer | string, lightWasm?: any): Promise<Utxo | null>;
+    getUtxoPrivateKeyWithVersion(version: 'v1' | 'v2'): string;
+    deriveUtxoPrivateKey(encryptedData?: Buffer | string): string;
+    hasUtxoPrivateKeyWithVersion(version: 'v1' | 'v2'): boolean;
+    /**
+     * Get the cached V1 UTXO private key
+     * @returns A private key in hex format that can be used to create a UTXO keypair
+     * @throws Error if V1 encryption key has not been set
+     */
+    getUtxoPrivateKeyV1(): string;
+    /**
+     * Get the cached V2 UTXO private key
+     * @returns A private key in hex format that can be used to create a UTXO keypair
+     * @throws Error if V2 encryption key has not been set
+     */
+    getUtxoPrivateKeyV2(): string;
+}
+export declare function serializeProofAndExtData(proof: any, extData: any, isSpl?: boolean): Buffer<ArrayBuffer>;