mirror of
https://github.com/Rate-Limiting-Nullifier/rln-docs.git
synced 2026-01-10 07:48:01 -05:00
572 lines
41 KiB
HTML
572 lines
41 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Rate-Limiting Nullifier</title>
|
||
<meta name="robots" content="noindex" />
|
||
<!-- Custom HTML head -->
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
<!-- MathJax -->
|
||
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script>
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script>
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script>
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script>
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="rln.html"><strong aria-hidden="true">1.</strong> RLN</a></li><li class="chapter-item expanded "><a href="overview.html"><strong aria-hidden="true">2.</strong> Overview</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="what_is_rln.html"><strong aria-hidden="true">2.1.</strong> What is RLN</a></li><li class="chapter-item expanded "><a href="under_the_hood.html"><strong aria-hidden="true">2.2.</strong> Under the hood</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="protocol_spec.html"><strong aria-hidden="true">2.2.1.</strong> Protocol spec</a></li><li class="chapter-item expanded "><a href="circuits.html"><strong aria-hidden="true">2.2.2.</strong> Circuits</a></li></ol></li><li class="chapter-item expanded "><a href="uses.html"><strong aria-hidden="true">2.3.</strong> Uses</a></li></ol></li><li class="chapter-item expanded "><a href="how_to_use.html"><strong aria-hidden="true">3.</strong> How to use</a></li><li><ol class="section"><li class="chapter-item expanded "><div><strong aria-hidden="true">3.1.</strong> JavaScript RLN</div></li><li class="chapter-item expanded "><div><strong aria-hidden="true">3.2.</strong> Rust RLN</div></li></ol></li><li class="chapter-item expanded "><a href="theory.html"><strong aria-hidden="true">4.</strong> Theory</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="sss.html"><strong aria-hidden="true">4.1.</strong> Shamir's Secret Sharing</a></li></ol></li><li class="chapter-item expanded "><a href="appendix.html"><strong aria-hidden="true">5.</strong> Appendix</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="terminology.html"><strong aria-hidden="true">5.1.</strong> A - Terminology</a></li><li class="chapter-item expanded "><a href="references.html"><strong aria-hidden="true">5.2.</strong> B - References</a></li></ol></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Rate-Limiting Nullifier</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script>
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<h1 id="rln"><a class="header" href="#rln">RLN</a></h1>
|
||
<p><strong>RLN</strong> (Rate-Limiting Nullifier) is a zk-gadget/protocol that enables spam prevention mechanism for anonymous environments.</p>
|
||
<p><strong>RLN</strong> is part of (<strong>PSE</strong>) <a href="https://appliedzkp.org">Privacy & Scaling Explorations</a>, a multidisciplinary team supported by the Ethereum Foundation. PSE explores new use cases for zero-knowledge proofs and other cryptographic primitives.</p>
|
||
<p><img src="./images/logo.svg" alt="alt text" /></p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="overview"><a class="header" href="#overview">Overview</a></h1>
|
||
<p>This section is a starting point for understanding the concepts of <strong>RLN</strong>.</p>
|
||
<p>Here we'll discuss:</p>
|
||
<ul>
|
||
<li>Basic explanation of the <strong>RLN</strong> protocol</li>
|
||
<li><strong>RLN</strong> protocol under the hood</li>
|
||
<li><strong>RLN</strong> uses</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="what-is-rate-limiting-nullifier"><a class="header" href="#what-is-rate-limiting-nullifier">What is Rate-Limiting Nullifier?</a></h1>
|
||
<p><strong>RLN</strong> is a zero-knowledge gadget that enables spam prevention for decentralized, anonymous environments.</p>
|
||
<p>The anonymity property opens up the possibility for spam and Sybil attack vectors for certain applications, which could seriously degrade the user experience and the overall functioning of the application. For example, imagine a chat application where users are anonymous. Now, everyone can write an unlimited number of spam messages, but we don't have the ability to kick this member because the spammer is anonymous. </p>
|
||
<p><strong>RLN</strong> helps us identify and "kick" the spammer.</p>
|
||
<p>Moreover, <strong>RLN</strong> can be useful not only to prevent spam attacks but, in general, to limit users (in anonymous environments) in the number of actions (f.e. to vote or to make a bid).</p>
|
||
<h2 id="how-it-works"><a class="header" href="#how-it-works">How it works</a></h2>
|
||
<p>The <strong>RLN</strong> construct's functionality consists of three parts, which, when integrated together, provide spam and Sybil attack protection. These parts should be integrated by the upstream applications, which require anonymity and spam protection. The applications can be centralized or decentralized. For decentralized applications, each user maintains separate storage and compute resources for the application. The three parts are:</p>
|
||
<ul>
|
||
<li>User registration</li>
|
||
<li>User interaction</li>
|
||
<li>User removal (slashing)</li>
|
||
</ul>
|
||
<h3 id="user-registration"><a class="header" href="#user-registration">User registration</a></h3>
|
||
<p>Before registering to the application, the user needs to generate a secret key and derive an identity commitment from the secret key using the <code>Poseidon</code> hash function <code>identityCommitment = posseidonHash(secretKey)</code>.</p>
|
||
<p>The user registers to the application by providing a form of stake and their identity commitment, which is derived from the secret key. The application maintains a Merkle tree data structure (in the latest iteration of <strong>RLN</strong>, we use an Incremental Merkle Tree algorithm for gas efficiency, but the Merkle tree does not have to be on-chain), which stores the identity commitments of the registered users. Upon successful registration, the user's identity commitment is stored in a leaf of the Merkle tree, and an index is given to them, representing their position in the tree.</p>
|
||
<h3 id="user-interaction"><a class="header" href="#user-interaction">User interaction</a></h3>
|
||
<p>For each interaction that the user wants to make with the application, the user must generate a zero-knowledge proof ensuring that their identity commitment is part of the membership Merkle tree.</p>
|
||
<p>There are a number of use-cases for <strong>RLN</strong>, such as voting applications (1 vote per election), chat (one message per second), and rate-limiting cache access (CDN denial of service protection). The verifier can be a server for centralized applications or the other users for decentralized applications.</p>
|
||
<p>The general anti-spam rule is usually in the form of:
|
||
<code>Users must not make more than X interactions per epoch.</code></p>
|
||
<p>The epoch can be translated as a time interval of <code>Y</code> units of time unit <code>Z</code>. For simplicity's sake, let's transform the rule into: `Users must not send more than one message per second.</p>
|
||
<p>We can implement this using <em>Shamir's Secret Sharing</em> scheme (<a href="./sss.html"><em>read more</em></a>), which allows you to split a secret (f.e. to <code>n</code> parts) and recover it when any <code>m</code> of <code>n</code> parts <code>(m <= n)</code> are presented.</p>
|
||
<p>Thus, users have to split their <code>secret_key</code> into <code>n</code> parts, and for every interaction, they have to reveal the new part of the <code>secret_key.</code> So, in addition to proving the membership in the <em>Merkle Tree</em>, users have to prove that the revealed part is truly the part of their <code>secret_key.</code></p>
|
||
<p>If they make more interactions than allowed per epoch, their secret key can be fully reconstructed.</p>
|
||
<h3 id="user-removal-slashing"><a class="header" href="#user-removal-slashing">User removal (slashing)</a></h3>
|
||
<p>The final property of the <strong>RLN</strong> mechanism is that it allows for the users to be removed from the membership tree by anyone that knows their secret key. The membership tree contains the identity commitments of all registered users. Users' identity commitment is derived from their secret key, and the secret key of the user is only revealed in a spam event (except for the scenarios where the original users want to remove themselves, which they can always do because they know their secret key). When an economic stake is present, the <strong>RLN</strong> mechanism can be implemented in a way that the spammer's stake is sent to the first user that correctly reports the spammer by providing the reconstructed secret key of the spammer as proof.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="under-the-hood"><a class="header" href="#under-the-hood">Under the hood</a></h1>
|
||
<p>This section provides deep and technical <strong>RLN</strong> overview.</p>
|
||
<p>We'll discuss:</p>
|
||
<ul>
|
||
<li>Technical side of <strong>RLN</strong> (specification demo)</li>
|
||
<li>How circuits are implemented</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="technical-side-of-rln"><a class="header" href="#technical-side-of-rln">Technical side of RLN</a></h1>
|
||
<p><em>This topic is a less strict version of specifications. If you want a more formal description, you can find specs in the <a href="./references.html">references</a>. Also, if you're unfamiliar with Shamir's Secret Sharing scheme, you can <a href="./sss.html">read it here</a>.</em></p>
|
||
<hr />
|
||
<p><img src="./images/rln-circuit.png" alt="alt text" /></p>
|
||
<p align="center">
|
||
<i>Under the hood: The <b>RLN</b> Circom Circuit</i>
|
||
</p>
|
||
<p><strong>RLN</strong> consists of three parts:</p>
|
||
<ul>
|
||
<li>User registration</li>
|
||
<li>User interaction (signaling)</li>
|
||
<li>User removal (slashing) - additional part</li>
|
||
</ul>
|
||
<p>Well, let's discuss them.</p>
|
||
<h2 id="user-registration-1"><a class="header" href="#user-registration-1">User registration</a></h2>
|
||
<p>The first part of <strong>RLN</strong> is registration. There is nothing special in <strong>RLN</strong> registration; it's almost the same process as in other protocols/apps with anonymous environments: we need to create a Merkle Tree, and every participant must submit a <code>commitment</code> and place it in the Merkle Tree, and after that to interact with the app every participant will create a zkProof's, that they are a <em>member of the tree</em> (we use an <em>Incremental Merkle Tree</em>, as it more <em>GAS efficient</em>).</p>
|
||
<p>So, each member generates a secret key, denoted by \(a_0\). Identity commitment \(q\) is the hash (Poseidon) of the secret key: \(q = Poseidon(a_0)\).</p>
|
||
<p><strong>RLN</strong> wouldn't work if there were no punishment for spam; that's why to become a member, a user has to register and provide something at stake. So, whoever has our \(a_0\) can "slash" us. </p>
|
||
<p>The slight difference is that we must enable a <em>secret sharing</em> scheme (to split the <code>commitment</code> into parts). We need to come up with a polynomial. For simplicity we use linear polynomial (e.g. \(f(x) = kx + b\). Therefore, with two points, we can reconstruct the polynomial and recover the secret. </p>
|
||
<p>Our polynomial will be: \(A(x) = a_1 * x + a_0\), where \(a_1 = Poseidon(a_0, external\_nullifier)\).
|
||
The meaning of \(external\_nullifier\) is described below.</p>
|
||
<h2 id="signalling"><a class="header" href="#signalling">Signalling</a></h2>
|
||
<p>Now that the user is registered, he wants to interact with the system. Imagine that the system is an <em>anonymous chat</em> and the interaction is the sending of messages.
|
||
So, to send a message user have to come up with <em>share</em> - the point \((x, y)\) on her polynomial.
|
||
We denote: \(x = Poseidon(message), y = A(x)\). </p>
|
||
<p>Thus, if the same epoch user sends more than one message, their polynomial and, therefore, their secret (\(a_0\)) can be recovered.</p>
|
||
<p>Of course, we somehow must prove that our <em>share</em> = \((x, y)\) is valid (that this is really a point on our <code>polynomial = A(x)</code>), as well as we must prove other things are valid too, that's why we use zkSNARK. An explanation of the zk-circuits can be found in the next topic.</p>
|
||
<h2 id="slashing"><a class="header" href="#slashing">Slashing</a></h2>
|
||
<p>As it's been said, if a user sends more than one message, everyone else will be able to recover his secret, slash them and take their stake.</p>
|
||
<h2 id="nullifiers"><a class="header" href="#nullifiers">Nullifiers</a></h2>
|
||
<p>There are also \(internal\_nullifier\) and \(external\_nullifier\), which can be found in the <strong>RLN</strong> protocol/circuits.</p>
|
||
<p>\(external\_nullifier = Poseidon(epoch, rln\_identifier)\), where \(rln\_identifier\) is a random finite field value, unique per RLN app.</p>
|
||
<p>The \(external\_nullifier\) is required so that the user can securely use the same private key \(a_0\) across different <strong>RLN</strong> apps - in different applications (and in different eras) with the same secret key, the user will have different values of the coefficient \(a_1\).</p>
|
||
<p>Now, imagine there are a lot of users sending messages, and after each received message, we need to check if any member can be slashed. To do this, we can use all combinations of received <em>shares</em> and try to recover the polynomial, but this is a naive and non-optimal approach. Suppose we have a mechanism that will tell us about the connection between a person and their messages while not revealing their identity. In that case, we can solve this without brute-forcing all possibilities by using a public \(internal\_nullifier = Poseidon(a_1)\), so if a user sends more than one message, it will be immediately visible to everyone.</p>
|
||
<h2 id="some-important-notes"><a class="header" href="#some-important-notes">Some important notes</a></h2>
|
||
<p>Also, in our example (and <a href="https://github.com/njofce/zk-chat">zk-chat</a> implementation), we use linear polynomial, but <a href="sss.html">SSS</a> allows us to use various degree polynomials; therefore we can implement a protocol, where more than one signal (message) can be sent in per epoch. </p>
|
||
<p>To learn more, check out the <a href="https://hackmd.io/7GR5Vi28Rz2EpEmLK0E0Aw?view">specification</a>; there are also <a href="https://github.com/privacy-scaling-explorations/rln/tree/master/circuits">circuits</a> implemented for various degree polynomials too.</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="circuits"><a class="header" href="#circuits">Circuits</a></h1>
|
||
<p><em><a href="https://vitalik.ca/general/2022/06/15/using_snarks.html">zkSNARK</a> is used in the <strong>RLN</strong> core. Therefore, we must represent the protocol in <a href="https://www.zeroknowledgeblog.com/index.php/the-pinocchio-protocol/r1cs">R1CS</a> (as we use <a href="https://www.zeroknowledgeblog.com/index.php/groth16">Groth16</a>). <a href="https://docs.circom.io/">Circom</a> was chosen for this. This section explains <strong>RLN</strong> circuits for the linear polynomial case (one message per epoch). You can find implementation for the general case <a href="https://github.com/privacy-scaling-explorations/rln/blob/master/circuits/nrln-base.circom">here</a></em></p>
|
||
<hr />
|
||
<p><strong>RLN</strong> circuits implement the logic described in <a href="./protocol_spec.html">previous topic</a>.</p>
|
||
<h2 id="merkle-tree-circuit"><a class="header" href="#merkle-tree-circuit">Merkle Tree circuit</a></h2>
|
||
<p>One of the critical components of <strong>RLN</strong> is the <em>Incremental Merkle Tree</em> for the membership tree. Any Merkle tree can be used, but we have chosen the Incremental Merkle Tree for gas efficiency.
|
||
Let's look at the <a href="https://github.com/privacy-scaling-explorations/rln/blob/master/circuits/incrementalMerkleTree.circom">implementation</a>.</p>
|
||
<p>At the beginning of the file, we denote that we use Circom 2.0 and include two helper <em>zk-gadgets</em>:</p>
|
||
<pre><code class="language-swift">pragma circom 2.0.0;
|
||
|
||
include "../node_modules/circomlib/circuits/poseidon.circom";
|
||
include "../node_modules/circomlib/circuits/mux1.circom";
|
||
</code></pre>
|
||
<p><em>Poseidon</em> gadget is just the implementation of the <em>Poseidon</em> hash function; the <em>mux1</em> gadget will be described later.</p>
|
||
<p>Next, we can see two implemented gadgets:</p>
|
||
<pre><code class="language-swift">template PoseidonHashT3() {
|
||
var nInputs = 2;
|
||
signal input inputs[nInputs];
|
||
signal output out;
|
||
|
||
component hasher = Poseidon(nInputs);
|
||
for (var i = 0; i < nInputs; i ++) {
|
||
hasher.inputs[i] <== inputs[i];
|
||
}
|
||
out <== hasher.out;
|
||
}
|
||
|
||
template HashLeftRight() {
|
||
signal input left;
|
||
signal input right;
|
||
|
||
signal output hash;
|
||
|
||
component hasher = PoseidonHashT3();
|
||
left ==> hasher.inputs[0];
|
||
right ==> hasher.inputs[1];
|
||
|
||
hash <== hasher.out;
|
||
}
|
||
</code></pre>
|
||
<p>These are helper gadgets to make the code more clean. <em>Poseidon</em> gadget is implemented with the ability to take a different number of arguments. We use <code>PoseidonHashT3()</code> to initialize it like a function with two arguments. And <code>HashLeftRight</code> use <code>PoseidonHashT3</code> in a more "readable" way: it takes two inputs, <code>left</code> and <code>right,</code> and outputs the result of the calculation.</p>
|
||
<p>Next comes the core of the Merkle Tree gadget:</p>
|
||
<pre><code class="language-swift">template MerkleTreeInclusionProof(n_levels) {
|
||
signal input leaf;
|
||
signal input path_index[n_levels];
|
||
signal input path_elements[n_levels][1];
|
||
signal output root;
|
||
|
||
component hashers[n_levels];
|
||
component mux[n_levels];
|
||
|
||
signal levelHashes[n_levels + 1];
|
||
levelHashes[0] <== leaf;
|
||
|
||
...
|
||
|
||
root <== levelHashes[n_levels];
|
||
}
|
||
</code></pre>
|
||
<p>Here we have three inputs: <code>leaf,</code> <code>path_index,</code> and <code>path_elements.</code> </p>
|
||
<p><code>path_index</code> is the position of the leaf represented in binary. We need the binary representation of the position in the Merkle tree to understand the hashing path from the leaf to the root (more on that <em><a href="">"3. Recursive Incremental Merkle Tree Algorithm, page 4"</a></em>). </p>
|
||
<p><code>path_elements</code> are sibling leaves that are part of Merkle Proof.</p>
|
||
<p><code>leaf = Poseidon(identity_secret)</code>, so it's just <em>identity commitment</em>.</p>
|
||
<p>There is a Merkle Tree hashing algorithm in the omitted part, no more than that.</p>
|
||
<h2 id="rln-core"><a class="header" href="#rln-core">RLN core</a></h2>
|
||
<p>RLN circuit is the implementation of <strong>RLN</strong> logic itself (which in turn uses the <em>Merkle Tree</em> gadget). You can find the implementation <a href="https://github.com/privacy-scaling-explorations/rln/blob/master/circuits/rln-base.circom">here</a>.</p>
|
||
<p>So, let's start with helper gadgets:</p>
|
||
<pre><code class="language-swift">template CalculateIdentityCommitment() {
|
||
signal input identity_secret;
|
||
signal output out;
|
||
|
||
component hasher = Poseidon(1);
|
||
hasher.inputs[0] <== identity_secret;
|
||
|
||
out <== hasher.out;
|
||
}
|
||
|
||
template CalculateExternalNullifier() {
|
||
signal input epoch;
|
||
signal input rln_identifier;
|
||
|
||
signal output out;
|
||
|
||
component hasher = Poseidon(2);
|
||
hasher.inputs[0] <== epoch;
|
||
hasher.inputs[1] <== rln_identifier;
|
||
|
||
out <== hasher.out;
|
||
}
|
||
|
||
template CalculateA1() {
|
||
signal input a_0;
|
||
signal input external_nullifier;
|
||
|
||
signal output out;
|
||
|
||
component hasher = Poseidon(2);
|
||
hasher.inputs[0] <== a_0;
|
||
hasher.inputs[1] <== external_nullifier;
|
||
|
||
out <== hasher.out;
|
||
}
|
||
|
||
template CalculateInternalNullifier() {
|
||
signal input a_1;
|
||
signal output out;
|
||
|
||
component hasher = Poseidon(1);
|
||
hasher.inputs[0] <== a_1;
|
||
|
||
out <== hasher.out;
|
||
}
|
||
</code></pre>
|
||
<p>It's easy to understand these samples: <code>CalculateIdentityCommitment()</code>, <code>CalculateA1()</code>, <code>CalculateInternalNullifier()</code>, <code>CalculateExternalNullifier()</code> - they do exactly what their name says; they are implemented as it's described in <a href="./protocol_spec.html">previous topic</a>.</p>
|
||
<p>Now, let's look at the core logic of the <strong>RLN</strong> circuit. </p>
|
||
<pre><code class="language-swift">...
|
||
|
||
signal input identity_secret;
|
||
signal input path_elements[n_levels][LEAVES_PER_PATH_LEVEL];
|
||
signal input identity_path_index[n_levels];
|
||
|
||
signal input x;
|
||
signal input epoch;
|
||
signal input rln_identifier;
|
||
|
||
signal output y;
|
||
signal output root;
|
||
signal output nullifier;
|
||
|
||
...
|
||
</code></pre>
|
||
<p>So, here we have many inputs. Private inputs are: <code>identity_secret</code> (basically <code>a_0</code> from the polynomial), <code>path_elements[][]</code>, <code>identity_path_index[]</code>. Public inputs are: <code>x</code> (actually just the hash of a signal), <code>epoch,</code> <code>rln_identifier</code>. Outputs are: <code>y</code> (polynomial share/secret share), <code>root</code> of a Merkle Tree, and <code>nullifier</code> (which is basically <code>internal_nullifier</code>).</p>
|
||
<p><strong>RLN</strong> circuit consists of two checks:</p>
|
||
<ul>
|
||
<li>Membership in Merkle Tree</li>
|
||
<li>Correctness of secret share</li>
|
||
</ul>
|
||
<h3 id="membership-in-merkle-tree"><a class="header" href="#membership-in-merkle-tree">Membership in Merkle Tree</a></h3>
|
||
<p>To check membership in a Merkle Tree, we can simply use the previously described Merkle Tree gadget:</p>
|
||
<pre><code class="language-swift">...
|
||
|
||
component identity_commitment = CalculateIdentityCommitment();
|
||
identity_commitment.identity_secret <== identity_secret;
|
||
|
||
var i;
|
||
var j;
|
||
component inclusionProof = MerkleTreeInclusionProof(n_levels);
|
||
inclusionProof.leaf <== identity_commitment.out;
|
||
|
||
for (i = 0; i < n_levels; i++) {
|
||
for (j = 0; j < LEAVES_PER_PATH_LEVEL; j++) {
|
||
inclusionProof.path_elements[i][j] <== path_elements[i][j];
|
||
}
|
||
inclusionProof.path_index[i] <== identity_path_index[i];
|
||
}
|
||
|
||
...
|
||
</code></pre>
|
||
<p>Here we are calculating the <code>identity_commitment</code> and passing it along with sibling leaves and binary representation of the position to a Merkle Tree gadget. It gives us the calculated root as an output, and we can put the constraint on that:</p>
|
||
<pre><code class="language-swift">root <== inclusionProof.root;
|
||
</code></pre>
|
||
<h3 id="correctness-of-secret-share"><a class="header" href="#correctness-of-secret-share">Correctness of secret share</a></h3>
|
||
<p>As we use linear polynomial we need to check that <code>y = a_1 * x + a_0</code> (<code>a_0</code> is identity secret). For that, we need to calculate <code>external_nullifier</code> and constraints on <code>a_1</code> and secret share:</p>
|
||
<pre><code class="language-swift">...
|
||
|
||
component external_nullifier = CalculateExternalNullifier();
|
||
external_nullifier.epoch <== epoch;
|
||
external_nullifier.rln_identifier <== rln_identifier;
|
||
|
||
component a_1 = CalculateA1();
|
||
a_1.a_0 <== identity_secret;
|
||
a_1.external_nullifier <== external_nullifier.out;
|
||
|
||
y <== identity_secret + a_1.out * x;
|
||
|
||
...
|
||
</code></pre>
|
||
<p>To calculate and reveal the <code>nullifier</code>:</p>
|
||
<pre><code class="language-swift">...
|
||
|
||
component calculateNullifier = CalculateInternalNullifier();
|
||
calculateNullifier.a_1 <== a_1.out;
|
||
|
||
nullifier <== calculateNullifier.out;
|
||
|
||
...
|
||
</code></pre>
|
||
<h2 id="main-runner-of-the-circuits"><a class="header" href="#main-runner-of-the-circuits">Main runner of the circuits</a></h2>
|
||
<p>Now the Circuits can be used as gadgets. If we want to use it in our app, we need to initialize it and have a <em>main</em> - starting point function. It can be found <a href="https://github.com/privacy-scaling-explorations/rln/blob/master/circuits/rln.circom">here</a>.</p>
|
||
<p>The implementation is super basic:</p>
|
||
<pre><code class="language-swift">pragma circom 2.0.0;
|
||
|
||
include "./rln-base.circom";
|
||
|
||
component main { public [x, epoch, rln_identifier] } = RLN(15);
|
||
</code></pre>
|
||
<p>That's the whole <strong>RLN</strong> Circom Circuit :) Here we just need to list all public inputs (<code>x,</code> <code>epoch,</code> <code>rln_identifier</code>; the rest of the inputs are private). Also, we set the depth of the Merkle Tree = 15 (max of 32768 members).</p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="uses"><a class="header" href="#uses">Uses</a></h1>
|
||
<p>This section contains list of apps that use <strong>RLN</strong>:</p>
|
||
<ul>
|
||
<li><a href="https://github.com/njofce/zk-chat">zk-chat</a> - A spam resistant instant messaging application for private and anonymous communication</li>
|
||
<li><a href="https://github.com/b-d1/rln-anonymous-chat-app">rln-chat-app</a> - PoC app, created using rln-js</li>
|
||
<li><a href="https://rfc.vac.dev/spec/17/">waku-rln-relay</a> - Extension of <a href="https://rfc.vac.dev/spec/11/">waku-relay</a> (spam protection with <strong>RLN</strong>)</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="how-to-use"><a class="header" href="#how-to-use">How to use</a></h1>
|
||
<p>This section provides information on how to use <strong>RLN</strong> in your project:</p>
|
||
<ul>
|
||
<li>JavaScript RLN (for <a href="https://github.com/Rate-Limiting-Nullifier/rlnjs">rln-js</a>)</li>
|
||
<li>Rust RLN (for <a href="https://github.com/vacp2p/zerokit/tree/master/rln">zerokit-rln</a>)</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="theory"><a class="header" href="#theory">Theory</a></h1>
|
||
<p>This section provides theoretical information that underpins <strong>RLN</strong>.</p>
|
||
<p>Here we'll discuss:</p>
|
||
<ul>
|
||
<li>Shamir's Secret Sharing</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="shamirs-secret-sharing-scheme"><a class="header" href="#shamirs-secret-sharing-scheme">Shamir's Secret Sharing Scheme</a></h1>
|
||
<p><em>This topic is an explanation of <strong>Shamir's Secret Sharing</strong> scheme (<strong>SSS</strong>), also known as \((k, n)\) threshold secret sharing scheme. <strong>SSS</strong> is one of the critical parts of <strong>RLN</strong>.</em></p>
|
||
<h2 id="overview-1"><a class="header" href="#overview-1">Overview</a></h2>
|
||
<p>Imagine if you have some important secret (secret key) and you don't want to store it anywhere. For that, you can use the <em>SSS</em> scheme. It allows you to split this secret into \(n\) parts (each individual part doesn't give any information about the secret) and restore this secret upon presentation of \(k\) \((k <= n)\) parts.</p>
|
||
<p>For example, you have a secret that you want to split into \(n\) parts/shares. You can divide these shares between your friends (1 share to 1 friend). Now when \(k\) of your friends reveal their share, you can restore the secret.</p>
|
||
<p>This scheme is also called \((k, n)\) <em>threshold secret sharing scheme</em>.</p>
|
||
<p>This scheme is possible due to <em>polynomial interpolation</em> (especially Lagrange interpolation). Let's describe how <em>Lagrange interpolation</em> works and how it's used in a <em>SSS</em> scheme.</p>
|
||
<h2 id="polynomial-lagrange-interpolation"><a class="header" href="#polynomial-lagrange-interpolation">Polynomial (Lagrange) interpolation</a></h2>
|
||
<p><em>Interpolation</em> is a method of constructing (or restoring) new points/values (or function) based on the range of a set of known points/values (f.e. we can restore the line (linear function) from two points that are from this line). The previous example describes how that works. </p>
|
||
<p align="center">
|
||
<img src="./images/graph1.png" width="300">
|
||
</p>
|
||
<p align="center">
|
||
<i>An unlimited number of parabolas (second-degree polynomials) can be drawn through two points. To choose the only one, you need a third point.</i>
|
||
</p>
|
||
<p>Thus, if we have a polynomial \(f(x) = 3x + 2\), we only need two points from this polynomial to restore it. Let's peek two random \(x\) values and calculate \(f(x)\):</p>
|
||
<ul>
|
||
<li>For \(x = 1\) we have \(f(1) = 3 * 1 + 2 = 5\)</li>
|
||
<li>For \(x = 10\) we have \(f(10) = 32\)</li>
|
||
</ul>
|
||
<p>Now we have to shares: \((1, 5)\) and \((10, 32)\). If we draw a graph based on these two shares, we can easily see that this is the same line (function):</p>
|
||
<p align="center">
|
||
<img src="./images/line.png" width="500" height="400">
|
||
</p>
|
||
<p>We also can "restore" the function analytically. For that let's denote: \[f(x) = y_1 * \frac{x - x_2}{x_1 - x_2} + y_2 * \frac{x - x_1}{x_2 - x_1}\]
|
||
where \(x_1 = 5, x_2 = 10, y_1 = 5, y_2 = 32\). If we make substitution we got: \[f(x) = 3x + 2 \]
|
||
which is the same polynomial.</p>
|
||
<p>The same technique can be made with every polynomial. Main thing to remember is that we need \(n + 1\) points to interpolate \(n\)-degree polynomial.</p>
|
||
<p>Now that we know how interpolation works, we can learn how it is used in SSS.</p>
|
||
<h2 id="shamirs-secret-sharing"><a class="header" href="#shamirs-secret-sharing">Shamir's Secret Sharing</a></h2>
|
||
<p>To create the <strong>SSS</strong> construct, we must choose \((k, n)\), where \(n\) is the number of shares we want to get from the secret and \(k\) is the number of shares required to restore the secret. The degree of the "secret" polynomial is \(k - 1\) (covered in the previous section).
|
||
Let's try to construct <strong>SSS</strong> with an example.</p>
|
||
<h3 id="sharing"><a class="header" href="#sharing">Sharing</a></h3>
|
||
<ol>
|
||
<li>Our secret = \(S = 30\) </li>
|
||
<li>As the linear polynomial used in current <strong>RLN</strong> implementations, let's set \(k = 2\) (2 points are enough to recover the polynomial); \(n\) is not that important, but we can make it any number, f.e. 3</li>
|
||
<li>The secret polynomial is: \[f(x) = a_1 * x + a_0 \]
|
||
where zero coefficient \(a_0 = S\), and \(a_1\) is some random number (f.e. 5); </li>
|
||
<li>We must pick \(n = 3\) different points (shares) on that polynomial, for that we can pick three random \(x\) values (f.e. 5, 8, 16) and calculate \(f(x)\):
|
||
\[f(5) = 5 * 5 + 30 = 55\]
|
||
\[f(8) = 5 * 8 + 30 = 70 \]
|
||
\[f(16) = 5 * 16 + 30 = 110 \]
|
||
So, the shares are: \((5, 55), (8, 70), (16, 110)\)</li>
|
||
</ol>
|
||
<h3 id="recovering"><a class="header" href="#recovering">Recovering</a></h3>
|
||
<p>We can take any two shares to recover (as described in the interpolation section) the "secret" polynomial. Zero coefficient (\(a_0\)) in the recovered polynomial is the secret \(S\).</p>
|
||
<h2 id="important-notes"><a class="header" href="#important-notes">Important notes</a></h2>
|
||
<p>Arithmetic in this topic is usual for us. However, in real life, <strong>SSS</strong> arithmetic is defined over some finite field. This means that all calculations are carried out modulo some big prime field. In fact, it happens by itself in Circom because the arithmetic there is defined over the finite field, too, so we don't need to do anything extra). </p>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="appendix"><a class="header" href="#appendix">Appendix</a></h1>
|
||
<p>The following sections contain reference material you may find useful:</p>
|
||
<ul>
|
||
<li>Terminology</li>
|
||
<li>References</li>
|
||
</ul>
|
||
<div style="break-before: page; page-break-before: always;"></div><h1 id="terminology"><a class="header" href="#terminology">Terminology</a></h1>
|
||
<div class="table-wrapper"><table><thead><tr><th>Term</th><th>Description</th></tr></thead><tbody>
|
||
<tr><td>zkSNARK</td><td>Proof construction where one can prove possession of certain information, e.g. a secret key, without revealing that information, and without any interaction between the prover and verifier.</td></tr>
|
||
<tr><td>Circuit</td><td>A program, that describes constraints for the prover in zkSNARK (for more information read <a href="https://medium.com/@VitalikButerin/quadratic-arithmetic-programs-from-zero-to-hero-f6d558cea649">this</a>).</td></tr>
|
||
<tr><td>zk-Gadget</td><td>Circuit, that can be used as a building block for another circuit, e.g. Poseidon hash function gadget.</td></tr>
|
||
<tr><td>Stake</td><td>Financial or social stake required for registering in the RLN applications. Common stake examples are: locking cryptocurrency (financial), linking reputable social identity.</td></tr>
|
||
<tr><td>Identity secret</td><td>Random number, which must be kept private by the user.</td></tr>
|
||
<tr><td>Identity commitment</td><td>The result of Poseidon(Identity secret) calculation. It is used by the users for registering in the protocol.</td></tr>
|
||
<tr><td>Signal</td><td>The message generated by a user. It is an arbitrary bit string that may represent a chat message, a URL request, protobuf message, etc.</td></tr>
|
||
<tr><td>Signal hash</td><td>Hash of the signal, used as an input in the RLN circuit.</td></tr>
|
||
<tr><td>RLN Identifier</td><td>Random finite field value unique per RLN app. It is used for additional cross-application security. The role of the RLN identifier is protection of the user secrets being compromised if signals are being generated with the same credentials at different apps.</td></tr>
|
||
<tr><td>RLN membership tree</td><td>Merkle tree data structure, filled with identity commitments of the users. Serves as a data structure that ensures user registrations.</td></tr>
|
||
<tr><td>Merkle proof</td><td>Proof that a user is member of the RLN membership tree.</td></tr>
|
||
</tbody></table>
|
||
</div><div style="break-before: page; page-break-before: always;"></div><h1 id="references"><a class="header" href="#references">References</a></h1>
|
||
<ul>
|
||
<li>
|
||
<p><a href="https://ethresear.ch/t/semaphore-rln-rate-limiting-nullifier-for-spam-prevention-in-anonymous-p2p-setting/5009">First Proposal/Idea of RLN by Barry WhiteHat</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://medium.com/privacy-scaling-explorations/rate-limiting-nullifier-a-spam-protection-mechanism-for-anonymous-environments-bbe4006a57d">RLN Overview by Blagoj</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://hackmd.io/@aeAuSD7mSCKofwwx445eAQ/BJcfDByNF">Demo RLN Spec</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://rfc.vac.dev/spec/32/">VAC RLN Spec</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://vitalik.ca/general/2016/12/10/qap.html">Understand zkSNARK</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://docs.circom.io/">Circom Docs</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://github.com/Rate-Limiting-Nullifier/rlnjs">rln-js</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://github.com/vacp2p/zerokit">zerokit-rln</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://arxiv.org/pdf/2105.06009v1.pdf">Incremental Merkle Tree paper</a></p>
|
||
</li>
|
||
</ul>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<script>
|
||
window.playground_copyable = true;
|
||
</script>
|
||
<script src="elasticlunr.min.js"></script>
|
||
<script src="mark.min.js"></script>
|
||
<script src="searcher.js"></script>
|
||
<script src="clipboard.min.js"></script>
|
||
<script src="highlight.js"></script>
|
||
<script src="book.js"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
<script src="mermaid.min.js"></script>
|
||
<script src="mermaid-init.js"></script>
|
||
<script>
|
||
window.addEventListener('load', function() {
|
||
MathJax.Hub.Register.StartupHook('End', function() {
|
||
window.setTimeout(window.print, 100);
|
||
});
|
||
});
|
||
</script>
|
||
</body>
|
||
</html>
|