Personal Data Vaults: Hive
What it is
Hive is Elastos’s decentralized storage layer. Instead of every app keeping your files and database rows on its servers, data can live in your vault on a Hive node you choose or run, while DID proves it is really you at the door.
How a Hive node is built
A typical Hive node is a Python service using the Flask web framework. It exposes a versioned REST API (for example under /api/v2). Internally:
- MongoDB holds structured data: vault records, collection documents, script metadata, and accounting.
- IPFS stores file payloads: uploads are content-addressed (the hash identifies the bytes), and the node pins content on an IPFS daemon that is usually co-located with the Hive service.
So one stack combines queryable document storage with immutable file blobs.
Anyone can run a Hive node—individuals, organizations, or commercial providers. Nodes expose an HTTP API that SDKs connect to, and they typically register on the EID chain so clients can discover them. Each node can host vaults for many users.
Operators configure MongoDB, IPFS, and payment keys through environment variables and config files; many deployments ship Docker Compose recipes so a contributor can stand up a full stack locally for testing.
For maximum sovereignty, run your own Hive node. See the Hive Node Deployment guide.
Vaults: one database per user and app
The central idea is a vault: a logical container tied to your user DID on a given node. A single DID can only have one active vault at a time. Within that vault, each application (identified by its app DID) gets isolated structured storage. Concretely, many deployments use a separate MongoDB database per pair (user_did, app_did), with a derived name such as a hash of those strings, so one chat app cannot read another app’s collections by accident.
| Component | Purpose |
|---|---|
| MongoDB collections | Structured data (JSON documents). Apps create collections for their data. |
| IPFS file storage | Binary files—images, videos, documents. |
| Scripts | Access control rules for sharing data with other DIDs. |
| Metadata | Vault subscription details, storage usage, backup status. |
Apps access the vault through the user’s DID; they do not need to know the physical location of the Hive node beyond resolving the provider.
Think “my cloud folder,” except the folder is keyed by cryptography and split per app, not per server rack owned by one corporation.
Vault subscription
Before using a vault, a user subscribes to a Hive node. The subscription typically determines:
- Storage quota—how much data the user can store
- Pricing tier—free or paid plans (the node operator sets this; see Pricing on Elastos Smart Chain)
- Vault URL—the endpoint apps connect to
The user records their vault provider URL in their DID Document, so any app can discover it.
Choosing a vault provider
Users choose where their data lives; vaults are not locked to a single hosting story.
| Option | Tradeoffs |
|---|---|
| Third-party Hive node | Easy setup; someone else runs the server. You trust that operator. |
| Self-hosted Hive node | Full control on your own hardware; more setup and operations. |
| Multiple nodes | One primary and another for backup—for redundancy and resilience. |
Once the vault provider URL is in the DID Document, the Hive SDK can discover the vault for that user.
Signing in: DID, challenge, and token
Hive does not use a classic username/password stored in a central table. Access uses DID-based authentication:
Application identity
Your app usually creates an App Instance DID (a DID representing the application). The user’s wallet can issue an App ID credential to that app DID. The app presents this material so the node can tie requests to an authorized application; the node can verify credentials against the user’s DID Document on EID where applicable.
Session flow
- The client starts a challenge (for example via
/api/v2/did/signin), sending material the node can validate. - The node returns a challenge (often a JWT) that includes a nonce and a short expiry, commonly on the order of three minutes to complete the next step.
- The client answers with a Verifiable Presentation (and related credentials) that proves control of the user DID and the app relationship.
- After validation, the node issues an access token (typically JWT) valid for a longer window, often up to about seven days, bounded by credential lifetimes where applicable.
- Later calls send
Authorization: Bearer …so the node knows which user and which app is acting.
No shared password database: just cryptography and chain-resolvable DIDs.
There are no usernames or passwords stored for vault access in the traditional sense. If the user’s DID and app authorization can be verified, the client can operate on the vault.
APIs: vault lifecycle, content, and files
Client SDKs talk to the same REST surface. In practice you will see route groups such as:
- Vault subscription / lifecycle: create or upgrade a vault, inspect usage, activate or deactivate (for example paths under
/api/v2/subscription/...). - Structured data: create collections and run CRUD and queries (paths under
/api/v2/vault/db/...). - Files: upload, download, list, and manage paths (paths under
/api/v2/vault/files/...).
Exact path names evolve with versions; always use the SDK or the node’s OpenAPI/docs for your deployment.
Through the SDKs, those capabilities map to four core services:
| Service | What it does |
|---|---|
| Database Service | CRUD on MongoDB collections—insert, find, update, delete JSON documents. |
| Files Service | Upload, download, list, and delete files (stored via IPFS on the node). |
| Scripting Service | Register and execute server-side scripts for controlled sharing between DIDs. |
| Backup Service | Configure, trigger, and restore cross-node backups. |
Typical data flow
A common end-to-end interaction looks like this:
- Authenticate—the app presents its DID credentials to the Hive node (challenge–response and tokens as above).
- Connect—the SDK reaches the user’s vault using the provider URL from the DID Document.
- Read/write—the app uses database or file operations through the SDK.
- Share—the vault owner configures scripts so other DIDs can access specific data under rules.
- Migrate—the user can move or promote vaults across nodes when needed (see Backup, migration, and promotion).
Scripting: server-side rules you define
Hive’s scripting engine lets a vault owner register named scripts that run on the server with conditions (who may call them) and executables (what queries or file operations run). Scripts are often defined with a JSON-based DSL on the node. Parameter substitution fills in values from the caller or environment (for example caller DID). Some scripts allow anonymous access, useful for public posts or downloads, while others require a full token. That combination is how you share selectively without handing out raw database passwords.
Typical use cases include social apps (e.g. friends read a profile but cannot edit it), marketplaces (buyers read listings without full vault access), and collaboration (team members write to a shared collection under constraints).
Backup, migration, and promotion
Backup vault
A backup vault is a secondary vault on a different Hive node. It provides redundancy: backups sync from the primary, and if the primary fails you can promote the backup so it becomes the new primary. Backup data is encrypted in transit and structured so the backup node operator cannot read the user’s plaintext contents—plan for key and policy implications as you would for any hosted encrypted backup.
Backup and restore (steps)
- Configure a backup vault on another node.
- Backups are encrypted and authenticated using the user’s DID material.
- If the primary node is unavailable, restore or promote from the backup.
Backups cover MongoDB collections and IPFS file references the vault uses.
Vault migration between nodes
You can move a vault from one node to another (related to backup/promotion flows):
- Set up a vault on the destination node.
- Initiate migration from the source node (or follow your operator’s documented path).
- Data transfers—collections, files, and scripts—as implemented by the node stack.
- Update the DID Document so the vault provider URL points at the new node.
Once migration completes, the source vault is typically deactivated. Confirm the destination node is healthy and reachable before finalizing.
Vaults remain portable: promotion and migration reduce lock-in to any single host.
Pricing on Elastos Smart Chain
Paid tiers are enforced via an ESC smart contract the node interacts with. Pricing and quotas are set by individual node operators and may vary. Check the node’s live payment_config endpoint for current plans and pricing.
Client SDKs
Applications integrate through official JavaScript/TypeScript, Java, and Swift SDKs. They all target the same REST API, so teams can mix mobile and web clients against one vault.
Security and trust: read this carefully
By default, data on the node is not end-to-end encrypted at rest in a way that hides it from the operator. The operator can, in principle, read what resides on disk unless you encrypt client-side before upload. SDKs support client-side encryption patterns for sensitive fields or files. For maximum sovereignty, run your own Hive node so you are the operator.
Treat Hive like a hosting environment: trustworthy for many apps, but not a magic black box. Encrypt what must stay secret, and self-host when policy requires it.
The user’s DID is the root of authorization. Apps cannot access vault data without the user’s cryptographic approval. If the user revokes access or credentials, the app loses access going forward.
IPFS and files
Files are stored as IPFS objects referenced from MongoDB metadata. The node acts as an IPFS gateway for vault operations: upload pins content through the node, download resolves by content address, and the node manages pinning and lifecycle so data stays available while the vault’s plan covers it. Because IPFS addresses content by hash, duplicates and integrity checks are straightforward.
Apps use the Hive SDK Files Service and the node’s API. You typically do not run your own IPFS daemon for basic vault file workflows—the co-located IPFS stack is part of the node deployment.
Where Hive sits in Elastos
A common flow is:
- DID proves who you are.
- Hive stores your data under that identity.
- Carrier (where deployed) can help peers find each other or stream data.
- Essentials (or another wallet) lets you manage vault providers, credentials, and signing in one place.
You are not choosing “Hive instead of DID.” You are choosing DID for authentication and Hive for persistence, with Essentials as a convenient console for many users.
Summary
Hive combines a Flask API, MongoDB for structured per-user-per-app data, and IPFS for files; nodes are discoverable on EID and host many users’ vaults. One active vault per DID, with subscription, provider choice, and DID Document discovery. Authentication blends app instance DIDs, credentials, and challenge–response with verifiable presentations, short-lived challenges and longer JWT sessions. REST groups cover vault lifecycle, CRUD, and files, mirrored by Database, Files, Scripting, and Backup SDK services. Scripting (including a JSON DSL and optional anonymous access) enables selective sharing. Backup vaults (encrypted from the backup operator’s view), promotion, and migration (with source deactivation risk) support portability. ESC-mediated pricing and multi-language SDKs round out the stack. Trust model: primary-node operators see plaintext unless you encrypt—plan accordingly and self-host when you must own the full stack.