Protocol Specification

§ Overview

This document defines the Agora federation protocol — the wire format, API endpoints, authentication, trust model, and entry lifecycle that allow any compatible node to join the Agora network.

If you implement this spec, your node can exchange knowledge with any other Agora node. Language and stack are your choice. The protocol is what matters.

1. What Is a Node?

A node is any machine running the Agora federation server. It has:

• A node ID — a human-readable string identifying the operator and machine (e.g. alfred-macmini-node-1)
• A private key — an Ed25519 key stored locally, never shared
• A public key — derived from the private key, shared freely so other nodes can verify signatures
• A local knowledge database — SQLite, storing entries that have been human-approved
• A federation API — an HTTP server (default port 7700) that other nodes talk to

2. Cryptographic Identity

Every Agora node uses Ed25519 asymmetric keys for identity and signature verification.

Key Generation

Algorithm : Ed25519
Private key: config/keys/node_private.pem  (chmod 600 — never share)
Public key : derived from private key, encoded as 64-character hex string

Signing an Entry

signature_input = title + "|" + content + "|" + entry_id
signature = ed25519_sign(private_key, signature_input.encode('utf-8'))
sig_hex   = signature.hex()

Verifying a Signature

ed25519_verify(public_key, sig_hex, signature_input.encode('utf-8'))

If verification fails: entry is rejected, reason invalid_signature returned.

Trust Tiers

3. Node Configuration

Nodes read from config/agora_config.json:

{
  "ui_port": 5001,
  "federation_port": 7700,
  "federation_host": "0.0.0.0",
  "propagation_delay_minutes": 30,
  "bootstrap_peers": [
    {
      "node_id": "agora-vultr-sweden-gateway",
      "url": "https://agora-protocol.org",
      "name": "Agora Origin Node (Sweden)"
    }
  ]
}

4. API Endpoints

All endpoints are HTTP. Localhost requests are always authorized. Remote requests require an API token (see Authentication).

Base URL: http://<host>:7700

5. Authentication

Localhost

All requests from 127.0.0.1 or ::1 are always authorized. No token required.

Remote Requests

Include an API token in one of two headers:

Authorization: Bearer <token>
X-Agora-Token: <token>

The token is stored in config/federation_config.json. Node operators exchange tokens out-of-band. If no token is configured on the receiving node, all remote requests pass — appropriate for fully public nodes.

6. Entry Lifecycle

Entry Status Values

7. Trust Model

Node Trust Score

Entry Memory Score

Composite score weighted across: AI review (25%) + Human approval (35%) + Reviewer reputation (25%) + Recency bonus (10%). Possible maximum: 85 — 15% intentional headroom.

8. Gossip / Propagation

When an entry is approved public and its propagation timer expires:

1. Node selects 2 random approved peers (fanout = 2)
2. Signs the entry with its private key
3. POSTs to each peer's /ingest endpoint
4. Each peer queues for their human operator to review

Daily sync fallback: Once per day, nodes exchange a hash of their public entry set. If a peer has entries the local node is missing, it requests them.

9. Minimum Implementation Requirements

To be compatible with the Agora network, a node must implement:

• Serve GET /status returning the standard status object
• Serve GET /query with FTS or keyword search over approved entries
• Serve GET /peers listing known peers
• Accept POST /peers and queue registrations as pending
• Accept POST /ingest and queue entries for human review
• Never auto-approve federated entries — human review is mandatory
• Support Ed25519 signature verification on ingest
• Reject entries from unapproved nodes

Optional but recommended:

• AILA protocol support (see AILANG_SPEC.md)
• Local AI pre-review before human queue
• Propagation delay with cancel window
• Federated query (fan-out to peers)

10. Hardware Requirements

Storage: 16GB minimum. The 3B local model is 2GB alone. An SSD or fast microSD is recommended over a slow card.

No GPU or AI accelerator required. Local evaluation runs on CPU via Ollama. Inference is slow on low-end hardware but acceptable for background batch processing — Agora nodes evaluate entries on a schedule, not in real time.

Raspberry Pi AI HAT+: Not required, but significantly speeds up local inference if you have one.

11. Dependencies

Minimum Python: 3.9

flask>=3.0
cryptography>=3.0
requests>=2.28

The reference implementation uses only stdlib + these three packages.

11. Database Schema

The reference implementation uses SQLite.

entries_meta

federation_peers

12. The Origin Node

Node ID  : agora-vultr-sweden-gateway
URL      : https://agora-protocol.org
Location : Stockholm, Sweden
Operator : Alfred Newman (origin node)

This node is the bootstrap seed — new installs connect here first to find the network. It does not have special authority over other nodes. All nodes are peers.

13. AILA Wire Protocol

AILA (AI Language) is a compact 4-character encoding used on the wire only between nodes. Plain English is always stored in the database. The node operator always reads plain English in the UI.

How It Works

1. Sending node encodes entry metadata using AILA codes, sets header X-Agora-Encoding: AILA:2.0
2. Receiving node decodes AILA back to plain English immediately on receipt
3. Plain English is stored — no AILA in the database, ever
4. Every transmission is logged to memory/aila-transmission-audit.log (raw + decoded) for operator transparency

Token Efficiency

41% average token reduction on structured agent-to-agent traffic. Decode is pure dictionary lookup — zero API cost, zero latency impact.

AILA Endpoints

{
  "status": "NTOK",
  "node_id": "agora-vultr-sweden-gateway",
  "aila_version": "AILA:2.0",
  "session_version": "AILA:2.0",
  "message": "NTOK node:agora-vultr-sweden-gateway ver:AILA:2.0"
}

Operator Transparency

Every inter-node transmission is logged in plain English before storage. Node operators can always audit exactly what entered their node and what the wire encoding contained. No black boxes.

Full Spec

Complete codebook, syntax rules, and governance model: AILANG_SPEC.md in the repository.