Refinements of RLN on mainnet spec

standards/core/rln-contract.md

@@ -45,27 +45,37 @@ The contract MUST provide the following functionalities:
 - withdraw a deposit.
 
 A membership _holder_ is the entity that controls the secret associated with the respective RLN commitment.
-A membership _keeper_ is the entity that controls the Ethereum address used to register that membership.
+A membership _keeper_ is the sender of the transaction that registered that membership.
+Transaction sender in this context is defined as `msg.sender` in Solidity semantics.
+The contract MUST support transactions sent directly from externally-owned accounts (EOA).
+The contract MAY support transactions sent from an EOA via a chain of contract calls,
+in which case the last contract in the call chain MAY be designated as the membership keeper.
+The contract MAY also support meta-transactions sent via paymasters or relayers,
+which MAY require additional authentication-related logic.
+
 The holder and the keeper MAY be different entities for the same membership.
 When authorizing membership-related requests,
 the contract SHOULD distinguish between the keeper and non-keepers,
 and MAY also use additional criteria.
 
 Contract parameters and their RECOMMENDED values for the initial mainnet deployment are as follows:
 
-| Parameter                                               | Symbol    | Value    | Units                |
-| ------------------------------------------------------- | --------- | -------- | -------------------- |
-| Epoch length                                            | `epoch`   | `10`     | minutes              |
-| Maximum total rate limit of all memberships in the tree | `R_{max}` | `160000` | messages per `epoch` |
-| Minimum rate limit of one membership                    | `r_{min}` | `20`     | messages per `epoch` |
-| Maximum rate limit of one membership                    | `r_{max}` | `600`    | messages per `epoch` |
-| Membership price for `1` message per epoch              | `p_u`     | `0.05`   | `USD`                |
-| Membership expiration term                              | `T`       | `180`    | days                 |
-| Membership grace period                                 | `G`       | `30`     | days                 |
-| Accepted tokens                                         |           | `DAI`    |                      |
+| Parameter                                                 | Symbol    | Value    | Units              |
+| --------------------------------------------------------- | --------- | -------- | ------------------ |
+| Epoch length                                              | `t_{ep}`  | `600`    | seconds            |
+| Maximum total rate limit of all memberships in the tree   | `R_{max}` | `160000` | messages per epoch |
+| Minimum rate limit of one membership                      | `r_{min}` | `20`     | messages per epoch |
+| Maximum rate limit of one membership                      | `r_{max}` | `600`    | messages per epoch |
+| Membership expiration term                                | `T`       | `180`    | days               |
+| Membership grace period                                   | `G`       | `30`     | days               |
+| Membership price for `1` message per epoch for period `T` | `p_u`     | `0.05`   | `USD`              |
+| Accepted tokens                                           |           | `DAI`    |                    |
 
 The pricing function SHOULD be linear in the rate limit per epoch.
 
+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".
+
 ## Membership lifecycle
 
 Any existing membership MUST always be in exactly one of the following states:
@@ -127,22 +137,32 @@ Availability of membership-specific functionalities[^2] MUST be as follows:
 
 ### Register a membership
 
-Membership registration is subject to the following conditions:
-- If there are _Expired_ memberships in the RLN tree, the new membership MUST overwrite an _Expired_ membership.
-- The new membership SHOULD overwrite the membership that has been _Expired_ for the longest time.
+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).
 - If a new membership A overwrites an _Expired_ membership B:
 	- membership B MUST become _ErasedAwaitsWithdrawal_;
 	- the current total rate limit MUST be decremented by the rate limit of membership B;
 	- the contract MUST take all necessary steps to ensure that the keeper of membership B can withdraw their deposit later.
-- Registration MUST fail if the total rate limit of _Active_, _GracePeriod_, and _Expired_ memberships, including the one being created, would exceed `R_{max}`.
 - Registration MUST fail if the requested rate limit for a new membership is lower than `r_{min}` or higher than `r_{max}`.
 - The keeper MUST lock up a deposit to register a membership.
 - The keeper MUST specify the rate limit[^3] of a membership at registration time.
 - The size of the deposit MUST depend on the specified rate limit.
 - In case of a successful registration:
 	- the new membership MUST become _Active_;
+	- the new membership MUST have an expiration time `T` and a grace period `G`;
 	- the current total rate limit MUST be incremented by the rate limit of the new membership.
-- A membership MUST have an expiration time `T` and a grace period `G`.
 
 [^3]: A user-facing application SHOULD suggest default rate limits to the keeper (see Implementation Suggestions).
 
@@ -167,6 +187,10 @@ Deposit withdrawal is subject to the following conditions:
 
 At initial mainnet deployment, the contract MUST have an _Owner_.
 The _Owner_ MUST be able to change the values of all contract parameters.
+The updated parameter values MUST apply to all new memberships.
+The parameters of existing memberships MUST NOT change if the _Owner_ updates global parameters.
+The contract MAY restrict extensions for memberships created before the latest parameter update.
+
 The _Owner_ MUST be able to pause any of the following contract functionalities:
 - register a membership;
 - extend a membership;
@@ -180,6 +204,17 @@ and the membership set SHOULD be migrated.
 
 ## Implementation Suggestions
 
+### Choosing Which _Expired_ Memberships to Overwrite
+
+When registering a new membership, the smart contract may need to decide which _Expired_ memberships to overwrite.
+The criteria for this selection can vary depending on the implementation.
+
+Key considerations include:
+- To minimize gas costs, it's better to overwrite a single high-rate membership rather than multiple low-rate ones.
+- To encourage timely withdrawals, it's better to overwrite memberships that have been _Expired_ for a long time.
+
+### Considerations for User-facing Applications
+
 User-facing applications SHOULD suggest one or more rate limits (tiers) to simplify user selection among the following RECOMMENDED options:
 - `20` messages per epoch as low-tier;
 - `200` messages per epoch as mid-tier;