@opendatalabs/vana-sdk 2.0.0 → 2.1.0
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.
- package/README.md +67 -351
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,426 +1,142 @@
|
|
|
1
1
|
# Vana SDK
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
>
|
|
5
|
-
> This SDK is in early alpha development and is **NOT SUITABLE FOR PRODUCTION USE**.
|
|
6
|
-
> Features may change without notice, and data loss or unexpected behavior may occur.
|
|
7
|
-
> Use at your own risk and avoid using with mainnet assets or critical operations.
|
|
8
|
-
|
|
9
|
-
A TypeScript SDK for building data-driven applications on the Vana Network. Enable users to grant gasless permissions, manage encrypted data, and interact with privacy-preserving infrastructure.
|
|
3
|
+
Build user-owned data applications with gasless permissions, encrypted data management, and privacy-preserving infrastructure.
|
|
10
4
|
|
|
11
5
|
[](https://www.npmjs.com/package/@opendatalabs/vana-sdk)
|
|
12
|
-
[ • [Examples](#examples) • [Configuration](#configuration)
|
|
6
|
+
[](https://www.npmjs.com/package/@opendatalabs/vana-sdk)
|
|
7
|
+
[](https://opensource.org/licenses/ISC)
|
|
16
8
|
|
|
17
|
-
|
|
9
|
+
The SDK is production-ready. APIs may evolve in minor versions as we incorporate feedback and expand functionality.
|
|
18
10
|
|
|
19
|
-
|
|
20
|
-
npm install @opendatalabs/vana-sdk
|
|
21
|
-
```
|
|
11
|
+
## Get Started
|
|
22
12
|
|
|
23
|
-
|
|
13
|
+
### 1. Install
|
|
24
14
|
|
|
25
15
|
```bash
|
|
26
|
-
npm install viem
|
|
16
|
+
npm install @opendatalabs/vana-sdk viem
|
|
27
17
|
```
|
|
28
18
|
|
|
29
|
-
|
|
19
|
+
### 2. Set up your client
|
|
30
20
|
|
|
31
|
-
|
|
21
|
+
Choose the build for your environment:
|
|
32
22
|
|
|
33
|
-
|
|
34
|
-
| -------------- | --------------------------------- | ---------------------------------- | ----------------- |
|
|
35
|
-
| **`/browser`** | Browser apps (React, Vue) | Pure JavaScript (@noble/secp256k1) | **Zero config** ✓ |
|
|
36
|
-
| **`/node`** | Server-side (Node.js, API routes) | Native bindings (secp256k1) | Zero config ✓ |
|
|
37
|
-
|
|
38
|
-
### Browser Applications
|
|
39
|
-
|
|
40
|
-
The browser build uses pure JavaScript cryptography and requires **no special configuration**:
|
|
23
|
+
**Browser:**
|
|
41
24
|
|
|
42
25
|
```typescript
|
|
43
|
-
// Browser build - works out of the box with any bundler
|
|
44
26
|
import { Vana, mokshaTestnet } from "@opendatalabs/vana-sdk/browser";
|
|
45
|
-
import { createWalletClient,
|
|
46
|
-
import { privateKeyToAccount } from "viem/accounts";
|
|
27
|
+
import { createWalletClient, custom } from "viem";
|
|
47
28
|
|
|
48
|
-
// Create wallet client
|
|
49
|
-
const account = privateKeyToAccount("0x...");
|
|
50
29
|
const walletClient = createWalletClient({
|
|
51
|
-
account,
|
|
52
30
|
chain: mokshaTestnet,
|
|
53
|
-
transport:
|
|
31
|
+
transport: custom(window.ethereum),
|
|
54
32
|
});
|
|
55
33
|
|
|
56
|
-
|
|
57
|
-
const vana = Vana({
|
|
58
|
-
walletClient,
|
|
59
|
-
relayerUrl: "https://relayer.moksha.vana.org",
|
|
60
|
-
});
|
|
34
|
+
const vana = Vana({ walletClient });
|
|
61
35
|
```
|
|
62
36
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
The Node.js build uses native secp256k1 bindings for optimal performance:
|
|
37
|
+
**Node.js:**
|
|
66
38
|
|
|
67
39
|
```typescript
|
|
68
|
-
// For server-side applications (Next.js API routes, Express)
|
|
69
40
|
import { Vana, mokshaTestnet } from "@opendatalabs/vana-sdk/node";
|
|
70
41
|
import { createWalletClient, http } from "viem";
|
|
71
42
|
import { privateKeyToAccount } from "viem/accounts";
|
|
72
43
|
|
|
73
|
-
// Create wallet client
|
|
74
44
|
const account = privateKeyToAccount("0x...");
|
|
75
|
-
const walletClient = createWalletClient({
|
|
76
|
-
account,
|
|
77
|
-
chain: mokshaTestnet,
|
|
78
|
-
transport: http("https://rpc.moksha.vana.org"),
|
|
79
|
-
});
|
|
80
|
-
|
|
81
|
-
// Initialize SDK
|
|
82
45
|
const vana = Vana({
|
|
83
|
-
walletClient
|
|
46
|
+
walletClient: createWalletClient({
|
|
47
|
+
account,
|
|
48
|
+
chain: mokshaTestnet,
|
|
49
|
+
transport: http("https://rpc.moksha.vana.org"),
|
|
50
|
+
}),
|
|
84
51
|
relayerUrl: "https://relayer.moksha.vana.org",
|
|
85
52
|
});
|
|
86
|
-
|
|
87
|
-
// Grant gasless permission
|
|
88
|
-
const txHash = await vana.permissions.grant({
|
|
89
|
-
grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
90
|
-
operation: "llm_inference",
|
|
91
|
-
parameters: {
|
|
92
|
-
prompt: "Analyze my data for insights",
|
|
93
|
-
maxTokens: 1000,
|
|
94
|
-
},
|
|
95
|
-
expiresAt: Math.floor(Date.now() / 1000) + 86400, // 24 hours
|
|
96
|
-
});
|
|
97
53
|
```
|
|
98
54
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
### Gasless Permissions
|
|
102
|
-
|
|
103
|
-
Users can grant data access permissions without paying gas fees through EIP-712 signatures and relay infrastructure.
|
|
55
|
+
### 3. Use the SDK
|
|
104
56
|
|
|
105
57
|
```typescript
|
|
106
|
-
// Grant
|
|
58
|
+
// Grant gasless data access permission
|
|
107
59
|
await vana.permissions.grant({
|
|
108
|
-
grantee:
|
|
109
|
-
operation: "
|
|
60
|
+
grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
61
|
+
operation: "llm_inference",
|
|
110
62
|
parameters: {
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
model: "gpt-4",
|
|
63
|
+
prompt: "Analyze my data for insights",
|
|
64
|
+
maxTokens: 1000,
|
|
114
65
|
},
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
### Encrypted Data Management
|
|
119
|
-
|
|
120
|
-
Upload, query, and manage encrypted user data files with built-in schema validation.
|
|
121
|
-
|
|
122
|
-
```typescript
|
|
123
|
-
// Query user files
|
|
124
|
-
const files = await vana.data.getUserFiles({
|
|
125
|
-
owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
66
|
+
expiresAt: Math.floor(Date.now() / 1000) + 86400,
|
|
126
67
|
});
|
|
127
68
|
|
|
128
69
|
// Upload encrypted file with decryption permissions
|
|
129
|
-
|
|
70
|
+
await vana.data.upload({
|
|
130
71
|
content: "Sensitive user data",
|
|
131
|
-
filename: "
|
|
72
|
+
filename: "data.json",
|
|
132
73
|
schemaId: 123,
|
|
133
74
|
permissions: [
|
|
134
75
|
{
|
|
135
|
-
account: "0xServerAddress...",
|
|
136
|
-
publicKey: "0x04ServerKey...",
|
|
76
|
+
account: "0xServerAddress...",
|
|
77
|
+
publicKey: "0x04ServerKey...",
|
|
137
78
|
},
|
|
138
79
|
],
|
|
139
80
|
});
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
### Flexible Storage
|
|
143
81
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/browser";
|
|
149
|
-
// OR for server-side applications
|
|
150
|
-
// import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/node";
|
|
151
|
-
|
|
152
|
-
const storageManager = new StorageManager();
|
|
153
|
-
storageManager.register(
|
|
154
|
-
"ipfs",
|
|
155
|
-
new PinataStorage({
|
|
156
|
-
apiKey: process.env.PINATA_API_KEY,
|
|
157
|
-
secretKey: process.env.PINATA_SECRET_KEY,
|
|
158
|
-
}),
|
|
159
|
-
);
|
|
82
|
+
// Query user files
|
|
83
|
+
const files = await vana.data.getUserFiles({
|
|
84
|
+
owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
85
|
+
});
|
|
160
86
|
```
|
|
161
87
|
|
|
162
|
-
##
|
|
88
|
+
## Features
|
|
163
89
|
|
|
164
|
-
The SDK provides
|
|
90
|
+
The SDK provides six main controllers:
|
|
165
91
|
|
|
166
|
-
| Controller | Purpose
|
|
167
|
-
| ------------- |
|
|
168
|
-
| `permissions` |
|
|
169
|
-
| `data` |
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
92
|
+
| Controller | Purpose |
|
|
93
|
+
| ------------- | -------------------------------------------- |
|
|
94
|
+
| `permissions` | Grant and revoke gasless data access |
|
|
95
|
+
| `data` | Upload, query, and decrypt encrypted files |
|
|
96
|
+
| `schemas` | Validate data against schemas |
|
|
97
|
+
| `server` | Interact with trusted servers |
|
|
98
|
+
| `protocol` | Direct smart contract access |
|
|
99
|
+
| `operations` | Track and poll transaction status |
|
|
172
100
|
|
|
173
101
|
## Configuration
|
|
174
102
|
|
|
103
|
+
Configure storage, relay, and subgraph services:
|
|
104
|
+
|
|
175
105
|
```typescript
|
|
106
|
+
import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/node";
|
|
107
|
+
|
|
176
108
|
const vana = Vana({
|
|
177
109
|
walletClient,
|
|
178
|
-
|
|
179
|
-
// Gasless transaction relay
|
|
180
110
|
relayerUrl: "https://relayer.moksha.vana.org",
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
// Storage configuration
|
|
190
|
-
storageManager: new StorageManager({
|
|
191
|
-
defaultProvider: "ipfs",
|
|
192
|
-
providers: {
|
|
193
|
-
ipfs: new PinataStorage({ apiKey: "...", secretKey: "..." }),
|
|
194
|
-
},
|
|
195
|
-
}),
|
|
196
|
-
|
|
197
|
-
// Subgraph for efficient queries
|
|
111
|
+
storageManager: new StorageManager().register(
|
|
112
|
+
"ipfs",
|
|
113
|
+
new PinataStorage({
|
|
114
|
+
apiKey: process.env.PINATA_API_KEY,
|
|
115
|
+
secretKey: process.env.PINATA_SECRET_KEY,
|
|
116
|
+
})
|
|
117
|
+
),
|
|
198
118
|
subgraphUrl: "https://api.thegraph.com/subgraphs/name/vana/moksha",
|
|
199
119
|
});
|
|
200
120
|
```
|
|
201
121
|
|
|
202
|
-
##
|
|
203
|
-
|
|
204
|
-
The SDK provides specific error types for different failure scenarios:
|
|
122
|
+
## Networks
|
|
205
123
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
SchemaValidationError,
|
|
211
|
-
NetworkError,
|
|
212
|
-
} from "@opendatalabs/vana-sdk/browser";
|
|
213
|
-
// OR for server-side applications
|
|
214
|
-
// } from "@opendatalabs/vana-sdk/node";
|
|
215
|
-
|
|
216
|
-
try {
|
|
217
|
-
await vana.permissions.grant(params);
|
|
218
|
-
} catch (error) {
|
|
219
|
-
if (error instanceof UserRejectedRequestError) {
|
|
220
|
-
// User cancelled transaction
|
|
221
|
-
} else if (error instanceof RelayerError) {
|
|
222
|
-
// Relayer service error
|
|
223
|
-
} else if (error instanceof SchemaValidationError) {
|
|
224
|
-
// Schema validation failed
|
|
225
|
-
}
|
|
226
|
-
}
|
|
227
|
-
```
|
|
124
|
+
| Network | Chain ID | RPC URL |
|
|
125
|
+
| -------------- | -------- | --------------------------- |
|
|
126
|
+
| Vana Mainnet | 1480 | https://rpc.vana.org |
|
|
127
|
+
| Moksha Testnet | 14800 | https://rpc.moksha.vana.org |
|
|
228
128
|
|
|
229
|
-
##
|
|
129
|
+
## Learn More
|
|
230
130
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
## Examples
|
|
237
|
-
|
|
238
|
-
### Complete Data Sharing Flow
|
|
239
|
-
|
|
240
|
-
```typescript
|
|
241
|
-
import { Vana } from "@opendatalabs/vana-sdk/browser";
|
|
242
|
-
// OR for server-side applications
|
|
243
|
-
// } from "@opendatalabs/vana-sdk/node";
|
|
244
|
-
|
|
245
|
-
async function shareDataWithServer() {
|
|
246
|
-
const vana = Vana({ walletClient });
|
|
247
|
-
|
|
248
|
-
// Step 1: Upload encrypted file with decryption permissions
|
|
249
|
-
const uploadResult = await vana.data.upload({
|
|
250
|
-
content: { data: "sensitive medical records" },
|
|
251
|
-
filename: "health-data.json",
|
|
252
|
-
schemaId: 123,
|
|
253
|
-
permissions: [
|
|
254
|
-
{
|
|
255
|
-
// Grant decryption access to the AI server
|
|
256
|
-
account: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
257
|
-
publicKey: "0x04abc...", // Server's public key for encryption
|
|
258
|
-
},
|
|
259
|
-
],
|
|
260
|
-
});
|
|
261
|
-
|
|
262
|
-
// Step 2: Grant operation permissions for what the server can do
|
|
263
|
-
const permissionResult = await vana.permissions.grant({
|
|
264
|
-
grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
|
|
265
|
-
fileIds: [BigInt(uploadResult.fileId)],
|
|
266
|
-
operation: "medical_analysis",
|
|
267
|
-
parameters: {
|
|
268
|
-
model: "medical-ai-v2",
|
|
269
|
-
analysisType: "comprehensive",
|
|
270
|
-
},
|
|
271
|
-
});
|
|
272
|
-
|
|
273
|
-
return { uploadResult, permissionResult };
|
|
274
|
-
}
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
### Schema Validation
|
|
278
|
-
|
|
279
|
-
```typescript
|
|
280
|
-
// Define data schema
|
|
281
|
-
const schema = {
|
|
282
|
-
name: "Social Media Export",
|
|
283
|
-
version: "1.0.0",
|
|
284
|
-
dialect: "json",
|
|
285
|
-
schema: {
|
|
286
|
-
type: "object",
|
|
287
|
-
properties: {
|
|
288
|
-
posts: { type: "array" },
|
|
289
|
-
profile: { type: "object" },
|
|
290
|
-
},
|
|
291
|
-
required: ["profile"],
|
|
292
|
-
},
|
|
293
|
-
};
|
|
294
|
-
|
|
295
|
-
// Validate schema
|
|
296
|
-
vana.data.validateDataSchema(schema);
|
|
297
|
-
|
|
298
|
-
// Validate user data
|
|
299
|
-
const userData = {
|
|
300
|
-
profile: { username: "alice" },
|
|
301
|
-
posts: [],
|
|
302
|
-
};
|
|
303
|
-
vana.data.validateDataAgainstSchema(userData, schema);
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
## API Reference
|
|
307
|
-
|
|
308
|
-
### Permissions
|
|
309
|
-
|
|
310
|
-
```typescript
|
|
311
|
-
// Grant operation permission
|
|
312
|
-
await vana.permissions.grant({
|
|
313
|
-
grantee: Address,
|
|
314
|
-
fileIds: bigint[],
|
|
315
|
-
operation: string,
|
|
316
|
-
parameters: object,
|
|
317
|
-
expiresAt?: number
|
|
318
|
-
}): Promise<PermissionGrantResult>
|
|
319
|
-
|
|
320
|
-
// Revoke permission
|
|
321
|
-
await vana.permissions.revoke({
|
|
322
|
-
grantId: string
|
|
323
|
-
}): Promise<Hash>
|
|
324
|
-
|
|
325
|
-
// Get user permissions
|
|
326
|
-
await vana.permissions.getUserPermissions({
|
|
327
|
-
owner: Address
|
|
328
|
-
}): Promise<GrantedPermission[]>
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
### Data
|
|
332
|
-
|
|
333
|
-
```typescript
|
|
334
|
-
// Get user files
|
|
335
|
-
await vana.data.getUserFiles({
|
|
336
|
-
owner: Address
|
|
337
|
-
}): Promise<UserFile[]>
|
|
338
|
-
|
|
339
|
-
// Upload data with automatic encryption
|
|
340
|
-
await vana.data.upload({
|
|
341
|
-
content: string | Blob | Buffer,
|
|
342
|
-
filename?: string,
|
|
343
|
-
schemaId?: number,
|
|
344
|
-
permissions?: Array<{
|
|
345
|
-
account: Address, // Who can decrypt
|
|
346
|
-
publicKey: string // Their public key
|
|
347
|
-
}>,
|
|
348
|
-
encrypt?: boolean // Default: true
|
|
349
|
-
}): Promise<UploadResult>
|
|
350
|
-
|
|
351
|
-
// Validate schema
|
|
352
|
-
vana.data.validateDataSchema(schema: unknown): void
|
|
353
|
-
|
|
354
|
-
// Validate data against schema
|
|
355
|
-
vana.data.validateDataAgainstSchema(data: unknown, schema: DataSchema): void
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
## Documentation
|
|
359
|
-
|
|
360
|
-
- [API Documentation](https://vana-com.github.io/vana-sdk) - Complete TypeDoc API reference
|
|
361
|
-
- [Getting Started](https://vana-com.github.io/vana-sdk/getting-started) - Step-by-step setup guide
|
|
362
|
-
- [Architecture](https://vana-com.github.io/vana-sdk/architecture) - SDK design and patterns
|
|
363
|
-
- [Configuration](https://vana-com.github.io/vana-sdk/configuration) - All configuration options
|
|
364
|
-
- [Security](https://vana-com.github.io/vana-sdk/security) - Best practices and security
|
|
131
|
+
- [Documentation](https://docs.vana.org/docs/sdk) - Comprehensive guides and tutorials
|
|
132
|
+
- [API Reference](https://vana-com.github.io/vana-sdk) - Complete TypeScript documentation
|
|
133
|
+
- [Examples](https://github.com/vana-com/vana-sdk/tree/main/examples) - Full demo applications
|
|
134
|
+
- [Discord](https://discord.gg/vanabuilders) - Community support
|
|
365
135
|
|
|
366
136
|
## Support
|
|
367
137
|
|
|
368
|
-
|
|
369
|
-
- **Issues**: [GitHub Issues](https://github.com/vana-com/vana-sdk/issues)
|
|
370
|
-
- **Discord**: [Join our community](https://discord.gg/vanabuilders)
|
|
371
|
-
|
|
372
|
-
## Generated Code
|
|
373
|
-
|
|
374
|
-
The SDK includes automatically generated code from various sources to provide type-safe interfaces. All generated files are located in `src/generated/` and should **never be edited manually**.
|
|
375
|
-
|
|
376
|
-
### Code Generation Scripts
|
|
377
|
-
|
|
378
|
-
| Script | Purpose | Generated Files |
|
|
379
|
-
| ---------------------------- | -------------------------------------- | --------------------------- |
|
|
380
|
-
| `npm run fetch-abis` | Smart contract ABIs from blockchain | `src/generated/abi/*.ts` |
|
|
381
|
-
| `npm run fetch-server-types` | Personal server API types from OpenAPI | `src/generated/server/*.ts` |
|
|
382
|
-
| `npm run codegen:subgraph` | GraphQL types from subgraph schema | `src/generated/subgraph.ts` |
|
|
383
|
-
|
|
384
|
-
### Network-Specific Generation
|
|
385
|
-
|
|
386
|
-
Some generation scripts support different networks:
|
|
387
|
-
|
|
388
|
-
```bash
|
|
389
|
-
# Generate subgraph types for different networks
|
|
390
|
-
npm run codegen:subgraph:moksha # Moksha testnet (default)
|
|
391
|
-
npm run codegen:subgraph:mainnet # Vana mainnet
|
|
392
|
-
|
|
393
|
-
# Generate ABIs for different networks
|
|
394
|
-
npm run fetch-abis moksha # Moksha testnet (default)
|
|
395
|
-
npm run fetch-abis mainnet # Vana mainnet
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
### Development Workflow
|
|
399
|
-
|
|
400
|
-
When working with the SDK:
|
|
401
|
-
|
|
402
|
-
1. **Never edit generated files** - They are overwritten on regeneration
|
|
403
|
-
2. **Regenerate after schema changes** - Run generation scripts when external schemas change
|
|
404
|
-
3. **Generated files are committed** - They're included in version control for consistency
|
|
405
|
-
4. **ESLint ignores generated code** - Style rules don't apply to generated files
|
|
406
|
-
|
|
407
|
-
```bash
|
|
408
|
-
# Regenerate all code after schema updates
|
|
409
|
-
npm run fetch-abis
|
|
410
|
-
npm run fetch-server-types
|
|
411
|
-
npm run codegen:subgraph
|
|
412
|
-
```
|
|
413
|
-
|
|
414
|
-
## Development
|
|
415
|
-
|
|
416
|
-
```bash
|
|
417
|
-
git clone https://github.com/vana-com/vana-sdk.git
|
|
418
|
-
cd vana-sdk
|
|
419
|
-
npm install
|
|
420
|
-
npm run build
|
|
421
|
-
npm test
|
|
422
|
-
```
|
|
138
|
+
Report issues on [GitHub Issues](https://github.com/vana-com/vana-sdk/issues).
|
|
423
139
|
|
|
424
140
|
## License
|
|
425
141
|
|
|
426
|
-
[ISC
|
|
142
|
+
[ISC](https://opensource.org/licenses/ISC)
|