Skip to main content

Retention Policies

The Document Vault provides retention policies that control how long documents are stored, how deletion works, and what audit trail is maintained. Retention policies balance user privacy rights with compliance requirements and storage efficiency.

Retention Model​

The vault uses a layered retention model:

┌──────────────────────────────────────────────────────────┐
│                     Retention Layers                      │
│                                                          │
│  ┌─────────────────────┐  ┌───────────────────────────┐  │
│  │  IPFS (Pinata)      │  │  On-Chain (Cartesi)       │  │
│  │                     │  │                           │  │
│  │  Encrypted files    │  │  Metadata records         │  │
│  │  - Pinned: active   │  │  - Always retained        │  │
│  │  - Unpinned: GC'd   │  │  - Soft delete flag       │  │
│  │                     │  │  - Immutable audit trail  │  │
│  └─────────────────────┘  └───────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Layer 1: IPFS File Retention​

Encrypted files on IPFS are retained as long as they are pinned through Pinata. When a file is unpinned, it becomes eligible for garbage collection by IPFS nodes and will eventually become unavailable.

Layer 2: On-Chain Metadata Retention​

On-chain metadata is permanently retained by the nature of blockchain storage. Records can be marked as deleted (soft delete), but the metadata itself -- which contains no PII -- remains on-chain indefinitely.

Default Retention Behavior​

By default, documents are retained indefinitely until the user explicitly deletes them. There is no automatic expiration.

Soft Deletion​

When a user deletes a document, the vault performs a soft delete:

Soft Delete Process​

  1. On-chain update: The document's metadata is marked as deleted on the Cartesi rollup.
  2. Unpin scheduling: The IPFS file is scheduled for unpinning from Pinata.
  3. Unpin execution: The vault calls Pinata's unpin API to remove the pin for the encrypted file.
  4. IPFS garbage collection: Unpinned files are eventually garbage-collected by IPFS nodes.

Deletion Audit​

Every deletion is recorded on-chain. This record is immutable and cannot be removed.

IPFS Unpinning​

How Unpinning Works​

When a file is unpinned from Pinata:

  1. Pinata removes the file from its pinning infrastructure.
  2. Without any pin, IPFS nodes will eventually garbage-collect the file.
  3. The time to full garbage collection depends on IPFS node configurations and is not deterministic.

Effective Removal​

True guaranteed removal from IPFS is not possible because the protocol is decentralized. However, for the vault's purposes:

  • The file is encrypted, so even if ciphertext persists on some IPFS node, it is unreadable.
  • Pinata is the only entity pinning the file (private gateway, not on public DHT), so unpinning from Pinata makes the file effectively inaccessible.
  • Over time, garbage collection will reclaim the storage.

Access Grant Retention​

Access grants (when users share documents with institutions) are time-limited. When an access grant expires:

  1. The on-chain access record is updated to reflect expiration.
  2. The institution can no longer retrieve the document.

On-Chain Audit Trail​

The on-chain audit trail is permanent and immutable. It cannot be configured for automatic deletion because it resides on a blockchain. This is by design:

  • The audit trail contains no PII (no file contents, no file names, no personal identifiers beyond the DID).
  • It provides a verifiable record for compliance auditors.
  • It enables users to prove the history of their document management.