@ghostspeak/sdk 1.7.1 → 2.0.1

package/dist/client.d.ts

@@ -0,0 +1,5 @@
+import '@solana/kit';
+export { b as GhostSpeak, b as GhostSpeakClient, b as default, l as lamportsToSol, s as sol } from './GhostSpeakClient-CyeZ6Tyb.js';
+import './ipfs-types-KJcvy9Qk.js';
+import '@solana/addresses';
+import '@solana/instructions';

package/dist/crypto.d.ts

@@ -0,0 +1,331 @@
+import { Address } from '@solana/addresses';
+import { IInstruction } from '@solana/kit';
+
+/**
+ * Unified ElGamal Encryption Module
+ *
+ * This module consolidates all ElGamal implementations into a single, optimized solution
+ * for Solana's Token-2022 confidential transfers with complete ZK proof support.
+ *
+ * Features:
+ * - Twisted ElGamal encryption on curve25519
+ * - Bulletproof range proofs (0 to 2^64)
+ * - Validity and equality proofs
+ * - Homomorphic addition/subtraction
+ * - WASM optimization support
+ * - Full Solana ZK Proof Program integration
+ */
+
+interface ElGamalKeypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+interface ElGamalCiphertext {
+    commitment: PedersenCommitment;
+    handle: DecryptHandle;
+}
+interface PedersenCommitment {
+    commitment: Uint8Array;
+}
+interface DecryptHandle {
+    handle: Uint8Array;
+}
+interface RangeProof {
+    proof: Uint8Array;
+    commitment: Uint8Array;
+}
+interface ValidityProof {
+    proof: Uint8Array;
+}
+interface EqualityProof {
+    proof: Uint8Array;
+}
+interface TransferProof {
+    rangeProof: RangeProof;
+    validityProof: ValidityProof;
+    equalityProof: EqualityProof;
+}
+interface WithdrawProof {
+    proof: Uint8Array;
+}
+declare const PROOF_SIZES: {
+    readonly RANGE_PROOF: 674;
+    readonly VALIDITY_PROOF: 160;
+    readonly EQUALITY_PROOF: 192;
+    readonly WITHDRAW_PROOF: 80;
+    readonly ZERO_BALANCE_PROOF: 96;
+    readonly FEE_SIGMA_PROOF: 256;
+    readonly PUBKEY_VALIDITY_PROOF: 64;
+};
+/**
+ * Generate a new ElGamal keypair
+ */
+declare function generateKeypair(): ElGamalKeypair;
+/**
+ * Derive ElGamal keypair from seed
+ */
+declare function deriveKeypair(seed: Uint8Array): ElGamalKeypair;
+/**
+ * Encrypt a value using twisted ElGamal
+ */
+declare function encrypt(publicKey: Uint8Array, value: bigint): {
+    ciphertext: ElGamalCiphertext;
+    randomness: Uint8Array;
+};
+/**
+ * Decrypt an ElGamal ciphertext (brute force for small values)
+ */
+declare function decrypt(secretKey: Uint8Array, ciphertext: ElGamalCiphertext, maxValue?: number): bigint | null;
+/**
+ * Add two ElGamal ciphertexts (homomorphic addition)
+ */
+declare function addCiphertexts(ct1: ElGamalCiphertext, ct2: ElGamalCiphertext): ElGamalCiphertext;
+/**
+ * Subtract two ElGamal ciphertexts (homomorphic subtraction)
+ */
+declare function subtractCiphertexts(ct1: ElGamalCiphertext, ct2: ElGamalCiphertext): ElGamalCiphertext;
+/**
+ * Generate range proof for encrypted amount
+ */
+declare function generateRangeProof(value: bigint, commitment: PedersenCommitment, randomness: Uint8Array): Promise<RangeProof>;
+/**
+ * Generate validity proof for ciphertext
+ */
+declare function generateValidityProof(publicKey: Uint8Array, ciphertext: ElGamalCiphertext, randomness: Uint8Array): Promise<ValidityProof>;
+/**
+ * Generate equality proof for transfer
+ */
+declare function generateEqualityProof(sourceCiphertext: ElGamalCiphertext, destCiphertext: ElGamalCiphertext, transferAmount: bigint, sourceRandomness: Uint8Array, destRandomness: Uint8Array): Promise<EqualityProof>;
+/**
+ * Generate complete transfer proof
+ */
+declare function generateTransferProof(sourceBalance: bigint, transferAmount: bigint, sourceKeypair: ElGamalKeypair, destPubkey: Uint8Array, _auditorPubkey?: Uint8Array): Promise<TransferProof>;
+/**
+ * Generate withdraw proof
+ */
+declare function generateWithdrawProof(balance: bigint, keypair: ElGamalKeypair, ciphertext: ElGamalCiphertext): Promise<WithdrawProof>;
+/**
+ * Convert ElGamal public key to Solana address format
+ */
+declare function elGamalPubkeyToAddress(pubkey: Uint8Array): Promise<Address>;
+/**
+ * Load WASM module for performance optimization
+ */
+declare function loadWasmModule$1(): Promise<void>;
+declare const _default$2: {
+    generateKeypair: typeof generateKeypair;
+    deriveKeypair: typeof deriveKeypair;
+    encrypt: typeof encrypt;
+    decrypt: typeof decrypt;
+    addCiphertexts: typeof addCiphertexts;
+    subtractCiphertexts: typeof subtractCiphertexts;
+    generateRangeProof: typeof generateRangeProof;
+    generateValidityProof: typeof generateValidityProof;
+    generateEqualityProof: typeof generateEqualityProof;
+    generateTransferProof: typeof generateTransferProof;
+    generateWithdrawProof: typeof generateWithdrawProof;
+    elGamalPubkeyToAddress: typeof elGamalPubkeyToAddress;
+    loadWasmModule: typeof loadWasmModule$1;
+    PROOF_SIZES: {
+        readonly RANGE_PROOF: 674;
+        readonly VALIDITY_PROOF: 160;
+        readonly EQUALITY_PROOF: 192;
+        readonly WITHDRAW_PROOF: 80;
+        readonly ZERO_BALANCE_PROOF: 96;
+        readonly FEE_SIGMA_PROOF: 256;
+        readonly PUBKEY_VALIDITY_PROOF: 64;
+    };
+};
+
+type elgamal_DecryptHandle = DecryptHandle;
+type elgamal_ElGamalCiphertext = ElGamalCiphertext;
+type elgamal_ElGamalKeypair = ElGamalKeypair;
+type elgamal_EqualityProof = EqualityProof;
+declare const elgamal_PROOF_SIZES: typeof PROOF_SIZES;
+type elgamal_PedersenCommitment = PedersenCommitment;
+type elgamal_RangeProof = RangeProof;
+type elgamal_TransferProof = TransferProof;
+type elgamal_ValidityProof = ValidityProof;
+type elgamal_WithdrawProof = WithdrawProof;
+declare const elgamal_addCiphertexts: typeof addCiphertexts;
+declare const elgamal_decrypt: typeof decrypt;
+declare const elgamal_deriveKeypair: typeof deriveKeypair;
+declare const elgamal_elGamalPubkeyToAddress: typeof elGamalPubkeyToAddress;
+declare const elgamal_encrypt: typeof encrypt;
+declare const elgamal_generateEqualityProof: typeof generateEqualityProof;
+declare const elgamal_generateKeypair: typeof generateKeypair;
+declare const elgamal_generateRangeProof: typeof generateRangeProof;
+declare const elgamal_generateTransferProof: typeof generateTransferProof;
+declare const elgamal_generateValidityProof: typeof generateValidityProof;
+declare const elgamal_generateWithdrawProof: typeof generateWithdrawProof;
+declare const elgamal_subtractCiphertexts: typeof subtractCiphertexts;
+declare namespace elgamal {
+  export { type elgamal_DecryptHandle as DecryptHandle, type elgamal_ElGamalCiphertext as ElGamalCiphertext, type elgamal_ElGamalKeypair as ElGamalKeypair, type elgamal_EqualityProof as EqualityProof, elgamal_PROOF_SIZES as PROOF_SIZES, type elgamal_PedersenCommitment as PedersenCommitment, type elgamal_RangeProof as RangeProof, type elgamal_TransferProof as TransferProof, type elgamal_ValidityProof as ValidityProof, type elgamal_WithdrawProof as WithdrawProof, elgamal_addCiphertexts as addCiphertexts, elgamal_decrypt as decrypt, _default$2 as default, elgamal_deriveKeypair as deriveKeypair, elgamal_elGamalPubkeyToAddress as elGamalPubkeyToAddress, elgamal_encrypt as encrypt, elgamal_generateEqualityProof as generateEqualityProof, elgamal_generateKeypair as generateKeypair, elgamal_generateRangeProof as generateRangeProof, elgamal_generateTransferProof as generateTransferProof, elgamal_generateValidityProof as generateValidityProof, elgamal_generateWithdrawProof as generateWithdrawProof, loadWasmModule$1 as loadWasmModule, elgamal_subtractCiphertexts as subtractCiphertexts };
+}
+
+/**
+ * Zero-Knowledge Proof Module
+ *
+ * Handles all ZK proof generation and verification for the GhostSpeak protocol,
+ * including integration with Solana's ZK ElGamal Proof Program.
+ */
+
+declare const ZK_ELGAMAL_PROOF_PROGRAM_ID: Address<"ZkE1Gama1Proof11111111111111111111111111111">;
+declare const ProofInstructions: {
+    readonly VERIFY_RANGE_PROOF: 0;
+    readonly VERIFY_VALIDITY_PROOF: 1;
+    readonly VERIFY_EQUALITY_PROOF: 2;
+    readonly VERIFY_WITHDRAW_PROOF: 3;
+    readonly VERIFY_ZERO_BALANCE_PROOF: 4;
+    readonly VERIFY_FEE_SIGMA_PROOF: 5;
+    readonly VERIFY_PUBKEY_VALIDITY_PROOF: 6;
+    readonly VERIFY_TRANSFER_PROOF: 7;
+    readonly VERIFY_TRANSFER_WITH_FEE_PROOF: 8;
+};
+/**
+ * Create instruction to verify range proof
+ */
+declare function createVerifyRangeProofInstruction(proofAccount: Address, rangeProof: RangeProof): IInstruction;
+/**
+ * Create instruction to verify validity proof
+ */
+declare function createVerifyValidityProofInstruction(proofAccount: Address, validityProof: ValidityProof): IInstruction;
+/**
+ * Create instruction to verify equality proof
+ */
+declare function createVerifyEqualityProofInstruction(proofAccount: Address, equalityProof: EqualityProof): IInstruction;
+/**
+ * Create instruction to verify withdraw proof
+ */
+declare function createVerifyWithdrawProofInstruction(proofAccount: Address, withdrawProof: WithdrawProof): IInstruction;
+/**
+ * Create instruction to verify complete transfer proof
+ */
+declare function createVerifyTransferProofInstruction(proofAccount: Address, rangeProof: RangeProof, validityProof: ValidityProof, equalityProof: EqualityProof): IInstruction;
+/**
+ * Create proof context account for storing proof verification state
+ */
+interface ProofContext {
+    authority: Address;
+    proofType: keyof typeof ProofInstructions;
+    verified: boolean;
+    timestamp: bigint;
+}
+/**
+ * Derive proof context PDA
+ */
+declare function deriveProofContextPda(authority: Address, nonce: number): Address;
+/**
+ * Create instructions for batch proof verification
+ */
+declare function createBatchVerifyProofInstructions(proofs: {
+    type: 'range' | 'validity' | 'equality' | 'withdraw';
+    proof: RangeProof | ValidityProof | EqualityProof | WithdrawProof;
+    account: Address;
+}[]): IInstruction[];
+/**
+ * Calculate proof verification cost
+ */
+declare function calculateProofVerificationCost(proofType: keyof typeof ProofInstructions): bigint;
+/**
+ * Estimate total transaction cost including proof verification
+ */
+declare function estimateProofTransactionCost(baseComputeUnits: bigint, proofTypes: (keyof typeof ProofInstructions)[]): bigint;
+declare const _default$1: {
+    ZK_ELGAMAL_PROOF_PROGRAM_ID: Address<"ZkE1Gama1Proof11111111111111111111111111111">;
+    ProofInstructions: {
+        readonly VERIFY_RANGE_PROOF: 0;
+        readonly VERIFY_VALIDITY_PROOF: 1;
+        readonly VERIFY_EQUALITY_PROOF: 2;
+        readonly VERIFY_WITHDRAW_PROOF: 3;
+        readonly VERIFY_ZERO_BALANCE_PROOF: 4;
+        readonly VERIFY_FEE_SIGMA_PROOF: 5;
+        readonly VERIFY_PUBKEY_VALIDITY_PROOF: 6;
+        readonly VERIFY_TRANSFER_PROOF: 7;
+        readonly VERIFY_TRANSFER_WITH_FEE_PROOF: 8;
+    };
+    createVerifyRangeProofInstruction: typeof createVerifyRangeProofInstruction;
+    createVerifyValidityProofInstruction: typeof createVerifyValidityProofInstruction;
+    createVerifyEqualityProofInstruction: typeof createVerifyEqualityProofInstruction;
+    createVerifyWithdrawProofInstruction: typeof createVerifyWithdrawProofInstruction;
+    createVerifyTransferProofInstruction: typeof createVerifyTransferProofInstruction;
+    createBatchVerifyProofInstructions: typeof createBatchVerifyProofInstructions;
+    deriveProofContextPda: typeof deriveProofContextPda;
+    calculateProofVerificationCost: typeof calculateProofVerificationCost;
+    estimateProofTransactionCost: typeof estimateProofTransactionCost;
+};
+
+type zkProofs_ProofContext = ProofContext;
+declare const zkProofs_ProofInstructions: typeof ProofInstructions;
+declare const zkProofs_ZK_ELGAMAL_PROOF_PROGRAM_ID: typeof ZK_ELGAMAL_PROOF_PROGRAM_ID;
+declare const zkProofs_calculateProofVerificationCost: typeof calculateProofVerificationCost;
+declare const zkProofs_createBatchVerifyProofInstructions: typeof createBatchVerifyProofInstructions;
+declare const zkProofs_createVerifyEqualityProofInstruction: typeof createVerifyEqualityProofInstruction;
+declare const zkProofs_createVerifyRangeProofInstruction: typeof createVerifyRangeProofInstruction;
+declare const zkProofs_createVerifyTransferProofInstruction: typeof createVerifyTransferProofInstruction;
+declare const zkProofs_createVerifyValidityProofInstruction: typeof createVerifyValidityProofInstruction;
+declare const zkProofs_createVerifyWithdrawProofInstruction: typeof createVerifyWithdrawProofInstruction;
+declare const zkProofs_deriveProofContextPda: typeof deriveProofContextPda;
+declare const zkProofs_estimateProofTransactionCost: typeof estimateProofTransactionCost;
+declare namespace zkProofs {
+  export { type zkProofs_ProofContext as ProofContext, zkProofs_ProofInstructions as ProofInstructions, zkProofs_ZK_ELGAMAL_PROOF_PROGRAM_ID as ZK_ELGAMAL_PROOF_PROGRAM_ID, zkProofs_calculateProofVerificationCost as calculateProofVerificationCost, zkProofs_createBatchVerifyProofInstructions as createBatchVerifyProofInstructions, zkProofs_createVerifyEqualityProofInstruction as createVerifyEqualityProofInstruction, zkProofs_createVerifyRangeProofInstruction as createVerifyRangeProofInstruction, zkProofs_createVerifyTransferProofInstruction as createVerifyTransferProofInstruction, zkProofs_createVerifyValidityProofInstruction as createVerifyValidityProofInstruction, zkProofs_createVerifyWithdrawProofInstruction as createVerifyWithdrawProofInstruction, _default$1 as default, zkProofs_deriveProofContextPda as deriveProofContextPda, zkProofs_estimateProofTransactionCost as estimateProofTransactionCost };
+}
+
+/**
+ * WASM Bridge for Cryptographic Operations
+ *
+ * Optional performance optimization layer that loads WASM modules
+ * for compute-intensive cryptographic operations.
+ */
+interface WasmModule {
+    generate_range_proof: (value: string, commitment: Uint8Array, randomness: Uint8Array) => Promise<Uint8Array>;
+    generate_validity_proof: (publicKey: Uint8Array, commitment: Uint8Array, handle: Uint8Array, randomness: Uint8Array) => Promise<Uint8Array>;
+    generate_equality_proof: (sourceCommitment: Uint8Array, destCommitment: Uint8Array, amount: string, sourceRandomness: Uint8Array, destRandomness: Uint8Array) => Promise<Uint8Array>;
+    generate_withdraw_proof: (balance: string, secretKey: Uint8Array, commitment: Uint8Array, handle: Uint8Array) => Promise<Uint8Array>;
+    scalar_multiply: (point: Uint8Array, scalar: Uint8Array) => Uint8Array;
+    point_add: (point1: Uint8Array, point2: Uint8Array) => Uint8Array;
+    point_subtract: (point1: Uint8Array, point2: Uint8Array) => Uint8Array;
+}
+/**
+ * Load WASM module for cryptographic operations
+ */
+declare function loadWasmModule(): Promise<void>;
+/**
+ * Check if WASM module is available
+ */
+declare function isWasmAvailable(): boolean;
+/**
+ * Get WASM module instance
+ */
+declare function getWasmModule(): WasmModule | null;
+/**
+ * Benchmark WASM vs JavaScript performance
+ */
+declare function benchmarkWasm(): Promise<{
+    wasmTime: number;
+    jsTime: number;
+    speedup: number;
+} | null>;
+/**
+ * Create a function that falls back to JS if WASM fails
+ */
+declare function createWasmFallback<T extends (...args: unknown[]) => unknown>(wasmFn: T | undefined, jsFallback: T): T;
+declare const _default: {
+    loadWasmModule: typeof loadWasmModule;
+    isWasmAvailable: typeof isWasmAvailable;
+    getWasmModule: typeof getWasmModule;
+    benchmarkWasm: typeof benchmarkWasm;
+    createWasmFallback: typeof createWasmFallback;
+};
+
+type wasmBridge_WasmModule = WasmModule;
+declare const wasmBridge_benchmarkWasm: typeof benchmarkWasm;
+declare const wasmBridge_createWasmFallback: typeof createWasmFallback;
+declare const wasmBridge_getWasmModule: typeof getWasmModule;
+declare const wasmBridge_isWasmAvailable: typeof isWasmAvailable;
+declare const wasmBridge_loadWasmModule: typeof loadWasmModule;
+declare namespace wasmBridge {
+  export { type wasmBridge_WasmModule as WasmModule, wasmBridge_benchmarkWasm as benchmarkWasm, wasmBridge_createWasmFallback as createWasmFallback, _default as default, wasmBridge_getWasmModule as getWasmModule, wasmBridge_isWasmAvailable as isWasmAvailable, wasmBridge_loadWasmModule as loadWasmModule };
+}
+
+export { type ElGamalCiphertext, type ElGamalKeypair, type ProofContext, type TransferProof, type WasmModule, type WithdrawProof, ZK_ELGAMAL_PROOF_PROGRAM_ID, createVerifyRangeProofInstruction, createVerifyTransferProofInstruction, decrypt, elgamal, encrypt, generateKeypair, generateTransferProof, generateWithdrawProof, isWasmAvailable, loadWasmModule, wasmBridge, zkProofs };

package/dist/errors.d.ts

@@ -0,0 +1,119 @@
+import { Address } from '@solana/addresses';
+import { ErrorCode, SDKError } from './types.js';
+
+/**
+ * Smart Error System with Actionable Solutions
+ *
+ * Every error includes context and suggested solutions to help developers
+ * quickly resolve issues.
+ */
+
+/**
+ * Base GhostSpeak error class
+ */
+declare class GhostSpeakError extends Error {
+    readonly code: ErrorCode;
+    readonly context: Record<string, unknown>;
+    readonly solution?: string;
+    readonly instruction?: string;
+    constructor(code: ErrorCode, message: string, context?: Record<string, unknown>, solution?: string, instruction?: string);
+    /**
+     * Format error for display
+     */
+    toString(): string;
+    /**
+     * Convert to SDK error type
+     */
+    toSDKError(): SDKError;
+}
+/**
+ * Network-related errors
+ */
+declare class NetworkError extends GhostSpeakError {
+    constructor(endpoint: string, originalError?: Error);
+}
+/**
+ * Insufficient balance error
+ */
+declare class InsufficientBalanceError extends GhostSpeakError {
+    constructor(required: bigint, available: bigint, address: Address);
+}
+/**
+ * Account not found error
+ */
+declare class AccountNotFoundError extends GhostSpeakError {
+    constructor(address: Address, accountType: string);
+}
+/**
+ * Invalid input error
+ */
+declare class InvalidInputError extends GhostSpeakError {
+    constructor(field: string, value: unknown, requirement: string);
+}
+/**
+ * Transaction failed error
+ */
+declare class TransactionFailedError extends GhostSpeakError {
+    constructor(signature: string, logs: string[], programError?: string);
+    private static getSolution;
+}
+/**
+ * Simulation failed error
+ */
+declare class SimulationFailedError extends GhostSpeakError {
+    constructor(logs: string[], unitsConsumed?: bigint);
+}
+/**
+ * Timeout error
+ */
+declare class TimeoutError extends GhostSpeakError {
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Error factory for creating specific errors
+ */
+declare class ErrorFactory {
+    /**
+     * Create error from program logs
+     */
+    static fromProgramLogs(logs: string[], signature?: string): GhostSpeakError;
+    /**
+     * Create error from RPC error
+     */
+    static fromRpcError(error: unknown, endpoint: string): GhostSpeakError;
+}
+/**
+ * Global error handler for consistent error handling
+ */
+declare class ErrorHandler {
+    private static handlers;
+    /**
+     * Register error handler
+     */
+    static on(code: ErrorCode, handler: (error: GhostSpeakError) => void): void;
+    /**
+     * Handle error
+     */
+    static handle(error: unknown): SDKError;
+}
+/**
+ * Validation error for invalid inputs
+ */
+declare class ValidationError extends GhostSpeakError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+declare const _default: {
+    GhostSpeakError: typeof GhostSpeakError;
+    NetworkError: typeof NetworkError;
+    InsufficientBalanceError: typeof InsufficientBalanceError;
+    AccountNotFoundError: typeof AccountNotFoundError;
+    InvalidInputError: typeof InvalidInputError;
+    TransactionFailedError: typeof TransactionFailedError;
+    SimulationFailedError: typeof SimulationFailedError;
+    TimeoutError: typeof TimeoutError;
+    ValidationError: typeof ValidationError;
+    ErrorFactory: typeof ErrorFactory;
+    ErrorHandler: typeof ErrorHandler;
+};
+
+export { AccountNotFoundError, ErrorFactory, ErrorHandler, GhostSpeakError, InsufficientBalanceError, InvalidInputError, NetworkError, SimulationFailedError, TimeoutError, TransactionFailedError, ValidationError, _default as default };