Merge pull request #29 from danceratopz/docs/improve-doc-and-autogenerate-from-natspec

Docs: Improve readme and autogenerate natspec doc

Author: 0xmichalis

.github/workflows/ci.yml

@@ -61,6 +61,9 @@ jobs:
         env:
           POLYGON_URL: ${{ secrets.POLYGON_URL }}
 
+      - name: Test solidity-docgen builds
+        run: yarn doc
+
       - name: Deploy contract
         run: yarn hardhat --network hardhat deployOffsetHelper --verify false
         env:

README.md

@@ -1,6 +1,6 @@
 # Example Implementations
 
-A collection of examples that implement, integrate with or otherwise use Toucan's contracts and infrastructure. Some of these may be used in production.
+A collection of Solidity contract examples that integrate with or demonstrate the use of Toucan's contracts and infrastructure. Some of these may be used in production.
 
 ## Contracts
 
@@ -10,46 +10,39 @@ A collection of examples that implement, integrate with or otherwise use Toucan'
 
 ## OffsetHelper
 
-The `OffsetHelper` abstracts the carbon offsetting process offered by Toucan to make it easier. Instead of you manually swapping your USDC for NCT, redeeming the NCT for TCO2, then retiring the TCO2... you can just use the `OffsetHelper` to swiftly do this process in 1-2 transactions.
+The `OffsetHelper` contract implements helper functions that simplify the carbon offsetting (retirement) process.
 
-This contract has 2 main methods that users would interact with: `autoOffset` and `autoOffsetUsingPoolToken`.
+See [./docs/OffsetHelper.md](./docs/OffsetHelper.md) for detailed documentation.
 
-### `autoOffset(address _depositedToken, address _poolToken_, uint256 _amountToOffset)`
+### Development
 
-This method takes your tokens, swaps them for pool tokens (BCT or NCT), redeems that for the lowest quality TCO2 and then retires it.
+## Preqrequisites
 
-Let's discuss the params: the first is the token you will deposit to do the offset (could be USDC, WETH or WMATIC), the second is the pool token you want the contract to use (could be NCT or BCT) and the last is the amount of TCO2 to retire.
+1. Install the required packages:
+   ```
+   yarn
+   ```
+2. Copy `.env.example` to `.env` and modify values of the required environment variables: 
+   1. `POLYGON_URL`/`MUMBAI_URL` to specify custom RPC endpoints for Polygon Mainnet, respectively, the Mumbai Testnet.  
+   2. `PRIVATE_KEY` and `POLYGONSCAN_KEY` in order to deploy contract and publish source code on [polygonscan](https://polygonscan.com).
 
-You will have to approve the `OffsetHelper` from the token you wish to deposit before calling `autoOffset()` in this case.
+## Commands
 
-### `autoOffset(address _poolToken_, uint256 _amountToOffset)`
+Use the following commands to compile, test and deploy the contracts:
+```
+yarn compile
+yarn test      # test using a polygon fork
+yarn coverage  # test using a polygon fork with coverage report
+yarn deploy
+```
 
-If you call the `autoOffset()` method specifying only 2 params, it will be payable and you will need to specify a `msg.value`. It works the same as the above method, only this one will swap MATIC for pool tokens instead.
+Documentation can be auto-generated from the contract's [natspec](https://docs.soliditylang.org/en/latest/natspec-format.html) in [./docs/](./docs/) using
+```
+yarn doc
+```
 
-The first param is the pool token you want the contract to use (could be NCT or BCT) and the second is the amount of TCO2 to retire.
+Deploy the contract locally with:
+```
+yarn hardhat --network hardhat deployOffsetHelper --verify false
+```
 
-In case you send too much MATIC in the `msg.value`, the contract is programed to send leftover MATIC back to the user. But, I suggest you use the `calculateNeededETHAmount()` method of the contract before calling `autoOffset()` in this case.
-
-We'll discuss the `calculateNeededETHAmount()` method below.
-
-### `autoOffsetUsingPoolToken(address _poolToken, uint256 _amountToOffset)`
-
-This method is made for users that already have a pool token in their wallet (BCT or NCT), but still would like to use the `OffsetHelper` to abstract away a few steps.
-
-It takes your pool token, redeems it for the lowest quality TCO2 and retires it.
-
-The first parameter is the pool token you will deposit to do the offset (could be NCT or BCT), the second is the amount of TCO2 to retire.
-
-You will want to approve the `OffsetHelper` from the token you wish to deposit before calling `autoOffsetUsingPoolToken()` in this case.
-
-### `calculateNeededETHAmount(address _toToken, uint256 _amount)`
-
-This is a view method that allows you to see how much MATIC it would cost you to get a certain amount of BCT / NCT.
-
-Since (when automatically redeeming pool tokens for the lowest quality TCO2s) the redeeming has no fees and you get 1 TCO2 for each pool token you redeem, effectively this method will tell you how much MATIC you have to deposit to be able to retired a specific amount of TCO2.
-
-Normally, you'd use it before calling `autoOffset(address _poolToken_, uint256 _amountToOffset)` and the result it returns will be assigned as msg.value when you call `autoOffset(address _poolToken_, uint256 _amountToOffset)`.
-
-### Others
-
-There are other methods you can interact with, but you probably won't because it would result in a fairly manual, multi-step offsetting process which is what we're trying to abstract.