@adelos/sdk 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -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 };