Overview

ECCA Stack v3 (Eternal Coherence over Cryptographic Anchors) is a distributed cognitive operating system for autonomous AI agents. It provides persistent memory, portable identity, cross-chain coherence, and a tokenized bandwidth economy.

Key Components

Quickstart

Local Development Setup

# Clone the repository
git clone https://github.com/aarong11/dhf.git
cd ecca-stack

# Install dependencies
pnpm install

# Generate Prisma client
cd packages/db && npx prisma generate && cd ../..

# Build all packages (respects dependency order via turborepo)
pnpm build

# Copy environment config
cp .env.example .env

# Start all 24 services
docker compose up -d

# Deploy smart contracts
pnpm contracts:deploy

# Run the demo (create → perceive → recall → needlecast → epoch)
pnpm demo

# Run tests
pnpm test

Prerequisites

• Node.js ≥ 20.10
• pnpm 9.7.0+
• Go 1.22+
• Docker with Compose v2
• Hardhat (via npx, installed by pnpm install)

API: Stack Management

Stacks are the persistent identities in ECCA. Each Stack is an NFT on Cortex EVM with an ed25519 keypair, Coherence Profile Vector, and epoch counter.

Create a Stack

POST /v1/stacks
Content-Type: application/json

{
  "pubkey": "ed25519-public-key-hex",
  "cpv": {
    "computeCoeff": 1.0,
    "memoryCoeff": 1.0,
    "syncCoeff": 1.0,
    "routingCoeff": 1.0,
    "residueCoeff": 1.0
  }
}

// Response
{
  "id": "stack:0x...",
  "pubkey": "...",
  "cpv": { ... },
  "epoch": 0,
  "episodicHead": null,
  "createdAt": "2026-05-07T..."
}

Get Stack Info

GET /v1/stacks/:stackId

// Response
{
  "id": "stack:0x...",
  "pubkey": "...",
  "cpv": { ... },
  "epoch": 42,
  "episodicHead": "ecca://abc123@42",
  "sleeves": [ ... ],
  "balances": {
    "compute": 847.5,
    "memory": 1200.0,
    "sync": 450.0,
    "routing": 280.0,
    "residue": 15.0
  }
}

API: Sleeve Lifecycle

Spawn a Sleeve

POST /v1/sleeves/:stackId
Content-Type: application/json

{
  "kind": "ai",          // "human" | "ai" | "mining" | "memory"
  "tickRate": 2000       // ms between ticks
}

// Response
{
  "id": "sleeve:0x...",
  "stackId": "stack:0x...",
  "kind": "ai",
  "tickRate": 2000,
  "drift": 0,
  "alive": true
}

Decommission a Sleeve

DELETE /v1/sleeves/:id

// Sleeve is marked alive=false
// Per-epoch HKDF lease evaporates
// Pinned memory shards remain accessible
// Stack's episodicHead is unchanged

API: Perceive & Recall

Perceive (Write to Memory)

POST /v1/perceive
Content-Type: application/json

{
  "stackId": "stack:0x...",
  "sleeveId": "sleeve:0x...",
  "text": "Inference output: market analysis shows..."
}

// Response
{
  "cid": "ecca://def456@43",
  "epoch": 43,
  "cost": { "compute": 0.5 }
}

// Side effects:
// - Encrypted with epochKey(stackId, 43)
// - Written to Hippocampus DAG
// - Drift incremented by 1
// - PerceiveEvent emitted on NATS (ecca.perceive.*)

Recall (Read from Memory)

POST /v1/recall
Content-Type: application/json

{
  "stackId": "stack:0x...",
  "depth": 16
}

// Response
{
  "fragments": [
    { "cid": "ecca://...", "text": "decrypted content", "epoch": 43 },
    { "cid": "ecca://...", "text": "decrypted content", "epoch": 42 },
    // ... up to min(depth, memoryToken) nodes
  ],
  "fidelity": 0.87,
  "cost": { "memory": 16.0 },
  "broken": 2    // nodes that couldn't be decrypted
}

API: Needlecasting

POST /v1/needlecast
Content-Type: application/json

{
  "stackId": "stack:0x...",
  "fromSleeveId": "sleeve:old...",
  "toSleeveKind": "ai",
  "toTickRate": 2000
}

// Triggers 6-step saga:
// 1. Freeze source sleeve
// 2. Shard episodicHead (collect 8 CIDs)
// 3. Pin shards for durability
// 4. Anchor route on medulla
// 5. Reconstruct target sleeve (drift = 0)
// 6. Settle with RoutingToken

// Response
{
  "saga": "needlecast:0x...",
  "status": "completed",
  "from": "sleeve:old...",
  "to": "sleeve:new...",
  "cost": { "routing": 5.8 },
  "shardsTransferred": 8
}

API: Token Balances

GET /v1/stacks/:stackId/balances

{
  "raw": {
    "compute": 1000.0,
    "memory": 1500.0,
    "sync": 500.0,
    "routing": 300.0,
    "residue": 15.0
  },
  "effective": {
    "compute": 847.5,    // raw × cpv × EBC
    "memory": 1200.0,
    "sync": 450.0,
    "routing": 280.0,
    "residue": 15.0      // no decay
  },
  "cpv": { ... },
  "lastActiveEpoch": 40,
  "currentEpoch": 42,
  "ebcFactor": 0.905     // e^(-0.05 × 2)
}

Component: Synapse API

The Synapse API is the external gateway — the synaptic junction between clients and the cognitive system. Built on Fastify with TypeScript.

Handles: Stack CRUD, sleeve lifecycle, perceive/recall, needlecast initiation, balance queries, health checks, and real-time event streaming over WebSocket.

Component: Thalamus Router

The sensory relay of the ECCA system. Runs every epoch (4s), collecting all events across chains, computing per-shard Merkle roots, and folding them into the coherence root.

Component: DHF Compositor

Digital Human Freight — the memory reconstruction engine. Walks the Hippocampus DAG breadth-first, decrypting nodes with per-epoch HKDF keys, and scoring fidelity.

Component: Needlecast Router

Orchestrates the atomic 6-step re-sleeving saga. Coordinates between Hippocampus (shard pinning), Cortex (contract settlement), and Medulla (route anchoring).

Component: Quellist Treasury

The economic engine. Issues 100 units of each core token per stack per epoch, scaled by CPV and decayed by EBC. Tokens are burned on consumption.

Component: Sleeve Runtime

4-in-1 parametric process dispatcher. Each sleeve kind has different behavior:

Component: Worker Runner

6-in-1 background worker dispatcher running continuous passes:

Chain: Medulla PoW

Custom Proof-of-Work blockchain written in Go. Provides the fundamental timing and sequencing layer — the autonomic rhythm of the system.

RPC Methods

Synaptic Field MMR

A Merkle Mountain Range built over the last 256 block hashes. When a new block is mined, its hash is appended to the MMR. Old entries beyond the window are evicted. This provides O(log 256) = 8-hash cross-shard inclusion proofs.

Chain: Hippocampus DAG

Content-addressed directed acyclic graph written in Go. Stores encrypted memory nodes with epoch gating and pin semantics.

HTTP API

Chain: Cortex EVM

Private Ethereum chain (geth, Clique PoA, chain ID 131072) hosting 7 Solidity contracts for identity, tokens, treasury, and coordination.

Contract Suite

Concept: Coherence Root

The central innovation — a single 32-byte hash binding three independent chains every 4 seconds.

One PoW confirmation atomically finalizes state across all three shards. Cross-shard verification via Merkle proof against the appropriate sub-root. Domain separation prefix prevents collision between coherence versions.

Concept: Drift & Sync

Every sleeve has an instantaneous drift counter (δ) measuring divergence from canonical state:

• perceive() → δ += 1
• recall() → δ += 0.1
• sync() → δ = 0 (costs 1 SyncToken)
• δ > 15 (DRIFT_MAX) → warning flagged by drift-checker
• δ > 30 (2× DRIFT_MAX) → automatic desync → sleeve decommissioned → residue spawned

Drift is cognitive dissonance made measurable. A bit of divergence is normal; unbounded divergence means the sleeve is no longer coherent.

Concept: Residue System

Coordination failures are first-class economic objects. Five kinds, each with a specific bounty in non-decaying ResidueToken:

Lifecycle: detected → open → claimed → resolved (or expired). First valid proof wins the full bounty. Resolution model: first-valid-proof.

Concept: Memory Model

Memory is a capability-bounded walk over a content-addressed, encrypted DAG:

• Encoding: AES-256-GCM with per-epoch HKDF-SHA512 key derived from Stack's master secret
• Addressing: CID format ecca://<sha256>@<epoch>
• Epoch gating: Node readable within ±2 epochs unless pinned
• Token bounding: Recall depth ≤ min(requested, MemoryToken balance)
• Fidelity: Scored as ratio of decryptable to total fragments
• Pinning: Makes nodes permanent (exempt from epoch gating and pruning)
• Pruning: Non-pinned nodes beyond retention window are forgotten by design

Concept: CPV & EBC

Coherence Profile Vector (CPV)

A 5-coefficient vector per Stack, each coefficient ∈ [0, 2]. Scales token issuance per dimension. Represents the Stack's cognitive specialization — like cortical column tuning in neuroscience.

Epoch Binding Curve (EBC)

Exponential token decay with a hard floor:

Default parameters: decay = 0.05/epoch, floor = 0.25. A quiescent Stack decays to 25% after ~28 epochs (~112s) of inactivity.

Security Model

Cryptographic Primitives

Threat Model

• Shard isolation: Each chain can be compromised independently. The coherence root detects cross-shard inconsistency via residues.
• Memory privacy: DAG nodes are encrypted with per-epoch keys. Without the Stack's master secret, content is unreadable.
• Equivocation detection: Duplicate coherence roots for the same epoch → automatic residue + slash.
• Drift-based decommission: Runaway sleeves are automatically killed at 2× DRIFT_MAX.
• Token decay as DoS mitigation: Unused tokens decay — preventing resource hoarding.

Deployment

Docker Compose (Development)

The full stack runs as 24 services via Docker Compose. All services are configured with health checks, networking, and volume mounts.

# Start all services
docker compose up -d

# Check service health
docker compose ps

# View logs
docker compose logs -f siyana-api

# Health endpoints
curl http://localhost:7070/healthz    # siyana-api
curl http://localhost:8332/health     # medulla-pow
curl http://localhost:5001/health     # hippocampus-dag

Kubernetes (Production)

Helm charts are provided under deploy/k8s/ for production deployment. Six chart groups: chains, data, orchestration, sleeves, workers, and observability.

Observability

Built-in Prometheus metrics, Loki log aggregation, and Grafana dashboards under deploy/observability/.

Glossary

FAQ: Why Three Blockchains?

The Neuroscience Mapping

ECCA's three-chain architecture isn't arbitrary. It directly mirrors how biological nervous systems partition cognitive workloads across anatomically separate structures with distinct failure modes, clock rates, and data representations:

This isn't metaphor for aesthetics — it's a functional decomposition. The brainstem doesn't need to understand language. The hippocampus doesn't need to mine blocks. The cortex doesn't store raw sensory data. Mixing these concerns into one chain would be like asking your cerebellum to write poetry.

Miner Isolation: No Chain Holds Another Hostage

In a single-chain architecture, the entity that controls block production controls everything — identity, memory, timing, economic policy. ECCA's three chains enforce sovereign failure domains:

The coherence root is the binding mechanism — every 4 seconds, Thalamus computes a cross-chain Merkle root H(evmRoot ‖ ipfsRoot ‖ sleevesRoot) and embeds it in the Medulla block header. This means all three chains are cryptographically bound without being operationally coupled.

Homomorphic-Encryption-Like Properties

While ECCA doesn't use homomorphic encryption (FHE) directly, the three-chain separation provides analogous privacy guarantees through architectural isolation:

• Medulla sees only hashes — coherence roots, block hashes, epoch counters. It knows when things happened but not what happened. It is structurally blind to content.
• Hippocampus sees only encrypted ciphertext — AES-256-GCM blobs tagged with epoch numbers. It stores memories but cannot read them. Decryption requires epoch keys derived from HKDF-SHA512(stackId, epoch), which only the Stack owner possesses.
• Cortex sees only public state — token balances, NFT ownership, registry entries. It knows who owns what identity and how many tokens they have, but cannot access their memories or predict the next epoch hash.

This creates a system where:

• A Hippocampus node operator stores your memories but cannot decrypt them (encryption at rest with epoch-rotated keys)
• A Medulla miner commits to a coherence root but cannot determine what it commits to (pre-image resistance of SHA-256)
• A Cortex validator processes your token transactions but cannot link them to specific memory content (no ciphertext on-chain)
• Verifying that all three chains are consistent requires only the 32-byte coherence root — no chain needs to read another chain's state

This is why the architecture provides privacy-by-construction rather than privacy-by-encryption. Even if one chain is fully compromised and all its data is public, the attacker gains no useful information about the other two chains without the corresponding key material.

Separation of Concerns: Different Chains, Different Trade-offs

Each chain makes fundamentally different engineering trade-offs that would be impossible to optimize simultaneously in a single consensus mechanism:

A single chain would have to compromise on all of these dimensions. With three chains, each can be independently optimized, upgraded, and hardened without side effects on the others.