Design Document

This is the canonical technical reference for ItsGoin. It describes the vision, the architecture, and the target state of every subsystem — with full implementation detail. This edition describes the v0.8 target design as one coherent architecture; status badges — Implemented Rework Planned — mark where the code has and hasn't caught up. See the download page for the release changelog.

1. The Vision

The honest promise: The CDN is an attention-driven delivery amplifier, not a storage guarantee. Hot content spreads naturally through demand; cold content decays unless intentionally hosted. Authors are responsible for their own content durability — a post backup/export tool is the author's safety net, not the network's job. The system is a loss-risk network — best-effort availability, not durability guarantees.

Guiding principles

• Our distributed network first, direct connections always preferred
• Social graph and friendly UX in front, infrastructure truth in back
• Privacy by design: public profile is minimal, private profiles are per-circle, social graph visibility is controlled, and traffic patterns are shaped so observers cannot tell where content originates
• Don't break content addressing (PostId = BLAKE3(post), visibility is separate metadata)
• Your feed is yours: reverse-chronological by default, no algorithmic ranking, user-controlled discovery
• Narrow mesh, deep knowledge: the mesh provides width (~20 diverse random connections), network knowledge provides reach (uniques known to 4 bounces), and the CDN provides depth (content storage and distribution). See the three-layer architecture.

2. Identity & Bootstrap

First startup

1. Identity: Load or generate ed25519 keypair from {data_dir}/identity.key. NodeId = 32-byte public key. This is the network identity only — posting personas use separate keys (see the identity architecture). A unique device identity is also generated for multi-device coordination (see multi-device).
2. Storage: Open SQLite database (distsoc.db), auto-migrate schema.
3. Blob store: Create {data_dir}/blobs/ with 256 hex-prefix shards (00/ through ff/).
4. Port mapping: Attempt UPnP-IGD + NAT-PMP + PCP via the portmapper crate (parallel; first router response wins; ~3s wait). PCP adds IPv6 firewall pinholes and works on iOS without the multicast entitlement. Auto-renewal is internal to portmapper. On Android, WiFi/Ethernet links acquire a WifiManager.MulticastLock for the lifetime of the mapping (cellular skipped). See port mapping.
5. NAT type detection: STUN probes to two public servers (3s timeout each). Classifies as Public/Easy/Hard/Unknown. Port-mapping success overrides to Public. Anchors skip probing. Result stored on ConnectionManager, shared in InitialExchangePayload, stored per-peer. See relay & NAT traversal.
6. Stale knowledge sweep: Remove all stored network-knowledge entries tagged to peers not in the current mesh. Clears stale reach data from previous sessions (e.g., unclean shutdown). Today this sweeps the N2/N3 share-list tables; under the target model it sweeps the uniques store.
7. Bootstrap anchors: Load from {data_dir}/anchors.json. If missing, use hardcoded default anchor.
8. Bootstrap: If the node has fewer than 5 connections at startup, probe known anchors — discovered (non-bootstrap) anchors first, bootstrap anchors only as a fallback phase when every discovered anchor failed. Probes run in batches of 3 (2s stagger between batches, 10s per-anchor timeout, no abort on first success). First success unblocks the bootstrap flow; remaining probes continue in background and fill peer connections naturally. Failed probes to anchors with last_seen > 3 days are immediately pruned from known_anchors. From the connected anchor: run a NAT filter probe, then request convection referrals and begin the growth loop immediately.

Mesh target Rework

The mesh target is ~20 peers (plus +4–10 temporary referral slots that carry no knowledge exchange — see connections). Knowledge reach comes from depth (uniques known to 4 bounces, N1–N4), not from connection count.

Startup cycles

Spawned after bootstrap completes:

3. Anchors & Connection Convection

Intent

An anchor is any directly-reachable, opted-in node — a standard ItsGoin node with a routable address, running the same code with no special protocol. Anchors are the network's entry and re-entry points: they serve bootstrap (first startup), recovery (mesh loss), and convection (topping up under-connected meshes), and they serve public posts over HTTP to browsers (see HTTP delivery). Anchors include VPS-deployed nodes (always-on) and any desktop with a working port mapping.

Candidacy: reachability, not popularity

A node is a viable anchor when a complete stranger can connect to it directly — no introduction, no hole punch, no relay. Candidacy has three parts:

• Reachability watcher Implemented — an event-driven watcher on the portmapper's external-address channel. If the mapping disappears for >5 minutes, anchor candidacy is cleared; when the mapping comes back, it is restored. Mobile never auto-anchors (cellular IPs look public but aren't anchorable).
• Opt-in Planned — anchor service must be explicitly enabled by the operator. Today anchor mode switches on automatically for any reachable desktop; the target adds an opt-in gate (mirroring the session-relay opt-in principle: the nodes most likely to pay for bandwidth get to choose).
• Self-verification probe Implemented — external confirmation of cold reachability, described below.

Anchor self-verification

A port mapping or public IPv6 address is a claim, not proof. The node selects a witness from its network knowledge that is NOT a current peer — a genuine stranger with no prior connection, no cached address, no warm path — reached via the peer that reported it (AnchorProbeRequest, 0xC3). The witness performs a raw cold QUIC connect to the candidate's external address (15s timeout), deliberately skipping the entire resolution cascade — hole punch, introduction, or relay success would be a false positive.

Asymmetric return path: on success the witness reports back over its fresh direct connection (AnchorProbeResult, 0xC4); on failure there is by definition no direct path, so the result routes back through the reporting peer.

Connection convection Implemented

The anchor's referral service is a rotating referral chain — "connection convection." The anchor keeps only a small rolling window of recent callers; there is no peer database and no persistent registration.

1. A caller connects and announces "I'm joining / I need peers."
2. The anchor returns the addresses of the 2 most recent viable prior callers.
3. The caller's own address is handed out to the next 2 callers, then rotates out of the window.

Window parameters (previously open, now decided in code): the window holds 16 entries; each entry is handed to 2 callers before rotating out; an entry older than 15 minutes is not handed out at all — a stale address is worse than none, because it costs the next caller a hole-punch timeout. A caller with no routable address is admitted to nothing. Self-reported addresses are a caller's unverified claim: at most 2 are kept, and when the anchor has an observed address for the caller (essentially always over QUIC) self-reported entries are kept only if they share its IP — a different port is the legitimate endpoint-dependent-mapping case, a different host is not. Only the observed address is ever named in an anchor-initiated introduction; self-reported ones ride the referral payload as a hint the referred peer may try itself.

Sparse-window supplement: a young anchor with an empty window may fill referrals from its own live mesh peers — but those peers never called and never offered themselves for redistribution, so the supplement is consent-shaped. It discloses no address (the referral carries an empty address list and relies on the coordinated introduction, so the target discloses its own addresses on its own terms), it is used only for peers the anchor can actually introduce, and each supplemented peer carries its own hand-out budget (2 per 15 minutes). Without that budget, unconditional entry-class service plus a reshuffle would be an enumeration oracle over the anchor's entire mesh membership.

Request classes: convection requests carry a one-bit class — entry (bootstrap or recovery: fewer than 2 connections) versus top-up (growth with a working mesh). Anchors always serve entry; top-ups are served capacity-permitting and refused cheaply (a single refusal message, no timeout burned), so deprioritizing the non-needy is harmless. The refusal doubles as the load signal the adaptive weights consume. Top-ups are not freeloading: every caller freshens the anchor's referral window, so top-up traffic is the convection medium — a network where nobody tops up hands its next genuine joiner stale referrals.

Referral quality: the anchor prefers callers it is still connected to — and when both the referred peer and the caller are live on the anchor, it coordinates a RelayIntroduce hole-punch introduction between them instead of handing out a cold address. A referred peer lands in whatever slot class is free: a mesh slot first, and only the temporary referral band above the cap when the mesh is full — from there it graduates into a freed mesh slot or expires.

Trigger — stochastic, per-disconnect Implemented: each time a mesh peer disconnects — a temp referral slot expiring is not mesh churn and does not roll the dice — the node randomly chooses one of three actions: do nothing, request an introduction from a random known anchor (mined from the uniques pools — see bookkeeping below), or request an introduction via a connected mesh peer (the growth loop's diversity-scored path — see connection lifecycle). The randomness itself de-synchronizes the network's reaction to shared disconnection events — no jitter timer, no threshold. Because every caller becomes a referral for the next callers, ordinary churn keeps the chain circulating: convection. With IPv6 making anchors abundant (an estimated 20–30% of nodes), anchors rebuild the mesh among themselves and with their callers, absorbing even large disconnection events. The action-choice weights are adaptive, not fixed. The anchor ratio is locally observable — anchor entries are the ones carrying addresses in the pools, so anchor density among known uniques is a free statistic needing no census — and it sets the prior: anchor-rich networks lean anchor-heavy (which also keeps convection windows fresh), anchor-poor lean mesh-ward. Refusals then steer: an anchor refusing a growth request shifts the caller's weights toward mesh introductions and other anchors, drifting back as requests succeed. How many operators will announce addresses versus hide them (or lack public ones) is unknowable before deployment — the adaptive weights are designed to find that ratio rather than assume it. (The node-ID–to–persona ratio stays deliberately unknowable; this statistic never needs it.)

Anchor bookkeeping Implemented

Target: the uniques pools ARE the anchor directory. Anchor entries carry addresses in the N0–N3 pools (see Network Knowledge), so a node needing a connection mines its retained pools for a random anchor-flagged entry. Pool knowledge is overwritten memory: a slot's contributed entries are wiped only when a new handshake replaces them — so a node knocked down from 20 peers to 4 still holds 16 dead peers' pools full of anchor addresses to reconnect through. No separately curated anchor list is needed.

The shipped known_anchors table survives as the bootstrap cache, capped at 32 entries and ordered by last_seen_ms (freshest first). Its old success_count ranking solved an anchor-scarcity problem that pool-mined abundance retires. It is written only for anchors we have actually connected to — never from a peer's announce — which is both what keeps gossip from re-inflating a table the ruling deliberately demoted, and what makes its recency ordering mean something again (a cache refreshed by hearsay would evict the DNS-resolved bootstrap anchor first).

Selection order:

1. Uniques pools Implemented — anchor-flagged entries, shallowest and freshest first, including entries from disconnected peers' retained pools.
2. known_anchors bootstrap cache Implemented — ordered by last_seen_ms descending. Failed probes to entries not seen for 3 days are deleted on the spot (self-healing against stale data dirs).
3. Hardcoded default anchor(s) — only if everything above is empty or exhausted. A brand-new node hits the hardcoded anchor once on first bootstrap, populates its caches from that session, and the hardcoded list recedes to pure fallback.

When anchors are used

• Bootstrap: First startup with an empty peers table — batched probing as described in Identity & Bootstrap, then a convection referral request.
• Recovery: When the mesh drops below 2 connections. Reconnect via anchor addresses mined from the retained uniques pools, then the known_anchors cache, then any still-connected anchor peers.
• Convection top-up Implemented: the per-disconnect stochastic action described above. This is the ONLY ongoing anchor contact — there is no periodic registration.
• itsgoin.net node: A permanent, well-connected ItsGoin node runs on itsgoin.net as part of the share-link redirect infrastructure (see share links). It participates as a standard anchor — it bootstraps new nodes and serves convection referrals — and is not special-cased in the protocol. Its value comes from permanent uptime, not from any privileged role.

Session fallback for full anchors

When an anchor's mesh is full, callers fall back to a session connection. The anchor serves convection requests over session connections, not just mesh — a full mesh never makes an anchor unreachable for referrals.

4. Connections & Slot Architecture Implemented

Connection types

• Mesh connection — long-lived routing slot in a single ~20-slot pool. Structural backbone for search and propagation; participates in the N1–N4 knowledge system's uniques announce (two pools: forwardable N0–N2 + terminal N3 — see Network Knowledge). DB table: mesh_peers.
• Temp referral connection Implemented — short-lived slot above the mesh cap, created by anchor convection or peer introductions. Carries NO knowledge exchange; exists purely to facilitate introductions. Graduates into a mesh slot or expires.
• Cadence-driven session — connection to a social or file-layer peer that isn't in the mesh pool, opened on demand by the update-cadence cycle and closed when idle (see Update Cadence & Keep-Alive). There is no standing keep-alive pool — only the shaped check cycle recurs.
• Session connection — short-lived, held open for active interaction (DM conversations, group activity, anchor matchmaking). Tracks remote_addr so a relay can inject observed addresses during introductions.
• Ephemeral connection — single request/response, no slot allocation.

Slot architecture

MeshConnection struct

Each mesh connection tracks: node_id, connection (QUIC), remote_addr (captured from Incoming before accept), last_activity (AtomicU64, updated on every stream accept), connected_at. The per-slot slot_kind discriminator (Preferred/Local/Wide) is gone with the pool merge; a small enum distinguishes Mesh from TempReferral { expires_at_ms }. Allocation is mesh-first, then the temp band, then refuse — nothing in the rule can evict anything, so an established mesh peer is never displaced by an arriving stranger.

Temp referral slots Implemented

Nodes hold temporary connections above the mesh cap — +10 on desktop, +4 on mobile, within the +4..+10 ruling. These exist so that introductions (anchor convection referrals, growth-loop introductions) never fail for want of a free slot, without paying the knowledge-state cost of a full mesh peer:

• No knowledge exchange — temp referral peers do not participate in the uniques announce exchange, in either direction, and the boundary is structural: a temp peer is never written to mesh_peers, which is the table the announce builder reads. The knowledge gate covers the whole initial exchange, not just the uniques pools: a temp referral peer is also sent an empty peer-address list, since up to 10 of our mesh peers with their addresses is knowledge by any reading. On the wire "no knowledge" is an explicit null, not empty vectors, so the peer can tell "nothing to share" from "not sharing".
• Graduate or expire — when a mesh slot is free, a temp connection can be promoted into it (and only then joins knowledge exchange). Otherwise it expires after its introduction purpose is served.
• Graduation requires a free mesh slot — a temp referral never evicts an established mesh peer.

Mutual mesh blacklist Planned

Targeted two-node stranger relationship. Both nodes opt in, maintaining genuine N2 stranger status indefinitely regardless of growth loop behavior. Stored in a local mesh_blacklist { node_id } table (table does not exist yet).

• Growth loop skips blacklisted nodes during candidate selection
• Incoming mesh upgrade from a blacklisted node → respond with RefuseRedirect (0x05)
• Both nodes must add each other — asymmetric blacklist is valid but only prevents the blacklisting side from upgrading
• Full session/ephemeral interaction still works — messages, probes, routing participation; blacklisted nodes never consume each other's mesh slots

Mesh-cap override Implemented

Topology control for testing, shipped as the ITSGOIN_TEST_MESH_SLOTS environment override rather than the originally-planned --max-mesh <n> CLI flag. It caps a node's mesh pool below the 20 default so the integration suite can reach the temp-referral boundary with four nodes instead of twenty-one, and so a node can be held permanently in other nodes' N2. Read once into a OnceLock at first use — the cap cannot change under a running node. Refusals reuse RefuseRedirect (0x05) — no new protocol machinery. Testing affordance only.

Keepalive Implemented

• Interval: 30 seconds (MeshKeepalive message, 0xE0)
• Zombie detection: no stream activity for 600s (10 min) = zombie, removed in rebalance
• last_activity updated on every stream accept

5. Connection Lifecycle

Growth Loop (reactive, signal-driven) Rework

There is no periodic growth timer. The loop blocks on a signal channel, coalesces queued signals, then runs connection attempts until slots fill or it backs off. Signals fire on:

• Routing knowledge receipt with new N1 additions (initial exchange, routing diff)
• A disconnect that leaves free mesh slots
• Completion of bootstrap/recovery referral connects
• Failed auto-reconnect after an unexpected disconnect
• Rebalance-cycle backstop (every cycle ends by signaling growth)

Candidate selection (N2 diversity scoring) Implemented:

score = 1.0 / reporter_count + (0.3 if not_in_N3)

• Fewer reporters = higher diversity = better candidate. Diversity matters more at 20 slots than it did at 101 — each slot is 5× scarcer.
• Bonus for peers not already visible in N3 (locally discovered, not transitive)
• Sorted descending; already-connected, self, and known-unreachable peers filtered out
• Blacklist filter (Planned): skip nodes in mesh_blacklist

Connection attempt cascade:

1. Direct connect (15s timeout) — stored address, or resolved via AddressRequest to the N2/N3 reporters who announced the candidate
2. Introduction fallback — ask each connected reporter to relay-introduce us (hole-punch coordination)

Failure handling: consecutive-failure counter; after 3 consecutive failures the loop breaks and waits for the next signal. Failed candidates are marked unreachable and skipped in future scoring. After each success the counter resets, a routing diff is broadcast, and the loop pauses 500ms so the new peer's initial exchange can expand the candidate pool before the next pick.

Rebalance Cycle (every 600s) Rework

Executed in order:

1. Dead connection removal: connections with close_reason() set, or idle > 600s (zombie)
2. Stale knowledge pruning: entries tagged to a disconnected reporter are cleared immediately at disconnect time; the cycle adds an age-based sweep (5 hours) plus social-route watcher pruning (30 days)
3. Reconnect recently dead: re-establish dropped mesh connections from stored addresses
4. Signal growth loop: backstop signal to fill any remaining free slots
5. Idle session cleanup: reap interactive sessions idle > 300s (5 min). Sessions with a reason to live are exempt: anchor-side referral-list peers and client-side sessions to known anchors.
6. Relay intro dedup pruning: clear seen_intros entries older than 30s once the map exceeds 500 entries

Recovery Loop (reactive, mesh < 2) Rework

Trigger: fires when the mesh drops below 2 connections — the one non-stochastic case: at the edge of isolation the node always acts, immediately.

1. Debounce 2 seconds (let cascading disconnects settle), coalesce queued signals
2. Gather anchors: mine the retained uniques pools for anchor-flagged addresses (Implemented — disconnected peers' pools survive as overwritten memory until new handshakes replace them), then the known_anchors bootstrap cache, then anchor-flagged entries in the peers table. Anchors that recently refused us are pushed to the back rather than dropped — a refusal is a load signal, not a blacklist.
3. Make a convection call to each anchor in turn: receive referrals, try direct connect to each, fall back to anchor-coordinated hole punch for unreachable referrals (15s per attempt)
4. Signal the growth loop as soon as any connection lands; stale anchors are pruned per the 3-day rule (see Anchors & Connection Convection)

Initial Exchange (on every new mesh connection) Implemented

When two nodes connect into mesh slots, each sends an InitialExchange (0x02) carrying:

• Knowledge share: N1 NodeIds (mesh peers + social contacts, merged) and deduplicated N2 NodeIds — no addresses
• Profile: PublicProfile (display name, bio, avatar CID, visibility flag)
• Delete records: signed post deletions
• Post IDs: local post IDs for replica tracking
• Peer addresses: connected peers with addresses, for social routing
• NAT profile: NAT type, mapping behavior (EIM/EDM), filtering behavior — feeds hole-punch strategy selection
• Observed address: what the sender sees as the receiver's address (STUN-like reflexive discovery)
• Anchor address: the sender's stable advertised address, if it is an anchor
• HTTP capability: whether the sender serves /p/ over HTTP, plus its external HTTP address
• CDN posture: device role (intermittent/available/persistent) and cache-pressure score (0–255)

Processing: their N1 → our N2 table (tagged to reporter), their N2 → our N3 table (tagged to reporter). Store profile, apply deletes, record replica overlaps. New N1 knowledge signals the growth loop immediately.

Incremental Routing Diffs (every 120s + 4h full state) Rework

NodeListUpdate (0x01) carries N1 added/removed and N2 added/removed, sent to connected peers on a 120s cycle; every 4 hours a full-state re-broadcast catches missed diffs. Diffs are also pushed eagerly after each growth-loop connection. Receiver processing mirrors the initial exchange: their N1 adds → our N2 adds, their N2 adds → our N3 adds; diffs with N1 additions signal the growth loop.

6. Network Knowledge: N1–N4 Uniques Implemented

Every node maintains a layered index of uniques — IDs it can help other nodes reach. The index spans four bounces (N1–N4) and is exchanged only between directly-connected mesh peers. Collectively, these per-node indexes form the network's distributed search index: a pull (see Sync Protocol) is an exchange of uniques lists — "if you want these IDs, talk to me and I'll help you find them" — and answering "who can get me to ID X?" is a walk down reporter chains. Content never travels with the index; it lives in the CDN (see Files & Storage).

What is a unique

A unique is any ID a node has a live path to, regardless of why it knows it:

• Mesh peers — our ~20 direct mesh connections
• Directs — social contacts we hold routes for (follows, audience, DM partners)
• CDN file authors — authors of files we hold or recently fetched
• CDN file peers — holders we exchanged files with

Sources are merged before announcing — a receiver cannot tell whether we know an ID from a mesh slot, a friendship, or a file transfer. Anonymous and throwaway IDs (temporary poster IDs in comment chains, greeting senders) are deliberately kept in the lists: they are network noise that protects anonymity and future hooks for anonymous encrypted messaging over temp IDs. Comment TTL expiry (see Delete Propagation) retires them naturally — when the content dies, the throwaway ID falls out of everyone's uniques.

Our own posting identities are never in our own uniques Implemented. Our node ID — and, when we are an anchor, our address — ride slice 0 of the same announce, so listing one of our personas at bounce 1 would be a signed-by-transport persona→device mapping handed to all ~20 mesh peers. It is also the easiest possible mapping to extract: our own personas are the invariant across every announce we send while everything else churns. Every persona is excluded (not just the default posting ID), as is the author of any comment we wrote locally — which covers the per-greeting throwaway IDs we mint, where we would otherwise be the first node in the network to announce the ID, at bounce 1, the instant the greeting was created. Our personas stay discoverable through everyone else who holds our content; we simply must not be the reporter. See Graph Privacy.

Temp referral slots (see Connections) are the one class of direct connection that does not enter the exchange: they carry no knowledge state in either direction until they graduate into mesh slots.

The four layers

There is one reachable table, keyed (reporter_node_id, reachable_id), with bounce, id_class, is_anchor, addresses and updated_at columns — not a table per layer. The composite key gives per-reporter set-merge for free, and the upsert keeps the shallowest bounce ever heard from that reporter, so one ID can never occupy two depths from one source (the ambiguity the old reachable_n2/reachable_n3 pair papered over by sorting).

Announce protocol Rework

• To/from N1 only. Uniques are exchanged exclusively with direct mesh peers — never forwarded on a node's behalf.
• Every announce is a full snapshot Implemented (full: true) that replaces the sender's rows wholesale. Incremental seq-numbered diffing across four layers with anchor metadata was rejected as not worth the divergence risk; instead the sender hashes the pools (ignoring seq) and skips the send entirely when nothing changed, which recovers most of the saving. Slice trimming is deterministic (anchors first, then by ID) so a stable index yields a stable digest rather than thrashing it.
• An announcement carries two explicitly separated pools. Pool 1 — the forwardable pool: our N0–N2 uniques (self + own uniques + two bounces), deduplicated internally. Pool 2 — the terminal pool: our N3 uniques, deduplicated against pool 1. The receiver stores each entry shifted one bounce deeper (pool 1 → their N1–N3, pool 2 → their N4), all tagged to us as reporter.
• The terminal pool is used, never forwarded. Entries received via pool 2 (stored as N4) may be searched and resolved through, but never appear in the receiver's own announcements. The explicit terminal tag is what stops eternal re-propagation — some data must be differentiated as use-only, and there is no N5 anywhere in the network. (Carrying stored N4 in the payload was considered and rejected: dedup math put the resulting stored horizon near ~760k entries per node.)
• Node-class and author-class IDs travel in separate packed arrays Implemented. A slice is { nodes, authors, anchors }: two base64 blobs of concatenated 32-byte IDs plus the address-bearing anchor array. The separation is load-bearing, not cosmetic — a receiver structurally cannot mistake a persona ID for a connectable node ID (so persona IDs never enter connect/hole-punch paths and never burn punch timeouts), and the anchor array is the only place an address can appear. An author-class entry is emitted as a bare ID even if its stored row carries an anchor flag.
• Anchor entries carry addresses; everything else is a bare ID. There is no point sharing an address that cannot be connected without an introduction, so pool entries carry addresses only when flagged as anchors (directly reachable). The uniques index thereby doubles as the network's anchor directory — and with IPv6 pushing an estimated 20–30% of nodes into anchor candidacy, every node's pools hold a deep reserve of re-entry addresses. A received anchor entry is an index row, not an address record: nothing has proven the address belongs to that node ID, so it stays in the uniques index (where the anchor mine reads it) and never mutates authoritative address state. Only an anchor we have completed a QUIC handshake to — iroh having proven the node ID owns that path — is promoted into peers.is_anchor and the known_anchors bootstrap cache. Without that rule a single mesh peer could overwrite our stored address for any node (including the DNS-resolved bootstrap anchor), aim thousands of entries at one victim IP, and have every node one bounce out re-announce them.
• Sizes are enforced, not merely budgeted Implemented. The uniques opcodes read against a dedicated 2 MB ceiling rather than the 64 MB file-transfer cap; built slices are capped (4,000 shallow / 12,000 terminal); received slices are truncated to a per-bounce accept cap (8,000 at N2 and N3, 24,000 at N4) with a log rather than rejected, so a large-but-honest peer degrades gracefully and a hostile one cannot make us write six figures of rows per announce. A payload whose forwardable pool is not exactly three slices is rejected outright — nothing may ever be stored past bounce 4.
• Addresses are filtered on receipt as well as on send Implemented. Inbound anchor addresses are normalized (IPv4-mapped IPv6 → v4) and dropped unless publicly routable; an anchor entry left with no usable address degrades to a bare node entry. Storing a peer-supplied 127.0.0.1 or RFC1918 address would turn the index into attacker-directed internal probing from our own host — and every such dial enters iroh's per-endpoint path store permanently.
• Disconnect retention Implemented: when a peer drops, its reported entries are kept. Pool knowledge is overwritten memory — a reporter's rows are replaced (per reporter, per bounce) only when a new handshake from that reporter lands, which is exactly what lets a node knocked down from 20 peers to 4 mine 16 dead peers' pools for anchor addresses to reconnect through (see Anchors). Staleness is bounded by the 5-hour prune, not by disconnection. Wiping on disconnect would empty the index — and collapse the anchor-density prior that steers the adaptive convection weights — at precisely the moment the node needs both most.
• Refreshes ride the regular update cadence (see Update Cadence & Keep-Alive) so index traffic blends into uniform network overhead.

Deduplication

Dedup happens at both store and announce. Store side: incoming uniques are set-merged per reporter — the same ID reported twice costs one row. Announce side: an ID already announced at a shallower layer is not repeated at deeper layers, so each announcement names each ID at most once, at its closest bounce. Duplication counts are never transmitted (topology leak); dedup keeps the lists to their unique-ID floor.

Size budget

Upper bounds at 20 mesh peers, pure fan-out (real graphs overlap heavily and dedup shrinks all of this):

Because N1 includes directs and CDN contacts (not just the 20 mesh slots), per-node branching runs above 20 and real N4 lists can exceed the pure-mesh bound — the "160k+" is a planning floor, not a ceiling. With reporter tags and SQLite index overhead, expect low tens of MB worst-case on disk. That is acceptable on desktop; if list sizes blow past the budget in practice, the depth default shrinks (<20 peers @ 3 bounces was the explicit fallback in the design ruling).

Device-tiered depth

Depth is a per-device choice, not a protocol constant. Desktop and anchor nodes hold the full N1–N4. Mobile holds 3 bounces Implemented: it drops the terminal pool on receipt and advertises depth = 3 in its announce, so senders skip building the terminal slice for it — the single biggest bandwidth saving on a cellular link. Mobile still announces its own N3, so it remains a full participant in the network's depth; it only declines to store the terminal layer.

Bloom-compressed N4 Planned was the alternative (~10 bits/entry at 1% false-positive → ~200 KB for 160k entries) and is not implemented. A Bloom N4 would answer the only question N4 exists for — "can this peer help me reach ID X?" — without supporting enumeration, which N4 never needs since it is never announced. Dropping is the simpler of the two and is what ships.

Indexed access

A node has indexed access to a target if the target appears anywhere in its N1–N4: the target is then resolvable by reporter-chain queries alone, with no worm search or relay introduction. The update-cadence system (see Update Cadence & Keep-Alive) uses indexed access to decide whether extra session connections are needed for social and file operations. (This replaces the old "<N4 access" term, which meant "within 3 hops" back when N4 didn't exist as a layer.)

What is NEVER shared

• Addresses for non-anchor entries (anchors' addresses ride the pools by design — they are self-declared reachable infrastructure; every other ID resolves on-demand via chain queries. Social-routing payloads are the deliberate, consented exception — see Social Routing and Graph Privacy)
• N4 entries (terminal — held for search, never re-announced)
• Duplication counts (topology leak)
• Why we know an ID — mesh, social, and CDN sources are merged in the announcement

Address resolution cascade (connect_by_node_id) Implemented

Peers that fail all direct steps are marked likely-unreachable, so later attempts skip straight to introduction rather than burning timeouts on dead addresses — but only when a reporter was actually available to ask; failing for want of a connected reporter says nothing about the candidate and must not suppress it. Resolution and growth-candidate scoring now share one horizon (bounces 2–4), and depth is a graded penalty in the scorer so a bounce-4 sighting can never outrank a bounce-2 one. The third reporter-chain link — resolving an N4 hit through the reporter's reporter — has not landed Planned: today an N4 entry is resolved by asking its direct reporter, exactly like N2 and N3.

7. Three-Layer Architecture (Mesh / Social / File) Rework

The network operates across three layers, each with its own connections, routing, and purpose. The division of labor is: mesh is width, CDN is depth. The mesh gives every node a diverse random slice of the network — enough width that searches terminate and the uniques index covers the graph. The CDN gives content a home and every lookup a concrete target — updates, messages, and FoF-adjacent content discovery all resolve to "find a holder, fetch from it."

Key principle: the mesh carries the index, the CDN carries the content

Pulls between mesh peers exchange uniques lists — the search index — never post bodies or blobs. When the index says an author or file exists, the actual bytes come from a CDN holder via a point fetch. So mesh connections stay cheap and optimizable purely for topology (diversity scoring has no social bias), while content bandwidth concentrates on the flat holder set where replication and eviction manage it.

Cross-layer benefits

Each layer feeds the others through the uniques index. Social directs and CDN file contacts enter our N1 alongside mesh peers, so a friendship or a file transfer improves everyone's reach — a follow can provide the N2 entry that helps a stranger's chain query terminate, and a mesh peer can provide the reporter chain that reconnects two friends after an address change. Because sources are merged before announcing, this sharing costs no relationship privacy.

8. Social Routing Implemented

Caches addresses for follows and audience members, separate from mesh connections. Social contacts are consented relationships, so — unlike the uniques exchange — these payloads do carry addresses: that is the point of the layer (see Graph Privacy for the exact scoping). Every social route is also an N1 unique, announced source-merged like any other.

social_routes table

Wire messages Implemented

Reconnect watchers Implemented

reconnect_watchers table: when peer A asks about disconnected peer B, A is registered as a watcher. When B reconnects, A gets a SocialAddressUpdate notification and the watch is cleared. Watchers are pruned after 30 days.

Social route lifecycle

• Follow → store their addresses + referrals, upgrade to Mutual (if audience)
• Unfollow → downgrade/remove
• Approve audience → Mutual/Audience

Role under the v0.8 model

Social routing is the warm path for the people you actually talk to: step 0 of the address resolution cascade, the delivery route for DMs, and the freshness signal that drives the top tiers of the update cadence (see Update Cadence & Keep-Alive — messaged, followed, and vouched relationships check most often). Content from social contacts still arrives via the CDN like everything else; the social layer only carries the addresses and the relationship state.

9. Relay & NAT Traversal Implemented

How a node reaches a peer behind NAT: a mutual contact performs introduction (signaling only), then both sides hole punch. Relaying actual session bytes through a third party is a separate, opt-in facility (see below) — introduction and hole punching are always on.

Relay selection (find_relays_for) Rework

Find up to 3 relay candidates from knowledge-layer reporters, prioritized:

1. N2 reporters: Our mesh peers who announced the target among their own uniques. They are connected to the target right now (or were very recently). TTL=0.
2. N3 reporters: Peers whose announced knowledge places the target two hops away. TTL=1 — the relay chains the introduction through its own peer.
3. Deep uniques reporters: With N1–N4 knowledge (see Network Knowledge), the uniques index names which mesh peer "can help reach" the target even when the target sits three or four bounces out. The introduction chains along the announce path, decrementing TTL at each hop (max TTL=2).

RelayIntroduce flow (0xB0/0xB1)

1. Requester → opens bi-stream to relay, sends RelayIntroduce { target, requester, requester_addresses, ttl }
2. Relay handles three cases:
   • We ARE the target: Return our addresses, spawn hole punch to requester
   • Target is our mesh or session peer: Forward request to target on new bi-stream, relay response back. Inject observed public addresses for both parties (session peers carry remote_addr from their inbound connection).
   • TTL > 0 and target in our N2: Forward to the reporter with TTL-1 (chain forwarding, max TTL=2)
3. Requester receives RelayIntroduceResult { target_addresses, relay_available }, then:
   • hole_punch_parallel(): Try all returned addresses in parallel, retry every 2s, 30s total timeout
   • If hole punch fails, relay_available is true, and the local user has enabled session relay: open SessionRelay (0xB2) pipe through the intermediary

Anchors also perform introduction as part of connection convection: when a convection caller and a referred peer are both live on the anchor, the anchor coordinates RelayIntroduce between them (see Anchors).

Session relay (relay pipes)

Intermediary splices bi-streams between requester and target. Desktop: max 10 concurrent pipes. Mobile: max 2. Each pipe has a 50MB byte cap and 2-min idle timeout.

This rule covers only full byte-piping. Small relay-style signaling/discovery — RelayIntroduce for hole-punch coordination, worm_lookup multi-hop search, uniques-list announce exchange — remains always-on; that's not session relay. The anchor's HTTP proxy path (anchor fetches a post via QUIC and serves it back over HTTP) is also not session relay — it's the anchor doing its own QUIC fetch on the browser's behalf.

Deduplication & cooldowns

Hole punch mechanics

Both sides filter self-reported addresses to publicly-routable only (no Docker bridge, VPN, or LAN IPs) and prepend the port-mapped external address if available. The relay injects each party's observed public address (from the QUIC connection) at the front of the list. All paths use hole_punch_parallel(): parse returned addresses into QUIC EndpointAddr, spawn parallel connect attempts to every address simultaneously. Each attempt: 2s timeout, retried until 30s total deadline. First successful connection wins.

NAT type detection Implemented (interim: public STUN servers)

On startup, each node classifies its NAT type as one of four categories:

• Public — observed address matches local, or port-mapped. Directly reachable.
• Easy — same mapped port from multiple probes (endpoint-independent mapping / cone NAT). Hole punch will likely succeed.
• Hard — different mapped ports per destination (symmetric / address-dependent mapping). Port is unpredictable.
• Unknown — detection failed or not yet run.

Current implementation (interim)

Raw STUN Binding Requests (20 bytes, no crate dependency) sent to stun.l.google.com:19302 and stun.cloudflare.com:3478 from a single UDP socket. XOR-MAPPED-ADDRESS parsed from each response (IPv4 + IPv6 supported). Comparison: same mapped port = Easy, different = Hard, matches local = Public. 3s timeout per server. Port-mapping success overrides to Public. Anchors skip probing entirely (already Public).

Target design (multi-anchor STUN) Planned

When the network has enough anchors, replace public STUN servers with anchor-reported your_observed_addr from InitialExchange. Connecting to two or more anchors at different public IPs provides the same classification without external dependencies. Anchor convection makes this cheap: the convection trigger already contacts anchors periodically.

NAT type sharing

NAT type is included as a string field ("public"/"easy"/"hard"/"unknown") in InitialExchangePayload. Stored per-peer in the peers table (nat_type TEXT column). Available for hole punch decisions before any connection attempt.

Hole punch strategy

All hole punch paths use hole_punch_with_scanning(). NAT profiles (NatMapping + NatFiltering) from InitialExchange determine whether scanning is attempted. Behavioral inference updates filtering classification from connection outcomes.

Advanced NAT traversal (EDM port scanner) Rework

NAT "hardness" has two independent dimensions:

• Mapping: Endpoint-Independent Mapping (EIM / "easy") uses the same external port for all destinations. Endpoint-Dependent Mapping (EDM / "hard") assigns a different port per destination.
• Filtering: Address-restricted (Open) accepts from any port on an IP the host has sent to. Port-restricted accepts only from the exact IP:port the host has sent to.

STUN probing at startup classifies mapping (EIM/EDM). Filtering is determined reliably via the anchor filter probe.

NAT filter probe (0xC6/0xC7)

At startup, after first anchor contact, each node with Unknown filtering sends a NatFilterProbe bi-stream request to its anchor. The anchor creates a temporary QUIC endpoint on a random port and attempts to connect to the node’s observed address (2s timeout). If the connection succeeds, the node is Open (address-restricted or better — accepts packets from any port on the anchor’s IP). If it times out, the node is PortRestricted.

The result feeds into all subsequent InitialExchange payloads, so peers know each other’s exact filtering type.

Note: “Public” NAT type does not automatically mean Open filtering. A node may be public on IPv6 but NATed on IPv4. The filter probe tests actual reachability from a different port, regardless of self-declared NAT type. Startup logs report public (v4 only), public (v6 only), or public (v4+v6).

NAT combination matrix

Key insight: if both sides have Open (address-restricted) filtering, scanning is never needed — should_try_scanning() returns false and basic hole punch handles it.

Role-based scanning protocol

Each side independently determines its role based on its own NAT profile:

• EIM (stable port) → Puncher: Punch peer’s anchor-observed address every 2s. Our port is stable — the peer’s scanner will find us.
• EDM or Unknown → Scanner+Puncher: Walk outward from peer’s anchor-observed base port at ~100 ports/sec (base, base+1, base-1, base+2, base-2, ...). Each probe opens a firewall entry on our NAT. Also punch every 2s to check if peer has opened their port for us.

The scanner opens ports on its own firewall. The other side’s periodic punch (one every 2s to the scanner’s observed address) checks if the scanner has opened a port matching the puncher’s actual port. For both-EDM pairs, both sides scan and punch simultaneously.

Scan parameters

• Rate: ~100 ports/sec (one probe every 10ms)
• In-flight: ~20 concurrent (100/sec × 200ms connect timeout)
• Direction: Outward walk from anchor-observed base port
• Target address: Anchor-observed (relay-injected) address only — not VPN/cellular/LAN addresses
• Max duration: 5 minutes (covers full 65K port space at ~100/sec in ~11 minutes; ±2000 range covered in first 40 seconds)
• Task management: JoinSet with abort_all() on success or exhaustion — no orphaned tasks
• Punch interval: Every 2s to peer’s anchor-observed address

Why 5-minute scan duration is acceptable

The cost is time, not resources (~20 in-flight at any time, ~100 probes/sec). For connections that would otherwise be impossible (both EDM + port-restricted), accepting a longer setup time is far better than giving up entirely. Most successful connections resolve within the first 40 seconds (±2000 port range).

10. Port Mapping — UPnP-IGD + NAT-PMP + PCP Implemented

Purpose

Asks the local gateway router to forward an external port to this node's local QUIC port. A successful mapping makes the node directly reachable from the internet without hole punching — any peer with the external address can connect immediately. Three protocols are attempted in parallel; the first router-response wins.

Protocols

• UPnP-IGD — long-standing consumer-router default. Discovery via SSDP multicast on 239.255.255.250:1900. Behavior varies; many routers ship with UPnP disabled by default.
• NAT-PMP (RFC 6886) — Apple lineage; widespread on routers that ever shipped Bonjour. Unicast to the gateway on UDP/5351.
• PCP (RFC 6887) — modern IETF-track successor to NAT-PMP. Unicast on UDP/5351. Supports both IPv4 NAT mapping and IPv6 firewall pinholes. Works on iOS without the multicast networking entitlement.

Implementation uses the portmapper crate (also used by iroh internally), wrapped in the upnp.rs module (named for historical reasons; it covers all three protocols); network.rs holds the resulting mapping handle alongside the iroh Endpoint — port mapping is an Endpoint concern, not a connection concern.

Startup flow

bind Endpoint → spawn portmapper Client (UDP) → wait up to 3s for first protocol response → bootstrap (TCP mapping fires in parallel for HTTP serving)

1. Probe all three protocols in parallel: portmapper's background service fires UPnP-IGD discovery + NAT-PMP unicast + PCP unicast concurrently. First success wins; failures from the others are absorbed silently.
2. UDP mapping for QUIC: maps the local QUIC port to an external port. Required for direct inbound. Address feeds self-identification, InitialExchange, anchor candidacy, and peer address advertisements.
3. TCP mapping for HTTP: separate parallel attempt for HTTP serving (see HTTP Content Delivery). Independent of UDP — either can succeed alone. Phones with permissive NAT can serve HTTP directly to browser fetches.
4. Per-platform behavior: All three protocols on desktop. On Android, a WiFi/Ethernet gate skips probing on cellular (no UPnP/PCP gateway exposed by carriers) and a WifiManager.MulticastLock is held for the lifetime of the mapping so UPnP-IGD's SSDP responses actually arrive. On iOS, PCP and NAT-PMP work without the multicast entitlement; UPnP-IGD silently fails until the entitlement is granted.

Auto-renewal

The portmapper::Client renews leases internally in a background task. No external renewal cycle to schedule. Dropping the PortMapping handle aborts the renewal task and releases the mapping.

Bidirectional anchor reachability watcher

A startup-spawned task watches the UDP mapping's reactive external-address channel:

• Mapping lost for >5 min → clear is_anchor. The node stops advertising itself as an anchor at a now-stale external address.
• Mapping restored (None → Some) → re-evaluate auto-anchor. On non-mobile devices the anchor flag is set back on so the node re-joins the anchor set without a restart.

Network roams between UPnP-capable WiFi networks self-heal. Mobile devices never auto-anchor regardless — cellular IPs look public but sit behind CGNAT.

Port mapping drives anchor candidacy

A node with a successful mapping is directly reachable from the internet — which is the only thing that makes an anchor an anchor. Anchor candidacy under v0.8 is exactly this: stable direct reachability (the watcher above) + opt-in, not a peer-count threshold. When the mapping succeeds on an opted-in non-mobile node, is_anchor is set and the node begins offering the convection service (see Anchors); when the mapping is lost, it reverts to non-anchor and peers prune the stale entry via failed-probe pruning. Any desktop on a home network with a mapping-capable router becomes a potential entry point for the network, with no manual server deployment.

Shutdown

Explicitly release the mapping on clean shutdown. Routers have finite mapping tables — releasing is good citizenship.

Integration with existing address logic

The mapped external address is treated the same as any other address the node knows about. It feeds into:

• Self-identification: Included when identifying ourselves to peers so they store a routable address
• InitialExchange: Advertised to new connections
• Anchor convection: The address handed to convection callers as a referral (see Anchors)
• Social routing: Available in the social route address cache for follows/audience
• Relay introduction results: Returned alongside hole-punch candidate addresses
• HTTP serving eligibility: A node only serves browser traffic (or lists itself as a redirect target) if it has confirmed TCP reachability — either via a TCP port mapping or a known public IPv6 address (see HTTP Content Delivery)

Why this matters for mobile

Mobile devices on cellular networks cannot use UPnP (carrier NAT doesn't expose it). However, if the peers they're trying to reach (especially desktop nodes and anchors) have port mappings, those peers become directly reachable from the phone without hole punching. The phone doesn't need a mapping — the other side does.

Honest limitations

11. LAN Discovery Planned (passive lookup Implemented)

What exists today: passive mDNS address lookup

iroh's built-in MdnsAddressLookupBuilder is registered on the endpoint (service name "irohv1", backed by the swarm-discovery crate). It resolves addresses passively: when this node already knows a peer's NodeId and tries to connect, mDNS supplies the peer's LAN address if the peer is on the same network segment, and the connection rides the local link. There is no subscribe loop, no proactive session establishment, and no LAN-specific treatment beyond address resolution.

Active discovery flow

1. Hold the mDNS handle: Build MdnsAddressLookup explicitly (not via the endpoint builder) so we retain a clone for subscribing.
2. Spawn a LAN scan loop: Call mdns.subscribe().await to get a stream of DiscoveryEvent::Discovered and DiscoveryEvent::Expired events.
3. On discovery: Extract NodeId + LAN addresses from the event. If not already connected, initiate a direct connection + initial exchange. Register as a LAN session (its own planned session class — see below).
4. On expiry: Clean up the LAN session. Peer left the network or powered off.

LAN sessions

LAN peers are special: zero-cost bandwidth, sub-millisecond latency, and very likely someone you know (same household/office). They deserve their own treatment beyond regular mesh or session slots:

• Automatic keep-alive: LAN sessions stay open as long as the peer is on the network (mDNS heartbeat). No idle timeout. Not counted against session slot limits. This is a deliberate, explicitly-scoped exception to the no-standing-sessions rule (see Update Cadence & Keep-Alive), justified by zero-cost local bandwidth.
• Sync priority: Update checks and uniques exchanges go to LAN peers first — instant delivery over the local link.
• Local relay: relaying traffic between LAN peers costs nothing, so limits on LAN-local relaying can be much more generous than over the internet. Relaying a LAN peer out to the wider internet — e.g., a phone behind carrier NAT riding the desktop's port-mapped connection — is session relay: it consumes the serving device's WAN bandwidth and remains gated by relay.session_relay_enabled, opt-in and OFF by default (see Relay & NAT Traversal). A same-owner linked-device carve-out may be proposed later, but only as an explicit opt-in extension, never as automatic behavior.
• Blob transfer: Large blob transfers between LAN peers are essentially free. Prefer LAN peers as blob sources when available.

Design rationale

Today, two devices on the same WiFi network only connect over the LAN if one already knows the other's NodeId. That's a narrow win — they're on the same network segment and should find each other unaided. Active LAN discovery turns mDNS from a passive address resolver into an active peer source, exploiting the fact that local bandwidth is essentially unlimited.

The LAN-session pattern means a household with one well-connected desktop and several phones creates its own mini-mesh: the desktop provides anchor-like connectivity (routing the phones' traffic through it requires the owner's session-relay opt-in), and everyone syncs instantly over the LAN even when the internet connection drops.

12. Worm Search Implemented

The network's point-query mechanism: given a specific NodeId, post ID, or blob ID, find someone who has it. Used at step 4 of connect_by_node_id, after direct-address and N2/N3 resolution fail. Under v0.8 it is the fallback behind the uniques index — deep N1–N4 knowledge answers most "who can reach X" questions locally, and worm search covers the remainder.

Algorithm

1. Build needles: target NodeId + up to 10 of the target's recent peers (from their stored profile) — 11 needles total. Finding anyone who can reach any needle gives a path to the target.
2. Local check: Search own connections + N2/N3 for any needle. Also check local storage, known file_holders, and the blob store for any requested post/blob content.
3. Burst (500ms timeout): Send WormQuery{ttl=0} (0x60) to all mesh peers in parallel. Each peer runs the same local check against its own knowledge.
4. Nova (1.5s timeout): Each burst response includes a random referral to one of the responder's other peers (historically called a "wide referral," after the retired Wide slot tier). Connect to those referrals and send WormQuery{ttl=1}; the referred peer fans out to its own mesh with ttl=0. Expansion is one hop at a time rather than a flood, keeping network pressure low.
5. Total timeout: 3 seconds for the entire search.

With a ~20-peer mesh the raw two-hop fan-out is a few hundred nodes — smaller than the old 101-mesh's reach — but under the v0.8 knowledge model Rework each queried peer will answer from much deeper knowledge: its N1–N4 uniques (tens of thousands of IDs at 4 bounces) plus its file_holders map. (Today peers answer from N2/N3 share lists.) Coverage shifts from "how many nodes did the query touch" to "how much does each touched node know".

Content search

WormQuery carries optional post_id and blob_id fields, enabling unified search for nodes, posts, and blobs in a single query. Each peer checks:

• Posts: local storage (direct match), then the flat file_holders map (up to 5 known holders per post — see Content Propagation)
• Blobs: local blob store, then CDN post ownership (get_blob_post_id → file_holders)

WormResponse carries post_holder and blob_holder fields alongside the node search results. A content hit (post or blob holder found) is treated as a successful response even without a node match.

PostFetch (0xD4/0xD5)

Lightweight single-post retrieval after worm search identifies a holder. Opens a bi-stream to the holder and requests one post by ID. Much lighter than a full pull exchange — no filtering, no batch processing, just the target post.

Dedup & cooldown

13. Update Cadence & Keep-Alive Rework

Purpose

One scheduled system drives all recurring traffic: content freshness checks, uniques-list refresh, and connection keep-alive. Every node runs a check cycle whose per-item frequency descends from minutes to days, computed from two axes:

• Freshness — how recently the content saw a comment, update, or engagement. Fresh content is checked often; stale content decays toward daily checks.
• Relationship tier — how much the local user cares, in descending priority: actively searching/engaging right now → own content (posts of ours held elsewhere) → messaged → followed → pinned → vouched → vouched-by → reacted-to. Untiered content sits at the floor cadence.

The effective interval is the product of both axes: a followed author's post commented on an hour ago might check every few minutes; a reacted-to post untouched for a month checks daily.

What rides the cycle

• Content update checks: fetch new comments/edits for held posts from their holders (CDN-level, no mesh involvement).
• Uniques-list refresh: the uniques announce (two pools: forwardable N0–N2 + terminal N3 — see Network Knowledge) with mesh peers piggybacks on the same scheduler — it doubles as the mesh keep-alive.
• Replication traffic: holder-count maintenance and the author-concealment push (see Content Propagation) are deliberately scheduled through the same shaped cycle.

Same-author dedup

A successful check against one of an author's posts is evidence about all of them: their other posts' checks are deprioritized (pushed later in the cycle) rather than fired back-to-back. This is the main lever for finding the lowest viable cadence — per-author, not per-post, contact frequency.

Jitter as traffic shaping

Every interval carries random jitter, and checks are spread rather than batched at tier boundaries. The goal is that a node's outbound request stream looks like uniform network overhead: an observer watching traffic timing should not be able to infer which authors the user cares about, which posts are theirs, or where content originated. Request-timing correlation is the primary deanonymizer in a P2P network; the cadence system is the defense (adversary model in Graph Privacy).

Mobile

Mobile stretches all cadence bands and batches wakeups — the radio is the battery cost, not the bytes. Background-restricted platforms run the cycle only while the foreground service is alive.

Implementation status

The seed exists: a freshness-tiered engagement check in storage (get_posts_due_for_engagement_check) schedules per-post checks at 5 min / 1 h / 4 h / 24 h keyed on last-engagement age. The relationship-tier axis, same-author dedup, jittered shaping, and the uniques-refresh piggyback are not built — the current code is the freshness axis only.

14. Content Propagation

Intent

"Attention creates propagation": when you view something, you cache it. The cache is optionally offered for serving. Hot content spreads naturally through demand. Cold content decays unless intentionally hosted.

Content travels through the network exclusively via the CDN: the mesh provides width (who exists, who can reach whom — the N1–N4 uniques index), the CDN provides depth (the actual posts, blobs, comments, and updates). A pull tells you who to talk to; the CDN holder model is how the bytes move.

The flat holder model Implemented

Every file (blob CID) has a single flat set of known holders in the file_holders table, capped at 5 per file with LRU eviction — the 5 most recently interacted-with holders survive, older entries are dropped. A holder entry records the peer's NodeId, last-known addresses, last interaction time, and a direction flag:

Holder knowledge accretes as a side effect of every transfer: serving a blob registers the requester, fetching a blob registers the source, replication acceptance registers both ends, and engagement propagation refreshes entries. No registration protocol exists — the table is a passive record of observed reality, which is why the LRU cap is safe: stale entries age out under real traffic.

Holder redirect at capacity Implemented

When a node serving a BlobRequest already knows 5 holders for the file, it still serves the bytes but declines to register the requester (cdn_registered: false) and instead returns its holder list as redirect candidates. The requester records those peers as additional sources for future lookups. This spreads lookup load across the holder set instead of concentrating it on whichever node happens to be well-known.

Manifest freshness Implemented

• ManifestPush (0x94): when an author posts again, updated AuthorManifests for their blobs are pushed to the file's known holders; a receiving holder re-pushes newly-stored manifests to its own connected holders of the same CID, excluding the sender. No tree structure — propagation follows the flat holder set.
• ManifestRefreshRequest/Response (0x92/0x93): pull-side counterpart — "has this manifest changed since updated_at?" Used by the update-cadence cycle (see Update Cadence & Keep-Alive) to pick a refresh source from file_holders.
• BlobHeaderDiff/BlobHeaderRequest (0xD0/0xD1): engagement state (comments, reactions, encrypted slots, FoF ops) travels as header diffs between holders; a header can be fetched without retransferring blob data.

Passive discovery via manifest neighborhoods

Every AuthorManifest carries a neighborhood of the author's surrounding PostIds. Holding any file by author X therefore passively reveals some of X's other recent posts — hosts of old content are pulled toward new content by the same author. Attention creates propagation. In v0.8 the neighborhood is deliberately small: it is capped to the author's concealment budget of 2–5 publicly revealed posts (below), not a full recent-history window.

Active replication cycle Rework

Authors own durability for their own recent content. Every 10 minutes, a node checks its own posts younger than 72 hours; any with fewer than 2 known holders are offered to connected peers via ReplicationRequest. Target selection ranks peers by device role (Available desktops > Persistent anchors > Intermittent phones) plus advertised cache pressure. Accepting peers store the blob and both ends record each other in file_holders.

Author concealment & traffic shaping Planned

The replication cycle is also the privacy mechanism. An author's node publicly holds and reveals only 2–5 of its own posts at any time; the surplus is pushed out to holder sets on other nodes via replication requests, so the full catalog is served from behind public mesh IDs rather than from the author's device. Combined with the jittered update cadence, the goal is that update and replication traffic is indistinguishable from uniform network overhead — an observer watching traffic cannot tell where content originates or which node is the author. The adversary model is detailed in Network Graph Privacy.

Deletion

There is no delete notification message. Deletes are signed control posts that propagate through the same manifest/pull machinery as any other post; holders that process one drop the content and its holder entries, and everyone else's copy ages out via LRU eviction. Details in Delete Propagation & Expiry.

15. Files & Storage

Blob storage Implemented

Blob content immutability

Blob data is BLAKE3-addressed — the CID is the hash of the content. This means blob content is immutable by definition. Any mutable metadata (engagement, holder knowledge, signatures) MUST be stored separately in a BlobHeader. Inline mutable headers are architecturally incompatible with content addressing.

BlobHeader Implemented

Mutable structure stored and transmitted separately from blob data. Carries engagement state and encrypted slots for private posts; mutations travel as BlobHeaderDiff ops between holders.

BlobHeader {
    post_id,                // PostId this header belongs to
    author,                 // Author posting ID
    reactions,              // Vec of public reactions (emoji + reactor + timestamp)
    comments,               // Vec of comments (text + author + timestamp + signature)
    policy,                 // Author-controlled CommentPolicy (incl. FriendsOfFriends)
    updated_at,             // Timestamp of last header update
    thread_splits,          // Linked thread posts when comments exceed 16KB
    receipt_slots,          // Encrypted delivery/read/react receipt slots (private posts)
    comment_slots,          // Encrypted comment slots (private posts)
    prior_author,           // Original author before cross-identity post merge (optional)
}

Header diffs also carry the FoF lifecycle ops (FoFRevocation, FoFAccessGrant, FoFKeyBurn — see Friend-of-Friend Visibility) and, in the v0.8 target, each comment carries its expiry timestamp fixed at creation (see Delete Propagation & Expiry).

Blob transfer flow (0x90/0x91) Implemented

1. Requester sends BlobRequest { cid, requester_addresses }
2. Host checks local BlobStore and delivery budget:
   • Has blob, budget OK: Return base64-encoded data + CDN manifest (with current holder count). If the host knows fewer than 5 holders, register the requester (cdn_registered: true); otherwise return the known holders as cdn_redirect_peers.
   • No blob / budget exhausted: Return found: false
3. Requester verifies CID, stores blob locally, records the host in file_holders (direction received), and stores any redirect peers as additional holder knowledge.

Manifests Rework

• AuthorManifest: ed25519-signed by the post author (posting key). Contains the anchor post, creation/update timestamps, and the author's post neighborhood. In v0.8 the neighborhood is capped to the 2–5 post concealment budget and the manifest carries no device addresses — readers reach the author's content through file_holders search, never through addresses tied to the posting identity.
• CdnManifest: AuthorManifest + serving-host metadata. The v0.8 wire format drops the legacy tree fields (source, source addresses, downstream count) as part of the clean protocol break (see Sync Protocol).

Blob eviction Implemented

priority = pin_boost + share_boost + (relationship × heart_recency × freshness / (peer_copies + 1))

Eviction is also the passive half of delete propagation: unreferenced blobs (orphaned by a delete control post that hasn't reached this node) simply score low and age out.

Pin modes Planned

The CDN is delivery infrastructure, not storage. Authors own durability. Pinning extends content in the local delivery pool — it is not a network obligation.

16. Erasure-Coded CDN Replication Planned

Problem

Full-copy replication works well when the replicating node chose to pull the content — a follow relationship or explicit action establishes user consent. But the ReplicationRequest (0xE1) protocol also pushes content to infrastructure nodes that never chose to host it. A node holding a full copy of content it never reviewed faces potential liability for that content.

Encryption does not solve this for public posts: the content is plaintext by definition. A different mechanism is needed that makes it technically impossible for a CDN node to possess reconstructable content.

Approach: sub-threshold erasure shards

Instead of replicating full blobs, public post auto-replication distributes erasure-coded shards using a 3-of-10 scheme (k=3, n=10). Each shard contains 1/3 of the data. Reconstruction requires cooperation from any 3 of the 10 shard holders. A single shard is mathematically meaningless noise — not encrypted content where the full payload exists behind a key, but genuinely incomplete data that cannot be reconstructed alone.

Where sharding applies

The existing storage tiers each have their own liability story. Sharding only fills the gap for public auto-replication:

Composition with the flat holder model

Each shard is content-addressed like any other blob and tracked through the same file_holders machinery, keyed on the shard's own CID. The 5-holder LRU cap applies per shard, so the 10 slots of a 3-of-10 chain are 10 independent holder sets — the cap and the slot count do not interact. Eviction scoring, holder redirect, and manifest refresh work unchanged; sharding is an additional layer on the auto-replication path only, and full copies continue to flow through the flat model untouched.

Shard assignment

Slot assignment is deterministic from the PostId via DHT-style hashing, carried in the existing BlobHeader metadata — no additional discovery round required. Each node enforces single-slot acceptance: it only accepts shard push offers for its assigned slot, rejecting others. This prevents a bad actor from accumulating multiple shards toward the reconstruction threshold. Slot assignment is acceptance policy, not exclusivity — transient duplicate holders for the same slot are harmless and add redundancy.

Health monitoring

• ≥5 live slots: healthy, no action
• 4 live slots: trigger background re-replication, targeting the longest-dark slot first
• <3 live slots: content at risk (requires catastrophic loss of 8+ nodes simultaneously)

Interaction with full copies

As content gains followers, the follow graph naturally absorbs redundancy through full-copy pulls. The shard layer can back off:

• 2+ known full copies: equivalent to ≥4 live shards → shard chain deprioritizes, may decay
• 1 full copy: shard chain reformation trigger
• 0 full copies: shard chain is sole redundancy, maintain aggressively

This means popular content automatically shifts from CDN shard infrastructure to the social follow graph. The shard layer only works hard for content nobody has explicitly chosen to keep — exactly the content with the highest liability exposure.

Re-replication

When a slot goes dark, a new shard holder is assigned via DHT. The new holder determines which chunks belong to its slot and pulls only those chunks from the live shard holders that have them. No shard holder ever reconstructs the full content — each node only ever possesses its own slot’s chunks. The pulling node identifies what it needs, requests those specific chunks, and aggressively refuses anything outside its assigned slot. The author’s node can go offline permanently once shard replication is established.

Replication window

Active shard push replication applies the same 72-hour window as full-copy replication: only posts less than 72 hours old are actively pushed to shard holders. Beyond 72 hours, the shard chain relies on natural decay and pull-based replication only.

Exception — share link re-promotion: When a share link is added to a post’s BlobHeader, the 72-hour active replication window resets from that event. This ensures that content being actively shared gets CDN-prioritized delivery regardless of original post age. The re-promotion window is 72 hours from the share link addition, not from the original post timestamp.

Implementation path

Extends the existing ReplicationRequest/ReplicationResponse (0xE1/0xE2) protocol. Shard slot metadata fits in the existing BlobHeader. Flat holder tracking and eviction scoring continue to work unchanged for full copies. Shard traffic also serves the traffic-shaping goal: shard pushes are one more class of replication traffic that makes origin-tracing harder.

17. Sync Protocol Rework

Wire format Implemented

[1 byte: MessageType] [4 bytes: length (big-endian)] [length bytes: JSON payload]

Max payload: 64 MB. ALPN: itsgoin/4. Every message travels on its own QUIC stream — uni-directional for fire-and-forget pushes, bi-directional for request/response pairs. Unknown message-type bytes fail the stream; unknown fields inside known payloads are ignored by serde.

Message types (40 total; rows marked “Removed in v0.8” are kept for history) Implemented

Retired type bytes, never reused: 0x42–0x45 (PostNotification/PostPush/AudienceRequest/AudienceResponse, v0.6.2), 0x95 (BlobDeleteNotice — holders evict via LRU, no notice needed), 0xA0 (GroupKeyDistribute — group seeds travel as encrypted posts).

Pull = uniques-index exchange Implemented

In v0.8 a pull is not a post transfer. A pull exchanges uniques lists: the set of unique IDs each side can help the other reach — mesh peers, direct contacts, CDN file authors, and CDN file peers, including throwaway/anonymous IDs (deliberate noise that protects real identities). The semantics are “if you want one of these IDs, talk to me and I'll help you find their CDN holders to connect to and search.” The union of these lists across the mesh forms a distributed search index — the same index that powers person-discovery for the registry. What a node knows and announces at each depth (N1–N4, termination rules, dedup, size budgets) is specified in Network Knowledge; this section covers only the wire exchange.

Content itself never rides the pull path: posts and blobs travel through the CDN (PostFetchRequest/BlobRequest against holders resolved through the index — see Content Propagation). The old “never pull from mesh peers” principle dissolves cleanly: the mesh exchanges the index, the CDN carries the content.

The pull opcodes (0x40/0x41) now carry only the index — that is what makes "a pull is not a post transfer" literally true of them. Post bodies still move between mesh peers over a separate, explicitly transitional content-sync pair (0x46 ContentSyncRequest / 0x47 ContentSyncResponse) Rework, which exists until the CDN cadence work in Iteration D can carry everything. Read caps differ accordingly: the uniques opcodes read against a 2 MB ceiling, not the 64 MB file-transfer cap.

Recipient matching (merged pull) Implemented

The query list a node sends with a pull merges its public follows with every posting identity it holds, so DMs addressed to any of its personas match. The responder's filter, should_send_post(), sends a post when:

1. Author is the requester → always send (own posts relayed back)
2. Public or FoFClosed + author in the query list → send (FoFClosed carries no recipient IDs on the wire; it propagates by author like public content)
3. Encrypted + any wrapped-key recipient in the query list → send
4. GroupEncrypted + any known group member in the query list → send
5. Otherwise → skip

The network NodeId is never an author or recipient (persona split), so it never appears in query lists. This matching machinery survives the v0.8 pull redefinition as the visibility filter on CDN content fetches.

Manifest machinery Implemented

Each post's AuthorManifest carries the author, creation/update timestamps, a post neighborhood (up to 10 previous + 10 following ManifestEntry items), and an ed25519 signature over the canonical digest. It travels wrapped in a CdnManifest alongside blob responses and via ManifestPush (0x94). On receipt:

• Signature verified; unsigned or forged manifests dropped
• Newer-wins: stored only if updated_at beats the local copy
• Holder tracking: the pusher is recorded in file_holders (they evidently hold the file)
• Relay: the manifest is re-pushed to connected file holders of the same CID, excluding the sender
• Post discovery: neighborhood post IDs from followed authors that are missing locally are fetched via PostFetch, capped at 10 per push to avoid storms

ManifestRefreshRequest/Response (0x92/0x93) let any holder check manifest freshness for a CID and receive the newer copy. This is how a post's neighborhood keeps growing on CDN copies after the author publishes newer posts.

Engagement propagation via file holders Implemented

Reactions, comments, policy changes, slot writes, and FoF ops propagate as BlobHeaderDiff (0xD0) batches through the flat holder set — there is no tree:

• Push: on receipt of a diff, the sender is recorded as a holder, ops are verified and applied, the header JSON is rebuilt from the authoritative tables, and the diff is re-propagated to all known file_holders of the post (flat set, max 5), excluding the sender.
• Holder registration: nodes that receive a post via pull or manifest discovery send PostDownstreamRegister (0xD3) to the sender, which simply records them in the sender's file_holders — ensuring diffs flow both ways.
• Pull (safety net): tiered polling by engagement freshness — 5 min (<72h), 1 hr (3–14d), 4 hr (14–30d), 24 hr (older) — via a single SQL pass over last_engagement_ms/last_check_ms. BlobHeaderRequest (0xD1) carries the local header timestamp; peers respond with the full header only if theirs is newer. In v0.8 this cadence folds into the update cadence system with jitter as traffic shaping.
• Tombstones: deleted reactions and comments keep a deleted_at timestamp instead of being hard-deleted, and propagate through header rebuilds — preventing re-introduction by peers that missed the deletion.

Engagement security Implemented

Engagement operations are cryptographically verified on receipt to prevent forgery and unauthorized modification:

• Reaction signatures: each reaction carries an ed25519 signature over BLAKE3(reactor || post_id || emoji || timestamp_ms), verified before storing.
• Comment signatures: verify_comment_signature() runs on every comment received via BlobHeaderDiff; forged comments are rejected. FoF-gated comments additionally pass the CDN-level pub_post_set gate (FoF).
• Reaction removal: only the original reactor or the post author can remove a reaction; the QUIC-authenticated sender is checked against both.
• Comment edit/delete: only the comment author can edit; comment author or post author can delete. Sender identity comes from QUIC transport authentication (iroh ed25519).
• Header author: rebuilt headers take the author from the stored post, never from the payload — relay nodes cannot misattribute.
• Source of truth: the reactions and comments tables are authoritative; blob_headers JSON is a derived snapshot rebuilt after each engagement op.

Encrypted receipt & comment slots Implemented

Private posts (Friends, Circle, Direct) carry encrypted slots in their BlobHeader for delivery receipts, read receipts, reactions, and private comments. The CDN propagates these as opaque bytes — only participants with the post's CEK can decrypt them. (FoFClosed posts skip this path; their wrap-slot mechanism covers both reads and comments.)

• Pre-filled noise: all slots are filled with random bytes at post creation; writing replaces noise with same-size ciphertext, so writes are indistinguishable from creation to observers.
• Slot key: slot_key = BLAKE3_derive_key("itsgoin/slot/v1", CEK) — only participants who can decrypt the post can read or write slots.
• Receipt slots (64 bytes each): one per participant, index = position in the NodeId-sorted participant list. Decrypted: [1B state][8B timestamp LE][23B emoji/padding]; states empty/delivered/seen/reacted. The author may pre-feed their own slot with a reaction at creation.
• Comment slots (256 bytes each): ceil(participants / 3) initial slots. Decrypted: [32B author][8B timestamp LE][216B UTF-8 + padding]. First-available selection; when exhausted, any participant appends new noise-filled slots via AddCommentSlots.
• CDN-safe: relay nodes store and forward slot bytes without decryption; slots travel inside BlobHeaderDiff, no dedicated messages.

DM conversations render these as delivery indicators: sent → delivered → seen checkmarks, emoji on react. Opening a conversation auto-marks incoming messages as seen.

Device roles & bandwidth budgets Implemented

Each node advertises its device role in InitialExchange, which sets hourly budgets for replication (pulling posts to cache) and delivery (serving requests from peers):

• Budgets auto-reset every hour; anchors reserve delivery headroom for browser-facing HTTP serving
• Role is self-declared from device type; peers respect advertised budgets when selecting replication targets (Content Propagation)

Connection rate limiting Implemented

Incoming QUIC connections that fail authentication are rate-limited per source IP to prevent CPU exhaustion from rogue or stale nodes:

• First 3 failures: logged normally, connection attempts proceed
• 4+ failures: silently dropped with exponential backoff (2^n-3 seconds, capped at ~256s)
• Successful connection: clears the failure count for that IP
• Cleanup: stale entries pruned after 5 minutes of inactivity

Knowledge freshness Implemented

Gossiped knowledge decays unless refreshed. Today's timers, which carry forward under the N1–N4 uniques model (Network Knowledge):

• TTL: N2/N3 entries expire after 5 hours (pruned during the rebalance cycle)
• Full state broadcast: every 4 hours, nodes re-broadcast complete state (not just diffs) to catch missed incrementals
• Disconnect cleanup: when a mesh peer disconnects, everything they reported is immediately removed (clear_peer_n2/clear_peer_n3)
• Startup sweep: on boot, all gossiped entries and mesh-peer rows are cleared — stale from the previous session, rebuilt as connections establish

Bootstrap isolation recovery Implemented

Prevents network segments from becoming permanently isolated from the main network:

• 24-hour check: starting 24 hours after boot, nodes verify the bootstrap anchor is within their knowledge reach
• If absent: reconnect to bootstrap, request referrals, connect to referred peers
• Sticky N1: the bootstrap joins a sticky N1 set for 24 hours, so mesh peers learn about it via routing diffs and can independently bridge back
• Self-limiting: once the bootstrap is within reach, the check passes silently; goes quiet as the network grows

Schema versioning Implemented

SQLite databases track their schema version via PRAGMA user_version. On startup:

• If the database version is older than MIN_MIGRATABLE_VERSION, the database is reset (preserving identity key)
• If older than the current version, data migrations run once and the version is bumped
• Schema-level changes are handled by init_tables() (CREATE TABLE IF NOT EXISTS) and migrate() (column-level ALTER TABLE checks)

IPv6 HTTP address advertisement Implemented

Nodes with public IPv6 addresses advertise their actual routable address (from endpoint.addr().ip_addrs()) paired with their bound port, rather than the bind address (0.0.0.0). This enables direct browser-to-node HTTP serving for share links. Unroutable addresses (0.0.0.0, 127.x) are filtered out in the tiered web-serving redirect path (HTTP Delivery).

18. Encryption

Envelope encryption (1-layer) Implemented

1. Generate random 32-byte CEK (Content Encryption Key)
2. Encrypt content: ChaCha20-Poly1305(plaintext, CEK, random_nonce)
3. Store as: base64(nonce[12] || ciphertext || tag[16])
4. For each recipient (including self):
   • X25519 DH: our_ed25519_private (as X25519) * their_ed25519_public (as montgomery)
   • Derive wrapping key: BLAKE3_derive_key("itsgoin/cek-wrap/v1", shared_secret)
   • Wrap CEK: ChaCha20-Poly1305(CEK, wrapping_key, random_nonce) → 60 bytes per recipient

Recipients are posting identities (personas), never network identities. The wrapping key derivation runs against the recipient's posting pubkey; the sender wraps with the authoring persona's posting secret.

Visibility variants

PostId integrity

PostId = BLAKE3(Post) covers the ciphertext, NOT the recipient list. Visibility is separate metadata. This means visibility can be updated (re-wrapped) without changing the PostId.

Group keys (circles) Implemented

• Each circle gets its own ed25519 keypair
• group_id = BLAKE3(initial_public_key) — permanent identifier
• Group seed wrapped per-member via X25519 DH (KDF domain: "itsgoin/group-key-wrap/v1")
• Epoch rotation: On member removal, generate new keypair, increment epoch, re-wrap for remaining members
• Distribution: the group seed travels as a normal encrypted post (VisibilityIntent::GroupKeyDistribute) authored by the admin's persona, with each member's posting ID as a recipient. Members receive it via the ordinary CDN / pull paths and unwrap with their posting secret. No dedicated wire push exists — there is no wire-level signal that one endpoint is coordinating group membership with another.

Three-tier access revocation

Three levels of revocation, chosen based on threat level:

Private profiles Implemented

Different profile versions per circle, encrypted with the circle/group key. A peer sees the profile version for the most-privileged circle they belong to. CircleProfileUpdate (0xB4) wire message. Public profiles can be hidden (public_visible=false strips display_name/bio).

19. Friend-of-Friend Visibility Implemented

The problem

Existing visibility variants gate by explicit recipient lists (Encrypted{recipients}) or named-circle membership (GroupEncrypted). Neither expresses "people who are reachable through my social graph" without leaking the graph itself. FoF visibility fills that gap: posts whose readership emerges from cryptographic reachability through a unilateral vouch graph, with no recipient IDs on the wire and no centrally-computed membership lists.

User-facing model

Authors pick one of four visibility levels at compose time:

Core primitives

• V_me: a 32-byte symmetric key owned by each persona. Distributed to everyone the persona vouches for. Anyone holding V_alice can decrypt wrap slots Alice sealed under it.
• Keyring: per-persona, holds the persona's own V_me plus every V_x received from vouchers. The union of these is what makes FoF reach emergent: an author wraps a post slot under every V_x they hold, and any reader whose keyring intersects with that set can decrypt.
• Wrap slot: an anonymous AEAD ciphertext in the post header, sealed under one V_x. Dual-derived: a 48-byte read part carries the post's CEK, a 48-byte sign part carries a per-slot signing seed. With the 2-byte prefilter tag, each slot is 98 bytes on the wire. No recipient ID visible.
• slot_binder_nonce: a random 32-byte value in the post header that all slot derivations are bound to. It plays the role "post_id in the KDF info" would — but PostId = BLAKE3(post) depends on the wrap slots themselves, so keying on the PostId would be circular.
• Prefilter tag: 2 bytes, HMAC(V_x, slot_binder_nonce)[:2], on each slot. Readers precompute tags for keys in their keyring and skip non-matching slots, cutting trial-decrypt cost ~65,000× per post.
• pub_post_set: list of all admitted signing pubkeys for a post's FoF set. Inline in the post header, randomly ordered. Allows CDN-level verification of comment signatures without revealing membership identities.

Distribution: vouches ride bio posts

Vouches are NOT delivered via DM. Instead, the voucher publishes anonymous sealed wrappers (one per recipient) inside their bio post. The sealing is an HPKE-style construction — per-batch ephemeral X25519 keypair, ECDH against the recipient's persona key, BLAKE3-derived wrapping key and nonce (domain itsgoin/vouch-grant/v1, bound to the bio post's ID), ChaCha20-Poly1305 seal. It is not RFC 9180 HPKE, but provides the same recipient anonymity property: wrappers carry no recipient identifier, the KDF context is recipient-free, and every wrapper in a batch shares one ephemeral pubkey. Each wrapper is 48 bytes (32-byte sealed V_me + 16-byte AEAD tag).

Readers auto-scan bio posts of accounts they follow, trial-decrypting each wrapper against each of their personas. Cost is ~60µs per wrapper per persona on mobile — a 200-wrapper bio scanned against 3 personas is ~36 ms. The bio's VouchGrantBatch is padded with dummy wrappers and shuffled on every publish so observers see neither vouch-set size nor change-targets.

Two modes

CDN-level comment verification

Each wrap slot is dual-derived: one half yields the shared CEK (read capability), the other yields a per-V_x Ed25519 signing keypair (priv_x sealed inside the slot; the corresponding pub_x published in the post's pub_post_set). Comments declare which pub_x signed them and carry the signature.

Propagation nodes verify three things before forwarding a comment:

1. pub_x_index points to a valid entry in pub_post_set.
2. That entry is not in the post's revocation_list.
3. The comment's group_sig validates against that pub_x.

Any failure → drop, do not forward. This kills the bandwidth-amplification attack that a single admitted-but-malicious FoF member could otherwise mount: their forgeries cannot pass the propagation gate.

Privacy properties

• Unilateral: vouching is a one-way act, no handshake. The FoF graph forms without bilateral negotiation.
• Graph-private: wrap slots carry no recipient IDs. Observers cannot enumerate who can read a post.
• Bucketed padding: slot count and body size are deterministically padded to fixed buckets (power-of-2 up to 256, then +128 steps for slots; same shape up to 256 KB then +256 KB steps for bodies). Observers learn the bucket, not the position within it.
• Recipient anonymity on vouch distribution: the sealed wrappers' key privacy ensures bio-post wrappers do not reveal recipients.
• Per-post chain pseudonym (accepted tradeoff): the pub_x_index in a comment lets observers correlate "these N comments came through the same chain" within a single post. Cross-post correlation is broken because keys regenerate per post.

Revocation & key lifecycle

Three complementary mechanisms:

Performance budget

At realistic scale (~500 vouchees, ~500 wrap slots per post), reader-side decryption uses an unlock cache: the first time persona P decrypts a post from author A via key V_x, the (P, V_x) tuple is cached. Subsequent posts from A try that key first — one HMAC + one AEAD attempt in the hot path. Full scan only on cache miss; newly-received V_x triggers a retry sweep over the unreadable-posts table.

Post-quantum readiness

Body encryption, wrap slots, and HKDF/HMAC are all symmetric — PQ-safe. Comment signing uses Ed25519 today; the spec shape is algorithm-agnostic so ML-DSA-65 (~2 KB pubkey, ~3.3 KB signature) can substitute, optionally with a Merkle-commit variant on pub_post_set to keep header size bounded.

Implementation

Full crypto-level byte layouts, data models, wire-format additions, ship criteria, and integration tests are specified in docs/fof-spec/. All five layers shipped in v0.7.0:

20. Delete Propagation & Comment Expiry

Deletes are signed control posts Implemented

A delete is a control post: a small public post with VisibilityIntent::Control, signed by the target's authoring persona, naming the PostId to delete. It propagates exactly like any other post — it enters the author's neighbor manifests (following_posts lists on their other posts) and rides manifest diffs out to file_holders; anyone following any of the author's posts picks it up via the normal CDN / pull paths.

On receipt, a node verifies the control post's signature against the target post's author before applying. Application is atomic with the control-post insert: record in deleted_posts (INSERT OR IGNORE), then DELETE the target from posts. The deleted_posts table also guards against re-ingesting the deleted post from a stale holder later.

Blob cleanup on delete Implemented

1. Locally: blob metadata and CDN records for the post's blobs are removed, blob files deleted from disk.
2. Remotely: no notice is sent. Copies held by other file_holders become orphans — nothing references them, nothing re-shares them — and are evicted naturally by the CDN's LRU eviction cycle (see Content Propagation).

Comment expiry: rand(30–365 days) TTL Planned

Every comment gets an expiry timestamp at creation: created_at + rand(30–365 days). The expiry is fixed at creation, signed, and carried with the comment — it is part of the comment's identity, not a per-holder policy. Every holder in the network expires the comment at (near) the same moment.

• Why carried, not local: if each holder chose its own retention, staggered disappearance would fingerprint individual holders and their policies. A carried timestamp makes expiry a network-wide event that reveals nothing about who holds what.
• Why random: a fixed TTL would let observers date a comment's creation from its expiry. A 30–365-day uniform draw breaks that inference.
• Identity hygiene: throwaway persona IDs used for greeting comments (Discovery & First Contact) exist in the network only through their comments. When the comments expire, the IDs vanish from uniques lists entirely — the network forgets them by construction.
• No silent extension: the TTL cannot be edited — re-posting the content is a new comment with a new ID and a fresh draw.

21. Social Graph Privacy & Traffic Shaping

What is never shared

• Follows are never shared in gossip or profiles. Implemented
• Uniques announcements carry bare IDs — except anchors. The uniques announce (see Network Knowledge) ships NodeIds without addresses; the sole exception is anchor-flagged entries, whose addresses ride the pools by design (self-declared reachable infrastructure — publishing them links nothing to any person). Node-class and author-class IDs travel in separate packed arrays, and the anchor array is the only address-bearing field, so the exception is structural rather than conventional. Implemented
• N4 is never re-announced — knowledge terminates at the fourth bounce, so an observer M hops away cannot enumerate your neighborhood through transitive gossip. The announce builder simply never reads bounce-4 rows, and third-party anchor reports are never promoted into our own bounce-1 slice — that promotion would have reset the horizon of every address-bearing entry on every hop, forever. Implemented
• Posting identities never map to device addresses on the wire. Addresses attach to network identities only; the persona split (see Identity Architecture) keeps the two namespaces unlinkable. Implemented — AuthorManifest.author_addresses is gone (Iteration A). The same invariant is enforced a second time in the uniques announce (Iteration C): the wire separates node-class from author-class IDs into distinct arrays so an address can never attach to a persona, and our own personas — every one of them, plus the author of any comment we wrote locally, which covers per-greeting throwaway IDs — are excluded from the uniques we announce, because our node ID and anchor address ride the same payload. Our personas stay discoverable through other holders of our content; we must simply never be the reporter. See Network Knowledge.

Where addresses do travel, and why

Routing needs somewhere to connect. Addresses appear in exactly these payload classes, all scoped to network identities:

• Social-routing peer addresses: the initial exchange includes addresses of our currently connected mesh peers. These are network endpoints an observer at that vantage could already see us talking to — sharing them reveals mesh topology (public by design), not social links.
• Point lookups: worm address-requests and lookup responses return addresses for a specific queried network ID.
• Connection convection referrals: anchors hand out addresses of recent callers, and RelayIntroduce coordination carries both ends' addresses for hole-punching (see Anchors).

Uniques lists as cover traffic

The N1 uniques list deliberately merges mesh peers, social contacts, CDN file authors, CDN file peers, and throwaway/anonymous IDs into one flat set. An observer diffing your announcements over time is looking at a list dominated by high-churn CDN-derived entries and deliberate throwaway-ID noise; the stable social core does not stand out the way it did when the share list was just mesh-plus-contacts. Throwaway IDs additionally age out of the network via comment TTL (above), so the noise floor is self-renewing rather than monotonically accumulating. Our own personas and our own greeting throwaways are the deliberate exception — they are excluded, because we would be the reporter. Implemented

The timing adversary Planned

With content encrypted and recipient lists off the wire, the remaining deanonymizer is request-timing correlation: an observer who can watch traffic sees who fetches what, when. If your device checks an author's CDN seconds after every new post, you are that author's reader; if fresh content always radiates outward from one node first, that node is the author. The v0.8 defenses are behavioral, not cryptographic:

• Jittered, tiered update cadence: CDN update checks run on a descending-frequency schedule (minutes → days) keyed on freshness × relationship tier, with jitter on every timer (see Update Cadence). No check fires because a post appeared; checks fire because a schedule slot came up.
• Replication shaped as overhead: replication pushes are paced and jittered so an author seeding their own content is indistinguishable from a holder performing routine redundancy maintenance. The goal: update + replication traffic reads as uniform network overhead, with no observable "origin burst".
• 2–5 visible posts per author: the public CDN surface reveals at most 2–5 posts per author at any time; the surplus is pushed out to holders via replication requests and reached through the uniques index. This caps what enumeration of any single node's public holdings discloses about any author's corpus — and hides the author's own node behind ordinary public mesh IDs.
• Comment TTL: long-lived comment trails are the easiest correlation anchors across time; the 30–365-day expiry bounds how long any trail exists.

22. Identity Management

Multi-identity per device Implemented

A single device can hold multiple identities, each with its own ed25519 keypair, database, blob store, follows, and posts. One identity is active at a time — switching performs a hot-swap (Node teardown + rebuild, ~3-5 seconds).

• Directory structure: itsgoin-data/identities/{node_id_hex}/ — each identity gets its own subdirectory with identity.key, itsgoin.db, blobs/, and meta.json
• Create, import, switch, delete via Settings UI
• Key permissions: identity.key files written with 0600 permissions (Unix)

Multi-device: posting-key bundles Implemented

Devices are linked by sharing posting keys, never network keys. Each device keeps its own network key (its own QUIC NodeId); what travels between your devices is the export bundle — a ZIP containing the identity key, all posting identities, posts, blobs, follows, and settings. Transfer happens out-of-band between your own devices; the network sees no linking message.

• Export: Settings → Export produces the ZIP bundle. All posting keys held by the identity are included (posting_identities.json), so every persona restores on the target device.
• Import as personas (the multi-device path): the bundle’s posting keys are added to the current identity’s persona set and its posts are inserted as-authored — original PostIds, authors, and signatures intact. Content encrypted to any imported key becomes decryptable because the device now holds those secrets. Idempotent; duplicates are skipped.
• Import as new identity: alternatively, the bundle can be imported as a separate identity on the device (creates the identity subdirectory from the bundle’s key; data restores on first switch).
• QR / file-share linking flows for pairing a new device without manual file transfer Planned

Post import & merge Implemented

Two ways to bring another identity’s posts into the current one, both wired into the import wizard:

• Import public posts: public posts from the bundle are re-created under the current identity with new PostIds.
• Merge with key: supply the original identity’s key; encrypted posts are decrypted with it, then re-created under the current identity. Posts the original identity could not read are skipped. Original timestamps are preserved and the prior author is recorded in the BlobHeader for provenance.

23. Reciprocity (Reconsidered) Planned

The original Phase 2 design centered on hosting quotas (3x rule), chunk audits, and tit-for-tat QoS. On reflection, the attention-driven delivery model makes quota enforcement unnecessary. The CDN is a delivery amplifier, not a storage system — hot content propagates through demand, cold content decays. Authors are responsible for their own content durability.

Tit-for-tat QoS solves the wrong problem: it optimizes for fairness in a storage-obligation model that no longer exists. What matters is that the delivery network functions efficiently, which it does through natural attention dynamics.

If reciprocity mechanisms are needed at scale, they should address delivery quality (bandwidth, latency, uptime) rather than storage quotas. This remains an open design area.

24. Identity Architecture

ItsGoin separates network identity (per-device routing/connection key) from posting identity (the face/persona authoring content). This is the architectural foundation for multi-device, multi-persona, and DM-level traffic-graph privacy — and it fully survives into v0.8: the uniques index treats posting IDs (including throwaway ones) as first-class searchable entries, and the registry + greeting-comment first-contact design (Discovery & First Contact) builds directly on the split.

Two layers of identity Implemented

Each device has ONE network key — used for QUIC connections, endpoint ID, mesh routing. It’s never linked on the wire to any posting key.

Each user can hold MANY posting keys simultaneously — no “active” persona, no switching. Each posting key is a persona (Public, Private, Work, Family, etc). Posts are signed with the posting key chosen at compose time. The two key layers are always distinct: fresh installs generate an independent default posting identity, and the v0.6.1 migration rotates the network key of any install whose default posting key still equaled it. No node’s network key ever doubles as a posting key.

Privacy invariant: peers cannot determine which network IDs belong to a given posting ID, which posting IDs belong to the same network ID, or which posting IDs belong to the same user. These associations are private to the device owner.

Persona types Implemented

• Public posting IDs — main persona(s), openly associated with “you”
• Private posting IDs — smaller-context personas for close contacts or specific groups
• Contextual posting IDs — per-relationship or per-group; user creates one per context and sticks with it
• Throwaway posting IDs — single-purpose IDs (e.g., the outer signer of a greeting comment). Deliberately kept in uniques lists as network noise; retired naturally by comment TTL expiry (see Deletes & Expiry)

Required fixes: network-ID/posting-ID confusion Rework

The key split left four code paths comparing the device’s network NodeId where posting IDs now live. Since the two are always distinct, each path silently fails. All four are required v0.8 fixes (first item on the roadmap):

• Visibility revocation: the author check compares post.author (posting ID) against the network ID, so every revoke bails with “not the author”; the rewrap path also pairs the default posting secret with the network ID.
• Group key granting: the GroupKeyRequest handler checks the requester’s network ID against a posting-ID member list and wraps with the network key — it can never grant. (No send side exists; the message pair is retired in the v0.8 protocol.)
• Replication cycle: under-replicated own posts are queried by network ID, so the set is always empty and the cycle is inert.
• Blob-eviction relationship tier: eviction scoring compares candidate.author (a posting ID) against the network ID, so the 5.0 own-content tier never matches. Masked in practice because own blobs are auto-pinned (pin boost 1000), but the tier is inert.

The fix class is uniform: every self.node_id comparison or query against post/persona authors must use posting identities (all of them, not just the default). A full sweep for further instances is part of the fix.

Multi-device is a special case Implemented

“Two devices holding the same posting key” is a trivial case of the multi-key model. Link happens out-of-band between the user’s own devices via the export/import bundle (Identity Management) — the export includes all posting identities so they restore on the second device, which keeps its own network key. The network sees no cross-device message announcing the relationship; each device pulls content for its posting IDs via the normal CDN. The fact that two network nodes hold the same posting key is only discoverable if an observer has private knowledge (which they shouldn’t).

In-app QR / file-share flows for easy linking between an existing device and a new one are not wired yet — today it’s manual export-then-import.

Ephemeral rotating IDs for DM threads Planned

The intent: DM threads and group messages use per-thread unique posting IDs that rotate per message. Each encrypted message would include a handshake field — the next posting ID to use. Observer sees a stream of distinct posting IDs with no cryptographic tie between them, defeating thread-level traffic correlation. Desync recovery via a sliding window of the last N accepted IDs. Message history kept in a local encrypted-to-self archive that replicates across linked devices via self-follow.

v0.8 removes most of the old blockers. The uniques index deliberately carries throwaway/anonymous posting IDs (they double as network noise), so an ephemeral author is findable through the same distributed search as any other ID; comment TTL expiry retires spent IDs without leaving a permanent trail; and the greeting-comment machinery provides the cold-contact channel. What still needs a crisp design is freshness: how a just-generated posting ID becomes reachable fast enough to receive a reply before the next rotation.

CDN: per-file holder sets Implemented

Each file (post, blob, manifest) has its own flat holder set — up to 5 most-recent peers, LRU-capped. Once a file already has 5 holders, further requesters are redirected to existing holders instead of being registered. Eviction scoring is relationship-tiered (own content > followed > other). There is no tree rooted at the author and no upstream/downstream structure anywhere.

When a new post is created, the creator’s updated AuthorManifests (whose neighborhoods now reference the new post) are pushed to each prior post’s holder set via ManifestPush; recipients see the reference and fetch the new post via PostFetch. Notifications thus route via network-ID peers who happen to hold related files — content always arrives via pull, never pushed directly. Full mechanics in Files & Storage and Sync Protocol.

DM privacy model Implemented

Three mechanisms eliminate the “A messaged B” traffic signal:

1. CDN-only propagation. There is no direct push for encrypted posts. All encrypted posts propagate via the file-holder CDN, indistinguishable on the wire from any other encrypted content.
2. Merged pull + recipient-match. Content queries are a uniform list of IDs; a serving peer returns posts matching author ∈ query_list OR wrapped_key.recipient ∈ query_list. The client always includes every one of its own posting identities alongside follows, so there is no distinguishable “searching for DMs” traffic fingerprint. This matching machinery survives the v0.8 pull redefinition — it runs at the CDN content-fetch step (see Sync Protocol).
3. Greeting comments for cold contact Planned. First contact from outside the graph arrives as an HPKE-sealed comment on a bio post, signed by a throwaway outer ID — see Discovery & First Contact.

What the user sees

• One merged incoming feed (all content to all personas), with filter-by-persona pills Implemented
• Per-post “(you) as <persona>” label on own posts authored by a non-default persona Implemented
• Persona picker at post-creation time, auto-hidden with a single persona Implemented
• Settings → Personas to create, delete, and set default Implemented
• Reply/comment default persona = whichever key decrypted the post Planned
• Contextual compose defaults (e.g., posting to a circle auto-picks that circle’s last-used persona) Planned
• DMs to different personas as distinct inbox threads Planned

Key/collision safety

Posting keys and network keys are ed25519 seeds (256 bits of entropy). Birthday paradox reaches 50% collision at ~2¹²⁸ keys generated — not a concern even at aggressive rotation rates across a global userbase. The operational risk is weak RNG during key generation; we rely on the platform CSPRNG everywhere.

Status

The persona split is fully implemented: key-layer plumbing, multi-persona storage and UX, CDN-only encrypted propagation, and merged-pull recipient matching are all live. Ephemeral rotating DM IDs remain planned. The network-ID/posting-ID bug family above is the one required rework before v0.8 features (registry, concealment budget) can sit on this foundation.

25. HTTP Post Delivery Implemented

Intent

Every ItsGoin node that is publicly reachable can serve its cached public posts directly to browsers over HTTP — no extra infrastructure, no additional dependencies, no new binary. The same port number used for QUIC (UDP) carries a TCP listener for a minimal raw HTTP/1.1 handler baked into the binary. This makes every publicly-reachable node a browser-accessible content endpoint, enabling share links that deliver content peer-to-browser without routing post bytes through itsgoin.net.

Dual listener architecture

<port>/UDP  →  QUIC (app protocol)
<port>/TCP  →  HTTP/1.1 (read-only, two routes)

Both listeners bind the same port number. The OS routes UDP and TCP to separate sockets — no conflict, no protocol ambiguity. The handler is raw tokio::net::TcpListener, no HTTP crate, zero new dependencies.

Routes

• Both hex arguments must be exactly 64 lowercase hex characters (BLAKE3 hash). Anything else — any other path, method, or malformed request — is a hard close with no response. Do not be helpful to malformed requests.
• Posts must be PostVisibility::Public. Blobs are served only if they are an attachment of a public post. Encrypted content is never served over HTTP regardless of what the node holds.
• Connections are keep-alive: one connection serves sequential requests (the post page, then its attachments) inside its slot.

Connection budget

The server runs a two-tier slot budget instead of a flat connection cap:

A new connection tries to acquire a content slot first; if those are full it gets a redirect slot, where post requests are answered with a 302 to another holder (below) and blob requests are hard-closed. Over-budget connections are closed immediately — no queue, no wait.

Security constraints

Which nodes serve HTTP

A node starts the HTTP listener only if it is publicly TCP-reachable, meaning any of:

• Active TCP port mapping via UPnP-IGD / NAT-PMP / PCP (see Port Mapping). Since v0.7.2 this includes mobile: phones on WiFi/Ethernet behind a permissive NAT serve HTTP too.
• Public IPv6 address — serves directly (desktop, anchor, or mobile).
• Explicit public bind (servers started with --bind).

Nodes behind a NAT that refuses all three mapping protocols cannot serve HTTP but can still appear as holders for app-protocol delivery; the share-link tiers (see Share Links) route around them. A serving node advertises its HTTP capability and address to peers so they can be selected as redirect targets. This is the same direct-reachability signal that drives anchor candidacy (see Anchors & Connection Convection) — in practice the HTTP-serving population and the anchor-candidate population are the same nodes.

302 load shedding via file holders

A redirect-slot request is answered from the flat holder model:

1. Verify the post exists locally and is public (else hard close).
2. Query file_holders for the post (flat set, cap 5 — see Content Propagation).
3. Filter each holder's known addresses to publicly-routable ones.
4. TCP-probe candidates with a 200 ms timeout; 302 → http://<addr>:<port>/p/<postid> to the first live one.
5. All dead → hard close.

The receiving node applies the same logic recursively if its own content slots are full. Load spreads across whichever holders are publicly reachable, mirroring the attention-driven holder model at the HTTP layer.

26. Share Links Implemented

Intent

Every public post can be shared as a URL that works for both app users and browser users:

• App installed: OS intercepts the URL via Universal Links (iOS) / App Links (Android) before the browser loads. App opens directly to the post, fetched via QUIC. Zero browser involvement. (Planned — see below.)
• No app: Browser loads itsgoin.net, which finds the post on the network and delivers it through the tiered strategy below. The share link becomes a product demo and install opportunity.

URL format Implemented

https://itsgoin.net/p/<postid_hex>

• postid_hex: 64 hex characters (BLAKE3 post hash). That is the whole payload — no author ID, no host hints, no binary encoding. The anchor resolves holders itself.
• Older /p/<postid>/<author> URLs (pre-v0.7.2) still parse; the trailing author hex is used as an extra holder hint for the search rather than encoded into new links.
• Only public posts generate share links.

Tiered web serving Implemented

When a browser visits a share link, the itsgoin.net web handler attempts three tiers:

1. 302 redirect: holders advertising HTTP capability with a known public address (and still connected or in session) — redirect the browser straight to that node's HTTP endpoint. Zero post bytes flow through itsgoin.net.
2. TCP punch: holders behind endpoint-independent (EIM) NAT that are connected but not publicly reachable — the anchor sends TcpPunchRequest (0xD6) asking the holder to punch TCP toward the browser's IP; on success TcpPunchResult (0xD7) returns the HTTP address for a redirect.
3. QUIC proxy: serve from local storage if the post is already held; otherwise a worm point-query (see Worm Search) finds a holder and PostFetchRequest/Response (0xD4/0xD5) pulls the post (15 s budget), which is rendered as HTML and served directly. Posts fetched this way are cached, not permanently hosted — the proxy is a convenience service, not a data store.

If all three tiers fail, the browser gets the unavailable page below.

itsgoin.net node

itsgoin.net runs a permanent, well-connected ItsGoin node with the web handler enabled. It is an anchor in the v0.8 sense — a directly-reachable, opted-in node serving connection convection to joining peers (see Anchors & Connection Convection) — and its mesh position plus uniques knowledge is what makes share-link holder resolution likely to succeed even for content it has never synced. Scalable via additional instances (1.itsgoin.net, 2.itsgoin.net, …), each with its own mesh connections increasing total search coverage.

Unavailable page

⬡ This content isn't currently reachable.

  It may be available again when someone
  who has it comes back online.

  [ Install ItsGoin to find it when it resurfaces ]

This is not a 404. It communicates the honest model: content lives on devices, not servers. Cold content decays. The install CTA is the honest answer to “how do I get this.”

Universal Links / App Links Planned

Same URL — itsgoin.net/p/... — intercepts to the native app for users who have ItsGoin installed. No separate URL scheme, no app:// links. Requires two static JSON files on itsgoin.net:

/.well-known/apple-app-site-association     (iOS Universal Links)
/.well-known/assetlinks.json                (Android App Links)

App-side: register the URL pattern in Tauri config; on receipt, parse the postid and fetch via QUIC (render immediately if already in local SQLite). Universal Links intercept before the browser loads, so itsgoin.net sees zero traffic for app users. Until this ships, share links always traverse itsgoin.net's tiered serving even on app-installed devices.

iOS caveat: Universal Links require the app to have been opened manually once before interception activates. A first-time tap goes to the browser fallback — which is the full product-demo page, the right outcome for a first-time user anyway.

QR codes

Share links are valid QR payloads as-is: the full URL is under 90 characters, comfortably scannable at low error correction. A phone camera sees an itsgoin.net URL and offers to open it in the app (once link interception ships) or the browser. No custom QR scheme.

Chrome HTTPS (October 2026)

Chrome 154 enables “Always Use Secure Connections” by default, warning before HTTP sites. This does not affect the architecture: itsgoin.net is HTTPS (Universal Links work normally); the 302 redirect is a header only, taking the browser off the HTTPS page before any content loads; and node HTTP endpoints are raw IP:port addresses, which Chrome exempts from the public-site warning requirement. No changes needed before or after the rollout.

27. Discovery & First Contact Planned

The problem

The mesh-CDN architecture deliberately has no global feed and no keyword flood-search (see Worm Search for why flooding is rejected). That leaves two gaps: discovery — how do you find a person you don't already have a graph path to? — and first contact — how does a stranger send you an initial message when every messaging rail (DMs, FoF comments) requires an existing key relationship? This section is the designed answer: an opt-in registry for discovery, and greeting comments for first contact. Both compose with machinery that already exists (bio posts, CDN comment verification, HPKE-sealed wrappers, RevocationEntry, comment TTL).

The registry: opt-in discoverable bio posts

Registration is a flag on a public bio post: “this persona wants to be findable.” A discoverable bio post links a public persona (display name, bio text, avatar) to a public author ID (a posting identity) — and nothing else. There is no directory server; the registry is the set of discoverable-flagged bio posts, replicated as ordinary CDN content.

• Location-anonymous by construction: a registry entry maps name → author ID only. Resolving the author ID to actual content goes through normal CDN holder search — never through an address in the entry. This depends on the AuthorManifest privacy fix (manifests must not carry device addresses — see Files & Storage); the fix must land before or with the registry.
• Replication set: flagging a bio discoverable is explicit consent to wide replication. Discoverable bios form their own replication set that opted-in holders spread beyond the 2–5-post concealment budget that applies to ordinary content — registration trades concealment for reach, deliberately and per-persona.
• Search: a searching node fetches the registry post's comment chain (below) via an ordinary pull, then queries locally. No flood queries; search cost lands on the searcher, not the network.
• Consent gradient: registered personas are searchable by anyone. Unregistered personas are reachable only through the graph — someone must encounter their author ID via the uniques index (see Network Knowledge), a comment thread, or a vouch. Nothing about an unregistered persona is indexed.

The v0.6.2 Discover tab — a local list of named, public-visible profiles already held in storage — is the UI seed for this: the registry generalizes it from “profiles I happen to hold” to a replicated, searchable set.

The registry post: rendezvous & enumeration Planned — tester-critical

Discoverable bios alone leave a gap: how does a searcher enumerate them? The answer is a well-known “registrations here” post whose comment chain is the registry index. A registration is a signed public comment on that post — structurally the same open-slot comment as a greeting (see below), aimed at a well-known target instead of a stranger's bio. One implementation serves both features.

• The post: published at network genesis by the default anchor's persona; its ID is derived from a well-known seed the app ships with (shard(seed, k) — shard count starts at 1, and the derivation scheme exists from day one so splitting by hash(persona_id) later is a threshold change, not a migration). It replicates as ordinary CDN content; anchors hold it by durability, not appointment.
• The entry: a registration comment carries {display name, search keywords, persona ID / public author ID} signed by the registering persona's posting key — self-certifying: any holder can verify the entry against the key it names, no authority consulted.
• Self-cleaning: registration comments carry a fixed 30-day TTL (unlike ordinary comments' randomized TTL — that randomness serves anonymity, which a deliberately-public registration doesn't want). Staying listed means re-signing a fresh entry; holders keep one active entry per persona ID (newest wins). The chain self-cleans and is never more than 30 days stale.
• Delete / modify: a delete request signed by the same persona key is honored by every holder (verifiable from the entry itself — the network agreement is checkable, not honor-system). Modify = delete + re-register; no separate primitive needed.
• Moderation hook: the registry post's author retains the standard per-post RevocationEntry power — manual spam removal for the alpha era, at the acknowledged cost that the author could censor entries. Acceptable while the author is the project's own anchor; the trust layer (see Directory Trust Layer) is the eventual replacement.
• Flood limits: registrations fit a single small size bucket and are rate-capped per holder. Proof-of-work was considered and rejected: its cost lands inverted (a phone registrant pays seconds of battery; a botnet rig pays effectively nothing), so it taxes the users we want while barely inconveniencing the adversary we fear. The registry's real defenses are the bounded blast radius and vouch gating below.

Greeting comments: sealed first contact

First contact rides the comment rails. A bio post that opts into contact includes a greeting slot in its pub_post_set (see Friend-of-Friend Visibility) whose signing keypair is published — derivable by anyone from material in the bio post header. A stranger's greeting comment signed with the greeting key passes the CDN-level comment-verification gate that otherwise drops non-member comments, so it propagates like any FoF comment.

• Sealed content: the greeting body is HPKE-sealed to the bio author's posting key. Inside: the sender's real persona ID and a return path. Outside: an opaque ciphertext authored by a throwaway outer ID. Observers learn that the bio received a greeting, not from whom.
• Blends in: FoF Mode 2 already makes encrypted comment blobs commonplace on public posts. Greetings are one more ciphertext among many — if everyone's anonymous, anonymity doesn't stand out.
• Off-switch: the author revokes the greeting pub_x via the existing per-post RevocationEntry sweep — propagation nodes delete stored greetings and stop accepting new ones. No new revocation machinery.
• Retirement: comments expire at a random TTL fixed at creation (see Delete Propagation & Comment Expiry), so throwaway greeting IDs eventually vanish from the network — and from everyone's uniques lists — entirely.

Spam controls

The composed flow

28. Directory Trust Layer (Future) Planned

Scope

• Whitelist track — vouch-weighted discoverability and graph-scoped visibility over registry entries.
• Blacklist track — community-flagged accounts and content; voluntary node-level replication refusal.
• Out of scope — node access, message delivery, post sync, existing follows, and bare registry presence. All continue to work without trust-layer standing.

Because trust-layer loss is a low-cost outcome for real humans and a high-cost outcome for bad actors, enforcement thresholds can be deliberately aggressive without meaningful false-positive risk.

Vouch capacity

A member's outbound vouch capacity is derived from received vouches:

• Base rate: 1 outbound vouch per 30 days per received vouch, up to a hard cap of 5 outbound vouches per 30 days.
• A registered persona with zero received vouches has zero outbound capacity — presence in the registry grants findability, never vouch power.
• Capacity regenerates; unused capacity does not accumulate beyond the monthly window.

Trust signals are internal, not purchasable. Aged off-platform accounts (FB, X, etc.) can be bought cheaply; in-system tenure crossed with graph density cannot. Vouch weight derives from the voucher's in-system graph depth and their history of non-revoked vouches — not account age.

Cascade punishment

A "bad vouch" is a vouch later determined to have been extended to a bot, impersonator, content thief, or other removable actor. Punishment is asymmetric — mild for humans who miscalled a single vouch, devastating for botnets whose strength is their dense internal vouch graph.

"NEW" is strictly defined: a voucher who has never previously vouched this member and is not within the first-degree graph of any prior voucher for this member. This blocks ring members from cycling each other through as "recovery" vouchers.

Cascade radius. Invalidation of received vouches propagates the effective penalty upward: the bad actor's vouchers lose the credibility granted by that downstream relationship. One verified human assertion against a single botnet node can cascade through the entire dense cluster because bots' own topology carries the invalidation. They build the weapon that points back at them.

Graph-relative visibility

Trust-layer discovery is not global. A viewer sees vouched entries N hops from their own social graph (N tunable; start with N=3). Bots at the fringe of the graph are structurally invisible to most humans. Visibility is further rate-limited (Y new profiles per viewer per day, Y tunable) to make harvesting economically unattractive without affecting normal discovery.

This scoping is also why the vouch system's bot-ring problem is bounded: even a successful ring has no harvest value if it cannot be seen by real users.

Verification (circuit breaker)

Verification is an emergency override, not a standing credential. In normal operation, the vouch system runs unassisted. When a creator notices their content suppressed or a bot cluster drowning legitimate signals, they invoke verification on their own terms.

• Trigger: creator-initiated only. No automatic verification prompts.
• Method: human interaction + fresh content submission (specifics TBD; must resist CAPTCHA-farmed and LLM-automated completion).
• Effect: verified status outweighs normal vouches for the duration it applies. A verified creator's reports of content theft or impersonation trigger cascade invalidation across the offender's vouch graph.
• Cost asymmetry: a botnet must sustain attacks indefinitely; the defender verifies once.

Reporting

The reporting pipeline is lightweight, member-facing, and feeds a single review queue with multiple severity tracks:

• Impersonation — a member reports an account copying their (or someone they know's) identity. High-confidence signal: verifiable via profile comparison and content signatures.
• Bad vouch — a member flags an entry they vouched for, or vouches in their extended graph. Triggers cascade punishment on confirmation.
• Content theft — a creator reports unauthorized reposting. Evidence is the signed original versus the repost.
• Automated topology detection — graph analysis flags ring structures, abnormal clustering coefficients, and low-bridging clusters. Feeds the same queue as human reports.

Reports from verified accounts carry higher weight. A confirmed report against one member in a tight cluster opens review on the whole cluster.

Blacklist

Blacklist is a higher-severity tier than trust-layer suspension. Two states:

• Under review — enough independent reports to warrant scrutiny; member still discoverable but flagged.
• Confirmed blacklisted — entry persists at the identity level. A bad actor creating a new identity starts from zero; the old identity's blacklist entry remains as a reputational cost that outlasts the account.

Escalation paths:

• Confirmed impersonation → direct blacklist.
• Vouch violations → trust-layer suspension first, blacklist only on repeated/escalated offenses.
• Content theft → voluntary replication refusal (below); blacklist for repeat offenders.

The blacklist must be slower and more evidence-bound than suspension. Suspension costs a bot everything but costs a human almost nothing; blacklist has real network consequences (below) and must not be a censorship weapon.

Voluntary network compliance

Nodes may configure policies to decline replication or delivery of blacklisted content and accounts. This is opt-in, not forced. The effect is architectural starvation: stolen or abusive content cannot sustain replication when hosts collectively decline to be its infrastructure, while the legitimately signed original continues propagating normally.

This is the key lever for creator protection. ItsGoin does not enforce copyright; it gives creators a network that structurally prefers their signed original over any derivative copy. Combined with embedded ads (below), there is no version of content theft that economically benefits the thief inside ItsGoin.

Creator-embedded ads

The platform does not insert or intermediate ads. Creators may embed ads directly in their content or feed, as part of the signed post.

• Ads inside signed content cannot be stripped without breaking the ed25519 signature — tampering is detectable.
• A repost that strips ads produces an unsigned-or-differently-signed copy, which compliance rules treat as non-compliant.
• A repost that preserves ads intact monetizes the original creator automatically.
• Ad revenue therefore follows the legitimate copy by construction, not by enforcement.

Repost framework

A two-track fair-use model. Compliant reposts are unblocked; non-compliant reposts feed the content-theft reporting pipeline.

Edge cases (what counts as "amplification" vs. "wholesale copy masquerading as amplification") route to human reviewer capacity. The signed original is cryptographic evidence against the repost in any contested case — reviewers do not need to take anyone's word for what the original contained.

Philosophical position

Most platforms have a structural conflict of interest with creators: fakes inflate engagement metrics, thieves generate content volume, both drive ad revenue. ItsGoin's incentives are inverted by design. Fakes degrade the vouch system; thieves attack the network's most valuable users; bots pollute the replication layer the network depends on. Every bad actor makes ItsGoin worse as software, not just ethically. The enforcement mechanisms above are therefore load-bearing, not policy theater.

Implementation status

Designed, not implemented — and deliberately beyond the v0.8 scope. Requires:

• Trust-layer storage schema (vouch records, blacklist records, report queue, graph-density caches)
• New protocol messages (vouch, revoke, report, verify challenge/response)
• Graph-topology analysis job (automated ring/cluster detection)
• Client UX for vouching, reporting, verification
• Node-side replication policy config (blacklist honoring)
• Review-queue tooling for contested cases

Recommended staging: minimum viable slice = registry (see Discovery & First Contact) + single-vouch trust entries + impersonation reports → manual review queue. Defer cascade math, automated topology detection, verification override, and repost compliance until real graph data exists to calibrate thresholds.

Tunable parameters

Appendix A: Timeout & Interval Reference

Every constant below exists in code today (cited per row in source comments) or comes from a v0.8 ruling (marked Planned). Constants tied to retired subsystems (preferred peers, register loop, keep-alive pool) are gone; the two registration-model referral constants remain, badged Rework, until the convection window replaces them.

Appendix B: Design Constraints

Appendix C: Implementation Scorecard

Code status as of v0.7.3, measured against the v0.8 target. Implemented = code matches the target today. Rework = built, but differently; migration required. Planned = not built.

Appendix D: Roadmap — v0.8 Critical Path

The path from today's code to the v0.8 target, in order. Items 1–2 clear the ground; 3–7 are the architecture shift; 8–10 build on it.

Appendix E: File Map

As of v0.7.3 code. Use this as a navigation map, not an exhaustive line count.

crates/core/
  src/
    lib.rs                     — module registration, parse_connect_string, parse_node_id_hex,
                                 DEFAULT_ANCHOR_POSTING_ID
    types.rs                   — Post, PostId, NodeId, PublicProfile, PostVisibility (incl. FoFClosed),
                                 WrappedKey, VisibilityIntent, Circle, DeviceProfile slot tables,
                                 AuthorManifest/CdnManifest, BlobHeader + diff ops, DeviceRole budgets
    content.rs                 — compute_post_id (BLAKE3), verify_post_id
    crypto.rs                  — X25519 conversion, CEK wrap (itsgoin/cek-wrap/v1), group-key wrap,
                                 encrypt/decrypt_post, FoF wrap slots + prefilter, slot keys
    blob.rs                    — BlobStore (256-shard layout), compute_blob_id, verify_blob,
                                 delivery budget tracking

    identity.rs                — IdentityManager: multi-identity dirs, create/list/switch/delete,
                                 network vs posting identity (v0.6.0 split)
    profile.rs                 — profile posts (signed, content-addressed profile updates)
    control.rs                 — control posts: audience removal, delete control posts,
                                 persona admin ops
    fof.rs                     — Friend-of-Friend visibility: V_x wrap slots, anonymous prefilter,
                                 pub_post_set, CDN-level comment verification,
                                 V_me rotation / cascade-revoke / KeyBurnDiff
    group_key_distribution.rs  — circle group key distribution as encrypted posts + epoch rotation
    activity.rs                — in-memory ring buffer (200 events) of node activity
                                 (growth/rebalance/recovery/anchor/connection/relay) for the UI
                                 status panel — NOT engagement storage
    announcement.rs            — release announcement post handling

    storage.rs                 — SQLite (auto-migration): posts, peers, follows, profiles,
                                 circles/circle_members/circle_profiles, deleted_posts,
                                 post_replicas, peer_neighbors, mesh_peers, reachable_n2/n3,
                                 social_routes, reconnect_watchers, blobs, blob_headers,
                                 cdn_manifests, file_holders (flat CDN, cap 5), post_hosts,
                                 reactions/comments/comment_policies/thread_meta,
                                 seen_engagement/seen_messages, group_keys/group_member_keys/
                                 group_seeds, known_anchors, ignored_peers, relay_cooldowns,
                                 worm_cooldowns, settings, post_recipients, posting_identities,
                                 preferred_peers (dropped in v0.8 Iteration B), + 10 vouch/FoF tables
                                 (vouch_keys_own/received, vouch_bio_scan_cache, own_vouch_targets,
                                 fof_revocations, own_post_slot_provenance, vouch_unlock_cache,
                                 vouch_unreadable_posts, own_fof_post_ceks, fof_key_burns).
                                 post/blob_upstream+downstream tables dropped in v0.6.1-beta.
    protocol.rs                — MessageType enum, ALPN (itsgoin/4),
                                 length-prefixed JSON framing, InitialExchangePayload
    connection.rs              — ConnectionManager + ConnHandle/ConnectionActor (actor pattern):
                                 mesh + session slots, initial exchange, N1/N2 diff broadcast,
                                 pull sync, worm search, relay introduction, referral list,
                                 anchor self-probe, engagement diff handling. EDM scanner
                                 preserved as edm_port_scan_disabled_v0_7_3 (#[allow(dead_code)]).
                                 session_relay_enabled gate (opt-in OFF by default).
    network.rs                 — iroh Endpoint, accept loop, connect_to_peer, growth loop,
                                 connect_by_node_id support, mDNS passive address lookup,
                                 bidirectional anchor reachability watcher, per-IP rate limiting
    node.rs                    — Node struct, post CRUD, follow/unfollow, profile/circle CRUD,
                                 encrypted post creation, startup cycles, bootstrap with
                                 probe_anchors_batched + stale-anchor prune, pull/diff/rebalance/
                                 recovery/replication cycles, delete control posts,
                                 connect_by_node_id resolution cascade, blob eviction scoring
    web.rs                     — itsgoin.net web handler: QUIC proxy for share links, tiered
                                 serving (redirect/TCP punch/proxy), on-demand post fetch
    http.rs                    — raw-TCP HTTP listener: /p/ + /b/ routes, 5+15 slot budget,
                                 holder 302 redirect with 200ms probe, render_post_html
    upnp.rs                    — port mapping: UPnP-IGD + NAT-PMP + PCP via portmapper crate;
                                 PortMapping holds Client for service lifetime; watch_external()
    stun.rs                    — STUN probes (NAT type detection)
    android_wifi.rs            — Android-only JNI bridge: WifiManager.MulticastLock,
                                 WiFi/Ethernet detection, NodeService.stopFromNative
    export.rs / import.rs      — posting-key ZIP bundles: export, import-as-personas,
                                 import-as-new-identity, post import & merge (merge_with_key)

crates/cli/
  src/main.rs       — interactive REPL + anchor/daemon mode (--bind, --daemon, --web)

crates/tauri-app/
  src/lib.rs        — Tauri v2 commands (DTOs + IPC handlers): persona CRUD, identity
                       import/export, exit_app (Android NodeService stop), session-relay toggle
  gen/android/      — Android shell: NodeService.kt foreground service with
                       companion stopFromNative() static

frontend/
  index.html        — single-page UI: 5 tabs (Feed / My Posts / People / Messages / Settings),
                       close-app button with inline SVG power icon, session-relay toggle
  app.js            — Tauri invoke calls, rendering, identicon generator, circle CRUD
  style.css         — dark theme, post cards, visibility badges, transitions

website/
  design.html       — this document (canonical design reference)
  download.html     — release notes
  index.html, tech.html, contribute.html
  style.css         — shared site styling

License

ItsGoin is released under the Apache License, Version 2.0. You may use, modify, and distribute this software freely under the terms of that license.

This is a gift. Use it well.