Skip to content
Get packs

Guide · Open source

How to use Canopy: build, run and test the Go implementation

Updated · written with AI from the project's own documentation and checked against our catalogue data

Canopy is an open-source blockchain protocol written in Go. This guide walks through what the project is, how to clone and build it, how to start a Docker Localnet and how to run its unit tests. It is written for developers who want to explore protocol internals, not for end users looking for a finished app.

Canopycanopy-network/canopy · ★ 14.7k · MIT

Quick start

  1. 1Check prerequisites. Install Go (the README references v1.21), make, and Docker if you want the Localnet.
  2. 2Clone the repository. Run git clone https://github.com/canopy-network/canopy to get the source.
  3. 3Build the binary. Run make build/canopy-full from the repository root.
  4. 4Start the node. Run canopy start to launch the built binary.
  5. 5Build the Docker image. Run make docker/build to build the Localnet image.
  6. 6Start the Localnet. Run make docker/up-fast, then make docker/logs to watch output.
  7. 7Run tests. Run make test to execute the unit tests.

What is Canopy?

According to its README, Canopy is a recursive framework for building blockchains, where chains help bootstrap new chains. It is also the seed chain that started that cycle.

It is an Ethereum-RPC compatible layer 1 for native transfers. The README describes the project as being in alphanet status, so treat it as experimental.

  • Recursive framework: chains bootstrap each other into independence.
  • Seed chain: the first chain in that cycle.
  • Ethereum-RPC compatible layer 1 for native transfers.

Check the prerequisites before you start

The README lists three tools: Go (its badge references v1.21), Docker for the containerized Localnet, and make. Docker is only needed if you want the Localnet path.

The README's platform badge lists linux and macos. It does not give detailed setup guidance for other systems.

  • Go (the README badge references v1.21)
  • Docker (for the containerized Localnet)
  • make

Clone and build the Canopy binary

Clone the repository from GitHub, then build the full binary with make. Run these commands from the repository root.

After the build, the README shows running the binary with canopy start.

git clone https://github.com/canopy-network/canopy make build/canopy-full canopy start

Run a Localnet with Docker

To run a Canopy Localnet in a containerized environment, build the Docker image first and then start it. The README also lists a faster variant and a combined command.

The logs target shows output from the running Localnet.

  • make docker/build builds the image.
  • make docker/up-fast starts it using the faster option.
  • make docker/up starts it, and make docker/logs shows logs.
  • make docker/up && make docker/logs does both in one line.
make docker/build make docker/up-fast make docker/logs

Run the unit tests

The README says unit tests use the Go testing tools and are run through make.

make test

Understand the main modules

The README points to documentation for each core module. Reading these is the best way to find your way around the code.

  • Controller: coordinates communication between the major parts of the chain.
  • Finite State Machine (FSM): defines which transactions are valid and how state changes from block to block.
  • Byzantine Fault Tolerant (BFT) consensus: lets the network agree on blocks even if some nodes are unreliable or malicious.
  • Peer-to-peer networking: encrypted node-to-node communication without a central server.
  • Persistence: stores state, indexes past transactions and verifies data.

Connect Ethereum tools through the RPC layer

The README says Canopy can plug into existing Ethereum exchange, wallet and indexer tooling, including MetaMask. It says to use the /v1/eth endpoint as a custom Ethereum RPC. Compatibility notes are in the eth-spec document and the full RPC specification is linked from the README.

The README does not say how well any specific tool works, so test your own workflow before relying on it.

  • Use the /v1/eth endpoint as a custom Ethereum RPC.
  • Read the eth-spec notes in fsm/ethereum.md for compatibility details.
  • Read the full RPC specification in cmd/rpc/README.md.

What people use it for

  • Reading the Go source to learn how a BFT blockchain is structured, module by module.
  • Running a local Localnet in Docker to experiment with the protocol.
  • Checking whether Ethereum wallet or indexer tools can point at the /v1/eth endpoint.
  • Studying recursive chain bootstrapping as a research topic.

Frequently asked questions

Is Canopy free to use?

Canopy is released under the MIT licence, according to the README badge. That licence allows you to use, modify and redistribute the code under its terms. Read the licence file in the repository for the full text.

What do I need to install Canopy?

The README lists Go (its badge references v1.21), Docker for the containerized Localnet, and make. You install it by cloning the repository and building it, not from a packaged installer.

Is Canopy production ready?

No. The README marks the project as alphanet status, so it is not suitable for production users who need a stable network.

How do I run Canopy with Docker?

Run make docker/build, then make docker/up-fast or make docker/up, and make docker/logs to view output. The README describes these commands for a containerized Localnet.

Can I use MetaMask with Canopy?

The README says Canopy is Ethereum-RPC compatible and that tools such as MetaMask may connect through the /v1/eth endpoint. Check the eth-spec notes for compatibility details before relying on it.

How does Canopy compare to Cosmos SDK or Substrate?

The README does not compare Canopy with other frameworks. Projects often mentioned alongside it include Cosmos SDK, Substrate, go-ethereum and Polkadot SDK, so review each one's docs against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Canopy suits Go developers who want to study a BFT blockchain protocol, or teams evaluating an Ethereum-RPC compatible layer 1 for experimentation. It is not a good fit for end users, for anyone needing a stable production network, or for readers who need detailed setup instructions, since the README is brief.

Install options & downloads