@adelos/sdk 0.1.14 → 0.1.20

package/README.md

@@ -2,6 +2,8 @@
 
 TypeScript SDK for Adelos Protocol - Privacy Stealth Transfers on Solana.
 
+[![npm version](https://img.shields.io/npm/v/@adelos/sdk.svg)](https://www.npmjs.com/package/@adelos/sdk)
+
 ## 📦 Installation
 
 ```bash
@@ -11,16 +13,12 @@ npm install @adelos/sdk
 ## 🚀 Quick Start
 
 ```typescript
-import { AdelosSDK, generateStealthAddress } from "@adelos/sdk";
-
-// Initialize with cluster
-const sdk = new AdelosSDK({ cluster: "devnet" });
+import { AdelosSDK, AdelosIndexer, derivePublicKey, bytesToHex } from "@adelos/sdk";
 
-// Or with custom RPC (Helius, QuickNode)
+// Initialize with RPC URL
 const sdk = new AdelosSDK({ 
-  cluster: "devnet",
-  rpcUrl: "https://your-rpc-endpoint.com",
-  heliusApiKey: "your-helius-api-key" // Optional, for webhooks
+  rpcUrl: "https://api.devnet.solana.com",
+  debug: true // Enable debug logging
 });
 ```
 
@@ -28,102 +26,147 @@ const sdk = new AdelosSDK({
 
 ### AdelosSDK
 
+Main SDK class for interacting with the Adelos Protocol.
+
 #### Constructor Options
 
 ```typescript
 interface AdelosOptions {
-  cluster?: "devnet" | "mainnet-beta" | "localnet";
-  rpcUrl?: string;      // Custom RPC URL
-  heliusApiKey?: string; // For indexer webhooks
+  rpcUrl?: string;   // RPC URL (default: devnet)
+  debug?: boolean;   // Enable debug logging
 }
 ```
 
-#### Methods
+#### Identity Methods
 
 | Method | Description |
 |--------|-------------|
-| `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 |
+| `unlockPrivacy(signMessage)` | Derive meta secret key from wallet signature |
+| `getRegistry(owner)` | Fetch registry account for a wallet |
+| `isRegistered(owner)` | Check if wallet has registered identity |
 
-### Crypto Functions
+#### Transaction Builders
+
+| Method | Description |
+|--------|-------------|
+| `createRegisterTransaction(owner, metaPk)` | Create register transaction |
+| `createUpdateTransaction(owner, newMetaPk)` | Create update transaction |
+| `createStealthTransfer(sender, receiver, amount, txVersion)` | Create stealth transfer |
+| `createWithdrawTransaction(stealthSk, stealthAddr, dest, amount?)` | Create withdraw transaction |
+| `sendAndConfirm(signedTx)` | Send and confirm transaction |
+
+### Stealth Transfer Flow
 
 ```typescript
-import { 
-  generateStealthAddress,
-  generateEphemeralKeypair,
-  computeSharedSecret,
-  deriveStealthPubkey,
-  recoverStealthSecretKey,
-  parseStealthMemo
-} from "@adelos/sdk";
+// 1. Sender creates stealth transfer
+const { transaction, stealthAddress, memo } = await sdk.createStealthTransfer(
+  senderPubkey,
+  receiverPubkey,
+  0.1, // SOL
+  "v0"
+);
 
-// Generate stealth address for recipient
-const { stealthPubkey, memo } = await generateStealthAddress(recipientMetaPubkey);
+// 2. Sign and send
+const signedTx = await signTransaction(transaction);
+const signature = await sdk.sendAndConfirm(signedTx);
+```
 
-// Recipient scans for their transactions
-const ephemeralPubkey = parseStealthMemo(memo);
-const sharedSecret = await computeSharedSecretAsRecipient(metaSk, ephemeralPubkey);
-const stealthSk = recoverStealthSecretKey(metaSk, sharedSecret);
+### Withdraw Flow
+
+```typescript
+// Withdraw full balance (auto-calculates fee)
+const { signature } = await sdk.createWithdrawTransaction(
+  stealthSecretKey,
+  stealthAddress,
+  destinationPubkey
+  // amount is optional - if omitted, withdraws full balance
+);
+
+// Or specify exact amount
+const { signature } = await sdk.createWithdrawTransaction(
+  stealthSecretKey,
+  stealthAddress,
+  destinationPubkey,
+  BigInt(50000000) // 0.05 SOL in lamports
+);
 ```
 
-### Indexer
+### AdelosIndexer
+
+Scan the blockchain for incoming stealth transfers.
 
 ```typescript
 import { AdelosIndexer } from "@adelos/sdk";
 
-const indexer = new AdelosIndexer({
-  rpcUrl: "https://api.devnet.solana.com",
-  heliusApiKey: "your-api-key" // Optional
-});
+const indexer = new AdelosIndexer(connection);
 
-// Scan for incoming stealth transfers
+// Scan for stealth transfers
 const transfers = await indexer.scanForStealthTransfers(
   metaSecretKey,
   metaPublicKey,
-  100 // limit
+  50 // limit
 );
 
-// Real-time scanning
-indexer.onTransaction = (tx) => console.log("Received:", tx);
-indexer.startScanning(metaSk, metaPubkey);
+// Prepare withdrawal
+const withdrawable = indexer.prepareWithdraw(transfer, metaSk, metaPk);
+// Returns: { stealthSecretKey, stealthPublicKey }
 ```
 
-### Light Protocol (ZK-Compression)
+### Crypto Functions
 
 ```typescript
-import { LightClient } from "@adelos/sdk";
-
-const light = LightClient.create("https://zk-rpc-endpoint.com");
+import { 
+  derivePublicKey,
+  generateStealthAddress,
+  recoverStealthSecretKey,
+  computeSharedSecret,
+  bytesToHex,
+  hexToBytes
+} from "@adelos/sdk";
 
-// Get compressed balance
-const balance = await light.getCompressedSolBalance(owner);
+// Derive public key from secret key
+const metaPk = derivePublicKey(metaSk);
 
-// Create stealth compressed transfer
-const tx = await light.createStealthCompressedTransfer(
-  sender,
-  stealthPubkey,
-  amount,
-  memo
+// Generate stealth address for recipient
+const { stealthPubkey, ephemeralPubkey, memo } = generateStealthAddress(
+  recipientMetaPubkey
 );
+
+// Recover stealth secret key (for withdrawal)
+const stealthSk = recoverStealthSecretKey(metaSk, sharedSecret);
+```
+
+### Utility Functions
+
+```typescript
+import { bytesToHex, hexToBytes, validatePublicKey } from "@adelos/sdk";
+
+// Convert bytes to hex string
+const hex = bytesToHex(bytes); // "a1b2c3..."
+
+// Convert hex string to bytes
+const bytes = hexToBytes(hex); // Uint8Array
+
+// Validate public key bytes
+const isValid = validatePublicKey(pubkeyBytes);
 ```
 
 ## 🔗 Constants
 
 ```typescript
 import { 
-  PROGRAM_IDS,      // Program ID per cluster
-  RPC_URLS,         // Default RPC URLs
+  PROGRAM_ID,       // Adelos Registry Program ID
   MEMO_PROGRAM_ID,  // Solana Memo Program
-  MEMO_PREFIX,      // "ADLSv1:"
-  STEALTH_DOMAIN    // "adelos:stealth:v1"
+  MEMO_PREFIX       // "ADLSv1:" - Protocol prefix
 } from "@adelos/sdk";
 ```
 
+## 🔒 Security Notes
+
+- Meta secret keys are derived deterministically from wallet signatures
+- Stealth secret keys are computed using Ed25519 scalar addition
+- All cryptographic operations use `@noble/ed25519` and `@noble/hashes`
+
 ## 📄 License
 
 MIT

package/dist/index.d.mts

@@ -177,7 +177,7 @@ declare class AdelosSDK {
      * @param destination - Where to send the funds (can be ANY address)
      * @param amountLamports - Amount to withdraw in lamports (use BigInt)
      */
-    createWithdrawTransaction(stealthSecretKey: Uint8Array, stealthAddress: PublicKey, destination: PublicKey, amountLamports: bigint): Promise<{
+    createWithdrawTransaction(stealthSecretKey: Uint8Array, stealthAddress: PublicKey, destination: PublicKey, amountLamports?: bigint): Promise<{
         transaction: VersionedTransaction;
         signature: string;
     }>;

package/dist/index.d.ts

@@ -177,7 +177,7 @@ declare class AdelosSDK {
      * @param destination - Where to send the funds (can be ANY address)
      * @param amountLamports - Amount to withdraw in lamports (use BigInt)
      */
-    createWithdrawTransaction(stealthSecretKey: Uint8Array, stealthAddress: PublicKey, destination: PublicKey, amountLamports: bigint): Promise<{
+    createWithdrawTransaction(stealthSecretKey: Uint8Array, stealthAddress: PublicKey, destination: PublicKey, amountLamports?: bigint): Promise<{
         transaction: VersionedTransaction;
         signature: string;
     }>;

package/dist/index.js

@@ -421,10 +421,19 @@ var AdelosSDK = class {
    * @param amountLamports - Amount to withdraw in lamports (use BigInt)
    */
   async createWithdrawTransaction(stealthSecretKey, stealthAddress, destination, amountLamports) {
+    let finalAmount = amountLamports;
+    if (finalAmount === void 0) {
+      const balance = await this.connection.getBalance(stealthAddress);
+      const FEE_BUFFER = 5e3;
+      if (balance <= FEE_BUFFER) {
+        throw new Error(`Insufficient funds (Balance: ${balance}, Fee: ${FEE_BUFFER})`);
+      }
+      finalAmount = BigInt(balance - FEE_BUFFER);
+    }
     const ix = import_web33.SystemProgram.transfer({
       fromPubkey: stealthAddress,
       toPubkey: destination,
-      lamports: amountLamports
+      lamports: finalAmount
     });
     const { blockhash } = await this.connection.getLatestBlockhash();
     const message = new import_web33.TransactionMessage({

package/dist/index.mjs

@@ -371,10 +371,19 @@ var AdelosSDK = class {
    * @param amountLamports - Amount to withdraw in lamports (use BigInt)
    */
   async createWithdrawTransaction(stealthSecretKey, stealthAddress, destination, amountLamports) {
+    let finalAmount = amountLamports;
+    if (finalAmount === void 0) {
+      const balance = await this.connection.getBalance(stealthAddress);
+      const FEE_BUFFER = 5e3;
+      if (balance <= FEE_BUFFER) {
+        throw new Error(`Insufficient funds (Balance: ${balance}, Fee: ${FEE_BUFFER})`);
+      }
+      finalAmount = BigInt(balance - FEE_BUFFER);
+    }
     const ix = SystemProgram.transfer({
       fromPubkey: stealthAddress,
       toPubkey: destination,
-      lamports: amountLamports
+      lamports: finalAmount
     });
     const { blockhash } = await this.connection.getLatestBlockhash();
     const message = new TransactionMessage({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adelos/sdk",
-  "version": "0.1.14",
+  "version": "0.1.20",
   "description": "Adelos Protocol SDK - Privacy Stealth Transfers on Solana",
   "main": "dist/index.js",
   "module": "dist/index.mjs",