Uploads data with automatic encryption and blockchain registration.
Upload configuration object
Upload parameters with encryption enabled.
Raw file data as string, Blob, or Buffer.
Optionalfilename?: stringOptional filename for the uploaded file.
OptionalschemaId?: numberOptional schema ID for data validation.
OptionalproviderName?: stringOptional storage provider name.
Optionalowner?: `0x${string}`Optional owner address (defaults to current wallet address).
OptionalschemaValidation?: "strict" | "warn" | "skip"Schema validation mode when schemaId is provided:
Optionalpermissions?: FilePermissionParams[]File permissions with required public keys for encrypted data sharing.
Encryption is enabled.
Upload result with file ID, URL, and transaction hash
Primary method for uploading data to Vana. Handles complete workflow: content normalization, schema validation, encryption, storage upload, permission granting, and blockchain registration.
Automatic Processing:
TypeScript Overloads:
EncryptedUploadParams: When encrypt: true (default), permissions require publicKeyUnencryptedUploadParams: When encrypt: false, permissions optionalUploadParams: General signature for runtime determinationPermission Separation:
vana.permissions.grant() separatelyOwner/Encryption Constraint:
When encryption is enabled (default), the owner parameter must match
the connected wallet address. This ensures only the wallet that performs
encryption can decrypt the file. For delegation scenarios where the owner
differs from the connected wallet, set encrypt: false.
When encryption is enabled and owner differs from wallet.
Set encrypt: false for delegation scenarios, or omit owner to use connected wallet.
Data doesn't match schema.
Verify data structure matches schema from vana.schemas.get(schemaId).
// Basic file upload
const result = await vana.data.upload({
content: "My personal data",
filename: "diary.txt"
});
// Upload with schema validation
const result = await vana.data.upload({
content: { name: "John", age: 30 },
filename: "profile.json",
schemaId: 1
});
// Upload with file permissions (for decryption access)
const result = await vana.data.upload({
content: "Data for AI analysis",
filename: "analysis.txt",
permissions: [{
account: "0x1234...", // Server address that can decrypt
publicKey: "0x04..." // Server's public key for encryption
}]
});
// After upload, grant operation permissions separately:
// await vana.permissions.grant({
// grantee: "0x1234...",
// fileIds: [result.fileId],
// operation: "llm_inference",
// parameters: { model: "gpt-4" }
// });
// Upload without encryption (public data)
// Note: Cast to UnencryptedUploadParams for TypeScript
const result = await vana.data.upload({
content: "Public data",
filename: "public.txt",
encrypt: false
} as const); // 'as const' ensures TypeScript infers encrypt: false literally
// Upload on behalf of another user (delegation without encryption)
const result = await vana.data.upload({
content: "User's data",
filename: "delegated.txt",
owner: "0x5678...", // Different from connected wallet
encrypt: false // Required when owner differs from wallet
});
Uploads data with automatic encryption and blockchain registration.
Upload configuration object
Upload parameters with encryption disabled.
Raw file data as string, Blob, or Buffer.
Optionalfilename?: stringOptional filename for the uploaded file.
OptionalschemaId?: numberOptional schema ID for data validation.
Optionalpermissions?: FilePermissionParams[]Optional file permissions to grant decryption access during upload.
OptionalproviderName?: stringOptional storage provider name.
Optionalowner?: `0x${string}`Optional owner address (defaults to current wallet address).
OptionalschemaValidation?: "strict" | "warn" | "skip"Schema validation mode when schemaId is provided:
Encryption is disabled.
Upload result with file ID, URL, and transaction hash
Primary method for uploading data to Vana. Handles complete workflow: content normalization, schema validation, encryption, storage upload, permission granting, and blockchain registration.
Automatic Processing:
TypeScript Overloads:
EncryptedUploadParams: When encrypt: true (default), permissions require publicKeyUnencryptedUploadParams: When encrypt: false, permissions optionalUploadParams: General signature for runtime determinationPermission Separation:
vana.permissions.grant() separatelyOwner/Encryption Constraint:
When encryption is enabled (default), the owner parameter must match
the connected wallet address. This ensures only the wallet that performs
encryption can decrypt the file. For delegation scenarios where the owner
differs from the connected wallet, set encrypt: false.
When encryption is enabled and owner differs from wallet.
Set encrypt: false for delegation scenarios, or omit owner to use connected wallet.
Data doesn't match schema.
Verify data structure matches schema from vana.schemas.get(schemaId).
// Basic file upload
const result = await vana.data.upload({
content: "My personal data",
filename: "diary.txt"
});
// Upload with schema validation
const result = await vana.data.upload({
content: { name: "John", age: 30 },
filename: "profile.json",
schemaId: 1
});
// Upload with file permissions (for decryption access)
const result = await vana.data.upload({
content: "Data for AI analysis",
filename: "analysis.txt",
permissions: [{
account: "0x1234...", // Server address that can decrypt
publicKey: "0x04..." // Server's public key for encryption
}]
});
// After upload, grant operation permissions separately:
// await vana.permissions.grant({
// grantee: "0x1234...",
// fileIds: [result.fileId],
// operation: "llm_inference",
// parameters: { model: "gpt-4" }
// });
// Upload without encryption (public data)
// Note: Cast to UnencryptedUploadParams for TypeScript
const result = await vana.data.upload({
content: "Public data",
filename: "public.txt",
encrypt: false
} as const); // 'as const' ensures TypeScript infers encrypt: false literally
// Upload on behalf of another user (delegation without encryption)
const result = await vana.data.upload({
content: "User's data",
filename: "delegated.txt",
owner: "0x5678...", // Different from connected wallet
encrypt: false // Required when owner differs from wallet
});
Uploads data with automatic encryption and blockchain registration.
Upload configuration object
High-level parameters for uploading user data with automatic encryption and blockchain registration.
Raw file data as string, Blob, or Buffer.
Optionalfilename?: stringOptional filename for the uploaded file.
OptionalschemaId?: numberOptional schema ID for data validation.
Optionalpermissions?: FilePermissionParams[]Optional file permissions to grant decryption access during upload.
Optionalencrypt?: booleanWhether to encrypt the data (defaults to true).
OptionalproviderName?: stringOptional storage provider name.
Optionalowner?: `0x${string}`Optional owner address (defaults to current wallet address).
OptionalschemaValidation?: "strict" | "warn" | "skip"Schema validation mode when schemaId is provided:
Upload result with file ID, URL, and transaction hash
Primary method for uploading data to Vana. Handles complete workflow: content normalization, schema validation, encryption, storage upload, permission granting, and blockchain registration.
Automatic Processing:
TypeScript Overloads:
EncryptedUploadParams: When encrypt: true (default), permissions require publicKeyUnencryptedUploadParams: When encrypt: false, permissions optionalUploadParams: General signature for runtime determinationPermission Separation:
vana.permissions.grant() separatelyOwner/Encryption Constraint:
When encryption is enabled (default), the owner parameter must match
the connected wallet address. This ensures only the wallet that performs
encryption can decrypt the file. For delegation scenarios where the owner
differs from the connected wallet, set encrypt: false.
When encryption is enabled and owner differs from wallet.
Set encrypt: false for delegation scenarios, or omit owner to use connected wallet.
Data doesn't match schema.
Verify data structure matches schema from vana.schemas.get(schemaId).
// Basic file upload
const result = await vana.data.upload({
content: "My personal data",
filename: "diary.txt"
});
// Upload with schema validation
const result = await vana.data.upload({
content: { name: "John", age: 30 },
filename: "profile.json",
schemaId: 1
});
// Upload with file permissions (for decryption access)
const result = await vana.data.upload({
content: "Data for AI analysis",
filename: "analysis.txt",
permissions: [{
account: "0x1234...", // Server address that can decrypt
publicKey: "0x04..." // Server's public key for encryption
}]
});
// After upload, grant operation permissions separately:
// await vana.permissions.grant({
// grantee: "0x1234...",
// fileIds: [result.fileId],
// operation: "llm_inference",
// parameters: { model: "gpt-4" }
// });
// Upload without encryption (public data)
// Note: Cast to UnencryptedUploadParams for TypeScript
const result = await vana.data.upload({
content: "Public data",
filename: "public.txt",
encrypt: false
} as const); // 'as const' ensures TypeScript infers encrypt: false literally
// Upload on behalf of another user (delegation without encryption)
const result = await vana.data.upload({
content: "User's data",
filename: "delegated.txt",
owner: "0x5678...", // Different from connected wallet
encrypt: false // Required when owner differs from wallet
});
Encrypts data using wallet-derived encryption.
The data to encrypt (Blob, string, or object)
Optionaloptions: EncryptFileOptionsOptional encryption configuration
Promise resolving to encrypted data and the encryption key used
This method provides secure, wallet-based encryption for data before uploading to the Vana network. It's the counterpart to decryptFile for preparing data for secure storage.
The method automatically:
The encryption key returned can be stored and later used for decryption, or shared with others to grant them decryption access.
// Encrypt a string
const { encryptedData, encryptionKey } = await vana.data.encryptFile(
"My secret data"
);
// Encrypt JSON with custom MIME type
const { encryptedData, encryptionKey } = await vana.data.encryptFile(
{ name: "Alice", age: 30 },
{ mimeType: "application/json" }
);
// With custom encryption seed
const { encryptedData, encryptionKey } = await vana.data.encryptFile(
"Secret message",
{ seed: "My custom encryption seed" }
);
// Upload the encrypted data
const result = await vana.data.uploadToStorage(encryptedData);
Decrypts a file using wallet-derived decryption key.
UserFile object from getUserFiles()
Optionaloptions: DecryptFileOptionsDecryption options
Options for decrypting a file
Optionalseed?: stringEncryption seed for key derivation. Defaults to DEFAULT_ENCRYPTION_SEED
Decrypted content as Blob
Counterpart to upload() for decrypting user files. Automatically
generates decryption key from wallet, fetches encrypted content,
and decrypts. Supports IPFS (with gateway fallback) and HTTP URLs.
// Basic file decryption
const files = await vana.data.getUserFiles({ owner: userAddress });
const decryptedBlob = await vana.data.decryptFile(files[0]);
// Convert to text
const text = await decryptedBlob.text();
console.log('Decrypted content:', text);
// Convert to JSON
const json = JSON.parse(await decryptedBlob.text());
console.log('Decrypted data:', json);
// With custom encryption seed
const decryptedBlob = await vana.data.decryptFile(
files[0],
"My custom encryption seed"
);
// Save to file (in Node.js)
const buffer = await decryptedBlob.arrayBuffer();
fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
Retrieves all files owned by a specific user address.
Query configuration
Wallet address of the file owner
OptionalsubgraphUrl?: stringSubgraph endpoint override. Defaults to context configuration.
Optionaloptions: ConsistencyOptions & PaginationOptionsArray of UserFile objects sorted by timestamp (newest first)
Retrieves information about a specific Data Liquidity Pool (DLP).
The unique identifier of the DLP
Optional parameters
OptionalsubgraphUrl?: stringCustom subgraph URL to override default
OptionalminBlock?: numberOptionalwaitForSync?: numberPromise resolving to DLP information
Lists all Data Liquidity Pools (DLPs) with optional pagination.
Optional parameters for pagination and filtering
Optionallimit?: numberMaximum number of DLPs to return (default: 100)
Optionaloffset?: numberNumber of DLPs to skip (default: 0)
OptionalsubgraphUrl?: stringCustom subgraph URL to override default
Promise resolving to array of DLP information
Retrieves a list of permissions granted by a user.
This method supports automatic fallback between subgraph and RPC modes:
Object containing the user address and optional subgraph URL
The wallet address of the user to query permissions for
OptionalsubgraphUrl?: stringOptional subgraph URL to override the default
Optionaloptions: ConsistencyOptions & PaginationOptionsPromise resolving to an array of permission objects
Retrieves a list of trusted servers for a user.
This method supports automatic fallback between subgraph and RPC modes:
Query parameters including user address and optional pagination
Parameters for getUserTrustedServers method
User address to query trusted servers for
OptionalsubgraphUrl?: stringOptional subgraph URL to override default
Optionaloptions: ConsistencyOptions & PaginationOptionsPromise resolving to an array of trusted server objects
// Basic usage with automatic fallback
const servers = await vana.data.getUserTrustedServers({
user: '0x...'
});
// With pagination
const servers = await vana.data.getUserTrustedServers({
user: '0x...',
limit: 10,
offset: 20
});
// With custom subgraph URL
const servers = await vana.data.getUserTrustedServers({
user: '0x...',
subgraphUrl: 'https://custom-subgraph.com/graphql'
});
Retrieves file metadata by ID from the blockchain.
Numeric file ID to retrieve
UserFile object with metadata
Registers a file URL directly on the blockchain with a schema ID.
The URL of the file to register (IPFS or HTTP/HTTPS)
The schema ID to associate with the file
Optionaloptions: TransactionOptionsPromise resolving to the file ID and transaction hash
Adds a file with permissions to the DataRegistry contract.
The file URL to register
The address of the file owner
Array of permissions to set for the file
Optionaloptions: TransactionOptionsPromise resolving to file ID and transaction hash
Adds a file to the registry with permissions and schema. This combines the functionality of addFileWithPermissions and schema validation.
The URL of the file to register
The address of the file owner
Array of permissions to grant, each with account and publicKey properties
The schema ID to associate with the file (0 for no schema)
Optionaloptions: TransactionOptionsPromise resolving to TransactionResult with fileId and transactionHash
This method automatically encrypts permissions when a publicKey is provided. It generates the user's encryption key and encrypts it with each recipient's public key before registering on the blockchain.
// Get server's public key
const serverIdentity = await vana.server.getIdentity({
userAddress: "0x..."
});
// Add file with permissions and schema
const result = await vana.data.addFileWithPermissionsAndSchema(
"ipfs://QmXxx...",
ownerAddress,
[{
account: serverIdentity.address,
publicKey: serverIdentity.publicKey
}],
schemaId
);
console.log(`File ${result.fileId} registered in tx ${result.hash}`);
Adds a file with pre-encrypted permissions and schema to the DataRegistry.
The storage URL of the file (e.g., IPFS URL)
The address that will own this file
Array of pre-encrypted permissions with 'account' and 'key' fields
Optional schema ID for data validation (defaults to 0)
Optionaloptions: TransactionOptionsPromise resolving to transaction result with hash and contract details
This method is designed for relay services and advanced use cases where permissions
have already been encrypted client-side. Unlike addFileWithPermissionsAndSchema(),
this method expects permissions in the encrypted format with a 'key' field instead
of 'publicKey'.
This is typically used by relay endpoints that receive pre-encrypted data from
the client SDK's upload() method, avoiding double encryption.
// In a relay endpoint that receives pre-encrypted permissions
const result = await vana.data.addFileWithEncryptedPermissionsAndSchema(
"ipfs://QmXxx...",
ownerAddress,
[
{
account: "0xServerAddress...",
key: "encrypted_key_string" // Already encrypted by client
}
],
schemaId
);
console.log(`File registered in tx ${result.hash}`);
Registers a data refiner for processing templates.
Refiner configuration
Parameters for registering a new data refiner in the Vana network.
Refiners are processors that transform and validate user data according to specific schemas and instructions. They enable applications to work with structured, verified user data while maintaining privacy and user control.
DLP ID this refiner belongs to
Refiner name
Schema ID to associate with this refiner
URL containing refinement instructions
Optionaloptions: TransactionOptionsRefiner ID and transaction hash
Retrieves refiner configuration by ID.
Numeric refiner ID
Refiner configuration object
Validates schema ID existence.
Numeric schema ID to validate
True if schema exists, false otherwise
Gets the total number of refiners in the registry.
Promise resolving to the total refiner count
Updates the schema ID for an existing refiner.
Update parameters
Parameters for updating a refiner's schema ID
Refiner ID to update
New schema ID to associate with the refiner
Optionaloptions: TransactionOptionsPromise resolving to the transaction hash
Uploads an encrypted file and grants permission to a party with a public key.
This method handles the complete workflow:
Upload parameters including data, permissions, and options
Promise resolving to upload result with file ID and storage URL
Uploads content to storage without registering it on the blockchain. This method only handles the storage upload and returns the file URL.
The content to upload (string, Blob, Buffer, or object - objects will be JSON stringified)
Optionalfilename: stringOptional filename for the uploaded file (defaults to timestamp-based name)
Optional flag to encrypt the content before upload
OptionalproviderName: stringOptional specific storage provider to use
Promise resolving to the storage upload result with url, size, and contentType
Adds a permission for a party to access an existing file.
This method handles the complete workflow:
For advanced users who need more control over transaction timing,
use submitFilePermission() instead.
Parameters for adding file permission
Parameters for adding permission to a file
The file ID to grant permission for
The account to grant permission to
The public key of the account for encryption
Optionaloptions: TransactionOptionsPromise resolving to permission data from PermissionGranted event
Submits a file permission transaction to the blockchain.
The ID of the file to grant permission for
The recipient's wallet address that will access the file
The recipient's public key for encryption.
Obtain via vana.server.getIdentity(account).publicKey
Optionaloptions: TransactionOptionsPromise resolving to TransactionResult for tracking the transaction
Gets the encrypted key for a specific account's permission to access a file.
The ID of the file
The account address to get the permission for
Promise resolving to the encrypted key for that account
Decrypts a file that the user has permission to access using their private key.
This method handles the complete workflow for servers or other permitted parties:
The file to decrypt
The private key to decrypt the user's encryption key
Optionaloptions: DecryptFileWithPermissionOptionsOptional decryption configuration
Options for decrypting a file with permission
Optionalaccount?: `0x${string}`Optional account address to verify permission against
Promise resolving to the decrypted file data
Simple network-agnostic fetch utility for retrieving file content.
The URL to fetch content from
Promise resolving to the fetched content as a Blob
This is a thin wrapper around the global fetch API that returns the response as a Blob. It provides a consistent interface for fetching encrypted content before decryption. For IPFS URLs, consider using fetchFromIPFS for better reliability.
// Fetch and decrypt a file
const encryptionKey = await generateEncryptionKey(walletClient);
const encryptedBlob = await vana.data.fetch(file.url);
const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
// With custom headers for authentication
const response = await fetch(file.url, {
headers: { 'Authorization': 'Bearer token' }
});
const encryptedBlob = await response.blob();
Specialized IPFS fetcher with gateway fallback mechanism.
The IPFS URL (ipfs://...) or CID to fetch
Optionaloptions: { gateways?: string[] }Optional configuration
Optionalgateways?: string[]Array of IPFS gateway URLs to try (must end with /)
Promise resolving to the fetched content as a Blob
This method provides robust IPFS content fetching by trying multiple gateways in sequence until one succeeds. It supports both ipfs:// URLs and raw CIDs.
The default gateway list includes public gateways, but you should provide your own gateways for production use to ensure reliability and privacy.
// Fetch from IPFS with custom gateways
const encryptedBlob = await vana.data.fetchFromIPFS(file.url, {
gateways: [
'https://my-private-gateway.com/ipfs/',
'https://dweb.link/ipfs/',
'https://ipfs.io/ipfs/'
]
});
// Decrypt the fetched content
const encryptionKey = await generateEncryptionKey(walletClient);
const decryptedBlob = await decryptBlob(encryptedBlob, encryptionKey, platform);
// With raw CID
const blob = await vana.data.fetchFromIPFS('QmXxx...', {
gateways: ['https://ipfs.io/ipfs/']
});
Validates a data schema definition against the Vana meta-schema.
The data schema definition to validate
The validated DataSchema
Validates data against a JSON Schema from a data schema.
The data to validate
The data schema containing the schema
Void (throws if validation fails)
Fetches and validates a data schema from a URL, then returns the parsed data schema.
The URL to fetch the data schema from
The validated data schema
// Fetch and validate a schema from IPFS or HTTP
const schema = await vana.data.fetchAndValidateSchema("https://example.com/schema.json");
console.log(schema.name, schema.dialect);
// Use the schema to validate user data
if (schema.dialect === "json") {
vana.data.validateDataAgainstSchema(userData, schema);
}
Manages encrypted user data files and blockchain registration on the Vana network.
Remarks
The DataController provides comprehensive file lifecycle management from encrypted upload through blockchain registration to decryption. Client-side encryption ensures data privacy before transmission. The controller integrates with multiple storage providers (IPFS, Pinata, Google Drive) and supports both gasless transactions via relayers and direct blockchain interaction.
Architecture: Files use dual storage: encrypted content on decentralized storage (IPFS/Pinata/Google Drive), metadata and permissions on blockchain. This design minimizes on-chain data while maintaining decentralization and access control.
Method Selection:
upload()- Complete workflow: encryption, storage, blockchain registrationgetUserFiles()- Query file metadata from blockchain/subgraphdecryptFile()- Decrypt files you have permission to accessgetFileById()- Retrieve specific file metadata by IDStorage Requirements:
upload(),encryptFile()getUserFiles(),decryptFile(),getFileById()Permission Model:
vana.permissions.grant()Example
See
For conceptual overview, visit https://docs.vana.org/docs/data-registry