@adelos/sdk 0.1.2 → 0.1.3

package/dist/index.d.mts

@@ -1,90 +1,44 @@
 import { PublicKey, Connection, TransactionInstruction, Transaction, VersionedTransaction } from '@solana/web3.js';
-
-/** Supported Solana clusters */
-type SolanaCluster = "devnet" | "mainnet-beta" | "localnet";
-/** Program IDs for Adelos Registry per cluster */
-declare const PROGRAM_IDS: Record<SolanaCluster, PublicKey>;
-/** RPC URLs per cluster */
-declare const RPC_URLS: Record<SolanaCluster, string>;
-/** Default Program ID (Devnet) */
-declare const PROGRAM_ID: PublicKey;
-/** Memo Program ID for stealth address scanning */
-declare const MEMO_PROGRAM_ID: PublicKey;
-/** Seed prefix for registry PDA derivation */
-declare const REGISTRY_SEED = "registry";
-/** Size of the registry account in bytes */
-declare const REGISTRY_ACCOUNT_SIZE: number;
-/** Adelos Protocol version prefix for memos */
-declare const MEMO_PREFIX = "ADLSv1:";
-/** Stealth address derivation domain separator */
-declare const STEALTH_DOMAIN = "adelos:stealth:v1";
+import * as ed from '@noble/ed25519';
 
 /** Represents a registry account data */
 interface RegistryAccount {
-    /** Owner's wallet public key */
     owner: PublicKey;
-    /** Meta public key (encryption key, 32 bytes) */
     metaPubkey: Uint8Array;
-    /** PDA bump seed */
     bump: number;
 }
-/**
- * Options for initializing the Adelos SDK
- *
- * @example
- * // Simple usage - just specify cluster
- * const sdk = new AdelosSDK({ cluster: "devnet" });
- *
- * // Custom RPC (e.g., QuickNode, Helius)
- * const sdk = new AdelosSDK({
- *   cluster: "devnet",
- *   rpcUrl: "https://my-quicknode-endpoint.com"
- * });
- */
+/** Options for initializing the Adelos SDK */
 interface AdelosOptions {
-    /** Solana cluster (devnet, mainnet-beta, or localnet) */
-    cluster?: SolanaCluster;
-    /** Custom RPC URL (optional - overrides cluster default) */
+    /** Custom RPC URL (optional - uses devnet default if not set) */
     rpcUrl?: string;
     /** Helius API key for indexer webhooks (optional) */
     heliusApiKey?: string;
 }
 /** Result of a registry lookup */
 interface RegistryInfo {
-    /** PDA address of the registry */
     address: PublicKey;
-    /** Registry account data */
     account: RegistryAccount;
-    /** Whether the registry exists */
     exists: boolean;
 }
-/** Transaction result */
-interface TransactionResult {
-    /** Transaction signature */
-    signature: string;
-    /** Registry PDA address */
-    registryAddress: PublicKey;
-}
-/** Stealth transfer info for sender */
-interface StealthTransferInfo {
-    /** Derived stealth address */
-    stealthPubkey: Uint8Array;
-    /** Ephemeral keypair used for derivation */
-    ephemeralKeypair: {
-        secretKey: Uint8Array;
-        publicKey: Uint8Array;
-    };
-    /** Shared secret (for debugging, don't expose in production) */
-    sharedSecret: Uint8Array;
-    /** Memo to include in transaction */
-    memo: string;
-}
+
+type SolanaCluster = "devnet";
+declare const ADELOS_CONFIG: {
+    readonly PROGRAM_ID: PublicKey;
+    readonly RPC_URL: string;
+    readonly MEMO_PROGRAM_ID: PublicKey;
+    readonly REGISTRY_SEED: "registry";
+    readonly MEMO_PREFIX: "ADLSv1:";
+    readonly STEALTH_DOMAIN: "adelos:stealth:v1";
+};
+declare const PROGRAM_ID: PublicKey;
+declare const RPC_URL: string;
+declare const MEMO_PROGRAM_ID: PublicKey;
+declare const REGISTRY_SEED: "registry";
+declare const MEMO_PREFIX: "ADLSv1:";
+declare const STEALTH_DOMAIN: "adelos:stealth:v1";
 
 /**
  * Derives the registry PDA for a given owner
- * @param owner - The owner's wallet public key
- * @param programId - Optional custom program ID
- * @returns Tuple of [PDA address, bump seed]
  */
 declare function deriveRegistryPda(owner: PublicKey, programId?: PublicKey): [PublicKey, number];
 /**
@@ -238,461 +192,79 @@ type AdelosIDL = typeof IDL;
 
 /**
  * Adelos Cryptography Module
- *
  * Implements Single-Key Stealth Address (SKSA) using Ed25519 curve operations.
- *
- * Flow:
- * 1. Sender gets recipient's meta_pubkey from registry
- * 2. Sender generates ephemeral keypair
- * 3. ECDH: shared_secret = ephemeral_sk * meta_pubkey
- * 4. Stealth pubkey = meta_pubkey + hash_to_scalar(shared_secret) * G
- * 5. Recipient can recover stealth_sk = meta_sk + hash_to_scalar(shared_secret)
- */
-/**
- * Generates an ephemeral keypair for stealth address derivation
- * @returns Object with secretKey (32 bytes) and publicKey (32 bytes)
  */
+
 declare function generateEphemeralKeypair(): {
-    secretKey: Uint8Array;
-    publicKey: Uint8Array;
+    secretKey: ed.Bytes;
+    publicKey: ed.Bytes;
 };
-/**
- * Computes ECDH shared secret between ephemeral secret key and recipient's meta pubkey
- * @param ephemeralSk - Ephemeral secret key (32 bytes)
- * @param recipientMetaPubkey - Recipient's meta public key (32 bytes)
- * @returns Shared secret (32 bytes)
- */
-declare function computeSharedSecret(ephemeralSk: Uint8Array, recipientMetaPubkey: Uint8Array): Promise<Uint8Array>;
-/**
- * Derives a stealth public key from meta pubkey and shared secret
- *
- * stealth_pubkey = meta_pubkey + hash_to_scalar(shared_secret) * G
- *
- * @param metaPubkey - Recipient's meta public key (32 bytes)
- * @param sharedSecret - ECDH shared secret (32 bytes)
- * @returns Stealth public key (32 bytes)
- */
-declare function deriveStealthPubkey(metaPubkey: Uint8Array, sharedSecret: Uint8Array): Uint8Array;
-/**
- * Recovers the stealth secret key (for recipient)
- *
- * stealth_sk = meta_sk + hash_to_scalar(shared_secret)
- *
- * @param metaSk - Recipient's meta secret key (32 bytes)
- * @param sharedSecret - ECDH shared secret (32 bytes)
- * @returns Stealth secret key (32 bytes)
- */
+declare function computeSharedSecret(ephemeralSk: Uint8Array, recipientMetaPk: Uint8Array): Uint8Array;
+declare function computeSharedSecretAsRecipient(metaSk: Uint8Array, ephemeralPk: Uint8Array): Uint8Array;
+declare function deriveStealthPubkey(metaPk: Uint8Array, sharedSecret: Uint8Array): Uint8Array;
 declare function recoverStealthSecretKey(metaSk: Uint8Array, sharedSecret: Uint8Array): Uint8Array;
-/**
- * Computes shared secret from recipient's perspective
- * (using meta secret key and sender's ephemeral pubkey)
- *
- * @param metaSk - Recipient's meta secret key (32 bytes)
- * @param ephemeralPubkey - Sender's ephemeral public key (32 bytes)
- * @returns Shared secret (32 bytes)
- */
-declare function computeSharedSecretAsRecipient(metaSk: Uint8Array, ephemeralPubkey: Uint8Array): Promise<Uint8Array>;
-/**
- * Generates memo string for stealth transfer
- * Format: ADLSv1:[ephemeral_pubkey_hex]
- *
- * @param ephemeralPubkey - Ephemeral public key (32 bytes)
- * @returns Memo string
- */
 declare function generateStealthMemo(ephemeralPubkey: Uint8Array): string;
-/**
- * Parses a stealth transfer memo
- *
- * @param memo - Memo string
- * @returns Ephemeral public key or null if invalid
- */
 declare function parseStealthMemo(memo: string): Uint8Array | null;
-/**
- * Full stealth address generation flow (for sender)
- *
- * @param recipientMetaPubkey - Recipient's meta public key from registry
- * @returns Object with stealthPubkey, ephemeralPubkey, and memo
- */
-declare function generateStealthAddress(recipientMetaPubkey: Uint8Array): Promise<{
-    stealthPubkey: Uint8Array;
+declare function generateStealthAddress(recipientMetaPk: Uint8Array): {
+    stealthPubkey: Uint8Array<ArrayBufferLike>;
     ephemeralKeypair: {
-        secretKey: Uint8Array;
-        publicKey: Uint8Array;
+        secretKey: ed.Bytes;
+        publicKey: ed.Bytes;
     };
-    sharedSecret: Uint8Array;
+    sharedSecret: Uint8Array<ArrayBufferLike>;
     memo: string;
-}>;
-/**
- * Checks if a transaction is for this recipient (for scanning)
- *
- * @param metaSk - Recipient's meta secret key
- * @param metaPubkey - Recipient's meta public key
- * @param ephemeralPubkey - Ephemeral pubkey from memo
- * @param targetAddress - The address that received funds
- * @returns True if this transaction is for the recipient
- */
-declare function isStealthTransactionForMe(metaSk: Uint8Array, metaPubkey: Uint8Array, ephemeralPubkey: Uint8Array, targetAddress: Uint8Array): Promise<boolean>;
-
-/**
- * Adelos Light Protocol Integration
- *
- * Provides ZK-Compression for confidential transfers using Light Protocol.
- * Compressed tokens are stored in Merkle trees instead of regular accounts,
- * providing significant cost savings and enhanced privacy.
- */
-
-/** Light Protocol program IDs */
-declare const LIGHT_PROGRAM_IDS: {
-    LIGHT_SYSTEM_PROGRAM: PublicKey;
-    COMPRESSED_TOKEN_PROGRAM: PublicKey;
-    ACCOUNT_COMPRESSION_PROGRAM: PublicKey;
 };
-/** Configuration for Light Protocol RPC */
-interface LightConfig {
-    /** Light Protocol RPC endpoint */
-    rpcUrl: string;
-    /** Compression public key (for tree) */
-    compressionPubkey?: PublicKey;
-}
-/** Compressed account info */
-interface CompressedAccount {
-    /** Account hash */
-    hash: string;
-    /** Owner public key */
-    owner: PublicKey;
-    /** Lamports in account */
-    lamports: number;
-    /** Account data */
-    data: Uint8Array;
-    /** Merkle tree address */
-    tree: PublicKey;
-    /** Leaf index in tree */
-    leafIndex: number;
-}
-/** Compressed token balance */
-interface CompressedTokenBalance {
-    /** Token mint */
-    mint: PublicKey;
-    /** Balance amount */
-    amount: bigint;
-    /** Source accounts */
-    accounts: CompressedAccount[];
-}
-/**
- * Light Protocol client for ZK-Compression operations
- */
-declare class LightClient {
-    private connection;
-    private config;
-    constructor(connection: Connection, config: LightConfig);
-    /**
-     * Creates a new Light Protocol client
-     *
-     * @param rpcUrl - Solana RPC URL with Light Protocol support
-     * @returns LightClient instance
-     */
-    static create(rpcUrl: string): LightClient;
-    /**
-     * Gets compressed SOL balance for an address
-     *
-     * @param owner - Owner public key
-     * @returns Compressed SOL balance in lamports
-     */
-    getCompressedSolBalance(owner: PublicKey): Promise<bigint>;
-    /**
-     * Gets compressed token balances for an address
-     *
-     * @param owner - Owner public key
-     * @param mint - Optional token mint to filter
-     * @returns Array of compressed token balances
-     */
-    getCompressedTokenBalances(owner: PublicKey, mint?: PublicKey): Promise<CompressedTokenBalance[]>;
-    /**
-     * Creates a compressed SOL transfer instruction
-     *
-     * Note: This creates the instruction data structure.
-     * Actual ZK proof generation requires Light Protocol SDK.
-     *
-     * @param from - Sender public key
-     * @param to - Recipient public key (can be stealth address)
-     * @param amount - Amount in lamports
-     * @returns Transaction instruction (placeholder)
-     */
-    createCompressedTransferInstruction(from: PublicKey, to: PublicKey, amount: bigint): TransactionInstruction;
-    /**
-     * Compresses SOL from regular account to compressed account
-     *
-     * @param owner - Owner public key
-     * @param amount - Amount in lamports to compress
-     * @returns Transaction (unsigned)
-     */
-    createCompressSolTransaction(owner: PublicKey, amount: bigint): Promise<Transaction>;
-    /**
-     * Decompresses SOL from compressed account to regular account
-     *
-     * @param owner - Owner public key
-     * @param amount - Amount in lamports to decompress
-     * @returns Transaction (unsigned)
-     */
-    createDecompressSolTransaction(owner: PublicKey, amount: bigint): Promise<Transaction>;
-    /**
-     * Creates a stealth compressed transfer
-     * Combines stealth addressing with ZK-compression
-     *
-     * @param from - Sender public key
-     * @param stealthPubkey - Derived stealth address for recipient
-     * @param amount - Amount in lamports
-     * @param memo - Stealth memo containing ephemeral pubkey
-     * @returns Transaction (unsigned)
-     */
-    createStealthCompressedTransfer(from: PublicKey, stealthPubkey: Uint8Array, amount: bigint, memo: string): Promise<Transaction>;
-}
-/**
- * Creates a Light Protocol client for ZK-compression operations
- *
- * @param rpcUrl - RPC URL with Light Protocol support
- * @returns LightClient instance
- */
-declare function createLightClient(rpcUrl: string): LightClient;
 
 /**
- * Adelos Indexer Module
- *
- * Provides transaction scanning for stealth transfers.
- * Supports:
- * 1. Helius Webhook integration for real-time notifications
- * 2. Manual RPC scanning for historical transactions
+ * Adelos Indexer - Privacy-Preserving Transaction Scanner
  */
 
-/** Stealth transaction detected by indexer */
 interface StealthTransaction {
-    /** Transaction signature */
     signature: string;
-    /** Block time (unix timestamp) */
     blockTime: number | null;
-    /** Slot number */
-    slot: number;
-    /** Sender's wallet (if detectable) */
-    sender: PublicKey | null;
-    /** Stealth address that received funds */
     stealthAddress: PublicKey;
-    /** Amount transferred (lamports) */
     amount: bigint;
-    /** Ephemeral public key from memo */
-    ephemeralPubkey: Uint8Array;
-    /** Whether this is for the current user */
-    isForMe: boolean;
-    /** Recovered stealth secret key (if isForMe) */
-    stealthSecretKey?: Uint8Array;
 }
-/** Helius webhook payload */
-interface HeliusWebhookPayload {
-    type: string;
-    signature: string;
-    slot: number;
-    timestamp: number;
-    accountData: Array<{
-        account: string;
-        nativeBalanceChange: number;
-        tokenBalanceChanges: Array<{
-            mint: string;
-            rawTokenAmount: {
-                tokenAmount: string;
-            };
-        }>;
-    }>;
-    instructions: Array<{
-        programId: string;
-        data: string;
-        accounts: string[];
-    }>;
-}
-/** Indexer configuration */
 interface IndexerConfig {
-    /** Solana RPC URL */
     rpcUrl: string;
-    /** Helius API key (optional, for webhooks) */
     heliusApiKey?: string;
-    /** Scan interval in ms (for polling mode) */
-    scanInterval?: number;
 }
-/**
- * Adelos Indexer for scanning stealth transfers
- */
 declare class AdelosIndexer {
     private connection;
-    private config;
-    private isScanning;
-    private scanIntervalId;
-    /** Callback for when a stealth transaction is detected */
-    onTransaction?: (tx: StealthTransaction) => void;
+    private heliusApiKey?;
     constructor(config: IndexerConfig);
-    /**
-     * Creates an indexer instance
-     */
     static create(config: IndexerConfig): AdelosIndexer;
-    /**
-     * Scans recent transactions for stealth transfers to a recipient
-     *
-     * IMPORTANT: We scan the Memo Program, NOT the metaPubkey!
-     * The metaPubkey should never appear in transactions - that's the whole point of stealth addresses.
-     * We scan memo program for ADLSv1: prefix, then use Trial Decryption to check if it's for us.
-     *
-     * @param metaSk - Recipient's meta secret key
-     * @param metaPubkey - Recipient's meta public key
-     * @param limit - Number of transactions to scan
-     * @returns Array of stealth transactions for this recipient
-     */
-    scanForStealthTransfers(metaSk: Uint8Array, metaPubkey: Uint8Array, limit?: number): Promise<StealthTransaction[]>;
-    /**
-     * Scans all transactions with ADLSv1 memo prefix
-     *
-     * @param metaSk - Recipient's meta secret key
-     * @param metaPubkey - Recipient's meta public key
-     * @param since - Scan transactions after this signature
-     * @returns Array of stealth transactions
-     */
-    scanByMemoPrefix(metaSk: Uint8Array, metaPubkey: Uint8Array, since?: string): Promise<StealthTransaction[]>;
-    /**
-     * Extracts memo from a parsed transaction
-     */
+    /** Scan for stealth transfers to this recipient */
+    scanForStealthTransfers(metaSk: Uint8Array, metaPk: Uint8Array, limit?: number): Promise<StealthTransaction[]>;
+    /** Trial Decryption: Check if transaction is for this recipient */
+    private attemptDecryption;
     private extractMemo;
-    /**
-     * Parses a transaction to extract stealth transfer info using Trial Decryption
-     *
-     * Trial Decryption: First compute expected stealth address, then find if it exists in tx accounts
-     */
-    private parseStealthTransaction;
-    /**
-     * Starts continuous scanning for stealth transfers
-     *
-     * @param metaSk - Recipient's meta secret key
-     * @param metaPubkey - Recipient's meta public key
-     */
-    startScanning(metaSk: Uint8Array, metaPubkey: Uint8Array): void;
-    /**
-     * Stops continuous scanning
-     */
-    stopScanning(): void;
-    /**
-     * Processes a Helius webhook payload
-     *
-     * @param payload - Webhook payload from Helius
-     * @param metaSk - Recipient's meta secret key
-     * @param metaPubkey - Recipient's meta public key
-     * @returns Stealth transaction if detected and for this recipient
-     */
-    processWebhook(payload: HeliusWebhookPayload, metaSk: Uint8Array, metaPubkey: Uint8Array): Promise<StealthTransaction | null>;
-    /**
-     * Sets up Helius webhook for real-time notifications
-     *
-     * @param webhookUrl - Your server's webhook endpoint
-     * @returns Webhook ID
-     */
-    setupHeliusWebhook(webhookUrl: string): Promise<string | null>;
 }
-/**
- * Creates an Adelos indexer instance
- */
 declare function createIndexer(config: IndexerConfig): AdelosIndexer;
 
 /**
- * Adelos SDK - Privacy Identity Registry on Solana
+ * Adelos SDK - Privacy Stealth Transfers on Solana (Devnet)
  *
  * @example
- * ```typescript
- * import { AdelosSDK } from "@adelos/sdk";
- *
- * // Simple usage with cluster
- * const sdk = new AdelosSDK({ cluster: "devnet" });
- *
- * // With custom RPC (QuickNode, Helius)
- * const sdk = new AdelosSDK({
- *   cluster: "devnet",
- *   rpcUrl: "https://my-quicknode-endpoint.com"
- * });
- *
- * // Register identity
- * const metaPubkey = new Uint8Array(32).fill(1);
- * const tx = await sdk.createRegisterTransactionV0(walletPubkey, metaPubkey);
- *
- * // Get registry
+ * const sdk = new AdelosSDK();
  * const registry = await sdk.getRegistry(ownerPubkey);
- * console.log(registry.account.metaPubkey);
- * ```
  */
 declare class AdelosSDK {
     readonly connection: Connection;
     readonly programId: PublicKey;
-    readonly cluster: SolanaCluster;
-    readonly heliusApiKey?: string;
     constructor(options?: AdelosOptions);
-    /**
-     * Derives the registry PDA for an owner
-     */
     deriveRegistryAddress(owner: PublicKey): [PublicKey, number];
-    /**
-     * Fetches a registry account by owner
-     */
     getRegistry(owner: PublicKey): Promise<RegistryInfo>;
-    /**
-     * Gets the meta pubkey for an owner
-     * @returns The meta pubkey as Uint8Array, or null if not registered
-     */
     getMetaPubkey(owner: PublicKey): Promise<Uint8Array | null>;
-    /**
-     * Gets the meta pubkey as hex string
-     */
-    getMetaPubkeyHex(owner: PublicKey): Promise<string | null>;
-    /**
-     * Checks if an owner has a registered identity
-     */
     isRegistered(owner: PublicKey): Promise<boolean>;
-    /**
-     * Creates a register identity instruction
-     */
     createRegisterInstruction(owner: PublicKey, metaPubkey: Uint8Array): TransactionInstruction;
-    /**
-     * Creates an update identity instruction
-     */
     createUpdateInstruction(owner: PublicKey, newMetaPubkey: Uint8Array): TransactionInstruction;
-    /**
-     * Creates a close registry instruction
-     */
     createCloseInstruction(owner: PublicKey): TransactionInstruction;
-    /**
-     * Creates a register transaction (unsigned) - Legacy format
-     */
+    buildTransaction(payer: PublicKey, instructions: TransactionInstruction[], version?: "legacy" | "v0"): Promise<Transaction | VersionedTransaction>;
     createRegisterTransaction(owner: PublicKey, metaPubkey: Uint8Array): Promise<Transaction>;
-    /**
-     * Creates a register transaction (unsigned) - Versioned format (v0)
-     * Recommended for modern Solana applications
-     */
     createRegisterTransactionV0(owner: PublicKey, metaPubkey: Uint8Array): Promise<VersionedTransaction>;
-    /**
-     * Creates an update transaction (unsigned) - Legacy format
-     */
-    createUpdateTransaction(owner: PublicKey, newMetaPubkey: Uint8Array): Promise<Transaction>;
-    /**
-     * Creates an update transaction (unsigned) - Versioned format (v0)
-     */
-    createUpdateTransactionV0(owner: PublicKey, newMetaPubkey: Uint8Array): Promise<VersionedTransaction>;
-    /**
-     * Creates a close transaction (unsigned) - Legacy format
-     */
-    createCloseTransaction(owner: PublicKey): Promise<Transaction>;
-    /**
-     * Creates a close transaction (unsigned) - Versioned format (v0)
-     */
-    createCloseTransactionV0(owner: PublicKey): Promise<VersionedTransaction>;
-    /**
-     * Sends a signed legacy transaction and confirms it
-     */
-    sendAndConfirm(signedTransaction: Transaction): Promise<string>;
-    /**
-     * Sends a signed versioned transaction and confirms it
-     */
-    sendAndConfirmV0(signedTransaction: VersionedTransaction): Promise<string>;
+    sendAndConfirm(signedTx: Transaction): Promise<string>;
+    sendAndConfirmV0(signedTx: VersionedTransaction): Promise<string>;
 }
 
-export { type AdelosIDL, AdelosIndexer, type AdelosOptions, AdelosSDK, type CompressedAccount, type CompressedTokenBalance, type HeliusWebhookPayload, IDL, type IndexerConfig, LIGHT_PROGRAM_IDS, LightClient, type LightConfig, MEMO_PREFIX, MEMO_PROGRAM_ID, PROGRAM_ID, PROGRAM_IDS, REGISTRY_ACCOUNT_SIZE, REGISTRY_SEED, RPC_URLS, type RegistryAccount, type RegistryInfo, STEALTH_DOMAIN, type SolanaCluster, type StealthTransaction, type StealthTransferInfo, type TransactionResult, bytesToHex, computeSharedSecret, computeSharedSecretAsRecipient, createIndexer, createLightClient, deriveRegistryPda, deriveStealthPubkey, generateEphemeralKeypair, generateStealthAddress, generateStealthMemo, getDiscriminator, hexToBytes, isStealthTransactionForMe, isValidMetaPubkey, parseStealthMemo, recoverStealthSecretKey };
+export { ADELOS_CONFIG, type AdelosIDL, AdelosIndexer, type AdelosOptions, AdelosSDK, IDL, type IndexerConfig, MEMO_PREFIX, MEMO_PROGRAM_ID, PROGRAM_ID, REGISTRY_SEED, RPC_URL, type RegistryAccount, type RegistryInfo, STEALTH_DOMAIN, type SolanaCluster, type StealthTransaction, bytesToHex, computeSharedSecret, computeSharedSecretAsRecipient, createIndexer, deriveRegistryPda, deriveStealthPubkey, generateEphemeralKeypair, generateStealthAddress, generateStealthMemo, getDiscriminator, hexToBytes, isValidMetaPubkey, parseStealthMemo, recoverStealthSecretKey };