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. 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

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.