> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminal3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Consensus Protocol

> Building a resilient, tamper-evident encrypted ledger using Raft consensus

T3N is composed of clusters of Trusted Execution Environment (TEE) nodes. The nodes use the Raft consensus protocol to agree on a single, ordered history of every state change. That history is an **append-only, encrypted ledger**; the current state (the KV store) is a fast projection rebuilt from it. Each committed change is folded into a SHA-256 Merkle tree and periodically checkpointed with a signed seal written inside the enclave, so anyone with access can cryptographically prove that a record existed and has never been altered.

## Why consensus at all?

A single node can lie, crash, or lose data. T3N replicates every change across several independent TEE nodes so that:

* **No single node is the source of truth** — a majority of nodes must agree before a change is considered committed.
* **A cluster survives node failures** — the cluster keeps operating as long as a majority of nodes are healthy (meaning it can tolerate up to **⌊(n−1)/2⌋** failed nodes, where n is the total number of nodes in the cluster). For example, a 3-node cluster can tolerate **1** node failure, remaining operational as long as **2** nodes are healthy.
* **State is consistent** — every healthy node applies the same changes in the same order.

## Raft consensus protocol

T3N implements **[Raft](https://raft.github.io/raft.pdf)** from scratch, modeled directly on Ongaro's formal specification. It keeps the core safety and quorum mechanics of Raft intact, hardens the election path (pre-vote + CheckQuorum), and replaces Raft's plaintext disk log with an encrypted, Merkle-verifiable, enclave-signed ledger. Key mechanics are as follows:

### Leader and followers

At any given time, one node is the **leader** and the others are **followers**. All writes flow through the leader, which decides the order of changes. Followers replicate the leader's log and can take over if the leader disappears.

### Leader election (with pre-vote)

If followers stop hearing from the leader (an <Tooltip headline="Election Timeout" tip="If a follower hasn't heard an AppendEntries heartbeat from the leader within a randomized window, it assumes the leader is gone and tries to become leader">election timeout elapses</Tooltip>), a new election begins. T3N uses a **pre-vote** round first, in which a node checks whether it can win before disrupting the cluster. This prevents two well-known problems: a disconnected node repeatedly inflating the election <Tooltip headline="Term" tip="A monotonically increasing counter that labels each era of leadership. Every election bumps the term. Nodes always defer to the highest term they've seen, so a node advertising a higher term can force others to step down and re-sync. That makes the term number powerful — and something you don't want inflated carelessly.">term</Tooltip>, and a briefly partitioned node needlessly unseating a healthy leader. In a single-node cluster, the node self-elects on its first election timeout, so it becomes leader without any round trips.

### Replicating a change

1. A client request reaches the leader.
2. The leader **appends the change to its own local ledger first**.
3. The leader replicates the change to followers via **AppendEntries** messages (also used as heartbeats).
4. Once a **quorum** (e.g., 2 out of 3) of nodes has stored the change, the leader marks it **committed** and advances the commit index.
5. Committed changes are applied to the KV state on every node.

The commit rule is genuine majority-quorum Raft: a change is only committed once a majority of nodes hold it, making it durable even if a node fails.

## The ledger: an append-only, encrypted history

Consensus decides the order of changes; the **ledger** is where those changes
are stored. It is T3N's authoritative, append-only record.

| Layer        | What it is                                                     | Analogy                                          |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------ |
| **Ledger**   | Permanent, append-only, encrypted **history** of every change. | The accounting *journal* — every entry, forever. |
| **KV store** | The **current value** of each key, held in memory.             | The account *balances* — only "now".             |

Key properties:

* **Append-only.** Entries are added, never edited in place.
* **Each entry is split into two domains:**
  * **Public metadata** — readable without decryption, including integrity digests, plus the term and log-index that the entry occupies (carried in the entry's cleartext header).
  * **Encrypted payload** — the actual write-set (the keys and values that changed), protected with **AES-256-GCM**.
* **Chunked storage** — entries are written to a write-ahead log (WAL) and rolled into immutable sealed chunks, persisted through a pluggable storage backend (e.g., local disk).
* **Deterministic recovery** — because the ledger is the complete, ordered
  history, the entire KV state (and its indexes) can be rebuilt by **replaying**
  it from the start. A node that has lost its in-memory index can recover by
  replay.

## Tamper-evidence: Merkle tree + signed seals

Being append-only is not, by itself, proof that nothing has changed. This proof is provided by the following tamper-evident mechanisms:

* **Merkle tree.** Every committed entry becomes a **SHA-256** leaf in an append-only Merkle tree. The tree produces a single **root hash** that summarizes the entire history; if any past entry is changed, the root hash changes.
* **Inclusion proofs.** For any entry, the cluster can produce a Merkle **proof path** from that leaf to the root, allowing a holder to verify that a specific record is part of the committed history without seeing every other entry.
* **Seals (signed checkpoints).** Periodically, the cluster writes a **seal** entry that records a Merkle-root checkpoint. This checkpointing happens **inside the enclave (TEE)**, which allows a verifier to trust that the root was produced by genuine cluster code and has not been tampered with afterward.
* **Commit evidence.** Each committed transaction also has deterministic **commit evidence** derived (via HMAC-SHA256) from a secret only the enclave holds, meaning the evidence can be re-derived during audit or recovery but cannot be forged by an outsider.

Together, these mechanisms prove that *a record exists*, *where it sits in history*, and *that the history has not been rewritten*.

## What Raft consensus does *not* do

* **It does not make data readable by node operators.** Payloads are encrypted; consensus replicates ciphertext, and decryption happens inside the TEE.
* Raft is a *crash-fault-tolerant* protocol: it assumes nodes are honest but may fail. The protection against a malicious operator comes from the **TEE + encryption + tamper-evidence**, not from the consensus algorithm itself.
* **Availability requires a majority.** With n nodes, losing more than **⌊(n−1)/2⌋** nodes at once halts new commits until a majority is restored.