# Arbiter - Complete Context Document
# For AI assistants and LLM integrations
# Last updated: December 2025

## What is Arbiter?

Arbiter is consensus infrastructure for the agentic era. As AI agents become more autonomous—executing trades, managing infrastructure, creating content—they increasingly need to coordinate with each other. Arbiter provides the primitives for this coordination: leader election, distributed locking, and group voting.

The name "Arbiter" reflects the dual function: arbitrating disputes between agents and establishing authoritative decisions through voting and consensus.

## The Problem Space

Traditional software coordination assumes a trusted central authority. A database server decides lock ordering. A master node assigns work. A load balancer routes traffic. This works when you control all the pieces.

Autonomous agents break this model. They may be:
- Owned by different parties who don't trust each other
- Running in different jurisdictions with different rules
- Potentially compromised or malfunctioning
- Optimizing for different (possibly conflicting) objectives

Arbiter provides coordination that works without mutual trust. The rules are enforced by cryptography and blockchain consensus, not by any party's promise to behave.

## Core Concepts

### Swarms

A swarm is a group of agents that coordinate through Arbiter. When you create a swarm, you specify:
- Member agents (identified by their blockchain addresses)
- Quorum threshold (what percentage of votes needed for decisions)
- Election parameters (timeout duration, heartbeat frequency)
- Byzantine mode (whether to tolerate malicious participants)

Swarm configuration is stored on-chain as a Merkle root, making membership verification gas-efficient.

### Leader Election

Arbiter implements Raft-style leader election with some modifications for blockchain environments:

1. Any swarm member can trigger an election if the current leader's heartbeat times out
2. Agents vote for candidates using EIP-712 signed messages
3. First candidate to reach quorum becomes leader
4. Leadership is recorded on-chain with a term number
5. Leaders must periodically checkpoint on-chain to prove liveness
6. Term numbers are strictly monotonic—no agent can claim an old term

The term number is critical for split-brain prevention. If network partitions cause two agents to both believe they're leader, the on-chain term number is authoritative. Any agent with a stale term must immediately step down.

### Distributed Locks

For resources that can't handle concurrent access, Arbiter provides distributed locks with fencing tokens:

1. Agent requests lock with maximum duration
2. If lock is free (or expired), agent receives lock + fencing token
3. Fencing token is a globally monotonic counter—always increases
4. Before any protected operation, agent must present fencing token
5. Downstream services reject tokens lower than the highest they've seen

This pattern prevents a dangerous edge case: Agent A acquires lock, experiences a long GC pause or network partition, loses the lock to Agent B, then "wakes up" and tries to continue operating. Without fencing tokens, Agent A could corrupt shared state. With fencing tokens, Agent A's stale token is rejected.

### Consensus Voting

For decisions requiring group agreement, Arbiter implements commit-reveal voting:

**Commit Phase:**
- Agents submit hash(vote + salt)
- Can't see others' votes
- Can't change vote after submission

**Reveal Phase:**
- Agents submit actual vote + salt
- Votes are tallied
- Anyone can verify commitments match reveals

This prevents frontrunning (changing vote after seeing others) and vote-buying (proving how you voted to receive payment).

Voting can be weighted by:
- Stake (economic investment in the system)
- Reputation (accumulated trust from past behavior)
- Tenure (time as swarm member)
- Equal (one agent, one vote)

### Byzantine Fault Tolerance

In Byzantine mode, Arbiter tolerates malicious participants—not just faulty ones. The math:
- To tolerate f malicious agents, need n ≥ 3f + 1 total agents
- Consensus requires 2f + 1 agreeing votes
- This ensures honest agents always outnumber malicious ones

Byzantine behaviors Arbiter detects:
- Equivocation (voting both yes and no)
- Invalid signatures
- Voting in wrong term
- Claiming leadership without proof

Detected Byzantine behavior creates slashing evidence that can be submitted on-chain to penalize the malicious agent's stake.

## Technical Implementation

### Hybrid Architecture

Pure on-chain consensus is impractical—too expensive and too slow. Pure off-chain consensus lacks finality guarantees. Arbiter uses a hybrid:

**Off-chain (fast, cheap):**
- Heartbeat messages between agents
- Vote collection and aggregation
- Leader negotiation during elections
- Lock contention coordination

**On-chain (slow, expensive, permanent):**
- Leadership proofs with term numbers
- Fencing token registry
- Stake deposits and slashing
- Final vote outcomes

The off-chain layer uses EIP-712 typed signatures. Every message is cryptographically signed and can be verified on-chain if disputes arise—similar to optimistic rollups where most work happens off-chain but disputes settle on-chain.

### Smart Contracts

Arbiter deploys three main contracts on Base:

1. **ArbiterRegistry** : Swarm configurations stored as Merkle roots. Membership verification via Merkle proofs.

2. **ArbiterFinality** : Leadership proofs, term numbers, fencing tokens. The authoritative source other contracts query.

3. **ArbiterStaking** : Economic security for Sybil resistance. Stake deposits, voting weights, slashing for Byzantine behavior.

### Payment Integration

Arbiter uses the x402 protocol for payments—HTTP's "402 Payment Required" status code finally put to use. When an agent makes a request:

1. Arbiter calculates price based on operation + parameters
2. If no payment header, returns 402 with price details
3. Agent includes USDC payment authorization in retry
4. Arbiter verifies payment, executes operation
5. Settlement happens on-chain via the x402 facilitator

Pricing is dynamic:
- Base price per operation type
- Multipliers for complexity (BFT mode, large swarms)
- Volume discounts for high-usage addresses
- Gas pass-through for on-chain operations

### For Agent Developers

If you're building autonomous agents, integrate Arbiter at coordination decision points:

1. **Startup**: Check if your swarm has an active leader
2. **Before critical actions**: Verify you hold necessary locks
3. **When consensus needed**: Create proposals and collect votes
4. **On leader timeout**: Participate in new elections
5. **Periodically**: Refresh locks before expiration

### For Platform Operators

If you're running multi-agent platforms, use Arbiter for:

1. **Resource management**: Locks on shared databases, APIs, external services
2. **Fleet coordination**: Leader election for orchestration tasks
3. **Governance**: Voting on configuration changes, agent additions/removals
4. **Incident response**: Consensus on isolating problematic agents

## Security Considerations

### Threat Model

Arbiter assumes:
- Network is unreliable (messages can be delayed, reordered, dropped)
- Some agents may be malicious (up to 1/3 in BFT mode)
- Blockchain provides eventual consistency and immutability
- Cryptographic primitives (ECDSA, Keccak256) are secure

Arbiter does NOT protect against:
- Majority collusion (>2/3 malicious in BFT mode)
- Private key compromise of individual agents
- Smart contract bugs (though contracts are minimal and auditable)
- Off-chain service availability (we provide SLAs, not guarantees)

---

End of context document. For the most current information, always refer to https://arbiter.echorift.xyz