update docs

docs/src/README.md

@@ -1,121 +1,194 @@
-# 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 use our contracts, we need an [Ethereum Wallet](#create-wallet), and an [RPC endpoint](#prepare-rpc-endpoint).
 
-**Step 1.**
-Import your `ETHERSCAN_API_KEY` to env file.
+### Create Wallet
 
-> [!NOTE]
->
-> Foundry expects the API key to be defined as `ETHERSCAN_API_KEY` even though you're using another explorer.
+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
+```
+
+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> \
+--broadcast \
+--verify --verifier blockscout \
+--verifier-url <VERIFIER_URL>
 ```
-or for instant verification use:
+
+You can verify an existing 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 --verify --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
+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. Foundry will read your `ETHERSCAN_API_KEY` from environment already, so this does not have to be within your URL.
+
+`https://base-sepolia.blockscout.com/api/` for `Base Sepolia Network`
+
 > [!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`
 >
+> The `--verifier` can accept any of the following: `etherscan`, `blockscout`, `sourcify`; but we are using Blockscout most of the time.
 
-You can see deployed contract addresses under the `deployment/<chainid>.json`
+## Testing & Diagnostics
+
+Run tests on local network:
+
+```sh
+forge clean && forge test
 
-## Verify Contract
+# 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 +198,20 @@ forge clean && forge snapshot
 
 You can see the snapshot `.gas-snapshot` file in the current directory.
 
-## Format
+## Documentation
 
-Format code with:
-
-```sh
-forge fmt
-```
-
-## Generate documentation
-
-Generate documentation with:
+We have auto-generated documentation under the [`docs`](./docs) folder, generated with the following command:
 
 ```sh
 forge doc
 ```
 
-## Update
-
-Update modules with:
+We provide an MDBook template over it, which you can open via:
 
 ```sh
-forge update
+cd docs && mdbook serve --open
 ```
 
-You can see the documentation under the `docs/` directory.
+## License
+
+We are using Apache-2.0 license.

docs/src/src/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md

@@ -1,5 +1,5 @@
 # LLMOracleCoordinator
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleCoordinator.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleCoordinator.sol)
 
 **Inherits:**
 [LLMOracleTask](/src/LLMOracleTask.sol/interface.LLMOracleTask.md), [LLMOracleManager](/src/LLMOracleManager.sol/abstract.LLMOracleManager.md), UUPSUpgradeable

docs/src/src/LLMOracleManager.sol/abstract.LLMOracleManager.md

@@ -1,5 +1,5 @@
 # LLMOracleManager
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleManager.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleManager.sol)
 
 **Inherits:**
 OwnableUpgradeable

docs/src/src/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md

@@ -1,5 +1,5 @@
 # LLMOracleRegistry
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleRegistry.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleRegistry.sol)
 
 **Inherits:**
 [Whitelist](/src/Whitelist.sol/abstract.Whitelist.md), UUPSUpgradeable

docs/src/src/LLMOracleRegistry.sol/enum.LLMOracleKind.md

@@ -1,5 +1,5 @@
 # LLMOracleKind
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleRegistry.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleRegistry.sol)
 
 The type of Oracle.
 

docs/src/src/LLMOracleTask.sol/interface.LLMOracleTask.md

@@ -1,5 +1,5 @@
 # LLMOracleTask
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleTask.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleTask.sol)
 
 An umbrella interface that captures task-related structs and enums.
 

docs/src/src/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md

@@ -1,10 +1,9 @@
 # LLMOracleTaskParameters
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/LLMOracleTask.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/LLMOracleTask.sol)
 
 Collection of oracle task-related parameters.
 
-*Prevents stack-too-deep with tight-packing.
-TODO: use 256-bit tight-packing here*
+*Prevents stack-too-deep with tight-packing.*
 
 
 ```solidity

docs/src/src/Statistics.sol/library.Statistics.md

@@ -1,5 +1,5 @@
 # Statistics
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/Statistics.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/Statistics.sol)
 
 Simple statistic library for uint256 arrays.
 

docs/src/src/Whitelist.sol/abstract.Whitelist.md

@@ -1,5 +1,5 @@
 # Whitelist
-[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/609653a954d5da8f6a2fba22755e9328ec77967f/src/Whitelist.sol)
+[Git Source](https://github.com/firstbatchxyz/dria-oracle-contracts/blob/a0589a694000a1a1e8d0cf54f0527c1c8a33c301/src/Whitelist.sol)
 
 **Inherits:**
 OwnableUpgradeable