Next
diff --git a/docs/manual/whatis.html b/docs/manual/whatis.html
index b1085071..a397597a 100644
--- a/docs/manual/whatis.html
+++ b/docs/manual/whatis.html
@@ -218,7 +218,7 @@
Zen of Reticulum
Programs Using Reticulum
Using Reticulum on Your System
-
Protecting Open Networks
+
Protecting Open Networks
Understanding Reticulum
Communications Hardware
Configuring Interfaces
diff --git a/docs/manual/zen.html b/docs/manual/zen.html
index 001fbb60..f381d9b7 100644
--- a/docs/manual/zen.html
+++ b/docs/manual/zen.html
@@ -218,7 +218,7 @@
Zen of Reticulum
Programs Using Reticulum
Using Reticulum on Your System
-
Protecting Open Networks
+
Protecting Open Networks
Understanding Reticulum
Communications Hardware
Configuring Interfaces
diff --git a/docs/markdown/index.md b/docs/markdown/index.md
index 09ebdef2..02a37783 100644
--- a/docs/markdown/index.md
+++ b/docs/markdown/index.md
@@ -130,16 +130,17 @@ to participate in the development of Reticulum itself.
* [Improving System Configuration](using.md#improving-system-configuration)
* [Fixed Serial Port Names](using.md#fixed-serial-port-names)
* [Reticulum as a System Service](using.md#reticulum-as-a-system-service)
-* [Protecting Open Networks](stamps.md)
- * [Cryptographic Stamps](stamps.md#cryptographic-stamps)
- * [Base Primitives](stamps.md#base-primitives)
- * [On-Network Types](stamps.md#on-network-types)
- * [Configuring Stamps](stamps.md#configuring-stamps)
- * [Filtering & QoS](stamps.md#filtering-qos)
- * [Instance Configuration](stamps.md#id1)
- * [For Developers](stamps.md#id2)
- * [Blackhole Management](stamps.md#blackhole-management)
- * [Ingress & Burst Control](stamps.md#ingress-burst-control)
+* [Protecting Open Networks](protecting.md)
+ * [Cryptographic Stamps](protecting.md#cryptographic-stamps)
+ * [Base Primitives](protecting.md#base-primitives)
+ * [On-Network Types](protecting.md#on-network-types)
+ * [Configuring Stamps](protecting.md#configuring-stamps)
+ * [Filtering & QoS](protecting.md#filtering-qos)
+ * [Instance Configuration](protecting.md#id1)
+ * [For Developers](protecting.md#id2)
+ * [Ingress & Burst Control](protecting.md#ingress-burst-control)
+ * [Blackhole Management](protecting.md#blackhole-management)
+ * [Fast-Flap Blocking](protecting.md#fast-flap-blocking)
* [Understanding Reticulum](understanding.md)
* [Motivation](understanding.md#motivation)
* [Goals](understanding.md#goals)
diff --git a/docs/markdown/stamps.md b/docs/markdown/protecting.md
similarity index 78%
rename from docs/markdown/stamps.md
rename to docs/markdown/protecting.md
index 5303d6af..bd4f294c 100644
--- a/docs/markdown/stamps.md
+++ b/docs/markdown/protecting.md
@@ -76,28 +76,6 @@ Reticulum, and its included utilities, provide sane default cost requirements an
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the `[stamps]` section of the Reticulum configuration file:
-> * The `stamp_destinations` option enables generation and emission
-> of destination stamps in announces. This is a transitory option.
-> It will become mandatory and enabled by default in RNS `1.6.1`.
->
-> * The `stamp_prs` option enables stamping of path requests emitted
-> by this instance. This is a transitory option. It will become
-> mandatory and enabled by default in RNS `1.6.1`.
->
-> * The `always_stamp_lrs` option will stamp *all* outgoing link
-> requests, even to destinations that have not announced a link
-> request cost (and will, in that case, use the configured or
-> default link request cost). This option is mostly useful for
-> testing and diagnostics. In general use, Reticulum will handle
-> link request stamping and cost targets automatically.
->
-> * The `enforce_stamps` option allows early activation of stamp
-> enforcement. When enabled, announces and path requests that do
-> not meet the configured cost requirements are dropped, and link
-> requests with insufficient stamps are ignored. This is a transitory
-> option. It will become mandatory and enabled by default in RNS
-> `1.6.2`.
->
> * The `destination_cost` option sets the default required stamp
> cost for announced destinations to be accepted, and have their
> announces propagated by this node. Defaults to `23.5`.
@@ -131,6 +109,28 @@ In reality, different kinds of networks will want to configure different kinds o
> and the link request or path request fails. Defaults to `15`
> seconds for both options.
>
+> * The `stamp_destinations` option enables generation and emission
+> of destination stamps in announces. This is a transitory option.
+> It will become mandatory and enabled by default in RNS `1.6.1`.
+>
+> * The `stamp_prs` option enables stamping of path requests emitted
+> by this instance. This is a transitory option. It will become
+> mandatory and enabled by default in RNS `1.6.1`.
+>
+> * The `always_stamp_lrs` option will stamp *all* outgoing link
+> requests, even to destinations that have not announced a link
+> request cost (and will, in that case, use the configured or
+> default link request cost). This option is mostly useful for
+> testing and diagnostics. In general use, Reticulum will handle
+> link request stamping and cost targets automatically.
+>
+> * The `enforce_stamps` option allows early activation of stamp
+> enforcement. When enabled, announces and path requests that do
+> not meet the configured cost requirements are dropped, and link
+> requests with insufficient stamps are ignored. This is a transitory
+> option. It will become mandatory and enabled by default in RNS
+> `1.6.2`.
+>
An example of customised stamp cost and value configuration follows below:
@@ -289,10 +289,46 @@ RNS.Reticulum.get_instance().required_announces_only(True)
Your application will now only receive, and have to process, the announces and paths that it actually cares about.
-## Blackhole Management
-
-TODO: Short section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
-
## Ingress & Burst Control
-TODO: Short section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).
\ No newline at end of file
+In addition to the economic incentives created by stamps, Reticulum enforces a set of hydraulic limits on how much announce traffic any peer or destination can inject into the network. These mechanisms work automatically, require no operator configuration (but can be tuned, if required), and apply equally to all peers.
+
+At the most basic level, the `announce_cap` mechanism limits the bandwidth any interface will allocate to propagating announces and other network upkeep traffic, and prioritises the local topology. Destinations that rapidly re-announce are down-prioritised in the transmission queue, so attempting to gain reach through announce spam has the exact *opposite* effect.
+
+On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. A grace period allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
+
+The final layer protects against bursts of announces for *newly created* destinations. If an interface receives a large influx of announces for previously unknown destinations in a short amount of time, these are held in a bounded queue, while announces for known and established destinations continue to be processed without interruption. After the burst subsides, and an additional waiting period has passed, held announces are released slowly until the queue is cleared.
+
+A node that connects to a public interface, announces a large number of bogus destinations, and then disconnects, will therefore never get those destinations into path tables at all. When the interface they arrived on disappears, the held announces are simply dropped and forgotten.
+
+Ingress control operates at the level of individual sub-interfaces, so one misbehaving client cannot disrupt announce processing for other clients connected to the same listener. Combined with stamps, these mechanisms are complementary:
+
+Rate limiting bounds the *rate* at which abuse can occur, for everyone, while stamps make the *volume* of abuse from any actor computationally expensive.
+
+Full configuration details are available in the [Announce Rate Control](interfaces.md#interfaces-announcerates) and [New Destination Rate Limiting](interfaces.md#interfaces-ingress-control) sections.
+
+## Blackhole Management
+
+The *blackhole* system allows any node operator or individual user to block specific identities at the transport layer.
+
+Once an identity has been blackholed on a node, announces originating from *any* destination associated with that identity are dropped, and the node will refuse to transport traffic, or establish and maintain links, to the blackholed identity’s destinations.
+
+It is important to understand the scope of this mechanism corrrectly. There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. A blackhole entry only applies on the network segments that enforce it, which is the exact intention. Operators retain full control over what is allowed on their own segments, while no one can impose restrictions on segments they do not operate.
+
+Blackholes can be managed directly with the `rnpath` utility. Identities can be blocked (optionally with an expiry duration and a human-readable reason), unblocked, and the current local blocklist can be inspected at any time. This is well suited for immediate responses to announce spam, unwanted content or malicious behaviour observed on your own networks.
+
+For anything larger than a few nodes, manual blocklist maintenance quickly becomes impractical. Reticulum therefore allows an instance to subscribe to blackhole lists published by trusted transport identities, periodically retrieving and merging them into the local list, and conversely to publish its own list to subscribers.
+
+This makes it possible to federate community-maintained blocklists across large networks, with the important caveat that subscribing to a list is an act of trust in its maintainer. See the [Blackhole Management](using.md#using-blackhole-management) section for full details on local management, automated list sourcing and publishing.
+
+## Fast-Flap Blocking
+
+High-performance listener interfaces, such as [BackboneInterface](interfaces.md#interfaces-backbone), will automatically block *fast-flapping* clients; remote peers that repeatedly connect for a very short amount of time, and then disconnect.
+
+This behaviour usually stems from attempts to dump announce or path request spam onto the network in short bursts, while rotating connections in an attempt to evade per-interface rate limits, but it can also be caused by broken implementations or automated scanning tools.
+
+Such bypass attempts generally have very limited effect. Ingress limiters trigger *immediately* once rate limits are exceeded, but the behaviour still causes needless interface rotation and wasted resources on the transport instance.
+
+With fast-flap blocking enabled, a client that exceeds the allowed flap grace is simply not allocated an actual interface again, for the configured block duration.
+
+On the `BackboneInterface` type, fast-flap blocking is enabled by default, with sensible standard settings. All parameters can be adjusted if necessary. See the [Automated Blocking](interfaces.md#interfaces-fastflap) section of the Interfaces chapter.
\ No newline at end of file
diff --git a/docs/markdown/using.md b/docs/markdown/using.md
index 739635ae..896b2708 100644
--- a/docs/markdown/using.md
+++ b/docs/markdown/using.md
@@ -1331,7 +1331,7 @@ The blackhole system relies on the trust relationship between the subscriber and
As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
-For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
+For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative overhead.
## Improving System Configuration
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ab191427..53a25f88 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,7 +23,7 @@ to participate in the development of Reticulum itself.
zen
software
using
- stamps
+ protecting
understanding
hardware
interfaces
diff --git a/docs/source/interfaces.rst b/docs/source/interfaces.rst
index 403ad1d6..6a671813 100644
--- a/docs/source/interfaces.rst
+++ b/docs/source/interfaces.rst
@@ -230,6 +230,8 @@ specify the target Yggdrasil IPv6 address and port, like so:
target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
target_port = 4343
+.. _interfaces-fastflap:
+
Automated Blocking
------------------
Listener instances of ``BackboneInterface`` will automatically block fast-flapping clients,
diff --git a/docs/source/stamps.rst b/docs/source/protecting.rst
similarity index 78%
rename from docs/source/stamps.rst
rename to docs/source/protecting.rst
index dc61ed51..82a68893 100644
--- a/docs/source/stamps.rst
+++ b/docs/source/protecting.rst
@@ -91,28 +91,6 @@ Instance Configuration
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the ``[stamps]`` section of the Reticulum configuration file:
- * | The ``stamp_destinations`` option enables generation and emission
- of destination stamps in announces. This is a transitory option.
- It will become mandatory and enabled by default in RNS ``1.6.1``.
-
- * | The ``stamp_prs`` option enables stamping of path requests emitted
- by this instance. This is a transitory option. It will become
- mandatory and enabled by default in RNS ``1.6.1``.
-
- * | The ``always_stamp_lrs`` option will stamp *all* outgoing link
- requests, even to destinations that have not announced a link
- request cost (and will, in that case, use the configured or
- default link request cost). This option is mostly useful for
- testing and diagnostics. In general use, Reticulum will handle
- link request stamping and cost targets automatically.
-
- * | The ``enforce_stamps`` option allows early activation of stamp
- enforcement. When enabled, announces and path requests that do
- not meet the configured cost requirements are dropped, and link
- requests with insufficient stamps are ignored. This is a transitory
- option. It will become mandatory and enabled by default in RNS
- ``1.6.2``.
-
* | The ``destination_cost`` option sets the default required stamp
cost for announced destinations to be accepted, and have their
announces propagated by this node. Defaults to ``23.5``.
@@ -147,6 +125,28 @@ In reality, different kinds of networks will want to configure different kinds o
and the link request or path request fails. Defaults to ``15``
seconds for both options.
+ * | The ``stamp_destinations`` option enables generation and emission
+ of destination stamps in announces. This is a transitory option.
+ It will become mandatory and enabled by default in RNS ``1.6.1``.
+
+ * | The ``stamp_prs`` option enables stamping of path requests emitted
+ by this instance. This is a transitory option. It will become
+ mandatory and enabled by default in RNS ``1.6.1``.
+
+ * | The ``always_stamp_lrs`` option will stamp *all* outgoing link
+ requests, even to destinations that have not announced a link
+ request cost (and will, in that case, use the configured or
+ default link request cost). This option is mostly useful for
+ testing and diagnostics. In general use, Reticulum will handle
+ link request stamping and cost targets automatically.
+
+ * | The ``enforce_stamps`` option allows early activation of stamp
+ enforcement. When enabled, announces and path requests that do
+ not meet the configured cost requirements are dropped, and link
+ requests with insufficient stamps are ignored. This is a transitory
+ option. It will become mandatory and enabled by default in RNS
+ ``1.6.2``.
+
An example of customised stamp cost and value configuration follows below:
.. code:: ini
@@ -312,12 +312,52 @@ That's really all there is to it. If you already now want to make you applicatio
Your application will now only receive, and have to process, the announces and paths that it actually cares about.
-Blackhole Management
-====================
-
-TODO: Short section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
Ingress & Burst Control
=======================
-TODO: Short section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options).
\ No newline at end of file
+In addition to the economic incentives created by stamps, Reticulum enforces a set of hydraulic limits on how much announce traffic any peer or destination can inject into the network. These mechanisms work automatically, require no operator configuration (but can be tuned, if required), and apply equally to all peers.
+
+At the most basic level, the ``announce_cap`` mechanism limits the bandwidth any interface will allocate to propagating announces and other network upkeep traffic, and prioritises the local topology. Destinations that rapidly re-announce are down-prioritised in the transmission queue, so attempting to gain reach through announce spam has the exact *opposite* effect.
+
+On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. A grace period allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
+
+The final layer protects against bursts of announces for *newly created* destinations. If an interface receives a large influx of announces for previously unknown destinations in a short amount of time, these are held in a bounded queue, while announces for known and established destinations continue to be processed without interruption. After the burst subsides, and an additional waiting period has passed, held announces are released slowly until the queue is cleared.
+
+A node that connects to a public interface, announces a large number of bogus destinations, and then disconnects, will therefore never get those destinations into path tables at all. When the interface they arrived on disappears, the held announces are simply dropped and forgotten.
+
+Ingress control operates at the level of individual sub-interfaces, so one misbehaving client cannot disrupt announce processing for other clients connected to the same listener. Combined with stamps, these mechanisms are complementary:
+
+Rate limiting bounds the *rate* at which abuse can occur, for everyone, while stamps make the *volume* of abuse from any actor computationally expensive.
+
+Full configuration details are available in the :ref:`Announce Rate Control
` and :ref:`New Destination Rate Limiting` sections.
+
+
+Blackhole Management
+====================
+
+The *blackhole* system allows any node operator or individual user to block specific identities at the transport layer.
+
+Once an identity has been blackholed on a node, announces originating from *any* destination associated with that identity are dropped, and the node will refuse to transport traffic, or establish and maintain links, to the blackholed identity's destinations.
+
+It is important to understand the scope of this mechanism corrrectly. There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. A blackhole entry only applies on the network segments that enforce it, which is the exact intention. Operators retain full control over what is allowed on their own segments, while no one can impose restrictions on segments they do not operate.
+
+Blackholes can be managed directly with the ``rnpath`` utility. Identities can be blocked (optionally with an expiry duration and a human-readable reason), unblocked, and the current local blocklist can be inspected at any time. This is well suited for immediate responses to announce spam, unwanted content or malicious behaviour observed on your own networks.
+
+For anything larger than a few nodes, manual blocklist maintenance quickly becomes impractical. Reticulum therefore allows an instance to subscribe to blackhole lists published by trusted transport identities, periodically retrieving and merging them into the local list, and conversely to publish its own list to subscribers.
+
+This makes it possible to federate community-maintained blocklists across large networks, with the important caveat that subscribing to a list is an act of trust in its maintainer. See the :ref:`Blackhole Management` section for full details on local management, automated list sourcing and publishing.
+
+
+Fast-Flap Blocking
+==================
+
+High-performance listener interfaces, such as :ref:`BackboneInterface`, will automatically block *fast-flapping* clients; remote peers that repeatedly connect for a very short amount of time, and then disconnect.
+
+This behaviour usually stems from attempts to dump announce or path request spam onto the network in short bursts, while rotating connections in an attempt to evade per-interface rate limits, but it can also be caused by broken implementations or automated scanning tools.
+
+Such bypass attempts generally have very limited effect. Ingress limiters trigger *immediately* once rate limits are exceeded, but the behaviour still causes needless interface rotation and wasted resources on the transport instance.
+
+With fast-flap blocking enabled, a client that exceeds the allowed flap grace is simply not allocated an actual interface again, for the configured block duration.
+
+On the ``BackboneInterface`` type, fast-flap blocking is enabled by default, with sensible standard settings. All parameters can be adjusted if necessary. See the :ref:`Automated Blocking` section of the Interfaces chapter.
\ No newline at end of file
diff --git a/docs/source/using.rst b/docs/source/using.rst
index 8cdb187b..ab871567 100644
--- a/docs/source/using.rst
+++ b/docs/source/using.rst
@@ -1391,7 +1391,7 @@ The blackhole system relies on the trust relationship between the subscriber and
As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
-For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
+For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative overhead.
Improving System Configuration
------------------------------