more docs on diagnostics

.gas-snapshot

@@ -1,22 +1,22 @@
-DeployTest:test_Deploy() (gas: 18806)
-LLMOracleCoordinatorTest:test_RegisterOracles() (gas: 85451094)
-LLMOracleCoordinatorTest:test_RevertWhen_ValidateWithoutWhitelist() (gas: 85992710)
-LLMOracleCoordinatorTest:test_ValidatorIsGenerator() (gas: 86132116)
-LLMOracleCoordinatorTest:test_WitValidation_NotEveryGeneratorGetFee() (gas: 86717264)
-LLMOracleCoordinatorTest:test_WithValidation() (gas: 86550482)
-LLMOracleCoordinatorTest:test_WithoutValidation() (gas: 86121119)
-LLMOracleRegistryTest:test_RegisterGeneratorOracle() (gas: 19039588)
-LLMOracleRegistryTest:test_RegisterValidatorOracle() (gas: 19145257)
-LLMOracleRegistryTest:test_RemoveFromWhitelist() (gas: 19155867)
-LLMOracleRegistryTest:test_RevertWhen_RegisterSameGeneratorTwice() (gas: 19043118)
-LLMOracleRegistryTest:test_RevertWhen_RegistryHasNotApprovedByOracle() (gas: 18819346)
-LLMOracleRegistryTest:test_RevertWhen_UnregisterBeforeEnoughTimeHasPassed() (gas: 19049072)
-LLMOracleRegistryTest:test_RevertWhen_UnregisterSameGeneratorTwice() (gas: 19040632)
-LLMOracleRegistryTest:test_UnregisterOracle() (gas: 19037706)
-LLMOracleRegistryTest:test_WithdrawStakesAfterUnregistering() (gas: 19242862)
-StatisticsTest:testFuzz_Average(uint8,uint8,uint8,uint8) (runs: 256, μ: 9729, ~: 9729)
-StatisticsTest:testFuzz_StandardDeviation(uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8) (runs: 256, μ: 21841, ~: 21835)
-StatisticsTest:testFuzz_Variance(uint8,uint8,uint8,uint8,uint8) (runs: 256, μ: 13876, ~: 13876)
-StatisticsTest:test_Average() (gas: 135675)
-StatisticsTest:test_StandardDeviation() (gas: 167016)
-StatisticsTest:test_Variance() (gas: 163714)
+DeployTest:test_Deploy() (gas: 18809)
+LLMOracleCoordinatorTest:test_RegisterOracles() (gas: 85619760)
+LLMOracleCoordinatorTest:test_RevertWhen_ValidateWithoutWhitelist() (gas: 86161487)
+LLMOracleCoordinatorTest:test_ValidatorIsGenerator() (gas: 86300915)
+LLMOracleCoordinatorTest:test_WitValidation_NotEveryGeneratorGetFee() (gas: 86886209)
+LLMOracleCoordinatorTest:test_WithValidation() (gas: 86719477)
+LLMOracleCoordinatorTest:test_WithoutValidation() (gas: 86290010)
+LLMOracleRegistryTest:test_RegisterGeneratorOracle() (gas: 19075287)
+LLMOracleRegistryTest:test_RegisterValidatorOracle() (gas: 19180970)
+LLMOracleRegistryTest:test_RemoveFromWhitelist() (gas: 19191592)
+LLMOracleRegistryTest:test_RevertWhen_RegisterSameGeneratorTwice() (gas: 19078826)
+LLMOracleRegistryTest:test_RevertWhen_RegistryHasNotApprovedByOracle() (gas: 18855003)
+LLMOracleRegistryTest:test_RevertWhen_UnregisterBeforeEnoughTimeHasPassed() (gas: 19084788)
+LLMOracleRegistryTest:test_RevertWhen_UnregisterSameGeneratorTwice() (gas: 19076362)
+LLMOracleRegistryTest:test_UnregisterOracle() (gas: 19073427)
+LLMOracleRegistryTest:test_WithdrawStakesAfterUnregistering() (gas: 19278666)
+StatisticsTest:testFuzz_Average(uint8,uint8,uint8,uint8) (runs: 256, μ: 9748, ~: 9748)
+StatisticsTest:testFuzz_StandardDeviation(uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8,uint8) (runs: 256, μ: 21895, ~: 21888)
+StatisticsTest:testFuzz_Variance(uint8,uint8,uint8,uint8,uint8) (runs: 256, μ: 13902, ~: 13902)
+StatisticsTest:test_Average() (gas: 135735)
+StatisticsTest:test_StandardDeviation() (gas: 167111)
+StatisticsTest:test_Variance() (gas: 163789)

README.md

@@ -75,7 +75,7 @@ forge update
 
 ### Setup
 
-To be able to use our contracts, we need an RPC endpoint and a wallet.
+To be able to use our contracts, we need an [Ethereum Wallet](#create-wallet), and an [RPC endpoint](#prepare-rpc-endpoint).
 
 ### Create Wallet
 
@@ -103,11 +103,11 @@ To interact with the blockchain, we require an RPC endpoint. You can get one fro
 
 - [Alchemy](https://www.alchemy.com/)
 - [Infura](https://www.infura.io/)
-- [or see more here](https://www.alchemy.com/best/rpc-node-providers)
+- [(see more)](https://www.alchemy.com/best/rpc-node-providers)
 
 You will use this endpoint for the commands that interact with the blockchain, such as deploying and upgrading; or while doing fork tests.
 
-### Deploy Contract
+### Deploy & Verify Contract
 
 Deploy the contract with:
 
@@ -118,30 +118,34 @@ forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
 --broadcast
 ```
 
-or for instant verification use:
+You can see deployed contract addresses under the `deployment/<chainid>.json`
+
+You can verify the contract during deployment by adding the verification arguments as well:
 
 ```sh
 forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
 --rpc-url <RPC_URL> \
 --account <WALLET_NAME> \
---sender <ADDRESS> --broadcast \
---verify --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
+--broadcast \
+--verify --verifier blockscout \
+--verifier-url <VERIFIER_URL>
 ```
 
-> [!NOTE] > `<VERIFIER_URL>` should be expolorer's homepage url. Forge reads your `<ETHERSCAN_API_KEY>` from .env file so you don't need to add this at the end of `<VERIFIER_URL>`.
->
-> e.g.
-> `https://base-sepolia.blockscout.com/api/` for `Base Sepolia Network`
+You can verify an existing contract with:
 
-You can see deployed contract addresses under the `deployment/<chainid>.json`
+```sh
+forge verify-contract <CONTRACT_ADDRESS> src/<CONTRACT_NAME>.sol:<CONTRACT_NAME> \
+--verifier blockscout \
+--verifier-url <VERIFIER_URL>
+```
 
-## Verify Contract
+Note that the `--verifier-url` value should be the target explorer's homepage URL. Foundry will read your `ETHERSCAN_API_KEY` from environment already, so this does not have to be within your URL.
 
-Verify contract manually with:
+`https://base-sepolia.blockscout.com/api/` for `Base Sepolia Network`
 
-```sh
-forge verify-contract <CONTRACT_ADDRESS> src/$<CONTRACT_NAME>.sol:<CONTRACT_NAME> --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
-```
+> [!NOTE]
+>
+> The `--verifier` can accept any of the following: `etherscan`, `blockscout`, `sourcify`; but we are using Blockscout most of the time.
 
 ## Testing & Diagnostics
 
@@ -160,28 +164,26 @@ or fork an existing chain and run the tests on it:
 forge clean && forge test --rpc-url <RPC_URL>
 ```
 
-### Coverage
+### Code Coverage
 
-Check coverages with:
+We have a script that generates the coverage information as an HTML page. This script requires [`lcov`](https://linux.die.net/man/1/lcov) and [`genhtml`](https://linux.die.net/man/1/genhtml) command line tools. To run, do:
 
 ```sh
-forge clean && bash coverage.sh
+forge clean && ./coverage.sh
 ```
 
-or to see summarized coverages on terminal:
+Alternatively, you can see a summarized text-only output as well:
 
 ```sh
 forge clean && forge coverage --no-match-coverage "(test|mock|script)"
 ```
 
-You can see coverages under the coverage directory.
-
 ### Storage Layout
 
 Get storage layout with:
 
 ```sh
-forge clean && bash storage.sh
+forge clean && ./storage.sh
 ```
 
 You can see storage layouts under the storage directory.

abis/parseAbi.js

@@ -28,7 +28,7 @@ fs.readFile(filename, "utf8", (err, data) => {
         process.exit(1);
       }
 
-      console.log("ABI extracted and written to abi.json");
+      console.log("ABI extracted and written to", filename);
     });
   } catch (parseErr) {
     console.error(`Error parsing JSON: ${parseErr}`);

coverage.sh

@@ -3,14 +3,28 @@
 # exit on error
 set -e
 
-# Run forge coverage
+# give error if `lcov` is not installed
+if ! command -v lcov &> /dev/null
+then
+    echo "lcov could not be found. Please install lcov"
+    exit
+fi
+
+# give error if `genhtml` is not installed
+if ! command -v genhtml &> /dev/null
+then
+    echo "genhtml could not be found. Please install lcov"
+    exit
+fi
+
+# generate coverage info
 forge coverage \
     --report lcov \
     --report summary \
     --no-match-coverage "(test|mock|script)" 
 
-# Install lcov
-brew install lcov
+# generate HTML report from lcov.info
+genhtml lcov.info -o coverage --branch-coverage --ignore-errors inconsistent,category,corrupt
 
-# Generate HTML report from lcov.info
-genhtml lcov.info -o coverage --branch-coverage --ignore-errors inconsistent,category,corrupt
+# open report
+open coverage/index.html

lcov.info

@@ -13,26 +13,26 @@ DA:98,6
 BRDA:98,1,0,-
 DA:99,0
 DA:104,6
-FN:104,LLMOracleCoordinator.isWhiteListed
-FNDA:6,LLMOracleCoordinator.isWhiteListed
+FN:104,LLMOracleCoordinator.onlyWhitelisted
+FNDA:6,LLMOracleCoordinator.onlyWhitelisted
 DA:105,6
 BRDA:105,2,0,1
 DA:106,1
-DA:118,6
+DA:118,7
 FN:118,LLMOracleCoordinator.constructor
-FNDA:6,LLMOracleCoordinator.constructor
-DA:119,6
+FNDA:7,LLMOracleCoordinator.constructor
+DA:119,7
 DA:128,0
 FN:128,LLMOracleCoordinator._authorizeUpgrade
 FNDA:0,LLMOracleCoordinator._authorizeUpgrade
-DA:139,6
+DA:139,7
 FN:139,LLMOracleCoordinator.initialize
-FNDA:6,LLMOracleCoordinator.initialize
-DA:148,6
-DA:149,6
-DA:150,6
-DA:151,6
-DA:152,6
+FNDA:7,LLMOracleCoordinator.initialize
+DA:148,7
+DA:149,7
+DA:150,7
+DA:151,7
+DA:152,7
 DA:167,5
 FN:167,LLMOracleCoordinator.request
 FNDA:5,LLMOracleCoordinator.request
@@ -187,81 +187,78 @@ BRH:12
 end_of_record
 TN:
 SF:src/LLMOracleManager.sol
-DA:50,6
+DA:50,7
 FN:50,LLMOracleManager.__LLMOracleManager_init
-FNDA:6,LLMOracleManager.__LLMOracleManager_init
-DA:57,6
-DA:59,6
-DA:60,6
-DA:62,6
-DA:63,6
-DA:64,6
+FNDA:7,LLMOracleManager.__LLMOracleManager_init
+DA:57,7
+DA:59,7
+DA:60,7
+DA:62,7
+DA:63,7
+DA:64,7
 DA:72,5
 FN:72,LLMOracleManager.onlyValidParameters
 FNDA:5,LLMOracleManager.onlyValidParameters
-DA:74,5
-DA:75,0
-BRDA:75,0,0,-
+DA:75,5
 DA:76,0
-DA:82,5
-DA:83,5
-DA:84,0
-BRDA:84,1,0,-
-DA:85,0
-DA:91,5
-DA:92,5
-DA:93,0
-BRDA:93,2,0,-
-DA:94,0
-DA:98,5
-BRDA:98,3,0,-
-DA:99,0
-DA:109,0
-FN:109,LLMOracleManager.setFees
+BRDA:76,0,0,-
+DA:77,0
+DA:84,5
+DA:85,5
+DA:86,0
+BRDA:86,1,0,-
+DA:87,0
+DA:94,5
+DA:95,5
+DA:96,0
+BRDA:96,2,0,-
+DA:97,0
+DA:110,0
+FN:110,LLMOracleManager.setFees
 FNDA:0,LLMOracleManager.setFees
-DA:110,6
-DA:111,6
-DA:112,6
-DA:120,5
-FN:120,LLMOracleManager.getFee
+DA:111,7
+DA:112,7
+DA:113,7
+DA:121,5
+FN:121,LLMOracleManager.getFee
 FNDA:5,LLMOracleManager.getFee
-DA:125,10
 DA:126,10
 DA:127,10
 DA:128,10
-DA:136,0
-FN:136,LLMOracleManager.setParameters
+DA:129,10
+DA:137,0
+FN:137,LLMOracleManager.setParameters
 FNDA:0,LLMOracleManager.setParameters
-DA:140,0
 DA:141,0
-DA:147,0
-FN:147,LLMOracleManager.setGenerationDeviationFactor
-FNDA:0,LLMOracleManager.setGenerationDeviationFactor
+DA:142,0
 DA:148,0
+FN:148,LLMOracleManager.setGenerationDeviationFactor
+FNDA:0,LLMOracleManager.setGenerationDeviationFactor
+DA:149,0
 FNF:6
 FNH:3
-LF:35
-LH:22
-BRF:4
+LF:33
+LH:21
+BRF:3
 BRH:0
 end_of_record
 TN:
 SF:src/LLMOracleRegistry.sol
-DA:75,15
+DA:75,16
 FN:75,LLMOracleRegistry.constructor
-FNDA:15,LLMOracleRegistry.constructor
-DA:76,15
+FNDA:16,LLMOracleRegistry.constructor
+DA:76,16
 DA:85,0
 FN:85,LLMOracleRegistry._authorizeUpgrade
 FNDA:0,LLMOracleRegistry._authorizeUpgrade
-DA:88,15
+DA:88,16
 FN:88,LLMOracleRegistry.initialize
-FNDA:15,LLMOracleRegistry.initialize
-DA:94,15
-DA:95,15
-DA:96,15
-DA:97,15
-DA:98,15
+FNDA:16,LLMOracleRegistry.initialize
+DA:94,16
+DA:95,16
+DA:96,16
+DA:97,16
+DA:98,16
 DA:108,54
 FN:108,LLMOracleRegistry.register
 FNDA:54,LLMOracleRegistry.register

src/LLMOracleTask.sol

@@ -3,7 +3,6 @@ pragma solidity ^0.8.20;
 
 /// @notice Collection of oracle task-related parameters.
 /// @dev Prevents stack-too-deep with tight-packing.
-/// TODO: use 256-bit tight-packing here
 struct LLMOracleTaskParameters {
     /// @notice Difficulty of the task.
     uint8 difficulty;

storage.sh

@@ -2,11 +2,12 @@
 OUTPUT_PATH=${1:-storage}
 EXCLUDE="test|mock|script|"
 
+# FIXME: what does IFS do here?
 IFS=$'\n'
 CONTRACT_FILES=($(find ./src -type f))
 unset IFS
 
-echo "Generating layouts in $OUTPUT_PATH"
+echo "Outputting storage layouts to: $OUTPUT_PATH"
 mkdir -p $OUTPUT_PATH
 
 for file in "${CONTRACT_FILES[@]}";
@@ -16,6 +17,6 @@ do
     fi
 
     contract=$(basename "$file" .sol)
-    echo "Generating storage layout of $contract"
+    echo "Generating storage layout for: $contract"
     forge inspect "$contract" storage --pretty > "$OUTPUT_PATH/$contract.md"
-done
+done