RepoPilot

canopy-network/canopy

The official go implementation of the Canopy Network protocol

Mixed

Mixed signals — read the receipts

MixedDependency

no tests detected; no CI workflows detected

MixedFork & modify

no tests detected; no CI workflows detected…

HealthyLearn from

Documented and popular — useful reference codebase to read through.

MixedDeploy as-is

Scorecard "Branch-Protection" is 0/10; no CI workflows detected…

  • ⚠No CI workflows detected
  • ⚠No test directory detected
  • ⚠Scorecard: default branch unprotected (0/10)
  • ✓Last commit 2d ago
  • ✓6 active contributors
  • ✓Distributed ownership (top contributor 46% of recent commits)
  • ✓MIT licensed

What would improve this?

  • •Use as dependency Mixed to Healthy if: add a test suite
  • •Fork & modify Mixed to Healthy if: add a test suite
  • •Deploy as-is Mixed to Healthy if: bring "Branch-Protection" to ≥3/10 (see scorecard report); wire up GitHub Actions or equivalent

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard

Informational only. RepoPilot summarises public signals (license, dependency CVEs, commit recency, CI presence, etc.) at the time of analysis. Signals can be incomplete or stale. Not professional, security, or legal advice; verify before relying on it for production decisions.

Want this for your own repo?

Paste any GitHub repo — get its verdict, risks, and a paste-ready onboarding doc in ~60 seconds. Free, no sign-up.

Embed the "Great to learn from" badge

Paste into your README — live-updates from the latest cached analysis.

RepoPilot: Great to learn from
[![RepoPilot: Great to learn from](https://repopilot.app/api/badge/canopy-network/canopy?axis=learn)](https://repopilot.app/r/canopy-network/canopy)

Paste at the top of your README.md — renders inline like a shields.io badge.

▸Preview social card

This card auto-renders when someone shares https://repopilot.app/r/canopy-network/canopy on X, Slack, or LinkedIn.

Ask AI about canopy-network/canopy

Grounded in the actual source code. Pick a starter question or write your own.

What does this repo do, in one paragraph?How would I get started using it?What are the main alternatives?Show me the entry point.
Or write your own question

Onboarding doc

Onboarding: canopy-network/canopy

Generated by RepoPilot · 2026-07-20 · Source

Verdict

Mixed — Mixed signals — read the receipts

  • Last commit 2d ago
  • 6 active contributors
  • Distributed ownership (top contributor 46% of recent commits)
  • MIT licensed
  • ⚠ No CI workflows detected
  • ⚠ No test directory detected
  • ⚠ Scorecard: default branch unprotected (0/10)

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard

TL;DR

Canopy is the official Go implementation of the Canopy Network Protocol—a Layer 1 blockchain with a recursive architecture where chains bootstrap each other into independence. It's Ethereum-RPC compatible, meaning it can plug into existing MetaMask, exchange, and indexer tooling while implementing Byzantine Fault Tolerant consensus and peer-to-peer networking for a decentralized launchpad platform. Monorepo with core blockchain logic in lib/ (block.go, consensus.go, dex.go, mempool.go), cryptographic primitives in lib/crypto/, protocol buffers in .pb.go files, major subsystems in sibling directories (controller/, fsm/, bft/, p2p/, store/), and a Next.js frontend explorer under a separate directory. The Go code is organized by responsibility: consensus, storage, networking, and state machine are cleanly separated.

LLM-derived; treat as a starting point, not verified fact.

Who it's for

Go developers building or validating blockchain nodes on the Canopy Network, protocol engineers implementing consensus mechanisms, and infrastructure teams deploying decentralized chain infrastructure. Contributors should understand consensus protocols, distributed systems, and blockchain architecture.

LLM-derived; treat as a starting point, not verified fact.

Maturity & risk

Alpha-stage (alphanet badge visible in README). The codebase is substantial (~3.9M LOC in Go) with comprehensive test files (_test.go suffixes throughout lib/ and crypto/) and Docker Compose for testing infrastructure, suggesting active development but pre-production stability. Likely 1-2 years old based on typical blockchain protocol maturity at this stage.

The codebase is young (alphanet status indicates pre-mainnet), relies on cryptographic primitives (VDF, BLS, Class Group) that require extreme scrutiny, and the recursive chain-bootstrapping architecture is novel and not battle-tested at scale. Dependencies on protobuf codegen (.pb.go files) and multiple crypto libraries increase surface area; no visible security audit badges. Single protocol maintainer risk typical of blockchain projects at this stage.

LLM-derived; treat as a starting point, not verified fact.

Active areas of work

Active development on core protocol: consensus mechanisms (lib/consensus.go, lib/certificate.go), block production (lib/block.go), decentralized exchange (lib/dex.go), and peer management (lib/peer.go) are actively tested. The repo includes a working Ethereum-RPC compatibility layer and FSM (Finite State Machine) for state transitions. No specific PR or milestone data visible, but file timestamps and test coverage suggest continuous refinement.

LLM-derived; treat as a starting point, not verified fact.

Get running

git clone https://github.com/canopy-network/canopy.git
cd canopy
go mod download
go test ./lib/... -v

For the explorer frontend: cd explorer && npm install && npm run dev. For running a node locally, check cmd/rpc/README.md and controller/README.md for specific node startup commands.

Daily commands: Go node: go run ./cmd/node (check cmd/ for exact entrypoint). Explorer frontend: cd explorer && npm run dev (starts Vite dev server on localhost:5173). Full test suite: go test ./... across all packages. Docker: docker-compose up for integration testing (referenced in README).

Map of the codebase

  • lib/consensus.go: Core BFT consensus logic that decides how blocks are validated and network agreement is achieved
  • lib/block.go: Defines block structure and validation—critical for understanding what the network accepts
  • lib/crypto/bls.go: BLS signature aggregation is likely central to the consensus protocol's batch verification
  • lib/crypto/vdf.go: Verifiable Delay Function implementation—novel cryptographic primitive for the recursive chain-bootstrap mechanism
  • controller/README.md: Documents the central hub that coordinates all subsystems; essential for understanding module interactions
  • lib/mempool.go: Transaction pool management—critical for understanding how pending transactions flow through the network
  • lib/peer.go: Peer discovery and management in the P2P layer
  • fsm/README.md: Finite State Machine docs define state transition rules—the operational logic of the blockchain

How to make changes

Adding consensus logic: Edit lib/consensus.go and lib/consensus_test.go, add protobuf definitions to lib/consensus.pb.go. Adding cryptographic functions: Add to lib/crypto/{algorithm}.go with corresponding _test.go file. Modifying state machine: Edit fsm/README.md structure and implement in fsm/ package. Updating RPC: Add endpoints in cmd/rpc/README.md and corresponding handler. Explorer UI changes: Edit explorer/src/ components with React/TypeScript. Start with lib/error.go to understand error handling patterns.

Traps & gotchas

Protobuf regeneration: .pb.go files are code-generated; modifying proto definitions requires running protoc to regenerate (check Makefile for protoc rules). Cryptographic key formats: lib/crypto/keystore.go manages multiple key types (Ed25519, Secp256k1, BLS)—ensure you use the correct type for your signature scheme. Consensus state: lib/consensus.go likely tracks Byzantine fault tolerance state; modifying block validation logic may require understanding the quorum rules and certificate requirements. Docker Compose setup required: Integration tests reference Docker Compose; running full test suite may fail without Docker daemon. Next.js version pinning: explorer/ uses Next.js 14.2.3 and React 19 precisely; version mismatches can cause build failures.

Concepts to learn

  • Byzantine Fault Tolerance (BFT) — Canopy's core consensus mechanism (bft/ package) allows agreement even when up to 1/3 of nodes are dishonest or faulty; understanding BFT thresholds and certificate generation is essential to modifying consensus logic
  • Verifiable Delay Function (VDF) — Implemented in lib/crypto/vdf.go and likely central to the recursive chain-bootstrap mechanism; VDF proves computation time without parallelism, novel for this codebase
  • Class Group Cryptography — lib/crypto/classgroup.go uses class groups (number-theoretic objects) for post-quantum-resistant operations; unique to Canopy and requires deep number theory understanding
  • BLS Signature Aggregation — lib/crypto/bls.go implements Boneh-Lynn-Shacham signatures allowing batch verification of many signatures; critical for scaling consensus to many validators
  • Finite State Machine (FSM) — fsm/ package defines how transactions transition blockchain state; understanding state invariants and transition rules is necessary to add new transaction types or modify validation logic
  • Ethereum-RPC Compatibility — Canopy exposes /v1/eth endpoint with Ethereum JSON-RPC methods, allowing MetaMask and indexers to work directly; fsm/ethereum.md specifies which EIPs are supported and how state is mapped
  • Recursive Chain Architecture — Core innovation: chains bootstrap each other in a recursive cycle; understanding how Canopy seeds new chains and ensures independence is the protocol's defining feature

Related repos

  • cosmos/cosmos-sdk — Reference implementation for modular blockchain architecture with pluggable modules; Canopy's lib/ and fsm/ organization mirrors Cosmos' approach to state machines
  • ethereum/go-ethereum — Go Ethereum client that Canopy emulates via its Ethereum-RPC endpoint (fsm/ethereum.md); understanding geth's RPC layer helps with Canopy's compatibility layer
  • tendermint/tendermint — Seminal BFT consensus implementation in Go; Canopy's consensus.go likely drew inspiration from or directly implements similar state machine patterns
  • libp2p/go-libp2p — Peer-to-peer networking library; Canopy's p2p/ module likely uses or parallels libp2p's secure transport and peer discovery patterns
  • ethereum/EIPs — Ethereum Improvement Proposals repository; Canopy's recursive chain-bootstrap and Ethereum-RPC compatibility draw from EIP standards

PR ideas

Click to expand

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for crypto package cross-signature verification

The lib/crypto directory contains 8 different signature schemes (ed25519, secp256k1, eth_secp256k1, bls, vdf, ecdh, aead, classgroup) but each has isolated unit tests. A new integration test file (lib/crypto/crypto_integration_test.go) should verify interoperability between these schemes, especially critical for a consensus protocol where validators use different key types. This catches real-world bugs where signature verification fails across protocol upgrades.

  • [ ] Create lib/crypto/crypto_integration_test.go
  • [ ] Add tests verifying key derivation consistency across all 8 schemes
  • [ ] Add tests for cross-signature validation (e.g., BLS multi-sig verification with mixed key types)
  • [ ] Add tests for ECDH key agreement with both secp256k1 variants
  • [ ] Reference existing test patterns in lib/crypto/*_test.go files

Add GitHub Actions CI workflow for Go unit tests and coverage reporting

The repo has a Dockerfile and Makefile but no visible GitHub Actions workflow. With 40+ test files across lib/ and bft/, contributors need automated testing on push/PR. This should run 'go test ./...' across the Go 1.21 requirement, report coverage, and fail PRs below a threshold. Critical for a blockchain protocol where test regressions are expensive.

  • [ ] Create .github/workflows/go-tests.yml
  • [ ] Configure matrix testing for Go 1.21.x and latest stable
  • [ ] Add 'go test -v -race -coverprofile=coverage.out ./...' step
  • [ ] Add codecov integration or use go tool cover for reporting
  • [ ] Add coverage threshold check (e.g., fail if <80%)
  • [ ] Configure to run on all PRs and main branch pushes

Add TypeScript type stubs and Vite integration tests for explorer frontend

The explorer frontend uses React 19, TanStack Query, and Tailwind but has no visible test configuration (package.json shows 'type-check' but no test script). The frontend likely calls Go backend APIs defined in lib/*.pb.go protobuf files. Add integration tests that verify API contract between frontend and backend to catch breaking changes early.

  • [ ] Add 'vitest' and '@testing-library/react' to explorer package.json devDependencies
  • [ ] Create explorer/src/tests/setup.ts with mock server/fixtures
  • [ ] Add explorer/vite.config.test.ts configuration for Vitest
  • [ ] Create integration test file (e.g., explorer/src/tests/api-integration.test.ts) that mocks calls to backend (e.g., querying blocks, transactions from lib/block.pb.go, lib/tx.pb.go)
  • [ ] Add 'test' and 'test:coverage' scripts to package.json
  • [ ] Update .github/workflows to run these tests on Node.js LTS

Good first issues

  • Add missing unit tests for lib/dex.go (DEX logic)—currently lib/dex_test.go exists but likely incomplete; expand test coverage for swap, liquidity pool, and error conditions: Medium: DeFi logic is security-critical and visible test coverage is a good starting point to learn the codebase
  • Document the class group cryptographic operations in lib/crypto/classgroup.go with code comments and a guide in docs/; this is a novel primitive that needs clarity for contributors: Medium: Class Group is non-standard cryptography; documentation will help future maintainers and increase protocol transparency
  • Add integration tests in cmd/rpc/ that verify Ethereum-RPC compatibility (eth_getBalance, eth_sendTransaction, eth_getBlockNumber) match Ethereum spec behavior: Medium-Hard: Ethereum compatibility is a core feature; explicit spec conformance tests prevent regressions and serve as documentation

Top contributors

Click to expand

Recent commits

Click to expand
  • 097ada9 — Merge pull request #475 from canopy-network/add-cap-orders (pablocampogo)
  • ea684c5 — fix(dex): cap DEX order settlement per block to prevent consensus livelock (pablocampogo)
  • 8ccd04a — Merge pull request #474 from canopy-network/fix-cap-error (pablocampogo)
  • 1cc7ed2 — fix(dex): refund at-cap LP deposits instead of erroring the whole batch (pablocampogo)
  • da6fa53 — Merge pull request #471 from canopy-network/feat/write-private-key-cmd (rem1niscence)
  • 18ebfae — Merge pull request #465 from canopy-network/fix-search-bar (rem1niscence)
  • b3005f3 — feat: new-validator-key command (rem1niscence)
  • 9474a50 — fix: stackoverflow error on set password (rem1niscence)
  • 723a998 — docs: clarify ethereum nonce compatibility (andrewnguyen22)
  • aca2b7c — Stabilize Ethereum nonce floor (andrewnguyen22)

Security observations

Click to expand
  • High · Outdated Go Version in Dockerfile — Dockerfile, line 1. The Dockerfile uses golang:1.26-alpine for building, which is a future/non-existent version. The README indicates Go v1.21 support. Using an invalid or outdated Go version may introduce unpatched security vulnerabilities and compatibility issues. Fix: Update to a stable, current Go version (e.g., golang:1.21-alpine or golang:1.22-alpine) that matches the project's minimum supported version.
  • High · Missing Input Validation in Cryptographic Functions — lib/crypto/ directory (all cryptographic modules). Multiple cryptographic modules (lib/crypto/*.go) handle sensitive operations like key generation, signing, and validation. Without visible input sanitization patterns in the file structure, there's risk of improper input handling leading to cryptographic failures or side-channel attacks. Fix: Implement comprehensive input validation and bounds checking for all cryptographic functions. Use established cryptographic libraries and ensure constant-time comparisons for sensitive operations.
  • High · Potential Hardcoded Configuration Paths — lib/config.go, lib/crypto/keystore.go. The presence of lib/config.go and lib/keystore.go suggests configuration and key management. Without source code review, there's risk of hardcoded secrets, API keys, or sensitive paths in configuration files. Fix: Externalize all configuration to environment variables or secure vaults. Never commit secrets to version control. Use tools like git-secrets or TruffleHog to detect leaked credentials.
  • Medium · Unsafe Docker Multi-stage Build with Conditional Logic — Dockerfile, lines 14-19. The Dockerfile uses shell conditional logic with BIN_PATH argument that could be exploited if not properly validated. The pattern 'if [ ! -f "${BIN_PATH}" ]' allows arbitrary file paths without validation, potentially leading to path traversal or unintended file operations. Fix: Validate and sanitize the BIN_PATH argument. Use absolute paths and whitelist allowed build targets. Consider removing conditional logic in favor of explicit build stages.
  • Medium · Missing Security Headers in Web Components — explorer package configuration, vite.config (not provided). The explorer frontend (React/TypeScript app) may serve HTTP content without proper security headers (CSP, X-Frame-Options, etc.). The file structure shows web components but no visible security configuration. Fix: Implement security headers via middleware or web server configuration. Set Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and other protective headers.
  • Medium · Protobuf Code Generation Without Verification — lib/*.pb.go, bft/*.pb.go, lib/crypto/crypto.pb.go. Multiple .pb.go files indicate protobuf usage for serialization. Without visible build verification, there's risk of stale or tampered generated code not matching .proto definitions. Fix: Add protobuf generation verification to CI/CD pipeline. Regenerate and commit .pb.go files as part of build process. Use pinned protoc compiler versions.
  • Medium · Dependency Version Pinning Issues in Frontend — package.json dependencies. The package.json uses caret (^) version specifiers allowing minor and patch updates automatically. Some security-critical packages like @tanstack/react-query, react-router-dom should have stricter version constraints. Fix: Review and pin critical dependencies to specific versions (e.g., react@19.1.1 instead of ^19.1.1). Implement automated dependency scanning with Dependabot or Snyk.
  • Medium · Missing CORS and Authentication Headers Configuration — explorer/ frontend configuration. No visible CORS configuration, authentication middleware, or API security headers in the explorer frontend setup. API endpoints may be exposed to unauthorized cross-origin requests. Fix: Implement proper CORS policies, add authentication headers, and API rate limiting. Use environment-specific configurations to restrict origins in production.
  • Low · Outdated Alpine Base Image — ``. Dockerfile uses alpine:3.19, which may not receive timely security updates. Consider using a more recent Alpine version for latest patches. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

Suggested reading order

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

  1. cmd/rpc/web/explorer/src/lib/utils.ts — Foundation: doesn't import anything internally and is imported by 29 other files. Read first to learn the vocabulary.
  2. cmd/rpc/web/explorer/src/components/AnimatedNumber.tsx — Foundation: imported by 16, no internal dependencies of its own.
  3. lib/crypto/address.go — Built on the foundation; imported by 58 downstream files.
  4. cmd/rpc/web/wallet/src/actions/fields/FieldWrapper.tsx — Built on the foundation; imported by 11 downstream files.
  5. lib/block.go — Layer 2 — composes lower-level code into reusable abstractions (imported 53×).
  6. fsm/account.go — Layer 3 — composes lower-level code into reusable abstractions (imported 13×).
  7. controller/block.go — Layer 4 — composes lower-level code into reusable abstractions (imported 5×).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.

The exported doc (Copy CLAUDE.md / Download / .cursor/rules) also includes an agent protocol and a verification script written for AI coding agents — omitted here to keep this view scannable.

Similar Go repos

Other mixed-signal Go repos by stars.

Embed this chat in your README

Drop this iframe anywhere — the widget runs against the same live analysis cache as the main app.

<iframe
  src="https://repopilot.app/embed/canopy-network/canopy"
  width="100%" height="500"
  style="border:1px solid #d0d7de; border-radius:8px;"
  allow="microphone"
  loading="lazy"
></iframe>