@adelos/sdk 0.1.1 → 0.1.3

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