Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[LILA-7729] README updates #114

Merged
merged 2 commits into from
Aug 21, 2024
Merged

[LILA-7729] README updates #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1488e66
README updates
0xmichalis Aug 21, 2024
915a51d
Run yarn docs
0xmichalis Aug 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Before you can make Subgraph queries, you need to set `GRAPH_API_KEY` in your `.

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.
We recommend using [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/)

Expand Down Expand Up @@ -76,7 +76,7 @@ toucan.setSigner(signer);

If you don't have a signer nor a provider set, you can only interact with the subgraph.

## Fetch pool prices from a Dex
## Fetch pool prices from a DEX

IMPORTANT:
_Fetching pool prices is currently not working. We are working on a fix for this._
Expand All @@ -102,7 +102,7 @@ The object returned by the above method will look like this:

# Interact with Toucan's Contracts?

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:
You can always access any method or property of the pool and TCO2 [contracts](https://github.com/ToucanProtocol/contracts) by first getting and storing them in a variable, like this:

```typescript
toucan.setSigner(signer);
Expand All @@ -119,7 +119,7 @@ It's important to note that, if you want to use write methods you need to have a

## Example to retire Carbon Credits

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).
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 TCO2s and get a certificate for the retirement. 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/developers/smart-contracts/tco2).

**Redeem your Pool Tokens and get an array of redeemed TCO2s**

Expand All @@ -139,7 +139,7 @@ Now, the above example of selective retirement is only useful in specific cases.

**What if you only have the name or symbol of the project?**

That's where subgraph queries come in handy. (and we have plenty of those 😉) - But feel free to also [create your own](#custom-queries).
That's where subgraph queries come in handy (and we have plenty of those 😉) - but feel free to also [create your own](#custom-queries).

**_Make sure all addresses are input in lowercase letters, as the queries are case sensitive._**

Expand Down Expand Up @@ -213,7 +213,7 @@ await toucan.fetchAggregations();

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:
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:

- [Matic](https://thegraph.com/explorer/subgraphs/FU5APMSSCqcRy9jy56aXJiGV3PQmFQHg2tzukvSJBgwW)
- [Celo](https://thegraph.com/explorer/subgraphs/BWmN569zDopYXp3nzDukJsGDHqRstYAFULFPH8rxyVBk)
Expand Down Expand Up @@ -253,7 +253,7 @@ const result = await toucan.fetchCustomQuery(query, { id: "1" });

Using the OffsetHelper methods is the easiest way to offset CO2 right now as it handles the whole process for you.

_(Uses Ubeswap/SushiSwap to acquire BCT/NCT, redeems it for TCO2s and retires them)_
_(Uses Ubeswap/SushiSwap to acquire pool tokens, redeems pool tokens for TCO2s and retires TCO2s)_

This is how you do that when you want to use ETH (or the network's native currency) in your balance.

Expand All @@ -280,9 +280,9 @@ const offsetReceipt = await toucan.autoOffsetExactInToken(
);
```

### Offset with your own BCT/NCT
### Offset with your pool tokens

If you already have BCT/NCT, you can use `autoOffsetPoolToken()` like this:
If you already have pool tokens (eg. NCT,) you can use `autoOffsetPoolToken()` like this:

```typescript
const offsetReceipt = await toucan.autoOffsetPoolToken(
Expand Down
74 changes: 57 additions & 17 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ For the full documentation, check our [docs](https://docs.toucan.earth/toucan/de

⚠️ This SDK is heavily under development. USE AT YOUR OWN RISK. ⚠️

## Install
## Install and setup

```
npm i toucan-sdk
Expand All @@ -24,13 +24,45 @@ or
yarn add toucan-sdk
```

Now, copy `.env.example` to `.env`.

Before you can make Subgraph queries, you need to set `GRAPH_API_KEY` in your `.env` file. You can create an API key in [The Graph Studio](https://thegraph.com/studio/apikeys/) after connecting your wallet.

# Quickstart

Instantiate the ToucanClient and set a `signer` & `provider` to interact with our infrastructure.

We recommend using [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);
```

Expand All @@ -46,7 +78,10 @@ toucan.setSigner(signer);

If you don't have a signer nor a provider set, you can only interact with the subgraph.

## Fetch pool prices from a Dex
## Fetch pool prices from a DEX

IMPORTANT:
_Fetching pool prices is currently not working. We are working on a fix for this._

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).

Expand All @@ -69,7 +104,7 @@ The object returned by the above method will look like this:

# Interact with Toucan's Contracts?

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:
You can always access any method or property of the pool and TCO2 [contracts](https://github.com/ToucanProtocol/contracts) by first getting and storing them in a variable, like this:

```typescript
toucan.setSigner(signer);
Expand All @@ -86,12 +121,12 @@ It's important to note that, if you want to use write methods you need to have a

## Example to retire Carbon Credits

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).
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 TCO2s and get a certificate for the retirement. 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/developers/smart-contracts/tco2).

**Redeem your Pool Tokens and get an array of redeemed TCO2s**

```typescript
const tco2Addresses = await toucan.redeemAuto2("NCT", parseEther("1"));
const tco2Addresses = await toucan.redeemAuto("NCT", parseEther("1"));
```

**Retire the Carbon Credits**
Expand All @@ -106,7 +141,7 @@ Now, the above example of selective retirement is only useful in specific cases.

**What if you only have the name or symbol of the project?**

That's where subgraph queries come in handy. (and we have plenty of those 😉) - But feel free to also [create your own](#custom-queries).
That's where subgraph queries come in handy (and we have plenty of those 😉) - but feel free to also [create your own](#custom-queries).

**_Make sure all addresses are input in lowercase letters, as the queries are case sensitive._**

Expand Down Expand Up @@ -135,12 +170,12 @@ The result will look like this:

Now you have quite some info on the project, including its address.

## All queries:
## All queries

Toucan SDK offers a lot of pre-defined queries. Try them out!

```typescript
import ToucanClient from "toucan-sdk";
import { ToucanClient } from "toucan-sdk";

// here we don't need to set the signer or provider
const toucan = new ToucanClient("alfajores");
Expand Down Expand Up @@ -180,13 +215,20 @@ await toucan.fetchAggregations();

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).
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:
0xmichalis marked this conversation as resolved.
Show resolved Hide resolved

- [Matic](https://thegraph.com/explorer/subgraphs/FU5APMSSCqcRy9jy56aXJiGV3PQmFQHg2tzukvSJBgwW)
- [Celo](https://thegraph.com/explorer/subgraphs/BWmN569zDopYXp3nzDukJsGDHqRstYAFULFPH8rxyVBk)
- [Base](https://thegraph.com/explorer/subgraphs/AEJ5PEDye6Z198HRQBioG6mZ6ZacHenBg2HTopZPsUCi)
- [Alfajores](https://thegraph.com/explorer/subgraphs/4uY2L3vQW8XKYPrFFk4i6ZuJkgbpJ8SbJayc8wzMBRYw)
- [Base Sepolia](https://thegraph.com/explorer/subgraphs/2oKCq3rDwdYPSao4UbDZKSNbawEdhBVf3BxmqJzFe1uj)
- [Amoy](https://thegraph.com/explorer/subgraphs/FKzFZuYHxyHiiDmdW9Qvwtet1Ad1ERsvjWMhhqd9V8pk)

- Getting all infos on a carbon project (`region` stands for the country)

```typescript
import { gql } from "@urql/core";
import ToucanClient from "toucan-sdk";
import { ToucanClient } from "toucan-sdk";

const toucan = new ToucanClient("alfajores");

Expand All @@ -213,7 +255,7 @@ const result = await toucan.fetchCustomQuery(query, { id: "1" });

Using the OffsetHelper methods is the easiest way to offset CO2 right now as it handles the whole process for you.

_(Uses Ubeswap/SushiSwap to acquire BCT/NCT, redeems it for TCO2s and retires them)_
_(Uses Ubeswap/SushiSwap to acquire pool tokens, redeems pool tokens for TCO2s and retires TCO2s)_

This is how you do that when you want to use ETH (or the network's native currency) in your balance.

Expand All @@ -240,9 +282,9 @@ const offsetReceipt = await toucan.autoOffsetExactInToken(
);
```

### Offset with your own BCT/NCT
### Offset with your pool tokens

If you already have BCT/NCT, you can use `autoOffsetPoolToken()` like this:
If you already have pool tokens (eg. NCT,) you can use `autoOffsetPoolToken()` like this:

```typescript
const offsetReceipt = await toucan.autoOffsetPoolToken(
Expand Down Expand Up @@ -284,16 +326,14 @@ If you do, that's also quite easy to pull off. You just replace the usage of the
```typescript
const retirementReceipt = await toucan.retireAndMintCertificate(
"Alice",
signer.address,
bobsAddress,
"Bob",
"Just helping the planet",
parseEther("3.0"),
tco2s[len - 1].address
);
```

Why do you see my name twice you ask? 🤔

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.
"Alice" represents the entity that is doing the retirement/offset. The second name 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.

This useful in case you happen to be an entity that retires on behalf of someone else.
Loading
Loading