Merge pull request #3 from randa-mu/feat/randomness

Add randomness consumer contract and deployment script, and readme updates

Author: najienka

.gitignore

@@ -19,3 +19,6 @@ ignition/deployments/chain-31337
 
 # Foundry files
 /broadcast
+
+# contract interaction files
+foundry.txt 

.gitmodules

@@ -7,3 +7,6 @@
 [submodule "lib/blocklock-solidity"]
 	path = lib/blocklock-solidity
 	url = https://github.com/randa-mu/blocklock-solidity
+[submodule "lib/randomness-solidity"]
+	path = lib/randomness-solidity
+	url = https://github.com/randa-mu/randomness-solidity

README.md

@@ -59,6 +59,8 @@ source .env
 forge script script/SealedBidAuction.s.sol --rpc-url $CALIBRATION_TESTNET_RPC_URL --private-key $CALIBRATION_TESTNET_PRIVATE_KEY --broadcast
 ```
 
+For common deployment issues (e.g., setting the gas estimate multiplier -g, --gas-estimate-multiplier) with the Filecoin calibration testnet, please refer to the  [FEVM (Ethereum Virtual Machine on Filecoin) Foundry toolkit](https://github.com/filecoin-project/fevm-foundry-kit).
+
 
 ## How It Works
 1. Encrypting Your Bid (Off-Chain): Bidders encrypt their bid amounts off-chain, generating ciphertexts for submission.
@@ -75,6 +77,5 @@ forge script script/SealedBidAuction.s.sol --rpc-url $CALIBRATION_TESTNET_RPC_UR
 Check out the detailed tutorial on [our blog](https://drand.love/blog/2025/03/04/onchain-sealed-bid-auction/).
 
 
-
 ## Licensing
 This source code is licensed under the MIT License which can be accessed [here](LICENSE).

lib/blocklock-solidity

@@ -7,3 +7,4 @@ config/=config/
 
 @openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
 @blocklock-solidity/src/=lib/blocklock-solidity/src/
+@randomness-solidity/src/=lib/randomness-solidity/src/

lib/randomness-solidity

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Script} from "forge-std/Script.sol";
+import {console} from "forge-std/console.sol";
+
+import {RandomnessConsumer} from "src/RandomnessConsumer.sol";
+
+contract RandomnessConsumerScript is Script {
+    function run() external {
+        vm.broadcast();
+        RandomnessConsumer randomnessConsumer = new RandomnessConsumer();
+
+        console.log("RandomnessConsumer deployed at: ", address(randomnessConsumer));
+    }
+}

remappings.txt

@@ -8,9 +8,13 @@ import {SealedBidAuction} from "src/SealedBidAuction.sol";
 
 contract SealedBidAuctionScript is Script {
     function run() external {
-        uint256 biddingDurationInBlocks = block.number + 200;
+        console.log("Current chain height: ", block.number);
+
+        uint256 biddingDurationInBlocks = block.number + 10;
         address blocklockSenderContractAddress = 0xfF66908E1d7d23ff62791505b2eC120128918F44;
 
+        console.log("Bid closes at chain height: ", biddingDurationInBlocks);
+
         vm.broadcast();
         SealedBidAuction auction = new SealedBidAuction(biddingDurationInBlocks, blocklockSenderContractAddress);
 

script/RandomnessConsumer.s.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {RandomnessReceiverBase} from "@randomness-solidity/src/RandomnessReceiverBase.sol";
+
+/// @title Randomness Consumer contract
+/// @author Randamu developers
+/// @notice A mock RandomnessConsumer contract that makes use of the Randamu randomness-solidity
+/// library to request verifiable randomness
+/// The library is available at: https://github.com/randa-mu/randomness-solidity/tree/main
+/// The library also contains logic for array shuffling using Feistel shuffle
+/// and selecting n items randomly from an array
+contract RandomnessConsumer is RandomnessReceiverBase {
+    // RandomnessSender proxy address on Filecoin calibration testnet
+    address public constant RANDOMNESS_SENDER = 0x9c789bc7F2B5c6619Be1572A39F2C3d6f33001dC;
+
+    bytes32 public randomness;
+    uint256 public requestId;
+
+    constructor() RandomnessReceiverBase(RANDOMNESS_SENDER) {}
+
+    /// @dev Requests randomness.
+    /// This function calls the `requestRandomness` method to request a random value.
+    /// The `requestId` is updated with the ID returned from the randomness request.
+    function rollDice() external {
+        requestId = requestRandomness();
+    }
+
+    /// @dev Callback function that is called when randomness is received.
+    /// @param requestID The ID of the randomness request that was made.
+    /// @param _randomness The random value received.
+    /// This function verifies that the received `requestID` matches the one that
+    /// was previously stored. If they match, it updates the `randomness` state variable
+    /// with the newly received random value.
+    /// Reverts if the `requestID` does not match the stored `requestId`, ensuring that
+    /// the randomness is received in response to a valid request.
+    function onRandomnessReceived(uint256 requestID, bytes32 _randomness) internal override {
+        require(requestId == requestID, "Request ID mismatch");
+        randomness = _randomness;
+    }
+}

script/SealedBidAuction.s.sol

@@ -8,13 +8,21 @@ import {AbstractBlocklockReceiver} from "@blocklock-solidity/src/AbstractBlocklo
 // Import ReentrancyGuard which is an Openzeppelin solidity library that helps prevent reentrant calls to a function.
 import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 
+/// @title Sealed Bid Auction interface
+/// @author Randamu developers
+/// @notice An interface for a sealed bid auction smart contract
+/// allowing encrypted bids which are decrypted at a future block number.
 interface ISealedBidAuction {
     function placeSealedBid(TypesLib.Ciphertext calldata sealedBid) external payable returns (uint256);
     function withdrawRefund() external;
     function fulfillHighestBid() external payable;
     function finalizeAuction() external;
 }
 
+/// @title Sealed Bid Auction contract
+/// @author Randamu developers
+/// @notice A bid smart contract which allows sealed bids to be made in an auction.
+/// The bids are automatically decrypted at a future block number (block number that closes the bidding window).
 contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, ReentrancyGuard {
     struct Bid {
         uint256 bidID; // Unique identifier for the bid
@@ -77,11 +85,12 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         seller = msg.sender;
     }
 
-    // BID PHASES
-    /**
-     * Phase 1. Bidding Phase
-     */
-    // Submit a sealed bid
+    /// BID PHASES
+
+    /// @dev Phase 1. Bidding Phase
+    /// @notice Submit a sealed bid to participate in the auction.
+    /// @param sealedBid The encrypted bid amount to submit to the auction.
+    /// @return bidID The unique identifier for the submitted bid.
     function placeSealedBid(TypesLib.Ciphertext calldata sealedBid)
         external
         payable
@@ -111,10 +120,10 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         return bidID;
     }
 
-    /**
-     * Phase 2. Reveal Phase
-     */
-    // Unseal sealed bid
+    /// @dev Phase 2. Reveal Phase
+    /// @notice Unseals the sealed bid after the bidding phase has ended.
+    /// @param requestID The unique identifier for the bid to unseal.
+    /// @param decryptionKey The key used to decrypt the sealed bid.
     function receiveBlocklock(uint256 requestID, bytes calldata decryptionKey)
         external
         override
@@ -140,6 +149,9 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         emit BidUnsealed(bid.bidID, bid.bidder, bid.unsealedBid);
     }
 
+    /// @dev Updates the highest bid during the reveal phase.
+    /// @param bidID The unique identifier of the bid being evaluated.
+    /// @param unsealedBid The decrypted bid amount.
     function updateHighestBid(uint256 bidID, uint256 unsealedBid) internal {
         Bid storage bid = bidsById[bidID];
 
@@ -155,10 +167,8 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         emit BidUnsealed(bidID, bid.bidder, unsealedBid);
     }
 
-    /**
-     * Phase 3. Auction Finalization
-     */
-    // Withdraw refundable reserve amounts paid during bidding
+    /// @dev Phase 3. Auction Finalization
+    /// @notice Allows bidders (except the highest bidder) to withdraw refundable reserve amounts.
     function withdrawRefund() external onlyAfter(biddingEndBlock) onlyAfterBidsUnsealed nonReentrant {
         require(msg.sender != highestBidder, "Highest bidder cannot withdraw refund.");
         Bid memory bid = bids[msg.sender];
@@ -169,7 +179,8 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         emit ReservePriceClaimed(bid.bidID, msg.sender, amount);
     }
 
-    // Fulfil highest bid
+    /// @dev Fulfill the highest bid after the bidding ends and bids are unsealed.
+    /// @notice Only the highest bidder can fulfill the bid and pay the difference.
     function fulfillHighestBid() external payable onlyAfter(biddingEndBlock) onlyAfterBidsUnsealed {
         require(highestBid > 0, "Highest bid is zero.");
         require(msg.sender == highestBidder, "Only the highest bidder can fulfil.");
@@ -183,16 +194,23 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         emit HighestBidFulfilled(msg.sender, msg.value + RESERVE_PRICE);
     }
 
-    // Finalize auction
+    /// @dev Finalizes the auction and declares the winner.
+    /// @notice Marks the auction as ended and emits an event with the winning bid and bidder.
     function finalizeAuction() external onlyAfterBidsUnsealed {
         require(!auctionEnded, "Auction already finalised.");
         auctionEnded = true;
         emit AuctionEnded(highestBidder, highestBid);
     }
 
-    /**
-     * Getters
-     */
+    /// GETTERS
+
+    /// @dev Retrieves bid details using the bid ID.
+    /// @param bidID The unique identifier for the bid.
+    /// @return sealedBid The encrypted sealed bid.
+    /// @return decryptionKey The decryption key used for revealing the bid.
+    /// @return unsealedBid The decrypted bid amount.
+    /// @return bidder The address of the bidder.
+    /// @return revealed Whether the bid has been revealed.
     function getBidWithBidID(uint256 bidID)
         external
         view
@@ -211,6 +229,13 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         revealed = bidsById[bidID].revealed;
     }
 
+    /// @dev Retrieves bid details using the bidder's address.
+    /// @param bidder The address of the bidder.
+    /// @return sealedBid The encrypted sealed bid.
+    /// @return decryptionKey The decryption key used for revealing the bid.
+    /// @return unsealedBid The decrypted bid amount.
+    /// @return _bidder The address of the bidder.
+    /// @return revealed Whether the bid has been revealed.
     function getBidWithBidder(address bidder)
         external
         view
@@ -229,6 +254,9 @@ contract SealedBidAuction is ISealedBidAuction, AbstractBlocklockReceiver, Reent
         revealed = bidsById[bidderToBidID[bidder]].revealed;
     }
 
+    /// @dev Retrieves the current highest bid and bidder's address.
+    /// @return highestBidAmount The amount of the highest bid.
+    /// @return highestBidderAddress The address of the highest bidder.
     function getHighestBid() external view returns (uint256 highestBidAmount, address highestBidderAddress) {
         highestBidAmount = highestBid;
         highestBidderAddress = highestBidder;