How Oak Chain Works

Use the diagrams below as the shortest path through the system. Click nodes for detail, or hit Play Animation to watch the flow.

Architecture Overview

This is the whole loop: authors write through the validator API or SDK, wallets fund the write, validators reach consensus, IPFS carries binaries, and Edge Delivery serves the result.

For cluster topology, sharding and scaling, see Architecture.

Content Write Flow

When an author creates or modifies content in Sling, the write should reach the cluster that owns that wallet namespace. Redirecting a write that lands on the wrong cluster is planned; today a validator only logs the owning cluster and processes the write locally. Inside a cluster, followers redirect writes to the leader. The leader accepts the signed proposal and replicates it across its own Aeron validators, and each validator commits it to its own Oak segment store.

The Steps

1. Author creates content via the validator API or Oak Chain SDK
2. Wallet signs the content change with secp256k1 key
3. Authority check (planned) resolves the owning cluster for that wallet namespace
4. Foreign cluster redirects (planned) if the request hit a non-owning cluster
5. Raft leader in the authoritative cluster receives and validates the proposal
6. Log replication sends entry to local followers
7. Followers acknowledge receipt
8. Commit happens when the local majority confirms
9. Oak Store persists content to TAR segments

Deeper view: the seven-stage consensus sequence (received, queued, flushed, verified, ingressed, committed, applied) with code anchors is explored in the Write Flow + Content Fabric visual.

Payment Flow

Authors settle on-chain through ValidatorPaymentV5, a single contract per Aeron cluster. The author calls settleWrite(proposalId, capabilityFlags) with the required ETH; the contract emits ProposalSettledV5; validators watch for that event and authorize the corresponding write. This applies in sepolia mode and is not yet validated; the default mock mode simulates payment.

For pricing, the full V5 contract surface and gas baseline, see Smart Contract.

IPFS Binary Storage

Binary assets (images, PDFs, videos) are stored on IPFS, not in Oak segments. The author's local IPFS node pins the content and generates a CID (content-addressed hash). Oak stores only the CID reference, enabling global retrieval via any IPFS gateway.

Why IPFS for Binaries?

• Content-addressed: Same content = same CID, automatic deduplication
• Separate from consensus: consensus stores CID references; the bytes live in the author's or the validator-configured BlobStore (IPFS by default)
• Global availability: Any IPFS gateway can serve the content
• Immutable: CID is a cryptographic hash of the content

Raft Consensus State Machine

Validators use Aeron Raft for consensus. Nodes start as Followers, campaign as Candidates on timeout, and become Leaders only after majority vote. Leaders hold authority by sending heartbeats.

State Transitions

Timing

Timeouts and failover limits: see Consensus Model.

The Complete Picture

┌─────────────────────────────────────────────────────────────┐
│                    AUTHORING LAYER                          │
│  Validator API / Oak Chain SDK + MetaMask Wallet            │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    CONSENSUS LAYER                          │
│  Aeron Raft Cluster (Leader + Followers)                    │
│  • Signed write proposals                                   │
│  • Settlement verification via Ethereum                     │
│  • Deterministic state machine                              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    STORAGE LAYER                            │
│  Oak Segment Store (TAR files) + IPFS (binaries)            │
│  • Immutable segments                                       │
│  • Append-only journal                                      │
│  • Content-addressed binaries                               │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    DELIVERY LAYER                           │
│  Edge Delivery Services (CDN)                               │
│  • 100 Lighthouse score                                     │
│  • Global distribution                                      │
│  • Real-time streaming                                      │
└─────────────────────────────────────────────────────────────┘

Key Principles

1. Wallet = Identity: Every participant has an Ethereum wallet
2. Signed Proposals: Every write is cryptographically signed
3. Payment = Authorization: No payment, no write
4. Consensus = Truth: Majority agreement determines state
5. Append-only writes, governed retention: accepted writes create new segment data; deletes and GC can reclaim unreachable history

Why These Principles?

These principles came out of first-principles constraints, not branding:

• What is identity? → Cryptographic proof (wallet), not username/password
• What is authorization? → Economic proof (payment), not role-based access
• What is truth? → Consensus (majority), not single-authority
• What is persistence? → Immutable (append-only), not mutable databases

We worked upward from those atoms. The result is not a traditional CMS trust model. It is a content system built from Ethereum, Oak, and Raft instead of admin roles and mutable databases.

Deep Dive: Segment Store GC

The append-only segment store accumulates garbage over time. Learn how Oak's generational garbage collection reclaims disk space while maintaining data integrity.