Retrieves cryptographic identity for a personal server.
Identity request parameters
Defines parameters for initializing personal server connections.
Identifies the user whose personal server to connect to. Must be a valid Ethereum address in hex format.
Server identity with public key and metadata
Fetches public key and metadata required for data encryption. Identity cached by infrastructure for offline retrieval. Each user address maps to deterministic server identity.
const identity = await vana.server.getIdentity({
userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
});
console.log(`Server: ${identity.name}`);
console.log(`Address: ${identity.address}`);
console.log(`Public Key: ${identity.publicKey}`);
// Use for encryption before data sharing
const encrypted = await encryptWithPublicKey(
data,
identity.publicKey
);
Creates a server operation and returns its details from the OpenAPI schema.
The operation request parameters
Defines parameters for creating server-side operations.
References the permission scope for this operation. Determines what data and actions are allowed.
Server response with operation ID
Retrieves the current status and result of a server operation.
The ID of the operation to query
The operation status response from the server
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 and timestamp data
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. Returns the server response directly from the OpenAPI schema.
// Using operation object
const operation = await vana.server.createOperation({ permissionId: 123 });
const completed = await vana.server.waitForOperation(operation);
// Using just the ID
const completed = await vana.server.waitForOperation("op_abc123");
// With custom timeout
const completed = await vana.server.waitForOperation(operation, {
timeout: 60000,
pollingInterval: 1000
});
// Access server-provided timestamps
console.log('Started:', completed.started_at);
console.log('Finished:', completed.finished_at);
Downloads an artifact generated by a server operation.
The download parameters
Parameters for downloading an artifact from a server operation.
The operation ID that generated the artifact.
The path to the artifact file to download.
A Blob containing the artifact data
Artifacts are files generated during operations like Gemini agent analysis. The download requires authentication using the application's signature. This method returns the artifact as a Blob that can be saved or processed.
Simplified Signature Scheme: The signature is generated over the operation ID only, allowing a single signature to be reused for listing and downloading multiple artifacts from the same operation. This simplifies client implementation while maintaining security - access to the operation ID grants access to all artifacts.
// Download an artifact after a Gemini operation
const blob = await vana.server.downloadArtifact({
operationId: 'op_123',
artifactPath: 'analysis_report.pdf'
});
// Save to file in Node.js
const buffer = await blob.arrayBuffer();
fs.writeFileSync('report.pdf', Buffer.from(buffer));
// Or create download link in browser
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'report.pdf';
a.click();
Lists all artifacts generated by a server operation.
The operation ID that generated the artifacts
Promise resolving to array of artifact metadata objects
Retrieves metadata for all artifact files produced by an operation, including file paths, sizes, and content types. This provides visibility into available outputs without downloading them.
Simplified Signature Scheme: Uses the same signature as downloadArtifact - signs only operation_id. This allows reusing the same signature for listing and downloading.
// List artifacts from a Gemini operation
const artifacts = await vana.server.listArtifacts('op_123');
console.log(`Found ${artifacts.length} artifacts:`);
artifacts.forEach(artifact => {
console.log(`- ${artifact.path} (${artifact.size} bytes)`);
});
// Download a specific artifact
const blob = await vana.server.downloadArtifact({
operationId: 'op_123',
artifactPath: artifacts[0].path
});
Cancels a running operation on the personal server.
The unique identifier of the operation to cancel,
obtained from createOperation() response
Promise that resolves when the cancellation request is accepted
This method attempts to cancel an operation that is currently processing
on the personal server. The operation must be in a cancellable state
(typically starting or processing). Not all operations support
cancellation, and cancellation may not be immediate. The server will
attempt to stop the operation and update its status to canceled.
Cancellation Behavior:
succeeded or failed states cannot be canceledWhen the operation cannot be canceled or doesn't exist. Check operation status - it may already be completed or failed.
// Start a long-running operation
const operation = await vana.server.createOperation({
permissionId: 123
});
// Cancel if needed
try {
await vana.server.cancelOperation(operation.id);
console.log("Cancellation requested");
// Verify cancellation
const status = await vana.server.getOperation(operation.id);
if (status.status === "canceled") {
console.log("Operation successfully canceled");
}
} catch (error) {
console.error("Failed to cancel:", error);
}
Manages personal server interactions for secure data processing.
Remarks
Handles communication with personal servers for computation requests and identity retrieval. Personal servers process user data with cryptographic verification, ensuring privacy and permission compliance.
Architecture: Servers use deterministic key derivation from user addresses. Identity cached for offline retrieval. Operations authenticated via wallet signatures and permission verification.
Method Selection:
getIdentity()- Retrieve server public key for encryptioncreateOperation()- Submit computation with permission IDgetOperation()- Check status and retrieve resultswaitForOperation()- Poll until completion or timeoutcancelOperation()- Stop running operationsTypical Workflow:
Example
See
For conceptual overview, visit https://docs.vana.org/docs/personal-servers