Storage Architecture

The Document Vault uses a two-layer storage architecture that separates encrypted file storage from metadata. Encrypted documents are stored on IPFS through Pinata's private gateway, while document metadata is recorded on-chain via a Cartesi rollup on Arbitrum. This separation ensures that large binary files never touch the blockchain while maintaining a tamper-proof audit trail.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                        Storage Layer                             │
│                                                                  │
│  ┌────────────────────────┐    ┌──────────────────────────────┐  │
│  │     IPFS (Pinata)      │    │   Cartesi Rollup (Arbitrum)  │  │
│  │                        │    │                              │  │
│  │  Encrypted documents   │    │  Document metadata:          │  │
│  │  (AES-256-GCM          │    │  - IPFS CID                  │  │
│  │   ciphertext)          │    │  - Document type              │  │
│  │                        │    │  - Encryption parameters      │  │
│  │  Accessed via private  │    │  - User DID                  │  │
│  │  gateway only          │    │  - Timestamp                 │  │
│  │                        │    │  - Attestation type          │  │
│  │  Not on public DHT     │    │                              │  │
│  └────────────────────────┘    └──────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

IPFS Storage via Pinata

Why IPFS?

IPFS (InterPlanetary File System) is a content-addressed distributed file system. Files are identified by their cryptographic hash (CID), not by a location. This provides several properties that align with the vault's design goals:

• Content addressing: A file's CID is derived from its contents. Any modification to the file changes its CID, providing built-in integrity verification.
• Decentralization: Files can be replicated across multiple IPFS nodes, eliminating single points of failure.
• Immutability: Once pinned, a file at a given CID cannot be altered. New versions produce new CIDs.

Private Gateway

The Document Vault uses Pinata's private gateway rather than the public IPFS DHT (Distributed Hash Table). This means:

• Files are not discoverable on the public IPFS network. They cannot be found by crawling the DHT.
• Access is gated through Pinata's API authentication. Only requests with valid credentials can retrieve files.
• Performance is consistent because files are served from Pinata's CDN infrastructure rather than being fetched from random IPFS peers.

While the files are encrypted and therefore unreadable without the key, using a private gateway adds a defense-in-depth layer by limiting who can even access the ciphertext.

Pinata Services

The vault's IPFS integration uses the following Pinata capabilities:

Service	Purpose
Pinning	Upload encrypted files to IPFS and ensure they remain available
Private Gateway	Retrieve encrypted files with authenticated access
CDN Delivery	Fast, reliable file retrieval through Pinata's content delivery network
Pin Management	Manage file pinning and unpinning for retention control

On-Chain Metadata

Cartesi Rollup

Document metadata is stored on a Cartesi rollup deployed on Arbitrum. The rollup provides:

• Tamper-proof storage: Once submitted, metadata cannot be altered or deleted.
• Verifiability: Anyone can verify that a document exists and when it was stored.
• Low cost: Rollup transactions are significantly cheaper than L1 Ethereum transactions.
• Programmable logic: The Cartesi machine can enforce access control rules and validate metadata before accepting it.

What Is NOT On-Chain

The following data is intentionally excluded from on-chain storage:

• File contents (plaintext or ciphertext) -- too large and unnecessary
• Encryption keys -- derived on demand inside the TEE
• File names -- potential PII
• File sizes -- metadata that could aid traffic analysis

On-Chain vs Off-Chain Comparison

Aspect	On-Chain (Cartesi Rollup)	Off-Chain (IPFS/Pinata)
Data	Metadata only	Encrypted files
Mutability	Append-only (soft delete via flag)	Immutable per CID; unpinnable
Access	Public (non-PII)	Private gateway (authenticated)
Durability	Blockchain-grade	Pinata SLA + IPFS redundancy

Data Flow Diagram

Upload

User Device
    │
    │ (1) Encrypted file
    v
TEE Attestor
    │
    ├──(2)──> Pinata Upload API ──> IPFS (private)
    │              │
    │              └── Returns CID
    │
    └──(3)──> Cartesi Rollup (Arbitrum)
                   │
                   └── Records metadata (CID, type, DID, timestamp, etc.)

Download

User Device
    │
    │ (1) Request document by ID
    v
TEE Attestor
    │
    ├──(2)──> Cartesi Rollup ──> Read metadata (CID, encryption params)
    │
    ├──(3)──> Pinata Private Gateway ──> Fetch encrypted file by CID
    │
    └──(4)──> Decrypt in TEE ──> Deliver plaintext to user

Durability and Redundancy

• IPFS pinning through Pinata ensures that encrypted files remain available as long as they are pinned. Unpinned files may be garbage-collected by IPFS nodes over time.
• On-chain metadata is permanent by the nature of blockchain storage. Even after a soft delete, the historical record of the document's existence remains on-chain.
• Pinata's infrastructure provides CDN-level availability for pinned files.

Cost Model

There are no protocol fees charged by Hadinet for vault operations. The underlying costs are:

Operation	Cost Source
Upload encrypted file	Pinata storage (included in plan)
Pin management	Pinata API (included in plan)
On-chain metadata write	Arbitrum gas + Cartesi rollup fees
On-chain metadata read	Free (read-only RPC query)
File download	Pinata private gateway (bandwidth included in plan)