charon-guide

name: charon-guide description: Use when porting Charon components to understand Go codebase architecture, workflow, design patterns, or component responsibilities

Charon Architecture Guide

Reference for understanding the Charon Go codebase when porting to Pluto (Rust).

What is Charon?

Distributed validator middleware for Ethereum staking. Enables running a single validator across multiple independent nodes using threshold BLS signatures. Each validator duty flows through a multi-stage workflow with consensus and signature aggregation.

Knowledge Base

When you need deeper understanding:

Reference Version

Use Charon v1.7.1 as the default Go reference for AI-assisted porting and review. For DKG, sync, reshare, FetchDefinition, and peer-indexed broadcast code, treat .claude/skills/pluto-review/references/trail-of-bits-charon-v2-audit.md as a required security overlay: preserve v1.7.1 compatibility unless the audit documents vulnerable behavior, then port the audited fix intent.

Core Workflow

Every validator duty (attestation, block proposal, etc.) flows through these components in order:

Scheduler → Fetcher → Consensus → DutyDB → ValidatorAPI → ParSigDB → ParSigEx → SigAgg → AggSigDB → Bcast

Porting note: When porting a component, trace its inputs and outputs through this pipeline.

Key Abstractions

Type encoding: Abstract types are encoded/decoded via core/encode.go. Always check this file when porting type serialization.

Design Patterns

Consensus (QBFT)

Charon uses QBFT (Istanbul BFT) for consensus. Each duty requires consensus to ensure all nodes sign identical data (required for BLS threshold signatures and slashing protection).

Key files:

• core/qbft/ - QBFT implementation
• core/consensus/ - Consensus component integration
• charon/docs/consensus.md - Design documentation

Porting note: QBFT is complex. Port incrementally and verify against Go test vectors.

Package Structure

Common Porting Scenarios

Porting a Workflow Component

1. Read charon/docs/architecture.md for component interfaces
2. Identify inputs (what triggers this component?)
3. Identify outputs (what does it produce? who consumes it?)
4. Check core/<component>/ for implementation
5. Check subscriptions in app/app.go (wiring/stitching logic)
6. Port logic, preserving immutability and callback patterns

Adding New Duty Types

When porting code that adds duty types:

1. Add to core/types.go (duty type constants)
2. Add to core/encode.go (encoding/decoding logic)
3. Update Scheduler, Fetcher, and relevant components

Understanding Error Handling

Go style:

• Just return errors, don't log and return
• Wrap external errors: errors.Wrap(err, "do something")
• Use app/errors for structured errors with fields

Rust style: See rust-style skill and AGENTS.md.

Working with Cluster Lock Files

• cluster-definition.json: Intended cluster config (operators, validators)
• cluster-lock.json: Extends definition with DV public keys and shares (DKG output)
• See cluster/ package for parsing/validation

Dependency Notes

Charon uses forked dependencies:

• github.com/ObolNetwork/kryptology (security fixes)
• github.com/ObolNetwork/go-eth2-client (kept up to date)

When porting code using these, check if Rust equivalents exist or if porting is needed.

Version Compatibility

Important for protocol compatibility:

• Compatible: Same MAJOR version, different MINOR/PATCH
• Incompatible: Different MAJOR version
• DKG: Requires matching MAJOR and MINOR versions (PATCH can differ)

Quick Reference Commands

When exploring Charon codebase:

# Find a function
grep -r "func FunctionName" charon/

# See package structure
ls -la charon/<directory>/

# Check imports
grep "^import" charon/path/to/file.go

# Run specific Go test (to understand behavior)
cd charon && go test -run TestFunctionName ./path/to/package