ARCHITECTURE

ENC Protocol Overview

Seven composable layers — from abstract math to React components. 63 Lean 4 files, 14,627 lines, 162 theorems.

7Layers
63Files
14,627Lines
162Theorems

sovereign data structures. 63 Lean 4 files, 14,627 lines, 162 theorems.


ARCHITECTURE

Architecture

Seven layers. Each composes from the ones below. No cycles.

OVERVIEW
┌─────────────────────────────────────────────────────────────────┐
│  Layer class="nm">7: Codegen Targets                    class="nm">595 lines, class="nm">3 files │
│  Server.lean  Client.lean  Frontend.lean                        │
│  Three duals. Three IO boundaries. Three faithful functors.     │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">6: Bridge + UI DSL                    class="nm">967 lines, class="nm">2 files │
│  Bridge.lean (theory  protocol)  UI.lean (React component DSL) │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">5: Typeclasses + Composition         class="nm">1,class="nm">215 lines, class="nm">3 files│
│  App/Typeclasses  App/Instances  Composition                    │
│  class="nm">6 typeclasses × class="nm">4 instances, class="nm">43 composition theorems           │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">4: Applications                     class="nm">7,class="nm">182 lines, class="nm">19 files│
│  Registry  Timeline  DM  Chat  Messenger                       │
│  (App, SDK, DataView, State, Components) per app                │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">3: Middleware                         class="nm">361 lines, class="nm">2 files │
│  ECDH (class="nm">1-to-class="nm">1 encryption)  MLS (group encryption)              │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">2: Core Protocol                    class="nm">3,class="nm">361 lines, class="nm">22 files│
│  Primitives  SMT  CT  Event  RBAC  Validation  Node  SDK       │
├─────────────────────────────────────────────────────────────────┤
│  Layer class="nm">1: FTA (Formal Theory)                class="nm">946 lines, class="nm">12 files│
│  Primitives  Identity  Trust  Secrecy  State  Storage           │
│  Binding  Transition  View  Effect  Application  Theorems       │
└─────────────────────────────────────────────────────────────────┘

DOCUMENTS

Documents

Each layer has a corresponding specification document.

OVERVIEW
Document       Layer      What it specifies
──────────     ─────      ─────────────────
fta.md         Layer class="nm">1    Abstract theory: class="nm">48 theorem obligations
enc.md         Layer class="nm">2-class="nm">4  Protocol instantiation: crypto, events, RBAC, apps
server.md      Layer class="nm">7    Server: Enclave  Runtime  Service  JS DO
client.md      Layer class="nm">7    Client: Enclave  ClientRuntime  Client  JS SDK
frontend.md    Layer class="nm">7    Frontend: AppView  FrontendRuntime  Frontend  React
overview.md    All        This document

Supporting references:

OVERVIEW
node-api.mdx   HTTP/WebSocket API reference (endpoints, auth, errors)
proof.mdx      Proof wire formats (SMT, CT, Bundle)
smt.mdx        Sparse Merkle Tree specification
spec.mdx       Legacy specification (superseded by fta.md + enc.md)

THE THREE DUALS

The Three Duals

One pattern applied three times. Each layer is a composition of a spec type with an IO boundary, yielding a codegen target.

OVERVIEW
Layer      Spec type       IO boundary        Composition      JS target
─────      ─────────       ───────────        ───────────      ─────────
Server     Enclave         Runtime (class="nm">12)       Service          Cloudflare DO
Client     Enclave (same)  ClientRuntime (class="nm">10) Client           SDK
Frontend   AppView         FrontendRuntime (class="nm">8) Frontend        React app

The client does not define its own type. ClientView = Enclave. The server's Enclave is the single source of truth for routes, reads, encryption, and schema. The client just reads it from a different perspective.

OVERVIEW
Enclave = {
  schema       extraRoutes   encrypted
     │              │             │
     ├──Server──────┤             │
     │  allRoutes   │             │
     │  ddl         │             │
     │  handlers    │             │
     │              │             │
     ├──Client──────┤─────────────┤
     │  reads       │  encrypt?   │
     │  writes      │             │
     │  protocol    │             │
     │              │             │
     └──Frontend────┤             │
        StateFns    │  wiring     │
        Components  │             │

I · NFORMATION FLOW

Information Flow

Information is defined once and flows downward. No re-specification.

OVERVIEW
fta.md   App.render : S  V                    pure function (Theorem class="nm">45)
  │
  ├─ enc.md   AppManifest.schema               event types + RBAC rules
  │    │
  │    ├─ enc.md   AppSDK W constructors       class="nm">17 write operations
  │    │    │
  │    │    └─ proven: all reduce to createCommit (Theorem class="nm">42)
  │    │
  │    └─ enc.md   Middleware (ECDH/MLS)        encryption parameters
  │
  ├─ server.md   Enclave                       class="nm">7 fields, SINGLE SOURCE
  │    │
  │    ├─ Enclave.allRoutes                     derived (protocol + extra)
  │    ├─ Enclave.ddl                           derived (hasDataView?)
  │    └─ Enclave.reads                         derived (GET from extraRoutes)
  │
  ├─ client.md   ClientView = Enclave           ZERO new fields
  │    │
  │    ├─ Client.write  = AppSDK.buildCommit    from enc.md
  │    ├─ Client.read   = Enclave.reads         from server.md
  │    └─ Client.query  = protocolRoutes        shared
  │
  └─ frontend.md   AppView = (Enclave, AppDef, CSSApp)
       │
       ├─ Components     from UI.lean (class="nm">5,class="nm">285 lines, class="nm">58 components)
       ├─ Handlers        SDKFunc  Client.write
       ├─ Effects         StateFn  Client.read
       └─ CSS            from CSSApp (theme, layout, rules)

TRUST BOUNDARIES

Trust Boundaries

37 axiomatized IO methods across three runtimes. Everything else is derived, proven, or structurally enforced.

OVERVIEW
Boundary           Methods   Implementation        Lines JS
────────           ───────   ──────────────        ────────
Runtime            class="nm">12        Cloudflare DO API      ~class="nm">50
ClientRuntime      class="nm">10        fetch + WebSocket      ~class="nm">30
FrontendRuntime    class="nm">8         React hooks + DOM      ~class="nm">20
Crypto             class="nm">7         noble-curves           ~class="nm">10
                   ──                               ───
Total              class="nm">37                               ~class="nm">110

Cryptographic axioms (standard hardness assumptions):

OVERVIEW
sha2class="nm">56_collision_resistance     if SHA-class="nm">256 is secure
schnorr_correctness             BIP-class="nm">340
ecdh_symmetric                  CDH assumption
encrypt_roundtrip               XChaCha20Poly1class="nm">305 AEAD
hkdf_one_wayness                random oracle model

These are not implementation trust — they are mathematical assumptions the entire field relies on.


THEOREM SUMMARY

Theorem Summary

162 theorems across all layers.

OVERVIEW
Layer                Theorems  Key results
─────                ────────  ───────────
Theory               class="nm">10        FTA meta-theorems
Core                 class="nm">20        SMT soundness, CT inclusion, expiry rejection
Middleware           class="nm">1         ECDH roundtrip
Apps                 class="nm">65        Schema well-formedness, SDK reductions
Typeclasses          class="nm">1         Complete witness existence
Composition          class="nm">43        C1-C6 composition conditions (all class="nm">4 apps)
Bridge               class="nm">3         class="nm">48 FTA theorem witnesses
Server               class="nm">15        Route counts, capability matrix, DDL
Client               class="nm">4         Read counts, no-DV-no-reads

Notable proofs:

4 applications reduce to createCommit(identity, enclave, eventType, content, exp, tags). Proven per-operation.

Client read endpoint counts derived from server route tables and verified by decide. Not specified separately.

Structural property of the Enclave definitions.

Prevents unnecessary work.


C · ODEGEN PIPELINE

Codegen Pipeline

The codegen pipeline is a faithful functor from Lean definitions to JavaScript artifacts. "Faithful" means structure-preserving: one output per input, no creative decisions.

Server codegen

OVERVIEW
Enclave                   one DO class
Enclave.allRoutes         Worker route dispatch
Enclave.ddl               DO constructor (SQL CREATE TABLE)
Runtime (class="nm">12 methods)      ~class="nm">50 lines JS (Cloudflare DO API)
Service (class="nm">4 entry points)  DO class (constructor, fetch, webSocketMessage, alarm)

Client codegen

OVERVIEW
AppSDK W constructors     sdk.createPost(text), sdk.like(id), ...
Enclave.reads             sdk.getFeed(opts), sdk.getProfile(id), ...
protocolRoutes            sdk.query(filter), sdk.getSTH(), ...
ClientRuntime             fetch() / WebSocket (trusted FFI)
Enclave.encrypted         encrypt/decrypt wiring (conditional)

Frontend codegen

OVERVIEW
AppDef.interfaces         src/types.ts
AppDef.sdkFuncs           src/sdk.ts
AppDef.stateFns           src/api.ts
AppDef.helpers            src/helpers.ts
AppDef.icons              src/icons.tsx
AppDef.components[i]      src/components/[Name].tsx
  .state[j]                 const [x, setX] = useState(initial)
  .effects[j]               useEffect(() => body(), [deps])
  .handlers[j]              const handleX = useCallback(...)
  .render                   return (<JSX tree>)
CSSApp.theme              src/styles.css :root { class=class="st">"cm">--var: val; }
CSSApp.layout             src/styles.css .app { display: grid; }
CSSApp.rules[i]           src/styles.css .selector { ... }
CSSApp.media[i]           src/styles.css @media (...) { ... }

Every mapping is a bijection. 8 bijections for frontend alone.


THE FOUR APPLICATIONS

The Four Applications

OVERVIEW
              Registry    Timeline    Chat        DM
              ────────    ────────    ────        ──
schema        static      static      static      static
addressing    singleton   per-user    per-group   per-pair
DataView      ✓           ✓           ✗           ✗
Push          ✗           ✗           ✗           ✗*
Bootstrap     ✗           ✓           ✓           ✗
encrypted     ✗           ✗           ✗           ✗*
middleware    none        none        MLS         ECDH
reads (GET)   class="nm">5           class="nm">7           class="nm">0           class="nm">0
writes        class="nm">3           class="nm">7           class="nm">5           class="nm">2
components    class="nm">8           class="nm">12          class="nm">9           class="nm">9

*enc-node handles push and transport encryption for DM.

Messenger (20 components) composes DM + Chat + Timeline at the frontend layer, importing their SDKs and states.


FILE MAP

File Map

63 Lean files organized by layer.

OVERVIEW
Enc/
├── Theory/                          Layer class="nm">1: FTA (class="nm">946 lines)
│   ├── Primitives.lean                Val, Key, Time, CryptoSuite
│   ├── Identity.lean                  Id (Anon|Hold|Share|Attest)
│   ├── Trust.lean                     Schema, Origin, Op
│   ├── Secrecy.lean                   Scheme (Direct|Tree), Transport
│   ├── State.lean                     Life, Persist
│   ├── Storage.lean                   Store, Atomicity, Interface
│   ├── Binding.lean                   Trigger, BindMode, Binding
│   ├── Transition.lean                Action (set|del|bind)
│   ├── View.lean                      V (el|text|empty)
│   ├── Effect.lean                    Effect (fetch|open|close|...)
│   ├── Application.lean               FTA.App typeclass (class="nm">48 obligations)
│   └── Theorems.lean                  FTA meta-theorems
│
├── Core/                            Layer class="nm">2: Protocol (class="nm">3,class="nm">361 lines)
│   ├── Primitives/                    Types, Crypto, Hash, SMTKey
│   ├── SMT.lean                       Sparse Merkle Tree
│   ├── CT.lean                        Certificate Transparency
│   ├── Event/                         Types, Commit, Lifecycle
│   ├── RBAC.lean                      Schema, permits, Grant/Revoke
│   ├── Validation.lean                class="nm">14-step commit pipeline
│   ├── Node.lean                      NodeState, processCommit
│   ├── SDK.lean                       createCommit, verify*, encrypt*
│   │   └── Client.lean                SessionManager, NodeClient, WS
│   ├── Handlers.lean                  Route dispatch, SQL type
│   ├── Persistence.lean               NODE_TABLES_DDL
│   ├── Push.lean                      P/N delivery, retry backoff
│   ├── WSHandlers.lean                WebSocket message handling
│   ├── DataView.lean                  SYNC_STATE_DDL, event indexing
│   └── Migration.lean                 Enclave migration protocol
│
├── Middleware/                      Layer class="nm">3: Encryption (class="nm">361 lines)
│   ├── ECDH.lean                      class="nm">1-to-class="nm">1 (DM): agree, encrypt, decrypt
│   └── MLS.lean                       Group (Chat): epochs, fwd secrecy
│
├── Apps/                            Layer class="nm">4: Applications (class="nm">7,class="nm">182 lines)
│   ├── Registry/                      Discovery service
│   │   ├── App.lean                     Schema (class="nm">3 event types)
│   │   ├── SDK.lean                     class="nm">3 writes
│   │   ├── DataView.lean                NodeIndex, EnclaveIndex, REST
│   │   ├── State.lean                   AppState + class="nm">4 component states
│   │   └── Components.lean              class="nm">8 components (class="nm">520 lines)
│   ├── Timeline/                      Public microblog
│   │   ├── App.lean                     Schema (class="nm">7 event types)
│   │   ├── SDK.lean                     class="nm">7 writes
│   │   ├── DataView.lean                PostIndex, ProfileIndex, REST
│   │   ├── State.lean                   AppState + class="nm">7 component states
│   │   └── Components.lean              class="nm">12 components (class="nm">1,class="nm">049 lines)
│   ├── DM/                            Encrypted messaging (ECDH)
│   │   ├── App.lean                     Schema (class="nm">3 event types)
│   │   ├── SDK.lean                     class="nm">2 writes
│   │   ├── State.lean                   AppState + class="nm">5 component states
│   │   └── Components.lean              class="nm">9 components (class="nm">810 lines)
│   ├── Chat/                          Group chat (MLS)
│   │   ├── App.lean                     Schema (class="nm">5 event types)
│   │   ├── SDK.lean                     class="nm">5 writes
│   │   ├── State.lean                   AppState + class="nm">4 component states
│   │   └── Components.lean              class="nm">9 components (class="nm">868 lines)
│   └── Messenger/                     Composed (DM + Chat + Timeline)
│       └── Components.lean              class="nm">20 components (class="nm">2,class="nm">038 lines)
│
├── App/                             Layer class="nm">5: Typeclasses (class="nm">693 lines)
│   ├── Typeclasses.lean                class="nm">6 typeclasses + ENCApp witness
│   └── Instances.lean                  class="nm">4 × class="nm">6 instances, class="nm">17 proofs
│
├── Bridge.lean                      Layer class="nm">6: Theory  Protocol (class="nm">508 lines)
├── UI.lean                          Layer class="nm">6: React DSL (class="nm">459 lines)
├── Composition.lean                 Layer class="nm">5: C1-C6 theorems (class="nm">522 lines)
│
├── Server.lean                      Layer class="nm">7: Server codegen (class="nm">281 lines)
├── Client.lean                      Layer class="nm">7: Client codegen (class="nm">134 lines)
└── Frontend.lean                    Layer class="nm">7: Frontend codegen (class="nm">180 lines)

READING ORDER

Reading Order

For understanding the protocol:

  1. fta.md — the abstract theory (what any app must satisfy)
  2. enc.md — the concrete instantiation (how ENC satisfies it)
  3. server.md — the backend (four services from one Enclave type)
  4. client.md — the SDK (dual of server, zero new types)
  5. frontend.md — the UI (AppView = Enclave + Components + CSS)

For understanding the Lean code:

  1. Enc/Theory/Application.lean — the FTA.App typeclass
  2. Enc/Core/Node.lean — the Node (ordering authority)
  3. Enc/App/Instances.lean — how apps satisfy the typeclasses
  4. Enc/Server.lean — the Enclave (single source of truth)
  5. Enc/Client.lean — the dual (ClientView = Enclave)
  6. Enc/Frontend.lean — the view (AppView = Enclave + AppDef + CSS)

ONE SENTENCE

One Sentence

The ENC protocol is seven composable layers — from abstract math to React components — where a single Enclave structure determines the complete server, SDK, and frontend for any application, with 162 theorems proving the pipeline preserves correctness at every stage.