From 4fa63c6892def831b6f76f4e92d79aa5265cb20d Mon Sep 17 00:00:00 2001 From: Aaron DeRuvo Date: Mon, 9 Dec 2024 11:55:19 +0100 Subject: [PATCH] update readme for contractkit and cli simplify and reduce number of examples. link to proper docs. try running tests on node 20 --- .github/workflows/ci.yml | 4 +- docs/sdk/contractkit/README.md | 272 ++++----------------------------- packages/cli/README.md | 52 +++++-- packages/cli/package.json | 2 +- 4 files changed, 72 insertions(+), 258 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af8fc95a5..b17391086 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/docs/sdk/contractkit/README.md b/docs/sdk/contractkit/README.md index 8761ddb2b..d005db316 100644 --- a/docs/sdk/contractkit/README.md +++ b/docs/sdk/contractkit/README.md @@ -6,44 +6,21 @@ 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 @@ -51,258 +28,67 @@ npm install @celo/contractkit 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 diff --git a/packages/cli/README.md b/packages/cli/README.md index 900486dc1..12bc54d35 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -4,7 +4,7 @@ Tool for interacting with the Celo Protocol. ## Installation -We are currently deploying the CLI with only Node.js v18.14.2 support. +celocli is tested on node 20, although we find it works with warnings on 18 and 22 as well. To install globally, run: @@ -14,6 +14,45 @@ npm install -g @celo/celocli If you have trouble installing globally (i.e. with the `-g` flag), try installing to a local directory instead with `npm install @celo/celocli` and run with `npx celocli`. +For the cutting edge of development you can install the latest beta + +``` +npm install -g @celo/celocli@beta +``` + +## Using the celo + +To see available commands + +```bash + +celocli commands + +``` + +Check version + +```bash + +celocli --version + +``` + +Example of running a command. + +```bash + +celocli network:whitelist --node celo + +``` + +### Documentation + +[Head to the documentation](https://docs.celo.org/cli) to read and learn more about the Celo +CLI. + + + ## How we work We are a GitHub-first team, which means we have a strong preference for communicating via GitHub. @@ -34,18 +73,7 @@ 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 🌟 -### Documentation - -[Head to the documentation](https://docs.celo.org/) to read and learn more about the Celo -CLI. - -### Plugins - -Additional plugins can be installed which make the CLI experience smoother. Currently, `celocli` only supports installing plugins published on NPM within the `@celo/*` and `@clabs/*` scopes. -> ⚠️ **Warning** -> -> Installing a 3rd party plugin can be dangerous! Please always be sure that you trust the plugin provider. ## Development diff --git a/packages/cli/package.json b/packages/cli/package.json index c37608720..d497b2204 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -19,7 +19,7 @@ "celo-cli" ], "engines": { - "node": ">=16" + "node": ">=18" }, "scripts": { "clean": "rm -f tsconfig.tsbuildinfo && rm -rf lib/ && yarn run --top-level tsc -b . --clean",