Documentation

Handle a batch of txids received from one peer.

Newly seen txids are interned, appended to the peer's unacknowledged queue, and entered into the shared tx table as claimable work. Any peer that later advertises the txid may claim it once its score-derived delay has elapsed, which avoids pinning fresh work to the first peer that happened to announce it.

Handle a batch of tx bodies received from one peer.

Received bodies are buffered locally in the peer state. Bodies that are already retained or already in the mempool are counted as late and dropped. Any requested tx omitted from the reply releases this peer's ownership. Late TXs contributes to the returned penalty count.

Handle the result of submitting buffered txs to the mempool.

Accepted txs leave the active table and move into the retained set so later txid advertisements can be acknowledged without re-requesting the body. Txs rejected by the mempool release this peer's lease and clear txInSubmission so another advertiser may try later.

Mark buffered txs as entering mempool submission.

Decrements txAttempt (the peer is leaving the attempting state) and sets txInSubmission. STM serialisation around the ChooseSubmit choice guarantees only one peer ever flips txInSubmission from False to True for a given key.

Bumps only sharedRevision (the structural dirty bit), not sharedGeneration (the wake counter). This transition only removes options for other peers (they may no longer claim or submit the key) and does not enable any new ack - that happens on the subsequent handleSubmittedTxs acceptance, which bumps the wake counter itself.

Compute the next peer-local action.

Pipelined version of nextPeerAction

Compute the current usefulness score for a peer after time-based decay.

Scores drain at scoreRate (txs/second) from the last update timestamp. Returns zero for peers whose accumulated rejections have fully decayed.

Decay the peer's score to now, updating the timestamp.

Fast path: a score that is already 0 stays 0, and the stale peerScoreTs is harmless because currentPeerScore short-circuits on peerScoreValue == 0 without reading the timestamp, while any later applyPeerEvents transition to a positive score overwrites peerScoreTs with the current now. Return the state unchanged.

Compute the peer's score-derived claim delay.

A peer with a fully drained score has no delay. Any non-zero score maps to a delay in [10 ms, maxPeerClaimDelay]: the linear interpolation saturates when the score reaches scoreMax, and the 10 ms floor ensures even a small accumulated score meaningfully nudges race outcomes against the peer rather than being swallowed by jitter.

Apply a batch of accept/reject events to the peer's local score. Drains the score by elapsed time at scoreRate, then adds the rejection count and subtracts scoreAcceptDecrement per accept; clamps to [0, scoreMax]. Returns the new score value (for tracing) and the updated local state.

Shared-state cleanup

Drops three kinds of dead entries in one pass:

• Retained entries whose retention deadline has passed. Only the sharedRetainedTxs membership is removed; the txid lookup tables (sharedTxIdToKey, sharedKeyToTxId) are preserved here because peers may still hold the key in peerUnacknowledgedTxIds until they ack it.
• Orphaned sharedTxTable entries: entries with a released lease, no in-flight attempt, and no live peer still tracking the key. These are safe to fully tear down (lookup tables included): by definition no peer references them.
• Stale lookup-table entries: keys present only in sharedTxIdToKey / sharedKeyToTxId with no peer still referencing them. Bounds the lookup tables so they don't grow unboundedly.

The liveReferences set is the union of every active peer's pifAdvertised and pifAcksPending, snapshotted by the caller in the same STM transaction as this function so it is coherent with the sharedTxTable read.

Bumps only sharedRevision (the structural dirty bit), not sharedGeneration (the wake counter). None of the three cleanup categories grant other peers new options: expired-retained drops and orphan removals never affect a referenced key, and stale-lookup removal doesn't touch any peer-visible state. Waking parked peers here would cost a full nextPeerAction pass per peer for nothing.