canopy-network/canopy 딥다이브
— 재귀적 멀티체인 부트스트랩 프로토콜 NestBFT 완전 해부

┌─────────────────────────────────────────────────────────┐ │ Canopy Node │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Controller (Bus) │ │ │ │ - 모든 컴포넌트의 참조를 보유하는 중앙 허브 │ │ │ │ - 블록 수신/제안/커밋 조율 │ │ │ │ - 크로스체인 체크포인트, 보상 계산 │ │ │ └──┬──────────┬──────────┬──────────┬─────────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌─────────┐ │ │ │ BFT │ │ FSM │ │ P2P │ │ Mempool │ │ │ │NestBFT │상태머신│ │네트워크 │ │Tx 대기열│ │ │ └──┬───┘ └──┬───┘ └──┬───┘ └────┬────┘ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ Store │ │ │ │ │ │ PebbleDB (LSM 트리) │ │ │ │ │ │ SMT (상태 루트 해시)│ │ │ │ │ │ Indexer (블록/Tx 색인)│ │ │ │ │ └─────────────────────┘ │ │ │ │ │ │ │ └─────── 합의 메시지 → P2P ───────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Plugin Interface (중첩 체인 연결) │ │ │ │ Go / Kotlin / Python / TypeScript / C# SDK │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ cmd/ — CLI · RPC Server · 자동 업데이트 │ │ │ │ Next.js Wallet · Explorer (프론트엔드) │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐ │ NestBFT 합의 한 라운드 (높이 H) │ │ │ │ [1] Election VRF(private_key, state) → 후보 생성 │ │ │ 지분 가중 정렬 → 리더 후보 결정 │ │ [2] ElectionVote 복제자들이 리더에게 투표 전송 │ │ │ QC(Quorum Certificate) 생성 │ │ [3] Propose 리더가 블록 제안 브로드캐스트 │ │ │ (Mempool Tx 선택 + 헤더 서명) │ │ [4] ProposeVote 복제자들이 제안 검증 후 투표 전송 │ │ │ ┌─────── 실패 시 ──────────┐ │ │ [5] Precommit QC 집계 후 Pre-commit 단계 │ │ │ │ │ Round Interrupt 발동 │ │ │ [6] PrecommitVote 복제자 재확인 투표 │ │ │ │ │ Pacemaker (재동기화) ───┘ │ │ [7] Commit 최종 커밋 QC 생성 │ │ │ │ │ [8] CommitProcess 보상 계산, 슬래싱, 크로스체인 체크포인트│ │ │ │ │ ─────────────────────── 다음 높이 ────────────────────── │ │ │ │ BLS 집계: 검증자들의 개별 서명 → 단일 다중서명 (O(1) 공간)│ │ Star 통신: 복제자 → 리더 → 브로드캐스트 (O(n) 메시지) │ └────────────────────────────────────────────────────────────┘

Canopy Root Chain (Betanet → Mainnet) │ ├── Committee A (검증자 부분집합, 동일 CNPY 스테이크 재활용) │ └── Nested Chain A (상태 머신·블록 저장은 자체 노드) │ │ ← Certificate Result → Root Chain에 블록 결과 제출 │ └── 성숙 후 독립(graduate) 가능 │ ├── Committee B │ └── Nested Chain B │ └── (재귀: Nested Chain도 자신의 nested chain을 가질 수 있음) * Plugin SDK로 중첩 체인 소프트웨어 개발 * 리더가 Certificate Result 트랜잭션을 Root Chain에 제출 * Root Chain이 최종 보안 앵커 역할

canopy/ ├── bft/ # NestBFT 합의 엔진 │ ├── README.md # NestBFT 전체 설계 문서 (필독!) │ ├── election.go # VRF 기반 리더 선출 │ ├── vote.go # BLS 투표 집계 │ ├── prop.go # 블록 제안 처리 │ ├── evidence.go # 이중 서명 증거 처리 │ └── msg.go # 합의 메시지 타입 │ ├── fsm/ # 유한 상태 기계 (블록체인 규칙) │ ├── README.md # FSM 설계 문서 │ ├── state.go # 상태 스냅샷 + 전이 함수 │ ├── account.go # 계좌 + 풀 관리 │ ├── committee.go # 검증자 위원회 관리 │ ├── transaction.go # 트랜잭션 검증·실행 │ ├── message.go # 트랜잭션 타입 정의 │ └── key.go # 상태 KV 키 스키마 │ ├── p2p/ # P2P 네트워크 레이어 │ ├── README.md │ ├── p2p.go # 메인 P2P 서비스 │ ├── peer.go # 피어 연결 관리 │ ├── multi_conn.go # 멀티플렉스 연결 │ ├── encrypted_conn.go # ECDH + ChaCha20 암호화 │ └── peer_book.go # 피어 주소록 │ ├── store/ # 영속성 레이어 │ ├── README.md # SMT·PebbleDB·Indexer 상세 문서 │ ├── store.go # 통합 Store 구조체 │ ├── txn.go # 중첩 트랜잭션 구현 │ ├── smt.go # Sparse Merkle Tree │ └── indexer.go # 블록·Tx·QC 색인 │ ├── controller/ # 조율 허브 │ ├── README.md │ ├── controller.go # 컨트롤러 초기화·생명주기 │ ├── block.go # 블록 수신·제안·커밋 │ ├── consensus.go # 합의 메시지 라우팅 │ ├── tx.go # 트랜잭션 시스템 │ └── result.go # Certificate Result 처리 │ ├── lib/ # 공용 라이브러리 │ ├── crypto/ # BLS, Ed25519, secp256k1, ECDH, VDF │ ├── codec/ # Protobuf 코덱 │ ├── block.pb.go # Protobuf 생성 타입 │ ├── config.go # 노드 설정 │ ├── vdf.go # VDF(Verifiable Delay Function) 구현 │ └── mempool.go # 멤풀 인터페이스 │ ├── cmd/ # 실행 진입점 │ ├── main/main.go # 노드 바이너리 진입점 │ ├── cli/ # Cobra CLI 커맨드 │ ├── rpc/ # HTTP·WebSocket·Ethereum RPC 서버 │ │ └── web/ # Next.js 지갑 + 탐색기 프론트엔드 │ └── auto-update/ # 자동 업데이트 릴리저 │ ├── plugin/ # 중첩 체인 SDK │ ├── go/ # Go 플러그인 (TUTORIAL.md 포함) │ ├── kotlin/ # Kotlin 플러그인 │ ├── python/ # Python 플러그인 │ ├── typescript/ # TypeScript 플러그인 │ └── csharp/ # C# 플러그인 │ ├── .docker/ # Docker Compose 설정 ├── Makefile # 빌드·테스트·Docker 타깃 ├── go.mod # Go 1.24 의존성 목록 └── README.md # 프로젝트 개요

# 1. 소스 클론
git clone https://github.com/canopy-network/canopy.git
cd canopy

# 2. 바이너리 빌드 (지갑+탐색기 포함 풀 빌드)
make build/canopy-full

# 3. 노드 실행
canopy start

# Docker로 로컬 테스트넷 실행 (4노드 구성)
make docker/build
make docker/up-fast
make docker/logs

# 유닛 테스트 실행
make test/all

# 특정 모듈만 테스트
go test ./bft/...
go test ./store/...
go test ./lib/crypto/...

# Go 플러그인 기반 중첩 체인 개발
cd plugin/go
cat TUTORIAL.md   # 튜토리얼 필독

# Docker로 플러그인 노드 실행
make PLUGIN=go build/plugin