diff --git a/content/p2p/ift/2026q2-nimlibp2p-kad-dht-optimizations.md b/content/p2p/ift/2026q2-nimlibp2p-kad-dht-optimizations.md new file mode 100644 index 0000000000..683be14bd8 --- /dev/null +++ b/content/p2p/ift/2026q2-nimlibp2p-kad-dht-optimizations.md @@ -0,0 +1,77 @@ +--- + +title: nim-libp2p Kad-DHT Optimizations +tags: + - "2026q2" + - "p2p" + - "ift" +draft: false +description: Improve Kad-DHT privacy and provider record advertisement behavior + +--- + +`ift-ts:p2p:ift:2026q2-nimlibp2p-kad-dht-optimizations` + +Improve nim-libp2p Kad-DHT privacy and provider record advertisement behavior. + +## Description + +This commitment covers two related Kad-DHT improvements. First, Kad-DHT response +messages should avoid disclosing peer connection type because it can reveal +network topology and increase eclipse-attack risk. This follows +[vacp2p/nim-libp2p#2050](https://github.com/vacp2p/nim-libp2p/issues/2050) +and the Logos extended Kad discovery privacy requirement that every Kad-DHT +`Peer.connection` field be encoded as `NOT_CONNECTED`. + +Second, provider record advertisement traffic can overload nodes close to +popular content. The libp2p community has discussed Coral-style rejection, +spillover, and backtracking for provider records in +[libp2p/specs#163](https://github.com/libp2p/specs/issues/163), and +[go-libp2p-kad-dht#345](https://github.com/libp2p/go-libp2p-kad-dht/issues/345) +tracks these as part of the critical path toward DHT efficiency and +performance. This commitment brings equivalent optimization work to the +nim-libp2p Kad-DHT implementation. + +## Task List + +### Kad-DHT Connection Field Privacy + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-kad-dht-optimizations:connection-field-privacy` +* owner: gabe +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Ensure Kad-DHT response messages can optionally not disclose local connection information. +When encoding Kad-DHT `Peer` records, set the `connection` field to +`NOT_CONNECTED`. Maintain backward compatibility by continuing to parse peers +that send other `ConnectionType` values. + +#### Deliverables +- Kad-DHT encoder always emits `NOT_CONNECTED` for peer connection type depending on kademlia setup option +- Receive-side compatibility for non-compliant peers +- Tests covering encoding and parsing of `ConnectionType` values +- Documentation of the privacy behavior and compatibility policy + + +### Provider Record Spillover + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-kad-dht-optimizations:provider-record-spillover` +* owner: gabe +* status: not started +* start-date: 2026/04/01 +* end-date: 2026/06/30 + +#### Description +Add provider record overload protection and advertisement spillover behavior. +Provider records should have local limits and throttling, and rejected +advertisements should be able to spill over by backtracking through the lookup +path rather than repeatedly targeting only the closest nodes to a popular key. + +#### Deliverables +- Configurable provider record limits and throttling policy +- Rejection response handling for provider advertisements +- Spillover/backtracking behavior for popular provider records +- Metrics or simulation coverage showing advertisement load distribution +- Tests for provider record limits, rejection, spillover, and lookup behavior diff --git a/content/p2p/ift/2026q2-nimlibp2p-maintenance.md b/content/p2p/ift/2026q2-nimlibp2p-maintenance.md index 62c872acaf..0b95546773 100644 --- a/content/p2p/ift/2026q2-nimlibp2p-maintenance.md +++ b/content/p2p/ift/2026q2-nimlibp2p-maintenance.md @@ -262,3 +262,48 @@ Some related work available is: - Agreed technical direction for `logos-delivery#3634` - Ownership decision between nim-libp2p and the relevant dependent components - Follow-up issue or PR breakdown, including Chronos work if needed + + +### Large RSA key limit + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-maintenance:large-rsa-key-limit` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Fix [vacp2p/nim-libp2p#1327](https://github.com/vacp2p/nim-libp2p/issues/1327) +by rejecting RSA keys that are too large to parse or verify safely. This should +protect nodes from resource exhaustion attacks where a malicious peer sends an +oversized RSA key and forces expensive signature verification. Use the +go-libp2p fix in +[libp2p/go-libp2p#2454](https://github.com/libp2p/go-libp2p/pull/2454) as +guidance, including the `<= 8192` bit maximum. + +#### Deliverables +- Maximum RSA key size enforced during key parsing and generation +- Tests for accepted RSA keys and rejected oversized RSA keys +- Documentation or changelog note describing the compatibility/security behavior + + +### Sink performance exploration + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-maintenance:sink-performance-exploration` +* owner: richard +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Explore using Nim `sink` parameters in internal code paths where ownership +transfer can reduce unnecessary copies and improve memory performance. This is +tracked in +[vacp2p/nim-libp2p#1641](https://github.com/vacp2p/nim-libp2p/issues/1641). +Maintain backward compatibility for public APIs. + +#### Deliverables +- Benchmarked list of candidate internal hot paths +- PRs applying `sink` where the ownership semantics are clear and beneficial +- Tests or benchmarks showing no behavioral regression +- No public API break. diff --git a/content/p2p/ift/2026q2-nimlibp2p-nat-traversal.md b/content/p2p/ift/2026q2-nimlibp2p-nat-traversal.md new file mode 100644 index 0000000000..e6350583da --- /dev/null +++ b/content/p2p/ift/2026q2-nimlibp2p-nat-traversal.md @@ -0,0 +1,69 @@ +--- + +title: nim-libp2p NAT Traversal +tags: + - "2026q2" + - "p2p" + - "ift" +draft: false +description: Add reusable NAT traversal address setup to nim-libp2p + +--- + +`ift-ts:p2p:ift:2026q2-nimlibp2p-nat-traversal` + +Add reusable NAT traversal and public address setup support to nim-libp2p. + +## Description + +nim-libp2p has long tracked NAT traversal support in +[vacp2p/nim-libp2p#51](https://github.com/vacp2p/nim-libp2p/issues/51). +Downstream users already carry NAT address setup logic, including a configuration +option with `any`, `none`, `upnp`, `pmp`, and `extip:` modes, +and Nimbus code that calls `setupAddress(config.nat, ...)` for TCP and UDP +ports. This commitment extracts the reusable behavior into nim-libp2p so +applications can configure public address discovery and port mapping through +the library instead of duplicating efforts downstream. + +## Task List + +### NAT Address Setup API + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-nat-traversal:address-setup-api` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Provide a reusable nim-libp2p API and builder/config integration for NAT public +address setup. The API should support the downstream modes already used by +Logos and Nimbus: automatic discovery, disabled NAT setup, UPnP, NAT-PMP, and +explicit external IP configuration. + +#### Deliverables +- Builder/config option for NAT address setup +- Support for `any`, `none`, `upnp`, `pmp`, and `extip:` modes or equivalent typed configuration +- Public address and mapped port results exposed to transport/listen address handling +- Tests for mode parsing, explicit external IP handling, and disabled NAT setup + + +### UPnP and NAT-PMP Integration + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-nat-traversal:upnp-pmp` +* owner: not assigned yet +* status: not started +* start-date: 2026/04/01 +* end-date: 2026/06/30 + +#### Description +Integrate UPnP and NAT-PMP address mapping through existing Nim NAT traversal +libraries where possible, reusing the behavior already proven by downstream +projects. The implementation should work for nim-libp2p TCP usage and be +structured so UDP-capable transports can use the same setup path. + +#### Deliverables +- UPnP and NAT-PMP mapping support available from nim-libp2p +- Address propagation into identify/listen address reporting where applicable +- Downstream migration guidance for Logos and Nimbus NAT configuration +- Tests or examples covering mapped TCP address advertisement diff --git a/content/p2p/ift/2026q2-nimlibp2p-stream-budgets.md b/content/p2p/ift/2026q2-nimlibp2p-stream-budgets.md new file mode 100644 index 0000000000..fdd72945f9 --- /dev/null +++ b/content/p2p/ift/2026q2-nimlibp2p-stream-budgets.md @@ -0,0 +1,118 @@ +--- + +title: nim-libp2p Stream Budgets +tags: + - "2026q2" + - "p2p" + - "ift" +draft: false +description: Per-protocol stream budgets in nim-libp2p + +--- + +`ift-ts:p2p:ift:2026q2-nimlibp2p-stream-budgets` + +Add opt-in per-protocol stream budgets to nim-libp2p so stream-count abuse can be rejected before a protocol handler is overloaded. + +## Description + +nim-libp2p currently exposes `LPProtocol.maxIncomingStreams` as an inbound +per-peer limit for a protocol, but it does not provide a complete budget model +for total inbound streams, outbound streams, or protocol-wide stream pressure. +This leaves protocol handlers vulnerable to overload when one peer or many +peers consume too much stream capacity. + +This commitment extends the existing `LPProtocol.maxIncomingStreams` model into +a small per-protocol stream budget matrix. The work should keep the V1 scope +narrow: it limits stream counts only, does not attempt memory accounting, idle +time tracking, or peer reputation, and keeps new limits opt-in unless a separate +compatibility decision changes existing defaults. + +## Task List + +### Budget API And Accounting + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-stream-budgets:budget-api` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Extend `LPProtocol` with stream budget settings for inbound total streams, +outbound per-peer streams, and outbound total streams, while preserving +`maxIncomingStreams` as the existing inbound per-peer cap. Track open stream +counters per mounted protocol handler, direction, and peer where per-peer caps +need it. If one protocol handler exposes multiple compatible codec strings, all +compatible codec strings should share the same budget. + +#### Deliverables +- `maxTotalIncomingStreams`, `maxOutgoingStreams`, and `maxTotalOutgoingStreams` + added to `LPProtocol` +- Existing `maxIncomingStreams` behavior preserved as the inbound per-peer cap +- Open stream accounting scoped by mounted protocol handler and direction +- Shared budget behavior for compatible codec strings mounted by the same protocol handler + + +### Inbound Stream Enforcement + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-stream-budgets:inbound-enforcement` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Enforce inbound per-peer and total protocol caps in the multistream accept path +after protocol negotiation, next to the existing `maxIncomingStreams` check. On +breach, reject or close the new stream while keeping the peer connection open. +Counters must be decremented on clean close, error close, connection drop, +handler crash, and muxer close paths. + +#### Deliverables +- Inbound per-peer stream limit enforced through the existing `maxIncomingStreams` path +- Inbound total stream limit enforced per mounted protocol handler +- Rejection behavior that closes only the new stream and keeps the connection up +- Tests covering clean close, error close, connection drop, handler crash, and muxer close + + +### Outbound Stream Enforcement + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-stream-budgets:outbound-enforcement` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Enforce outbound per-peer and total protocol caps after outbound protocol +negotiation, because the muxer and connection manager stream-open path does not +know which protocol will be selected before negotiation completes. Failed +negotiation, cancellation, stream close or reset, and muxer close must roll back +any counter reservation. + +#### Deliverables +- Outbound per-peer stream limit enforced after protocol negotiation +- Outbound total stream limit enforced per mounted protocol handler +- Counter rollback for negotiation failure, cancellation, stream close/reset, and muxer close +- Tests covering outbound negotiation failure and outbound cancellation + + +### Metrics And Validation + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-stream-budgets:metrics-validation` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Expose protocol stream budget metrics and validate the feature against overload +and lifecycle scenarios. Metrics should include protocol, direction, and scope +labels where useful, but should not add a per-peer label. + +#### Deliverables +- `libp2p_protocol_stream_cap_rejections_total{protocol, direction, scope}` metric +- `libp2p_protocol_streams_open{protocol, direction}` metric +- Integration tests for inbound and outbound cap breaches +- Documentation describing the opt-in V1 behavior and compatibility expectations diff --git a/content/p2p/ift/2026q2-nimlibp2p-stream-connection-refactor.md b/content/p2p/ift/2026q2-nimlibp2p-stream-connection-refactor.md new file mode 100644 index 0000000000..fb4eaec994 --- /dev/null +++ b/content/p2p/ift/2026q2-nimlibp2p-stream-connection-refactor.md @@ -0,0 +1,55 @@ +--- + +title: nim-libp2p Stream and Connection Refactor +tags: + - "2026q2" + - "p2p" + - "ift" +draft: false +description: Refactor nim-libp2p stream and connection abstractions + +--- + +`ift-ts:p2p:ift:2026q2-nimlibp2p-stream-connection-refactor` + +Refactor nim-libp2p stream and connection abstractions so peer connections and protocol streams are represented by distinct types. + +## Description + +The current nim-libp2p implementation uses `Connection` both for actual peer +connections and for streams opened over multiplexed connections. In the current +code shape `Connection` inherits from `LPStream`, muxers return `Connection` +from `newStream`, and protocol handlers receive `Connection` even when they are +handling a single protocol stream. This makes the abstraction harder to +understand, increases the cost of onboarding contributors, and complicates +resource lifecycle work such as close/reset behavior and stream ownership. + +This commitment separates the concepts so `Connection` refers to peer-level +connections and a new stream abstraction is used for protocol streams. The +refactor should preserve downstream compatibility during the migration and +reduce ambiguity in code, tests, metrics, and documentation. + +## Task List + +### Stream and Connection Abstractions + +* fully qualified name: `ift-ts:p2p:ift:2026q2-nimlibp2p-stream-connection-refactor:abstractions` +* owner: not assigned yet +* status: not started +* start-date: 2026/05/01 +* end-date: 2026/06/30 + +#### Description +Introduce a clear stream abstraction for protocol streams and narrow +`Connection` to represent actual peer connections. Update muxer and connection +manager interfaces so opening a stream returns the stream type, while peer-level +connection state remains on connection objects. + + +#### Deliverables +- New stream-level abstraction used by muxers and protocol handlers +- `Connection` narrowed to peer-level connection state and behavior +- Compatibility shims or migration aliases for existing downstream users +- Updated close/reset lifecycle behavior for streams and connections +- Tests covering stream creation, close/reset semantics, and protocol handler usage +- Documentation and examples using the new names consistently diff --git a/content/p2p/index.md b/content/p2p/index.md index 789ba66940..05994fe352 100644 --- a/content/p2p/index.md +++ b/content/p2p/index.md @@ -21,8 +21,12 @@ Major future work items on nim-libp2p (also beyond this reporting period are cap * [[p2p/ift/2026q2-nimlibp2p-cbindings|nimlibp2p-cbindings]] * [[p2p/ift/2026q2-nimlibp2p-connection-management|nimlibp2p-connection-management]] * [[p2p/ift/2026q2-nimlibp2p-gossipsub-queues|nimlibp2p-gossipsub-queues]] +* [[p2p/ift/2026q2-nimlibp2p-kad-dht-optimizations|nimlibp2p-kad-dht-optimizations]] * [[p2p/ift/2026q2-nimlibp2p-logos-core|nimlibp2p-logos-core]] * [[p2p/ift/2026q2-nimlibp2p-maintenance|nimlibp2p-maintenance]] +* [[p2p/ift/2026q2-nimlibp2p-nat-traversal|nimlibp2p-nat-traversal]] +* [[p2p/ift/2026q2-nimlibp2p-stream-budgets|nimlibp2p-stream-budgets]] +* [[p2p/ift/2026q2-nimlibp2p-stream-connection-refactor|nimlibp2p-stream-connection-refactor]] ## 2026q1 `ift-ts:p2p:` @@ -94,5 +98,3 @@ Major future work items on nim-libp2p (also beyond this reporting period are cap #### `acz:` * [[p2p/acz/2025q1-acz-consulting|2025q1-acz-consulting]] - -