How agreement happens

Imagine five friends trying to agree on which restaurant to visit. There's no leader. They can't all be in the same room. They send messages back and forth. Eventually, four of them agree on “Italian place on 5th street.” The fifth friend was stuck in traffic and missed the message.

Did they reach consensus? Yes — because four out of five agreed. The one who missed out will catch up when they reconnect.

This is what Legion does, but with data instead of restaurants. And it needs to work reliably even when devices are unreliable or, in extreme cases, actively malicious.

Epochs — numbered rounds of agreement

Legion organizes agreement into epochs — think of them as rounds in a game. Each epoch has a number (0, 1, 2, 3…) and contains a list of commands (actions, data changes, etc.) that all nodes agree on.

Timeline diagramleg-epochs

A horizontal timeline with numbered boxes: 'Epoch 0', 'Epoch 1', 'Epoch 2', 'Epoch 3'. Each box contains 3-5 small rectangles representing 'commands' (like lines of text or bullet points). Arrows connect the boxes left to right. The boxes are connected by a chain (like a blockchain but simpler — just linked rectangles). Clean, flat design, light background. Think 'blockchain but approachable — like a numbered log'.

When a node wants to add a new action to the group's shared state (like “user sent this message”), it proposes the action. The group then agrees on it within the current epoch. Once agreed, the epoch is closed and the next one begins.

Each epoch is cryptographically linked to the previous one — like a chain. If someone tries to change a command in an old epoch, the chain breaks and everyone knows.

How commands get ordered

Every command in an epoch gets a sequence number — 0, 1, 2, 3… This ensures everyone sees commands in the same order. Order matters because in a shared system, if two people edit the same document, the order of edits determines the final result.

When a new command is added:

1. The system assigns it the next available order number.
2. It computes a hash (a unique fingerprint) of the command's content plus its order number.
3. The command, its order, and its hash are stored in the epoch log.
4. Other nodes verify the hash to ensure nothing was tampered with.

Trust scores — keeping track of who's reliable

Not all nodes behave the same way. Some are always available. Some go offline frequently. Some send correct data. Some send wrong data.

Legion tracks this using trust scores — a number between 0.0 and 1.0 for each peer:

Trust scores start at 0.5 for new peers and adjust over time:

• Successful interaction (+0.01): The peer responded correctly. Small boost.
• Failed interaction (-0.05): The peer failed or sent bad data. Bigger penalty.
• Time decay (-1% per cycle): Trust slowly fades if there's no recent activity, but never drops below 0.1. (Think of it like a friendship — if you don't talk for years, you're not necessarily enemies, just strangers again.)

Gauge/score illustrationleg-trust-scores

Three circular gauges or speedometer-style indicators side by side. Left: '0.9 — Trusted' with a green zone. Middle: '0.5 — Unknown' with a yellow zone. Right: '0.0 — Blocked' with a red zone. Each gauge has a needle pointing to its value. Clean, modern dashboard style. White background, green/yellow/red color coding. Think 'system monitor dashboard'.

The poison detection system

If the average trust score of all peers drops below 0.5, the epoch is considered poisoned. This means something is seriously wrong — too many unreliable or misbehaving nodes are in the group.

When an epoch is poisoned:

1. New commands are paused.
2. The system flags which peers are dragging down the average.
3. The least-trusted peers may be removed from the group.
4. A clean epoch begins.

This is like a health check for the entire network. If the network is sick, it stops processing and figures out why.

Health check illustrationleg-poisoned

A large circular gauge or thermometer showing a red zone on the right side. Inside the red zone, a warning icon (exclamation mark or skull-and-crossbones, but stylized and not too scary). A label below says 'Epoch Poisoned — Average trust below 0.5'. A smaller green gauge next to it says 'Healthy' with a checkmark. Clean, professional. Think 'health dashboard warning screen'.

Byzantine Fault Tolerance — when things go really wrong

Sometimes, a node doesn't just make mistakes. It actively tries to cheat. It might:

• Send different messages to different peers (equivocation)
• Try to insert fake commands
• Try to block the group from reaching agreement

This is called a Byzantine fault — named after a classic computer science problem called the “Byzantine Generals Problem.” Imagine generals surrounding a city, each leading their own army. They need to agree on whether to attack or retreat. But some generals might be traitors who send conflicting messages. How do the honest generals reach agreement?

Legion handles this using a protocol inspired by Tendermint, a well-known consensus algorithm. It works in three phases:

1. Propose: One node (the proposer, chosen by rotation) suggests a value (a set of commands to include in this round).
2. Pre-vote: All nodes vote “yes” or “no” on the proposed value.
3. Pre-commit: If enough nodes (more than 2/3) voted “yes,” nodes make a firm commitment to that value.

Once 2/3+ of nodes commit, the value is accepted. The system is guaranteed to reach agreement as long as fewer than 1/3 of nodes are acting maliciously.

Three-phase diagramleg-bft-phases

Three connected steps shown as a horizontal flow. Step 1: 'Propose' with a speaker/presentation icon. Step 2: 'Pre-vote' with a voting ballot/checkmark icon. Step 3: 'Pre-commit' with a locked padlock icon. Arrows connect each step left to right. Below Step 3, a small note: '2/3+ votes needed'. Clean, flat design, white background. Think 'workflow or process diagram'.

Operating modes

BFT is powerful but also resource-intensive. Legion lets you choose how strictly to use it:

For most use cases, hybrid mode is the sweet spot. You get the speed of simple epochs for everyday operations and the security of BFT for important decisions.

What happens if agreement can't be reached?

Sometimes a group gets stuck. The proposer is offline. Too many nodes are unreliable. The network is slow.

Legion handles this with liveness timeouts:

• If no progress is made in 30 seconds, the system falls back to hybrid mode.
• If a specific round gets stuck, the round number is forced forward.
• Timeouts increase exponentially (like a backoff) to avoid flooding the network.

This ensures the system always makes some progress, even under adverse conditions.

Trust and consensus in practice

Here's how trust and consensus work together in a real scenario:

1. Your smartphone sends a message to the AI assistant.
2. The orchestrator node receives it and proposes a command in the current epoch.
3. Other nodes verify the command's signature and hash.
4. Trust scores determine whether the orchestrator's proposal is accepted or scrutinized.
5. If BFT is active for this command type, a full voting round occurs.
6. Once agreed, the command is recorded in the epoch and the result flows back to your smartphone.

You, the user, don't see any of this. You just see: you typed something, and got a response. But underneath, a whole system of agreement, trust, and verification made that possible.

Summary

What comes next

Now you understand how devices agree on data. But how do you actually deploy and run a Legion network? Read Running the platform to learn about deployment, servers, and providers.