Skip to content

docs: refresh stale architecture and structure docs#4580

Open
pinebit wants to merge 2 commits into
mainfrom
refresh-architecture-doc
Open

docs: refresh stale architecture and structure docs#4580
pinebit wants to merge 2 commits into
mainfrom
refresh-architecture-doc

Conversation

@pinebit

@pinebit pinebit commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Updates docs/architecture.md, docs/structure.md and the CLAUDE.md architecture summary to match the current implementation.

docs/architecture.md:

  • Keeps both ASCII diagrams; removes the Signer/remote-signer component from the workflow diagram (it does not exist in the code) and corrects the BFT fault tolerance note to t = ceil(2n/3) available and honest nodes, tolerating f = floor((n-1)/3) faulty nodes.
  • Updates all interface snippets to match core/interfaces.go (Scheduler, Fetcher, Consensus + ConsensusController, DutyDB, ValidatorAPI, ParSigDB, SigAgg, AggSigDB, Broadcaster) and notes that file as the source of truth.
  • Scheduler: bulk cached validator resolution, sync committee and derived aggregator/sync-contribution duty scheduling, slot offsets, SSE head/reorg event handling, builder registration submission.
  • Consensus: documents the pluggable consensus controller with QBFT v2.0 as default and priority-protocol-based selection, linking to docs/consensus.md.
  • DutyDB/ParSigDB/AggSigDB: replaces outdated relational data models with the actual in-memory designs, inline threshold matching and deadliner-based trimming; resolves stale TODO/open questions.
  • Validator API: replaces the outdated endpoint list with a table of currently intercepted endpoints and updates the SignedData implementations list.
  • Adds a duty lifecycle table (initiator, consensus, broadcast per duty type) and a supporting components section (Tracker, InclusionChecker, Priority/InfoSync, Deadliner, duty gater, caches, builder registration service).

docs/structure.md:

  • Removes references to deleted code (core/encode.go, app/dbindex/, p2p/discovery.go/discv5) and describes relay-based peer discovery.
  • Adds missing packages (core/consensus, core/tracker, core/priority, core/infosync, app infrastructure libraries, eth2util and testutil subpackages) and the current CLI command tree (combine, exit, deposit, feerecipient, alpha, unsafe).

CLAUDE.md:

  • Aligns the architecture summary with the refreshed docs: pluggable consensus controller, corrected Priority and peer discovery descriptions, adds the InclusionChecker.

category: docs
ticket: none

pinebit and others added 2 commits July 3, 2026 22:51
Update docs/architecture.md and docs/structure.md to match the current
implementation: fix component interfaces to match core/interfaces.go,
remove the nonexistent Signer/remote-signer component, correct the BFT
fault tolerance formula, document the consensus controller and priority
protocol, replace outdated DutyDB/ParSigDB data models, refresh the
validator API endpoint list, and add a duty lifecycle table and
supporting components section. Update the project structure doc with
current packages and CLI commands.

category: docs
ticket: none

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Mention the pluggable consensus controller, correct the Priority and
peer discovery descriptions, and add the InclusionChecker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Jul 3, 2026

Copy link
Copy Markdown

@pinebit pinebit requested review from KaloyanTanev and OisinKyne July 3, 2026 19:53
@codecov

codecov Bot commented Jul 3, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.22%. Comparing base (6ffb9bb) to head (5f116ee).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #4580      +/-   ##
==========================================
+ Coverage   57.20%   57.22%   +0.02%     
==========================================
  Files         245      245              
  Lines       33449    33449              
==========================================
+ Hits        19135    19142       +7     
+ Misses      11890    11880      -10     
- Partials     2424     2427       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant