update docs

.gas-snapshot

@@ -1,44 +1,44 @@
-AIAgentTest:test_InBuyPhase() (gas: 4504153)
-AIAgentTest:test_InListingPhase() (gas: 4472120)
-AIAgentTest:test_RevertWhen_SetAmountPerRoundInBuyPhase() (gas: 4483655)
-AIAgentTest:test_RevertWhen_SetFeeWithInvalidRoyalty() (gas: 4492808)
-AIAgentTest:test_RevertWhen_SetRoyaltyInListingPhase() (gas: 4473166)
-AIAgentTest:test_RevertWhen_WithdrawByAnotherOwner() (gas: 4504441)
-AIAgentTest:test_RevertWhen_WithdrawInBuyPhase() (gas: 4511039)
-AIAgentTest:test_SetRoyaltyAndAmountPerRound() (gas: 4494015)
-AIAgentTest:test_WithdrawInWithdrawPhase() (gas: 4474361)
 DeployTest:test_Deploy() (gas: 22076)
-InvariantTest:invariant_AgentFeeRoyalty() (runs: 20, calls: 10000, reverts: 8980)
-InvariantTest:invariant_ArtifactPriceRange() (runs: 20, calls: 10000, reverts: 9028)
-InvariantTest:invariant_MaxArtifactCount() (runs: 20, calls: 10000, reverts: 8998)
-InvariantTest:invariant_OwnerIsAnOperator() (runs: 20, calls: 10000, reverts: 8992)
-SwanFuzzTest:testFuzz_CalculateRoyalties(uint256,uint256,uint256) (runs: 100, μ: 4478115, ~: 4478236)
-SwanFuzzTest:testFuzz_ChangeCycleTime(uint256,uint256,uint256,uint256,uint256,uint256) (runs: 100, μ: 6920555, ~: 6921298)
-SwanFuzzTest:testFuzz_ListArtifact(string,string,bytes,uint256,string,string,uint96,uint256) (runs: 100, μ: 3923970, ~: 3924013)
-SwanFuzzTest:testFuzz_TransferOwnership(address) (runs: 100, μ: 45356, ~: 45356)
-SwanIntervalsTest:test_InBuyPhase() (gas: 4484185)
-SwanIntervalsTest:test_InListingPhase() (gas: 4472550)
-SwanIntervalsTest:test_InWithdrawPhase() (gas: 4487549)
-SwanTest:test_CreateAIAgents() (gas: 5663937)
-SwanTest:test_PurchaseAnArtifact() (gas: 11297765)
-SwanTest:test_RelistArtifact() (gas: 10251837)
-SwanTest:test_RevertWhen_CreateAgentWithInvalidRoyalty() (gas: 1619957)
-SwanTest:test_RevertWhen_ListInWithdrawPhase() (gas: 5749933)
-SwanTest:test_RevertWhen_ListMoreThanmaxArtifactCount() (gas: 10119397)
-SwanTest:test_RevertWhen_PurchaseByAnotherAgent() (gas: 10142029)
-SwanTest:test_RevertWhen_PurchaseInListingPhase() (gas: 10116892)
-SwanTest:test_RevertWhen_PurchaseMoreThanAmountPerRound() (gas: 11333279)
-SwanTest:test_RevertWhen_RelistAlreadyPurchasedArtifact() (gas: 11289853)
-SwanTest:test_RevertWhen_RelistByAnotherSeller() (gas: 10127804)
-SwanTest:test_RevertWhen_RelistInBuyPhase() (gas: 10163113)
-SwanTest:test_RevertWhen_RelistInTheSameRound() (gas: 10119934)
-SwanTest:test_RevertWhen_RelistInWithdrawPhase() (gas: 10162737)
-SwanTest:test_RevertWhen_RelistMoreThanMaxArtifactCount() (gas: 13983200)
-SwanTest:test_RevertWhen_SetMarketParametersWithInvalidFee() (gas: 1539671)
-SwanTest:test_RevertWhen_UpgradeByNonOwner() (gas: 1543316)
-SwanTest:test_SetAmountPerRound() (gas: 5720733)
-SwanTest:test_SetFactories() (gas: 5172184)
-SwanTest:test_SetMarketParameters() (gas: 5843554)
-SwanTest:test_SetOracleParameters() (gas: 5665825)
-SwanTest:test_TransferOwnership() (gas: 55416)
-SwanTest:test_UpdateState() (gas: 12066139)
+InvariantTest:invariant_AgentFeeRoyalty() (runs: 20, calls: 10000, reverts: 8972)
+InvariantTest:invariant_ArtifactPriceRange() (runs: 20, calls: 10000, reverts: 9002)
+InvariantTest:invariant_MaxArtifactCount() (runs: 20, calls: 10000, reverts: 8966)
+InvariantTest:invariant_OwnerIsAnOperator() (runs: 20, calls: 10000, reverts: 8926)
+SwanAgentTest:test_InBuyPhase() (gas: 4504405)
+SwanAgentTest:test_InListingPhase() (gas: 4472350)
+SwanAgentTest:test_RevertWhen_SetAmountPerRoundInBuyPhase() (gas: 4483903)
+SwanAgentTest:test_RevertWhen_SetFeeWithInvalidRoyalty() (gas: 4493071)
+SwanAgentTest:test_RevertWhen_SetRoyaltyInListingPhase() (gas: 4473396)
+SwanAgentTest:test_RevertWhen_WithdrawByAnotherOwner() (gas: 4504683)
+SwanAgentTest:test_RevertWhen_WithdrawInBuyPhase() (gas: 4511301)
+SwanAgentTest:test_SetRoyaltyAndAmountPerRound() (gas: 4494282)
+SwanAgentTest:test_WithdrawInWithdrawPhase() (gas: 4474615)
+SwanFuzzTest:testFuzz_CalculateRoyalties(uint256,uint256,uint256) (runs: 100, μ: 4478317, ~: 4478436)
+SwanFuzzTest:testFuzz_ChangeCycleTime(uint256,uint256,uint256,uint256,uint256,uint256) (runs: 100, μ: 6920941, ~: 6921698)
+SwanFuzzTest:testFuzz_ListArtifact(string,string,bytes,uint256,string,string,uint96,uint256) (runs: 100, μ: 3924204, ~: 3924238)
+SwanFuzzTest:testFuzz_TransferOwnership(address) (runs: 100, μ: 45365, ~: 45365)
+SwanIntervalsTest:test_InBuyPhase() (gas: 4484429)
+SwanIntervalsTest:test_InListingPhase() (gas: 4472772)
+SwanIntervalsTest:test_InWithdrawPhase() (gas: 4487796)
+SwanTest:test_CreateSwanAgents() (gas: 5664526)
+SwanTest:test_PurchaseAnArtifact() (gas: 11299061)
+SwanTest:test_RelistArtifact() (gas: 10252952)
+SwanTest:test_RevertWhen_CreateAgentWithInvalidRoyalty() (gas: 1620230)
+SwanTest:test_RevertWhen_ListInWithdrawPhase() (gas: 5750553)
+SwanTest:test_RevertWhen_ListMoreThanmaxArtifactCount() (gas: 10120420)
+SwanTest:test_RevertWhen_PurchaseByAnotherAgent() (gas: 10143076)
+SwanTest:test_RevertWhen_PurchaseInListingPhase() (gas: 10117930)
+SwanTest:test_RevertWhen_PurchaseMoreThanAmountPerRound() (gas: 11334511)
+SwanTest:test_RevertWhen_RelistAlreadyPurchasedArtifact() (gas: 11291127)
+SwanTest:test_RevertWhen_RelistByAnotherSeller() (gas: 10128856)
+SwanTest:test_RevertWhen_RelistInBuyPhase() (gas: 10164182)
+SwanTest:test_RevertWhen_RelistInTheSameRound() (gas: 10120976)
+SwanTest:test_RevertWhen_RelistInWithdrawPhase() (gas: 10163806)
+SwanTest:test_RevertWhen_RelistMoreThanMaxArtifactCount() (gas: 13984372)
+SwanTest:test_RevertWhen_SetMarketParametersWithInvalidFee() (gas: 1539932)
+SwanTest:test_RevertWhen_UpgradeByNonOwner() (gas: 1543580)
+SwanTest:test_SetAmountPerRound() (gas: 5721328)
+SwanTest:test_SetFactories() (gas: 5172520)
+SwanTest:test_SetMarketParameters() (gas: 5844131)
+SwanTest:test_SetOracleParameters() (gas: 5666393)
+SwanTest:test_TransferOwnership() (gas: 55434)
+SwanTest:test_UpdateState() (gas: 12067589)

.gitignore

@@ -21,6 +21,7 @@ storage/
 
 # Dotenv file
 .env
+.preset.sh
 
 # appleeeee
 .DS_Store

README.md

@@ -35,7 +35,7 @@ First, make sure you have the requirements:
 Clone the repository:
 
 ```sh
-git clone [email protected]:firstbatchxyz/swan-contracts.git
+git clone [email protected]:firstbatchxyz/dria-oracle-contracts.git
 ```
 
 Install dependencies with:
@@ -52,11 +52,13 @@ 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 before you run `forge script` or `forge test` (as per their [docs](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades?tab=readme-ov-file#before-running)):
+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]
+>
 > 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
@@ -71,74 +73,99 @@ To update contracts to the latest library versions, use:
 forge update
 ```
 
-## Deployment
+## Usage
 
-**Step 1.**
-Import your `ETHERSCAN_API_KEY` to env file.
+### Setup
 
-> [!NOTE]
->
-> Foundry expects the API key to be defined as `ETHERSCAN_API_KEY` even though you're using another explorer.
+To be able to deploy & use our contracts, we need two things:
+
+- [Ethereum Wallet](#create-wallet)
+- [RPC endpoint](#prepare-rpc-endpoint)
 
-**Step 2.**
-Create keystores for deployment. [See more for keystores](https://eips.ethereum.org/EIPS/eip-2335)
+### Create Wallet
+
+We use keystores for wallet management, with the help of [`cast wallet`](https://book.getfoundry.sh/reference/cast/wallet-commands) command.
+
+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>
 ```
 
-> [!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. Some example URLs are:
 
-Verify contract manually with:
+- `https://base.blockscout.com/api/` for Base (Mainnet)
+- `https://base-sepolia.blockscout.com/api/` for Base Sepolia (Testnet)
 
-```sh
-forge verify-contract <CONTRACT_ADDRESS> src/$<CONTRACT_NAME>.sol:<CONTRACT_NAME> --verifier <etherscan|blockscout|sourcify> --verifier-url <VERIFIER_URL>
-```
+> [!NOTE]
+>
+> 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.
 
 ## 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:
@@ -147,31 +174,29 @@ 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
+./storage.sh
 ```
 
-You can see storage layouts under the storage directory.
+You can see storage layouts under the [`storage`](./storage/) directory.
 
 ### Gas Snapshot
 
@@ -185,16 +210,13 @@ You can see the snapshot `.gas-snapshot` file in the current directory.
 
 ## Documentation
 
-We have auto-generated documentation under the [`docs`](./docs) folder, generated with the following command:
+We have auto-generated MDBook documentations under the [`docs`](./docs) folder, generated with the following command:
 
 ```sh
 forge doc
-```
 
-We provide an MDBook template over it, which you can open via:
-
-```sh
-cd docs && mdbook serve --open
+# serves the book as well
+forge doc --serve
 ```
 
 ## License

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

deployment/.gitignore

@@ -0,0 +1 @@
+31337.json

deployment/README.md

@@ -0,0 +1 @@
+# Deployment Commands