Skip to content

Commit

Permalink
update readme for contractkit and cli
Browse files Browse the repository at this point in the history 
simplify and reduce number of examples. link to proper docs.

try running tests on node 20
  • Loading branch information
@aaronmgdr
aaronmgdr committed Dec 9, 2024
1 parent 26b9779 commit 4fa63c6
Show file tree
Hide file tree
Showing 4 changed files with 72 additions and 258 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,14 @@ jobs:
steps:
- uses: actions/setup-node@v4
with:
node-version: '18'
node-version: '20'
- name: 'enable corepack for yarn'
run: sudo corepack enable yarn
- uses: actions/checkout@v4
# must call twice because of chicken and egg problem with yarn and node
- uses: actions/setup-node@v4
with:
node-version: '18'
node-version: '20'
cache: 'yarn'
- name: Restore node cache
uses: actions/cache@v4
Expand Down
272 changes: 29 additions & 243 deletions docs/sdk/contractkit/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,303 +6,89 @@ Celo's ContractKit is a library to help developers and validators to interact wi

ContractKit supports the following functionality:

- Connect to a node
- Access web3 object to interact with node's Json RPC API
- Interact with json RPC API
- Send Transaction with celo's extra fields: (feeCurrency)
- Simple interface to interact with CELO and cUSD
- Simple interface to interact with Celo Core contracts
- Utilities
- Build apps to interact with governance and staking

## User Guide

:::tip

You might not need the full ContractKit. Consider using `@celo/connect` which powers much of ContractKit such as building and sending Transactions, signing, etc, but does not give access to any celo Contract Wrappers. Or if a subset of Wrappers, setting the feeCurrency and account info is all your dapp needs consider replacing your imports of Contractkit with `@celo/contractkit/lib/mini-kit`
You might not need the ContractKit. We for new projects we recommened [viem](https://viem.sh/docs/chains/celo) or [web3](https://www.npmjs.com/package/web3) optionally with [our celo plugin](https://www.npmjs.com/package/@celo/web3-plugin-transaction-types).

:::

## How we work

We are a GitHub-first team, which means we have a strong preference for communicating via GitHub.
Please use GitHub to:

🐞 [File a bug report](https://github.com/celo-org/developer-tooling/issues/new/choose)

💬 [Ask a question](https://github.com/celo-org/developer-tooling/discussions)

✨ [Suggest a feature](https://github.com/celo-org/developer-tooling/issues/new/choose)

🧑‍💻 [Contribute!](/CONTRIBUTING.md)

🚔 [Report a security vulnerability](https://github.com/celo-org/developer-tooling/issues/new/choose)

> [!TIP]
>
> Please avoid messaging us via Slack, Telegram, or email. We are more likely to respond to you on
> GitHub than if you message us anywhere else. We actively monitor GitHub, and will get back to you shortly 🌟
### Getting Started

To install:
To install you will need Node.js v18.14.2. or greater.

```bash
npm install @celo/contractkit
// or
yarn add @celo/contractkit
```

You will need Node.js v18.14.2. or greater.

To start working with contractkit you need a `kit` instance:

```ts
import { newKit } from '@celo/contractkit' // or import { newKit } from '@celo/contractkit/lib/mini-kit'
// Remotely connect to the Alfajores testnet
const kit = newKit('https://alfajores-forno.celo-testnet.org')
```

To access balances:

```ts
// returns an object with {lockedGold, pending, cUSD, cEUR, cREAL}

const balances = await kit.getTotalBalance()

// returns an object with {cUSD, cEUR, cREAL}
const balances = await miniKit.getTotalBalance()
```

If you don't need the balances of all tokens use the balanceOf method

```ts
const stableTokenWrapper = await kit.getStableToken(StableToken.cREAL)

const cRealBalance = stableTokenWrapper.balanceOf(accountAddress)
```

### Setting Default Tx Options
### Examples

`kit` allows you to set default transaction options:
To start working with contractkit you need a `kit` instance:

```ts
import { newKit, CeloContract } from '@celo/contractkit/lib/mini-kit'

async function getKit(myAddress: string, privateKey: string) {
const kit = newKit('https://alfajores-forno.celo-testnet.org')

// default from account
kit.defaultAccount = myAddress

// add the account private key for tx signing when connecting to a remote node
kit.connection.addAccount(privateKey)
import { newKit } from '@celo/contractkit' // or import { newKit } from '@celo/contractkit/lib/mini-kit'
// paid gas in celo dollars
await kit.setFeeCurrency('0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1')
const kit = newKit("https://alfajores-forno.celo-testnet.org")

return kit
}
```

### Interacting with CELO & cUSD

Celo has two initial coins: CELO and cUSD (stableToken).
Both implement the ERC20 standard, and to interact with them is as simple as:
#### List Registered ValidatorGroups

```ts
// get the CELO contract
const celoToken = await kit.contracts.getGoldToken()

// get the cUSD contract
const stableToken = await kit.contracts.getStableToken()

const celoBalance = await celoToken.balanceOf(someAddress)
const cusdBalance = await stableToken.balanceOf(someAddress)
```

To send funds:

```ts
const oneGold = kit.connection.web3.utils.toWei('1', 'ether')
const tx = await goldToken.transfer(someAddress, oneGold).send({
from: myAddress,
})
const validatorsContractWrapper = await kit.contracts.getValidators()
const validatorGroups = await validatorsContractWrapper.getRegisteredValidatorGroups()

const hash = await tx.getHash()
const receipt = await tx.waitReceipt()
```

If you would like to pay fees in cUSD, (or other cStables like cEUR, cUSD).
### Show locked Celo balance for account

```ts
kit.setFeeCurrency('0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1') // Default to paying fees in cUSD

const stableTokenContract = kit.contracts.getStableToken()

const tx = await stableTokenContract
.transfer(recipient, weiTransferAmount)
.send({ from: myAddress, gasPrice })
const lockedGoldContractWrapper = await kit.contracts.getLockedGold()

const hash = await tx.getHash()
const accountAddress = kit.defaultAccount
const summary = lockedGoldContractWrapper.getAccountSummary(accountAddress!)

const receipt = await tx.waitReceipt()
```

### Interacting with Core Contracts

There are many core contracts.

- AccountsWrapper
- AttestationsWrapper
- BlockchainParametersWrapper
- DoubleSigningSlasherWrapper
- DowntimeSlasherWrapper
- ElectionWrapper
- EpochRewardsWrapper
- Erc20Wrapper
- EscrowWrapper
- FreezerWrapper
- GasPriceMinimumWrapper
- GoldTokenWrapper
- GovernanceWrapper
- LockedGoldWrapper
- MultiSigWrapper
- ReserveWrapper
- SortedOraclesWrapper
- StableTokenWrapper
- ValidatorsWrapper

#### Wrappers Through Kit

When using the `kit` you can access core contracts like

`kit.contracts.get{ContractName}`

E.G. `kit.contracts.getAccounts()`, `kit.contracts.getValidators()`

#### Stand Alone Wrappers

You can also initialize contracts wrappers directly. They require a `Connection` and their contract:

```typescript
// MiniContractKit only gives access to a limited set of Contracts, so we import Multisig

import { newKit } from '@celo/contractkit/lib/mini-kit'
import { MultiSigWrapper } from '@celo/contractkit/lib/wrappers/MultiSig'
import { newMultiSig } from '@celo/abis/web3/MultiSig'

const miniKit = newKit('https://alfajores-forno.celo-testnet.org/')

// Alternatively import { Connection } from '@celo/connect'
// const connection = new Connection(web3)

const contract = newMultiSig(web3)

const multisigWrapper = new MultiSigWrapper(miniKit.connection, contract)
```

### Accessing web3 contract wrappers

`MiniContractKit` _does not provide access to the web3 contracts_

Some user might want to access web3 native contract wrappers.

To do so, you can:

```ts
const feeCurrencyWhitelist = await kit._web3Contracts.getContract(CeloContract.FeeCurrencyWhitelist)
```

We expose native wrappers for all Celo core contracts.

The complete list of Celo Core contracts is:

- Accounts
- Attestations
- BlockchainParameters
- DoubleSigningSlasher
- DowntimeSlasher
- Election
- EpochRewards
- ERC20
- Escrow
- FederatedAttestations
- FeeCurrencyWhitelist
- FeeHandler
- Freezer
- GasPriceMinimum
- GoldToken
- Governance
- LockedGold
- MentoFeeHandlerSeller
- UniswapFeeHandlerSeller
- MultiSig
- OdisPayments
- Random
- Registry
- Reserve
- SortedOracles
- StableToken
- StableTokenEUR
- StableTokenBRL
- Validators

This can also be found in `packages/sdk/contractkit/src/base.ts`

### A Note About Contract Addresses

Celo Core Contracts addresses, can be obtained by looking at the `Registry` contract.
That's how `kit` obtains them.

We expose the registry API, which can be accessed by:

```ts
const goldTokenAddress = await kit.registry.addressFor(CeloContract.GoldToken)
```

### Sending Custom Transactions
### More Information

Celo transaction object is not the same as Ethereum's. There are three new fields present:
You can find more information about the ContractKit in the Celo docs at [https://docs.celo.org/developer-guide/contractkit](https://docs.celo.org/developer-guide/contractkit).

- feeCurrency (address of the ERC20 contract to use to pay for gas and the gateway fee)
- gatewayFeeRecipient (coinbase address of the full serving the light client's trasactions)
- gatewayFee (value paid to the gateway fee recipient, denominated in the fee currency)

:::note
The `gatewayFeeRecipient`, and `gatewayFee` fields are currently not used by the protocol.
:::
## How we work

This means that using `web3.eth.sendTransaction` or `myContract.methods.transfer().send()` should be avoided to take advantage of paying transaction fees in alternative currencies.
We are a GitHub-first team, which means we have a strong preference for communicating via GitHub.
Please use GitHub to:

Instead, `kit` provides an utility method to send transaction in both scenarios. **If you use contract wrappers, there is no need to use this.**
🐞 [File a bug report](https://github.com/celo-org/developer-tooling/issues/new/choose)

For a raw transaction:
💬 [Ask a question](https://github.com/celo-org/developer-tooling/discussions)

```ts
const tx = kit.sendTransaction({
from: myAddress,
to: someAddress,
value: oneGold,
})
const hash = await tx.getHash()
const receipt = await tx.waitReceipt()
```
✨ [Suggest a feature](https://github.com/celo-org/developer-tooling/issues/new/choose)

When interacting with a web3 contract object:
🧑‍💻 [Contribute!](/CONTRIBUTING.md)

```ts
const celoNativeToken = await kit._web3Contracts.getGoldToken()
const oneGold = kit.connection.web3.utils.toWei('1', 'ether')
🚔 [Report a security vulnerability](https://github.com/celo-org/developer-tooling/issues/new/choose)

const txo = await celoNativeToken.methods.transfer(someAddress, oneGold)
const tx = await kit.sendTransactionObject(txo, { from: myAddress })
const hash = await tx.getHash()
const receipt = await tx.waitReceipt()
```
> [!TIP]
>
> Please avoid messaging us via Slack, Telegram, or email. We are more likely to respond to you on
> GitHub than if you message us anywhere else. We actively monitor GitHub, and will get back to you shortly 🌟
### More Information

You can find more information about the ContractKit in the Celo docs at [https://docs.celo.org/developer-guide/contractkit](https://docs.celo.org/developer-guide/contractkit).

### Debugging

Expand Down
Loading

0 comments on commit 4fa63c6

Please sign in to comment.