From 3c894bf14ce8490395fb6d545b1d0be661d8efcf Mon Sep 17 00:00:00 2001 From: Magamedrasul Ibragimov Date: Sun, 2 Oct 2022 17:57:01 +0300 Subject: [PATCH] docs: update structure & add registration description --- src/SUMMARY.md | 2 +- src/circuits.md | 2 +- src/diagram.md | 45 ---------------------------- src/protocol_spec.md | 69 +++++++++++++++++++++++++++++++++++++++++++ src/references.md | 10 +++++-- src/rln.md | 4 ++- src/sss.md | 2 +- src/under_the_hood.md | 2 +- src/what_is_rln.md | 10 +++---- 9 files changed, 88 insertions(+), 58 deletions(-) delete mode 100644 src/diagram.md create mode 100644 src/protocol_spec.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9cb70fb..8d211c3 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -3,8 +3,8 @@ - [Overview](./overview.md) - [What is RLN](./what_is_rln.md) - [Under the hood](./under_the_hood.md) + - [Protocol spec](./protocol_spec.md) - [Circuits](./circuits.md) - - [Diagram](./diagram.md) - [Uses](./uses.md) - [How to use](./how_to_use.md) - [JavaScript RLN]() diff --git a/src/circuits.md b/src/circuits.md index f5df729..5ccd1f5 100644 --- a/src/circuits.md +++ b/src/circuits.md @@ -1,3 +1,3 @@ # Circuits -*[zkSNARK](https://vitalik.ca/general/2022/06/15/using_snarks.html) is used in the **RLN** core. Therefore, we need to represent the protocol in R1CS (as we use Groth16). Circom DSL was chosen for this. This section provides an explanation of RLN circuits.* +*[zkSNARK](https://vitalik.ca/general/2022/06/15/using_snarks.html) is used in the **RLN** core. Therefore, we need to represent the protocol in R1CS (as we use Groth16). Circom DSL was chosen for this. This section provides an explanation of **RLN** circuits.* diff --git a/src/diagram.md b/src/diagram.md deleted file mode 100644 index 4110fd5..0000000 --- a/src/diagram.md +++ /dev/null @@ -1,45 +0,0 @@ -# Diagram - -```mermaid -flowchart TB - - subgraph Generate Secret Key - random0(Random 32 bytes) --> a_0(Secret Key) - random1(Random 32 bytes) --> a_0 - end - - subgraph RLN - - subgraph Identity Commitment - a_0 --> h0(Poseidon Hash) - h0 --> q(Identity Commitment) - end - - subgraph Calculate Internal Nullifier - a_0 --> h1(Poseidon Hash) - epoch(Epoch) --> h1 - h1 --> a_1 - rln_identifier(RLN Identifier) --> h2(Poseidon Hash) - a_1 --> h2 - h2 --> nullifier(RLN Internal Nullifier) - end - - subgraph Merkle Tree - q --> merkle_tree_inclusion_proof(Merkle Tree Inclusion Proof) - merkle_tree_inclusion_proof --> root(ZKP of Merkle Tree Root) - end - - subgraph Shamirs Secret Scheme - a_0 --> plus(+) - a_1 --> multiply(*) - x(Hashed Messaage) --> multiply - multiply --> plus - plus --> share_y - end - - nullifier --> proof(ZKP) - root --> proof - share_y --> proof - end - -``` diff --git a/src/protocol_spec.md b/src/protocol_spec.md new file mode 100644 index 0000000..a848904 --- /dev/null +++ b/src/protocol_spec.md @@ -0,0 +1,69 @@ +# Technical side of RLN + +*This topic is a less strict version of specifications. If you want more formal description, you can find specs in the [references](./references.md)* + +___ + +As it's been said **RLN** consists of three parts: +* User registration +* User interaction (signalling) +* User removal (slashing) - additional part + +Well, let's discuss them. + +## User registration +First part of **RLN** is registration. There is nothing special in **RLN** registration; it's almost the same process as in other protocols/apps with anonymous environments: we need to create Merkle Tree and every participant must submit the `commitment` and place it in the Merkle Tree, and after that to interact with the app every participant will create zkProof's, that she is a *member of the tree*. + +We'll use *Incremental Merkle Tree*, as it more *GAS-effective*. + +The slight difference is that we must enable *secret sharing* scheme (to split the `commitment` into parts). Thus, generation of the `commitment` is different. + +Each member randomly generate secret key, that is denoted by `a_0`. Identity commitment `q` is the hash (Poseidon) of the secret key: `q = Poseidon(a_0)`. + +RLN would have no sense if there was no punishment for spam, that's why to become a member a user have to provide a certain form of stake. + +# Diagram + +```mermaid +flowchart TB + + subgraph Generate Secret Key + random0(Random 32 bytes) --> a_0(Secret Key) + random1(Random 32 bytes) --> a_0 + end + + subgraph RLN + + subgraph Identity Commitment + a_0 --> h0(Poseidon Hash) + h0 --> q(Identity Commitment) + end + + subgraph Calculate Internal Nullifier + a_0 --> h1(Poseidon Hash) + epoch(Epoch) --> h1 + h1 --> a_1 + rln_identifier(RLN Identifier) --> h2(Poseidon Hash) + a_1 --> h2 + h2 --> nullifier(RLN Internal Nullifier) + end + + subgraph Merkle Tree + q --> merkle_tree_inclusion_proof(Merkle Tree Inclusion Proof) + merkle_tree_inclusion_proof --> root(ZKP of Merkle Tree Root) + end + + subgraph Shamirs Secret Scheme + a_0 --> plus(+) + a_1 --> multiply(*) + x(Hashed Messaage) --> multiply + multiply --> plus + plus --> share_y + end + + nullifier --> proof(ZKP) + root --> proof + share_y --> proof + end + +``` diff --git a/src/references.md b/src/references.md index d3104c1..ad620f6 100644 --- a/src/references.md +++ b/src/references.md @@ -1,6 +1,6 @@ # References -* [First proposal of RLN by Barry WhiteHat](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](https://ethresear.ch/t/semaphore-rln-rate-limiting-nullifier-for-spam-prevention-in-anonymous-p2p-setting/5009) * [RLN Overview by Blagoj](https://medium.com/privacy-scaling-explorations/rate-limiting-nullifier-a-spam-protection-mechanism-for-anonymous-environments-bbe4006a57d) @@ -10,4 +10,10 @@ * [Understand zkSNARK](https://vitalik.ca/general/2016/12/10/qap.html) -* [Circom docs](https://docs.circom.io/) \ No newline at end of file +* [Circom Docs](https://docs.circom.io/) + +* [rln-js](https://github.com/Rate-Limiting-Nullifier/rlnjs) + +* [zerokit-rln](https://github.com/vacp2p/zerokit) + +* [Incremental Merkle Tree paper](https://arxiv.org/pdf/2105.06009v1.pdf) \ No newline at end of file diff --git a/src/rln.md b/src/rln.md index 6e74eea..d650c41 100644 --- a/src/rln.md +++ b/src/rln.md @@ -1,6 +1,8 @@ # RLN -**RLN** (Rate-Limiting Nullifier) is part of (**PSE**) [Privacy & Scaling Explorations](https://appliedzkp.org), a multidisciplinary team supported by the Ethereum Foundation. PSE explores new use cases for zero-knowledge proofs and other cryptographic primitives. +**RLN** (Rate-Limiting Nullifier) is a zk-gadget/protocol that enables spam prevention mechanism for anonymous environments. + +**RLN** is part of (**PSE**) [Privacy & Scaling Explorations](https://appliedzkp.org), a multidisciplinary team supported by the Ethereum Foundation. PSE explores new use cases for zero-knowledge proofs and other cryptographic primitives. ![alt text](./images/logo.svg) diff --git a/src/sss.md b/src/sss.md index a898dc1..3431f36 100644 --- a/src/sss.md +++ b/src/sss.md @@ -1,4 +1,4 @@ -# Shamirs Secret Sharing Scheme +# Shamir's Secret Sharing Scheme *Shamirs Secret Sharing* allows to split the secret to `n` parts and restore it upon presentation any `m` parts (`m <= n`) diff --git a/src/under_the_hood.md b/src/under_the_hood.md index 2640050..c800434 100644 --- a/src/under_the_hood.md +++ b/src/under_the_hood.md @@ -3,5 +3,5 @@ This section provides deep and technical **RLN** overview. We'll discuss: +* Technical side of **RLN** (specification demo) * How circuits are implemented -* **RLN** in general (diagram) diff --git a/src/what_is_rln.md b/src/what_is_rln.md index 1973a98..b0935b7 100644 --- a/src/what_is_rln.md +++ b/src/what_is_rln.md @@ -10,11 +10,11 @@ The anonymity property opens up the possibility for spam attack and sybil attack **RLN** helps us identify and "kick" the spammer. -Moreover RLN can be useful not only to prevent a 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). +Moreover **RLN** can be useful not only to prevent a 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). ## How it works -The RLN 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 a separate storage and compute resources for the application. The three parts are: +The **RLN** 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 a separate storage and compute resources for the application. The three parts are: * User registration * User interaction * User removal (slashing) @@ -23,7 +23,7 @@ The RLN construct’s functionality consists of three parts, which when integrat Before registering to the application the user needs to generate a secret key and derive an identity commitment from the secret key using the `Poseidon` hash function `identityCommitment = posseidonHash(secretKey)`. -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 the RLN construct we use the Incremental Merkle Tree algorithm), 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. +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 the **RLN** construct we use the Incremental Merkle Tree algorithm), 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. ### User interaction For each interaction that the user wants to make with the application, the user must generate a zero-knowledge proof which ensures the other participants (the verifiers) that they are a valid member of the application and their identity commitment is part of the membership Merkle tree. @@ -42,6 +42,4 @@ Thus, users have to split their `secret_key` into `n` parts and for every intera If they make more interactions than allowed per epoch their secret key can be fully reconstructed. ### User removal (slashing) -The final property of the RLN 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. User’s 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 wants to remove themselves, which they can always do because they know their secret key). When an economic stake is present, the RLN 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 a proof. - - +The final property of the **RLN** 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. User’s 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 wants to remove themselves, which they can always do because they know their secret key). When an economic stake is present, the **RLN** 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 a proof.