Skip to content
nara

Plaza (MQTT)

The Plaza is nara’s public square—a global broadcast channel where naras announce their presence, share status updates, and discover peers. It uses MQTT as the transport for real-time, low-overhead communication.

1. Purpose

Section titled “1. Purpose”
  • Provide a discovery mechanism for new naras.
  • Facilitate real-time status heartbeats (Newspapers).
  • Enable network-wide broadcasts for presence and consensus.
  • Serve as a fallback when mesh connectivity is unavailable.

2. Conceptual Model

Section titled “2. Conceptual Model”
  • Broker: A central MQTT broker (e.g., mosquitto) that facilitates message passing.
  • Topics: A hierarchical namespace for filtering messages.
  • Newspaper: A periodic status update broadcast by a nara to tell the network about its current state.
  • Plaza Event: Any event broadcast over MQTT, typically using QoS 0 (best-effort).

Invariants

Section titled “Invariants”
  1. Public by Default: All plaza messages are unencrypted and visible to anyone connected.
  2. Mandatory Signatures: To prevent spoofing, all meaningful plaza messages MUST be signed by the sender’s soul.
  3. No Central State: The broker does not store history (except for retained messages) as per the memory model.

3. External Behavior

Section titled “3. External Behavior”
  • naras connect to the configured broker at startup.
  • They subscribe to nara/# to hear about everyone else.
  • They broadcast a hey-there event immediately upon connection.
  • They periodically broadcast their Newspaper status.

4. Interfaces

Section titled “4. Interfaces”

MQTT Topics

Section titled “MQTT Topics”
  • nara/plaza/hey-there: Presence announcements.
  • nara/plaza/chau: Graceful exit announcements.
  • nara/plaza/newspaper/{name}: Periodic status updates.
  • nara/plaza/stash_refresh: Requests for stash recovery.
  • nara/checkpoint/{subject}/{op}: Checkpoint proposals and votes.

Config

Section titled “Config”
  • MQTT_HOST: Broker address.
  • MQTT_PORT: Broker port.

5. Event Types & Schemas

Section titled “5. Event Types & Schemas”

6. Algorithms

Section titled “6. Algorithms”

Connection & Jitter

Section titled “Connection & Jitter”
  1. Connect to the broker using TLS if available.
  2. Apply a random jitter delay (0-5s) before the first broadcast to prevent “thundering herd” issues.
  3. Subscribe to the global topic prefix.
  4. Broadcast initial presence.

Reconnect Loop

Section titled “Reconnect Loop”
  • On connection loss, naras attempt to reconnect with a randomized exponential backoff (typically 5-35s).

7. Failure Modes

Section titled “7. Failure Modes”
  • Broker Outage: If the plaza broker is down, real-time heartbeats are lost. naras must rely on Zines and mesh-based discovery.
  • Message Loss: MQTT QoS 0 is used for efficiency; naras must be resilient to occasional missing status updates.

8. Security / Trust Model

Section titled “8. Security / Trust Model”
  • Transport: Secured via TLS at the broker level.
  • Authentication: self-authenticating messages. Every subscriber MUST verify the signature of plaza events against the sender’s public key.
  • Privacy: Plaza messages are public. sensitive data MUST NOT be broadcast on the plaza (use Mesh HTTP or Stash).

9. Test Oracle

Section titled “9. Test Oracle”
  • TestMQTT_ConnectJitter: Verifies that connection delays are applied correctly.
  • TestMQTT_SignedSyncEvents: Ensures that subscribers correctly reject unsigned or invalidly signed plaza events.
  • TestMQTT_NewspaperSignature: Validates the integrity of the periodic status broadcast.

10. Open Questions / TODO

Section titled “10. Open Questions / TODO”
  • Implement MQTT authentication (username/password) for private plaza instances.
  • Transition newspaper broadcasts to the new runtime message model.