This document describes membership management within the RLN smart contract, specifically addressing:
- membership-related contract functionality;
- suggested parameter values for the initial mainnet deployment;
- contract governance and upgradability.
Currently, this document focuses solely on membership-related functionality.
It might later evolve into a comprehensive contract specification.
As of August 2024, RLN is deployed only on Sepolia testnet ([source code](https://github.com/waku-org/waku-rlnv2-contract/blob/main/src/WakuRlnV2.sol)).
This document aims to outline the path to its mainnet deployment.
## Syntax
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
## Background
Rate-Limiting Nullifier (RLN) is a Zero-Knowledge (ZK) based gadget used for privacy-preserving rate limiting in Waku.
The RLN smart contract (referred to as "the contract" hereinafter) is the central component of the RLN architecture.
Users interact with the contract to manage their memberships
and obtain the necessary data for proof generation and verification.
Message transmission is handled by Waku RLN Relay nodes.
The sender of a message MUST prove its validity according to RLN requirements.
RLN Relay nodes MUST NOT relay invalid messages.
For the full specification of RLN Relay, see See [17/WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md).
## Contract overview
The contract MUST provide the following functionalities:
- register a membership;
- extend a membership;
- withdraw a deposit.
A membership _holder_ is the entity that controls the secret associated with the respective RLN commitment.
Note: epoch length means the same as `period` as defined in [17/WAKU2-RLN-RELAY](https://github.com/vacp2p/rfc-index/blob/main/waku/standards/core/17/rln-relay.md).
This specification uses the term "epoch length" instead of "period" to avoid confusion with "grace period".
Let us define the following aggregate rate limits:
-`R_{active}` is the total rate limit of all _Active_ memberships;
-`R_{grace_period}` is the total rate limit of all _GracePeriod_ memberships;
-`R_{expired}` is the total rate limit of all _Expired_ memberships;
-`r` is the requested rate limit of a new membership.
Let `R_{free} = R_{max} - R_{active} - R_{grace_period} - R_{expired}` be the free rate limit that is available without overwriting _Expired_ slots.
Membership registration is subject to the following requirements:
- If `r <= R_{free}`, the new membership MUST be registered (assuming all other necessary conditions hold). The new membership MAY overwrite one or multiple _Expired_ memberships.
- If `r > R_{free}`:
- if `r > R_{free} + R_{expired}`, registration MUST fail;
- if `r <= R_{free} + R_{expired}`, the new membership MUST be registered by overwriting some _Expired_ memberships.
- The sender of the registration transaction MAY specify a list of _Expired_ memberships whose slots will be overwritten. If the list is not provided, the contract MAY use any criteria to select _Expired_ memberships to overwrite (see Implementation Suggestions).
An _Expired_ membership is erased only when a new membership overwrites it or when its deposit is withdrawn.
Once erased (i.e., _Erased_ or _ErasedAwaitsWithdrawal_), the membership can no longer be used to send messages.
### Will my deposit be slashed if I exceed the rate limit?
This specification does not include slashing.
The deposit's current purpose is purely to protect the network from denial-of-service attacks through bandwidth capping.
### Do I need an extra deposit to extend my membership?
Membership extension requires no additional deposit.
The opportunity cost of locked-up capital and gas fees for extension transactions make extensions non-free,
which is sufficient for the initial mainnet deployment.
### Why this particular epoch length?
Epoch length is a global parameter defined in the contract.
Rate limits are defined in terms of the maximum allowed messages per epoch.
There is a trade-off between short and long epochs.
Longer epochs accommodate short-term usage peaks better,
but they increase memory requirements for RLN Relay nodes.
An epoch length of `10` minutes was chosen as a reasonable middle ground.
Each message contains a nullifier that proves its validity in terms of RLN.
Each RLN Relay node must store a nullifier log for the current epoch in memory.
A nullifier plus metadata is `128` bytes per message.
With a `10`-minute epoch, a high-tier user with a `1` message per second rate limit generates up to `600 * 128 / 1024 = 75 KiB` of nullifier log data per epoch.
This equates to, approximately:
-`73 MiB` for 1000 users;
-`732 MiB` for 10 thousand users.
### Why is there a cap on the total rate limit?
Total network bandwidth is a limited resource.
To avoid overstretching the network's capabilities for the initial mainnet deployment,
we define a cap `R_{max}` on the total rate limit.
