@adelos/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,101 +1,129 @@
 # @adelos/sdk
 
-Adelos Protocol SDK - Privacy Identity Registry on Solana
+TypeScript SDK for Adelos Protocol - Privacy Stealth Transfers on Solana.
 
-## Installation
+## 📦 Installation
 
 ```bash
-npm install @adelos/sdk @solana/web3.js
+npm install @adelos/sdk
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ```typescript
-import { AdelosSDK } from "@adelos/sdk";
-import { Keypair, Connection } from "@solana/web3.js";
+import { AdelosSDK, generateStealthAddress } from "@adelos/sdk";
 
-// Initialize SDK
-const sdk = new AdelosSDK({
-  rpcUrl: "https://api.devnet.solana.com",
-});
+// Initialize with cluster
+const sdk = new AdelosSDK({ cluster: "devnet" });
 
-// Check if user is registered
-const isRegistered = await sdk.isRegistered(walletPubkey);
-
-// Get meta pubkey (encryption key)
-const metaPubkey = await sdk.getMetaPubkey(walletPubkey);
-console.log("Meta Pubkey:", metaPubkey);
+// Or with custom RPC (Helius, QuickNode)
+const sdk = new AdelosSDK({ 
+  cluster: "devnet",
+  rpcUrl: "https://your-rpc-endpoint.com",
+  heliusApiKey: "your-helius-api-key" // Optional, for webhooks
+});
 ```
 
-## API Reference
+## 📖 API Reference
 
-### `AdelosSDK`
+### AdelosSDK
 
-#### Constructor
+#### Constructor Options
 
 ```typescript
-const sdk = new AdelosSDK({
-  rpcUrl?: string,    // Default: "https://api.devnet.solana.com"
-  programId?: PublicKey,
-});
+interface AdelosOptions {
+  cluster?: "devnet" | "mainnet-beta" | "localnet";
+  rpcUrl?: string;      // Custom RPC URL
+  heliusApiKey?: string; // For indexer webhooks
+}
 ```
 
 #### Methods
 
 | Method | Description |
 |--------|-------------|
-| `getRegistry(owner)` | Gets full registry info for an owner |
-| `getMetaPubkey(owner)` | Gets just the meta pubkey |
-| `isRegistered(owner)` | Checks if owner has registered |
-| `createRegisterTransaction(owner, metaPubkey)` | Creates unsigned register tx |
-| `createUpdateTransaction(owner, newMetaPubkey)` | Creates unsigned update tx |
-| `createCloseTransaction(owner)` | Creates unsigned close tx |
-| `sendAndConfirm(signedTx)` | Sends and confirms transaction |
+| `getRegistry(owner)` | Fetch registry account |
+| `getMetaPubkey(owner)` | Get meta pubkey for stealth derivation |
+| `isRegistered(owner)` | Check if owner has registry |
+| `createRegisterTransactionV0(owner, metaPubkey)` | Create register tx (v0) |
+| `createUpdateTransactionV0(owner, newMetaPubkey)` | Create update tx (v0) |
+| `createCloseTransactionV0(owner)` | Create close tx (v0) |
+| `sendAndConfirmV0(signedTx)` | Send versioned transaction |
 
-## Usage with Wallet Adapter
+### Crypto Functions
 
 ```typescript
-import { useWallet } from "@solana/wallet-adapter-react";
-import { AdelosSDK } from "@adelos/sdk";
-
-function RegisterButton() {
-  const { publicKey, signTransaction } = useWallet();
-  const sdk = new AdelosSDK();
+import { 
+  generateStealthAddress,
+  generateEphemeralKeypair,
+  computeSharedSecret,
+  deriveStealthPubkey,
+  recoverStealthSecretKey,
+  parseStealthMemo
+} from "@adelos/sdk";
+
+// Generate stealth address for recipient
+const { stealthPubkey, memo } = await generateStealthAddress(recipientMetaPubkey);
+
+// Recipient scans for their transactions
+const ephemeralPubkey = parseStealthMemo(memo);
+const sharedSecret = await computeSharedSecretAsRecipient(metaSk, ephemeralPubkey);
+const stealthSk = recoverStealthSecretKey(metaSk, sharedSecret);
+```
 
-  const handleRegister = async () => {
-    // Generate encryption keypair
-    const metaPubkey = crypto.getRandomValues(new Uint8Array(32));
+### Indexer
 
-    // Create transaction
-    const tx = await sdk.createRegisterTransaction(publicKey!, metaPubkey);
+```typescript
+import { AdelosIndexer } from "@adelos/sdk";
 
-    // Sign with wallet
-    const signedTx = await signTransaction!(tx);
+const indexer = new AdelosIndexer({
+  rpcUrl: "https://api.devnet.solana.com",
+  heliusApiKey: "your-api-key" // Optional
+});
 
-    // Send
-    const signature = await sdk.sendAndConfirm(signedTx);
-    console.log("Registered!", signature);
-  };
+// Scan for incoming stealth transfers
+const transfers = await indexer.scanForStealthTransfers(
+  metaSecretKey,
+  metaPublicKey,
+  100 // limit
+);
 
-  return <button onClick={handleRegister}>Register Identity</button>;
-}
+// Real-time scanning
+indexer.onTransaction = (tx) => console.log("Received:", tx);
+indexer.startScanning(metaSk, metaPubkey);
 ```
 
-## Utility Functions
+### Light Protocol (ZK-Compression)
 
 ```typescript
-import { deriveRegistryPda, bytesToHex, hexToBytes } from "@adelos/sdk";
+import { LightClient } from "@adelos/sdk";
 
-// Derive PDA
-const [pda, bump] = deriveRegistryPda(ownerPubkey);
+const light = LightClient.create("https://zk-rpc-endpoint.com");
 
-// Convert bytes to hex
-const hex = bytesToHex(metaPubkey);
+// Get compressed balance
+const balance = await light.getCompressedSolBalance(owner);
 
-// Convert hex to bytes
-const bytes = hexToBytes("0101010101...");
+// Create stealth compressed transfer
+const tx = await light.createStealthCompressedTransfer(
+  sender,
+  stealthPubkey,
+  amount,
+  memo
+);
+```
+
+## 🔗 Constants
+
+```typescript
+import { 
+  PROGRAM_IDS,      // Program ID per cluster
+  RPC_URLS,         // Default RPC URLs
+  MEMO_PROGRAM_ID,  // Solana Memo Program
+  MEMO_PREFIX,      // "ADLSv1:"
+  STEALTH_DOMAIN    // "adelos:stealth:v1"
+} from "@adelos/sdk";
 ```
 
-## License
+## 📄 License
 
 MIT

package/dist/index.d.mts

@@ -1,4 +1,23 @@
-import { PublicKey, Connection, TransactionInstruction, Transaction } from '@solana/web3.js';
+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";
 
 /** Represents a registry account data */
 interface RegistryAccount {
@@ -9,12 +28,26 @@ interface RegistryAccount {
     /** PDA bump seed */
     bump: number;
 }
-/** Options for initializing the Adelos SDK */
+/**
+ * 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"
+ * });
+ */
 interface AdelosOptions {
-    /** Solana cluster URL */
+    /** Solana cluster (devnet, mainnet-beta, or localnet) */
+    cluster?: SolanaCluster;
+    /** Custom RPC URL (optional - overrides cluster default) */
     rpcUrl?: string;
-    /** Custom program ID (defaults to Devnet) */
-    programId?: PublicKey;
+    /** Helius API key for indexer webhooks (optional) */
+    heliusApiKey?: string;
 }
 /** Result of a registry lookup */
 interface RegistryInfo {
@@ -32,13 +65,20 @@ interface TransactionResult {
     /** Registry PDA address */
     registryAddress: PublicKey;
 }
-
-/** Program ID for Adelos Registry on Devnet */
-declare const 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;
+/** 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;
+}
 
 /**
  * Derives the registry PDA for a given owner
@@ -78,8 +118,31 @@ declare const IDL: {
         readonly name: "adelos_registry";
         readonly version: "0.1.0";
         readonly spec: "0.1.0";
+        readonly description: "Privacy Registry for Adelos Protocol";
     };
     readonly instructions: readonly [{
+        readonly name: "close_registry";
+        readonly discriminator: readonly [76, 32, 154, 180, 51, 159, 218, 102];
+        readonly accounts: readonly [{
+            readonly name: "owner";
+            readonly writable: true;
+            readonly signer: true;
+            readonly relations: readonly ["registry"];
+        }, {
+            readonly name: "registry";
+            readonly writable: true;
+            readonly pda: {
+                readonly seeds: readonly [{
+                    readonly kind: "const";
+                    readonly value: readonly [114, 101, 103, 105, 115, 116, 114, 121];
+                }, {
+                    readonly kind: "account";
+                    readonly path: "owner";
+                }];
+            };
+        }];
+        readonly args: readonly [];
+    }, {
         readonly name: "register_identity";
         readonly discriminator: readonly [164, 118, 227, 177, 47, 176, 187, 248];
         readonly accounts: readonly [{
@@ -113,10 +176,24 @@ declare const IDL: {
         readonly discriminator: readonly [130, 54, 88, 104, 222, 124, 238, 252];
         readonly accounts: readonly [{
             readonly name: "owner";
+            readonly writable: true;
             readonly signer: true;
+            readonly relations: readonly ["registry"];
         }, {
             readonly name: "registry";
             readonly writable: true;
+            readonly pda: {
+                readonly seeds: readonly [{
+                    readonly kind: "const";
+                    readonly value: readonly [114, 101, 103, 105, 115, 116, 114, 121];
+                }, {
+                    readonly kind: "account";
+                    readonly path: "owner";
+                }];
+            };
+        }, {
+            readonly name: "system_program";
+            readonly address: "11111111111111111111111111111111";
         }];
         readonly args: readonly [{
             readonly name: "new_meta_pubkey";
@@ -124,23 +201,20 @@ declare const IDL: {
                 readonly array: readonly ["u8", 32];
             };
         }];
-    }, {
-        readonly name: "close_registry";
-        readonly discriminator: readonly [76, 32, 154, 180, 51, 159, 218, 102];
-        readonly accounts: readonly [{
-            readonly name: "owner";
-            readonly writable: true;
-            readonly signer: true;
-        }, {
-            readonly name: "registry";
-            readonly writable: true;
-        }];
-        readonly args: readonly [];
     }];
     readonly accounts: readonly [{
         readonly name: "RegistryAccount";
         readonly discriminator: readonly [113, 93, 106, 201, 100, 166, 146, 98];
     }];
+    readonly errors: readonly [{
+        readonly code: 6000;
+        readonly name: "InvalidMetaPubkey";
+        readonly msg: "Invalid meta_pubkey";
+    }, {
+        readonly code: 6001;
+        readonly name: "Unauthorized";
+        readonly msg: "Unauthorized";
+    }];
     readonly types: readonly [{
         readonly name: "RegistryAccount";
         readonly type: {
@@ -159,15 +233,6 @@ declare const IDL: {
             }];
         };
     }];
-    readonly errors: readonly [{
-        readonly code: 6000;
-        readonly name: "InvalidMetaPubkey";
-        readonly msg: "Invalid meta_pubkey";
-    }, {
-        readonly code: 6001;
-        readonly name: "Unauthorized";
-        readonly msg: "Unauthorized";
-    }];
 };
 type AdelosIDL = typeof IDL;
 
@@ -469,6 +534,10 @@ declare class 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
@@ -489,7 +558,9 @@ declare class AdelosIndexer {
      */
     private extractMemo;
     /**
-     * Parses a transaction to extract stealth transfer info
+     * 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;
     /**
@@ -532,11 +603,18 @@ declare function createIndexer(config: IndexerConfig): AdelosIndexer;
  * ```typescript
  * import { AdelosSDK } from "@adelos/sdk";
  *
- * const sdk = new AdelosSDK({ rpcUrl: "https://api.devnet.solana.com" });
+ * // 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 result = await sdk.register(wallet, metaPubkey);
+ * const tx = await sdk.createRegisterTransactionV0(walletPubkey, metaPubkey);
  *
  * // Get registry
  * const registry = await sdk.getRegistry(ownerPubkey);
@@ -546,7 +624,8 @@ declare function createIndexer(config: IndexerConfig): AdelosIndexer;
 declare class AdelosSDK {
     readonly connection: Connection;
     readonly programId: PublicKey;
-    private program;
+    readonly cluster: SolanaCluster;
+    readonly heliusApiKey?: string;
     constructor(options?: AdelosOptions);
     /**
      * Derives the registry PDA for an owner
@@ -582,21 +661,38 @@ declare class AdelosSDK {
      */
     createCloseInstruction(owner: PublicKey): TransactionInstruction;
     /**
-     * Creates a register transaction (unsigned)
+     * Creates a register transaction (unsigned) - Legacy format
      */
     createRegisterTransaction(owner: PublicKey, metaPubkey: Uint8Array): Promise<Transaction>;
     /**
-     * Creates an update transaction (unsigned)
+     * 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 a close transaction (unsigned)
+     * 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>;
     /**
-     * Sends a signed transaction and confirms it
+     * 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>;
 }
 
-export { type AdelosIDL, AdelosIndexer, type AdelosOptions, AdelosSDK, type CompressedAccount, type CompressedTokenBalance, type HeliusWebhookPayload, IDL, type IndexerConfig, LIGHT_PROGRAM_IDS, LightClient, type LightConfig, PROGRAM_ID, REGISTRY_ACCOUNT_SIZE, REGISTRY_SEED, type RegistryAccount, type RegistryInfo, type StealthTransaction, type TransactionResult, bytesToHex, computeSharedSecret, computeSharedSecretAsRecipient, createIndexer, createLightClient, deriveRegistryPda, deriveStealthPubkey, generateEphemeralKeypair, generateStealthAddress, generateStealthMemo, getDiscriminator, hexToBytes, isStealthTransactionForMe, isValidMetaPubkey, parseStealthMemo, recoverStealthSecretKey };
+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 };