CivicOS Relay¶

The relay is CivicOS's coordination infrastructure — it stores and serves signed civic events (voices, actions, subscriptions) and provides authenticated AI access for residents.

Relay vs. MCP Server¶

CivicOS operators can run either or both of two independent services:

The MCP server is a data API. It answers questions like "what's on the agenda?" by querying structured civic records. Any AI client (Claude, ChatGPT) or application can connect to it. No identity required.

The relay is coordination infrastructure. It handles the things that require identity and trust: voicing support or opposition on an agenda item, committing to civic actions, subscribing to topics, and using AI to draft testimony. All relay interactions are signed with secp256k1 Schnorr signatures (Nostr-compatible) and most require attestation.

A city government might run only an MCP server to publish authoritative civic data. A neighborhood group might run only a relay to coordinate community voices. A full CivicOS operator runs both.

What the Relay Stores¶

All voice and action records are signed Nostr events. The relay verifies signatures on ingest and serves them to any client. Records are self-verifying — any relay, anywhere, can validate a voice by checking its signature and embedded attestation proof without contacting the original relay.

Services¶

VoiceService¶

Public expression of civic interest on entities (agenda items, decisions, initiatives).

• cast_voice(voice) — Submit a signed stance (support/oppose/watching)
• get_counts(entity) — Aggregate voice counts per entity
• verify(voice) — Verify signature and attestation proof

One key = one stance per entity. Casting a new stance revokes the previous one.

ActionService¶

Track commitments and completions on civic actions.

• record_commitment(action) — Record a commitment to act
• record_completion(action) — Record completion
• get_counts(entity) — Action counts per entity

RelayService¶

Event routing and subscription management.

• subscribe(subscription) — Subscribe to events by topic, geography, or event type
• unsubscribe(id) — Remove subscription
• emit(event) — Route event to subscribers

AI Proxy¶

Authenticated AI access for attested residents. See AI Proxy.

ProvenanceService¶

Trust signals for voice quality — tracks which keys have participated in which entities and jurisdictions.

SyncService¶

Voice and event synchronization between peer relays. See Federation.

Cryptography¶

All relay interactions use secp256k1 Schnorr signatures (Nostr-compatible, BIP-340). Not P-256 ECDSA.

• Keys are generated client-side in the browser extension
• Private keys never leave the user's device
• Signatures are verified by the relay on every write operation
• Attestation proofs are embedded on each voice/action record

Acceptance Policy¶

All relay write endpoints enforce signature verification and an acceptance policy. Writes are checked against a tiered system:

1. Attested — present a kind-30850 attestation proof for unlimited writes (Phase 3)
2. Paid — include a payment proof for unlimited writes (Phase 4)
3. Rate-limited — per-event-type daily limits (active now)

Default rate limits:

If a write exceeds the rate limit without an attestation or payment proof, the relay returns HTTP 402 with upgrade options:

{
  "accepted": false,
  "tier": "rejected",
  "reason": "Daily rate limit exceeded (50/day for voice)",
  "options": {
    "attestation": "Present a kind-30850 attestation proof for unlimited writes",
    "payment": "Include a payment proof for unlimited writes",
    "retry": "Wait until tomorrow when your rate limit resets"
  }
}

Write tools are not exposed in the MCP server — all writes go through the relay directly.

Current status: Rate limiting (tier 3) and attestation verification (tier 1) are active. Attestation codes are issued via multi-issuer registry — organizations register their signers and the relay verifies attestation proofs against trusted issuer pubkeys. Token-based payment verification (tier 2) is implemented — the relay issues blind signature tokens via /coordination/tokens/* and the acceptance policy verifies them against TOKEN_ISSUER_PUBKEYS. Rate limits are persistent (PostgreSQL-backed), unlike REST API rate limits which are in-memory.

HTTP Endpoints¶

All endpoints are under the relay's base URL. Write endpoints require Nostr-signed request bodies; read endpoints are public.

Voice¶

Comments¶

Initiatives¶

Civic Actions¶

Subscriptions¶

Attestation¶

Token Issuance¶

Blind signature token endpoints for paid relay access. Tokens provide privacy-preserving proof of payment — the issuer signs blinded challenges so it cannot link tokens to identities.

Flow: Client calls /tokens/info to get the issuer pubkey, creates a nonce session via /tokens/session, blinds a challenge locally, submits it to /tokens/sign, then unblinds the signature. The resulting token can be presented to any relay that trusts the issuer (via TOKEN_ISSUER_PUBKEYS).

Feedback¶

Federation & Sync¶

Health¶

Storage¶

• Production: PostgreSQL (RELAY_DATABASE_URL), separate from the civic data database
• Development: In-memory storage (fallback when no database URL is set)

The relay uses its own database, separate from the MCP server's civic data store. This is a deliberate architectural boundary — coordination data (who voiced what) is isolated from civic data (what happened at the meeting).

Attestation Signing¶

Trusted organizations run their own signing services via civicos-signer. When a resident redeems an attestation code, the relay calls the issuing organization's signer to produce the attestation event. This separates attestation authority from relay operation from day one — see Attestation: Multi-Issuer.

Further Reading¶

• Nostr Event Schemas — Complete tag structures for building CivicOS clients
• Attestation — How gated attestation prevents spam and ensures genuine participation
• Trust Model — Adversary analysis, commitment logs, operator integrity
• Federation — Multi-operator peering, jurisdiction rollup, data sovereignty
• AI Proxy — Privacy-preserving AI access for residents