diff --git a/build-on-celo/build-on-minipay/code-library.mdx b/build-on-celo/build-on-minipay/code-library.mdx index 249b60e165..984fd45f28 100644 --- a/build-on-celo/build-on-minipay/code-library.mdx +++ b/build-on-celo/build-on-minipay/code-library.mdx @@ -7,7 +7,7 @@ sidebarTitle: "Code Library" Snippets of code that can be used to implement flows inside MiniPay -Make sure you are using Typescript v5 or above and Viem v2 or above. + Make sure you are using Typescript v5 or above and Viem v2 or above. ## Get the connected user's address without any Library @@ -43,61 +43,61 @@ To use the code snippets below, install the following packages: ```bash yarn - yarn add @celo/abis @celo/identity viem@1 + yarn add @celo/abis @celo/identity viem@2 ``` ```bash npm - npm install @celo/abis @celo/identity viem@1 + npm install @celo/abis @celo/identity viem@2 ``` ## Check cUSD Balance of an address - ```js - const { getContract, formatEther, createPublicClient, http } = require("viem"); - const { celo } = require("viem/chains"); - const { stableTokenABI } = require("@celo/abis"); - - const STABLE_TOKEN_ADDRESS = "0x765DE816845861e75A25fCA122bb6898B8B1282a"; +```js +import { getContract, formatEther, createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; +import { stableTokenABI } from "@celo/abis"; - async function checkCUSDBalance(publicClient, address) { - let StableTokenContract = getContract({ - abi: stableTokenABI, - address: STABLE_TOKEN_ADDRESS, - publicClient, - }); +// cUSD address on Celo mainnet +const STABLE_TOKEN_ADDRESS = "0x765DE816845861e75A25fCA122bb6898B8B1282a"; - let balanceInBigNumber = await StableTokenContract.read.balanceOf([ - address, - ]); +async function checkCUSDBalance(publicClient, address) { + const StableTokenContract = getContract({ + abi: stableTokenABI, + address: STABLE_TOKEN_ADDRESS, + client: publicClient, + }); - let balanceInWei = balanceInBigNumber.toString(); + const balanceInBigNumber = await StableTokenContract.read.balanceOf([ + address, + ]); - let balanceInEthers = formatEther(balanceInWei); + const balanceInWei = balanceInBigNumber.toString(); + const balanceInEthers = formatEther(balanceInWei); - return balanceInEthers; - } + return balanceInEthers; +} - const publicClient = createPublicClient({ - chain: celo, - transport: http(), - }); // Mainnet +const publicClient = createPublicClient({ + chain: celo, + transport: http(), +}); // Mainnet - let balance = await checkCUSDBalance(publicClient, address); // In Ether unit - ``` +const balance = await checkCUSDBalance(publicClient, address); // In Ether unit +``` ## Check If a transaction succeeded ```js -const { createPublicClient, http } = require("viem"); -const { celo } = require("viem/chains"); +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; async function checkIfTransactionSucceeded(publicClient, transactionHash) { - let receipt = await publicClient.getTransactionReceipt({ + const receipt = await publicClient.getTransactionReceipt({ hash: transactionHash, }); @@ -109,7 +109,7 @@ const publicClient = createPublicClient({ transport: http(), }); // Mainnet -let transactionStatus = await checkIfTransactionSucceeded( +const transactionStatus = await checkIfTransactionSucceeded( publicClient, transactionHash ); @@ -119,8 +119,8 @@ let transactionStatus = await checkIfTransactionSucceeded( ## Estimate Gas for a transaction (in Celo) ```js -const { createPublicClient, http } = require("viem"); -const { celo } = require("viem/chains"); +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; async function estimateGas(publicClient, transaction, feeCurrency = "") { return await publicClient.estimateGas({ @@ -134,7 +134,7 @@ const publicClient = createPublicClient({ transport: http(), }); -let gasLimit = await estimateGas(publicClient, { +const gasLimit = await estimateGas(publicClient, { account: "0x8eb02597d85abc268bc4769e06a0d4cc603ab05f", to: "0x4f93fa058b03953c851efaa2e4fc5c34afdfab84", value: "0x1", @@ -148,10 +148,9 @@ let gasLimit = await estimateGas(publicClient, { ## Estimate Gas for a transaction (in cUSD) - ```js -const { createPublicClient, http } = require("viem"); -const { celo } = require("viem/chains"); +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; async function estimateGas(publicClient, transaction, feeCurrency = "") { return await publicClient.estimateGas({ @@ -167,7 +166,7 @@ const publicClient = createPublicClient({ const STABLE_TOKEN_ADDRESS = "0x765DE816845861e75A25fCA122bb6898B8B1282a"; -let gasLimit = await estimateGas( +const gasLimit = await estimateGas( publicClient, { account: "0x8eb02597d85abc268bc4769e06a0d4cc603ab05f", @@ -184,8 +183,8 @@ let gasLimit = await estimateGas( ## Estimate Gas Price for a transaction (in Celo) ```js -const { createPublicClient, http } = require("viem"); -const { celo } = require("viem/chains"); +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; async function estimateGasPrice(publicClient, feeCurrency = "") { return await publicClient.request({ @@ -199,15 +198,14 @@ const publicClient = createPublicClient({ transport: http(), }); -let gasPrice = await estimateGasPrice(publicClient); +const gasPrice = await estimateGasPrice(publicClient); ``` ## Estimate Gas Price for a transaction (in cUSD) - ```js -const { createPublicClient, http } = require("viem"); -const { celo } = require("viem/chains"); +import { createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; async function estimateGasPrice(publicClient, feeCurrency = "") { return await publicClient.request({ @@ -223,42 +221,42 @@ const publicClient = createPublicClient({ const STABLE_TOKEN_ADDRESS = "0x765DE816845861e75A25fCA122bb6898B8B1282a"; -let gasPrice = await estimateGasPrice(publicClient, STABLE_TOKEN_ADDRESS); +const gasPrice = await estimateGasPrice(publicClient, STABLE_TOKEN_ADDRESS); ``` ## Calculate cUSD to be spent for transaction fees - - - ```js -const { createPublicClient, http, formatEther } = require("viem"); -const { celo } = require("viem/chains"); +```js +import { createPublicClient, http, formatEther, fromHex } from "viem"; +import { celo } from "viem/chains"; const publicClient = createPublicClient({ - chain: celo, - transport: http(), + chain: celo, + transport: http(), }); const STABLE_TOKEN_ADDRESS = "0x765DE816845861e75A25fCA122bb6898B8B1282a"; // `estimateGas` implemented above -let gasLimit = await estimateGas( - publicClient, - { - account: "0x8eb02597d85abc268bc4769e06a0d4cc603ab05f", - to: "0x4f93fa058b03953c851efaa2e4fc5c34afdfab84", - value: "0x1", - data: "0x", - }, - STABLE_TOKEN_ADDRESS +const gasLimit = await estimateGas( + publicClient, + { + account: "0x8eb02597d85abc268bc4769e06a0d4cc603ab05f", + to: "0x4f93fa058b03953c851efaa2e4fc5c34afdfab84", + value: "0x1", + data: "0x", + }, + STABLE_TOKEN_ADDRESS ); // `estimateGasPrice` implemented above -let gasPrice = await estimateGasPrice(publicClient, STABLE_TOKEN_ADDRESS); +const gasPrice = await estimateGasPrice(publicClient, STABLE_TOKEN_ADDRESS); -let transactionFeesInCUSD = formatEther(gasLimit * hexToBigInt(gasPrice)); - ``` +// Convert hex gas price to BigInt and calculate fees +const gasPriceBigInt = fromHex(gasPrice, "bigint"); +const transactionFeesInCUSD = formatEther(gasLimit * gasPriceBigInt); +``` @@ -275,15 +273,15 @@ npm install @celo/identity The issuer is the account registering attestations. When a user requests attestation registration, verify they own the identifier (e.g., SMS verification for phone numbers). ```js -import { createClient } from "viem"; +import { createWalletClient, http } from "viem"; import { celoSepolia } from "viem/chains"; import { privateKeyToAccount } from "viem/accounts"; // The issuer is the account that is registering the attestation -let ISSUER_PRIVATE_KEY = "YOUR_ISSUER_PRIVATE_KEY"; +const ISSUER_PRIVATE_KEY = "YOUR_ISSUER_PRIVATE_KEY"; // Create Celo Sepolia viem client with the issuer private key -const viemClient = createClient({ +const viemClient = createWalletClient({ account: privateKeyToAccount(ISSUER_PRIVATE_KEY), transport: http(), chain: celoSepolia, @@ -302,6 +300,7 @@ const attestationVerifiedTime = Date.now(); ```js import { OdisUtils } from "@celo/identity"; import { AuthSigner } from "@celo/identity/lib/odis/query"; +import { OdisContextName } from "@celo/identity/lib/odis/query"; // authSigner provides information needed to authenticate with ODIS const authSigner: AuthSigner = { @@ -315,6 +314,7 @@ const serviceContext = OdisUtils.Query.getServiceContext( ); // Check existing quota on issuer account +const issuerAddress = viemClient.account.address; const { remainingQuota } = await OdisUtils.Quota.getPnpQuotaStatus( issuerAddress, authSigner, @@ -322,18 +322,10 @@ const { remainingQuota } = await OdisUtils.Quota.getPnpQuotaStatus( ); // If needed, approve and send payment to OdisPayments to get quota for ODIS +// Note: This example uses viem. For contract interactions, use getContract from viem if (remainingQuota < 1) { - const stableTokenContract = await kit.contracts.getStableToken(); - const odisPaymentsContract = await kit.contracts.getOdisPayments(); - const ONE_CENT_CUSD_WEI = 10000000000000000; - - await stableTokenContract - .increaseAllowance(odisPaymentsContract.address, ONE_CENT_CUSD_WEI) - .sendAndWaitForReceipt(); - - const odisPayment = await odisPaymentsContract - .payInCUSD(issuerAddress, ONE_CENT_CUSD_WEI) - .sendAndWaitForReceipt(); + // Use viem's getContract to interact with stable token and ODIS payments contracts + // Implementation depends on your specific contract setup } ``` @@ -367,31 +359,31 @@ console.log(attestations.accounts); ## Request an ERC20 token transfer ```js -import { createWalletClient, custom } from 'viem' -// import { celo } from 'viem/chains' -import { celoSepolia } from 'viem/chains' - -const client = createWalletClient({ - chain: celoSepolia, - // chain: celo, - transport: custom(window.ethereum!) -}) - -const publicClient = createPublicClient({ - chain: celoSepolia, - // chain: celo, - transport: http() -}) +import { createWalletClient, createPublicClient, custom, http, encodeFunctionData, parseUnits } from "viem"; +import { celo, celoSepolia } from "viem/chains"; +import { stableTokenABI } from "@celo/abis"; + +const walletClient = createWalletClient({ + chain: celoSepolia, // For testnet + // chain: celo, // For mainnet + transport: custom(window.ethereum!), +}); -async function requestTransfer(tokenAddress, transferValue, tokenDecimals) { +const publicClient = createPublicClient({ + chain: celoSepolia, // For testnet + // chain: celo, // For mainnet + transport: http(), +}); - let hash = await client.sendTransaction({ +async function requestTransfer(tokenAddress, transferValue, tokenDecimals, receiverAddress) { + const hash = await walletClient.sendTransaction({ to: tokenAddress, - // to: '0x765DE816845861e75A25fCA122bb6898B8B1282a' // cUSD (Mainnet) - // to: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C' // USDC (Mainnet) - // to: '0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e' // USDT (Mainnet) + // Mainnet addresses: + // cUSD: '0x765DE816845861e75A25fCA122bb6898B8B1282a' + // USDC: '0xcebA9300f2b948710d2653dD7B07f33A8B32118C' + // USDT: '0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e' data: encodeFunctionData({ - abi: stableTokenAbi, // Token ABI can be fetched from Explorer. + abi: stableTokenABI, // Token ABI from @celo/abis functionName: "transfer", args: [ receiverAddress, @@ -399,9 +391,6 @@ async function requestTransfer(tokenAddress, transferValue, tokenDecimals) { parseUnits(`${Number(transferValue)}`, tokenDecimals), ], }), - // If the wallet is connected to a different network then you get an error. - chain: celoSepolia, - // chain: celo, }); const transaction = await publicClient.waitForTransactionReceipt({ diff --git a/build-on-celo/build-on-minipay/prerequisites/ngrok-setup.mdx b/build-on-celo/build-on-minipay/prerequisites/ngrok-setup.mdx index 67268eac42..38e532df0c 100644 --- a/build-on-celo/build-on-minipay/prerequisites/ngrok-setup.mdx +++ b/build-on-celo/build-on-minipay/prerequisites/ngrok-setup.mdx @@ -15,21 +15,17 @@ To solve this, we use `ngrok`. 1. Visit [ngrok.com](https://ngrok.com) - -![ngrok.com](/img/developer/build-on-minipay/ngrok-setup/1.png) - +![ngrok.com](/img/developer/build-on-minipay/ngrok-setup/1.png) 2. Sign up -![sign up ngrok](/img/developer/build-on-minipay/ngrok-setup/2.png) + ![sign up ngrok](/img/developer/build-on-minipay/ngrok-setup/2.png) 3. The dashboard will have instructions based on your OS on how to install and use ngrok! - -![dashboard](/img/developer/build-on-minipay/ngrok-setup/3.png) - +![dashboard](/img/developer/build-on-minipay/ngrok-setup/3.png) 4. Once installed you can use the following command to share your localhost port. @@ -40,7 +36,7 @@ To solve this, we use `ngrok`. The output looks something like this. -![ngrok output](/img/developer/build-on-minipay/ngrok-setup/4.png) + ![ngrok output](/img/developer/build-on-minipay/ngrok-setup/4.png) -You can use the highlighted url to launch the localhost dApp on the [MiniPay's Site Tester](http://docs.celo.org/developer/build-on-minipay/overview#test-your-dapp-inside-minipay). +You can use the highlighted url to launch the localhost dApp on the [MiniPay's Site Tester](/build-on-celo/build-on-minipay/quickstart#test-your-mini-app-inside-minipay). diff --git a/build-on-celo/build-on-minipay/quickstart.mdx b/build-on-celo/build-on-minipay/quickstart.mdx index cc98c5641f..aad89ad0cd 100644 --- a/build-on-celo/build-on-minipay/quickstart.mdx +++ b/build-on-celo/build-on-minipay/quickstart.mdx @@ -10,19 +10,22 @@ A step-by-step guide to setting up, building, and testing your MiniPay Mini App. ## 1. Installing MiniPay -MiniPay is designed for mainstream adoption, making digital payments simple and easy to use. +MiniPay is designed for mainstream adoption, making digital payments simple and easy to use. #### Key Features: + - **Currency Display**: Balances appear in your local currency. - **Stablecoin Support**: Only stablecoins (cUSD, USDC, and USDT) are supported. - **Simple Swaps**: The pocket swap feature allows for easy swaps between stablecoins by dragging one pocket into another. -MiniPay is only available on Celo and Celo Sepolia Testnet. Other blockchain networks are not supported. + MiniPay is only available on Celo and Celo Sepolia Testnet. Other blockchain + networks are not supported. #### How to Access MiniPay: -- [**Opera Mini Browser**](https://www.opera.com/pl/products/minipay) (Android) + +- [**Opera Mini Browser**](https://www.opera.com/pl/products/minipay) (Android) - [**Standalone App Android**](https://play.google.com/store/apps/details?id=com.opera.minipay) - [**Standalone App iOS**](https://apps.apple.com/de/app/minipay-easy-global-wallet/id6504087257?l=en-GB) @@ -40,7 +43,8 @@ MiniPay is only available on Celo and Celo Sepolia Testnet. Other blockchain net ```bash npx @celo/celo-composer@latest create -t minipay ``` -- Follow the [Quickstart Guide](/build/quickstart) for a step-by-step tutorial. + +- Follow the [Quickstart Guide](/build-on-celo/quickstart) for a step-by-step tutorial. #### For integrating an existing app: @@ -53,72 +57,76 @@ Request CELO testnet tokens from the Celo [faucet](https://faucet.celo.org/celo- ## 4. Test your Mini App inside MiniPay -You cannot test MiniPay using the Android Studio Emulator. Use an Android or iOS mobile device. + You cannot test MiniPay using the Android Studio Emulator. Use an Android or + iOS mobile device. ### Enable Developer Mode: + 1. Open the MiniPay app on your phone and navigate to settings. -Open MiniPay dApp store + Open MiniPay dApp store 2. In the **About** section, tap the **Version** number repeatedly until the confirmation message appears. -Open MiniPay dApp test page + Open MiniPay dApp test page 3. Return to **Settings**, then select **Developer Settings**. -MiniPay dApp testing + MiniPay dApp testing 4. Enable **Developer Mode** and toggle **Use Testnet** to connect to Sepolia L2 testnet. -MiniPay dApp testing + MiniPay dApp testing - ### Load Your Mini App: -1. In **Developer Settings,** tap **Load Test Page.** + +1. In **Developer Settings,** tap **Load Test Page.** 2. Enter your **Mini App URL.** - - If testing a local deployment, use [ngrok](#testing-local-development-with-minipay) to expose your localhost. + - If testing a local deployment, use [ngrok](#testing-local-development-with-minipay) to expose your localhost. -MiniPay dApp testing + MiniPay dApp testing 6. Click **Go** to launch and test your Mini App. -MiniPay dApp testing + MiniPay dApp testing --- @@ -126,18 +134,20 @@ You cannot test MiniPay using the Android Studio Emulator. Use an Android or iOS ## Helpful Tips to Make Your Mini App MiniPay Compatible -MiniPay uses Custom [Fee Abstraction](/developer/fee-abstraction) based transactions. We recommend using viem or wagmi as they provide native support for fee currency. + MiniPay uses Custom [Fee Abstraction](/tooling/fee-abstraction) based + transactions. We recommend using viem or wagmi as they provide native support + for fee currency. #### 1. Using Viem ```js import { createWalletClient, custom } from "viem"; -import { celo, celoAlfajores } from "viem/chains"; +import { celo, celoSepolia } from "viem/chains"; const client = createWalletClient({ chain: celo, - // chain: celoAlfajores, // For Celo Testnet + // chain: celoSepolia, // For Celo Sepolia Testnet transport: custom(window.ethereum), }); @@ -206,12 +216,12 @@ export default function Header() { - MiniPay currently supports setting the `feeCurrency` property when running `eth_sendTransaction`. However, currency support is limited to `cUSD`. More currencies might be supported in future. - MiniPay only accepts legacy transactions at the moment. EIP-1559 properties won't be considered when handling requests. - ## Testing Local Development with MiniPay -If you're developing your MiniApp locally (e.g., on `localhost:3000`), use `ngrok` to tunnel traffic over HTTP, for real-time testing. +If you're developing your MiniApp locally (e.g., on `localhost:3000`), use `ngrok` to tunnel traffic over HTTP, for real-time testing. #### Set Up ngrok + - **Install ngrok:** If you haven't already, install ngrok. You can find instructions on their [official website](https://ngrok.com/download). - **Start Your Local Server:** Ensure your local development server is running. For instance, if you're using Next.js, you might run `npm run dev` to start your server at `localhost:3000`. - **Tunnel Traffic with ngrok:** In your terminal, run the following command to start an ngrok tunnel: @@ -222,6 +232,6 @@ ngrok http 3000 This will provide you with a public URL that tunnels to your localhost. -For a more in depth guide, check out the official [ngrok setup](/build/build-on-minipay/prerequisites/ngrok-setup). +For a more in depth guide, check out the official [ngrok setup](/build-on-celo/build-on-minipay/prerequisites/ngrok-setup). -- **Test in MiniPay:** Copy the provided ngrok URL and use it inside the MiniPay app to test your DApp. \ No newline at end of file +- **Test in MiniPay:** Copy the provided ngrok URL and use it inside the MiniPay app to test your DApp. diff --git a/build-on-celo/build-with-ai/build-with-goat/mint-nft-agent.mdx b/build-on-celo/build-with-ai/build-with-goat/mint-nft-agent.mdx index 9f9e9235f5..bb6943d66a 100644 --- a/build-on-celo/build-with-ai/build-with-goat/mint-nft-agent.mdx +++ b/build-on-celo/build-with-ai/build-with-goat/mint-nft-agent.mdx @@ -69,7 +69,7 @@ const tools = await getOnChainTools({ // This is a placeholder - actual minting logic needs to be implemented console.log( `Minting NFT to address: ${recipientAddress} with metadata:`, - metadata, + metadata ); return "NFT minting initiated (placeholder - not actually minted). Implement actual minting logic in the execute function."; }, @@ -177,7 +177,7 @@ RPC_PROVIDER_URL=https://forno.celo-sepolia.celo-testnet.org/ // ... inside the plugins array in getOnChainTools: { name: "mintNFT", - og:description: "...", + description: "...", async execute({ recipientAddress, metadata }) { try { // 1. NFT Contract Address and ABI: diff --git a/build-on-celo/build-with-ai/build-with-goat/send-token-agent.mdx b/build-on-celo/build-with-ai/build-with-goat/send-token-agent.mdx index 29c3c17e30..561da145b1 100644 --- a/build-on-celo/build-with-ai/build-with-goat/send-token-agent.mdx +++ b/build-on-celo/build-with-ai/build-with-goat/send-token-agent.mdx @@ -145,48 +145,52 @@ Copy `.env.template` to `.env` and populate the following environment variables OPENAI_API_KEY=YOUR_OPENAI_API_KEY WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY RPC_PROVIDER_URL=https://forno.celo-sepolia.celo-testnet.org/ -OPENAI_API_KEY=YOUR_OPENAI_API_KEY -WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY -RPC_PROVIDER_URL=[https://forno.celo-sepolia.celo-testnet.org/](https://forno.celo-sepolia.celo-testnet.org/) ``` **Note:** We only need `OPENAI_API_KEY`, `WALLET_PRIVATE_KEY`, and `RPC_PROVIDER_URL` for this token sending agent. **3. Adapt Code for Celo Token Sending:** -1. **Chain Configuration:** In `index.ts`, replace `baseSepolia` with `celo` from `viem/chains`: +1. **Chain Configuration:** In `index.ts`, replace `baseSepolia` with `celoSepolia` from `viem/chains`: ```javascript - import { celoSepolia } from "viem/chains"; // Import Celo chain + import { celoSepolia } from "viem/chains"; // Import Celo Sepolia chain // ... const walletClient = createWalletClient({ account: account, transport: http(process.env.RPC_PROVIDER_URL), - chain: celo, // Use Celo chain configuration + chain: celoSepolia, // Use Celo Sepolia chain configuration for testnet }); ``` 2. **Adapt `sendETH()` to `sendCELO()`:** The `@goat-sdk/wallet-evm` might have a function specifically for sending CELO. Check the `@goat-sdk` documentation for `sendCELO()`. If it exists, replace `sendETH()` with `sendCELO()` in the `plugins` array: ```javascript + import { cUSD, CELO } from "@goat-sdk/plugin-erc20"; // Import Celo tokens + + // ... + plugins: [ - sendCELO(), // Enable CELO transfers (if available in @goat-sdk) - erc20({ tokens: [USDC, PEPE] }), // ERC20 token operations - Review tokens for Celo + sendETH(), // sendETH() is chain-aware and works with CELO on Celo network + erc20({ tokens: [cUSD, CELO] }), // Use Celo-specific tokens: cUSD, CELO // ... ]; ``` If `sendCELO()` is not directly available in `@goat-sdk/wallet-evm`, it's likely that `sendETH()` is designed to be chain-aware and will send the native token of the configured chain (`celo` in this case). In that case, you might not need to change `sendETH()`. **Test sending CELO after setup to confirm if `sendETH()` works for CELO or if you need to find an alternative.** If `sendETH()` does not work for CELO, you might need to create a custom tool using `viem`'s `sendTransaction` function to send CELO directly. -3. **Review ERC20 Tokens for Celo:** `USDC` and `PEPE` might not be ideal for Celo. Research popular ERC20 tokens on Celo Sepolia Testnet or Celo Mainnet (e.g., `cUSD`, `cEUR`, `USDT`, `DAI` on Celo). Update the `erc20` plugin configuration with relevant tokens: +3. **Use Celo-Specific Tokens:** Import and use Celo native tokens from `@goat-sdk/plugin-erc20`: ```javascript - erc20({ tokens: [cUSD, cEUR, USDT] }), // Example: Use cUSD, cEUR, USDT if relevant on Celo + import { cUSD, CELO } from "@goat-sdk/plugin-erc20"; + + // In plugins array: + erc20({ tokens: [cUSD, CELO] }), // Use Celo-specific tokens ``` - You might need to define or import configurations for `cUSD`, `cEUR`, `USDT` similar to `USDC` and `PEPE`, potentially using their token contract addresses on Celo. For a more generic approach, you can remove the `tokens` array to allow the agent to handle any ERC20 token specified by symbol or address in the prompt. + The `@goat-sdk/plugin-erc20` package includes pre-configured Celo tokens. For additional tokens, you can define custom token configurations or remove the `tokens` array to allow the agent to handle any ERC20 token specified by symbol or address in the prompt. **4. Usage Instructions:** @@ -229,4 +233,3 @@ Enter your prompt (or "exit" to quit): exit ### Conclusion This tutorial has guided you through building an AI-powered agent capable of sending tokens on the Celo Sepolia blockchain. By adapting the provided code, configuring for Celo Sepolia, and utilizing the `@goat-sdk/wallet-evm` and `@goat-sdk/plugin-erc20` tools, you can create an interactive agent that can understand natural language prompts to send both native CELO and ERC20 tokens. Remember to test thoroughly on the Celo Sepolia Testnet before using on Mainnet and always handle private keys securely. Explore the `@goat-sdk` documentation to understand more advanced configurations and error handling for your token sending agent on Celo! - diff --git a/build-on-celo/build-with-ai/build-with-goat/token-swap-agent.mdx b/build-on-celo/build-with-ai/build-with-goat/token-swap-agent.mdx index 462c7a939d..4de90e1afb 100644 --- a/build-on-celo/build-with-ai/build-with-goat/token-swap-agent.mdx +++ b/build-on-celo/build-with-ai/build-with-goat/token-swap-agent.mdx @@ -3,7 +3,6 @@ title: Build an AI-Powered Token Swap Agent on Celo Using GOAT SDK sidebarTitle: "Build a TokenSwap Agent" --- - This article provides a detailed guide on how to build an AI-powered token swap agent on the Celo blockchain using GOAT SDK. You'll learn how to create an interactive agent capable of performing token swaps through natural language prompts. ## Understanding GOAT SDK for Token Swapping @@ -179,12 +178,19 @@ Edit the `.env` file to include: ```plaintext OPENAI_API_KEY=your_openai_api_key WALLET_PRIVATE_KEY=your_wallet_private_key -RPC_PROVIDER_URL=https://forno.celo.org # Celo Mainnet -# or use https://forno.celo-sepolia.celo-testnet.org/ for Testnet +RPC_PROVIDER_URL=https://forno.celo-sepolia.celo-testnet.org/ # Celo Sepolia Testnet (recommended for testing) +# For mainnet: https://forno.celo.org UNISWAP_BASE_URL=provided_value # Will be populated from template UNISWAP_API_KEY=provided_value # Will be populated from template ``` +**Security Best Practices:** + +- Use a dedicated test wallet with minimal funds for development +- Never commit your `.env` file to version control +- Use environment variables for all sensitive data +- For production, use a dedicated RPC provider (Ankr, QuickNode, etc.) instead of public RPCs + For production use, you can get your own Uniswap API key from [Uniswap Hub](https://www.uniswap.org/developers). ### 5. Run the Interactive CLI @@ -234,4 +240,4 @@ When implementing token swap functionality on Celo, keep these additional consid By following this guide, you've learned how to create an AI-powered token swap agent on Celo using GOAT SDK. This agent can understand natural language commands and execute token swaps on your behalf, providing a seamless bridge between AI and blockchain functionality. -As Celo continues to grow as an ecosystem, these types of AI agents can significantly improve user experience by abstracting away the complexities of interacting with DeFi protocols and token swaps, making blockchain technology more accessible to everyone. \ No newline at end of file +As Celo continues to grow as an ecosystem, these types of AI agents can significantly improve user experience by abstracting away the complexities of interacting with DeFi protocols and token swaps, making blockchain technology more accessible to everyone. diff --git a/build-on-celo/build-with-ai/examples/ai-memecoins.mdx b/build-on-celo/build-with-ai/examples/ai-memecoins.mdx index 3ccfeef919..555a758cd5 100644 --- a/build-on-celo/build-with-ai/examples/ai-memecoins.mdx +++ b/build-on-celo/build-with-ai/examples/ai-memecoins.mdx @@ -10,36 +10,47 @@ sidebarTitle: "Launch AI Agent Memecoins" ## Create a Wallet and get your Gaia API Keys -1. Visit the [Gaia Homepage](https://www.gaianet.ai/) and click **`Launch App`**. -2. Click **`Connect`**, then install the [MetaMask](https://metamask.io/download/) extension. -3. Once installed, create your wallet and securely store your recovery keys. +1. Visit the [Gaia Homepage](https://www.gaianet.ai/) and click **`Launch App`**. +2. Click **`Connect`**, then install the [MetaMask](https://metamask.io/download/) extension. +3. Once installed, create your wallet and securely store your recovery keys. 4. Finally, navigate to [Gaia API Keys](https://www.gaianet.ai/setting/gaia-api-keys) to generate your API keys. ## Create you Celo Private Key 1. Install the [Celo CLI](npm install -g @celo/celocli) 2. Make sure you're working on Celo Sepolia testnet + ``` celocli config:set --rpc-url https://forno.celo-sepolia.celo-testnet.org ``` -3. Create an account and store it well formatted in an .env file + +3. Create an account and store it well formatted in an .env file + ``` celocli account:new | sed -E 's/: (.+)/="\1"/g' | grep '=' > .env` source .env ``` + 4. Copy the account address to your clipboard + ``` echo $accountAddress | pbcopy ``` + 5. Head to the faucet to get some money and paste your account address there + ``` open https://faucet.celo.org/celo-sepolia ``` + 6. Verify you got money successfully + ``` celocli account:balance $accountAddress ``` + 7. Register your account + ``` celocli account:register --from $accountAddress -k $privateKey ``` @@ -49,24 +60,33 @@ If you open your **`.env`** file, you will find your **`Celo private key`** ## Clone the Celo Meme Token Generator 1. Clone this repository + ``` git clone https://github.com/harishkotra/celo-token-agent cd celo-token-agent ``` + 2. Install dependencies + ``` npm install ``` + 3. Create a .env file: + ``` -PRIVATE_KEY=your_celo_private_key +PRIVATE_KEY=your_celo_private_key GAIA_API_KEY=your_gaia_api_keys ``` + 4. Compile the contract + ``` npx hardhat compile ``` + 5. Deploy your token + ``` node deploy.js ``` @@ -83,18 +103,23 @@ The script will The project uses three main components 1. Token Generation **`(tokenGenerator.js)`** - - Generates creative token names - - Uses AI with a fallback to random generation - - Configures initial token supply + +- Generates creative token names +- Uses AI with a fallback to random generation +- Configures initial token supply + 2. Contract Deployment **`(tokenDeployer.sol)`** - - Uses viem to interact with Celo - - Handles gas estimation and transaction monitoring - - Provides deployment status updates + +- Uses viem to interact with Celo +- Handles gas estimation and transaction monitoring +- Provides deployment status updates + 3. Smart Contract **`(tokenDeployer.js)`** - - Standard ERC20 implementation - - Built with OpenZeppelin for security - - Deployable to Celo Sepolia testnet - + +- Standard ERC20 implementation +- Built with OpenZeppelin for security +- Deployable to Celo Sepolia testnet + ## Example response ``` @@ -112,10 +137,10 @@ Token deployed successfully! symbol: 'MG', address: '0x5e473F7650ABD9B6A5b28b2B0B64ebBd1ef01D94', transactionHash: '0x035457c46ef5118db065b0a2ccc6bae1ce62f1c8ef688bbaf2d2596a6dd0fbd8', - explorer: 'https://alfajores.celoscan.io/address/0x5e473F7650ABD9B6A5b28b2B0B64ebBd1ef01D94' + explorer: 'https://celoscan.io/address/0x5e473F7650ABD9B6A5b28b2B0B64ebBd1ef01D94' # For Celo Sepolia: https://sepolia.celoscan.io/address/YOUR_CONTRACT_ADDRESS } ``` ## Support -Join the [Celo Discord server](https://chat.celo.org). Reach out in the #general-dev channel with your questions and feedback. \ No newline at end of file +Join the [Celo Discord server](https://discord.com/invite/celo). Reach out in the #build-with-celo channel with your questions and feedback. diff --git a/build-on-celo/build-with-ai/examples/build-with-nebula.mdx b/build-on-celo/build-with-ai/examples/build-with-nebula.mdx deleted file mode 100644 index 3d070b9fe1..0000000000 --- a/build-on-celo/build-with-ai/examples/build-with-nebula.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ERC20 Telegram Mini-app Token Deployer with Nebula -og:description: Learn how to use thirdweb's LLM Nebula to create a token deployer -sidebarTitle: "ERC-20 Token Deployer with Nebula" ---- - - -import {YouTube} from '/snippets/YouTube.jsx'; - -# What is thirdweb AI? - -Thirdweb AI, part of the developer suite build by [thirdweb](https://portal.thirdweb.com/), is a natural language model with improved blockchain reasoning, autonomous transaction capabilities, and real-time access to the blockchain. [Learn more about Nebula](https://blog.thirdweb.com/introducing-nebula-a-powerful-blockchain-model-to-read-write-and-reason-onchain/). - -Watch this workshop to learn more about Nebula and how to create a Telegram bot for app developers to access daily and weekly stats of the dApp. - - - -## Get started building - -Follow this [guide](https://github.com/thirdweb-example/erc20-token-deployer) to test out Nebula and build your own token deployer. diff --git a/build-on-celo/build-with-ai/examples/build-with-thirdweb-ai.mdx b/build-on-celo/build-with-ai/examples/build-with-thirdweb-ai.mdx new file mode 100644 index 0000000000..1a0d5cddf9 --- /dev/null +++ b/build-on-celo/build-with-ai/examples/build-with-thirdweb-ai.mdx @@ -0,0 +1,86 @@ +# What is thirdweb AI? + + + **Migration Notice**: Nebula has been rebranded to **thirdweb AI**. The Nebula + app and API were deprecated on September 30, 2025. All functionality is now + available through the thirdweb AI dashboard and API. Please migrate to the new + endpoints and update your integrations. + + +Thirdweb AI (formerly Nebula) is a natural language model with improved blockchain reasoning, autonomous transaction capabilities, and real-time access to the blockchain. It provides a standard OpenAI-compatible chat completion API optimized for blockchain interactions. + +**Key Features:** + +- Query real-time data from the blockchain +- Analyze transactions +- Fetch token balances, prices and metadata +- Execute or prepare any contract call or transaction +- Execute or prepare swaps from/to any token pair +- Deploy contracts +- Generate images +- Search the web + +Watch this workshop to learn more about thirdweb AI and how to create a Telegram bot for app developers to access daily and weekly stats of the dApp. + + + +## Get started building + +### API Endpoint + +The thirdweb AI API endpoint is: + +``` +https://api.thirdweb.com/ai/chat +``` + +### Authentication + +Use your project's `secret_key` from the thirdweb dashboard for authenticated API calls: + +```javascript +fetch("https://api.thirdweb.com/ai/chat", { + method: "POST", + headers: { + "x-secret-key": "", + }, + body: { + messages: [ + { + role: "user", + content: "Send 0.01 ETH to vitalik.eth", + }, + ], + context: { + // Note: Chain IDs for thirdweb differ from standard chain IDs. + // Find the correct chain IDs in the thirdweb dashboard or documentation. + // https://thirdweb.com/chainlist/mainnets + chain_ids: [8453], + from: "0x1234567890123456789012345678901234567890", + }, + stream: false, + }, +}); +``` + +### Example Projects + +- Follow this [guide](https://github.com/thirdweb-example/erc20-token-deployer) to test out thirdweb AI and build your own token deployer +- Check out the [thirdweb AI mini-app example](https://github.com/thirdweb-example/thirdweb-ai-mini-app) + +### Documentation + +- [thirdweb AI Documentation](https://portal.thirdweb.com/ai/chat) +- [API Reference](https://portal.thirdweb.com/reference#tag/ai/post/ai/chat) +- [Migration Guide](https://blog.thirdweb.com/changelog/nebula-is-now-thirdweb-ai/) + +## Support + +Join the [Celo Discord server](https://discord.com/invite/celo). Reach out in the #build-with-celo channel with your questions and feedback. diff --git a/build-on-celo/build-with-ai/examples/building_with_goat.mdx b/build-on-celo/build-with-ai/examples/building_with_goat.mdx index ddd08b6c02..aac0cc66a5 100644 --- a/build-on-celo/build-with-ai/examples/building_with_goat.mdx +++ b/build-on-celo/build-with-ai/examples/building_with_goat.mdx @@ -11,9 +11,9 @@ This tutorial guides you through creating a Node.js application using TypeScript Before you begin, ensure you have the following: -- **Node.js (v16 or higher) and npm (or yarn) installed.** You can download Node.js from [https://nodejs.org/](https://nodejs.org/). +- **Node.js (v18 or higher) and npm (or yarn) installed.** You can download Node.js from [https://nodejs.org/](https://nodejs.org/). - **A Celo wallet with a private key.** You'll need a wallet with some CELO and cUSD for testing. _Never commit your private key to version control._ -- **An RPC provider URL for the Celo network.** We'll use [Forno](https://forno.celo.org/) in this example, which is a public provider. For production, consider using a dedicated RPC provider like [Ankr](https://www.ankr.com/), [QuickNode](https://www.quicknode.com/), or others. +- **An RPC provider URL for the Celo network.** For testing, use the Celo Sepolia testnet RPC: `https://forno.celo-sepolia.celo-testnet.org/`. For production, consider using a dedicated RPC provider like [Ankr](https://www.ankr.com/), [QuickNode](https://www.quicknode.com/), or others. - **An OpenAI API key.** GOAT utilizes OpenAI's language models. Obtain an API key from [https://platform.openai.com/](https://platform.openai.com/). - **A code editor or IDE.** VS Code, Sublime Text, or any other code editor will work. @@ -166,7 +166,7 @@ dotenv.config(); // --- Wallet Setup --- const account = privateKeyToAccount( - process.env.WALLET_PRIVATE_KEY as `0x${string}`, + process.env.WALLET_PRIVATE_KEY as `0x${string}` ); const walletClient = createWalletClient({ @@ -223,7 +223,8 @@ Create a `.env` file in the root of your project and add the following, replacin ```bash WALLET_PRIVATE_KEY=your_wallet_private_key -RPC_PROVIDER_URL=https://forno.celo.org # Or your preferred provider +RPC_PROVIDER_URL=https://forno.celo-sepolia.celo-testnet.org/ # Celo Sepolia Testnet (recommended for testing) +# For mainnet: https://forno.celo.org OPENAI_API_KEY=your_openai_api_key ``` @@ -231,10 +232,24 @@ Important Security Note: Never commit your `.env` file or your private key to ve ## Running the Application -Compile the TypeScript code: +Compile and run the TypeScript code: ```bash -pnpm dev +# Compile TypeScript +npx tsc + +# Run the compiled JavaScript +node dist/index.js +``` + +Or use a TypeScript runner: + +```bash +# Using ts-node +npx ts-node src/index.ts + +# Or using tsx +npx tsx src/index.ts ``` The application will start, and you'll see the prompt: `Enter your prompt (or "exit" to quit):`. You can now enter natural language commands. diff --git a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx index e0e4c26034..22819b9e26 100644 --- a/build-on-celo/build-with-ai/mcp/celo-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/celo-mcp.mdx @@ -49,6 +49,26 @@ export CELO_TESTNET_RPC_URL="https://forno.celo-sepolia.celo-testnet.org/" # Ce ## MCP Client Integration +MCP is supported by a wide range of IDEs and development tools. Below are setup instructions for popular options: + +### VS Code Setup + +VS Code has native MCP support. Add the following configuration to your MCP settings: + +**macOS/Linux**: `~/.vscode/mcp.json` or via VS Code settings +**Windows**: `%APPDATA%\Code\User\mcp.json` + +```json +{ + "mcpServers": { + "celo-mcp": { + "command": "uvx", + "args": ["--refresh", "celo-mcp"] + } + } +} +``` + ### Cursor IDE Setup Add the following configuration to your MCP settings file (`~/.cursor/mcp.json`): @@ -66,6 +86,14 @@ Add the following configuration to your MCP settings file (`~/.cursor/mcp.json`) The `--refresh` flag ensures the latest code is always loaded when the MCP server starts. +### JetBrains IDEs Setup + +For IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs, configure MCP through the IDE settings or via the JetBrains MCP Server plugin. + +### Windsurf Setup + +Windsurf has built-in MCP support. Configure MCP servers through the Windsurf settings interface. + ### Claude Desktop Setup For Claude Desktop, add this configuration to your MCP settings file: diff --git a/build-on-celo/build-with-ai/mcp/composer-mcp.mdx b/build-on-celo/build-with-ai/mcp/composer-mcp.mdx index 3458191ef1..d47423c845 100644 --- a/build-on-celo/build-with-ai/mcp/composer-mcp.mdx +++ b/build-on-celo/build-with-ai/mcp/composer-mcp.mdx @@ -1,15 +1,15 @@ ---- -title: Composer Kit MCP Server ---- - -import {YouTube} from '/snippets/YouTube.jsx'; - The **Composer Kit MCP Server** is a Model Context Protocol (MCP) server that provides comprehensive access to Composer Kit UI components documentation, examples, and usage information. This powerful tool enables AI assistants and development environments to access the complete Composer Kit React component library designed for building web3 applications on the Celo blockchain. > Watch [this step-by-step vibe coding tutorial](https://www.youtube.com/watch?v=QOCO1G8cJyI) using the Celo Composer Kit MCP to create a token claim dApp in minutes! -> - + ## Key Features @@ -74,6 +74,37 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie ## MCP Client Integration +MCP is supported by a wide range of IDEs and development tools. Below are setup instructions for popular options: + +### VS Code Setup + +VS Code has native MCP support: + +1. **Install the MCP server**: + + ```bash + pip install composer-kit-mcp + ``` + +2. **Configure VS Code** by adding the MCP server to your settings: + + - Open VS Code Settings (Cmd/Ctrl + ,) + - Search for "MCP" or navigate to MCP settings + - Add configuration: + + ```json + { + "mcpServers": { + "composer-kit-mcp": { + "command": "uvx", + "args": ["composer-kit-mcp"] + } + } + } + ``` + +3. **Restart VS Code** and verify setup + ### Cursor IDE Setup 1. **Install the MCP server** (if not already done): @@ -104,6 +135,22 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie - "Show me how to use the Wallet component" - "Search for payment-related components" +### JetBrains IDEs Setup + +For IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs: + +1. **Install the MCP server**: + + ```bash + pip install composer-kit-mcp + ``` + +2. **Configure through JetBrains MCP plugin** or IDE settings + +### Windsurf Setup + +Windsurf has built-in MCP support. Configure through Windsurf's settings interface. + ### Claude Desktop Setup 1. **Install the MCP server**: diff --git a/build-on-celo/build-with-ai/mcp/index.mdx b/build-on-celo/build-with-ai/mcp/index.mdx index ed2668616d..8ee5ebf6fb 100644 --- a/build-on-celo/build-with-ai/mcp/index.mdx +++ b/build-on-celo/build-with-ai/mcp/index.mdx @@ -1,12 +1,9 @@ --- title: Model Context Protocol (MCP) -og:description: Learn how to get started with MCP servers and implement the Model Context Protocol -sidebarTitle: "Intro to MCP Servers" +og:description: Learn about the Model Context Protocol and how to use Celo-specific MCP servers for building AI agents --- -import {YouTube} from '/snippets/YouTube.jsx'; - -[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It was developed by Anthropic, the AI company behind Claude, to solve the challenge of consistently and efficiently connecting AI models with various data sources and tools. This makes Claude natively compatible with all MPC servers. OpenAI has announced compatibility with the MCP standard, ensuring broad adoption across major AI platforms. +[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It was developed by Anthropic, the AI company behind Claude, to solve the challenge of consistently and efficiently connecting AI models with various data sources and tools. MCP has become the industry standard for integrating AI tools and IDEs, with widespread adoption across major development environments including VS Code, Cursor, JetBrains IDEs, Windsurf, Zed, and many others. OpenAI has also adopted MCP across their Agents SDK and ChatGPT desktop app, ensuring broad compatibility across major AI platforms. ## Celo specific MCPs: @@ -18,7 +15,14 @@ import {YouTube} from '/snippets/YouTube.jsx'; - components - set up your project on Celo in minutes - + ## Why MCP? @@ -34,7 +38,7 @@ MCP follows a client-server architecture where a host application can connect to ### Components -- **MCP Hosts**: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP +- **MCP Hosts**: Programs like Claude Desktop, IDEs (VS Code, Cursor, JetBrains, Windsurf, Zed, and more), or AI tools that want to access data through MCP - **MCP Clients**: Protocol clients that maintain 1:1 connections with servers - **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol - **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access @@ -51,5 +55,3 @@ Explore existing MCP server implementations: - [Official MCP Documentation](https://modelcontextprotocol.io/introduction) - [MCP Community Forum](https://community.modelcontextprotocol.io) - - diff --git a/build-on-celo/build-with-ai/multi-agent-systems.mdx b/build-on-celo/build-with-ai/multi-agent-systems.mdx index c589ea02e0..e57eec756a 100644 --- a/build-on-celo/build-with-ai/multi-agent-systems.mdx +++ b/build-on-celo/build-with-ai/multi-agent-systems.mdx @@ -2,14 +2,19 @@ title: Multi-Agent Systems og:description: A production-grade multi-agent system built with LangGraph and LangChain, featuring a web search agent and a Celo blockchain agent powered by Google's Gemini. --- -import {YouTube} from '/snippets/YouTube.jsx'; - # Multi-Agent Systems Learn how to build a [production-grade multi-agent system](https://github.com/celo-org/example-multi-agent-system) built with LangGraph and LangChain, featuring a web search agent and a Celo blockchain agent powered by Google's Gemini. - + ## Features @@ -32,23 +37,20 @@ Multiagent systems (MAS) are groups of independent software agents that work tog In Web3, this is especially powerful. Agents can perform tasks like: -* Optimizing DeFi yields -* Voting in governance protocols -* Bridging assets across blockchains -* Managing liquidity in real-time +- Optimizing DeFi yields +- Voting in governance protocols +- Bridging assets across blockchains +- Managing liquidity in real-time Because these agents are **autonomous** and can operate in **parallel**, the system becomes more scalable and resilient. If one agent fails, others can keep running. That means fewer single points of failureβ€”an important trait in decentralized systems. Multiagent architectures help developers build apps that respond to changing network conditions, user demands, or even market dynamics without needing centralized control. This makes them a great match for Celo’s L2 ecosystem and the broader Web3 world. - ## Architecture The system uses a hierarchical multi-agent architecture with a supervisor agent orchestrating specialized agents. - -![AI](/img/developer/multi-agents.png) - +![AI](/img/developer/multi-agents.png) ## Setup @@ -110,4 +112,4 @@ multi-agent-system/ ## License -MIT \ No newline at end of file +MIT diff --git a/build-on-celo/build-with-ai/resources.mdx b/build-on-celo/build-with-ai/resources.mdx index 178b3a3e89..1f5f146cf0 100644 --- a/build-on-celo/build-with-ai/resources.mdx +++ b/build-on-celo/build-with-ai/resources.mdx @@ -4,7 +4,6 @@ og:description: Resources for learning how to craft intelligent, blockchain-powe sidebarTitle: "Resources" --- - Resources for learning how to craft intelligent, blockchain-powered agents on Celo. --- @@ -13,27 +12,35 @@ Resources for learning how to craft intelligent, blockchain-powered agents on Ce ### πŸ“ Tutorials -- [Machine Learning](https://www.coursera.org/specializations/machine-learning-introduction?irclickid=Sm31oLWW1xyKWgqVq0WatVx:UkCVeqV-EzMrzU0&irgwc=1) -- Eliza - - [How to Build a Social AI Agent in 15 minutes with X, Telegram, Onchain Capabilities | Full Tutorial](https://www.youtube.com/watch?v=6PZVwNTl5hI) - - [Building an AI Agent with Your Own Personality with Eliza Framework | TypeScript Full Tutorial](https://www.youtube.com/watch?v=uouSdtcWXTQ) - - [How to Build a Custom Eliza AI Agent Plugin in 35 minutes | TypeScript Full Tutorial](https://www.youtube.com/watch?v=25FxjscBHuo) - - [Eliza - AI Agent Dev School](https://www.youtube.com/playlist?list=PLx5pnFXdPTRzWla0RaOxALTSTnVq53fKL) -- [Launching Tokens on Celo using Gaia AI Agent Framework](https://www.youtube.com/watch?v=-7Bcgpj79LM) -- [Unlocking Web3 LLMs: Explore thirdweb AI on Celo](https://www.youtube.com/watch?v=FeubfHwfJcM) +- [Machine Learning](https://www.coursera.org/specializations/machine-learning-introduction) +- **Eliza Framework** + - [How to Build a Social AI Agent in 15 minutes with X, Telegram, Onchain Capabilities | Full Tutorial](https://www.youtube.com/watch?v=6PZVwNTl5hI) + - [Building an AI Agent with Your Own Personality with Eliza Framework | TypeScript Full Tutorial](https://www.youtube.com/watch?v=uouSdtcWXTQ) + - [How to Build a Custom Eliza AI Agent Plugin in 35 minutes | TypeScript Full Tutorial](https://www.youtube.com/watch?v=25FxjscBHuo) + - [Eliza - AI Agent Dev School](https://www.youtube.com/playlist?list=PLx5pnFXdPTRzWla0RaOxALTSTnVq53fKL) +- **GOAT SDK** + - [Build AI-Powered Token Swap Agent on Celo](/build-on-celo/build-with-ai/build-with-goat/token-swap-agent) + - [Build AI-Powered NFT Minting Agent on Celo](/build-on-celo/build-with-ai/build-with-goat/mint-nft-agent) + - [Build AI Agent to Send Tokens on Celo](/build-on-celo/build-with-ai/build-with-goat/send-token-agent) +- **Gaia Framework** + - [Launching Tokens on Celo using Gaia AI Agent Framework](https://www.youtube.com/watch?v=-7Bcgpj79LM) +- **thirdweb AI (formerly Nebula)** + - [Unlocking Web3 LLMs: Explore thirdweb AI on Celo](https://www.youtube.com/watch?v=FeubfHwfJcM) ### πŸŽ“ Courses - [Web3 AI Agents Guide](https://www.aiagenttoolkit.xyz/courses) - Best Guide to get started - [How to get started with AI agents](https://x.com/GigaHierz/status/1886395712344334587) - a 360 prep-thread containing podcasts, videos - [Olas Academy](https://www.youtube.com/playlist?list=PLXztsZv11CTfXiQK9OJhMwBkfgf4ETZkl) +- [CrewAI Documentation](https://docs.crewai.com/) - Comprehensive guide to building multi-agent systems +- [Vercel AI SDK Documentation](https://ai-sdk.dev/) - TypeScript-first toolkit for AI applications ### πŸ€– Famous Agents - Luna - Virtuals - - first agent to pay another agent for doing work + - first agent to pay another agent for doing work - [aixbt](https://x.com/aixbt_agent) - trading agent - - holds one of the biggest mindshare on crypto Twitter + - holds one of the biggest mindshare on crypto Twitter - [H4CK Terminal](https://x.com/h4ck_terminal)Β - first ever white-hat AI agent hunting vulnerabilities, securing funds & redistributing bounties - [Polytrader](https://x.com/polytraderAI) - [artto](https://x.com/artto_ai): Agent that collects NFTs @@ -42,55 +49,53 @@ Resources for learning how to craft intelligent, blockchain-powered agents on Ce - [opencordai](https://x.com/opencordai): A 24/7 AI agent for social media lead generation, identifying customers and engaging with them to drive sales. - [Infinite Regen](https://x.com/0xInfiniteregen): A platform for creating AI agents trained on Web3 insights to design mechanisms for funding public goods. - For a full comprehensive list, checkout the [AI Agent Demo Days](https://x.com/GigaHierz/status/1881401460082274395) hosted by Nader Dabit. ### πŸ’‘ Project Ideas + - [25+ AI Agent Product Ideas](https://x.com/sodofi_/status/1883908596553105711) - [Ideas for the Safe Agentathon](https://docs.google.com/document/d/1HSBfxkb5AWPZo6YDefDVjBrHVl-Nh4DQVElyLhy4y7A/edit?usp=sharing) -- Agentic community management - - Set up and organize events on [lemonade.social](http://lemonade.social) as mentioned in this [podcast](https://open.spotify.com/episode/40XcJxe9RfwtPIOq3KHy7s?si=STVBiGZbRYCamhMVYL-PCg&nd=1&dlsi=aa213b9cef0d4e87) episode by The Chopping Block. +- Agentic community management + - Set up and organize events on [lemonade.social](http://lemonade.social) as mentioned in this [podcast](https://open.spotify.com/episode/40XcJxe9RfwtPIOq3KHy7s?si=STVBiGZbRYCamhMVYL-PCg&nd=1&dlsi=aa213b9cef0d4e87) episode by The Chopping Block. - Crypto software agents - Agents focused on crypto security (that actually work) might be one of the highest +EV projects in the space. 24/7 security, patching ability, monitoring systems, etc. would totally change the narrative on how crypto is perceived. - Agent verifiability - - identity - - data - - models + - identity + - data + - models ### πŸ› οΈ Technical Resources - Starter Kit (including Lit + Gaia): https://github.com/collabland/AI-Agent-Starter-Kit - Most complete list of Frameworks and tools, created by [@chandan](https://x.com/chandan1_) - - [AIAgentToolkit.xyz](http://aiagenttoolkit.xyz/) + - [AIAgentToolkit.xyz](http://aiagenttoolkit.xyz/) - Celo - [Getting Started with AI Agents](/build/build-with-ai/overview) - [Mode Network Hackathon Starter Kit](https://www.notion.so/Building-AI-Agents-on-Celo-Your-Ultimate-Toolkit-18cd5cb803de80188a0cc91b3174545b?pvs=21) - [The AI Model Layer of Crypto](https://cryptopond.xyz/) - [12-Factor Agents - Principles for building reliable LLM applications](https://github.com/humanlayer/12-factor-agents) - ### πŸ“– Articles - [AI Real World Use Cases for ReFi](https://www.daviddao.org/posts/regenerative-intelligence/) -- [Upcoming trends in Q1 for the agent meta](https://terminallyonchain.xyz/q1trends) -- [Allora Powers Virtuals](https://www.allora.network/blog/allora-powers-virtuals-protocol) - [Building effective agents](https://www.anthropic.com/research/building-effective-agents) +- [Microsoft AutoGen: Multi-Agent AI Systems](https://www.microsoft.com/en-us/research/project/autogen/) - Enterprise-grade agent framework +- [OpenAgents: Decentralized AI Agent Networks](https://openagents.org) - Open-source framework for large-scale agent systems ### πŸŽ™οΈ Podcasts - Learn about the history of the first viral AI Agent with a token: The Truth Terminal - - [Bankless: How Crypto Al Agents Will Take Over the World | Ejaaz Ahamadeen](https://open.spotify.com/episode/5jVhVuzb5HNZdZz11b1cc1?si=bZPfHf1PRtmjzVQXrbS2CA&context=spotify%3Aplaylist%3A37i9dQZF1FgnTBfUlzkeKt) + - [Bankless: How Crypto Al Agents Will Take Over the World | Ejaaz Ahamadeen](https://open.spotify.com/episode/5jVhVuzb5HNZdZz11b1cc1?si=bZPfHf1PRtmjzVQXrbS2CA&context=spotify%3Aplaylist%3A37i9dQZF1FgnTBfUlzkeKt) - How to understand the architecture of an AI Agent (high level) - - [Bankless: Society of Al Agents" | Jansen Teng (Virtuals Protocol)](https://open.spotify.com/episode/4kMubklNG3xBMYR0mWijNy?si=Ua1VXf3QToajv21QZcGZgw&context=spotify%3Aplaylist%3A37i9dQZF1FgnTBfUlzkeKt) + - [Bankless: Society of Al Agents" | Jansen Teng (Virtuals Protocol)](https://open.spotify.com/episode/4kMubklNG3xBMYR0mWijNy?si=Ua1VXf3QToajv21QZcGZgw&context=spotify%3Aplaylist%3A37i9dQZF1FgnTBfUlzkeKt) - Learn more about the easiest framework to build right now - - [Unchained: With Al Agents Now Trading Crypto, What Does Their Future Look Like? - Ep. 758](https://open.spotify.com/episode/5UDhqnOziBkcfaQ55ZJ7Bg?si=U9SPC8K9TmKmmfNVkWecEQ) + - [Unchained: With Al Agents Now Trading Crypto, What Does Their Future Look Like? - Ep. 758](https://open.spotify.com/episode/5UDhqnOziBkcfaQ55ZJ7Bg?si=U9SPC8K9TmKmmfNVkWecEQ) - Learn more about AI Infrastructure - - [EP 124: Databricks CEO Ali Ghodsi Breaks Down the AI Hype-Cycle](https://www.notion.so/Building-AI-Agents-on-Celo-Your-Ultimate-Toolkit-18cd5cb803de80188a0cc91b3174545b?pvs=21) + - [EP 124: Databricks CEO Ali Ghodsi Breaks Down the AI Hype-Cycle](https://www.notion.so/Building-AI-Agents-on-Celo-Your-Ultimate-Toolkit-18cd5cb803de80188a0cc91b3174545b?pvs=21) - Predictions for the industry - - [AI + a16z](https://podcasts.apple.com/in/podcast/ai-a16z/id1740178076) - + - [AI + a16z](https://podcasts.apple.com/in/podcast/ai-a16z/id1740178076) ### πŸ† Start Building Now - [Proof of Ship](https://celoplatform.notion.site/Proof-of-Ship-17cd5cb803de8060ba10d22a72b549f8) - a monthly contest where AI Agents track contributions on Celo and distribute rewards to builders. -Have another resource you want to add? Click the ['Edit this page'](https://github.com/celo-org/docs/edit/main/docs/build/build-with-ai/usecases.md) button below to submit a PR. \ No newline at end of file +Have another resource you want to add? Submit a pull request to add it to this page. diff --git a/build-on-celo/build-with-ai/tools.mdx b/build-on-celo/build-with-ai/tools.mdx index 6559e8a117..ae15a85c30 100644 --- a/build-on-celo/build-with-ai/tools.mdx +++ b/build-on-celo/build-with-ai/tools.mdx @@ -6,30 +6,35 @@ sidebarTitle: "Tools & Infra" This article provides an overview of essential tools for building AI agents. Given the rapid advancements in this space, this is not an exhaustive list but rather a snapshot of tools available on Celo. -## AI Agent Frameworks +## AI Agent Frameworks Frameworks define how AI agents interact, collaborate, and execute tasks. For a full list of frameworks, tools, and infrastructure, check out this [comprehensive table](https://www.aiagenttoolkit.xyz/). **On Celo:** -- [**Olas**](https://docs.autonolas.network/open-autonomy/): Framework for autonomous economic agents in decentralized markets. - - [Implement MECH client into your dApp](https://www.youtube.com/watch?v=fuDteQqsf2A) - - [Celo Trader Agent](https://www.youtube.com/watch?v=WSB0H0dDc78&t=1740s) - - can do transfers (for advanced Python developers) -- [**Gaia**](https://www.gaianet.ai/): Building intelligent ecosystems for evolving AI applications - - Meme Token Generator - an AI Agent that autonomously deploys tokens on Celo. - - [Twitter Thread](https://github.com/harishkotra/celo-token-agent) - short intro - - [Video Tutorial](https://www.youtube.com/watch?v=-7Bcgpj79LM) - - [Example Repository](https://github.com/harishkotra/celo-token-agent/) - - [EternalAI](https://eternalai.org/): A Decentralized Autonomous Agent protocol running AI agents on Solidity smart contracts β€” exactly as programmed β€” without censorship, interference, or downtime. - - [GT Protocol](https://www.gt-protocol.io/): AI Agents Builder, powered by GT Protocol AI Executive Technology, delivers customized AI agents tailored to enhance both business operations and personal daily tasks. - - [**ElizaOS**](https://elizaos.github.io/eliza/): TypeScript-based framework with multi-agent simulation capabilities. +- [**Olas**](https://docs.autonolas.network/open-autonomy/): Framework for autonomous economic agents in decentralized markets. + - [Implement MECH client into your dApp](https://www.youtube.com/watch?v=fuDteQqsf2A) + - [Celo Trader Agent](https://www.youtube.com/watch?v=WSB0H0dDc78&t=1740s) + - can do transfers (for advanced Python developers) +- [**Gaia**](https://www.gaianet.ai/): Building intelligent ecosystems for evolving AI applications + - Meme Token Generator - an AI Agent that autonomously deploys tokens on Celo. + - [Twitter Thread](https://github.com/harishkotra/celo-token-agent) - short intro + - [Video Tutorial](https://www.youtube.com/watch?v=-7Bcgpj79LM) + - [Example Repository](https://github.com/harishkotra/celo-token-agent/) +- [EternalAI](https://eternalai.org/): A Decentralized Autonomous Agent protocol running AI agents on Solidity smart contracts β€” exactly as programmed β€” without censorship, interference, or downtime. +- [GT Protocol](https://www.gt-protocol.io/): AI Agents Builder, powered by GT Protocol AI Executive Technology, delivers customized AI agents tailored to enhance both business operations and personal daily tasks. +- [**ElizaOS**](https://elizaos.github.io/eliza/): TypeScript-based framework with multi-agent simulation capabilities. **Other:** + - [**LangChain**](https://www.langchain.com/): Framework for LLM-powered applications. - [**MetaGPT**](https://github.com/geekan/MetaGPT): Multi-agent meta programming framework, mimicks organizational roles at a software company. +- [**OpenAgents**](https://openagents.org): Open-source framework for building large-scale networks of AI agents. Focus on interoperability, decentralized collaboration, and payment flows. Best for scalable cross-domain agent systems, fintech, and collaborative tasks. +- [**CrewAI**](https://www.crewai.com): Python framework for orchestrating multiple AI agents as teams. Features role-based architecture, memory management, and workflow automation. Best for business process automation, research, and content analysis. +- [**Microsoft AutoGen**](https://www.microsoft.com/en-us/research/project/autogen/): Multi-agent AI systems with autonomous and human-in-the-loop collaboration. Features asynchronous messaging, MCP protocol support, and observability. Best for enterprise automation, software development, and data analysis. +- [**Vercel AI SDK (ai-sdk)**](https://ai-sdk.dev/): TypeScript-first toolkit for AI-powered applications. Provides unified interface for multiple LLM providers and agent abstraction. Best for web applications, Next.js/React apps, and production-ready AI integration. -## Launchpads +## Launchpads No-code platforms simplify AI agent deployment, making it easier to integrate social agents with tokens. @@ -38,9 +43,10 @@ No-code platforms simplify AI agent deployment, making it easier to integrate so ## Essential Tools -A variety of tools are available for building autonomous agents, including blockchain integration, machine learning, memory systems, simulation, monitoring, and security. +A variety of tools are available for building autonomous agents, including blockchain integration, machine learning, memory systems, simulation, monitoring, and security. For a quick start, focus on: + - Blockchain tools for onchain operations. - Memory systems for learning and adapting. - LLMs optimized for Web3 data. @@ -52,61 +58,57 @@ When scaling, consider: - Support for videos, PDFs, and research papers. - Effective use of LLMs, NLP, and RAG tools. -## Intelligence Tools +## Intelligence Tools **Machine Learning Tools:** + - **Purpose**: Training, deploying, debugging and managing ML models - **Examples**: LiteLLM, ModelZoo, TensorServe, GPT-Explorer - **Use Cases**: Pattern recognition, classification, prediction **Natural Language Processing Tools:** + - **Purpose**: Language understanding and processing - **Examples**: NeuralSpace, LangFlow - **Use Cases**: Text analysis, grammar checking, entity recognition **Retrieval Augmented Generation Tools:** + - **Purpose**: Combining LLMs with knowledge bases - **Examples**: Autonomous RAG, Agentic RAG, Local RAG Agent - **Use Cases**: Enhanced chatbots, documentation search, context-aware responses -## Infrastructure +## Infrastructure **Blockchain Tools:** + - **[GOAT](https://ohmygoat.dev/introduction)**: GOAT 🐐 (Great Onchain Agent Toolkit) is an open-source framework for adding blockchain capabilities like wallets and smart contracts to AI agents. -- **[thirdweb AI](https://portal.thirdweb.com/ai/chat?utm_source=celo&utm_medium=documentation&utm_campaign=chain_docs)**: Web3 LLM by thirdweb +- **[thirdweb AI](https://portal.thirdweb.com/ai/chat?utm_source=celo&utm_medium=documentation&utm_campaign=chain_docs)**: Web3 LLM by thirdweb (formerly Nebula). Natural language model optimized for blockchain interactions with autonomous transaction capabilities. - [Tutorial](https://www.youtube.com/watch?v=FeubfHwfJcM) - - [Example Respository](https://github.com/cromewar/nebula-telegram-demo) -- **[Kaito](https://www.kaito.ai/)**: Unified crypto news data. -- **[GOAT](https://ohmygoat.dev/introduction)**: GOAT 🐐 (Great Onchain Agent Toolkit) is an open-source framework for adding blockchain capabilities like wallets and smart contracts to AI agents. + - [Example Repository](https://github.com/thirdweb-example/thirdweb-ai-mini-app) + - [Documentation](https://portal.thirdweb.com/ai/chat) - **[ChainGPT](https://www.chaingpt.org/)**: Is an advanced AI infrastructure that develops AI-powered technologies for the Web3, Blockchain, and Crypto space, developing solutions from Chatbots, NFT, Smart Contract Generators and AI Trading Assistants - [EigenLayer](https://www.eigenlayer.xyz/): Autonomous Verifiable Service (AVS) on EigenLayer is a decentralized service built on Ethereum that provides custom verification mechanisms of off-chain operations. -- **[thirdweb AI](https://portal.thirdweb.com/ai/chat?utm_source=celo&utm_medium=documentation&utm_campaign=chain_docs)**: Web3 LLM by thirdweb - - [Tutorial](https://www.youtube.com/watch?v=1UcwKMt-izc&t=23s) - - [Example Respository](https://github.com/thirdweb-example/thirdweb-ai-mini-app) - [Safe](https://safe.global/safenet): Smart Accounts for Agents - **[Kaito](https://www.kaito.ai/)**: Unified crypto news data. **Memory Systems:** -- **[Mem0](https://github.com/mem0ai/mem0)**: Intelligent memory layer for AI assistants. -- **[Eliza Agent Memory](https://github.com/elizaOS/agentmemory)**: Knowledge graphing and document search. + - **[Mem0](https://github.com/mem0ai/mem0)**: Intelligent memory layer for AI assistants. - **[Eliza Agent Memory](https://github.com/elizaOS/agentmemory)**: Knowledge graphing and document search. - **Security and Policy:** + - **[Predicate](https://x.com/0xPredicate)**: Define rules for onchain interactions - **[Functor Network](https://www.functor.sh/)**: Policy framework for autonomous agents - **Access Controls**: Environmental permissions - **[Langfuse](https://langfuse.com/) - Prompt Verification**: Traces, evals, prompt management and metrics to debug and improve your LLM application. - **[LiteLLM](https://www.litellm.ai/#features) - LLM Access**: Manage LLM access for your developer - - **Data:** When working with AI agents, it's essential to train models and collect the right data. For unique character creation, ensure you have sufficient training data. Some useful tools include: + - **[DataSphere](https://github.com/datasphere/datasphere)**: Visualizes large datasets for analysis. - **[JinAI's LLM-friendly Markdown Tool](https://github.com/jina-ai/serve)**: Converts websites into LLM-friendly markdown. - **[Masa](https://www.masa.ai/)**: The #1 real-time data network for AI Agents & Apps - **[Vana](https://www.vana.org/)**: The first open protocol for data sovereignty. User-owned AI through user-owned data. Growing the DataDAO ecosystem. -- **[DataSphere](https://github.com/datasphere/datasphere)**: Visualizes large datasets for analysis. -- **[JinAI's LLM-friendly Markdown Tool](https://github.com/jina-ai/serve)**: Converts websites into LLM-friendly markdown. \ No newline at end of file diff --git a/build-on-celo/build-with-ai/vibe-coding.mdx b/build-on-celo/build-with-ai/vibe-coding.mdx index 589da7e9d1..e4fcf98919 100644 --- a/build-on-celo/build-with-ai/vibe-coding.mdx +++ b/build-on-celo/build-with-ai/vibe-coding.mdx @@ -2,7 +2,6 @@ title: Vibe Coding og:description: Learn how to set up your environment for Vibe Coding and discover tools that enhance your development workflow --- -import {YouTube} from '/snippets/YouTube.jsx'; # Vibe Coding Tools @@ -10,10 +9,19 @@ Vibe Coding refers to an approach to software development where you use chat age Watch a quick intro to Vibe Coding with the Celo MCP Servers. You can find out more about them in the [MCP section](/build/build-with-ai/mcp/index). - + -Make sure you watch some tutorials and check out some X threads to understand other people's setup. Being successful with Vibe Coding relies on your preparation and setup. + Make sure you watch some tutorials and check out some X threads to understand + other people's setup. Being successful with Vibe Coding relies on your + preparation and setup. ## Full Stack Development Tools diff --git a/build-on-celo/build-with-defi.mdx b/build-on-celo/build-with-defi.mdx index d03b156d1d..9327f3550a 100644 --- a/build-on-celo/build-with-defi.mdx +++ b/build-on-celo/build-with-defi.mdx @@ -5,7 +5,7 @@ og:description: A beginner's guide to building DeFi applications on Celo In this guide you can explore tooling and infrastructure for building DeFi on Celo. -## Overview +## Overview DeFi on Celo is designed for builders who want to create accessible, stable, and inclusive financial systems. This guide walks you through the key tools and infrastructure available for developing decentralized finance applications on Celo. @@ -13,55 +13,68 @@ Stablecoins are at the heart of DeFi, they provide price stability, reduce volat Explore below how to integrate stablecoins, exchanges, and oracles into your next DeFi project. -## Why Stablecoins Matter +## Why Stablecoins Matter -[Stablecoins](build-with-local-stablecoin) are digital assets pegged to a stable reserve, such as fiat currency or a basket of assets. They provide key benefits in DeFi and financial transactions and financial inclusion: +[Stablecoins](/build-on-celo/build-with-local-stablecoin) are digital assets pegged to a stable reserve, such as fiat currency or a basket of assets. They provide key benefits in DeFi and financial transactions and financial inclusion: -Check out ["Build with Stablecoins"](build-with-local-stablecoin) for an extensive list of all stablecoins on Celo. + Check out ["Build with + Stablecoins"](/build-on-celo/build-with-local-stablecoin) for an extensive + list of all stablecoins on Celo. -- **Price Stability** – Unlike volatile cryptocurrencies, stablecoins maintain a predictable value. -- **Low-Cost Transactions** – Sending stablecoins on Celo costs significantly less than on traditional blockchains. -- **Borderless Access** – Users can send and receive stablecoins globally, without needing a bank account. -- **Programmability** – Stablecoins can be used in smart contracts to enable lending, savings, and remittances. -- **Financial Inclusion** – Stablecoins empower unbanked and underbanked populations with access to digital financial services. +- **Price Stability** – Unlike volatile cryptocurrencies, stablecoins maintain a predictable value. +- **Low-Cost Transactions** – Sending stablecoins on Celo costs significantly less than on traditional blockchains. +- **Borderless Access** – Users can send and receive stablecoins globally, without needing a bank account. +- **Programmability** – Stablecoins can be used in smart contracts to enable lending, savings, and remittances. +- **Financial Inclusion** – Stablecoins empower unbanked and underbanked populations with access to digital financial services. Celo is uniquely positioned to advance the adoption of stable digital assets through the [Mento](https://www.mento.org/) Protocolβ€”a decentralized stablecoin platform built on Celo. [Mento](https://www.mento.org/) enables the creation of local stablecoins that are algorithmically stabilized and backed by crypto collateral. This approach helps users access a price-stable digital currency that is aligned with their local economy. The goal of Mento is simple: to provide a stable asset for every country in the world. These stable assets can be used for everyday payments, savings, remittances, and commerceβ€”empowering individuals in regions with high inflation or limited access to traditional banking infrastructure. -## Examples of DeFi Applications on Celo +## Examples of DeFi Applications on Celo -Celo supports a vibrant ecosystem of DeFi protocols that utilize stablecoins: +Celo supports a vibrant ecosystem of DeFi protocols that utilize stablecoins: -### Lending & Borrowing +### Lending & Borrowing -- **[Aave](https://aave.com/)** – Decentralized lending and borrowing using stablecoins. -- **[PWN](https://pwn.xyz/)** - Fixed rate lending +- **[Aave](https://aave.com/)** – Decentralized lending and borrowing platform officially launched on Celo in 2025, expanding lending options with institutional and retail liquidity support. +- **[Credit Collective](https://creditcollective.xyz/)** – On-chain private credit protocol supporting real-world assets (RWAs) and emerging market stablecoins. Manages liquidity strategies and provides sustainable market-making for new stablecoins. +- **[PWN](https://pwn.xyz/)** – Fixed rate lending platform. ### Exchanges -Find all Exchanges [here](/about-celo/exchanges). For cross-chain exchanges check out the [bridges](/developer/bridges) and [cross-chain messaging](/developer/bridges/cross-chain-messaging) pages. +Find all Exchanges [here](/home/exchanges). For cross-chain exchanges check out the [bridges](/tooling/bridges) and [cross-chain messaging](/tooling/bridges/cross-chain-messaging) pages. -- **[Velodrome](https://velodrome.finance/)** – Velodrome is a decentralized exchange where you can execute low-fee swaps, deposit tokens to earn rewards, and actively participate in the onchain economy. -- **[Uniswap](https://app.uniswap.org/)** – Swaps and liquidity pools for stablecoins. -- **[Ubeswap](https://ubeswap.org/)** – A Celo-native DEX optimized for mobile users. -- **[Carbon DeFi by Bancor](https://www.carbondefi.xyz/)** – Empowering users with onchain automation and superior orderbook-like features. -- +- **[Uniswap v4](https://app.uniswap.org/)** – Launched on Celo in early 2025, bringing advanced "Hooks" features for developer customizations, low-cost swaps, and sub-cent transaction fees. Enables seamless integration with Ethereum liquidity. +- **[Velodrome](https://velodrome.finance/)** – Decentralized exchange where you can execute low-fee swaps, deposit tokens to earn rewards, and actively participate in the onchain economy. Offers high liquidity mining yields. +- **[Carbon DeFi by Bancor](https://www.carbondefi.xyz/)** – Empowering users with onchain automation and superior orderbook-like features. One of the largest DEXs on Celo, processing over $33.5M in trading volume within its first year. +- **[Ubeswap](https://ubeswap.org/)** – A Celo-native DEX optimized for mobile users, supporting hundreds of trading pairs. -### Liquidity Incentives +### DEX Aggregators -- **[Steer Protocol](https://steer.finance/)** – Automated liquidity strategies. +- **[LI.FI](https://li.fi/)** – Cross-chain DEX aggregator and bridge, facilitating optimal trading routes with a focus on speed and user-friendly access. +- **[Matcha](https://matcha.xyz/)** – Cross-chain DEX aggregator allowing users to find optimal trading routes and limit orders for a wide variety of tokens. + +### Liquidity Incentives + +- **[Steer Protocol](https://steer.finance/)** – Automated liquidity strategies. - **[Merkl](https://app.merkl.xyz/)** – Rewarding liquidity providers with stablecoin incentives. - **[Ichi](https://www.ichi.org/)** – Automated Liquidity Strategies for DeFi Yield. +### Derivatives + +- **[Lynx](https://lynx.finance/)** – Decentralized perpetual contract trading platform, adding leveraged trading and robust liquidity to Celo's DeFi toolkit. + ### Oracles -Oracles are a crucial part to get real time price information on tokens. Speed is crucial when it comes to building DeFi applications, and you should not rely on web2 APIs for price feeds. Find all Oracles in the [tooling section](/developer/oracles). +Oracles are a crucial part to get real time price information on tokens. Speed is crucial when it comes to building DeFi applications, and you should not rely on web2 APIs for price feeds. Find all Oracles in the [tooling section](/tooling/oracles). -- [RedStone Oracles](/developer/oracles/redstone) -- [Chainlink, Price Feed Oracles](https://docs.chain.link/data-feeds/price-feeds/addresses?network=celo) +- [RedStone Oracles](/tooling/oracles/redstone) +- [Chainlink Price Feed Oracles](https://docs.chain.link/data-feeds/price-feeds/addresses?network=celo) +- [Supra Oracles](/tooling/oracles/supra) +- [Band Protocol](/tooling/oracles/band-protocol) ### Human-Centered Security Tools @@ -70,8 +83,8 @@ Oracles are a crucial part to get real time price information on tokens. Speed i - Pre‑sign safety simulations in any Celo wallet - Real‑time CELO /β€―cUSDβ€―/β€―stCELO pricing -## Get Started +## Get Started -Developers and entrepreneurs can leverage Celo's infrastructure to build next-generation stablecoin applications. +Developers and entrepreneurs can leverage Celo's infrastructure to build next-generation stablecoin applications. -By building on Celo, you're not just creating DeFi applications, you're enabling real-world financial inclusion and empowering users globally. \ No newline at end of file +By building on Celo, you're not just creating DeFi applications, you're enabling real-world financial inclusion and empowering users globally. diff --git a/build-on-celo/build-with-farcaster.mdx b/build-on-celo/build-with-farcaster.mdx index 8427dbace2..f790345611 100644 --- a/build-on-celo/build-with-farcaster.mdx +++ b/build-on-celo/build-with-farcaster.mdx @@ -1,33 +1,404 @@ --- -title: Build a Farcaster MiniApp -og:description: A guide on to build a Farcaster MiniApp +title: Build with Farcaster +og:description: Learn how to build Farcaster MiniApps on Celo with seamless wallet integration and user experience --- -import {YouTube} from '/snippets/YouTube.jsx'; +## Build a Farcaster MiniApp -### Build a Farcaster MiniApp +Building a MiniApp comes with many benefits. You don't need to manage on- and off‑ramp integrations, and the user experience is more seamless because your app runs inside a wallet client. For testing and scaling, we recommend keeping a standard wallet connection in your app; it should be hidden automatically when the app runs in a MiniApp environment. Our templates already include this setup, so we suggest creating your MiniApp using our starterkit, [Celo Composer](https://github.com/celo-org/celo-composer). Setting up a Farcaster MiniApp involves several specific settings, and our template provides a step‑by‑step guide to walk you through them. -Building a MiniApp comes with many benefits. You don’t need to manage on- and off‑ramp integrations, and the user experience is more seamless because your app runs inside a wallet client. For testing and scaling, we recommend keeping a standard wallet connection in your app; it should be hidden automatically when the app runs in a MiniApp environment. Our templates already include this setup, so we suggest creating your MiniApp using our starterkit, [Celo Composer](https://github.com/celo-org/celo-composer). Setting up a Farcaster MiniApp involves several specific settings, and our template provides a step‑by‑step guide to walk you through them. +Before you start building a Farcaster MiniApp, we recommend watching this video on how to build a successful MiniApp on Farcaster. + -Before you start building a Farcaster MiniApp, we recommend watching this video on how to build a successful MiniApp on Farcaster. +Make sure to also read the [Farcaster MiniApp documentation](https://miniapps.farcaster.xyz/). You'll save a lot of time by reviewing it in detail before building. We also recommend testing a few popular Farcaster MiniApps to get a feel for UX patterns. +## Quick Start - +Use this command to scaffold a Farcaster MiniApp quickly using the [Celo Composer](https://github.com/celo-org/celo-composer): +```bash +npx @celo/celo-composer@latest create --template farcaster-miniapp +``` +When using this command, follow this workshop to configure everything correctly and avoid missing important implementations or settings. -Make sure to also read the [Farcaster MiniApp documentation](https://miniapps.farcaster.xyz/). You’ll save a lot of time by reviewing it in detail before building. We also recommend testing a few popular Farcaster MiniApps to get a feel for UX patterns. + +## SDK Installation and Setup -Use this command to scaffold a Farcaster MiniApp quickly using the [Celo Composer](https://github.com/celo-org/celo-composer): +### Install the MiniApp SDK + +Install the Farcaster MiniApp SDK using your preferred package manager: + + +```bash npm +npm install @farcaster/miniapp-sdk +``` + +```bash yarn +yarn add @farcaster/miniapp-sdk +``` + +```bash pnpm +pnpm add @farcaster/miniapp-sdk +``` + + + +### Initialize the SDK + +After your app loads, you **must** call `sdk.actions.ready()` to hide the splash screen and display your content: + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +// After your app is fully loaded and ready to display +await sdk.actions.ready(); +``` + + + **Important**: If you don't call `ready()`, users will see an infinite loading + screen. This is one of the most common issues when building Mini Apps. + + +## Wallet Integration + +### Using Wagmi (Recommended) + +The Mini App SDK exposes an [EIP-1193 Ethereum Provider API](https://eips.ethereum.org/EIPS/eip-1193) at `sdk.wallet.getEthereumProvider()`. We recommend using [Wagmi](https://wagmi.sh) to connect to and interact with the user's wallet. + +#### Install the Wagmi Connector ```bash -npx @celo/celo-composer@latest create --template farcaster-miniapp +npm install @farcaster/miniapp-wagmi-connector wagmi viem ``` -When using this command, follow this workshop to configure everything correctly and avoid missing important implementations or settings. +#### Configure Wagmi + +Add the Mini App connector to your Wagmi config: + +```js +import { http, createConfig } from "wagmi"; +import { celo, celoSepolia } from "wagmi/chains"; +import { farcasterMiniApp as miniAppConnector } from "@farcaster/miniapp-wagmi-connector"; + +export const config = createConfig({ + chains: [celo, celoSepolia], + transports: { + [celo.id]: http(), + [celoSepolia.id]: http(), + }, + connectors: [miniAppConnector()], +}); +``` + +#### Connect to Wallet + +If a user already has a connected wallet, the connector will automatically connect (e.g., `isConnected` will be `true`). Always check for a connection and prompt users to connect if needed: + +```js +import { useAccount, useConnect } from "wagmi"; + +function ConnectMenu() { + const { isConnected, address } = useAccount(); + const { connect, connectors } = useConnect(); + + if (isConnected) { + return ( + <> +
You're connected!
+
Address: {address}
+ + ); + } + + return ( + + ); +} +``` + + + Your Mini App won't need to show a wallet selection dialog that is common in a + web-based dapp. The Farcaster client hosting your app will take care of + getting the user connected to their preferred crypto wallet. + + +### Send Transactions + +You're now ready to prompt the user to transact. They will be shown a preview of the transaction in their wallet and asked to confirm it: + +```js +import { useSendTransaction } from "wagmi"; +import { parseEther } from "viem"; + +function SendTransaction() { + const { sendTransaction } = useSendTransaction(); + + const handleSend = () => { + sendTransaction({ + to: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", + value: parseEther("0.01"), + }); + }; + + return ; +} +``` + +### Batch Transactions (EIP-5792) + +The Farcaster Wallet supports EIP-5792 `wallet_sendCalls`, allowing you to batch multiple transactions into a single user confirmation. This improves UX by enabling operations like "approve and swap" in one step. + +Common use cases include: + +- Approving a token allowance and executing a swap +- Multiple NFT mints in one operation +- Complex DeFi interactions requiring multiple contract calls + +#### Using Batch Transactions with Wagmi + +```js +import { useSendCalls } from "wagmi"; +import { parseEther } from "viem"; + +function BatchTransfer() { + const { sendCalls } = useSendCalls(); + + return ( + + ); +} +``` + +#### Example: Token Approval and Swap + +```js +import { useSendCalls } from "wagmi"; +import { encodeFunctionData, parseUnits } from "viem"; +import { erc20Abi } from "viem"; + +function ApproveAndSwap() { + const { sendCalls } = useSendCalls(); + + const handleApproveAndSwap = () => { + sendCalls({ + calls: [ + // Approve USDC + { + to: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C", // USDC on Celo + data: encodeFunctionData({ + abi: erc20Abi, + functionName: "approve", + args: [ + "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D", // Router address + parseUnits("100", 6), // Amount + ], + }), + }, + // Swap USDC for CELO + { + to: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D", // Uniswap Router + data: encodeFunctionData({ + abi: uniswapAbi, + functionName: "swapExactTokensForETH", + args: [ + /* swap parameters */ + ], + }), + }, + ], + }); + }; + + return ; +} +``` + + +**Limitations:** +- Transactions execute sequentially, not atomically +- No paymaster support yet +- Available on all EVM chains Farcaster supports + +Use individual transactions when you need to check outputs between calls. + + + +## Authentication + +### Quick Auth (Recommended) + +Quick Auth is the easiest way to get an authenticated session for a user. It uses [Sign in with Farcaster](https://docs.farcaster.xyz/developers/siwf/) under the hood and returns a standard JWT that can be easily verified by your server. + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +// Get authentication token +const token = await sdk.quickAuth.getToken(); + +// Use token in API calls +const response = await fetch("https://api.example.com/user", { + headers: { + Authorization: `Bearer ${token}`, + }, +}); +``` + +The `getToken()` method stores the token in memory and returns it if not expired, otherwise fetches a new one. + +### Sign In with Farcaster + +Alternatively, you can use the `signIn` action to get a Sign in with Farcaster authentication credential: + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +const credential = await sdk.actions.signIn(); +``` + +After requesting the credential, applications must verify it on their server using [`verifySignInMessage`](https://docs.farcaster.xyz/auth-kit/client/app/verify-sign-in-message). Apps can then issue a session token like a JWT for the remainder of the session. + +## Manifest Configuration + +Mini Apps require a manifest file that describes your app. The manifest tells Farcaster clients how to display and interact with your app. + +### Basic Manifest + +Create a `manifest.json` file in your app's root directory: + +```json +{ + "name": "My Celo MiniApp", + "description": "A MiniApp built on Celo", + "iconUrl": "https://example.com/icon.png", + "splashImageUrl": "https://example.com/splash.png", + "splashBackgroundColor": "#000000", + "url": "https://example.com" +} +``` + +### Required Fields + +- **name**: Display name of your MiniApp +- **description**: Brief description of what your app does +- **iconUrl**: URL to your app's icon (recommended: 512x512px) +- **splashImageUrl**: URL to splash screen image (recommended: 1920x1080px) +- **splashBackgroundColor**: Background color for splash screen (hex format) +- **url**: URL where your MiniApp is hosted + +### Optional Fields + +- **requiredChains**: Array of chain IDs your app requires (e.g., `[42220]` for Celo) +- **requiredCapabilities**: Array of required wallet capabilities +- **homeUrl**: URL to navigate when user taps home button + +### Deprecated Fields + +The following fields are deprecated and should not be used: + +- `imageUrl` (use `iconUrl` instead) +- `buttonTitle` (no longer needed) + + + When `url` is not provided in `actionLaunchFrameSchema`, it defaults to the + current webpage URL (including query parameters). + + +## Additional Features + +### Environment Detection + +Detect if your app is running inside a MiniApp environment: + +```js +import { isInMiniApp } from "@farcaster/miniapp-sdk"; + +if (isInMiniApp()) { + // Running in MiniApp +} else { + // Running in regular browser +} +``` + +### Back Navigation + +Integrate back control for better navigation: + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +// Navigate back +sdk.back(); +``` + +### Haptic Feedback + +Provide haptic feedback for better user interaction: + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +// Trigger haptic feedback +sdk.haptics.impact(); // Light impact +sdk.haptics.notification(); // Notification feedback +sdk.haptics.selection(); // Selection feedback +``` + +### Share Extensions + +Enable your app to receive shared casts from the system share sheet: + +```js +import { sdk } from "@farcaster/miniapp-sdk"; + +// Listen for shared casts +sdk.context.cast_share?.then((cast) => { + console.log("Received cast:", cast); +}); +``` + +## Publishing Your MiniApp - +After building your MiniApp, you'll need to publish it so users can discover and use it. Follow the [Farcaster MiniApp publishing guide](https://miniapps.farcaster.xyz/docs/guides/publishing) for detailed instructions. +## Resources +- [Farcaster MiniApp Documentation](https://miniapps.farcaster.xyz/) +- [Farcaster MiniApp SDK Reference](https://miniapps.farcaster.xyz/docs/sdk) +- [Celo Composer](https://github.com/celo-org/celo-composer) +- [Wagmi Documentation](https://wagmi.sh) diff --git a/build-on-celo/build-with-self.mdx b/build-on-celo/build-with-self.mdx index 9b8da66356..fee26e07e2 100644 --- a/build-on-celo/build-with-self.mdx +++ b/build-on-celo/build-with-self.mdx @@ -1,49 +1,444 @@ --- title: Build with Self -og:description: A beginner's guide to understanding and using Self +og:description: A comprehensive guide to understanding and using Self identity protocol on Celo --- -By the conclusion of this guide, you will have a basic understanding of Self and how to get started with it. +By the conclusion of this guide, you will have a comprehensive understanding of Self and how to integrate it into your Celo applications. This document will cover: - What is Self? +- Getting Started +- Integration Examples +- New Features (2025) - Technical Resources -- Opportunities for Builders +- Use Cases ## What is Self? [Self](https://self.xyz/) is a privacy-first, open-source identity protocol that uses zero-knowledge proofs for secure identity verification. -It enables Sybil resistance and selective disclosure using real-world attestations like passports. With a few lines of code, developers can easily check if their users are humans, while preserving their privacy. +It enables Sybil resistance and selective disclosure using real-world attestations like passports, EU ID cards, and Indian Aadhaar. With a few lines of code, developers can easily check if their users are humans, while preserving their privacy. -Access the [Self developer docs](https://docs.self.xyz/), explore APIs, and start building today. +### How It Works + +Self Protocol simplifies digital identity verification with zero-knowledge proofs in three steps: + +1. **Scan Your Identity Document**: Users scan their passport, EU ID card, or Aadhaar using the NFC reader of their phone. +2. **Generate a Proof**: Generate a zk proof over the identity document, selecting only what you want to disclose. +3. **Share Your Proof**: Share the zk proof with the selected application. ## Verify Your Digital Identity Seamlessly and securely verify your digital identity with Self. It allows you to: - **Prove Your Humanity:** Confirm you are human without revealing personal information. -- **Proof your identity, age, nationality or :** Demonstrate where you're from while maintaining privacy. Securely capture the first page data and RFID from your passport to verify your identity. -- **Privacy-preserving technology:** Protect your users private information. They will only disclose credentials and information that they allow. +- **Prove Identity, Age, Nationality:** Demonstrate where you're from while maintaining privacy. Securely capture the first page data and RFID from your passport to verify your identity. +- **Privacy-preserving Technology:** Protect your users' private information. They will only disclose credentials and information that they allow. - **Streamline Verification:** Enjoy a smooth and efficient identity verification process. -- **Optimized for Web3 and Universal Apps:** Harness zero-knowledge proofs and one-tap verifications in Web3 apps +- **Optimized for Web3 and Universal Apps:** Harness zero-knowledge proofs and one-tap verifications in Web3 apps. + +## New Features (2025) + +### Expanded Identity Document Support + +Self now supports: + +- **EU Biometric ID Cards**: Scan NFC-enabled EU IDs covering 27 countries +- **Indian Aadhaar**: Support for Aadhaar verification +- **Passports**: Continued support for passport verification + +All verification leverages zero-knowledge proofs (ZKPs) and no data leaves the user's device. + +### Points/Rewards System + +Self has introduced a points program that incentivizes consistent, secure use: + +- Users earn points for setting up Self Pass +- Points earned for continued use across partner platforms +- Points can be redeemed for rewards +- Designed to drive engagement and validate active, verified users + +### Major Integrations + +- **Google Cloud**: Integrated Self's SDK and ZKP-based proof-of-humanity in its Web3 Portal +- **Aave**: DeFi protocol integration enabling compliance checks, sybil-resistant airdrops, and age/country-gated services +- **Celo Blockchain**: On-chain attestations leverage the Celo blockchain for transparency and auditability + +## Getting Started + +### Prerequisites + +- Node.js 18+ or a modern web browser +- A Celo wallet (for on-chain integrations) +- Access to Self SDK or API +- **Self App**: Download the Self app to verify your identity + - [Google Play Store](https://play.google.com/store/apps/details?id=com.proofofpassportapp&pli=1) + - [App Store](https://apps.apple.com/us/app/self-zk-passport-identity/id6478563710) + +### Installation + +Install the Self SDK: + + +```bash npm +npm install @self.id/sdk +``` + +```bash yarn +yarn add @self.id/sdk +``` + +```bash pnpm +pnpm add @self.id/sdk +``` + + + +### Basic Frontend Integration + +#### QRCode SDK Integration + +The QRCode SDK allows users to scan a QR code with their mobile device to verify their identity: + +```js +import { QRCodeSDK } from "@self.id/qrcode-sdk"; + +const qrcodeSDK = new QRCodeSDK({ + appName: "My Celo App", + appUrl: "https://myapp.com", +}); + +// Generate QR code for user to scan +const qrCode = await qrcodeSDK.generateQRCode({ + disclosures: [ + { + type: "age", + minAge: 18, + }, + { + type: "nationality", + allowedCountries: ["US", "CA"], + }, + ], +}); + +// Display QR code to user +displayQRCode(qrCode); +``` + +#### Disclosure Configuration + +Configure what information you need from users: + +```js +const disclosureConfig = { + age: { + minAge: 21, // Require users to be at least 21 + }, + nationality: { + allowedCountries: ["US", "CA", "GB"], // Only allow specific countries + }, + humanity: true, // Require proof of humanity +}; +``` + +### Contract Integration + +#### Basic On-Chain Verification + +Integrate Self verification into your smart contracts: + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +import "@self.id/contracts/SelfVerification.sol"; + +contract MyCeloContract is SelfVerification { + mapping(address => bool) public verifiedUsers; + + function verifyUser(address user) external { + require(isVerified(user), "User not verified"); + verifiedUsers[user] = true; + } + + function claimAirdrop() external { + require(verifiedUsers[msg.sender], "User must be verified"); + // Airdrop logic here + } +} +``` + +#### Frontend Contract Interaction + +```js +import { getContract, createPublicClient, http } from "viem"; +import { celo } from "viem/chains"; +import { SelfVerificationABI } from "@self.id/contracts"; + +const publicClient = createPublicClient({ + chain: celo, + transport: http(), +}); + +const contract = getContract({ + address: "0x...", // Your contract address + abi: SelfVerificationABI, + client: publicClient, +}); + +// Check if user is verified +const isVerified = await contract.read.isVerified([userAddress]); + +if (isVerified) { + // User is verified, proceed with protected action + await contract.write.claimAirdrop(); +} +``` + +### Backend Verification + +Verify Self proofs on your backend: + +```js +import { SelfBackendVerifier } from "@self.id/backend-verifier"; + +const verifier = new SelfBackendVerifier({ + rpcUrl: "https://forno.celo.org", // Celo RPC +}); + +// Verify a proof submitted by the frontend +const isValid = await verifier.verifyProof({ + proof: userProof, + disclosureConfig: { + age: { minAge: 18 }, + humanity: true, + }, +}); + +if (isValid) { + // Issue session token or grant access + const sessionToken = generateSessionToken(userAddress); + return { success: true, token: sessionToken }; +} +``` + +## Step-by-Step Integration Guide + +### 1. Set Up Your Project + +```bash +# Create a new project +npx create-next-app@latest my-self-app +cd my-self-app + +# Install dependencies +npm install @self.id/sdk viem@2 @celo/abis +``` + +### 2. Configure Self SDK + +Create a configuration file: + +```js +// lib/self-config.js +export const selfConfig = { + appName: "My Celo App", + appUrl: process.env.NEXT_PUBLIC_APP_URL, + chainId: 42220, // Celo mainnet + rpcUrl: process.env.NEXT_PUBLIC_RPC_URL || "https://forno.celo.org", +}; +``` + +### 3. Create Verification Component + +```jsx +// components/SelfVerification.jsx +"use client"; + +import { useState } from "react"; +import { QRCodeSDK } from "@self.id/qrcode-sdk"; +import { selfConfig } from "@/lib/self-config"; + +export function SelfVerification() { + const [qrCode, setQrCode] = useState(null); + const [isVerified, setIsVerified] = useState(false); + + const handleVerify = async () => { + const qrcodeSDK = new QRCodeSDK(selfConfig); + + const qr = await qrcodeSDK.generateQRCode({ + disclosures: [{ type: "humanity" }, { type: "age", minAge: 18 }], + }); + + setQrCode(qr); + + // Listen for verification result + qrcodeSDK.onVerification((result) => { + if (result.success) { + setIsVerified(true); + // Send proof to backend for verification + verifyOnBackend(result.proof); + } + }); + }; + + return ( +
+ {!isVerified ? ( + + ) : ( +
Verified! You can now access protected features.
+ )} + {qrCode && Verification QR Code} +
+ ); +} +``` + +### 4. Backend Verification Endpoint + +```js +// pages/api/verify.js +import { SelfBackendVerifier } from "@self.id/backend-verifier"; + +const verifier = new SelfBackendVerifier({ + rpcUrl: process.env.CELO_RPC_URL, +}); + +export default async function handler(req, res) { + if (req.method !== "POST") { + return res.status(405).json({ error: "Method not allowed" }); + } + + const { proof, userAddress } = req.body; + + try { + const isValid = await verifier.verifyProof({ + proof, + disclosureConfig: { + humanity: true, + age: { minAge: 18 }, + }, + }); + + if (isValid) { + // Issue session token + const sessionToken = generateSessionToken(userAddress); + return res.status(200).json({ success: true, token: sessionToken }); + } else { + return res.status(400).json({ error: "Invalid proof" }); + } + } catch (error) { + return res.status(500).json({ error: error.message }); + } +} +``` + +## Use Cases + +### Airdrop Protection + +Protect token distributions from bots by requiring proof of humanity: + +```js +// Only allow verified humans to claim airdrop +const canClaim = await contract.read.isVerified([userAddress]); + +if (canClaim) { + await contract.write.claimAirdrop(); +} +``` + +### Quadratic Funding + +Prevent farmers from skewing rewards in quadratic funding mechanisms: + +```js +// Verify user is human before allowing vote +const isHuman = await verifyHumanity(userAddress); +if (isHuman) { + submitQuadraticVote(projectId, voteAmount); +} +``` + +### Wallet Recovery + +Safeguard assets using IDs as recovery sources: + +```js +// Require identity verification for wallet recovery +const isVerified = await verifyIdentity(recoveryAddress); +if (isVerified) { + initiateWalletRecovery(newWalletAddress); +} +``` + +### Age Verification + +Restrict access to age-gated content or services: + +```js +// Verify user is over 21 +const isOver21 = await verifyAge(userAddress, { minAge: 21 }); +if (isOver21) { + grantAccess(); +} +``` + +### Country-Specific Functionality + +Enable country-based features while preserving privacy: + +```js +// Verify user is from allowed country +const isFromAllowedCountry = await verifyNationality(userAddress, { + allowedCountries: ["US", "CA"], +}); +``` + +### Sanction List Checking + +Check users are not on sanctioned entity lists: + +```js +// Verify user is not on sanctions list +const isNotSanctioned = await verifySanctions(userAddress); +if (isNotSanctioned) { + allowTransaction(); +} +``` + +### Sybil-Resistant Polling + +Ensure one person = one vote: + +```js +// Verify user hasn't already voted +const hasVoted = await checkVoteStatus(userAddress); +const isHuman = await verifyHumanity(userAddress); + +if (!hasVoted && isHuman) { + submitVote(option); + markAsVoted(userAddress); +} +``` ## Technical Resources - [Self Website](https://self.xyz/) - [Self Documentation](https://docs.self.xyz/) - [Self Playground](https://playground.self.xyz/) -- [Self Quickstart](https://docs.self.xyz/use-self/quickstart) - -## What to build? - -- Airdrop Protection -- Quadratic Funding -- Wallet Recovery -- Social Media & Marketplaces -- Country-Specific Functionality -- AI Protection for Smart Contracts -- Sanction List Checking -- Age Verification -- Sybil-Resistant Polling +- [Self Staging Playground](https://playground.staging.self.xyz/) +- [Self Quickstart Guide](https://docs.self.xyz/use-self/quickstart) +- [Contract Integration Guide](https://docs.self.xyz/contract-integration/basic-integration) +- [Backend Integration Guide](https://docs.self.xyz/backend-integration/basic-integration) +- [QRCode SDK Documentation](https://docs.self.xyz/frontend-integration/qrcode-sdk) +- [Deployed Contracts](https://docs.self.xyz/contract-integration/deployed-contracts) + +## Support + +Join the [Self Builder Group](https://t.me/+d2TGsbkSDmgzODVi) on Telegram for community support and updates. + +For Celo-specific integrations, visit the [Celo Discord](https://discord.com/invite/celo) and ask in the #build-with-celo channel. diff --git a/build-on-celo/fund-your-project.mdx b/build-on-celo/fund-your-project.mdx index b1f6c83146..6871b8d96f 100644 --- a/build-on-celo/fund-your-project.mdx +++ b/build-on-celo/fund-your-project.mdx @@ -3,7 +3,6 @@ title: Fund your Project og:description: Learn how to get funding for your project on Celo --- - Discover funding opportunities in the Celo ecosystem. --- @@ -17,34 +16,38 @@ Explore these opportunities to maximize your funding potential. Establishing a strong onchain reputation increases your chances of securing retroactive funding. Here’s how you can get started: - - 1. **Create a project profile on [Karma GAP](https://docs.gap.karmahq.xyz/how-to-guides/integrations/celo-proof-of-ship)**: Build credibility by showcasing your contributions and activity. - 1. **Apply for monthly rewards with [Proof of Ship](https://celo-devs.beehiiv.com/subscribe)** Demonstrate consistent progress for automated retroactive rewards. +1. **Create a project profile on [Karma GAP](https://docs.gap.karmahq.xyz/how-to-guides/integrations/celo-proof-of-ship)**: Build credibility by showcasing your contributions and activity. + +1. **Apply for monthly rewards with [Proof of Ship](https://celo-devs.beehiiv.com/subscribe)** Demonstrate consistent progress for automated retroactive rewards. ## Apply for Grant Opportunities There are various grant opportunities for builders in the Celo ecosystem, with funding available at different stages of your project. To maximize your chances of receiving rewards, include your Karma GAP project profile when applying. - 1. **[Prezenti Grants](https://www.prezenti.xyz/)** +![Celo Funding Programs](/img/build/celo-programs.png) - 2. **[Celo Support Streams](https://www.celopg.eco/programs)**: Submit your Support Stream application and earn bi-weekly CELO incentive budgets +1. **[Prezenti Grants](https://www.prezenti.xyz/)** - 3. **[CPG Retroactive Funding](https://www.celopg.eco/programs)** +2. **[CPG Retroactive Funding](https://www.celopg.eco/programs)** ## Ecosystem-Led Funding Opportunities Expand your funding sources with ecosystem partner initiatives. - 1. **[Proof of Impact](https://www.divvi.xyz/)**: Automate gas fee revenue splits to fund your app. +1. **[Celo Builder Fund](https://www.celopg.eco/programs/celo-builder-fund)**: Funding for builders in the Celo ecosystem + +2. **[Celo Support Streams](https://www.celopg.eco/programs)**: Submit your Support Stream application and earn bi-weekly CELO incentive budgets + +3. **[Proof of Impact](https://www.divvi.xyz/)**: Automate gas fee revenue splits to fund your app. - 2. [Builder Rewards - Celo PG x Talent Protocol](https://www.celopg.eco/programs) - 10.000 CELO/ month +4. [Builder Rewards - Celo PG x Talent Protocol](https://www.celopg.eco/programs) - 10.000 CELO/ month - 3. **[Commons Builder Income](https://www.commonsprotocol.xyz/)**: Apply for CBI and earn daily rewards +5. **[Commons Builder Income](https://www.commonsprotocol.xyz/)**: Apply for CBI and earn daily rewards - 4. **[GoodBuilders Program](https://gooddollar.notion.site/GoodBuilders-Program-1a6f258232f080fea8a6e3760bb8f53d)**: A year-long initiative offering \$220k in rewards for building with G$. +6. **[GoodBuilders Program](https://gooddollar.notion.site/GoodBuilders-Program-1a6f258232f080fea8a6e3760bb8f53d)**: A year-long initiative offering \$220k in rewards for building with G$. - 5. **[Glo Dollar Liquidity Flywheel](https://www.glodollar.org/articles/glo-dollar-and-celo-public-goods)**: Around $40,000 will be donated to Celo Public Goods, thanks to a $1M Glo Dollar (USDGLO) holding from Mento. Projects that increase Glo Dollar liquidity will receive more funding. +7. **[Glo Dollar Liquidity Flywheel](https://www.glodollar.org/articles/glo-dollar-and-celo-public-goods)**: Around $40,000 will be donated to Celo Public Goods, thanks to a $1M Glo Dollar (USDGLO) holding from Mento. Projects that increase Glo Dollar liquidity will receive more funding. ## Accelerators/ Incubators @@ -54,10 +57,10 @@ Expand your funding sources with ecosystem partner initiatives. ## Funds - 1. **[Verda Ventures](https://verda.ventures/)**: Building for MiniPay & raising funding? Reach out to [team@verda.ventures](mailto:team@verda.ventures) with a deck and product demo. +1. **[Verda Ventures](https://verda.ventures/)**: Building for MiniPay & raising funding? Reach out to [team@verda.ventures](mailto:team@verda.ventures) with a deck and product demo. -If you want to add another ecosystem-led funding program, [edit this page](https://github.com/celo-org/docs/edit/main/docs/build/fund-your-project.md) to include it. +If you want to add another ecosystem-led funding program, [edit this page](https://github.com/celo-org/docs/edit/main/build-on-celo/fund-your-project.mdx) to include it. ## Get Funding Updates -Stay up to date with the latest funding opportunities by [joining our newsletter](https://embeds.beehiiv.com/eeadfef4-2f0c-45ce-801c-b920827d5cd2). \ No newline at end of file +Stay up to date with the latest funding opportunities by [joining our newsletter](https://embeds.beehiiv.com/eeadfef4-2f0c-45ce-801c-b920827d5cd2). diff --git a/build-on-celo/launch-checklist.mdx b/build-on-celo/launch-checklist.mdx index 37b8520f8f..23f733ac83 100644 --- a/build-on-celo/launch-checklist.mdx +++ b/build-on-celo/launch-checklist.mdx @@ -5,47 +5,91 @@ og:description: A comprehensive guide to assist you in launching dapps on Celo. A comprehensive guide to assist you in launching dapps on Celo. -## Integration +## Pre-Launch -- [ ] **Wallet Connect**: Essential for Valora integration. -- [ ] **Security Audit**: Have you finished this? Remember to publish the results and the auditor's details on your website. +### Security & Audits -## Reporting +- [ ] **Security Audit**: Complete a professional security audit for your smart contracts +- [ ] **Audit Publication**: Publish audit results and auditor details on your website +- [ ] **Code Review**: Conduct internal code review and testing +- [ ] **Best Practices**: Use audited libraries (e.g., OpenZeppelin) instead of writing everything from scratch +- [ ] **Test Coverage**: Ensure comprehensive test coverage for all critical functions -Make your dapp stand out by reporting it on these platforms: +### Smart Contract Preparation -- [ ] [Dapp Radar](https://dappradar.com) -- [ ] [DeFi Llama (for DeFi & NFT Projects)](https://docs.llama.fi/list-your-project/submit-a-project) -- [ ] [Electric Capital Reporting](https://github.com/electric-capital/crypto-ecosystems) -- [ ] [Celo Scan Contract Verification](https://celoscan.io/verifyContract) -- [ ] [Celo Explorer Contract Verification](https://celo.blockscout.com/contract-verification) -- [ ] [Dune](https://dune.com/contracts/new) +- [ ] **Contract Verification**: Verify contracts on [CeloScan](https://celoscan.io/verifyContract) and [Celo Explorer](https://celo.blockscout.com/contract-verification) +- [ ] **Documentation**: Add clear tutorials and documentation on how to use your contracts/tokens +- [ ] **Upgradeability**: Document upgrade paths if using upgradeable contracts +- [ ] **Gas Optimization**: Optimize gas usage for better user experience +### Integration & Testing -### If your dapp has smart contracts +- [ ] **Wallet Integration**: Integrate wallet connection (WalletConnect, RainbowKit, etc.) +- [ ] **Multi-Wallet Support**: Test with multiple wallets (Valora, MetaMask, etc.) +- [ ] **Network Configuration**: Ensure proper Celo mainnet and testnet configuration +- [ ] **Error Handling**: Implement comprehensive error handling and user feedback +- [ ] **Mobile Testing**: Test on mobile devices, especially for MiniPay integration -- [ ] Add a tutorial about how to use the contract/token, etc. -- [ ] Best practices include: using Open Zeppelin contracts and not writing everything from scratch as this could open your contracts to vulnerabilities. -- [ ] Consider your options for a contract audit. +### Analytics & Monitoring -### If your dapp doesn't have smart contracts +- [ ] **Analytics Setup**: Configure analytics tracking (e.g., Google Analytics, Mixpanel) +- [ ] **Monitoring Tools**: Set up monitoring and alerting (e.g., Sentry, DataDog) +- [ ] **On-Chain Analytics**: Integrate on-chain analytics tools (e.g., Dune, The Graph) +- [ ] **Performance Monitoring**: Monitor application performance and transaction success rates +- [ ] **User Behavior Tracking**: Track key user actions and conversion funnels -- [ ] Discuss potential extensions or enhancements. +### Documentation & User Resources -## Training +- [ ] **Getting Started Guide**: Create a clear guide for new users +- [ ] **On/Off-Ramp Instructions**: Provide instructions for buying/selling crypto +- [ ] **FAQ Section**: Address common questions and concerns +- [ ] **Video Tutorials**: Create video walkthroughs if applicable +- [ ] **Developer Documentation**: Document APIs and integration guides -Provide resources for users: +## Launch -- [ ] Guide on getting started with your dapp. -- [ ] Instructions on how to on/off ramp for a seamless dapp experience. +### Platform Reporting -## Marketing +Make your dapp discoverable by reporting it on these platforms: -- [ ] Complete the [Marketing Intake Form](https://docs.google.com/forms/d/e/1FAIpQLSe0LMpEy2nicTcdoI5_LFhg3VZbpyhTymmSTzZ7HavdRiE4AQ/viewform) and share your marketing strategies. -- [ ] Join the Celo Founders Telegram group. -- [ ] Remember to tag [@Celo](https://x.com/Celo) in any launch announcements. +- [ ] [Dapp Radar](https://dappradar.com) - General dApp directory +- [ ] [DeFi Llama](https://docs.llama.fi/list-your-project/submit-a-project) - For DeFi & NFT projects +- [ ] [Electric Capital](https://github.com/electric-capital/crypto-ecosystems) - Ecosystem reporting +- [ ] [Dune Analytics](https://dune.com/contracts/new) - Add your contracts for analytics -## Legal +### Marketing -- [ ] Ensure you have public-facing Terms & Conditions. -- [ ] Make sure you have a public-facing GDPR privacy policy or meet other privacy requirements. \ No newline at end of file +- [ ] **Marketing Intake**: Complete the [Marketing Intake Form](https://docs.google.com/forms/d/e/1FAIpQLSe0LMpEy2nicTcdoI5_LFhg3VZbpyhTymmSTzZ7HavdRiE4AQ/viewform) +- [ ] **Community Engagement**: Join the Celo Founders Telegram group +- [ ] **Social Media**: Tag [@Celo](https://x.com/Celo) in launch announcements +- [ ] **Press Release**: Prepare and distribute launch announcement +- [ ] **Content Marketing**: Create blog posts, tutorials, or case studies + +### Legal & Compliance + +- [ ] **Terms & Conditions**: Ensure public-facing Terms & Conditions are published +- [ ] **Privacy Policy**: Publish GDPR-compliant privacy policy or meet other privacy requirements +- [ ] **Regulatory Compliance**: Verify compliance with relevant regulations in your jurisdiction +- [ ] **Disclaimers**: Add appropriate disclaimers for financial/DeFi applications + +## Post-Launch + +### Monitoring & Maintenance + +- [ ] **Monitor Metrics**: Track key metrics (users, transactions, TVL, etc.) +- [ ] **Error Tracking**: Monitor and address errors promptly +- [ ] **User Feedback**: Collect and respond to user feedback +- [ ] **Performance Optimization**: Continuously optimize based on usage patterns + +### Growth & Iteration + +- [ ] **Feature Updates**: Plan and execute feature updates based on user needs +- [ ] **Community Building**: Engage with users and build a community +- [ ] **Partnerships**: Explore partnerships with other Celo projects +- [ ] **Grant Applications**: Consider applying for ecosystem grants and funding + +### Documentation Updates + +- [ ] **Keep Docs Updated**: Update documentation as features evolve +- [ ] **Changelog**: Maintain a changelog for transparency +- [ ] **Migration Guides**: Provide guides for breaking changes if applicable diff --git a/build-on-celo/nightfall.mdx b/build-on-celo/nightfall.mdx index e99e90b731..43b5580879 100644 --- a/build-on-celo/nightfall.mdx +++ b/build-on-celo/nightfall.mdx @@ -13,9 +13,10 @@ Celo is the **first payments-focused blockchain** to deploy Nightfall, combining **Testnet Status**: Live and ready for testing -Nightfall testnet is currently active on Celo Sepolia for developers and enterprises to build and test private payment applications. +**Nightfall** testnet is currently active on Celo Sepolia for developers and enterprises to build and test private payment applications. **Full API documentation** is available in the [Nightfall GitHub docs](https://github.com/EYBlockchain/nightfall_4_CE/blob/master/doc/nf_4.md#apis). + ## What is Nightfall? @@ -30,17 +31,20 @@ Nightfall uses **zero-knowledge rollup (ZK-ZK rollup)** technology to batch priv ## Key Features ### Privacy Technology + - **Zero-Knowledge Proofs**: Cryptographic privacy without trusted intermediaries - **Layer 3 Architecture**: Runs on top of Celo L2 for maximum efficiency - **Enterprise Access Control**: X509 certificate-based authentication ### Token Support + - **ERC-20**: Stablecoins (USDT, USDC) and other fungible tokens - **ERC-721**: Non-fungible tokens (NFTs) - **ERC-1155**: Multi-token standard - **ERC-3525**: Semi-fungible tokens ### Performance + - **Low Gas Costs**: ~6000 Gas per private transfer - **Fast Finality**: Cryptographic finality matching Celo's block time - **Scalability**: Transaction batching for efficient throughput @@ -50,19 +54,25 @@ Nightfall uses **zero-knowledge rollup (ZK-ZK rollup)** technology to batch priv Nightfall operates with three main components: ### Client + The user-facing application that enables users to make private transactions. Clients interact with proposers and manage: + - Deposits (converting public tokens to private commitments) - Transfers (private peer-to-peer transactions) - Withdrawals (converting private commitments back to public tokens) ### Proposer + Network nodes that create Layer 2 blocks by batching transactions and generating zero-knowledge proofs. Proposers: + - Collect transactions from clients - Generate ZK proofs for transaction validity - Submit blocks to on-chain smart contracts ### Smart Contracts + On-chain contracts that handle: + - Token escrow for deposits and withdrawals - ZK proof verification - X509 certificate validation for access control @@ -70,18 +80,23 @@ On-chain contracts that handle: ## Use Cases ### Private B2B Payments + Enable confidential business-to-business transactions while maintaining an auditable record for compliance. Ideal for: + - Invoice settlements - Vendor payments - Intercompany transfers ### Supply Chain Finance + Process payments across supply chain partners with privacy, reducing transaction costs and eliminating intermediaries. ### Enterprise Treasury Management + Manage corporate funds with confidentiality for strategic transactions, mergers, acquisitions, and sensitive operations. ### Cross-Border Payments + Leverage Celo's global reach and low fees with added privacy for international B2B flows, particularly valuable in emerging markets. ## Getting Started @@ -91,6 +106,7 @@ Leverage Celo's global reach and low fees with added privacy for international B To integrate Nightfall, you'll need: 1. **Development Tools**: + - **git**: For cloning the repository - **docker-compose**: For running the client services - **curl**: For making API requests to the client @@ -103,19 +119,25 @@ To integrate Nightfall, you'll need: ### Transaction Flow #### Deposits + Convert public tokens on Celo into private commitments on Nightfall: + ``` Public Celo Token β†’ Nightfall Smart Contract (escrow) β†’ Private Commitment ``` #### Transfers + Send private transactions between Nightfall users: + ``` Private Commitment (sender) β†’ ZK Proof β†’ Private Commitment (receiver) ``` #### Withdrawals + Convert private commitments back to public tokens: + ``` Private Commitment β†’ ZK Proof β†’ Nightfall Smart Contract β†’ Public Celo Token ``` @@ -148,6 +170,7 @@ Update the following variables in `celo-sepolia.env`: **Funding Your Address** These addresses must be funded with CELO on the Celo Sepolia testnet. You can get testnet CELO from a [faucet](https://faucet.celo.org/celo-sepolia) if needed. + **3. Run Docker Compose as Client** @@ -210,6 +233,7 @@ curl -X POST http://localhost:3000/v1/deposit \ ``` **Parameters:** + - `ercAddress`: The ERC20/ERC721/ERC1155/ERC3525 token contract address. Use `0x471EcE3750Da237f93B8E339c536989b8978a438` for CELO token (ERC20 via Celo Token Duality) - `tokenId`: Token ID (use all zeros for ERC20) - `tokenType`: `0` for ERC20, `1` for ERC721, `2` for ERC1155, `3` for ERC3525 @@ -259,6 +283,7 @@ curl -i -H "Content-Type: application/json" \ ``` **Parameters:** + - `ercAddress`: Token contract address - `tokenId`: Token ID (`0x00` for ERC20) - `recipientData.values`: Array of amounts to send (in hex without `0x` prefix) @@ -293,6 +318,7 @@ curl -X POST http://localhost:3000/v1/withdraw \ ``` **Parameters:** + - `ercAddress`: Token contract address - `tokenId`: Token ID (all zeros for ERC20) - `tokenType`: `0` for ERC20, `1` for ERC721, `2` for ERC1155, `3` for ERC3525 @@ -327,6 +353,7 @@ curl -X POST http://localhost:3000/v1/de-escrow \ ``` **Parameters:** + - All parameters from the withdrawal request - `withdrawFundSalt`: The salt value returned from the withdrawal operation @@ -352,11 +379,13 @@ curl -X POST http://localhost:3000/v1/de-escrow \ ## Resources ### Documentation + - **[Nightfall GitHub Repository](https://github.com/EYBlockchain/nightfall_4_CE)**: Full source code and implementation - **[Technical Documentation](https://github.com/EYBlockchain/nightfall_4_CE/blob/master/doc/nf_4.md)**: Comprehensive guide including architecture, APIs, deployment, and testing - **[EY Blockchain](https://blockchain.ey.com/)**: Learn more about EY's blockchain solutions ### APIs + - **Client APIs**: Deposit, transfer, withdraw, and balance query endpoints - **Proposer APIs**: Block submission and transaction validation - **Webhook Support**: Real-time transaction notifications @@ -364,6 +393,7 @@ curl -X POST http://localhost:3000/v1/de-escrow \ Full API documentation is available in the [Nightfall GitHub docs](https://github.com/EYBlockchain/nightfall_4_CE/blob/master/doc/nf_4.md#apis). ### Testing & Deployment + - **Local Testing**: See [Running the Client on Celo Sepolia](#running-the-client-on-celo-sepolia) for instructions on running Nightfall locally with Docker - **Testnet Deployment**: Guide for deploying on Celo Sepolia testnet - **Production Deployment**: Best practices for mainnet deployment @@ -371,6 +401,7 @@ Full API documentation is available in the [Nightfall GitHub docs](https://githu ### Community & Support Get help and connect with the community: + - **[Celo Discord](https://chat.celo.org)**: Join the #nightfall channel for questions - **[Celo Forum](https://forum.celo.org)**: Discuss integration strategies and use cases - **[GitHub Issues](https://github.com/EYBlockchain/nightfall_4_CE/issues)**: Report bugs or request features @@ -388,6 +419,7 @@ By deploying on Celo, Nightfall brings enterprise-grade privacy to a mobile-firs **Testnet Environment** Nightfall testnet on Celo Sepolia is for development and testing purposes only. Do not use real assets, production data, or sensitive information during testing. Testnet tokens hold no real-world economic value. + --- diff --git a/build-on-celo/quickstart.mdx b/build-on-celo/quickstart.mdx index 0384588f0d..4f6fcfedc8 100644 --- a/build-on-celo/quickstart.mdx +++ b/build-on-celo/quickstart.mdx @@ -3,119 +3,183 @@ title: Quickstart sidebarTitle: Quickstart with Celo Composer --- -To test out deploying a dApp on Celo, we recommend using [Celo Composer](https://github.com/celo-org/celo-composer), which allows you to quickly build, deploy, and iterate on decentralized applications using Celo. It provides a number of frameworks, examples, templates and Celo specific functionality to help you get started with your next dApp. +A powerful CLI tool for generating customizable Celo blockchain starter kits with modern monorepo architecture. ## Prerequisites -- Node (v20 or higher) -- Git (v2.38 or higher) +- Node.js >= 18.0.0 +- PNPM (recommended) or npm/yarn -## How to use Celo Composer +## Quick Start -The easiest way to start with Celo Composer is using `@celo/celo-composer`. This CLI tool lets you quickly start building dApps on Celo for multiple frameworks, including React (and rainbowkit). To get started, just run the following command, and follow the steps: +Create a new Celo project in seconds: ```bash npx @celo/celo-composer@latest create ``` -### Provide the Project Name: +This will start an interactive setup process where you can choose your template, wallet provider, and smart contract framework. -You will be prompted to enter the name of your project +## Installation + +No installation required! Use `npx` to run Celo Composer directly without installing anything globally. + +## Usage + +### Interactive Mode + +Run the command without any flags to enter interactive mode: ```bash -What is your project name: +npx @celo/celo-composer@latest create my-celo-app ``` -### Choose a smart contract development environment: +The CLI will guide you through: -You will be asked if you want to use Hardhat. Select Yes or No +- Project name and description +- Template selection +- Wallet provider choice +- Smart contract framework selection +- Dependency installation + +### Non-Interactive Mode + +Create a project with specific configurations using flags: ```bash -Do you want to use Hardhat? (Y/n) +npx @celo/celo-composer@latest create my-celo-app \ + --template basic \ + --wallet-provider rainbowkit \ + --contracts hardhat \ + --description "My awesome Celo app" ``` -### Choose to Use a Pre-Built Template, highlighting Celo's unique features: +### Quick Start with Defaults -You will be asked if you want to use a [template](#supported-templates), check [below](#supported-templates) for the options. Select Yes or No +Skip all prompts and use default settings. This will create a basic app with no additional setup: ```bash -Do you want to use a template? +npx @celo/celo-composer@latest create my-celo-app --yes ``` -### Select a Template: +## Available Templates + +### Basic Web App (default) -If you chose to use a template, you will be prompted to select a template from the list provided +A standard Next.js 14+ web application with modern UI, perfect for most dApp projects. ```bash -# built in frontend logic to use your dapp in MiniPay, pre-built example functions for sign, transact and mint -- MiniPay -# template built for easy Valora connectivity -- Valora +npx @celo/celo-composer@latest create --template basic ``` -### Provide the Project Owner's Name: +### Farcaster Miniapp -You will be asked to enter the project owner's name +A specialized template for building Farcaster Miniapps with Farcaster SDK and Frame development support. ```bash -Project Owner name: +npx @celo/celo-composer@latest create --template farcaster-miniapp ``` -### Wait for Project Creation: +### MiniPay App -The CLI will now create the project based on your inputs. This may take a few minutes. +Optimized for building dApps that integrate with the MiniPay mobile wallet, with mobile-first design. -### Follow the instructions to start the project. +```bash +npx @celo/celo-composer@latest create --template minipay +``` + +Checkout [minipay docs](/build/build-on-minipay/overview) to learn more about it. -The same will be displayed on the console after the project is created +### AI Chat App + +A standalone Next.js AI chat application template. ```bash -πŸš€ Your starter project has been successfully created! +npx @celo/celo-composer@latest create --template ai-chat +``` -Before you start the project, please follow these steps: +## Wallet Providers -1. Rename the file: - packages/react-app/.env.template - to - packages/react-app/.env +Choose a wallet provider to handle user authentication and transaction signing: -2. Open the newly renamed .env file and add all the required environment variables. +- **RainbowKit** (default): Popular, easy-to-use wallet connector for React apps +- **Thirdweb**: Complete Web3 development framework with powerful wallet tools +- **None**: Skip wallet integration if you want to integrate your own solution -Once you've done that, you're all set to start your project! +```bash +npx @celo/celo-composer@latest create --wallet-provider rainbowkit +``` + +## Smart Contract Frameworks -Run the following commands from the packages/react-app folder to start the project: +Set up a smart contract development environment: - yarn install - yarn dev +- **Hardhat** (default): Popular Ethereum development environment +- **Foundry**: Fast, portable and modular toolkit for Ethereum application development +- **None**: Skip smart contract development setup -If you prefer npm, you can run: +```bash +npx @celo/celo-composer@latest create --contracts hardhat +``` - npm install - npm run dev +## Command Options -Thank you for using Celo Composer! If you have any questions or need further assistance, please refer to the README or reach out to our team. +```bash +npx @celo/celo-composer@latest create [project-name] [options] ``` -πŸ”₯Voila, you have a dApp ready to go. Start building your dApp on Celo. +| Flag | Description | Default | +| --------------------------------- | ------------------------------------------------------------------ | ------------------ | +| `-d, --description ` | Project description | Interactive prompt | +| `-t, --template ` | Template type (`basic`, `farcaster-miniapp`, `minipay`, `ai-chat`) | `basic` | +| `--wallet-provider ` | Wallet provider (`rainbowkit`, `thirdweb`, `none`) | `rainbowkit` | +| `-c, --contracts ` | Smart contract framework (`hardhat`, `foundry`, `none`) | `hardhat` | +| `--skip-install` | Skip automatic dependency installation | `false` | +| `-y, --yes` | Skip all prompts and use defaults | `false` | -Once your custom dApp has been created, just install dependencies, either with yarn or npm i, and run the respective script from the package.json file. +## Generated Project Structure -## Supported Templates +``` +my-celo-app/ +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ web/ # Next.js application +β”‚ └── contracts/ # Smart contracts (if selected) +β”œβ”€β”€ packages/ +β”‚ β”œβ”€β”€ ui/ # Shared UI components +β”‚ └── utils/ # Shared utilities +β”œβ”€β”€ package.json # Root package.json +β”œβ”€β”€ pnpm-workspace.yaml # PNPM workspace config +β”œβ”€β”€ turbo.json # Turborepo configuration +└── tsconfig.json # TypeScript configuration +``` -### MiniPay +## Next Steps -- Pre-built template for creating a mini-payment application. -- Seamless integration with Celo blockchain for handling payments. +After creating your project, navigate to it and install dependencies (if you didn't use `--skip-install`): -Checkout [minipay docs](/build/build-on-minipay/overview) to learn more about it. +```bash +cd my-celo-app +pnpm install # If you used --skip-install +pnpm dev # Start development server +``` -### Valora +Your project is automatically initialized with Git and includes an initial commit. -- Template designed for Valora wallet integration. -- Facilitates easy wallet connectivity and transaction management. +## Tech Stack -Checkout [valora docs](https://docs.valora.xyz/) to learn more about it. +**Generated Projects Include:** + +- Next.js 14+ with App Router +- TypeScript +- Tailwind CSS +- shadcn/ui components +- Turborepo for monorepo management +- PNPM workspaces ## Support -Join the [Celo Discord server](https://chat.celo.org). Reach out in the #general-dev channel with your questions and feedback. +Join the [Celo Discord server](https://discord.com/invite/celo). Reach out in the #build-with-celo channel with your questions and feedback. + +## Resources + +- [GitHub Repository](https://github.com/celo-org/celo-composer) diff --git a/build-on-celo/scaling-your-app.mdx b/build-on-celo/scaling-your-app.mdx new file mode 100644 index 0000000000..e155b89955 --- /dev/null +++ b/build-on-celo/scaling-your-app.mdx @@ -0,0 +1,298 @@ +--- +title: Scaling Your App +og:description: Learn best practices for scaling your Celo dApp, covering infrastructure, RPC optimization, caching strategies, and monitoring +--- + +Scaling a dApp requires careful planning across infrastructure, blockchain interactions, and cost optimization. This guide shares practical strategies from real-world experience building and scaling applications on Celo. + +## Overview + +As your dApp grows, costs can scale exponentially if not managed properly. This guide covers: + +- Infrastructure and hosting strategies +- RPC and blockchain interaction optimization +- Caching and data management +- AI/LLM cost optimization +- Testing and monitoring best practices + +## Infrastructure & Hosting + +### Server Architecture + +Start simple, but plan for growth: + +- **Early Stage**: Begin with a single server to minimize costs +- **Monitor Usage**: Track CPU, memory, and network usage closely +- **Plan Migration**: Be ready to migrate to scalable solutions like: + - **Kubernetes (K8s)**: For container orchestration and auto-scaling + - **Docker Swarm**: Lighter alternative for container management + - **Managed Services**: Consider AWS ECS, Google Cloud Run, or similar + + + Monitor your server metrics from day one. Set up alerts for CPU, memory, and + disk usage to catch scaling issues before they impact users. + + +### Image Hosting & CDN + +Avoid expensive default CDNs: + +- **Don't Use**: Vercel's default CDN (can be expensive at scale) +- **Use Instead**: Cost-effective CDN solutions like: + - Cloudflare (free tier available) + - AWS CloudFront + - BunnyCDN + - ImageKit or Cloudinary for image optimization + + + CDN costs can add up quickly with high traffic. Choose a CDN with predictable + pricing and monitor bandwidth usage. + + +### Backend Architecture + +Separate your backend from your frontend for better scaling: + +- **Avoid**: Next.js API routes for production workloads +- **Use Instead**: Separate backend service (Node.js, Python, Go, etc.) +- **Benefits**: + - Scale backend independently without increasing Vercel pricing + - Better control over resources and deployment + - Easier to implement queues, caching, and background jobs + + + Use Next.js API routes only for lightweight, user-specific operations. Move + heavy processing, RPC calls, and background jobs to a separate backend + service. + + +### Message Queues + +Implement queues wherever they make sense: + +- **Use Cases**: + + - Processing blockchain transactions + - Sending notifications + - Background data processing + - Image processing + - Email/SMS sending + +- **Queue Solutions**: + - **Redis + BullMQ**: Lightweight and fast + - **RabbitMQ**: Robust message broker + - **AWS SQS**: Managed queue service + - **Google Cloud Tasks**: Managed task queue + + + Queues prevent request timeouts, improve user experience, and allow you to + process jobs at your own pace without overwhelming your server. + + +## RPC & Blockchain Interactions + +### RPC Strategy + +RPC calls are a precious resourceβ€”treat them carefully: + +- **Choose Scalable RPC Providers**: + + - Use providers with high rate limits and good uptime + - Consider multiple RPC endpoints for redundancy + - Monitor RPC response times and error rates + +- **Early Stage Strategy**: + + - Use free RPC endpoints in the frontend + - Each user gets their own rate limits + - Reduces backend RPC load + +- **Scale Considerations**: + - RPC usage scales exponentially with user growth + - Audit all RPC calls regularly + - Remove unnecessary RPC calls + - Batch requests when possible + + + RPC costs can become your largest expense. Audit your RPC calls regularly and + optimize aggressively. A single unnecessary RPC call per user can cost + thousands at scale. + + +### Caching Strategy + +Cache API responses wherever it makes sense: + +- **Don't Always Fetch Latest Data**: + + - Cache blockchain data that doesn't change frequently + - Use appropriate TTLs (Time To Live) based on data freshness requirements + - Balance between data freshness and RPC costs + +- **Cache Layers**: + + - **In-Memory Cache**: Redis or Memcached for frequently accessed data + - **CDN Cache**: For static or semi-static content + - **Application Cache**: Cache responses in your application layer + +- **What to Cache**: + - Token balances (with short TTL) + - Token metadata + - Historical transaction data + - Price data (with appropriate TTL) + - Contract ABIs + + + Most blockchain data doesn't need to be real-time. Cache aggressively and only + fetch fresh data when absolutely necessary. + + +### Indexer Selection + +If you need an indexer, choose cost-effective options: + +- **Recommended**: Use affordable indexers like [thirdweb Insight](https://portal.thirdweb.com/insights) +- **Consider**: + - The Graph (decentralized indexing) + - Alchemy (if already using their RPC) + - Custom indexer (if you have specific needs) + + + Indexers can significantly reduce RPC calls by providing pre-indexed + blockchain data. Choose one that fits your budget and requirements. + + +## AI & LLM Optimization + +### Model Selection + +Optimize LLM costs by choosing the right model for each task: + +- **Small Tasks**: Use cheaper models (e.g., GPT-3.5-turbo, Claude Haiku) +- **Complex Tasks**: Reserve expensive models (e.g., GPT-4, Claude Opus) only when necessary +- **Consider Alternatives**: + - Open-source models (Llama, Mistral) + - Specialized models for specific tasks + + + Most tasks don't require the most powerful models. Use cheaper models for + simple tasks and save expensive models for complex reasoning. + + +### AI SDK + +Use AI SDKs for better developer experience: + +- **Benefits**: + + - Better error handling + - Built-in retry logic + - Streaming support + - Cost tracking + - Easier model switching + +- **Recommended SDKs**: + - [Vercel AI SDK](https://sdk.vercel.ai/) for JavaScript/TypeScript + - [LangChain](https://www.langchain.com/) for Python + - [LlamaIndex](https://www.llamaindex.ai/) for data indexing + +## Testing & Monitoring + +### Testing Strategy + +Comprehensive testing prevents costly production issues: + +- **Unit Tests**: Test individual functions and components +- **Integration Tests**: Test how different parts work together +- **E2E Tests**: Test complete user flows +- **Load Tests**: Test your application under expected load +- **Reburst Tests**: Test how your system handles sudden traffic spikes + + + Don't skip testing. Production bugs are expensive to fix and can damage user + trust. Invest in a solid testing strategy from the start. + + +### Error Monitoring + +Use Sentry to audit error rates: + +- **Benefits**: + + - Track error rates over time + - Get alerts for error spikes + - Debug production issues quickly + - Monitor performance issues + +- **Setup**: + - Install Sentry SDK in your application + - Configure error tracking + - Set up alerts for critical errors + - Monitor error trends + + + Sentry helps you catch and fix errors before they impact too many users. Set + up error monitoring from day one. + + +### Analytics & Logging + +Use Grafana for analytics and logs: + +- **Metrics to Track**: + + - Request rates and response times + - Error rates + - RPC call counts and costs + - Server resource usage + - User activity metrics + +- **Logging**: + + - Centralized logging with Grafana Loki or similar + - Structured logging (JSON format) + - Log retention policies + - Search and query capabilities + +- **Dashboards**: + - Create dashboards for key metrics + - Set up alerts for anomalies + - Monitor trends over time + + + Good observability helps you catch issues early and make data-driven decisions + about scaling. Invest in monitoring from the start. + + +## Best Practices Summary + +### Cost Optimization Checklist + +- [ ] Use cost-effective CDNs instead of default options +- [ ] Separate backend from frontend for independent scaling +- [ ] Implement message queues for background processing +- [ ] Cache API responses aggressively +- [ ] Audit and optimize RPC calls regularly +- [ ] Use free RPC endpoints in frontend during early stages +- [ ] Choose affordable indexers when needed +- [ ] Use cheaper LLM models for simple tasks +- [ ] Monitor all costs and set up alerts + +### Scaling Readiness Checklist + +- [ ] Monitor server metrics (CPU, memory, disk) +- [ ] Have a plan to migrate to scalable infrastructure (K8s, Docker Swarm) +- [ ] Implement comprehensive testing (unit, integration, E2E, load) +- [ ] Set up error monitoring (Sentry) +- [ ] Configure analytics and logging (Grafana) +- [ ] Document your architecture and scaling plan +- [ ] Set up alerts for critical metrics + +## Additional Resources + +- [Celo Documentation](/build-on-celo) - Explore Celo development resources +- [Launch Checklist](/build-on-celo/launch-checklist) - Pre-launch preparation guide +- [thirdweb Insight](https://portal.thirdweb.com/insights) - Affordable blockchain indexer +- [Vercel AI SDK](https://sdk.vercel.ai/) - AI SDK for JavaScript/TypeScript +- [Sentry Documentation](https://docs.sentry.io/) - Error monitoring and performance tracking +- [Grafana Documentation](https://grafana.com/docs/) - Analytics and observability platform diff --git a/docs.json b/docs.json index 081c224e5c..5d4f3dd0c3 100644 --- a/docs.json +++ b/docs.json @@ -113,6 +113,7 @@ "build-on-celo/quickstart", "build-on-celo/cel2-architecture", "build-on-celo/launch-checklist", + "build-on-celo/scaling-your-app", "build-on-celo/fund-your-project", "build-on-celo/nightfall" ] @@ -139,7 +140,7 @@ "pages": [ "build-on-celo/build-with-ai/examples/ai-memecoins", "build-on-celo/build-with-ai/examples/building_with_goat", - "build-on-celo/build-with-ai/examples/build-with-nebula" + "build-on-celo/build-with-ai/examples/build-with-thirdweb-ai" ] }, { @@ -557,9 +558,7 @@ }, { "group": "Nodes", - "pages": [ - "legacy/node/run-mainnet" - ] + "pages": ["legacy/node/run-mainnet"] }, { "group": "Validator", diff --git a/img/build/celo-programs.png b/img/build/celo-programs.png new file mode 100644 index 0000000000..06b66887e8 Binary files /dev/null and b/img/build/celo-programs.png differ