From a0bae94facde871ca0c9e605fc72a93a1fd5770b Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:49:12 +0100 Subject: [PATCH 1/7] Create Kip-0019.md initial commit. --- Kip-0019.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 Kip-0019.md diff --git a/Kip-0019.md b/Kip-0019.md new file mode 100644 index 0000000..9638158 --- /dev/null +++ b/Kip-0019.md @@ -0,0 +1,149 @@ +``` + KIP: XXXX + Layer: Routing, Networking, P2P, Node + Title: Inbound Peer Eviction Policy + Author: D-Stakes + Status: Draft + Created: 2026-01-07 +``` + +This document specifies a multi-metric, prefix-diversity-aware inbound peer eviction policy for Kaspa nodes. + +# Motivation + +When a node's inbound peer set exceeds its configured limit, it must disconnect peers. The current randomized eviction is vulnerable to eclipse attacks: a Sybil attacker can repeatedly request inbound connections, relying on random eviction to gradually replace honest peers. + +While a node's outbound connections remain the primary defense against eclipse attacks, a sophisticated eviction policy for inbound peers increases overall resilience. + +This policy is inspired by Bitcoin Core's eviction approach: protect peers with diverse, difficult-to-forge characteristics, and evict based on non-latency performance metrics. + +**Goals:** +- Reduce the probability that one entity dominates a node's inbound peer set +- Maintain diversity across network locations via IP prefix bucketing +- Prefer stable, long-connected peers +- Prefer peers that contribute blocks/transactions +- Avoid systematically excluding geographically distant peers + +# Specification + +## Definitions + +- **Inbound limit** (`L`): Maximum allowed inbound peers +- **Active inbound set** (`P`): Current inbound peers, with size `N = |P|` +- **Overflow**: `max(0, N - L)` — when positive, exactly this many peers must be evicted + +## Peer Attributes + +For each inbound peer `p`, the node tracks: + +| Attribute | Description | +|-----------|-------------| +| `uptime(p)` | Duration since connection | +| `ping(p)` | Most recent ping RTT | +| `block_ts(p)` | Last block transfer timestamp (optional) | +| `tx_ts(p)` | Last transaction transfer timestamp (optional) | +| `bucket(p)` | IP prefix bucket | + +## Prefix Buckets + +Each peer is assigned a bucket derived from its IP address: + +- **IPv4**: First two octets (`/16` prefix) +- **IPv6**: First eight octets (`/64` prefix) +- **IPv4-mapped IPv6**: Use IPv4 rule + +The node computes `count[b]` — the number of peers in each bucket — per eviction cycle. + +## Metrics + +Peers are ranked on five metrics. Lower rank = better. Ties share the average rank. + +| Metric | Preference | Rank rule | +|--------|------------|-----------| +| Prefix concentration | Sparse buckets | Higher `count[bucket(p)]` → worse rank | +| Uptime | Longer | Shorter `uptime(p)` → worse rank | +| Ping RTT | Lower | Higher `ping(p)` → worse rank | +| Block transfer | Recent | Missing or older `block_ts(p)` → worse rank | +| Transaction transfer | Recent | Missing or older `tx_ts(p)` → worse rank | + +## Classification + +**Latency-correlated metrics:** ping, block transfer, transaction transfer + +**Non-latency metrics:** uptime, prefix concentration + +## Eviction Procedure + +### Stage 1: Protected Set + +Protect the top 40% of peers (by inbound limit): + +``` +retain_count = floor(L * 0.4) +``` + +Each peer's "best rank" is the minimum across all five metrics: + +``` +best(p) = min(rank_bucket, rank_uptime, rank_ping, rank_block, rank_tx) +``` + +Sort peers by ascending `best(p)`, breaking ties randomly. The first `retain_count` peers are protected and cannot be evicted. + +### Stage 2: Weighted Random Eviction + +From the remaining unprotected peers, evict exactly `N - L` peers using weighted random sampling without replacement. + +The weight uses only non-latency metrics: + +``` +worst_non_latency(p) = max(rank_uptime, rank_bucket) +weight(p) = 1 + worst_non_latency(p) +``` + +Higher weight → more likely to be evicted. + +## Eviction Action + +Selected peers are disconnected immediately. + +# Rationale + +**Multi-signal protection:** Protecting peers exceptional in *any* dimension limits attackers who can only optimize one metric cheaply. + +**Prefix diversity:** Biasing eviction toward crowded buckets maintains geographic and ownership diversity. + +**Non-latency eviction weights:** Using only uptime and bucket concentration for eviction weighting avoids penalizing high-latency but otherwise valuable peers, while pressuring connection spam and prefix concentration. + +**Random tie-breaking:** Reduces predictability and information leakage. + +# Security Considerations + +A Sybil attacker must simultaneously: +1. Establish nodes with good ping (geographic proximity) +2. Position near block producers and transaction sources +3. Maintain long uptime toward the target +4. Disperse connections across multiple IP prefixes + +The probabilistic eviction of unprotected peers makes connection spam self-defeating. + +**Limitations:** +- Prefix saturation attacks can increase churn for honest peers in the same prefix +- Prefix buckets are an imperfect proxy; attackers with diverse address space may still cluster + +# Backwards Compatibility + +This policy changes behavior only when inbound connections exceed the limit. No protocol changes required. + +# Disclaimer + +This KIP was partially AI-generated, then expanded and edited by a human. + +# Reference Implementation + +[kaspanet/rusty-kaspa#431](https://github.com/kaspanet/rusty-kaspa/pull/431) + +# References + +- Heilman et al., "Eclipse Attacks on Bitcoin's Peer-to-Peer Network", USENIX Security 2015 +- Bitcoin Core eviction: [src/node/eviction.cpp](https://github.com/bitcoin/bitcoin/blob/master/src/node/eviction.cpp) From f49a89914a4cd827d4399c263026fdad5d962009 Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 14:56:12 +0100 Subject: [PATCH 2/7] Update KIP number to 0019 --- Kip-0019.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Kip-0019.md b/Kip-0019.md index 9638158..c4dc163 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -1,5 +1,5 @@ ``` - KIP: XXXX + KIP: 0019 Layer: Routing, Networking, P2P, Node Title: Inbound Peer Eviction Policy Author: D-Stakes From 6200b8747114191aa64b6ac968783b56e3651393 Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 15:18:31 +0100 Subject: [PATCH 3/7] Revise peer selection and security considerations in KIP-0019 Updated KIP-0019 to refine peer selection criteria and clarify security considerations. --- Kip-0019.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/Kip-0019.md b/Kip-0019.md index c4dc163..7f20dc8 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -22,7 +22,7 @@ This policy is inspired by Bitcoin Core's eviction approach: protect peers with - Maintain diversity across network locations via IP prefix bucketing - Prefer stable, long-connected peers - Prefer peers that contribute blocks/transactions -- Avoid systematically excluding geographically distant peers +- Avoid systematically excluding disadvantaged high-latency peers # Specification @@ -90,6 +90,8 @@ best(p) = min(rank_bucket, rank_uptime, rank_ping, rank_block, rank_tx) Sort peers by ascending `best(p)`, breaking ties randomly. The first `retain_count` peers are protected and cannot be evicted. +**Note:** due to the nature of ranking this min, and sorting, implictly diversifies the metrics used. + ### Stage 2: Weighted Random Eviction From the remaining unprotected peers, evict exactly `N - L` peers using weighted random sampling without replacement. @@ -119,13 +121,17 @@ Selected peers are disconnected immediately. # Security Considerations +**Stage 1** A Sybil attacker must simultaneously: 1. Establish nodes with good ping (geographic proximity) 2. Position near block producers and transaction sources 3. Maintain long uptime toward the target 4. Disperse connections across multiple IP prefixes -The probabilistic eviction of unprotected peers makes connection spam self-defeating. +**Stage 2** +A Sybil / Spam attacker wishing to establish connections: +1. Will probablistically evict one of his own connections by weighting uptime, +2. Requires diverse Ip bucketing to not probablistically evict one of his own connections. **Limitations:** - Prefix saturation attacks can increase churn for honest peers in the same prefix @@ -137,7 +143,7 @@ This policy changes behavior only when inbound connections exceed the limit. No # Disclaimer -This KIP was partially AI-generated, then expanded and edited by a human. +This KIP was partially AI-generated. # Reference Implementation From 3704e11fb8df33c068e056f98d554f4e31e5d376 Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 15:22:52 +0100 Subject: [PATCH 4/7] Update note on ranking and metrics in Kip-0019 Clarify note on ranking and metrics diversification. --- Kip-0019.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Kip-0019.md b/Kip-0019.md index 7f20dc8..f06ae95 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -90,7 +90,7 @@ best(p) = min(rank_bucket, rank_uptime, rank_ping, rank_block, rank_tx) Sort peers by ascending `best(p)`, breaking ties randomly. The first `retain_count` peers are protected and cannot be evicted. -**Note:** due to the nature of ranking this min, and sorting, implictly diversifies the metrics used. +**Note:** Due to the nature of ranked variables not being duplicatable (beyond tie breaking), The min function and sorting used here implictly diversifies the metrics used. ### Stage 2: Weighted Random Eviction From c4ab4cea9e8625e38b6dc8bff9e923434459e5ad Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 16:57:17 +0100 Subject: [PATCH 5/7] Clarify inbound peer eviction policy for Kaspa nodes Revised the inbound peer eviction policy document for clarity and precision, including updates to the goals and specifications sections. --- Kip-0019.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Kip-0019.md b/Kip-0019.md index f06ae95..2323621 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -7,22 +7,23 @@ Created: 2026-01-07 ``` -This document specifies a multi-metric, prefix-diversity-aware inbound peer eviction policy for Kaspa nodes. +This document specifies an inbound peer eviction policy and logic for Kaspa nodes. # Motivation When a node's inbound peer set exceeds its configured limit, it must disconnect peers. The current randomized eviction is vulnerable to eclipse attacks: a Sybil attacker can repeatedly request inbound connections, relying on random eviction to gradually replace honest peers. -While a node's outbound connections remain the primary defense against eclipse attacks, a sophisticated eviction policy for inbound peers increases overall resilience. +While a node's outbound connections remain the primary defense against eclipse attacks, a sophisticated eviction policy for inbound peers can increase overall resilience. This policy is inspired by Bitcoin Core's eviction approach: protect peers with diverse, difficult-to-forge characteristics, and evict based on non-latency performance metrics. **Goals:** - Reduce the probability that one entity dominates a node's inbound peer set -- Maintain diversity across network locations via IP prefix bucketing +- Maintain diversity across network locations utilizing IP prefix bucketing - Prefer stable, long-connected peers - Prefer peers that contribute blocks/transactions - Avoid systematically excluding disadvantaged high-latency peers +- Slow-down connection spamming success-rates. # Specification @@ -42,7 +43,7 @@ For each inbound peer `p`, the node tracks: | `ping(p)` | Most recent ping RTT | | `block_ts(p)` | Last block transfer timestamp (optional) | | `tx_ts(p)` | Last transaction transfer timestamp (optional) | -| `bucket(p)` | IP prefix bucket | +| `bucket(p)` | IP prefix bucket | ## Prefix Buckets @@ -66,6 +67,8 @@ Peers are ranked on five metrics. Lower rank = better. Ties share the average ra | Block transfer | Recent | Missing or older `block_ts(p)` → worse rank | | Transaction transfer | Recent | Missing or older `tx_ts(p)` → worse rank | +**note:** Considering kaspa's high throughput raw last transfered `block_ts` and `tx_ts`, may not be an ideal metric, potentially using averages, or counts, may be a better metric. none-the-less `last transfer`, is easy and cheap to implement and track, and should at the very least act as a proxy for closeness to tx / block producing parts of the network. But alternatives may be considered here. + ## Classification **Latency-correlated metrics:** ping, block transfer, transaction transfer @@ -115,7 +118,7 @@ Selected peers are disconnected immediately. **Prefix diversity:** Biasing eviction toward crowded buckets maintains geographic and ownership diversity. -**Non-latency eviction weights:** Using only uptime and bucket concentration for eviction weighting avoids penalizing high-latency but otherwise valuable peers, while pressuring connection spam and prefix concentration. +**Non-latency eviction weights:** Using only uptime and bucket concentration for eviction weighting avoids penalizing high-latency, but otherwise valuable, peers, while pressuring connection spam and prefix concentration. **Random tie-breaking:** Reduces predictability and information leakage. From f2c5b470b12f3caaccda6febd8bc94d62675ed80 Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 19:49:56 +0100 Subject: [PATCH 6/7] Enhance security considerations and eviction policies Expanded security considerations for Sybil and spam attacks, detailing stages and statistical analysis of connection eviction policies. --- Kip-0019.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/Kip-0019.md b/Kip-0019.md index 2323621..01fef96 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -124,21 +124,36 @@ Selected peers are disconnected immediately. # Security Considerations -**Stage 1** -A Sybil attacker must simultaneously: +## Pros: + +**Stage 1:** Protect a diverse set of peers, accross different metrics 1. Establish nodes with good ping (geographic proximity) 2. Position near block producers and transaction sources 3. Maintain long uptime toward the target 4. Disperse connections across multiple IP prefixes -**Stage 2** -A Sybil / Spam attacker wishing to establish connections: -1. Will probablistically evict one of his own connections by weighting uptime, -2. Requires diverse Ip bucketing to not probablistically evict one of his own connections. +**Result** + +To eclipse protected peers, an adversary must carefully construct an artificial network around the target node — one that mimics and ultimately outperforms the strongest participants in a natural Gaussian distribution, on a wide array of independent variables. + +**Stage 2:** Connection Spam Resistance + +Preliminary statistical analysis conducted also demonstrates the effectiveness of this defense. For an unprotected peer set of 77 peers (corresponding to an inbound limit of 128 peers), assuming heterogeneous prefix distribution and consecutive uptime ranks: + +| Eviction Policy | Mean Attempts to Replace All Peers | First-Attempt Self-Eviction Rate | +|-----------------|-----------------------------------|----------------------------------| +| Random eviction | 379.4 | 1.3% | +| Weighted eviction (this KIP) | 2,248 | 2.5% | + +**Result** + +- The weighted eviction policy requires approximately **6× more connection attempts** for an adversary to replace all unprotected peers +- The self-eviction rate for honest peers (i.e. on first attempt eviction) increases only marginally (from 1.3% to 2.5%) **2x more liklyhood** +- Furthermore, without diverse IP prefix bucketing, attackers will probabilistically evict their own connections with even more liklyhood, making sustained spam attacks significantly more resource-intensive + +## Cons -**Limitations:** -- Prefix saturation attacks can increase churn for honest peers in the same prefix -- Prefix buckets are an imperfect proxy; attackers with diverse address space may still cluster +- Prefix saturation attacks can increase churn and decrease connection availability for honest peers in the same prefix, i.e. instead of targeting the node directly, an adversary can try and establish a large amount of nodes within the same prefix as a target, thereby making it more difficult for the target to gain reliable access to the network. This might particularly be problematic for prefixes belonging to known hosting providers, where it becomes easy to establish oneself in the same prefix. # Backwards Compatibility From dd12e6b689a4de571363dcd74f473162327b78e7 Mon Sep 17 00:00:00 2001 From: D-Stacks <78099568+D-Stacks@users.noreply.github.com> Date: Wed, 7 Jan 2026 20:21:47 +0100 Subject: [PATCH 7/7] Enhance KIP-0019 with spam protection details Added note on fine-tuning spam protection mechanism. --- Kip-0019.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Kip-0019.md b/Kip-0019.md index 01fef96..4b3e7e4 100644 --- a/Kip-0019.md +++ b/Kip-0019.md @@ -151,6 +151,8 @@ Preliminary statistical analysis conducted also demonstrates the effectiveness o - The self-eviction rate for honest peers (i.e. on first attempt eviction) increases only marginally (from 1.3% to 2.5%) **2x more liklyhood** - Furthermore, without diverse IP prefix bucketing, attackers will probabilistically evict their own connections with even more liklyhood, making sustained spam attacks significantly more resource-intensive +**Note:** By multiplying these weights by some multiplier, this mechnisim can be fine tuned to increase, or decrease spam protection, which potentially can be used to fine-tune this mechanisim, for example when the node "thinks" it is under a spam attack. + ## Cons - Prefix saturation attacks can increase churn and decrease connection availability for honest peers in the same prefix, i.e. instead of targeting the node directly, an adversary can try and establish a large amount of nodes within the same prefix as a target, thereby making it more difficult for the target to gain reliable access to the network. This might particularly be problematic for prefixes belonging to known hosting providers, where it becomes easy to establish oneself in the same prefix.