brighter47/canopy

Purpose and Runtime Entry Points

Canopy is the Go reference implementation of the Canopy Network Protocol: a recursive blockchain framework plus seed chain. The node binary starts at cmd/main/main.go; command-line administration and queries are in cmd/cli/cli.go, cmd/cli/admin.go, and cmd/cli/query.go. The runtime is primarily Go 1.21, with a TypeScript browser wallet and explorer served independently from the node.

Node Orchestration

The controller is the central coordination boundary between networking, consensus, transaction handling, state transitions, and persistence. It owns block/consensus coordination and routes node-level work rather than embedding domain rules itself.

• controller/controller.go

• controller/consensus.go

• controller/block.go

Primary flow: P2P-delivered transactions and consensus messages enter controller-managed paths; accepted blocks are executed through the FSM and committed to storage.

Deterministic State Machine

The FSM defines consensus-critical validation and state mutation. It handles accounts, validators/committees, governance, DEX and swaps, Ethereum-oriented functionality, events, genesis, and transaction/message interpretation. State logic must remain deterministic because every validator executes it for the same block.

• fsm/state.go

• fsm/transaction.go

• fsm/automatic.go

• fsm/gov.go

• fsm/dex.go

BFT Consensus Pipeline

The BFT package implements proposer selection/election, proposals, votes, evidence, and consensus messages. It produces agreement on a block before the controller applies its state transition; evidence represents the fault-handling boundary for Byzantine behavior.

• bft/bft.go

• bft/election.go

• bft/prop.go

• bft/vote.go

• bft/evidence.go

P2P Transport and Cryptographic Boundary

Nodes discover and maintain peers, exchange protocol messages, and encrypt connections through the P2P subsystem. Cryptographic identity, signatures, key storage, hashing, BLS, secp256k1/Ed25519, and Ethereum secp256k1 support sit in shared library code. P2P supplies the distributed transport; consensus and controller own message semantics.

• p2p/p2p.go

• p2p/conn.go

• p2p/encrypt.go

• lib/crypto/key.go

• lib/crypto/keystore.go

Persistence, Data Models, and Wire Contracts

Storage maintains versioned chain state, sparse Merkle-tree verification, transactional updates, and historical indexing. Shared lib types cover blocks, transactions, certificates, configuration, peers, mempool, and plugin contracts. Protobuf definitions are the canonical cross-package/wire schema source, with generated Go bindings checked in.

• store/versioned_store.go

• store/smt.go

• store/indexer.go

• lib/.proto/tx.proto

• lib/.proto/consensus.proto

External Interfaces: RPC, UIs, and Plugins

The RPC server exposes query, administration, Ethereum-facing, and client routes over server/socket layers. Two TypeScript/Vite applications consume node-facing APIs: an explorer and a wallet. The wallet contains a manifest-driven declarative action engine that renders forms and submits action workflows. Plugin SDKs let independently implemented chain/plugin logic communicate through protobuf/RPC contracts in Go, C#, Kotlin, Python, or TypeScript.

• cmd/rpc/server.go

• cmd/rpc/routes.go

• cmd/rpc/eth.go

• cmd/rpc/web/wallet/src/actions/ActionRunner.tsx

• cmd/rpc/web/explorer/src/lib/api.ts

• plugin/go/contract/plugin.go

Deployment and Automation

Docker Compose provides a multi-node local network with per-node genesis, validator keys, keystores, and persisted state fixtures. Auto-update is a separate Go service with language-specific container images for plugin release/update coordination.

• .docker/compose.yaml

• .docker/volumes/node_1/genesis.json

• .docker/volumes/node_1/validator_key.json

• cmd/auto-update/main.go