celo-monorepo: The Core Contracts Behind the Celo Blockchain

The monorepo that shrank to one package

celo-monorepo is described as the official repository for the core projects of the Celo platform, and its own readme says most Celo projects have moved to dedicated repositories. The list of departures is explicit. The Celo Blockchain Execution Client lives in celo-org/op-geth, developer tooling in celo-org/developer-tooling, Helm charts in celo-org/charts, SocialConnect in celo-org/social-connect, the Valora Wallet under the valora-inc organisation, and the Mento Protocol in its own repository. What remains here is the core contracts for the Celo blockchain. That is a significant reorganisation of a blockchain monorepo, and it means the name is now slightly misleading: this is a contracts repository with a monorepo's build system still around it.

Building the protocol package with yarn

The getting started section is four commands, and they are all yarn.

git clone https://github.com/celo-org/celo-monorepo.git
cd celo-monorepo
yarn
yarn build --ignore docs

The `--ignore docs` flag on the build is the interesting detail, since it implies that a documentation step exists in the build graph and that you can skip it when you only need the compiled contracts. The root package.json confirms the shape: it is private, the build and test scripts delegate into `packages/protocol` with `yarn --cwd packages/protocol`, and the workspaces section declares `packages/*` with a `nohoist` entry for `**/openzeppelin-solidity`. That nohoist rule exists because a hoisted OpenZeppelin copy can resolve to the wrong version for a Solidity package, and Solidity projects are sensitive to that in a way most JavaScript ones are not.

A lint rule that keeps a warning out of the tree

One script in the root package.json is worth reading closely, because it encodes a governance practice rather than a technical need. The lint script runs the protocol package's own lint and then runs a second check called `lint:do-not-merge`, whose body is a negated grep over the repository for the pattern `DO NOT MERGE`, written either with spaces or with a joining character. The effect is that the build fails if any file anywhere in the tree contains that marker, which means an emergency or rejected change cannot be merged while leaving the marker in place. It is a cheap, language-agnostic way to enforce a policy that would otherwise depend on reviewers noticing a comment. The same file also carries a licence check script that lists production dependencies and reports any that are GPL, with a message telling the user to look up the offending package.

Keys, mnemonics and the environment files in the tree

The repository root contains a set of files that reveal what running this code involves. There are `.env` variants per network: `.env.alfajores`, `.env.rc1`, `.env.staging`, and a `.env` for the default, plus encrypted mnemonic files named `.env.mnemonic.enc`, `.env.mnemonic.alfajores.enc`, `.env.mnemonic.baklava.enc` and `.env.mnemonic.mainnet.enc`. A `secrets/` directory and a `developer_key_publishing.md` file sit alongside them. The package scripts give the workflow: `keys:encrypt` and `keys:decrypt` both run a shell script called `scripts/key_placer.sh`, so the mnemonic files are encrypted at rest and decrypted locally when needed. The presence of a developer key publishing document suggests the procedure for sharing or rotating these keys is written down rather than folklore.

Network names as separate configuration targets

The environment file names double as a map of the test networks the project targets, since Alfajores, Baklava and RC1 each appear as a distinct variant. That separation is the pattern: a single protocol codebase is run against several networks, and the differences between them are configuration rather than code. The repository supports this with a `dockerfiles/` directory and a `scripts/` directory, and the top level carries `.nvmrc` to pin the Node version, a `jest.config.js` for the test runner, `.eslintrc.js` and `.prettierrc.js` for linting and formatting, and `.husky/` for git hooks installed by a `prepare` script. The prettier script covers TypeScript, JavaScript and Solidity in one pass, which is the practical way to keep contract source and the TypeScript tooling around it formatted consistently.

Contract releases are versioned separately from the code

The release record shows that the contracts get their own version line rather than tracking the repository's commit history. Three tags are visible: core-contracts.v16 on 2026-04-14, core-contracts.v15 on 2026-02-10 and core-contracts.v14 on 2026-02-10, the last two on the same day. The naming convention matters for anyone integrating with Celo, because the deployed address of a contract is tied to a release of that release line rather than to a branch. The repository is not archived and the last push was on 2026-10-19, so the contracts continue to change, and the contract release tags are how you pin to a specific audited state of them. The protocol package also sits under a `packages/` directory alongside other workspace members, so the contracts are one package in a wider TypeScript and Solidity workspace.

What this repository is not for

The scope is narrow enough that it is worth being explicit about what a newcomer will not find here. Running a Celo node is the job of the execution client, which moved to celo-org/op-geth, and the developer tooling for building applications moved to celo-org/developer-tooling, with the Helm charts for deployment in celo-org/charts. The mobile wallet is the Valora app under the valora-inc organisation, and the stablecoin protocol referenced as Mento Protocol has its own repository. For a full list of what exists, the readme points at the Celo GitHub organisation. That reorganisation is a reasonable structure for a project that has outgrown a single repository, but it means a task like adding a feature to the chain now spans several codebases rather than one clone.

Licensing, community and where the answers live

The licence is Apache-2.0, and there is a wrinkle in the root package manifest, where the licence field reads as a reference to the licences in the sub-packages rather than naming a single file, so the terms differ per package and the top-level LICENSE file does not settle it for every directory. On documentation, the readme points to the Celo Docs site and a Developer Guide, and the community table lists the website, X, Discord, docs, blog, forum, YouTube, Reddit and GitHub Discussions, which is a lot of surface area for a repository that now holds one package. The mission statement in the readme is to build a regenerative digital economy that creates conditions of prosperity for all, which is the framing the project uses for its financial inclusion work rather than a technical statement about the contracts.

Editorial conclusion

celo-monorepo fits a contributor changing Celo's core contracts, or a dapp team that needs to read the exact contract source behind a given release rather than a summary of it. It is the wrong tool for running a node, since the execution client lives in a separate repository, and the wrong tool for general application development, since the developer tooling has moved out as well. Before you touch the protocol package, run yarn build --ignore docs and the test suite, then confirm which contract release tag you are working against.

Frequently asked questions

Official sources

1. celo-org/celo-monorepo on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases