Storage Protocol

Hive Architecture

Repo: Elastos.Hive.Node Backend: Python / Flask Database: MongoDB (per-user sandboxed) File Storage: IPFS with local cache Auth: DID challenge-response → JWT

┌─────────────────────────────────────────────────────┐
│                    dApp (Application)                │
│         uses JS/Java/Swift SDK to talk to Hive      │
└──────────────┬──────────────────────┬───────────────┘
               │ REST API (HTTPS)     │
               │ /api/v2/*            │
               ▼                      ▼
┌──────────────────────┐   ┌────────────────────────────┐
│    Hive Node A       │   │      Hive Node B           │
│  (User's Vault)      │◄──│  (Backup Node)             │
│                      │   │                            │
│  ┌────────────────┐  │   │  Internal backup APIs      │
│  │ Flask REST API │  │   │  Node-to-node auth         │
│  └──────┬─────────┘  │   └────────────────────────────┘
│         │            │
│  ┌──────▼─────────┐  │
│  │  Auth Module   │  │  DID Document + VP/VC
│  │  (DID-based)   │──│──────► EID Chain
│  └──────┬─────────┘  │
│         │            │
│  ┌──────▼─────────┐  │
│  │  Vault Manager │  │  Storage quotas, plans
│  └──────┬─────────┘  │
│         │            │
│    ┌────┴────┐       │
│    │         │       │
│  ┌─▼──┐  ┌──▼──┐    │
│  │ DB │  │Files│    │
│  └─┬──┘  └──┬──┘    │
│    │        │        │
│  ┌─▼────┐ ┌─▼────┐  │
│  │Mongo │ │ IPFS │  │
│  │ DB   │ │ Node │  │
│  └──────┘ └──────┘  │
└──────────────────────┘

Authentication Protocol

DID-based challenge-response authentication:

1. Client → Node:   POST /api/v2/did/signin
                     Body: { "document": <DID Document> }

2. Node → Client:   { "challenge": <JWT containing nonce> }
                     JWT claims: { iss: node_DID, sub: "DIDAuthChallenge",
                                   aud: user_DID, nonce: <random>, exp: ... }

3. Client:          Signs challenge with DID private key (P-256)
                     Creates Verifiable Presentation wrapping the challenge

4. Client → Node:   POST /api/v2/did/auth
                     Body: { "challenge_response": <VP containing signed challenge> }

5. Node:            Verifies VP signature against user's DID document
                     Resolves DID via EID chain (or cache)
                     Issues access JWT token

6. Node → Client:   { "token": <JWT access token>, "exp": <expiry> }

All subsequent API calls include the JWT in the Authorization: Bearer <token> header.

Vault Operations

Database Operations (MongoDB)

POST   /api/v2/vault/db/collections          Create collection
DELETE /api/v2/vault/db/collections/{name}    Delete collection
POST   /api/v2/vault/db/{collection}          Insert document(s)
PUT    /api/v2/vault/db/{collection}          Update document(s)
DELETE /api/v2/vault/db/{collection}          Delete document(s)
GET    /api/v2/vault/db/{collection}          Find documents
POST   /api/v2/vault/db/{collection}/count    Count documents

Each user gets a sandboxed MongoDB database named hive_user_{user_did_hash}.

File Operations (IPFS)

PUT    /api/v2/vault/files/{path}             Upload file
GET    /api/v2/vault/files/{path}             Download file
DELETE /api/v2/vault/files/{path}             Delete file
GET    /api/v2/vault/files/{path}?list=true   List files in directory
POST   /api/v2/vault/files/{path}/move        Move/rename file
GET    /api/v2/vault/files/{path}/hash         Get file hash (CID)

Files are pinned to IPFS with content-addressed CIDs. Reference counting ensures files are unpinned only when no references remain.

Scripting Engine

Users define server-side scripts (essentially stored MongoDB queries with access control):

POST   /api/v2/vault/scripting/{script_name}        Register script
POST   /api/v2/vault/scripting/{script_name}/run     Execute script
DELETE /api/v2/vault/scripting/{script_name}         Remove script

Script structure:

{
    "name": "get_messages",
    "condition": {
        "type": "queryHasResults",
        "collection": "access_grants",
        "filter": { "target_did": "$caller_did" }
    },
    "executable": {
        "type": "find",
        "collection": "messages",
        "filter": { "recipient": "$params.user_did" }
    }
}

Executable types: find, insert, update, delete, fileUpload, fileDownload

Parameter substitution: $caller_did, $params.* are replaced at runtime.

Payment Model

Payment verification via ESC smart contract:

Pricing and quotas are set by individual Hive node operators. Check a node's payment_config endpoint for its current plans.

POST /api/v2/payment/order     Place order for plan upgrade
POST /api/v2/payment/settle    Settle order (verify on-chain payment)
GET  /api/v2/payment/receipts  List payment receipts

Settlement verifies the ESC smart contract state via web3.py.

Backup and Migration

POST /api/v2/vault/backup              Initiate backup to remote node
GET  /api/v2/vault/backup/state        Check backup status
POST /api/v2/vault/backup/restore      Restore from backup
POST /api/v2/vault/backup/promote      Promote backup to primary

Backup process:

1. Primary Hive Node authenticates with backup node using DID
2. Streams MongoDB data + IPFS files to backup node
3. Backup node stores data in separate namespace
4. Promotion converts backup into a fully operational vault