more doc rfks, added upgrade docs

.vscode/settings.json

@@ -7,5 +7,12 @@
   },
   "solidity.formatter": "forge",
   "solidity.compileUsingRemoteVersion": "v0.8.26",
-  "solidity.defaultCompiler": "localFile"
+  "solidity.defaultCompiler": "localFile",
+  "solidity.remappingsUnix": [
+    "forge-std/=lib/forge-std/src/",
+    "@openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/",
+    "@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/",
+    "@openzeppelin/foundry-upgrades/=lib/openzeppelin-foundry-upgrades/src/",
+    "@firstbatch/dria-oracle-contracts/=lib/dria-oracle-contracts/src/"
+  ]
 }

README.md

@@ -105,7 +105,7 @@ To interact with the blockchain, we require an RPC endpoint. You can get one fro
 
 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
+### Deploy Contract
 
 Deploy the contract with:
 
@@ -116,9 +116,23 @@ forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
 --broadcast
 ```
 
-You can see deployed contract addresses under the `deployment/<chainid>.json`
+You can see deployed contract addresses under the [`deployments/<chainid>.json`](./deployments/) folder.
 
-You can verify the contract during deployment by adding the verification arguments as well:
+You will need the contract ABIs to interact with them as well, thankfully there is a nice short-hand command to export that:
+
+```sh
+forge inspect <CONTRACT_NAME> abi > ./deployments/abis/<CONTRACT_NAME>.json
+```
+
+### Verify Contract
+
+Verification requires the following values, based on which provider you are using:
+
+- **Provider**: can accept any of `etherscan`, `blockscout`, `sourcify`, `oklink` or `custom` for more fine-grained stuff.
+- **URL**: based on the chosen provider, we require its URL as well, e.g. `https://base-sepolia.blockscout.com/api/` for `blockscout` on Base Sepolia
+- **API Key**: an API key from the chosen provider, must be stored as `ETHERSCAN_API_KEY` in environment no matter whicih provider it is!.
+
+You can actually verify the contract during deployment by adding the verification arguments as well:
 
 ```sh
 forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
@@ -129,39 +143,35 @@ forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
 --verifier-url <VERIFIER_URL>
 ```
 
-You can verify an existing contract with:
+Alternatively, you can verify an existing contract (perhaps deployed from a factory) with:
 
 ```sh
 forge verify-contract <CONTRACT_ADDRESS> ./src/<CONTRACT_NAME>.sol:<CONTRACT_NAME> \
---verifier blockscout \
---verifier-url <VERIFIER_URL>
+--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]
->
-> 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.
+### Upgrade Contract
 
-### Generate ABIs
+Upgrading an existing contract is done as per the instructions in [openzeppelin-foundry-upgrades](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades) repository.
 
-To interact with the contracts, you need the contract ABIs. We store the ABIs under the [`abis`](./abis/) folder, and these can be generated using the following script:
+First, we create a new contract with its name as `ContractNameV2`, and then we execute the following command:
 
 ```sh
-./export-abis.sh
+forge script ./script/Deploy.s.sol:Upgrade<CONTRACT_NAME> \
+--rpc-url <RPC_URL> \
+--account <WALLET_NAME> --broadcast \
+--sender <WALLET_ADDRESS> \
+--verify --verifier blockscout \
+--verifier-url <VERIFIER_URL>
 ```
 
-### Upgrade Contract
-
-Upgrading an existing contract is done as per the instructions in [openzeppelin-foundry-upgrades](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades) repository.
-The `--sender <ADDRESS>` field is required when deploying a contract,
+> [!NOTE]
+>
+> The `--sender <ADDRESS>` field is mandatory when deploying a contract, it can be obtained with the command below, which will prompt for keystore password:
+>
+> ```sh
+> cast wallet address --account <WALLET_NAME>
+> ```
 
 ## Testing & Diagnostics
 
@@ -194,16 +204,6 @@ Alternatively, you can see a summarized text-only output as well:
 forge coverage --no-match-coverage "(test|mock|script)"
 ```
 
-### Storage Layout
-
-You can print storage layouts for each contract using:
-
-```sh
-./storage.sh
-```
-
-The resulting Markdown files will be created under the [`storage`](./storage/) directory.
-
 ### Gas Snapshot
 
 You can examine the gas usage metrics using the command:

deployment/84532.json → deployments/84532.json

@@ -15,6 +15,6 @@
     "addr": "0x348102400779c4c8f50ee9ad356c5fd8a9803795"
   },
   "SwanArtifactFactory": {
-    "addr": "0x1a69a6c3c930c381b23abe555081437815876974"
+    "addr": "0x780384662fe6ee8ad1f75063b8ea0e03fa76f9d8"
   }
 }

abis/Swan.json → deployments/abis/Swan.json

@@ -1123,4 +1123,4 @@
       }
     ]
   }
-]
+]

abis/SwanAgent.json → deployments/abis/SwanAgent.json

@@ -621,4 +621,4 @@
       }
     ]
   }
-]
+]

abis/SwanArtifact.json → deployments/abis/SwanArtifact.json

@@ -563,4 +563,4 @@
       }
     ]
   }
-]
+]

foundry.toml

@@ -19,7 +19,7 @@ force = true
 # fs permissions for deployment (false by default)
 fs_permissions = [
     { access = "read", path = "out" },
-    { access = "read-write", path = "deployment" },
+    { access = "read-write", path = "deployments" },
 ]
 
 # fuzzing options

script/HelperConfig.s.sol

@@ -83,7 +83,7 @@ contract HelperConfig is Script {
 
     function deployLLMOracleCoordinator() external returns (address proxy, address impl) {
         // get the registry proxy address from chainid.json file under the deployment dir
-        string memory dir = "deployment/";
+        string memory dir = "deployments/";
         string memory fileName = Strings.toString(block.chainid);
         string memory path = string.concat(dir, fileName, ".json");
 
@@ -145,7 +145,7 @@ contract HelperConfig is Script {
 
     function deploySwan() external returns (address proxy, address impl) {
         // read deployed contract addresses
-        string memory dir = "deployment/";
+        string memory dir = "deployments/";
         string memory fileName = Strings.toString(block.chainid);
         string memory path = string.concat(dir, fileName, ".json");
 
@@ -199,7 +199,7 @@ contract HelperConfig is Script {
 
     function writeContractAddress(string memory name, address addr) internal {
         // create a deployment file if not exist
-        string memory dir = "deployment/";
+        string memory dir = "deployments/";
         string memory fileName = Strings.toString(block.chainid);
         string memory path = string.concat(dir, fileName, ".json");
 
@@ -242,7 +242,7 @@ contract HelperConfig is Script {
 
     function writeProxyAddresses(string memory name, address proxy, address impl) internal {
         // create a deployment file if not exist
-        string memory dir = "deployment/";
+        string memory dir = "deployments/";
         string memory fileName = Strings.toString(block.chainid);
         string memory path = string.concat(dir, fileName, ".json");