Celo Composer

A starter pack to get started with building dapps on Celo.

View Demo View Github

About The Project

Celo Composer allows you to quickly build, deploy, and iterate on decentralized applications using Celo. It provides a number of frameworks, examples, and Celo specific functionality to help you get started with your next dApp.

Built With

Celo Composer is built on Celo to make it simple to build dApps using a variety of front-end frameworks.

Getting Started

To build your dApp, you’ll need to install the dependencies, create a new project, and run the following commands:

Prerequisites

  • Node (v12), NVM
  • Yarn
  • Git

Installation

  1. Clone the repo
git clone https://github.com/celo-org/celo-composer
  1. Set the correct node version (several Celo packages require using node version 12.x):

cd celo-composer
nvm use # uses node v12 as specified in .nvmrc
  1. Get testnet funds and install dependencies.

cd packages/hardhat
yarn install
npx hardhat create-account # prints a private key + account
  1. Paste the private key in packages/hardhat/.env and fund the account from the faucet here. Once the account is funded, deploy the contracts with:
yarn deploy
  1. In another terminal, start the frontend (React app using Next.js)

Read more details about the hardhat package here.

cd packages/react-app
yarn install
yarn dev
  1. Testing on Mobile
  • Get the Alfajores Testnet mobile wallet for Android and iOS here.
  • Serve your React app to your mobile device for testing via a tunnel. Next.js defaults to serving your app on port 3000, so point the tunnel there:
npx localtunnel --port 3000

Review

  • Edit smart contracts in packages/hardhat/contracts.
  • Edit deployment scripts in packages/hardhat/deploy.
  • Edit frontend in packages/react-app/pages/index.tsx.
  • Open http://localhost:3000 to see the app.

You can run yarn deploy --reset to force re-deploy your contracts to your local development chain.

Deploy Your DApp

This repo comes with a netlify.toml file that makes it easy to deploy your front end using Netlify. The toml file contains instructions for Netlify to build and serve the site, so all you need to do is create an account and connect your GitHub repo to Netlify.

Developing with local devchain

You can import account account keys for the local development chain into Metamask. To print the private keys of the local chain accounts cd /packages/hardhat and run

npx hardhat devchain-keys

If you are working on a local development blockchain, you may see errors about the tx doesn't have the correct nonce. This is because wallets often cache the account nonce to reduce the number of RPC calls and can get out of sync when you restart your development chain. You can reset the account nonce in Metamask by going to Settings > Advanced > Reset Account. This will clear the tx history and force Metamask to query the appropriate nonce from your development chain.

Note: You can get a local copy of mainnet by forking with Ganache. Learn more about forking mainnet with Ganache here.

React library choices

The example UI in packages/react-app uses the Next.js React framework, and use-contractkit Celo library to get you started with building a responsive, web3 DApp quickly. Feel free to use it as a reference and use whatever web3 packages you are familiar with.

The Graph

Using the Graph is not a requirement for building a web3 application. It is more of a convenience for when your application is reading a lot of data from a blockchain.

Its suggested to only adding support for the Graph when you need it, avoid premature optimization.

The /packages/subgraphs directory includes an example subgraph for reading data from the example Storage.sol contract. The Graph is a blockchain data indexing service that makes it easier to read data from EVM blockchains. You can read more about how the Graph works and how to use it in the README here.

? Learning Solidity

? Read the docs: https://docs.soliditylang.org

? Learn the Solidity globals and units

Support

Join the Celo Discord server at https://chat.celo.org. Reach out on the dedicated repo channel here.

Roadmap

See the open issues for a full list of proposed features (and known issues).

Contributing

As a contributor, you can add your own dApp to this repository and include it as a tab for others to access. Follow the steps below and reference existing files for additional details to help you get started.

If you decide to try this out and find something confusing, consider opening an pull request to make things more clear for the next developer that comes through. If you improve the user interface or create new components that you think might be useful for other developers, consider opening a PR.

We will happily compensate you for contributions. Anywhere between 5 and 50 cUSD (or more) depending on the work. This is dependent on the work that is done and is ultimately up to the discretion of the Celo Foundation developer relations team.

You can view the associated bounty on Gitcoin here.

How to Contribute a new dApp

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag “enhancement”. Don’t forget to give the project a star! Thanks again!

  • Create a new smart contract in packages/hardhat/contracts.
  • Add a new deployment script within packages/hardhat/deploy/00-deploy.js using the name of your smart contract.
  • Deploy your Smart Contract from within packages/hardhat using yarn deploy
  • Add a new component named ContractName.tsx to packages/react-app/components to create front end of your dApp.
  • Export component using packages/react-app/components/index.tsx using export * from './ContractName
  • Import component to packages/react-app/pages/index.tsx by adding contract to import { ContractName } from "@/components";
  • Add tab within tabs component in packages/react-app/pages/index.tsx and replace # with tab number.
<Tab label="Contract Label" {...a11yProps(#)} />
  • Add tab panel to page replacing # with tab number and ContractName with your smart contract name

<TabPanel value={value} index={#}>
    <GreeterContract contractData={contracts?.ContractName} />
</TabPanel>

You should now be able to view your new dApp from http://localhost:3000.

Troubleshooting

For M1 Mac developers who have installed nvm using brew, the server may crash. To resolve this issue, take a look here at this solution

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Acknowledgments

GitHub

View Github