The Data Portability Protocol encrypts user data before it leaves the Personal Server. This page covers how encryption keys are derived, how data is encrypted, where encrypted blobs are stored, and how multiple Personal Server instances stay in sync.
Key derivation
Encryption keys are deterministically derived from the user’s wallet signature. This means any Personal Server instance with the correct signature can decrypt the user’s data — no key exchange required.
Derivation chain
Wallet
→ EIP-191 personal_sign("vana-master-key-v1")
→ raw signature bytes (master key material)
→ HKDF-SHA256(master_key_material, "vana", "scope:{scope}")
→ 32-byte scope key
→ hex(scope_key) = encryption password
Step by step
-
Master key material. The user signs the fixed message
"vana-master-key-v1" using EIP-191 personal_sign. The raw signature bytes become the master key material. This happens once — when the user first opens the Desktop App or when enabling ODL Cloud.
-
Scope key. For each scope, a 32-byte scope key is derived using HKDF-SHA256:
scope_key = HKDF-SHA256(
ikm: master_key_material,
salt: "vana",
info: "scope:{scope}"
)
instagram.profile produces HKDF-SHA256(master_key_material, "vana", "scope:instagram.profile").
-
Encryption password. The scope key is hex-encoded to a 64-character string, which serves as the password for OpenPGP symmetric encryption.
Changing a scope name changes the derived key. If a scope is renamed, existing encrypted data for that scope cannot be decrypted with the new key. Keep scope names stable.
Key derivation stability
The derivation inputs are versioned and stable:
- Signed message:
"vana-master-key-v1" — the v1 suffix is a version marker.
- HKDF salt:
"vana" (fixed).
- HKDF info:
"scope:{scope}" (deterministic from scope name).
These inputs are part of the protocol specification. They will not change without a major protocol version bump. If a future version introduces a new derivation (e.g. v2), Personal Servers will support both versions during a migration window so existing encrypted data remains accessible.
Builders do not manage encryption keys — the Personal Server and Desktop App handle all key derivation, encryption, and decryption internally. Builders read plaintext data from the Personal Server API; the encryption layer is transparent.
What the Personal Server needs
The Personal Server does not need the user’s wallet private key. It only needs the master key signature (the output of personal_sign). For desktop-bundled servers, the user signs on app open. For ODL Cloud, the signature is stored encrypted in the Sprite (see delegated signature).
Encryption
The protocol uses OpenPGP password-based symmetric encryption.
How it works
- Take the plaintext JSON data file
- Derive the scope key for the file’s scope
- Hex-encode the scope key to get the encryption password
- Encrypt the entire JSON as a single OpenPGP message using the password
The output is a standard OpenPGP binary message. No plaintext metadata is stored alongside the ciphertext — the entire file envelope (including scope, collectedAt, and data) is encrypted as one blob.
Encryption requirements by hosting option
| Hosting option | Encrypted at rest? | Rationale |
|---|
| ODL Cloud (Vana-hosted) | Must encrypt | Blind infrastructure — Vana must not access plaintext |
| Desktop-bundled | May store unencrypted | User’s device is the security zone |
| Self-hosted | User’s choice | User controls the infrastructure |
Storage backends
Storage backends hold encrypted data blobs. The Personal Server encrypts data before upload and decrypts on download — the backend never sees plaintext.
Users select one storage backend for all their data (per-user, not per-file). The selection is made during Desktop App setup and stored in ~/.vana/server.json. Until a backend is selected, the Personal Server operates in local-only mode with no remote storage or DataRegistry writes.
Available backends
| Backend | URL format | Notes |
|---|
| Vana Storage (default) | https://storage.vana.com/v1/blobs/{owner}/{scope}/{collectedAt} | Managed by Vana, zero-config |
| Google Drive | gdrive://{fileId} | User authorizes via OAuth |
| Dropbox | dropbox://{path} | User authorizes via OAuth |
| IPFS | ipfs://{cid} | Content-addressed, immutable |
Backend requirements
Every storage backend must:
- Accept only encrypted blobs
- Authenticate requests (verify the requester is authorized)
- Support hierarchical key format
- Return a canonical URL after upload
Backend interface
interface StorageBackend {
upload(key: string, data: Uint8Array): Promise<string>;
download(url: string): Promise<Uint8Array>;
delete(url: string): Promise<boolean>;
exists(url: string): Promise<boolean>;
deleteScope?(scope: string): Promise<number>;
deleteAll?(): Promise<number>;
}
Server configuration
Storage backend selection and OAuth tokens are stored in ~/.vana/server.json:
{
"version": "1.0",
"server": {
"address": "0x...",
"url": "https://user-abc.server.vana.com",
"capabilities": {
"mcp": true,
"compute": true
}
},
"storage": {
"backend": "vana",
"config": {},
"oauth": {
"gdrive": { "accessToken": "...", "refreshToken": "...", "expiresAt": "..." },
"dropbox": { "accessToken": "...", "refreshToken": "...", "expiresAt": "..." }
}
},
"sync": {
"lastProcessedTimestamp": "2026-01-21T10:00:00Z"
}
}
backend field accepts: vana, gdrive, dropbox, ipfs, or local.
Data flow
When new data is collected:
- Data Connector collects data from a platform
- Desktop App sends raw data to the Personal Server via
POST /v1/data/{scope}
- Personal Server stores the data locally (unencrypted) at
~/.vana/data/{scope}/
- Personal Server encrypts the data with the scope key
- Encrypted blob is uploaded to the storage backend
- File record is registered in the DataRegistry via the Gateway (with
schemaId)
If no storage backend is selected, steps 4-6 are skipped and data remains local-only.
Data sync
When a user has multiple Personal Server instances (e.g. desktop-bundled + ODL Cloud), they stay in sync through the storage backend and Data Registry. The storage backend is the source of truth for encrypted data; each Personal Server maintains a local decrypted copy.
How sync works
Each Personal Server polls the Gateway for new file records using a lastProcessedTimestamp cursor:
GET /v1/files?user={address}&since={lastProcessedTimestamp}
- Download the encrypted blob from the storage backend
- Resolve the
schemaId to the canonical scope (via GET /v1/schemas/{schemaId})
- Derive the scope key and decrypt
- Read
scope and collectedAt from the decrypted payload
- Store locally at
~/.vana/data/{scope}/{collectedAt}.json
- Update the local index (
fileId → path, scope, collectedAt)
First activation
When a Personal Server starts for the first time (e.g. when a user enables ODL Cloud), it runs a full backfill:
- Query the Gateway for all file records for the user
- Download, decrypt, and index each file
- Set
lastProcessedTimestamp to the most recent record
Conflict resolution
If two instances write to the same scope concurrently, the last-write-wins strategy applies based on the collectedAt timestamp in the payload.
Sync API (internal)
The Personal Server exposes internal sync endpoints:
| Method | Path | Description |
|---|
POST | /v1/sync/trigger | Force a sync from the storage backend |
GET | /v1/sync/status | Get sync status (last sync, pending files, errors) |
POST | /v1/sync/file/{fileId} | Sync a specific file from the storage backend |
Before storage backend selection
Until the user selects a storage backend, sync is disabled. Data exists only on the local Personal Server instance, and no DataRegistry writes occur.
Data deletion
DataRegistry file entries are immutable — you cannot remove a record from the chain. Deletion is implemented as:
- Delete the encrypted blob from the storage backend
- Remove the local decrypted copy
- Write a tombstone / delete marker via the Gateway
Personal Servers treat tombstoned file records as non-existent and return 410 Gone or 404 Not Found.
Data deletion is user-initiated only. Builders cannot delete user data.
