Initializes a new VanaCore client instance with the provided configuration.
The platform adapter for environment-specific operations
The configuration object specifying wallet or chain settings
The constructor validates the configuration, initializes storage providers if configured, creates wallet and public clients, and sets up all SDK controllers with shared context.
IMPORTANT: This constructor will validate storage requirements at runtime to fail fast. Methods that require storage will throw runtime errors if storage is not configured.
ReadonlypermissionsManages gasless data access permissions and trusted server registry.
ReadonlydataHandles user data file operations.
ReadonlyschemasManages data schemas and refiners.
ReadonlyoperationsManages asynchronous operation recovery and status checking.
ReadonlyserverProvides personal server setup and trusted server interactions.
ReadonlyprotocolOffers low-level access to Vana protocol smart contracts.
The user's wallet address. In wallet mode, this always returns the current wallet account address. In read-only mode, this returns the static address provided during initialization.
Validates that storage is available for storage-dependent operations. This method enforces the fail-fast principle by checking storage availability at method call time rather than during expensive operations.
Type guard to check if this instance has storage enabled at compile time. Use this when you need TypeScript to understand that storage is available.
True if storage is configured, with type narrowing
Retrieves comprehensive runtime configuration information.
The current runtime configuration including chain, storage, and relayer settings
Sets the platform adapter for environment-specific operations. This is useful for testing and advanced use cases where you need to override the default platform detection.
The platform adapter to use
Gets the current platform adapter. This is useful for advanced use cases where you need to access the platform adapter directly.
The current platform adapter
Encrypts data using the Vana protocol standard encryption.
The data to encrypt (string or Blob)
The encryption key (typically generated via generateEncryptionKey)
The encrypted data as a Blob
This method implements the Vana network's standard encryption protocol using platform-appropriate cryptographic libraries. It automatically handles different input types (string or Blob) and produces encrypted output suitable for secure storage or transmission. The encryption is compatible with the network's decryption protocols and can be decrypted by authorized parties.
import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
// Generate encryption key from wallet signature
const encryptionKey = await generateEncryptionKey(vana.walletClient);
// Encrypt string data
const sensitiveData = "User's private information";
const encrypted = await vana.encryptBlob(sensitiveData, encryptionKey);
// Encrypt file data
const fileBlob = new Blob([fileContent], { type: 'application/json' });
const encryptedFile = await vana.encryptBlob(fileBlob, encryptionKey);
// Store encrypted data safely
await storageProvider.upload(encrypted, 'encrypted-data.bin');
Decrypts data that was encrypted using the Vana protocol.
The encrypted data (string or Blob)
The wallet signature used as decryption key
The decrypted data as a Blob
This method decrypts data that was previously encrypted using the Vana network's standard encryption protocol. It requires the same wallet signature that was used for encryption and automatically uses the appropriate platform adapter for cryptographic operations. The decrypted output maintains the original data format.
import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
// Retrieve encrypted data from storage
const encryptedBlob = await storageProvider.download('encrypted-data.bin');
// Generate the same key used for encryption
const decryptionKey = await generateEncryptionKey(vana.walletClient);
// Decrypt the data
const decrypted = await vana.decryptBlob(encryptedBlob, decryptionKey);
// Convert back to original format
const originalText = await decrypted.text();
const originalJson = JSON.parse(originalText);
console.log('Decrypted data:', originalJson);
// Decrypt file downloaded from Vana network
const userFiles = await vana.data.getUserFiles();
const file = userFiles[0];
// Download encrypted content
const encrypted = await fetch(file.url).then(r => r.blob());
// Decrypt with user's key
const decryptionKey = await generateEncryptionKey(vana.walletClient);
const decrypted = await vana.decryptBlob(encrypted, decryptionKey);
// Process original data
const fileContent = await decrypted.arrayBuffer();
Waits for an operation to complete and returns the final result.
Either an Operation object or operation ID string
Kind
Id
Status
Optionalstarted_at?: string | nullStarted At
Optionalfinished_at?: string | nullFinished At
Optionalresult?: { [key: string]: unknown } | nullResult
Optionaloptions: PollingOptionsOptional polling configuration
The completed operation with result or error
This method polls the operation status at regular intervals until it reaches a terminal state (succeeded, failed, or canceled). Supports ergonomic overloads to accept either an Operation object or just the ID.
// Using operation object
const operation = await vana.server.createOperation({ permissionId: 123 });
const completed = await vana.waitForOperation(operation);
// Using just the ID
const completed = await vana.waitForOperation("op_abc123");
// With custom timeout
const completed = await vana.waitForOperation(operation, {
timeout: 60000,
pollingInterval: 1000
});
Waits for a transaction to be confirmed and returns the receipt.
Either a TransactionResult object or hash string
Optionaloptions: TransactionWaitOptionsOptional wait configuration
The transaction receipt with logs and status
This method polls for transaction confirmation on the blockchain. Supports ergonomic overloads to accept either a transaction result object or just the hash string.
// Using transaction result object
const tx = await vana.permissions.grant(params);
const receipt = await vana.waitForTransactionReceipt(tx);
// Using just the hash
const receipt = await vana.waitForTransactionReceipt("0x123...");
// With custom confirmations
const receipt = await vana.waitForTransactionReceipt(tx, {
confirmations: 3,
timeout: 60000
});
Waits for transaction confirmation and extracts blockchain event data.
Transaction result with operation context
Optionaloptions: TransactionWaitOptionsOptional confirmation and timeout settings
Parsed event data specific to the transaction's operation type
This method leverages the context-carrying POJO architecture. When passed a
TransactionResult with an operation field, it automatically parses the
correct events from the transaction logs. For legacy compatibility, it accepts
raw hashes but will not parse events without operation context.
// Recommended: Pass the transaction result for automatic event parsing
const tx = await vana.permissions.submitAddServerFilesAndPermissions(params);
const events = await vana.waitForTransactionEvents<{ permissionId: bigint }>(tx);
console.log(`Permission ID: ${events.permissionId}`);
// Legacy: Raw hash without event parsing (returns receipt)
const receipt = await vana.waitForTransactionEvents("0x123...");
For understanding transaction flows, visit https://docs.vana.org/docs/transactions
Enhances a unified relayer response with client-side behavior.
The unified relayer response to enhance
EnhancedTransactionResponse if the response can be enhanced, null otherwise
This method wraps a relayer response in an enhanced object that provides
a fluent .wait() method for handling asynchronous operations. The enhanced
response intelligently handles both submitted transactions (via hash) and
pending operations (via operationId).
// Enhance a relayer response for fluent waiting
const response = await handleRelayerOperation(vana, request);
const enhanced = vana.enhanceRelayerResponse(response);
if (enhanced) {
const result = await enhanced.wait();
if (result.expectedEvents?.FileAdded) {
console.log('File ID:', result.expectedEvents.FileAdded.fileId);
}
}
Provides the core SDK functionality for interacting with the Vana network.
Remarks
This environment-agnostic class contains all SDK logic and accepts a platform adapter to handle environment-specific operations. It initializes all controllers and manages shared context between them, providing a unified interface for data management, permissions, smart contracts, and storage operations.
The class uses TypeScript overloading to enforce storage requirements at compile time. Methods that require storage will throw
InvalidConfigurationErrorat runtime if storage providers are not configured, implementing a fail-fast approach to prevent errors during expensive operations.Core Architecture:
For public usage, use the platform-specific factory functions:
import { Vana } from '@opendatalabs/vana-sdk/browser'import { Vana } from '@opendatalabs/vana-sdk/node'Example