Skip to content

Commit

Permalink
tidy
Browse files Browse the repository at this point in the history
  • Loading branch information
@aaronmgdr
aaronmgdr committed Dec 9, 2024
1 parent 8906238 commit cdd8fa1
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 261 deletions.
14 changes: 2 additions & 12 deletions docs/sdk/contractkit/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,24 +13,18 @@ ContractKit supports the following functionality:
## User Guide

> [!TIP]
> 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).
:::
> You might not need the ContractKit. 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).
### Getting Started

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

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





### Examples

To start working with contractkit you need a `kit` instance:
Expand Down Expand Up @@ -61,12 +55,10 @@ const summary = lockedGoldContractWrapper.getAccountSummary(accountAddress!)

```


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


## How we work

We are a GitHub-first team, which means we have a strong preference for communicating via GitHub.
Expand All @@ -87,8 +79,6 @@ Please use GitHub to:
> 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 🌟


### Debugging

If you need to debug `kit`, we use the well known [debug](https://github.com/visionmedia/debug) node library.
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/README.md
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

276 changes: 28 additions & 248 deletions packages/sdk/contractkit/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,303 +4,83 @@ 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`

:::

## 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 🌟
> You might not need the ContractKit. 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).

### Getting Started

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

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

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

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:
const kit = newKit("https://alfajores-forno.celo-testnet.org")

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

`kit` allows you to set default transaction options:

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

// paid gas in celo dollars
await kit.setFeeCurrency('0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1')

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 lockedGoldContractWrapper = await kit.contracts.getLockedGold()

const stableTokenContract = kit.contracts.getStableToken()
const accountAddress = kit.defaultAccount
const summary = lockedGoldContractWrapper.getAccountSummary(accountAddress!)

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

const hash = await tx.getHash()

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

0 comments on commit cdd8fa1

Please sign in to comment.