P2: LILA-5460: Add OffsetHelper to SDK

.env.example

@@ -3,3 +3,4 @@ TEST_TIMEOUT=700000
 NODE_PROVIDER_MUMBAI_RPC_URL=https://rpc.ankr.com/polygon_mumbai
 NODE_PROVIDER_CELO_RPC_URL=https://rpc.ankr.com/celo
 NODE_PROVIDER_ALFAJORES_RPC_URL=https://alfajores-forno.celo-testnet.org
+TEST_TIMEOUT=500000

.gitignore

@@ -103,4 +103,8 @@ dist
 # TernJS port file
 .tern-port
 
-cache
+cache
+
+# DS Store
+*./DS_Store
+.DS_Store

README.md

@@ -2,9 +2,11 @@
 
 [![NPM Package](https://img.shields.io/npm/v/toucan-sdk.svg)](https://www.npmjs.com/package/toucan-sdk)
 
+The Toucan SDK allows developers to build using Toucan's infrastructure tools on [Celo](https://celo.org/) and [Polygon](https://polygon.technology/). It provides a set of functions that allow developers to interact with Toucan Protocol's smart contracts and subgraphs. This includes redeeming of pool tokens and retirements of carbon credits, as well as querying data on projects and retirements.
+
 A Typescript SDK for [Toucan Protocol](https://toucan.earth/). Wraps around [Ethers.js](https://docs.ethers.io/v5/). Works in the web browser and Node.js.
 
-_Full documentation coming soon._
+For the full documentation, check our [docs](https://docs.toucan.earth/toucan/dev-resources/sdk).
 
 ⚠️ This SDK is heavily under development. USE AT YOUR OWN RISK. ⚠️
 
@@ -22,11 +24,39 @@ yarn add toucan-sdk
 
 # Quickstart
 
-Instantiate the ToucanClient and set a signer & provider to interact with our infrastructure.
+Instantiate the ToucanClient and set a `signer` & `provider` to interact with our infrastructure.
+
+We recommend using to use [ethers.js ^5.6.4](https://docs.ethers.org/v5/api/signer/) for the signer and provider. When you are considering using [wagmi](https://0.3.x.wagmi.sh/docs/hooks/useSigner), only versions under 1.0 will work as this library has not yet been upgraded to viem.
+
+### [ethers.js](https://docs.ethers.org/v5/api/signer/)
 
 ```typescript
 import ToucanClient from "toucan-sdk";
+import { ethers } from "ethers";
+
+// ethers signer and provider
+const provider = new ethers.providers.JsonRpcProvider(
+  "https://rpc.ankr.com/polygon"
+);
+
+// make sure to set your private key in your .env file
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
+
+// set signer & provider
+const toucan = new ToucanClient("alfajores", provider, signer);
+```
+
+### [wagmi](https://0.3.x.wagmi.sh/docs/hooks/useSigner)
+
+```typescript
+import { ToucanClient } from "toucan-sdk";
+import { useProvider, useSigner } from "wagmi";
 
+// get signer & provider
+const { data: signer } = useSigner();
+const provider = useProvider();
+
+// set signer & provider
 const toucan = new ToucanClient("alfajores", provider, signer);
 ```
 
@@ -44,15 +74,15 @@ If you don't have a signer nor a provider set, you can only interact with the su
 
 ## Fetch pool prices from a Dex
 
-You can find pools for Toucan pool tokens on [Celo Network](https://celo.org) at [Ubeswap](https://ubeswap.org) and for [Polygon Network](https://polygon.technology) on [SushiSwap](sushi.com)
+You can find pools for Toucan pool tokens on [Celo Network](https://celo.org) at [Uniswap](https://uniswap.org/) and for [Polygon Network](https://polygon.technology) on [SushiSwap](sushi.com).
 
 Something that may come in handy in your applications is fetching the USD price of our pool tokens.
 
 ```typescript
 nctPrice = await toucan.fetchTokenPriceOnDex("NCT");
 ```
 
-The object returned by the above method will look like so:
+The object returned by the above method will look like this:
 
 ```json
 {
@@ -65,7 +95,7 @@ The object returned by the above method will look like so:
 
 # Interact with Toucan's Contracts?
 
-You can always access any method or property of the BCT, NCT and TCO2 contracts by first getting and storing them in a variable, like so:
+You can always access any method or property of the BCT, NCT and TCO2 [contracts](https://github.com/ToucanProtocol/contracts) by first getting and storing them in a variable, like this:
 
 ```typescript
 toucan.setSigner(signer);
@@ -78,11 +108,11 @@ const remainingTCO2 = await nct.tokenBalances(tco2Address);
 
 This is useful if you need to interact with a method of our contracts that hasn't been implemented in the SDK yet.
 
-It's important to note that, if you want to use write methods you need to have a signer set!
+It's important to note that, if you want to use write methods you need to have a signer set in your ToucanClient!
 
 ## Example to retire Carbon Credits
 
-To retire Carbon Credits on mainnet, you will have to get Carbon Pool Tokens from a DEX like Ubeswap, which you need to redeem for TCO2s. You can then retire these and get a certificate for that. If you already own NCTs, you can follow this example. In case you don't and are developing on testnet, you can also just get some at the [Toucan Faucet](https://faucet.toucan.earth). You can find more ways to retire in our [documentation](https://docs.toucan.earth/toucan/dev-resources/smart-contracts/tco2).
+To retire Carbon Credits on mainnet, you will have to get Carbon Pool Tokens from a DEX like [Uniswap](https://uniswap.org), which you need to redeem for TCO2s. You can then retire these and get a certificate for that. If you already own NCTs, you can follow this example. In case you don't and are developing on testnet, you can also just get some at the [Toucan Faucet](https://faucet.toucan.earth). You can find more ways to retire in our [documentation](https://docs.toucan.earth/toucan/dev-resources/smart-contracts/tco2).
 
 **Redeem your Pool Tokens and get an array of redeemed TCO2s**
 
@@ -93,7 +123,7 @@ const tco2Addresses = await toucan.redeemAuto("NCT", parseEther("1"));
 **Retire the Carbon Credits**
 
 ```typescript
-await toucan.retire(parseEther("1"), tco2addresses[0].address);
+await toucan.retire(parseEther("1"), tco2Addresses[0].address);
 ```
 
 # Subgraph queries
@@ -112,7 +142,7 @@ That's where subgraph queries come in handy. (and we have plenty of those 😉)
 const tco2 = await toucan.fetchTCO2TokenByFullSymbol("TCO2-VCS-1718-2013");
 ```
 
-The result will look like so:
+The result will look like this:
 
 ```json
 {
@@ -136,49 +166,55 @@ Now you have quite some info on the project, including its address.
 Toucan SDK offers a lot of pre-defined queries. Try them out!
 
 ```typescript
+import { ToucanClient } from "toucan-sdk";
+
+// here we don't need to set the signer or provider
+const toucan = new ToucanClient("alfajores");
+
 // Fetch the batches of a user.
-fetchUserBatches(address: string);
+await toucan.fetchUserBatches(address: string, first?: number, skip?: number);
 
-// Fetch TCO2 token by it's address to get details like name, symbol, address and projectVintage.
-fetchTCO2TokenById(address: string);
+// Fetch TCO2 token by its address to get details like name, symbol, address and projectVintage.
+await toucan.fetchTCO2TokenById(address: string);
 
 // Fetch TCO2Token with the symbol to get details like name, symbol, address and projectVintage. A symbol would look like this: `TCO2-VCS-<projectId>-YYYY`. Make sure to input the full symbol.
-fetchTCO2TokenByFullSymbol(symbol: string);
+await toucan.fetchTCO2TokenByFullSymbol(symbol: string);
 
 // Fetch all TCO2s details like name, symbol, address and projectVintage.
-
-fetchAllTCO2Tokens();
+await toucan.fetchAllTCO2Tokens(first?: number, skip?: number);
 
 // Fetch all user retirements to get information like creationTX, amount, token details and certificate details.
-fetchUserRetirements(address: string, first?: number, skip?: number);
+await toucan.fetchUserRetirements(address: string, first?: number, skip?: number);
 
 // Fetch all redeems of a given pool to get information like amount, creator and token details. Only accepts the Pooltypes "NCT" or "BCT".
-fetchRedeems(poolSymbol: Pooltypes, first?: number, skip?: number);
+await toucan.fetchRedeems(poolSymbol: Pooltypes, first?: number, skip?: number);
 
 // Fetch all redeems of a user by pool and get information like amount and token details.
-fetchUserRedeems(address: string, poolSymbol: Pooltypes, first?: number, skip?: number);
+await toucan.fetchUserRedeems(address: string, poolSymbol: Pooltypes, first?: number, skip?: number);
 
 // Fetch TCO2 tokens that are part of the given pool and get information on name, amount, methodology and more.
-fetchPoolContents(poolSymbol: Pooltypes, first?: number, skip?: number);
-
-// Fetch a project by it's id to get more info on region and the standard.
+await toucan.fetchPoolContents(poolSymbol: Pooltypes, first?: number, skip?: number);
 
-fetchProjectById();
+// Fetch a project by it's id (e.g., Verra Project ID) to get more info on region and the standard.
+await toucan.fetchProjectById(id: string);
 
 // Fetch all aggregations (including for example, tco2TotalRetired or totalCarbonBridged).
-fetchAggregations();
+await toucan.fetchAggregations();
 ```
 
 ## Custom queries
 
-There's a lot more other pre-built subgraph queries that I could show you, but what I really want to show you is the `fetchCustomQuery` method.
+Now that you have an overview of our pre-build queries, let's have a look at the `fetchCustomQuery` method.
 
 This allows you to fetch with your own queries and can be very powerful if you know graphQL. You can also check out a lot of example queries in our subgraph [playgrounds](https://thegraph.com/hosted-service/subgraph/toucanprotocol/matic).
 
-- Getting all infos on a project of a Carbon Credit
+- Getting all infos on a carbon project (`region` stands for the country)
 
 ```typescript
 import { gql } from "@urql/core";
+import { ToucanClient } from "toucan-sdk";
+
+const toucan = new ToucanClient("alfajores");
 
 const query = gql`
   query ($id: String) {
@@ -197,11 +233,9 @@ const query = gql`
 const result = await toucan.fetchCustomQuery(query, { id: "1" });
 ```
 
-# AutoOffset using the OffsetHelper
-
-⚠️ This part is currently under construction and can't be used. ⚠️
+# Auto Offset using the OffsetHelper
 
-## AutoOffset CO2
+## Auto Offset CO2
 
 Using the OffsetHelper methods is the easiest way to offset CO2 right now as it handles the whole process for you.
 
@@ -212,17 +246,20 @@ This is how you do that when you want to use ETH (or the network's native curren
 In this example, you'd be offsetting 1 TON of CO2 with carbon projects from the NCT pool.
 
 ```typescript
-const offsetReceipt = await toucan.autoOffsetUsingETH("NCT", parseEther("1.0"));
+const offsetReceipt = await toucan.autoOffsetExactOutETH(
+  "NCT",
+  parseEther("1.0")
+);
 ```
 
 ### Don't want to spend your ETH to offset?
 
-You can use different tokens to do it. Currently it works with USDC, WMATIC and WETH only.
+You can use different tokens to do it. Currently it works with cUSD, USDC, WMATIC and WETH.
 
 ```typescript
 const weth = new ethers.Contract(wethAddress, wethAbi, signer);
 
-const offsetReceipt = await toucan.autoOffsetUsingSwapToken(
+const offsetReceipt = await toucan.autoOffsetExactInToken(
   "NCT",
   parseEther("1.0"),
   weth
@@ -231,10 +268,10 @@ const offsetReceipt = await toucan.autoOffsetUsingSwapToken(
 
 ### Offset with your own BCT/NCT
 
-If you already have BCT/NCT, you can use `autoOffsetUsingPoolToken()` like so:
+If you already have BCT/NCT, you can use `autoOffsetPoolToken()` like this:
 
 ```typescript
-const offsetReceipt = await toucan.autoOffsetUsingPoolToken(
+const offsetReceipt = await toucan.autoOffsetPoolToken(
   "NCT",
   parseEther("1.0")
 );
@@ -272,9 +309,9 @@ If you do, that's also quite easy to pull off. You just replace the usage of the
 
 ```typescript
 const retirementReceipt = await toucan.retireAndMintCertificate(
-  "Alex",
+  "Alice",
   signer.address,
-  "Alex",
+  "Bob",
   "Just helping the planet",
   parseEther("3.0"),
   tco2s[len - 1].address
@@ -283,6 +320,6 @@ const retirementReceipt = await toucan.retireAndMintCertificate(
 
 Why do you see my name twice you ask? 🤔
 
-Well, the first "Alex" represents the entity that is doing the retirement/offset. The second one represents the party that 'benefits' from it. The address also represents the beneficiary.
+Well, the first "Alice" represents the entity that is doing the retirement/offset. The second one represents the party that 'benefits' from it, in this case "Bob". We will also add Bob's address so now the relation of the certificate is set to that address instead of the retiring party.
 
-That's useful in case you happen to be an entity that retires on behalf of someone else.
+This useful in case you happen to be an entity that retires on behalf of someone else.

docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.