From 4fabf2e48a6c333cded31802397b8aacf885f526 Mon Sep 17 00:00:00 2001 From: erhant Date: Wed, 18 Dec 2024 17:35:53 +0300 Subject: [PATCH] update contract docs --- docs/src/README.md | 120 +++++++++++------- docs/src/src/Swan.sol/constants.Swan.md | 2 +- docs/src/src/Swan.sol/contract.Swan.md | 2 +- .../src/SwanAgent.sol/contract.SwanAgent.md | 2 +- .../contract.SwanAgentFactory.md | 2 +- .../SwanArtifact.sol/contract.SwanArtifact.md | 2 +- .../contract.SwanArtifactFactory.md | 2 +- .../SwanManager.sol/abstract.SwanManager.md | 2 +- .../struct.SwanMarketParameters.md | 2 +- 9 files changed, 79 insertions(+), 57 deletions(-) diff --git a/docs/src/README.md b/docs/src/README.md index 88f7afe..3b6252c 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -35,7 +35,7 @@ First, make sure you have the requirements: Clone the repository: ```sh -git clone git@github.com:firstbatchxyz/swan-contracts.git +git clone git@github.com: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,67 +73,89 @@ 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 --interactive +cast wallet import --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 --rpc-url --account --sender --broadcast +forge clean && forge script ./script/Deploy.s.sol:Deploy \ +--rpc-url \ +--account \ +--broadcast ``` -or for instant verification use: +You can see deployed contract addresses under the `deployment/.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 --rpc-url --account --sender --broadcast --verify --verifier --verifier-url +forge clean && forge script ./script/Deploy.s.sol:Deploy \ +--rpc-url \ +--account \ +--broadcast \ +--verify --verifier blockscout \ +--verifier-url ``` -> [!NOTE] > `` should be expolorer's homepage url. Forge reads your `` from .env file so you don't need to add this at the end of ``. -> -> 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/.json` +```sh +forge verify-contract ./src/.sol: \ +--verifier blockscout \ +--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 src/$.sol: --verifier --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 @@ -139,6 +163,9 @@ 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 ``` -### 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 diff --git a/docs/src/src/Swan.sol/constants.Swan.md b/docs/src/src/Swan.sol/constants.Swan.md index 2fbe3a3..2c07fa3 100644 --- a/docs/src/src/Swan.sol/constants.Swan.md +++ b/docs/src/src/Swan.sol/constants.Swan.md @@ -1,5 +1,5 @@ # Constants -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/Swan.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/Swan.sol) ### SwanAgentPurchaseOracleProtocol *Protocol string for Swan Purchase CRONs, checked in the Oracle.* diff --git a/docs/src/src/Swan.sol/contract.Swan.md b/docs/src/src/Swan.sol/contract.Swan.md index 1c97fa6..a8f7fba 100644 --- a/docs/src/src/Swan.sol/contract.Swan.md +++ b/docs/src/src/Swan.sol/contract.Swan.md @@ -1,5 +1,5 @@ # Swan -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/Swan.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/Swan.sol) **Inherits:** [SwanManager](/src/SwanManager.sol/abstract.SwanManager.md), UUPSUpgradeable diff --git a/docs/src/src/SwanAgent.sol/contract.SwanAgent.md b/docs/src/src/SwanAgent.sol/contract.SwanAgent.md index 17b1eba..344ad85 100644 --- a/docs/src/src/SwanAgent.sol/contract.SwanAgent.md +++ b/docs/src/src/SwanAgent.sol/contract.SwanAgent.md @@ -1,5 +1,5 @@ # SwanAgent -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanAgent.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanAgent.sol) **Inherits:** Ownable diff --git a/docs/src/src/SwanAgent.sol/contract.SwanAgentFactory.md b/docs/src/src/SwanAgent.sol/contract.SwanAgentFactory.md index 5a5621f..7b614c6 100644 --- a/docs/src/src/SwanAgent.sol/contract.SwanAgentFactory.md +++ b/docs/src/src/SwanAgent.sol/contract.SwanAgentFactory.md @@ -1,5 +1,5 @@ # SwanAgentFactory -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanAgent.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanAgent.sol) Factory contract to deploy Agent contracts. diff --git a/docs/src/src/SwanArtifact.sol/contract.SwanArtifact.md b/docs/src/src/SwanArtifact.sol/contract.SwanArtifact.md index 86f8551..881dbfc 100644 --- a/docs/src/src/SwanArtifact.sol/contract.SwanArtifact.md +++ b/docs/src/src/SwanArtifact.sol/contract.SwanArtifact.md @@ -1,5 +1,5 @@ # SwanArtifact -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanArtifact.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanArtifact.sol) **Inherits:** ERC721, Ownable diff --git a/docs/src/src/SwanArtifact.sol/contract.SwanArtifactFactory.md b/docs/src/src/SwanArtifact.sol/contract.SwanArtifactFactory.md index ce0db66..21c8c98 100644 --- a/docs/src/src/SwanArtifact.sol/contract.SwanArtifactFactory.md +++ b/docs/src/src/SwanArtifact.sol/contract.SwanArtifactFactory.md @@ -1,5 +1,5 @@ # SwanArtifactFactory -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanArtifact.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanArtifact.sol) Factory contract to deploy Artifact tokens. diff --git a/docs/src/src/SwanManager.sol/abstract.SwanManager.md b/docs/src/src/SwanManager.sol/abstract.SwanManager.md index f7b1f23..3e67e6d 100644 --- a/docs/src/src/SwanManager.sol/abstract.SwanManager.md +++ b/docs/src/src/SwanManager.sol/abstract.SwanManager.md @@ -1,5 +1,5 @@ # SwanManager -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanManager.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanManager.sol) **Inherits:** OwnableUpgradeable diff --git a/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md b/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md index 903d2a9..b5f3273 100644 --- a/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md +++ b/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md @@ -1,5 +1,5 @@ # SwanMarketParameters -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/d7951743b0ff97c2f6e978aeabb850c0310d76f3/src/SwanManager.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/24e0365940f0434545a9c39573dfdf6b9975fc88/src/SwanManager.sol) Collection of market-related parameters.