Reticulum/docs/manual/stamps.html
2026-11-07 13:25:25 +01:00

593 lines
No EOL
42 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html class="no-js" lang="en" data-content_root="./">
<head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Understanding Reticulum" href="understanding.html"><link rel="prev" title="Using Reticulum on Your System" href="using.html">
<link rel="prefetch" href="_static/rns_logo_512.png" as="image">
<!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
<title>Protecting Open Networks - Reticulum Network Stack 1.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=e1715074" />
<style>
body {
--color-code-background: #f2f2f2;
--color-code-foreground: #1e1e1e;
}
@media not print {
body[data-theme="dark"] {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
--color-background-primary: #202b38;
--color-background-secondary: #161f27;
--color-foreground-primary: #dbdbdb;
--color-foreground-secondary: #a9b1ba;
--color-brand-primary: #41adff;
--color-background-hover: #161f27;
--color-api-name: #ffbe85;
--color-api-pre-name: #efae75;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) {
--color-code-background: #202020;
--color-code-foreground: #d0d0d0;
--color-background-primary: #202b38;
--color-background-secondary: #161f27;
--color-foreground-primary: #dbdbdb;
--color-foreground-secondary: #a9b1ba;
--color-brand-primary: #41adff;
--color-background-hover: #161f27;
--color-api-name: #ffbe85;
--color-api-pre-name: #efae75;
}
}
}
</style></head>
<body>
<script>
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
</script>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-toc" viewBox="0 0 24 24">
<title>Contents</title>
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
</svg>
</symbol>
<symbol id="svg-menu" viewBox="0 0 24 24">
<title>Menu</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
<line x1="3" y1="12" x2="21" y2="12"></line>
<line x1="3" y1="6" x2="21" y2="6"></line>
<line x1="3" y1="18" x2="21" y2="18"></line>
</svg>
</symbol>
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
<title>Expand</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
<polyline points="9 18 15 12 9 6"></polyline>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24">
<title>Light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24">
<title>Dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
</svg>
</symbol>
<symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
<title>Auto light/dark, in light mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
<line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
<line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
<line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
<line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
<line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
<line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
<line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
<line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
<circle cx="14.5" cy="9.55" r="3.6"/>
</svg>
</symbol>
<symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
<title>Auto light/dark, in dark mode</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
class="icon-custom-derived-from-feather-sun-and-tabler-moon">
<path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
<line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
<line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
<line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
<line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
<line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
<line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
<line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
<line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
<circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
</svg>
</symbol>
<symbol id="svg-pencil" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
<path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
<path d="M13.5 6.5l4 4" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
<symbol id="svg-eye" viewBox="0 0 24 24">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
<path
d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
<path d="M20 21l2 -2l-2 -2" />
<path d="M17 17l-2 2l2 2" />
</svg>
</symbol>
</svg>
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
<label class="overlay sidebar-overlay" for="__navigation"></label>
<label class="overlay toc-overlay" for="__toc"></label>
<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<span class="icon"><svg><use href="#svg-menu"></use></svg></span>
</label>
</div>
<div class="header-center">
<a href="index.html"><div class="brand">Reticulum Network Stack 1.6.0 documentation</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon" for="__toc">
<span class="icon"><svg><use href="#svg-toc"></use></svg></span>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
<div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
<div class="sidebar-logo-container">
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
</div>
<span class="sidebar-brand-text">Reticulum Network Stack 1.6.0 documentation</span>
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
<input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
<input type="hidden" name="check_keywords" value="yes">
<input type="hidden" name="area" value="default">
</form>
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Protecting Open Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="distributed.html">Distributed Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="git.html">Git Over Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
<li class="toctree-l1"><a class="reference internal" href="brandolinis.html">Brandolini’s Reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
</ul>
</div>
</div>
</div>
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>Back to top</span>
</a>
<div class="content-icon-container">
<div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
<svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
<svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon" for="__toc">
<span class="icon"><svg><use href="#svg-toc"></use></svg></span>
</label>
</div>
<article role="main" id="furo-main-content">
<section id="protecting-open-networks">
<h1>Protecting Open Networks<a class="headerlink" href="#protecting-open-networks" title="Link to this heading"></a></h1>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.0</span></code> release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, <code class="docutils literal notranslate"><span class="pre">1.6.0</span></code> does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code> release will enable full stamp generation and emission of all types by default, but will leave the <em>enforcement</em> a configurable option.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">1.6.2</span></code> release will complete the transition, activating full stamp enforcement across all the systems.</p></li>
</ul>
<p>The stated version numbers are the <em>intended</em> release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.</p>
</div>
<p>While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.</p>
<p>Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.</p>
<p>Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.</p>
<p>In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:</p>
<blockquote>
<div><p>All nodes help combat spam and network abuse, according to the rules <em>set by the actual owners of supplied resources</em> - not by any bureaucracy or external authority.</p>
<p>Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.</p>
</div></blockquote>
<p>The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network’s operators.</p>
<section id="cryptographic-stamps">
<h2>Cryptographic Stamps<a class="headerlink" href="#cryptographic-stamps" title="Link to this heading"></a></h2>
<p>All networking primitives that consume shared network resources are gated by <em>stamps</em>. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.</p>
<p>The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.</p>
<p>While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target <em>values</em> and required <em>costs</em> for the built-in mechanisms will be sufficient.</p>
<p>The <em>value</em> of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from <code class="docutils literal notranslate"><span class="pre">0.0</span></code> to <code class="docutils literal notranslate"><span class="pre">100.0</span></code>. The scale is <strong>exponential</strong>. An increase of one point is equal to <em>doubling</em> the average compute time required. Fractional values are supported, such as <code class="docutils literal notranslate"><span class="pre">14.125</span></code>.</p>
<p>Internally, the fractional part is quantized to <code class="docutils literal notranslate"><span class="pre">256</span></code> different values, giving an approximately <code class="docutils literal notranslate"><span class="pre">0.4%</span></code> difficulty increase per step. You can use any decimal number when configuring stamps, such as <code class="docutils literal notranslate"><span class="pre">9.3691</span></code> and you do not have to worry about “landing on” the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.</p>
<p>The term <em>cost</em> is used everywhere a stamp value <em>requirement</em> is configured or specified. In general, <em>value</em> refers to the actual, determined value of a given stamp, <em>cost</em> refers to a value requirement.</p>
<section id="base-primitives">
<h3>Base Primitives<a class="headerlink" href="#base-primitives" title="Link to this heading"></a></h3>
<p>Reticulum provides two types of base stamp primitives:</p>
<blockquote>
<div><ul>
<li><p><strong>Detached stamps</strong> can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.</p>
<p>They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.</p>
</li>
<li><p><strong>Embedded stamps</strong> are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself <em>contains</em> the stamp, and there is no external, detached byte sequence for them.</p>
<p>Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.</p>
</li>
</ul>
</div></blockquote>
</section>
<section id="on-network-types">
<h3>On-Network Types<a class="headerlink" href="#on-network-types" title="Link to this heading"></a></h3>
<p>The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.</p>
<blockquote>
<div><ul>
<li><p><strong>Destination Stamps</strong> are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node’s cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.</p>
<p>Destination stamps are <em>one-time</em> generations, and are reusable across announces. They limit the number of <em>new</em> destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.</p>
<p>A generation time for such stamps in <em>minutes</em> rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.</p>
</li>
<li><p><strong>Path Request Stamps</strong> are also detached stamps, but generated <em>individually</em> for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.</p>
<p>The stamp is generated against the individually unique <em>emission</em>, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.</p>
</li>
<li><p><strong>Link Request Stamps</strong> embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.</p>
<p>Link request cost targets are set by the <em>endpoint destinations individually</em>. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.</p>
<p>Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.</p>
</li>
</ul>
</div></blockquote>
<p>All of the stamp primitives, functionality and on-wire signalling is <em>transparent and backwards-compatible</em> with older versions of Reticulum transport nodes. This means, that even if a node doesn’t itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.</p>
</section>
<section id="configuring-stamps">
<span id="stamps-configuring"></span><h3>Configuring Stamps<a class="headerlink" href="#configuring-stamps" title="Link to this heading"></a></h3>
<p>Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.</p>
<section id="instance-configuration">
<h4>Instance Configuration<a class="headerlink" href="#instance-configuration" title="Link to this heading"></a></h4>
<p>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 <code class="docutils literal notranslate"><span class="pre">[stamps]</span></code> section of the Reticulum configuration file:</p>
<blockquote>
<div><ul>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">stamp_destinations</span></code> 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 <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">stamp_prs</span></code> 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 <code class="docutils literal notranslate"><span class="pre">1.6.1</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">always_stamp_lrs</span></code> option will stamp <em>all</em> 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.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">enforce_stamps</span></code> 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
<code class="docutils literal notranslate"><span class="pre">1.6.2</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">destination_cost</span></code> option sets the default required stamp
cost for announced destinations to be accepted, and have their
announces propagated by this node. Defaults to <code class="docutils literal notranslate"><span class="pre">23.5</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">destination_value</span></code> option sets the default stamp value that
this instance will target when generating new destination stamps.
An application can request higher targets for destinations that it
creates, but a requested lower value will always be clamped to the
configured default as a minimum. Defaults to <code class="docutils literal notranslate"><span class="pre">25.0</span></code>.</div>
</div>
<blockquote>
<div><p><em>Destination stamps are one-time generations per destination, so it
is generally a good idea to target a slightly higher value than the
minimum required cost of the networks you want the destination to
be reachable on.</em></p>
</div></blockquote>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">pr_cost</span></code> option sets the required stamp cost for incoming
path requests. Defaults to <code class="docutils literal notranslate"><span class="pre">15.8</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">pr_value</span></code> option sets the target stamp value for path
request stamps generated by this instance. Defaults to <code class="docutils literal notranslate"><span class="pre">15.8</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">lr_cost</span></code> option sets the default link request stamp cost,
that destinations created on this instance will require. This
value can be freely overridden by applications that specify their
own link request cost requirements, and is solely used as the
default if no such specification is provided. Defaults to <code class="docutils literal notranslate"><span class="pre">12.5</span></code>.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The <code class="docutils literal notranslate"><span class="pre">lr_stamp_timeout</span></code> and <code class="docutils literal notranslate"><span class="pre">pr_stamp_timeout</span></code> options set the
maximum amount of time, in seconds, to spend while attempting to
generate link and path request stamps respectively. If a stamp is
not generated within this timespan, the generation is cancelled,
and the link request or path request fails. Defaults to <code class="docutils literal notranslate"><span class="pre">15</span></code>
seconds for both options.</div>
</div>
</li>
</ul>
</div></blockquote>
<p>An example of customised stamp cost and value configuration follows below:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[stamps]</span>
<span class="w"> </span><span class="na">stamp_destinations</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
<span class="w"> </span><span class="na">stamp_prs</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">24.8</span>
<span class="w"> </span><span class="na">destination_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">26.25</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">15.8</span>
<span class="w"> </span><span class="na">pr_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">16.45</span>
</pre></div>
</div>
<p>Stamp cost requirements can also be configured on a per-interface basis:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[[Public Gateway]]</span>
<span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">BackboneInterface</span>
<span class="w"> </span><span class="na">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">gateway</span>
<span class="w"> </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
<span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">25.0</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">17.2</span>
<span class="k">[[Local RNode]]</span>
<span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">RNodeInterface</span>
<span class="w"> </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/dev/ttyUSB0</span>
<span class="w"> </span><span class="c1"># Much lower requirements</span>
<span class="w"> </span><span class="c1"># for the local network.</span>
<span class="w"> </span><span class="na">destination_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">11.2</span>
<span class="w"> </span><span class="na">pr_cost</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">5.0</span>
</pre></div>
</div>
</section>
<section id="for-developers">
<h4>For Developers<a class="headerlink" href="#for-developers" title="Link to this heading"></a></h4>
<p>Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.</p>
<p>If you are setting these values at destination creation time, ensure that they are set <em>immediately</em> after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new destination</span>
<span class="n">my_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
<span class="n">my_identity</span><span class="p">,</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">IN</span><span class="p">,</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
<span class="s2">&quot;myapp&quot;</span><span class="p">,</span> <span class="s2">&quot;service&quot;</span>
<span class="p">)</span>
<span class="c1"># Configure stamps</span>
<span class="n">my_destination</span><span class="o">.</span><span class="n">set_value</span><span class="p">(</span><span class="mf">30.0</span><span class="p">)</span>
<span class="n">my_destination</span><span class="o">.</span><span class="n">set_link_cost</span><span class="p">(</span><span class="mf">15.0</span><span class="p">)</span>
</pre></div>
</div>
<p>Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.</p>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>Remember here, though, that announce cadence should be preserved for such situations! If your destination is announcing too often in general, and wants to dynamically adjust link request costs at a critical moment, it may already have exhausted its announce rate limits on upstream nodes. So plan your application’s announce cadence thoughtfully!</p>
</div>
<p>It is also possible for application code to directly get the destination value and link request cost for any known destination:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Get the value of a known destination</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall_stamp_value</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
<span class="c1"># Get the current link cost requirement</span>
<span class="c1"># of a known destination</span>
<span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall_link_cost</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
</pre></div>
</div>
<p>An <code class="docutils literal notranslate"><span class="pre">Identity</span></code> can be created with an embedded stamp value, by passing the target value at instantiation time:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new, stamped identity</span>
<span class="n">my_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="p">(</span><span class="n">value</span><span class="o">=</span><span class="mf">24.0</span><span class="p">)</span>
<span class="c1"># Get the value of any known identity</span>
<span class="n">another_identity</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>
</pre></div>
</div>
<p>As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value <em>cannot</em> be upgraded at a later point as with detached stamps.</p>
</section>
</section>
</section>
<section id="filtering-qos">
<h2>Filtering &amp; QoS<a class="headerlink" href="#filtering-qos" title="Link to this heading"></a></h2>
<p>TODO: Section explaining the <code class="docutils literal notranslate"><span class="pre">[filter]</span></code> configuration options, for creating allow and blocklists for specific destination types.</p>
</section>
<section id="blackhole-management">
<h2>Blackhole Management<a class="headerlink" href="#blackhole-management" title="Link to this heading"></a></h2>
<p>TODO: 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.</p>
</section>
<section id="ingress-burst-control">
<h2>Ingress &amp; Burst Control<a class="headerlink" href="#ingress-burst-control" title="Link to this heading"></a></h2>
<p>TODO: 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).</p>
</section>
</section>
</article>
</div>
<footer>
<div class="related-pages">
<a class="next-page" href="understanding.html">
<div class="page-info">
<div class="context">
<span>Next</span>
</div>
<div class="title">Understanding Reticulum</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
<a class="prev-page" href="using.html">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>Previous</span>
</div>
<div class="title">Using Reticulum on Your System</div>
</div>
</a>
</div>
<div class="bottom-of-page">
<div class="left-details">
<div class="copyright">
Copyright &#169; 2025, Mark Qvist
</div>
Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and
<a href="https://github.com/pradyunsg/furo">Furo</a>
</div>
<div class="right-details">
</div>
</div>
</footer>
</div>
<aside class="toc-drawer">
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
On this page
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
<ul>
<li><a class="reference internal" href="#">Protecting Open Networks</a><ul>
<li><a class="reference internal" href="#cryptographic-stamps">Cryptographic Stamps</a><ul>
<li><a class="reference internal" href="#base-primitives">Base Primitives</a></li>
<li><a class="reference internal" href="#on-network-types">On-Network Types</a></li>
<li><a class="reference internal" href="#configuring-stamps">Configuring Stamps</a><ul>
<li><a class="reference internal" href="#instance-configuration">Instance Configuration</a></li>
<li><a class="reference internal" href="#for-developers">For Developers</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#filtering-qos">Filtering &amp; QoS</a></li>
<li><a class="reference internal" href="#blackhole-management">Blackhole Management</a></li>
<li><a class="reference internal" href="#ingress-burst-control">Ingress &amp; Burst Control</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</aside>
</div>
</div><script src="_static/documentation_options.js?v=72d88caf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/scripts/furo.js?v=46bd48cc"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=f281be69"></script>
</body>
</html>