Merge pull request #19 from firstbatchxyz/erhant/fix-docs-and-issues

fix docs and issues

.env.example

@@ -1,2 +1 @@
-# API KEY (REQUIRED FOR CONTRACT VERIFICATION)
-ETHERSCAN_API_KEY=CHANGE_ME
+ETHERSCAN_API_KEY=<your-api-key>

.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)

.gitignore

@@ -20,4 +20,8 @@ storage/
 .gas-snapshot/
 
 # Dotenv file
-.env
+.env
+.preset.sh
+
+# appleeeee
+.DS_Store

.gitmodules

@@ -7,6 +7,3 @@
 [submodule "lib/openzeppelin-contracts-upgradeable"]
 	path = lib/openzeppelin-contracts-upgradeable
 	url = https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable
-[submodule "lib/openzeppelin-contracts"]
-	path = lib/openzeppelin-contracts
-	url = https://github.com/OpenZeppelin/openzeppelin-contracts

LICENSE

@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-Copyright 2023 FirstBatch
+Copyright 2024 FirstBatch
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -1,121 +1,202 @@
-# LLM Oracles
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firstbatchxyz/.github/refs/heads/master/branding/dria-logo-square.svg" alt="logo" width="168">
+</p>
+
+<p align="center">
+  <h1 align="center">
+    Dria Oracle Contracts
+  </h1>
+  <p align="center">
+    <i>Fully on-chain LLMs.</i>
+  </p>
+</p>
+
+<p align="center">
+    <a href="https://opensource.org/licenses/Apache-2-0" target="_blank">
+        <img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache_2.0-7CB9E8.svg">
+    </a>
+    <a href="./.github/workflows/test.yml" target="_blank">
+        <img alt="Workflow: Tests" src="https://github.com/firstbatchxyz/dria-oracle-contracts/actions/workflows/test.yml/badge.svg?branch=master">
+    </a>
+    <a href="https://discord.gg/dria" target="_blank">
+        <img alt="Discord" src="https://dcbadge.vercel.app/api/server/dria?style=flat">
+    </a>
+</p>
+
+## Installation
+
+First, make sure you have the requirements:
+
+- We are using [Foundry](https://book.getfoundry.sh/), so make sure you [install](https://book.getfoundry.sh/getting-started/installation) it first.
+- Upgradable contracts make use of [NodeJS](https://nodejs.org/en), so you should [install](https://nodejs.org/en/download/package-manager) that as well.
+
+Clone the repository:
 
-LLM Oracle is a **Decentralized Protocol** for **executing AI tasks on-chain**. It processes user-provided inputs through a network of nodes using predefined models, delivering outputs and metadata for use in blockchain applications. By combining decentralized infrastructure with advanced AI processing, LLM Oracle bridges the gap between blockchain and AI, enabling reliable and trustless computation​.
+```sh
+git clone [email protected]:firstbatchxyz/dria-oracle-contracts.git
+```
 
-## Compile
+Install dependencies with:
+
+```sh
+forge install
+```
 
 Compile the contracts with:
 
 ```sh
 forge clean && forge build
 ```
 
+### Upgradability
+
+We are using [openzeppelin-foundry-upgrades](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades) library. To make sure upgrades are **safe**, you must do one of the following (as per their [docs](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades?tab=readme-ov-file#before-running)) before you run `forge script` or `forge test`:
+
+- `forge clean` beforehand, e.g. `forge clean && forge test`
+- include `--force` option when running, e.g. `forge test --force`
+
 > [!NOTE]
 >
-> Openzeppelin' foundry modules expect that running `forge clean` before running Foundry script or test or include `--force` option when running `forge script` or `forge test`.
+> Note that for some users this may fail (see [issue](https://github.com/firstbatchxyz/dria-oracle-contracts/issues/16)) due to a missing NPM package called `@openzeppelin/upgrades-core`. To fix it, do:
+>
+> ```sh
+> npm install @openzeppelin/upgrades-core@latest -g
+> ```
 
-## Test
+### Updates
 
-Run tests on local:
+To update contracts to the latest library versions, use:
 
 ```sh
-forge clean && forge test
+forge update
 ```
 
-or on any other evm chain:
+## Usage
 
-```sh
-forge clean && forge test --rpc-url <RPC_URL>
-```
+### Setup
 
-## Deployment
+To be able to deploy & use our contracts, we need two things:
 
-**Step 1.**
-Import your `ETHERSCAN_API_KEY` to env file.
+- [Ethereum Wallet](#create-wallet)
+- [RPC endpoint](#prepare-rpc-endpoint)
 
-> [!NOTE]
->
-> Foundry expects the API key to be defined as `ETHERSCAN_API_KEY` even though you're using another explorer.
+### Create Wallet
+
+We use keystores for wallet management, with the help of [`cast wallet`](https://book.getfoundry.sh/reference/cast/wallet-commands) command.
 
-**Step 2.**
-Create keystores for deployment. [See more for keystores](https://eips.ethereum.org/EIPS/eip-2335)
+Use the command below to create your keystore. The command will prompt for your **private key**, and a **password** to encrypt the keystore itself.
 
 ```sh
-cast wallet import <FILE_NAME_OF_YOUR_KEYSTORE> --interactive
+cast wallet import <WALLET_NAME> --interactive
 ```
-You can see your wallets with:
+
+> [!ALERT]
+>
+> Note that you will need to enter the password when you use this keystore.
+
+You can see your keystores under the default directory (`~/.foundry/keystores`) with the command:
 
 ```sh
 cast wallet list
 ```
 
-> [!NOTE]
->
-> Recommended to create keystores on directly on your shell.
-> You HAVE to type your password on the terminal to be able to use your keys. (e.g when deploying a contract)
+### Prepare RPC Endpoint
 
-**Step 3.**
-Enter your private key (associated with your address) and password on terminal. You'll see your address on terminal.
+To interact with the blockchain, we require an RPC endpoint. You can get one from:
 
-> [!NOTE]
->
-> If you want to deploy contracts on localhost please provide local address for the command above.
+- [Alchemy](https://www.alchemy.com/)
+- [Infura](https://www.infura.io/)
+- [(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 & Verify Contract
 
-**Step 4.**
 Deploy the contract with:
 
 ```sh
-forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> --rpc-url <RPC_URL> --account <FILE_NAME_OF_YOUR_KEYSTORE> --sender <DEPLOYER_ADDRESS> --broadcast
+forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
+--rpc-url <RPC_URL> \
+--account <WALLET_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 <FILE_NAME_OF_YOUR_KEYSTORE> --sender <DEPLOYER_ADDRESS> --broadcast --verify --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
+forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
+--rpc-url <RPC_URL> \
+--account <WALLET_NAME> \
+--broadcast \
+--verify --verifier blockscout \
+--verifier-url <VERIFIER_URL>
 ```
 
+You can verify an existing contract with:
+
+```sh
+forge verify-contract <CONTRACT_ADDRESS> ./src/<CONTRACT_NAME>.sol:<CONTRACT_NAME> \
+--verifier blockscout \
+--verifier-url <VERIFIER_URL>
+```
+
+Note that the `--verifier-url` value should be the target explorer's homepage URL. Some example URLs are:
+
+- `https://base.blockscout.com/api/` for Base (Mainnet)
+- `https://base-sepolia.blockscout.com/api/` for Base Sepolia (Testnet)
+
 > [!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`
+> URL should not contain the API key! Foundry will read your `ETHERSCAN_API_KEY` from environment.
+
+> [!NOTE]
 >
+> The `--verifier` can accept any of the following: `etherscan`, `blockscout`, `sourcify`, `oklink`. We are using Blockscout most of the time.
 
-You can see deployed contract addresses under the `deployment/<chainid>.json`
+## Testing & Diagnostics
 
-## Verify Contract
+Run tests on local network:
+
+```sh
+forge clean && forge test
+
+# or -vvv to show reverts in detail
+forge clean && forge test -vvv
+```
 
-Verify contract manually with:
+or fork an existing chain and run the tests on it:
 
 ```sh
-forge verify-contract <CONTRACT_ADDRESS> src/$<CONTRACT_NAME>.sol:<CONTRACT_NAME> --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
+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
+### 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.
 
-## Gas Snapshot
+### Gas Snapshot
 
 Take the gas snapshot with:
 
@@ -125,28 +206,17 @@ forge clean && forge snapshot
 
 You can see the snapshot `.gas-snapshot` file in the current directory.
 
-## Format
-
-Format code with:
-
-```sh
-forge fmt
-```
-
-## Generate documentation
+## Documentation
 
-Generate documentation with:
+We have auto-generated MDBook documentations under the [`docs`](./docs) folder, generated with the following command:
 
 ```sh
 forge doc
-```
-
-## Update
-
-Update modules with:
 
-```sh
-forge update
+# serves the book as well
+forge doc --serve
 ```
 
-You can see the documentation under the `docs/` directory.
+## License
+
+We are using Apache-2.0 license.