gitignores and fixes

.gitignore

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

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,84 +1,137 @@
-# 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 RPC endpoint and a wallet.
 
-**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/)
+- [or see more here](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
 
-**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:
 
 ```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> \
+--sender <ADDRESS> --broadcast \
+--verify --verifier <etherscan|blockscout|sourcify> --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>`.
+> [!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. 
+> e.g.
 > `https://base-sepolia.blockscout.com/api/` for `Base Sepolia Network`
->
 
 You can see deployed contract addresses under the `deployment/<chainid>.json`
 
@@ -90,13 +143,31 @@ Verify contract manually with:
 forge verify-contract <CONTRACT_ADDRESS> src/$<CONTRACT_NAME>.sol:<CONTRACT_NAME> --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
 ```
 
-## Coverage
+## Testing & Diagnostics
+
+Run tests on local network:
+
+```sh
+forge clean && forge test
+
+# or -vvv to show reverts in detail
+forge clean && forge test -vvv
+```
+
+or fork an existing chain and run the tests on it:
+
+```sh
+forge clean && forge test --rpc-url <RPC_URL>
+```
+
+### Coverage
 
 Check coverages with:
 
 ```sh
 forge clean && bash coverage.sh
 ```
+
 or to see summarized coverages on terminal:
 
 ```sh
@@ -105,7 +176,7 @@ 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:
 
@@ -115,7 +186,7 @@ forge clean && bash storage.sh
 
 You can see storage layouts under the storage directory.
 
-## Gas Snapshot
+### Gas Snapshot
 
 Take the gas snapshot with:
 
@@ -125,28 +196,20 @@ 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 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.