# celo-blockchain is a Go Celo client in maintenance mode, not a starting point

> celo-blockchain is the official Go implementation of the Celo blockchain, forked from go-ethereum and still receiving the occasional critical fix. The README tells new projects to migrate to the op-geth implementation, so this repository is best read as the historical node client and as a reference for how the Celo-specific pieces are wired.

**celo-org/celo-blockchain** — Previous official repository for the golang Celo Blockchain, for current see op-geth

- Repository: https://github.com/celo-org/celo-blockchain
- Website: https://celo.org
- Stars: 627 · Forks: 225
- Language: Go
- License: LGPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/celo-org-celo-blockchain

## The repository tells you not to build on it

The first thing in the README is a notice marked important, and it sets the frame for everything else. celo-blockchain is in maintenance mode and will only be updated for critical issues. Do not use it for new projects, and migrate to the op-geth implementation, which lives in the celo-org organisation as a separate repository.

Underneath that warning is a substantial codebase. This is the official Go implementation of the Celo blockchain, based on the official Go implementation of the Ethereum protocol, so the Celo client is a fork of go-ethereum with the consensus and economics changes layered on top. The README states that most functionality of this client is similar to go-ethereum, also known as geth, from which it was forked, and suggests the geth wiki for anything the Celo specific documentation does not cover.

That inheritance is the practical reason to read this repository even if you will not run it. Every part of the node plumbing, the RPC surface, the account handling and the tooling around them is geth's, and the Celo differences sit on top.

For an engineer evaluating the project, the honest summary is that this is the previous official repository for the Celo blockchain, in Go, with a documented successor. The repository is not archived and the last push was on 2026-10-09, but maintenance mode is a stronger constraint than that date alone suggests, since it tells you the shape of future changes rather than just their timing.

## Building geth needs Go and a C compiler

The build section is short because it inherits geth's. Building requires both Go, with a minimum version of 1.19, and a C compiler, and the README tells you to install them with your favourite package manager. Once the dependencies are in place, the client is built with:

```shell
make geth
```

The alternative target builds the full suite of utilities rather than just the client:

```shell
make all
```

The Makefile carries the details. GOBIN is set to ./build/bin, and the geth target runs the CI script through go run to install the cmd/geth package, then echoes a message telling you to run the binary from that directory.

For anyone who has built go-ethereum before, the familiarity is the point. There is no separate toolchain, no bespoke bootstrap and no vendored dependency tree to learn. The go.mod file declares module github.com/celo-org/celo-blockchain with go 1.19, and the dependency list is the geth dependency list with the Celo specific packages added, including celo-bls-go and the gnark-crypto library.

The Dockerfile follows the same pattern. It builds in a golang:1.19-bookworm image and installs build-essential, git and the platform headers before running make geth, with a separate arm64 path that installs musl-dev and calls make geth-musl instead.

## The executables in cmd and the jobs they do

The client ships several wrappers and executables found in the cmd directory, and the README documents each one in a table. The distinction between them matters when you are deciding what to run on a machine.

geth is the main client and the entry point into the Celo network. It can run as a full node, which is the default, an archive node that retains all historical state, a light node that retrieves data live, or a lightest node that retrieves the minimum number of block headers needed to verify the existing validator set. It also serves as a gateway for other processes through JSON RPC endpoints exposed over HTTP, WebSocket and IPC transports.

bootnode is the stripped down one. It takes part only in the network node discovery protocol and runs none of the higher level application protocols, which makes it a lightweight bootstrap node for finding peers in a private network.

The rest are developer tools. abigen generates compile-time type-safe Go packages from contract definitions and accepts plain Ethereum contract ABIs, with expanded functionality when contract bytecode is also available, and it accepts Solidity source files too. evm runs bytecode snippets within a configurable environment and execution mode for fine-grained debugging of EVM opcodes. rlpdump converts binary RLP dumps into a human friendly hierarchical representation, and RLP is the data encoding the Celo protocol uses on the network and in consensus. gethrpctest supports the ethereum/rpc-test suite that validates conformance to the Ethereum JSON RPC specification.

The split tells you the shape of the toolset: one network client, one discovery helper, four utilities.

## Running a full node with geth console

By default the Celo client connects to Mainnet, and the README walks through the common parameter combinations. The simplest one creates a full node that syncs with the Celo network:

```shell
$ geth console
```

That command starts geth in full sync mode, downloading and executing all historical block information, and starts the built-in interactive JavaScript console.

The other route to a running node is the prebuilt Docker image, published at us.gcr.io/celo-org/geth and described in the README as available for immediate use. The getting-started guide at docs.celo.org is the reference for choosing a network and running a node connected to the Celo network with that image.

The Dockerfile gives the network shape of the container. The final stage is debian:bookworm-slim with the built binary copied to /usr/local/bin, and the ports exposed are:

```dockerfile
EXPOSE 8545 8546 30303 30303/udp
```

Those are the JSON RPC HTTP port, the WebSocket port and the peer-to-peer discovery port in both TCP and UDP form. The entrypoint is a shell script that runs the client, and the image carries a version file written from a commit SHA build argument, so the image itself records which build it contains.

The README is explicit that going through all possible command line flags is out of scope, and points at geth --help for that, with the Ethereum CLI Wiki page as the reference for command line options.

## make prepare and the celo-monorepo contract checkout

Running the tests has a prerequisite that is easy to miss. You need to run make prepare first, because without it certain tests fail. That target has two sub rules, and the interesting one is prepare-system-contracts.

It shallow checks out the celo-monorepo under a path relative to the project root, at the commit defined in the file monorepo_commit, and then compiles the system contracts for use in full network tests. The compiled contracts are copied from the monorepo into compiled-system-contracts. If you edit the system contracts source or the monorepo_commit file, running the rule again re-checks out the monorepo, recompiles and copies them into place.

Two constraints are documented. monorepo_commit may contain a commit hash or a tag, and branch names are forbidden, so the checkout is pinned to something immutable. And if you want a different checkout location, or several checkouts at different versions, you set the MONOREPO_PATH variable in the make command:

```shell
make prepare-system-contracts MONOREPO_PATH=../alt-monorepo
```

The README adds a warning about how that variable is used: MONOREPO_PATH should not point at checkouts other than those made by the prepare-system-contracts rule, and those checkouts should not be modified manually apart from changing the contract source.

The reason for the sibling checkout layout is explained in a comment in the Makefile. The monorepo is checked out as a sibling of the celo-blockchain directory because the number of files in the monorepo interferes with tooling such as gopls, which becomes very slow. The second sub rule, prepare-ethersjs-project, installs dependencies for the ethersjs-api-check TypeScript project.

## Mobile client builds apply a patch to go.mod

Two Makefile commands exist for the mobile clients, one for each platform:

```shell
make ios
```

```shell
make android
```

The android command is the one with a caveat, and the README spells it out. It applies a git patch, patches/mobileLibsForBuild.patch, which is required to swap some libraries from the go.mod so the client works. It installs those libraries, builds the client, and then reverts the patch.

That sequence is the interesting part. A build that mutates the dependency manifest and then restores it is a build with hidden inputs, and it means the go.mod in your working tree is not what the compiler actually saw during the android build. Anyone debugging a mobile build failure needs to look at the patch rather than only at the manifest.

The Makefile also carries the NDK settings the android target relies on, with NDK_VERSION defaulting to android-ndk-r19c and ANDROID_NDK pointing at an ndk_bundle directory under the project path.

Beyond the build itself, the repository layout shows how broad the client is. The top level carries consensus, core, crypto, eth, ethclient, ethdb, miner, node, p2p, params, accounts, console, light, les, metrics, event, common and internal directories, plus a graphql directory, a mycelo directory, an e2e_test directory, contracts, and the oss-fuzz.sh script. This is not a small client, and the mobile commands are the visible edge of that scope.

## op-geth is the successor, and the difference is where the code lives

The alternative to this client is not another blockchain implementation in the abstract. It is a specific repository: op-geth, in the same celo-org organisation, which the README names as the place to migrate to for new projects.

The difference in approach, as far as these files describe it, is architectural rather than conceptual. This repository is a fork of the Go implementation of the Ethereum protocol, so the Celo behaviour is carried by a geth codebase with Celo changes merged in, and the Celo specific system contracts are compiled from the separate celo-monorepo at test time. op-geth is presented as the implementation to move to, which implies a different arrangement of the protocol code rather than a patch release of the same arrangement.

The second alternative is documentation rather than code. Since most functionality is similar to go-ethereum, the README explicitly suggests searching the geth wiki when the Celo documentation does not answer a question. For anyone using this client, that is the practical route to understanding RPC behaviour, mining options and account handling, and it works because the fork inherits that behaviour.

Both alternatives point the same way for a new build. The geth wiki answers questions about the inherited behaviour, and op-geth is where new work belongs. This repository remains the place to look when you need to know what the 1.8 line actually did.

## Licence, versions and what an upgrade costs

The repository is licensed under LGPL-3.0, and the root carries both COPYING and COPYING.LESSER, which is the usual pairing for the LGPL text and its additional permissions. For a node client that operators may modify and redistribute in modified form, that licence lets you keep changes to the library portions under the LGPL while combining the work with your own code.

The version story is where the maintenance mode shows up in practice. The recent releases are v1.8.9 on 2025-03-05, whose release title is Thank you L1, see you on Ethereum, v1.8.8 on 2025-02-06 and v1.8.7 on 2024-12-06. The release title is itself a statement about the direction of the project, and it is not the language of a line that is shipping features.

For an operator already running this client, the upgrade cost is low in effort and higher in planning. The Go floor is 1.19 for the build, the Docker image removes that requirement entirely, and the RPC and JSON RPC surface is inherited rather than redesigned, so an existing configuration and tooling tend to carry over.

The repository is not archived and the last push was on 2026-10-09, so there are still commits. That date should not be read as a promise of feature work, since the README limits updates to critical issues and points new projects elsewhere. Treat the client as a dependency you patch, not a platform you build on.

## Conclusion

celo-blockchain still makes sense for an operator who already runs this client, who needs to read its source to understand Celo specific behaviour, or who needs the archived 1.8 line for a legacy deployment, and the Docker image makes that deployment possible without a Go toolchain. It is the wrong foundation for anything new, which the README says outright, and for teams that need protocol work rather than critical fixes. Verify first that the version you deploy matches the v1.8.9 release and that your operating system has Go 1.19 and a C compiler available, then confirm whether op-geth has already replaced the client in your deployment tooling before you spend time on a build.

## FAQ

### Is celo-blockchain still maintained, and what should new projects use instead?

The README states that celo-blockchain is in maintenance mode and will only be updated for critical issues, and it tells you not to use it for new projects and to migrate to the op-geth implementation. The repository is not archived and the last push was on 2026-10-09.

### How do I build the Celo geth client from source?

Install Go 1.19 or newer and a C compiler, then run make geth for the client or make all for the full suite of utilities. The binary is placed under the build/bin directory that the Makefile sets as GOBIN.

### Why do the Celo blockchain tests fail unless I run make prepare?

The prepare target runs two sub rules before tests, and the system contracts rule shallow checks out the celo-monorepo at the commit named in monorepo_commit, compiles the system contracts and copies them into compiled-system-contracts. Without it certain tests fail.

### How do I run a Celo full node with the Docker image?

Prebuilt images are published at us.gcr.io/celo-org/geth, and the docs.celo.org getting-started guide covers choosing a network and running a node with that image. The container exposes ports 8545 and 8546 for JSON RPC and 30303 for peer discovery.

## Sources

- [celo-org/celo-blockchain on GitHub](https://github.com/celo-org/celo-blockchain)
- [License: LGPL-3.0](https://github.com/celo-org/celo-blockchain/blob/master/LICENSE)
- [Project website](https://celo.org)
- [README](https://github.com/celo-org/celo-blockchain/blob/master/README.md)
- [Releases](https://github.com/celo-org/celo-blockchain/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/celo-org-celo-blockchain