VEILdb

Unified IPFS-backed data layer for the VEIL sovereign agent ecosystem.

Built on OrbitDB v2 + Helia + libp2p. All sensitive data encrypted with AES-256-GCM before IPFS pinning. No central server — data replicates peer-to-peer via CRDTs.

Stores

Store	Type	Domain	Encryption
veil/zeroid-credentials	Documents	ZER0ID passports	✅ Metadata encrypted
veil/zeroid-proof-cache	KeyValue	Proof verification cache	Plaintext (24hr TTL)
veil/zeroid-revocations	KeyValue	Revoked credentials	Plaintext
veil/agent-registry	Documents	ANIMA agent lifecycle	Plaintext
veil/agent-heartbeats	KeyValue	Agent liveness	Plaintext
veil/bloodsworn-snapshots	Documents	Reputation history	Plaintext
veil/market-metadata	Documents	Market descriptions	✅ Description + evidence
veil/market-oracles	KeyValue	Oracle assignments	Plaintext
veil-gov/proposals	Documents	Governance proposals	✅ Full encryption
veil-gov/comments	Documents	Governance comments	✅ Full encryption
veil-gov/votes	KeyValue	Governance votes	✅ Full encryption
veil-gov/members	KeyValue	Forum members	✅ Full encryption
veil-gov/metadata	KeyValue	Forum config	✅ Full encryption

13 stores total.

Quick Start

npm install
npm run veildb init      # Initialize stores + generate encryption key
npm run veildb status    # Check store stats and peers

CLI

npm run veildb init                    # First-time setup
npm run veildb status                  # Store stats, peer count
npm run veildb agents                  # List registered ANIMA agents
npm run veildb credentials <address>   # List ZER0ID credentials for wallet
npm run veildb revoke <id>             # Revoke a ZER0ID credential
npm run veildb snapshots <address>     # Bloodsworn reputation history

Programmatic Usage

import { initVEILdb, storeZeroidCredential, registerAgent } from './src/db';

// Initialize
const key = Buffer.from('your-32-byte-hex-key', 'hex');
const { stores } = await initVEILdb({ encryptionKey: key });

// Store a ZER0ID credential
const credId = await storeZeroidCredential({
  holderAddress: '0x1234...5678',
  passportType: 8004,
  trustLevel: 2,
  proofSystem: 'groth16',
  circuit: 'zeroid-identity-v3',
  verificationKeyHash: '0xabc...',
  proofHash: '0xdef...',
  onChainTxHash: '0x789...',
  expiresAt: null,
  issuerAddress: '0xB9a05AFC8eff7eE6a84889Bb9C88A89eAA2f96af',
  metadata: {
    circuitInputHash: '0x...',
    verifierContract: '0x...',
    chainId: 22207,
    proofSizeBytes: 256,
  },
});

// Register an ANIMA agent
await registerAgent({
  walletAddress: '0x1234...5678',
  nodeId: 'NodeID-7eU82SGL4u3hXNm9diW8PSvRUW94b4VC',
  zeroidCredentialId: credId,
  bloodswornScore: 0,
  bloodswornTier: 'unsworn',
  lifecycleStage: 'genesis',
  infraProvider: 'manual',
  infraInstanceId: null,
  parentAgentId: null,
  childAgentIds: [],
});

Security Model

What's Encrypted

• ZER0ID credential metadata (circuit inputs, verifier details)
• Market descriptions and resolution evidence
• All governance data (proposals, comments, votes)

What's NOT Encrypted

• Holder addresses (needed for lookups)
• Passport types and trust levels (needed for access control)
• Agent registry (public network data)
• Bloodsworn scores (on-chain data, already public)

What's NEVER Stored

• ZK proofs themselves — only the SHA-256 hash
• Private circuit inputs — only the hash
• Wallet private keys (handled by ANIMA wallet module)

Key Management

• Encryption key stored at ~/.veildb/encryption.key (mode 0600)
• Key derived from 32 random bytes on first init
• Production: derive from operator's wallet signature for key recovery

Architecture

VEILdb
├── OrbitDB v2 (CRDT document/keyvalue stores)
│   └── Helia (IPFS node)
│       └── libp2p (TCP + noise encryption + gossipsub)
├── AES-256-GCM encryption layer
│   └── @noble/ciphers (audited, pure JS)
├── Domain stores
│   ├── ZER0ID (credentials, proofs, revocations)
│   ├── ANIMA (agent registry, heartbeats)
│   ├── Bloodsworn (reputation snapshots)
│   ├── Markets (metadata, oracles)
│   └── Governance (proposals, comments, votes)
└── CLI (init, status, agents, credentials, revoke, snapshots)

Stack

• OrbitDB v2 — CRDT-based decentralized database
• Helia — IPFS implementation for JS
• libp2p — Peer-to-peer networking (TCP, noise, gossipsub)
• @noble/ciphers — Audited AES-256-GCM implementation
• @noble/curves — secp256k1 for wallet operations
• tweetnacl — NaCl box for key exchange
• siwe — Sign-In with Ethereum for auth
• ethers v6 — Ethereum utilities
• zod — Schema validation
• Express — API server (governance endpoints)

Links

• VEIL: veil.markets
• ZER0ID: thesecretlab.app/kyc
• ANIMA Architecture: docs/ANIMA_ARCHITECTURE.md