Architecture Decisions: Protocol Boundary and Moderation¶

1. The Two-Tier Problem¶

The moment we add capabilities that legacy clients can't see — DID-based identity, CRDT-synced state, iroh transport, E2EE channels — we create two tiers of experience. This is the central design tension.

Our Position¶

Two tiers are inevitable and correct. The question is whether the degradation is graceful.

Think of it like HTTP/1.1 and HTTP/2. Both work. One gets more features. Neither breaks the other. The protocol boundary must be explicit, and the degradation must be clean.

Where We Draw the Line¶

The Seam: IRCv3 CAP Negotiation¶

CAP negotiation is the right boundary. It was designed for exactly this:

Client: CAP LS
Server: CAP * LS :sasl message-tags
Client: CAP REQ :sasl message-tags
Server: CAP * ACK :sasl message-tags

We currently advertise: sasl message-tags

We should extend to:

CAP * LS :sasl message-tags did-identity channel-crdt p2p-dm

Where:
- did-identity — Server will include DID and AT handle in WHOIS numerics (672, etc.)
- channel-crdt — Channel state is CRDT-backed; client may see members from other servers
- p2p-dm — Server supports relaying iroh endpoint IDs for peer-to-peer DMs

A legacy client that doesn't REQ these caps sees a standard IRC server. No special cases in the protocol handler. The CAP bitmask determines what extra information flows.

What Legacy Clients Miss (Explicitly)¶

1. Identity portability — Your nick is server-local. No DID, no proof of identity.
2. E2EE — You see ENC1:nonce:ciphertext as the message body. You can't decrypt it. This is intentional — encrypted rooms are opt-in and participants must use a capable client.
3. P2P DMs — Not available. DMs go through the server as standard PRIVMSG.
4. Moderation context — You can't see that a ban is DID-based, not hostmask-based. It still works (the server enforces it), but you can't inspect why.

What Legacy Clients DO Get¶

1. Full IRC — JOIN, PART, PRIVMSG, MODE, KICK, TOPIC, NAMES, WHOIS, all work.
2. Guest access — Connect without SASL, get a nick, chat.
3. Operator privileges — If granted by an authenticated user, work normally.
4. Plaintext channels — Any channel without E2EE enabled works identically.

2. Moderation in a DID-First World¶

This is the harder problem. IRC's moderation model assumes server authority:

• Chanops are granted by other chanops or the server
• Server opers have god mode
• Bans are hostmask patterns, tied to connection metadata
• K-lines are server-level bans

When identity is portable (DIDs) and servers are peers (CRDT mesh), every one of these assumptions breaks.

2.1 What Breaks¶

Nick-based ops lose meaning across servers. If Alice is a chanop on Server A and Bob joins from Server B, who granted Alice's authority? Server A did. But Server B has never seen Alice.

Hostmask bans become meaningless with portable identity. A ban on alice!*@* doesn't work when Alice reconnects via iroh with a different transport address. DID-based bans work (did:plc:abc123), but they require the ban to be a semantic statement about identity, not connection metadata.

Server authority fragments. In classic IRC, the server you're connected to is the authority. In a mesh, there's no single authority for a channel.

2.2 What We're Building¶

DID-Based Bans (Already Implemented)¶

We already support banning by DID:

/ban did:plc:abc123

This bans the cryptographic identity, not a hostname. It works regardless of how the user connects (TCP, TLS, iroh, different IP). The ban entry is stored in BanEntry with both hostmask and DID matching.

Moderation Log as a CRDT¶

The feedback is exactly right: the moderation log itself must be a CRDT.

Current state: our crdt.rs uses flat keys like ban:{channel}:{mask} → set_by. This handles add/remove cleanly via Automerge's put/delete semantics.

But it doesn't capture:
- Who performed the action
- When (causal ordering)
- Why (reason)
- Conflict resolution for concurrent ban + unban

Proposed: Moderation Events in the CRDT¶

modaction:{channel}:{ulid} → {
  "action": "ban",
  "target": "did:plc:abc123",
  "by": "did:plc:operator",
  "reason": "spam",
  "timestamp": 1707500000
}

Using ULIDs (time-sortable unique IDs) as keys means:
- No two moderation actions conflict (unique keys)
- Temporal ordering is preserved
- The full moderation history is auditable
- Concurrent ban + unban produces both events in the log

To determine current ban state, you fold the moderation log: replay actions in causal order, applying bans and unbans. The last action wins.

This is more expensive than a simple set, but it gives us:
- Auditability — Full history of who did what and when
- Conflict resolution — Concurrent actions are both recorded; latest wins
- Portability — The moderation log travels with the channel state across servers
- Accountability — Every moderation action is attributed to a DID

Authority Model¶

The hard question: who is allowed to moderate?

Options, from simplest to most sophisticated:

Option A: Channel founder model (simplest)
- The DID that creates a channel is the founder
- Founders can grant/revoke operator status
- Operator grants are themselves CRDT entries: op:{channel}:{did} → granting_did
- Only operators can add moderation events
- Server validates operator status before accepting ban/kick commands

Option B: Threshold model
- Moderation actions require N-of-M operator agreement
- A ban proposed by one operator becomes effective only when K others confirm
- The CRDT stores proposals and confirmations separately
- More complex, but resistant to rogue operators

Option C: Reputation/stake model (future)
- Moderation weight tied to identity reputation
- AT Protocol social graph as a trust signal
- Out of scope for now, but the CRDT structure supports it

Our choice: Option A first, with the CRDT schema designed to support B later.

2.3 The Merge Problem¶

What happens when two servers in a mesh have conflicting moderation state?

Scenario: Server A bans did:plc:evil. Server B unbans did:plc:evil. Both happen concurrently before sync.

With our moderation log approach:
1. After sync, both events exist in the CRDT
2. Both have timestamps (and Automerge causal ordering)
3. Fold the log: the temporally-later action wins
4. If truly simultaneous: Automerge's deterministic conflict resolution picks one
5. Both servers converge to the same state

Scenario: Server A's operator bans a user. Server B doesn't recognize A's operator.

Resolution:
1. Operator grants are also in the CRDT
2. If the grant hasn't synced yet, Server B will reject the ban locally
3. Once the grant syncs, Server B can re-evaluate
4. Alternatively: accept all moderation events and validate authority during fold

This is why the moderation log is better than a simple ban set — you can retroactively validate authority as state converges.

2.4 What's Implemented Now vs. What's Next¶

Now:
- DID-based bans (server-local, BanEntry with DID matching)
- Automerge CRDT with ban:{channel}:{mask} → set_by
- Channel ops granted per-session

Next:
- [ ] Moderation event log in CRDT (ULIDs, full attribution)
- [ ] Operator grants as CRDT entries (DID → DID)
- [ ] Authority validation during ban fold
- [ ] Channel founder registration (first DID to create channel)
- [ ] CAP extension for moderation transparency (mod-log capability?)

3. Why This Matters (BlueYard Thesis Alignment)¶

This project sits at the intersection of:

1. Open protocol infrastructure — IRC is the original open chat protocol. We're not replacing it; we're upgrading the substrate.

2. Crypto-native identity — DIDs from the AT Protocol give us portable, self-sovereign identity without a new identity system. Your Bluesky account IS your IRC account.

3. P2P transport — Iroh gives us encrypted, NAT-traversing, relay-capable connectivity without centralized infrastructure.

4. Local-first data — Automerge CRDTs mean server state is replicated, conflict-free, and doesn't require a consensus leader.

The thesis: you can modernize a 37-year-old protocol without breaking it, by upgrading identity, transport, and state management independently. Each layer is separable. Each layer degrades gracefully. No single point of failure.

If this works for IRC, it's a template for upgrading any open protocol infrastructure.