darkfi/openspec/changes/swarm/specs/swarm-overlay/spec.md

Purpose

Defines a bounded rendezvous overlay that resolves known swarm descriptors to untrusted peer addresses while making bootstrap, replay, resource, persistence, and metadata-disclosure boundaries explicit.

ADDED Requirements

Requirement: Versioned swarm identifier derivation

A version-1 descriptor SHALL bind the swarm application name, magic bytes, and major/minor version pair used by the existing compatibility handshake. Its canonical bytes SHALL be, in order:

1. ASCII darkfi-swarm-id-v1 followed by one zero byte;
2. application-name UTF-8 byte length as unsigned 16-bit big-endian, followed by those exact bytes without Unicode normalization;
3. the four magic bytes;
4. major and minor versions as unsigned 64-bit big-endian integers;
5. zero for a public descriptor or one for a private descriptor; and
6. for a private descriptor only, exactly 32 secret bytes.

Application names MUST contain 1 through 32 UTF-8 bytes. Other private-secret lengths and flag values MUST be rejected. SwarmId SHALL be the 32-byte BLAKE3 hash of the canonical bytes. Implementations SHALL rely on collision resistance rather than claim collision is impossible. Patch, prerelease, and build metadata SHALL NOT affect the ID.

For public darkirc, magic fb e5 c7 b5, and compatibility pair 0.5, the canonical bytes SHALL be:

6461726b66692d737761726d2d69642d76310000076461726b697263fbe5c7b50000000000000000000000000000000500

and SwarmId SHALL be:

cad1d01807849a400541725bd75af14e53d259392082c14fa96ce6313551feb4.

Scenario: Golden public identifier

• WHEN an implementation derives the specified darkirc identifier
• THEN its canonical bytes and hash equal the normative values

Scenario: Compatibility-equivalent patch versions

• WHEN descriptors differ only in patch, prerelease, or build metadata
• THEN they derive the same identifier

Scenario: Bound field differs

• WHEN valid descriptors differ in any bound field
• THEN their canonical bytes differ and identifiers are expected to differ under BLAKE3 collision resistance

Scenario: Malformed private descriptor

• WHEN a private descriptor secret is not exactly 32 bytes
• THEN validation fails before hashing

Requirement: Private identifiers are rendezvous capabilities only

A generated private secret MUST use a cryptographically secure random source. A caller-supplied secret SHALL be accepted only as exactly 32 bytes and SHALL be documented as requiring independent high entropy. It makes an identifier difficult to derive only before observation. It MUST NOT be represented as authentication, encryption, authorization, or continuing confidentiality.

Public enumeration MUST omit records from accepted ads marked non-public, but visibility is unauthenticated sender data rather than an intrinsic property of an ID. Persistent gossip peers necessarily observe IDs they store or relay, and an attacker that learns an ID can submit another ad marking it public.

Scenario: Unobserved random private identifier

• WHEN a party neither knows nor observes a uniformly random secret
• THEN deriving its identifier requires guessing the 32-byte secret

Scenario: Private identifier is disclosed

• WHEN a private ID is sent in an ad or lookup
• THEN the receiving overlay peer can observe and reuse it

Scenario: Observed private ID is relabeled

• WHEN an attacker re-advertises an observed private ID with public visibility
• THEN the protocol may catalog the forged public record and makes no intrinsic-privacy claim for the ID

Requirement: Bootstrap uses staged ordinary non-seed overlay connections

Bootstrap addresses SHALL use ordinary non-seed sessions capable of carrying swarm requests and responses, not existing short-lived seed sessions. “Ordinary” SHALL describe session type, not a requirement that a transient keep the channel indefinitely. A transient with a cache SHALL first construct and start an overlay instance using cached peers only. If no ordinary compatible channel completes within the stage timeout, it SHALL fully stop and discard that instance before constructing a fresh overlay instance using configured ordinary bootstrap peers. It MUST NOT depend on runtime manual-session reload.

Each stage timeout MUST be finite and no greater than 300 seconds. The cache MUST contain no more than 256 endpoint records, 262,144 encoded file bytes, or 1,024 encoded bytes per URL. A record SHALL contain only the exact canonical connect URL and resolved endpoint actually used by a successfully completed ordinary channel advertising ("swarm-ad-store", 1). Advertised external addresses MUST NOT be cached from that feature handshake. The cache MUST NOT contain features, swarm IDs, ads, queries, or source/query associations.

Scenario: Cached stage succeeds

• WHEN a cached ordinary peer completes before the stage deadline
• THEN configured bootstrap peers are not contacted

Scenario: Cached stage fails

• WHEN no cached peer completes before the stage deadline
• THEN the cached overlay instance is stopped before a fresh configured-peer instance starts

Scenario: Bootstrap peer answers lookup

• WHEN a fresh configured-peer stage establishes an ordinary channel
• THEN lookup can run on that channel without a seed session

Scenario: Cache contains no swarm activity

• WHEN lookup sessions persist the swarm cache
• THEN it contains successful connect/resolved endpoint pairs only

Scenario: Advertised external address is not cache authority

• WHEN a connected persistent peer advertises an external address different from the endpoint used by its successful channel
• THEN the different external address is not added to the cache

Requirement: Untrusted dials use validated exact targets

Before dialing a fresh advertised or configured untrusted target, the joiner SHALL resolve clearnet names once and validate the selected socket address. A cached target SHALL instead revalidate and reuse its stored successfully connected socket without DNS resolution. Unless explicit local-test mode is enabled, both paths MUST reject loopback, private, shared, link-local, multicast, unspecified, documentation, benchmarking, and otherwise reserved destinations for IPv4 and IPv6. Production lilith MUST NOT enable local-test mode.

Every validated target SHALL carry the original URL, one mandatory exact socket, and a direct or trusted-proxy route kind. For a direct route, the socket is the validated destination and connection SHALL use it without a second DNS lookup; the original hostname MAY be retained only for TLS identity.

For a trusted-proxy route, the mandatory socket SHALL be the exact endpoint from trusted local proxy configuration, not the advertised destination. That proxy socket MAY be loopback/private under local trust policy; an advertisement MUST NOT select or override it. The untrusted destination SHALL be either a globally routable IP literal or a canonical Tor/I2P hidden-service name matching the transport. A hidden-service name MUST NOT undergo local DNS and MAY be passed only inside proxy negotiation and for TLS identity. Arbitrary clearnet hostnames MUST NOT be sent for remote proxy DNS. Missing/malformed proxy configuration and transport/scheme mismatch SHALL reject the candidate. One join attempt SHALL dial one exact route at most once.

A clearnet DNS answer SHALL contain at most 16 socket addresses and every answer SHALL consume the join's resolution budget and pass address classification. Empty or oversized answers SHALL fail. A bounded nonempty answer SHALL be iterated without unchecked indexing; its allowed sockets SHALL be shuffled with OsRng before selecting at most one exact socket for that URL. A cached trusted- proxy route SHALL revalidate that its exact socket still matches current trusted local proxy configuration; mismatch fails without DNS or fallback.

An advertised candidate SHALL remain a typed pair of original URL and validated resolved socket through the swarm connection attempt. Before compatibility succeeds it MUST NOT be downgraded into a URL-only hostlist, persisted, or sent through a connector/refinery path that resolves it again. Failed candidates SHALL be dropped. After compatibility succeeds, ordinary host persistence MAY record the peer URL, but every future reconnect or refinement attempt MUST resolve, validate, budget, and dial one exact socket again.

Scenario: DNS result changes after validation

• WHEN a hostname changes resolution after an address was validated
• THEN the connection uses the previously validated socket and performs no second DNS lookup

Scenario: Cached hostname would resolve differently

• WHEN a cached record contains an original hostname and successful socket but DNS now returns another address
• THEN cache reuse revalidates/dials the stored socket and performs no DNS lookup for that cached attempt

Scenario: Private or loopback result

• WHEN an untrusted clearnet target resolves to a prohibited range outside explicit local-test mode
• THEN it is rejected before connection

Scenario: Victim endpoint is repeatedly advertised

• WHEN many ads name one globally routable victim endpoint
• THEN one join attempt dials it at most once and all dial rate/concurrency/ total budgets remain enforced

Scenario: Remote proxy DNS target

• WHEN an untrusted ad supplies an arbitrary clearnet hostname to a proxy mode that would resolve it remotely
• THEN the target is rejected rather than bypassing egress validation

Scenario: Canonical hidden service uses trusted proxy

• WHEN an accepted Tor/I2P candidate names a canonical hidden service
• THEN its exact socket is the locally configured trusted proxy, the hidden name is not locally resolved, and the ad cannot alter the proxy endpoint

Scenario: Hidden-service proxy is absent

• WHEN an otherwise valid hidden-service candidate has no valid configured proxy matching its transport
• THEN it fails before dialer construction without direct-network fallback

Scenario: Candidate crosses into swarm connector

• WHEN a validated advertised candidate is handed to the swarm connection attempt
• THEN its original URL and exact socket remain typed until compatibility succeeds, with no second DNS lookup or URL-only greylist insertion

Scenario: Failed candidate is not persisted

• WHEN a validated candidate fails transport or compatibility
• THEN it is dropped without entering persistent hostlist or refinery state

Scenario: Compatible peer reconnects later

• WHEN an ordinary persisted peer is retried or refined in a later attempt
• THEN that attempt resolves and validates a new exact target under the same egress and dial budgets before connection

Requirement: Advertised-candidate processing is fully fallible

The complete attacker-selected candidate pipeline SHALL be fallible: URL parse, scheme allowlist, host/port extraction, DNS result handling, address classification, validated-target construction, proxy selection and negotiation, transport/TLS dialing, and compatibility. It MUST NOT use unwrap, expect, explicit panic, unchecked slicing/indexing, or an unimplemented transport branch. Unsupported or unaudited schemes MUST be rejected before dialer construction. Empty or oversized DNS results, malformed targets, missing/malformed proxies, timeouts, cancellation, and transport errors MUST return bounded candidate errors. Bounded multiple-address results MUST be iterated and classified without unchecked selection. Processing SHALL continue or terminate only according to the join budget.

Scenario: Resolution returns no addresses

• WHEN an advertised clearnet name resolves to an empty set
• THEN candidate processing returns an error without indexing or unwind

Scenario: Resolution returns multiple addresses

• WHEN a clearnet name resolves to a bounded nonempty address set
• THEN every result is budgeted/classified without unchecked indexing and at most one OsRng-shuffled allowed exact socket is selected for that URL

Scenario: Every accepted scheme receives hostile input

• WHEN arbitrary malformed targets exercise each scheme accepted from ads
• THEN parsing through compatibility returns bounded errors without unwind

Scenario: Enabled transport has no audited fallible adapter

• WHEN an advertisement selects an enabled but unsupported or unimplemented transport path
• THEN the candidate is rejected before transport construction or dialing

Requirement: Overlay control channels are never swarm data channels

An overlay channel SHALL remain owned by the overlay P2p identified by fixed swarm magic bytes, app name, version policy, host state, and protocol registry. It MUST NOT carry swarm application messages, be transferred to a swarm P2p, be re-handshaken in place under a swarm identity, or multiplex traffic tagged by swarm ID. Joining SHALL create a separate swarm channel under that swarm's own identity and state.

A persistent participant SHALL keep its overlay active while it performs durable store or gossip duties. A participant serving any swarm SHALL keep the overlay active while advertisement authoring is enabled. The default transient policy SHALL retain the overlay for the application session and MUST NOT stop it as an automatic reaction to lookup or join completion. The application session ends only through explicit overlay stop or full SwarmPool shutdown. An explicit reduced-privacy policy SHALL stop after every caller-visible lookup/join terminal outcome—success, empty result, error, timeout, or cancellation—but MUST NOT stop after an internal lookup phase within join. Configuration and documentation MUST warn that responder/swarm observers can correlate the query, swarm connection, and teardown timing. Stopping the overlay MUST NOT stop or transfer the independent swarm P2p; a later lookup establishes a new overlay session only when no active overlay remains.

Scenario: Overlay peer also serves requested swarm

• WHEN the lookup responder also operates a serving endpoint for the requested swarm
• THEN the client opens a separate swarm connection rather than reusing the overlay channel

Scenario: Default transient join does not trigger disconnect

• WHEN a default-policy transient completes lookup or swarm join
• THEN join completion itself does not stop the overlay

Scenario: Explicit reduced-privacy teardown

• WHEN a caller selects immediate teardown and lookup or join reaches any terminal outcome
• THEN the overlay stops without stopping the swarm and configuration/docs flag the timing-correlation risk

Scenario: Join's internal lookup completes

• WHEN reduced-privacy policy is active and an internal lookup yields candidates while the caller-visible join remains in progress
• THEN the overlay is not stopped until join reaches its terminal outcome

Scenario: Persistent duties retain overlay

• WHEN persistent store/gossip or serving-advertisement duties remain active
• THEN the participant does not intentionally stop its overlay

Requirement: Wire messages have fixed correlation and size bounds

Every lookup request SHALL carry a fresh cryptographically random 16-byte request ID. Its response or bounded error SHALL echo that ID. A channel SHALL have no more than 32 outstanding requests. Responses with unknown, duplicate, expired, or mismatched request IDs MUST be rejected. Pending request state MUST be removed on response, timeout, or disconnect. Request timeout SHALL default to 10 seconds, be configurable no higher than 60 seconds, and produce a local timeout error; a late response is unsolicited and receives no wire error.

Protocol hard limits SHALL be:

Message	Maximum encoded bytes
SwarmAd	65,536
GetSwarmAddrs	128
SwarmAddrs	65,536
GetPublicSwarms	128
PublicSwarms	16,384
SwarmError	128

Every encoded URL MUST be no more than 1,024 bytes. A page cursor SHALL be a fixed 65-byte value encoded as version u8, last returned key [32], and terminal key [32]. Size/count validation MUST occur before store, index, response, or relay work.

Message command strings and canonical field order SHALL be:

Command	Fields in encoded order
ad	SwarmId[32], visibility u8, ad ID [32], lifetime u32, URL vector
getaddr	request ID [16], SwarmId[32], optional cursor
addrs	request ID [16], SwarmId[32], URL vector, optional cursor
getswarm	request ID [16], optional cursor
swarms	request ID [16], SwarmId vector, optional cursor
err	request ID [16], error code u8

Fields SHALL use existing DarkFi canonical wire encoding. Visibility values SHALL be 0 = public and 1 = non-public; other values are invalid. Error values SHALL be 0 = malformed, 1 = invalid cursor, 2 = enumeration disabled, and 3 = busy; other values are invalid. Lifetime is unsigned 32-bit and cursor version SHALL be one.

Every attacker-controlled swarm, version, and verack decoder SHALL return a fallible error for malformed or truncated input without unwind. Such paths MUST NOT use unwrap, expect, explicit panic, unchecked slicing/indexing, or reserve/allocate from an unvalidated declared length/count. Bounds validation MUST precede allocation and element decoding.

Scenario: Concurrent requests correlate correctly

• WHEN multiple lookups are outstanding on one channel
• THEN each response completes only the request whose ID it echoes

Scenario: Unsolicited response

• WHEN a response carries no live matching request ID
• THEN it is rejected and consumes metering budget

Scenario: Message exceeds hard limit

• WHEN any message exceeds its encoded maximum
• THEN it is rejected before variable store or relay work

Scenario: Payload is truncated at any byte

• WHEN a valid swarm, version, or verack payload is truncated at any byte boundary
• THEN decoding returns an error without unwind or excessive allocation

Scenario: Declared length is hostile

• WHEN an arbitrary payload declares a count or length larger than its validated bound or remaining bytes
• THEN decoding rejects it before reservation, slicing, or element work

Requirement: Advertisement format is bounded and nonempty

An ad SHALL contain exactly one swarm ID, public/non-public visibility, a fresh 32-byte per-ad ID, lifetime seconds, and 1 through 32 serving addresses. The ad ID MUST use a cryptographically secure random source and MUST NOT be reused for another emission or swarm. It is deduplication data, not identity.

Lifetime MUST be 1 through 86,400 seconds. Ads MUST NOT contain last_seen, a stable node ID, signing key, author, relay provenance, hop count, or identifier shared with another swarm. Every address MUST be valid, publicly shareable, and within the URL bound. A receiver SHALL reject the entire ad if any field or address is invalid.

Scenario: Valid ad is swarm-scoped

• WHEN a valid ad for S is accepted
• THEN it contains only S, S's addresses, and a unique ephemeral ad ID

Scenario: Empty ad

• WHEN an ad contains no address
• THEN it is rejected without store or relay work

Scenario: Invalid address

• WHEN any ad address is malformed, non-shareable, or overlong
• THEN no part of the ad is stored or relayed

Requirement: Expiry, replay suppression, and storage remain bounded

A persistent participant SHALL use finite nonzero per-swarm, global-address, per-swarm protected-ID, and global protected-ID caps. Configured values MUST NOT exceed 1,024 addresses per swarm, 65,536 total addresses, 1,024 protected IDs per swarm in the general pool, or 262,144 protected IDs globally. Runtime expiry SHALL use a monotonic deadline from local receipt and sender clocks SHALL have no effect.

Those caps SHALL default respectively to 256 addresses per swarm, 16,384 total addresses, 256 general protected IDs per swarm, and 65,536 protected IDs globally.

The receiver SHALL clamp each accepted address lifetime to the lesser of the wire lifetime and a local receive cap. That cap SHALL default to 7,200 seconds, MUST be nonzero, and MUST NOT exceed 86,400 seconds. Local author lifetime SHALL also default to 7,200 seconds and MUST NOT exceed 86,400 seconds.

Receiving a retained ad ID MUST NOT extend expiry or repeat relay work. The dedup deadline SHALL be exactly 86,400 seconds after the associated locally clamped address expiry, making total protection no greater than 172,800 seconds from acceptance. A protected ID MUST NOT be evicted before that deadline. A fresh remote ad SHALL be rejected without address mutation or relay when its swarm's general-pool quota or the global general pool has no expired slot. Expired IDs may be evicted deterministically.

Local-author reserve-swarm partitions SHALL default to 32 and MUST NOT exceed

1. Each partition contains exactly 256 protected-ID slots and counts within the global cap; checked configuration arithmetic SHALL require a nonzero remaining general pool. Remote ads MUST NOT consume reserve partitions. A serving transition SHALL atomically allocate/reuse one partition for its swarm before listener or author activation and fail with a typed capacity error when none is available. Stopping service SHALL retain that partition until all its protected local IDs expire, then release it atomically when that swarm is not serving, so sequential swarm churn cannot overwrite protection.

Startup SHALL validate the partitions independently: general protected IDs MUST fit the global general capacity and each general per-swarm quota; local IDs MUST fit 256 slots for each distinct reserved swarm and the configured partition count. Persisted local IDs already occupy their reserve and MUST NOT be counted again as general state. Locally authored IDs MAY NOT evict protected IDs. The reserve prevents remote admission from blocking allocated local cadence, but does not provide preferential validation or remote role privilege.

Fresh IDs may refresh addresses subject to caps. Address eviction SHALL choose expired entries first, then earliest expiry, then lexical key. Stores MUST NOT dial advertised addresses or record ad sources, queriers, query history, or source-peer/swarm associations. Replay IDs SHALL remain globally keyed; each record SHALL bind its advertised swarm only for quota/protection accounting, so reuse of one ad ID under another swarm is still a duplicate. A local-author reserve record necessarily marks an ID as generated by this process; that local fact and reserve occupancy/use/failure/timing MUST NOT enter wire messages, RPC, status, metrics, telemetry, or peer-linked state, even as aggregate counters. Fresh forged IDs can still poison within bounds; the store provides no authenticity.

Acceptance SHALL atomically commit the global seen-ID record, quota/reserve accounting, address records, and public-index mutation before any relay job is enqueued. Commit failure SHALL cause no mutation or relay. Rollback of the database to a snapshot before that commit can remove the seen ID and permit a later replay; this capability makes no non-rollbackable replay guarantee.

Store state SHALL be normalized per (SwarmId, canonical address). Accepting a fresh ad updates visibility and expiry for every address present in that ad; addresses absent from it retain their current record until independently updated, expired, or evicted. An ID is publicly enumerable iff at least one live normalized record is marked public. Public-to-non-public and reverse updates of the same address take effect atomically. Direct lookup returns all live records regardless of visibility.

Persistent replay state SHALL use unsigned 64-bit monotonic epoch ticks in seconds. Each seen-ID record stores its checked deadline tick, and one atomic metadata checkpoint stores elapsed tick every 300 seconds by default, no less often than every 600 seconds, and on clean shutdown. On restart, a record with deadline <= checkpoint SHALL be expired without subtraction. Otherwise the implementation SHALL use checked subtraction, reject a delta greater than 173,400 seconds as incoherent, clamp valid remaining duration to 172,800 seconds, and use checked duration conversion and Instant deadline addition. Overflow, underflow, missing/incoherent epoch metadata, or failed deadline construction SHALL return a typed startup error.

If a durable checkpoint cannot complete before the 600-second maximum interval, the persistent store SHALL reject fresh ad acceptance and local authoring until a checkpoint succeeds or controlled shutdown completes; it MUST NOT continue creating deadline deltas outside the validated bound.

All surviving records and new epoch metadata SHALL replace the old epoch in one atomic batch; interruption leaves the old epoch loadable. Downtime and the uncheckpointed interval are not subtracted, so they MAY extend a record present in the loaded database, but restart MUST NOT reset every such ID to a fresh full horizon or shorten it. A database rollback before seen-ID commit can remove the record entirely and is explicitly outside that guarantee. Address records continue to use persisted wall expiry and MAY expire conservatively on clock anomalies. If separately validated general/reserve capacities cannot contain valid persisted protected IDs, startup SHALL fail without eviction.

Malformed or unverifiable persisted seen-ID, quota/reserve, or epoch state SHALL fail startup. Malformed address records MAY be quarantined and a public index MAY be rebuilt only when authoritative replay/accounting state remains intact.

Scenario: Duplicate does not refresh

• WHEN a retained ad ID is replayed
• THEN original expiry remains and no second relay occurs

Scenario: Ad ID is reused for another swarm

• WHEN a retained global ad ID appears with a different swarm ID
• THEN it remains a duplicate and does not consume that swarm's quota or mutate/relay addresses

Scenario: Protected dedup set is full

• WHEN a fresh ad arrives while every dedup slot is protected
• THEN the fresh ad is rejected instead of evicting a protected ID

Scenario: One swarm fills its protected-ID quota

• WHEN fresh remote ads for one swarm consume every unexpired slot in that swarm's general quota
• THEN another fresh ad for that swarm is rejected without consuming slots reserved for other swarms or local authoring

Scenario: Remote flood reaches the local-author reserve

• WHEN the remote general pool is full while local authoring remains active
• THEN a locally authored ad may use its swarm reserve and no remote ad may consume that slot

Scenario: Sequential serving exhausts reserve partitions

• WHEN stopped swarms with protected local IDs occupy every configured reserve partition and another swarm requests serving
• THEN transition fails before listener/author activation without evicting or shortening any occupied partition

Scenario: TTL expires without probe

• WHEN an address reaches local expiry without a fresh accepted ad
• THEN it is no longer returned and no address probe occurred

Scenario: Restart preserves address expiry conservatively

• WHEN durable state reloads before expiry with a non-rollback wall clock
• THEN only remaining lifetime is restored as a monotonic deadline

Scenario: Restart restores checkpointed protection

• WHEN a valid persisted seen ID loads after restart
• THEN its checked positive deadline/checkpoint difference is restored conservatively rather than resetting it to the full horizon

Scenario: Deadline equals checkpoint

• WHEN a persisted deadline tick is equal to or below the checkpoint tick
• THEN the record expires without unsigned subtraction or revival

Scenario: Epoch arithmetic is incoherent

• WHEN subtraction/addition would underflow/overflow or a stored delta exceeds 173,400 seconds
• THEN startup returns a typed error without clamping wrapped arithmetic

Scenario: Crash precedes the next checkpoint

• WHEN a process crashes less than 600 seconds after its last checkpoint
• THEN records present in the loaded database may be extended by the uncheckpointed interval and downtime but are not shortened

Scenario: Store rolls back before acceptance commit

• WHEN an operator restores a database snapshot predating an accepted ad ID
• THEN that ID may be accepted and relayed again, and documentation does not claim rollback-resistant replay suppression

Scenario: Reduced capacity cannot hold protected state

• WHEN configured dedup capacity is below valid persisted seen-ID count
• THEN startup fails without evicting a protected ID

Requirement: Gossip is bounded without anonymity overclaim

Persistent participants SHALL relay each newly accepted ad without changing identifying contents. Relay fanout MUST be finite and no greater than 64. Queued relay work MUST be bounded and duplicates MUST NOT be requeued. Own ads SHALL be authored only on a fixed 1,800-second base cadence with independently sampled uniform jitter from -600 through +600 seconds. This cadence is not configurable in version one. Authored lifetime SHALL default to 7,200 seconds and MUST NOT exceed 86,400 seconds. Swarm start, listener start, and new overlay channels MUST NOT trigger authoring.

A transient MAY relay newly accepted ads from bounded memory but SHALL NOT author one. No author field means an immediate sender is not protocol-level proof of authorship; this MUST NOT be described as hiding authorship against timing, topology, first-seen, or global observation.

Scenario: Relay preserves contents

• WHEN an accepted ad is relayed
• THEN swarm ID, visibility, ad ID, lifetime, and addresses are unchanged

Scenario: Gossip loop

• WHEN the same ad returns during its protected horizon
• THEN no second relay is queued

Scenario: Start remains silent

• WHEN serving or a new overlay channel starts
• THEN authoring waits for the cadence

Requirement: Lookup and optional public enumeration are paginated

Direct lookup SHALL name one swarm and return addresses only for it. Each page SHALL echo the request ID, contain at most 64 addresses and 65,536 encoded bytes, and include at most one fixed cursor. On the first page, the responder SHALL capture the current greatest live ordered key as the terminal key. A next cursor SHALL contain the last returned key and that fixed terminal key. Later pages SHALL return only live keys strictly greater than the last key and no greater than the terminal key, advancing the last key monotonically. A cursor whose version, length, or key ordering is invalid SHALL return a bounded invalid- cursor error. Index mutation MUST NOT invalidate a well-formed cursor, create a server snapshot, or force traversal restart; it MAY cause records added/removed during traversal to be included or omitted. Page limits still bound completion. For every page, the responder SHALL derive canonical keys, return each key at most once in strictly ascending order, and keep every key in (previous_last, terminal] when a previous cursor exists. A next cursor MUST be absent on an empty page and otherwise its last key MUST equal the greatest returned key with last < terminal. The requester SHALL independently derive and validate those keys, reject duplicates within/across pages, reject an empty page with a next cursor, and reject a response cursor that changes the first page's terminal, fails to advance, or disagrees with returned keys. Requester dedup state remains bounded by page/item limits.

Public enumeration SHALL be disabled by default and require explicit local enablement. If enabled, it SHALL return IDs having at least one live normalized address record marked public, at most 256 IDs and 16,384 bytes per page. It SHALL be available to every protocol-correct connected peer without role privilege and MAY be disabled globally without disabling direct lookup. Visibility is not authenticated: an attacker can cause an observed ID to appear by submitting a public-marked address record. No response SHALL include ad sources or querier data.

Scenario: Direct lookup is isolated

• WHEN addresses for S are requested
• THEN response pages contain S addresses only within both page bounds

Scenario: Non-public record is omitted

• WHEN an ID has only accepted non-public records
• THEN it is omitted while direct lookup remains possible to a caller already knowing the ID

Scenario: Enumeration setting is omitted

• WHEN an operator does not explicitly enable public enumeration
• THEN public-list requests return the bounded disabled error while direct lookup remains available

Scenario: Index changes during pagination

• WHEN records are inserted, updated, expired, or removed before the next page
• THEN traversal continues strictly after the prior key up to the original terminal key without restart or snapshot state

Scenario: Insertions sort after the initial terminal

• WHEN new records sort after the terminal key captured on the first page
• THEN they cannot extend that traversal and require a later lookup

Scenario: Hostile response does not advance semantically

• WHEN a responder returns duplicate/unordered/out-of-window items, changes the terminal, or advances a cursor on an empty page
• THEN the requester rejects the page without adding candidates or continuing from that cursor

Requirement: Role boundaries and version features are validated

A persistent participant SHALL advertise exactly ("swarm-ad-store", 1), maintain durable bounded state, and relay ads. A node without it SHALL be treated as transient. The feature MUST NOT grant privilege. Local and remote version messages SHALL allow at most 10 external addresses and 10 features; node ID SHALL be at most 64 encoded bytes, app name at most 32, semver prerelease and build strings at most 32 each, every URL at most 1,024, and every feature name at most 32. Complete outgoing VersionMessage and VerackMessage encoded-size validation MUST succeed before send. Inbound decoding of both messages MUST check every declared variable length/count, including semver strings, before reservation or allocation while preserving existing field order and valid wire encoding byte-for-byte.

A transient SHALL accept no inbound overlay connections, author no ads, and persist no swarm-overlay ad/query/history state. It MAY keep bounded in-memory ads and the bounded successful-endpoint-only cache. Swarm lifecycle persistence and transport-managed state are separate scopes and MUST be documented separately. Both roles apply identical decoding, validation, authorization, and work bounds.

Scenario: Claimed role grants no privilege

• WHEN a malicious peer self-declares the persistent feature
• THEN it receives no validation, query, metering, or storage exemption

Scenario: Complete version message is oversized

• WHEN otherwise valid local fields combine into an oversized outgoing version message
• THEN it is rejected before send

Scenario: Remote feature count is oversized

• WHEN an inbound payload declares more than 10 features despite fitting the total payload bound
• THEN decoding rejects it before reserving the declared vector capacity

Scenario: Remote semver string is oversized

• WHEN inbound version or verack declares an overlong prerelease/build string within the total payload bound
• THEN decoding rejects it before allocating the declared string

Scenario: Complete verack is oversized

• WHEN local app/version fields would exceed VERACK_MAX_BYTES
• THEN verack is rejected before send

Scenario: Transient overlay persistence

• WHEN a transient disconnects
• THEN swarm-overlay state retained by the module is at most its bounded successful connect-URL/resolved-endpoint cache, while separately configured swarm/transport state follows its own documented policy

Requirement: Resource accounting covers amplification paths

Every message type SHALL have hard per-channel metering. In a 10-second window, one channel SHALL accept at most 32 ads, 16 direct lookup requests, 16 direct responses, 4 public-list requests, 4 public-list responses, and 16 bounded errors before strict-policy delay/penalty. It SHALL also receive at most 32 store-write and 32 relay-enqueue work tokens per 10 seconds and at most 1,048,576 response bytes per 60 seconds.

Variable fields SHALL be validated before allocation or work. Configured local limits SHALL use these defaults and MUST NOT exceed these maxima:

Resource	Default	Maximum
relay queue jobs	1,024	4,096
concurrent durable writes	8	32
concurrent query reads	16	64
concurrent relay workers	8	32
pages consumed per direct join lookup	16	16
pages consumed per public enumeration	4	16
candidate addresses per join attempt	64	256
previously compatible retry attempts	16	64
persisted compatible retry URLs per swarm	64	256
local-author reserve swarm partitions	32	256
active swarms	32	256
concurrent lifecycle attempts	8	32
shutdown deadline seconds	120	600
pending-request timeout seconds	10	60
configured ordinary overlay peers	8	256
overlay bind/listener addresses	1	16
serving bind addresses per swarm	1	16
serving external addresses per swarm	1	32
overlay inbound channels	64	256
overlay outbound channels	8	64
overlay manual channels	8	256
total established overlay channels	80	512
untrusted dial concurrency	4	16
untrusted dial starts per minute	32	128
DNS resolutions per join attempt	64	256
dials per resolved destination per attempt	1	1

Overlay instances SHALL use strict ban policy. Queue/concurrency/retry settings outside these ranges SHALL be rejected at configuration time.

A small request MUST NOT induce an unbounded response, write, relay, allocation, or outbound connection. Budget accounting SHALL use ephemeral channel IDs, not peer addresses, and SHALL be removed on disconnect.

Scenario: Query amplification is bounded

• WHEN a channel floods minimal valid requests
• THEN pending state, response bytes, and processing stay bounded and strict penalties apply

Scenario: Advertisement cannot induce dialing

• WHEN an ad contains an attacker-selected shareable address
• THEN accepting, storing, relaying, expiring, or reporting it opens no connection to that address

Requirement: Swarm joining alone validates advertised addresses

Lookup results SHALL remain ephemeral typed original-URL/resolved-socket targets for the requested swarm until compatibility succeeds; they MUST NOT enter a URL-only host/refinery set first. A joining swarm MUST apply ordinary magic, application-name, and major/minor checks before treating a peer as compatible. Failure MUST drop the candidate, remain fallible, and MUST NOT penalize the overlay relay. Passing compatibility does not authenticate an operator or authorize application access. Future ordinary reconnect/refinement attempts MUST independently resolve and validate a new exact target.

Before resolution or dialing, the joiner SHALL place previously compatibility- verified persisted ordinary peers in one tier and fresh overlay URLs in another. The swarm retry index itself SHALL contain at most the configured persisted- compatible cap; when full, a newly compatible URL remains usable for its current session but MUST NOT evict an existing retry URL merely to enter that index.

A direct join lookup SHALL continue through the first page's terminal until no next cursor remains or its fixed 16-page cap is consumed. It SHALL use bounded OsRng reservoir sampling across every valid URL returned in that traversal to select at most the candidate-address cap, rather than truncating an ordered prefix when candidate capacity is reached. The full bounded persisted index and fresh reservoir SHALL then be independently shuffled with OsRng; wire, store, URL, hash, DNS-answer, or lexical order MUST NOT choose the attempted prefix.

After both URL tiers are built, candidate preparation SHALL consume no more than half the then-remaining overall deadline; verified and fresh resolution/ validation SHALL each have half that subdeadline. Unused verified time MAY be donated to fresh preparation but not conversely. Every persisted peer MUST still undergo fresh resolution and egress validation.

Already validated targets SHALL be installed as a two-phase pre-start manual plan. At swarm start, the remaining candidate-dial duration SHALL be split at a monotonic midpoint. The verified phase MUST stop/cancel by that midpoint and consume no more than its configured retry limit or half the total candidate- attempt budget. Fresh targets activate for the second half and retain at least half the attempt capacity; if the verified phase is empty, fresh dialing MAY begin immediately. Every connector uses the exact validated target. No fresh candidate is persisted before compatibility.

Scenario: Wrong swarm is rejected

• WHEN an advertised peer fails a bound compatibility field
• THEN it does not enter the verified ordinary swarm peer set

Scenario: Relay is not blamed

• WHEN a relayed address fails swarm connection
• THEN the immediate overlay relay is not treated as author

Scenario: Attacker grinds lexical address order

• WHEN an overlay response contains many addresses chosen to sort before an honest candidate
• THEN the client shuffles the complete bounded fresh tier with OsRng before resolution/dial selection, so lexical order does not choose the budget

Scenario: Previously compatible tier is large

• WHEN persisted compatible peers exceed their retry limit
• THEN the bounded full index is shuffled, a subset consumes at most half the attempt budget and first half of dial time, and fresh overlay candidates retain the remainder

Scenario: Ordered lookup exceeds candidate capacity

• WHEN terminal-bounded lookup returns more URLs than the candidate cap
• THEN bounded CSPRNG reservoir sampling covers every URL returned through terminal completion or the 16-page cap instead of taking its lexical prefix

Requirement: Metadata disclosure and identity scoping are explicit

Wire messages MUST NOT intentionally bind different swarms to one stable node or signing identity. Durable state MUST NOT contain querier identity or query history. An answering peer nevertheless observes the requested ID; requests on one channel are linkable; timing, topology, public enumeration, and endpoint reuse are metadata surfaces. The capability MUST NOT claim PIR, guaranteed origin anonymity, absence of remote traces, or global-observer resistance.

Gossip and store peers necessarily observe and MAY retain every swarm-ID to advertised-endpoint mapping they receive. The forbidden provenance association is a mapping from overlay source peer to swarm/ad authorship; the rendezvous ID-to-endpoint mapping is intentional protocol output and is not confidential.

Every overlay and swarm P2p instance SHALL use an independently CSPRNG- generated VersionMessage.node_id; it MUST NOT be persisted or reused across instances, swarms, overlay/swarm roles, or process restart.

Serving documentation SHALL identify endpoint reuse as directly linkable and SHALL NOT claim automatic independent Tor/I2P provisioning.

Scenario: Query disclosure is documented

• WHEN a lookup for S is issued
• THEN documentation states the answering peer observes S

Scenario: Overlay and swarm version identities

• WHEN one process starts an overlay and one or more swarm P2p instances
• THEN their version node IDs are independently generated and unequal

Scenario: Shared endpoint is linkable

• WHEN one endpoint is advertised for two swarms
• THEN guidance identifies the direct link and makes no contrary claim