@adelos/sdk 0.1.15 → 0.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +103 -60
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  TypeScript SDK for Adelos Protocol - Privacy Stealth Transfers on Solana.
4
4
 
5
+ [![npm version](https://img.shields.io/npm/v/@adelos/sdk.svg)](https://www.npmjs.com/package/@adelos/sdk)
6
+
5
7
  ## 📦 Installation
6
8
 
7
9
  ```bash
@@ -11,16 +13,12 @@ npm install @adelos/sdk
11
13
  ## 🚀 Quick Start
12
14
 
13
15
  ```typescript
14
- import { AdelosSDK, generateStealthAddress } from "@adelos/sdk";
15
-
16
- // Initialize with cluster
17
- const sdk = new AdelosSDK({ cluster: "devnet" });
16
+ import { AdelosSDK, AdelosIndexer, derivePublicKey, bytesToHex } from "@adelos/sdk";
18
17
 
19
- // Or with custom RPC (Helius, QuickNode)
18
+ // Initialize with RPC URL
20
19
  const sdk = new AdelosSDK({
21
- cluster: "devnet",
22
- rpcUrl: "https://your-rpc-endpoint.com",
23
- heliusApiKey: "your-helius-api-key" // Optional, for webhooks
20
+ rpcUrl: "https://api.devnet.solana.com",
21
+ debug: true // Enable debug logging
24
22
  });
25
23
  ```
26
24
 
@@ -28,102 +26,147 @@ const sdk = new AdelosSDK({
28
26
 
29
27
  ### AdelosSDK
30
28
 
29
+ Main SDK class for interacting with the Adelos Protocol.
30
+
31
31
  #### Constructor Options
32
32
 
33
33
  ```typescript
34
34
  interface AdelosOptions {
35
- cluster?: "devnet" | "mainnet-beta" | "localnet";
36
- rpcUrl?: string; // Custom RPC URL
37
- heliusApiKey?: string; // For indexer webhooks
35
+ rpcUrl?: string; // RPC URL (default: devnet)
36
+ debug?: boolean; // Enable debug logging
38
37
  }
39
38
  ```
40
39
 
41
- #### Methods
40
+ #### Identity Methods
42
41
 
43
42
  | Method | Description |
44
43
  |--------|-------------|
45
- | `getRegistry(owner)` | Fetch registry account |
46
- | `getMetaPubkey(owner)` | Get meta pubkey for stealth derivation |
47
- | `isRegistered(owner)` | Check if owner has registry |
48
- | `createRegisterTransactionV0(owner, metaPubkey)` | Create register tx (v0) |
49
- | `createUpdateTransactionV0(owner, newMetaPubkey)` | Create update tx (v0) |
50
- | `createCloseTransactionV0(owner)` | Create close tx (v0) |
51
- | `sendAndConfirmV0(signedTx)` | Send versioned transaction |
44
+ | `unlockPrivacy(signMessage)` | Derive meta secret key from wallet signature |
45
+ | `getRegistry(owner)` | Fetch registry account for a wallet |
46
+ | `isRegistered(owner)` | Check if wallet has registered identity |
52
47
 
53
- ### Crypto Functions
48
+ #### Transaction Builders
49
+
50
+ | Method | Description |
51
+ |--------|-------------|
52
+ | `createRegisterTransaction(owner, metaPk)` | Create register transaction |
53
+ | `createUpdateTransaction(owner, newMetaPk)` | Create update transaction |
54
+ | `createStealthTransfer(sender, receiver, amount, txVersion)` | Create stealth transfer |
55
+ | `createWithdrawTransaction(stealthSk, stealthAddr, dest, amount?)` | Create withdraw transaction |
56
+ | `sendAndConfirm(signedTx)` | Send and confirm transaction |
57
+
58
+ ### Stealth Transfer Flow
54
59
 
55
60
  ```typescript
56
- import {
57
- generateStealthAddress,
58
- generateEphemeralKeypair,
59
- computeSharedSecret,
60
- deriveStealthPubkey,
61
- recoverStealthSecretKey,
62
- parseStealthMemo
63
- } from "@adelos/sdk";
61
+ // 1. Sender creates stealth transfer
62
+ const { transaction, stealthAddress, memo } = await sdk.createStealthTransfer(
63
+ senderPubkey,
64
+ receiverPubkey,
65
+ 0.1, // SOL
66
+ "v0"
67
+ );
64
68
 
65
- // Generate stealth address for recipient
66
- const { stealthPubkey, memo } = await generateStealthAddress(recipientMetaPubkey);
69
+ // 2. Sign and send
70
+ const signedTx = await signTransaction(transaction);
71
+ const signature = await sdk.sendAndConfirm(signedTx);
72
+ ```
67
73
 
68
- // Recipient scans for their transactions
69
- const ephemeralPubkey = parseStealthMemo(memo);
70
- const sharedSecret = await computeSharedSecretAsRecipient(metaSk, ephemeralPubkey);
71
- const stealthSk = recoverStealthSecretKey(metaSk, sharedSecret);
74
+ ### Withdraw Flow
75
+
76
+ ```typescript
77
+ // Withdraw full balance (auto-calculates fee)
78
+ const { signature } = await sdk.createWithdrawTransaction(
79
+ stealthSecretKey,
80
+ stealthAddress,
81
+ destinationPubkey
82
+ // amount is optional - if omitted, withdraws full balance
83
+ );
84
+
85
+ // Or specify exact amount
86
+ const { signature } = await sdk.createWithdrawTransaction(
87
+ stealthSecretKey,
88
+ stealthAddress,
89
+ destinationPubkey,
90
+ BigInt(50000000) // 0.05 SOL in lamports
91
+ );
72
92
  ```
73
93
 
74
- ### Indexer
94
+ ### AdelosIndexer
95
+
96
+ Scan the blockchain for incoming stealth transfers.
75
97
 
76
98
  ```typescript
77
99
  import { AdelosIndexer } from "@adelos/sdk";
78
100
 
79
- const indexer = new AdelosIndexer({
80
- rpcUrl: "https://api.devnet.solana.com",
81
- heliusApiKey: "your-api-key" // Optional
82
- });
101
+ const indexer = new AdelosIndexer(connection);
83
102
 
84
- // Scan for incoming stealth transfers
103
+ // Scan for stealth transfers
85
104
  const transfers = await indexer.scanForStealthTransfers(
86
105
  metaSecretKey,
87
106
  metaPublicKey,
88
- 100 // limit
107
+ 50 // limit
89
108
  );
90
109
 
91
- // Real-time scanning
92
- indexer.onTransaction = (tx) => console.log("Received:", tx);
93
- indexer.startScanning(metaSk, metaPubkey);
110
+ // Prepare withdrawal
111
+ const withdrawable = indexer.prepareWithdraw(transfer, metaSk, metaPk);
112
+ // Returns: { stealthSecretKey, stealthPublicKey }
94
113
  ```
95
114
 
96
- ### Light Protocol (ZK-Compression)
115
+ ### Crypto Functions
97
116
 
98
117
  ```typescript
99
- import { LightClient } from "@adelos/sdk";
100
-
101
- const light = LightClient.create("https://zk-rpc-endpoint.com");
118
+ import {
119
+ derivePublicKey,
120
+ generateStealthAddress,
121
+ recoverStealthSecretKey,
122
+ computeSharedSecret,
123
+ bytesToHex,
124
+ hexToBytes
125
+ } from "@adelos/sdk";
102
126
 
103
- // Get compressed balance
104
- const balance = await light.getCompressedSolBalance(owner);
127
+ // Derive public key from secret key
128
+ const metaPk = derivePublicKey(metaSk);
105
129
 
106
- // Create stealth compressed transfer
107
- const tx = await light.createStealthCompressedTransfer(
108
- sender,
109
- stealthPubkey,
110
- amount,
111
- memo
130
+ // Generate stealth address for recipient
131
+ const { stealthPubkey, ephemeralPubkey, memo } = generateStealthAddress(
132
+ recipientMetaPubkey
112
133
  );
134
+
135
+ // Recover stealth secret key (for withdrawal)
136
+ const stealthSk = recoverStealthSecretKey(metaSk, sharedSecret);
137
+ ```
138
+
139
+ ### Utility Functions
140
+
141
+ ```typescript
142
+ import { bytesToHex, hexToBytes, validatePublicKey } from "@adelos/sdk";
143
+
144
+ // Convert bytes to hex string
145
+ const hex = bytesToHex(bytes); // "a1b2c3..."
146
+
147
+ // Convert hex string to bytes
148
+ const bytes = hexToBytes(hex); // Uint8Array
149
+
150
+ // Validate public key bytes
151
+ const isValid = validatePublicKey(pubkeyBytes);
113
152
  ```
114
153
 
115
154
  ## 🔗 Constants
116
155
 
117
156
  ```typescript
118
157
  import {
119
- PROGRAM_IDS, // Program ID per cluster
120
- RPC_URLS, // Default RPC URLs
158
+ PROGRAM_ID, // Adelos Registry Program ID
121
159
  MEMO_PROGRAM_ID, // Solana Memo Program
122
- MEMO_PREFIX, // "ADLSv1:"
123
- STEALTH_DOMAIN // "adelos:stealth:v1"
160
+ MEMO_PREFIX // "ADLSv1:" - Protocol prefix
124
161
  } from "@adelos/sdk";
125
162
  ```
126
163
 
164
+ ## 🔒 Security Notes
165
+
166
+ - Meta secret keys are derived deterministically from wallet signatures
167
+ - Stealth secret keys are computed using Ed25519 scalar addition
168
+ - All cryptographic operations use `@noble/ed25519` and `@noble/hashes`
169
+
127
170
  ## 📄 License
128
171
 
129
172
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adelos/sdk",
3
- "version": "0.1.15",
3
+ "version": "0.1.20",
4
4
  "description": "Adelos Protocol SDK - Privacy Stealth Transfers on Solana",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",