docs: natspec, docgen

.husky/pre-commit

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
+yarn docgen && git add docs
 npx lint-staged

contracts/PoseidonHasher.sol

@@ -5,6 +5,8 @@
 pragma solidity 0.8.15;
 
 interface IPoseidonHasher {
+    /// @notice Hashes the input using the Poseidon hash function, n = 2, second input is the constant 0
+    /// @param input The input to hash
     function hash(uint256 input) external pure returns (uint256 result);
 }
 

contracts/Rln.sol

@@ -5,17 +5,34 @@ pragma solidity 0.8.15;
 import {IPoseidonHasher} from "./PoseidonHasher.sol";
 
 contract RLN {
+    /// @notice The deposit amount required to register as a member
     uint256 public immutable MEMBERSHIP_DEPOSIT;
+
+    /// @notice The depth of the merkle tree
     uint256 public immutable DEPTH;
+
+    /// @notice The size of the merkle tree, i.e 2^depth
     uint256 public immutable SET_SIZE;
 
+    /// @notice The index of the next member to be registered
     uint256 public idCommitmentIndex;
+
+    /// @notice The amount of eth staked by each member
     mapping(uint256 => uint256) public stakedAmounts;
+
+    /// @notice The membership status of each member
     mapping(uint256 => bool) public members;
 
+    /// @notice The Poseidon hasher contract
     IPoseidonHasher public poseidonHasher;
 
+    /// Emitted when a new member is added to the set
+    /// @param idCommitment The idCommitment of the member
+    /// @param index The index of the member in the set
     event MemberRegistered(uint256 idCommitment, uint256 index);
+
+    /// Emitted when a member is removed from the set
+    /// @param idCommitment The idCommitment of the member
     event MemberWithdrawn(uint256 idCommitment);
 
     constructor(
@@ -29,6 +46,8 @@ contract RLN {
         poseidonHasher = IPoseidonHasher(_poseidonHasher);
     }
 
+    /// Allows a user to register as a member
+    /// @param idCommitment The idCommitment of the member
     function register(uint256 idCommitment) external payable {
         require(
             msg.value == MEMBERSHIP_DEPOSIT,
@@ -37,6 +56,8 @@ contract RLN {
         _register(idCommitment, msg.value);
     }
 
+    /// Allows batch registration of members
+    /// @param idCommitments array of idCommitments
     function registerBatch(uint256[] calldata idCommitments) external payable {
         uint256 idCommitmentlen = idCommitments.length;
         require(idCommitmentlen > 0, "RLN, registerBatch: batch size zero");
@@ -53,6 +74,9 @@ contract RLN {
         }
     }
 
+    /// Registers a member
+    /// @param idCommitment The idCommitment of the member
+    /// @param stake The amount of eth staked by the member
     function _register(uint256 idCommitment, uint256 stake) internal {
         require(
             !members[idCommitment],
@@ -67,6 +91,9 @@ contract RLN {
         idCommitmentIndex += 1;
     }
 
+    /// Allows a user to slash a batch of members
+    /// @param secrets array of idSecretHashes
+    /// @param receivers array of addresses to receive the funds
     function withdrawBatch(
         uint256[] calldata secrets,
         address payable[] calldata receivers
@@ -82,10 +109,16 @@ contract RLN {
         }
     }
 
+    /// Allows a user to slash a member
+    /// @param secret The idSecretHash of the member
     function withdraw(uint256 secret, address payable receiver) external {
         _withdraw(secret, receiver);
     }
 
+    /// Slashes a member by removing them from the set, and transferring their
+    /// stake to the receiver
+    /// @param secret The idSecretHash of the member
+    /// @param receiver The address to receive the funds
     function _withdraw(uint256 secret, address payable receiver) internal {
         require(
             receiver != address(0),
@@ -120,6 +153,9 @@ contract RLN {
         emit MemberWithdrawn(idCommitment);
     }
 
+    /// Hashes a value using the Poseidon hasher
+    /// NOTE: The variant of Poseidon we use accepts only 1 input, assume n=2, and the second input is 0
+    /// @param input The value to hash
     function hash(uint256 input) internal view returns (uint256) {
         return poseidonHasher.hash(input);
     }