update code documentation

Author: najienka

hardhat.config.ts

@@ -10,7 +10,7 @@ dotEnvConfig();
 
 const config: HardhatUserConfig = {
   solidity: {
-    version: "0.8.24",
+    version: "0.8.28",
     settings: {
       optimizer: {
         enabled: true,

script/single-deployment/DeployRandomnessReceiver.s.sol

@@ -14,7 +14,6 @@ import {Factory} from "src/factory/Factory.sol";
 /// @title DeploySignatureSchemeAddressProvider
 /// @dev Script for deploying MockRandomnessReceiver contract.
 contract DeployRandomnessReceiver is JsonUtils {
-
     function run() public virtual {
         address randomnessSenderAddr =
             _readAddressFromJsonInput(Constants.DEPLOYMENT_INPUT_JSON_PATH, "randomnessSenderProxyAddress");

script/single-deployment/DeployRandomnessSender.s.sol

@@ -17,7 +17,6 @@ import {Factory} from "src/factory/Factory.sol";
 /// @dev Script for deploying or upgrading the RandomnessSender contract.
 /// Reads an environment variable to determine if it's an upgrade (new implementation only) or a full deployment.
 contract DeployRandomnessSender is JsonUtils, EnvReader {
-
     /// @notice Runs the deployment script, checking the environment variable to determine whether to upgrade or deploy.
     function run() public virtual {
         bool isUpgrade = vm.envBool("IS_UPGRADE");

script/single-deployment/DeploySignatureSchemeAddressProvider.s.sol

@@ -15,7 +15,6 @@ import {Factory} from "src/factory/Factory.sol";
 /// @title DeploySignatureSchemeAddressProvider
 /// @dev Script for deploying SignatureSchemeAddressProvider contract.
 contract DeploySignatureSchemeAddressProvider is JsonUtils, EnvReader {
-
     function run() public virtual {
         deploySignatureSchemeAddressProvider();
     }

script/single-deployment/DeploySignatureSender.s.sol

@@ -18,7 +18,6 @@ import {Factory} from "src/factory/Factory.sol";
 /// @dev Script for deploying or upgrading the SignatureSender contract.
 /// Reads an environment variable to determine if it's an upgrade (new implementation only) or a full deployment.
 contract DeploySignatureSender is JsonUtils, SignatureUtils, EnvReader {
-
     function run() public virtual {
         bool isUpgrade = vm.envBool("IS_UPGRADE");
         address signatureSchemeAddressProvider =

src/RandomnessReceiverBase.sol

@@ -1,42 +1,50 @@
-// SPDX-License-Identifier: MIT
+/// SPDX-License-Identifier: MIT
 pragma solidity ^0.8;
 
 import {IRandomnessReceiver} from "./interfaces/IRandomnessReceiver.sol";
 import {IRandomnessSender} from "./interfaces/IRandomnessSender.sol";
 
+/// @title RandomnessReceiverBase contract
+/// @author Randamu
+/// @notice Abstract contract to facilitate receiving randomness from an external source.
+/// @dev This contract ensures that only a designated randomness sender can provide randomness values.
 abstract contract RandomnessReceiverBase is IRandomnessReceiver {
+    /// @notice The contract responsible for providing randomness.
+    /// @dev This is an immutable reference set at deployment.
     IRandomnessSender public immutable randomnessSender;
 
+    /// @notice Ensures that only the designated randomness sender can call the function.
     modifier onlyRandomnessSender() {
         require(msg.sender == address(randomnessSender), "Only randomnessSender can call");
         _;
     }
 
+    /// @notice Initializes the contract with a specified randomness sender.
+    /// @dev Ensures that the provided sender address is non-zero.
+    /// @param _randomnessSender The address of the randomness sender contract.
     constructor(address _randomnessSender) {
         require(_randomnessSender != address(0), "Cannot set zero address as randomness sender");
         randomnessSender = IRandomnessSender(_randomnessSender);
     }
 
-    /**
-     * @dev See {IRandomnessSender-requestRandomness}.
-     */
+    /// @notice Requests randomness from the designated randomness sender.
+    /// @dev Calls the `requestRandomness` function on the randomness sender contract.
+    /// @return requestID The unique identifier of the randomness request.
     function requestRandomness() internal returns (uint256 requestID) {
         requestID = randomnessSender.requestRandomness();
     }
 
-    /**
-     * @dev See {IRandomnessReceiver-receiveRandomness}.
-     */
+    /// @notice Receives randomness for a specific request ID from the designated sender.
+    /// @dev This function is restricted to calls from the designated randomness sender.
+    /// @param requestID The unique identifier of the randomness request.
+    /// @param randomness The generated random value as a `bytes32` type.
     function receiveRandomness(uint256 requestID, bytes32 randomness) external onlyRandomnessSender {
         onRandomnessReceived(requestID, randomness);
     }
 
-    /**
-     * @notice Handles the reception of a generated random value for a specific request.
-     * @dev This internal function is called when randomness is received for the given `requestID`.
-     * It is intended to be overridden by derived contracts to implement custom behavior.
-     * @param requestID The unique identifier of the randomness request.
-     * @param randomness The generated random value, provided as a `bytes32` type.
-     */
+    /// @notice Handles the reception of a generated random value for a specific request.
+    /// @dev This internal function is intended to be overridden by derived contracts to implement custom behavior.
+    /// @param requestID The unique identifier of the randomness request.
+    /// @param randomness The generated random value, provided as a `bytes32` type.
     function onRandomnessReceived(uint256 requestID, bytes32 randomness) internal virtual;
 }

src/interfaces/IRandomnessReceiver.sol

@@ -1,13 +1,14 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8;
 
+/// @title IRandomnessReceiver interface
+/// @author Randamu
+/// @notice Interface for randomness consumer contracts that receive randomness via callbacks.
 interface IRandomnessReceiver {
-    /**
-     * @notice Receives a random value associated with a specific request.
-     * @dev This function is called to provide the randomness generated for a given request ID.
-     * It is intended to be called by a trusted source that provides randomness.
-     * @param requestID The unique identifier of the randomness request.
-     * @param randomness The generated random value, provided as a `bytes32` type.
-     */
+    /// @notice Receives a random value associated with a specific request.
+    /// @dev This function is called to provide the randomness generated for a given request ID.
+    /// It is intended to be called by a trusted source that provides randomness.
+    /// @param requestID The unique identifier of the randomness request.
+    /// @param randomness The generated random value, provided as a `bytes32` type.
     function receiveRandomness(uint256 requestID, bytes32 randomness) external;
 }

src/interfaces/IRandomnessSender.sol

@@ -3,43 +3,35 @@ pragma solidity ^0.8;
 
 import "../libraries/TypesLib.sol";
 
-// todo subscription and payments
-// todo we could embed the following for subscription and payments - subscriptionID, numberOfRequestTxConfirmations, callbackGasLimit, numRandomValues
-// todo check for potential gaps in using uint256 as id compared to bytes32
+/// @title IRandomnessSender interface
+/// @author Randamu
+/// @notice Interface for randomness sender contract which sends randomness via callbacks to randomness consumer contracts.
 interface IRandomnessSender {
-    /**
-     * @notice Requests the generation of a random value for a specified blockchain height.
-     * @dev Initiates a randomness request.
-     * The generated randomness will be associated with the returned `requestID`.
-     * @return requestID The unique identifier assigned to this randomness request.
-     */
+    /// @notice Requests the generation of a random value for a specified blockchain height.
+    /// @dev Initiates a randomness request.
+    /// The generated randomness will be associated with the returned `requestID`.
+    /// @return requestID The unique identifier assigned to this randomness request.
     function requestRandomness() external returns (uint256 requestID);
-    /**
-     * @notice Retrieves a specific request by its ID.
-     * @dev This function returns the Request struct associated with the given requestId.
-     * @param requestId The ID of the request to retrieve.
-     * @return The Request struct corresponding to the given requestId.
-     */
+
+    /// @notice Retrieves a specific request by its ID.
+    /// @dev This function returns the Request struct associated with the given requestId.
+    /// @param requestId The ID of the request to retrieve.
+    /// @return The Request struct corresponding to the given requestId.
     function getRequest(uint256 requestId) external view returns (TypesLib.RandomnessRequest memory);
 
-    /**
-     * @notice Sets signatureSender contract address.
-     * @param newSignatureSender The new address to set.
-     */
+    /// @notice Sets signatureSender contract address.
+    /// @param newSignatureSender The new address to set.
     function setSignatureSender(address newSignatureSender) external;
 
-    /**
-     * @notice Retrieves all requests.
-     * @dev This function returns an array of all Request structs stored in the contract.
-     * @return An array containing all the Request structs.
-     */
+    /// @notice Retrieves all requests.
+    /// @dev This function returns an array of all Request structs stored in the contract.
+    /// @return An array containing all the Request structs.
     function getAllRequests() external view returns (TypesLib.RandomnessRequest[] memory);
-    /**
-     * @notice Generates a message from the given request.
-     * @dev Creates a hash-based message using the `DST` and `nonce` fields of the `Request` struct.
-     * The resulting message is the hash of the encoded values, packed into a byte array.
-     * @param r The `Request` struct containing the data for generating the message.
-     * @return A byte array representing the hashed and encoded message.
-     */
+
+    /// @notice Generates a message from the given request.
+    /// @dev Creates a hash-based message using the `DST` and `nonce` fields of the `Request` struct.
+    /// The resulting message is the hash of the encoded values, packed into a byte array.
+    /// @param r The `Request` struct containing the data for generating the message.
+    /// @return A byte array representing the hashed and encoded message.
     function messageFrom(TypesLib.RandomnessRequest memory r) external pure returns (bytes memory);
 }

src/interfaces/ISignatureReceiver.sol

@@ -1,14 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8;
 
+/// @title ISignatureReceiver interface
+/// @author Randamu
+/// @notice Interface for contracts receiving signatures via callbacks.
 interface ISignatureReceiver {
-    /// Setters
-
-    /**
-     * @notice Receives a signature for a specified request.
-     * @dev This function is intended to be called to provide a signature for the given `requestID`.
-     * @param requestID The unique identifier of the request associated with the signature.
-     * @param signature The cryptographic signature of the message, provided as a byte array.
-     */
+    /// @notice Receives a signature for a specified request.
+    /// @dev This function is intended to be called to provide a signature for the given `requestID`.
+    /// @param requestID The unique identifier of the request associated with the signature.
+    /// @param signature The cryptographic signature of the message, provided as a byte array.
     function receiveSignature(uint256 requestID, bytes calldata signature) external;
 }

src/interfaces/ISignatureScheme.sol

@@ -1,36 +1,30 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8;
 
+/// @title ISignatureScheme interface
+/// @author Randamu
+/// @notice Interface for signature schemes, e.g., BN254, BLS, etc.
 interface ISignatureScheme {
-    /// Getters
-
-    /**
-     * @notice Returns the scheme identifier as a string, e.g., "BN254", "BLS12-381", "TESS"
-     */
+    /// @notice Returns the scheme identifier as a string, e.g., "BN254", "BLS12-381", "TESS"
     function SCHEME_ID() external returns (string memory);
 
-    /**
-     * @notice Verifies a signature using the given signature scheme.
-     * @param message The message that was signed. Message is a G1 point represented as bytes.
-     * @param signature The signature to verify. Signature is a G1 point represented as bytes.
-     * @param publicKey The public key of the signer. Public key is a G2 point represented as bytes.
-     * @return isValid boolean which evaluates to true if the signature is valid, false otherwise.
-     */
+    /// @notice Verifies a signature using the given signature scheme.
+    /// @param message The message that was signed. Message is a G1 point represented as bytes.
+    /// @param signature The signature to verify. Signature is a G1 point represented as bytes.
+    /// @param publicKey The public key of the signer. Public key is a G2 point represented as bytes.
+    /// @return isValid boolean which evaluates to true if the signature is valid, false otherwise.
     function verifySignature(bytes calldata message, bytes calldata signature, bytes calldata publicKey)
         external
         view
         returns (bool isValid);
 
-    /**
-     * @notice Hashes a message to a G1 point on the elliptic curve.
-     * @param message The message to be hashed.
-     * @return (uint256, uint256) A point on the elliptic curve in G1, represented as x and y coordinates.
-     */
+    /// @notice Hashes a message to a G1 point on the elliptic curve.
+    /// @param message The message to be hashed.
+    /// @return (uint256, uint256) A point on the elliptic curve in G1, represented as x and y coordinates.
     function hashToPoint(bytes memory message) external view returns (uint256, uint256);
-    /**
-     * @notice Hashes a message to a G1 point on the elliptic curve.
-     * @param message The message to be hashed.
-     * @return bytes A point on the elliptic curve in G1, represented as bytes.
-     */
+
+    /// @notice Hashes a message to a G1 point on the elliptic curve.
+    /// @param message The message to be hashed.
+    /// @return bytes A point on the elliptic curve in G1, represented as bytes.
     function hashToBytes(bytes calldata message) external view returns (bytes memory);
 }