mirror of
https://github.com/Chia-Network/chia-blockchain.git
synced 2026-08-24 10:05:29 -05:00
Almog De PazandGitHub
346fb9a0cf
* Add Bugbot consensus review context Document the validation-state and sub-epoch-summary invariant so automated PR review has the same consensus context as local agents. * Route Bugbot to repository context docs Keep Bugbot guidance focused on subsystem context routing so automated reviews use the same module map as local agents. * Add generated repository context docs Include the expanded module context map and route Bugbot to the same subsystem docs used by local agents. * Add EDC agent context pointer Include the generated EDC agent guidance alongside the Cursor agent context docs. * Fold EDC guidance into AGENTS Keep agent context entrypoints consolidated in AGENTS.md and remove the separate EDC pointer. * Remove generator name from agent guidance Keep AGENTS.md focused on repository context locations rather than the tooling used to produce them. * Consolidate context corpus into one source-verified canonical set - Normalize all subsystem docs to canonical names without chia- prefix, removing the split between old and new-dominant corpora. - Merge new-dominant content into consensus.md, full-node.md, wallet.md; split networking.md into server.md, protocols.md, apis.md; add types.md. - Rename 15 genuinely-new subsystem docs; fold chia-root.md into architecture-overview.md. - Remove filter-branch leakage (filter_challenge, predictable filter, protocol 0.0.38) from types.md, protocols.md, harvester.md. - Correct factual inaccuracies: /push_tx vs wallet queue semantics, Err sign/ban policy, protocol import-time coverage, server peer-serving, address-manager mutation rule, wallet tx-store rollback, ValidationState speculative advancement, block-creation default, MempoolItem fallback. - Replace unreachable verification SHA with PR-head commit. - Consolidate test guidance into one small router plus 12 on-demand testing/ docs; remove duplicate auto-attached test guides. - Make INDEX.md the authoritative routing manifest; update BUGBOT.md, AGENTS.md, and context-routing.mdc to reference one canonical corpus. - Replace context-chia-*.mdc rules with canonical narrow rules; remove recursive .cursor/** rule and consolidate duplicate tooling rules. - Tighten clvm-execution.md: remove stale cost_calculator.py reference, fix block-creation default, replace opcode catalogue with pointer. * Trim redundant context and testing docs after value audit - Trim benchmarks.md: remove per-script Workload Groups narration that is obvious from opening each script; keep fidelity, coupling, and fragility sections. - Trim testing/patterns.md: slim to the module-by-module setup map and layered-assertion list; remove block/tx/assertion how-to that duplicates per-area testing docs. - Trim testing/full-node.md: slim to starter template and sync-convergence tip; remove fixture list and assertion patterns duplicated by patterns.md and architecture.md. - Fold testing/service-wiring.md per-cluster correlation details into testing/architecture.md; delete service-wiring.md (high overlap with architecture.md). - Fix protocols.md: correct NewSignagePointHarvester2 message-ID wording (ID reassigned to 66, not literally the same ID). - Update INDEX.md and testing-guide.mdc router to reflect service-wiring.md removal. * Fix verification SHA to reference the main source baseline The docs were verified against source at PR base24db9ad390(origin/main), nota5647a9327(the original PR head, which only adds context docs and is not a meaningful source baseline). The chia/ source tree is identical across both commits since the PR changes no production code. * Fix remaining V2 filter-branch leakage in harvester.md and types.md - harvester.md: replace calculate_effective_plot_filter_bits() and calculate_min_plot_strength() (filter-branch-only) with the actual main source path: calculate_prefix_bits() with NUMBER_ZERO_BITS_PLOT_FILTER_V2 and height adjustments, then passes_plot_filter(); strength bounds checked by check_plot_param() against MIN_PLOT_STRENGTH/MAX_PLOT_STRENGTH. - harvester.md: use meta_group (actual PartialProofsData field name) instead of "meta group". - types.md: correct that candidate height feeds prefix-bit reductions for both V1 and V2, not just V1; calculate_prefix_bits() branches on V1/V2 constants and height thresholds.
12 KiB
12 KiB
Chia Blockchain — Deep Context Index
Generated from deep context-building pass. Each subsystem file is self-contained: pull only the file(s) relevant to the code you're touching.
How to use
- Read this file first for orientation.
- Attach the subsystem file(s) that cover the code you're working on.
- If your change crosses subsystem boundaries, also attach
global-invariants.md— it documents the contracts between modules.
Subsystem files
| File | Covers | When to attach |
|---|---|---|
| architecture-overview.md | Module map, actors, entrypoints, key types, chia_rs boundary, package root |
Starting any unfamiliar work; first-time orientation |
| consensus.md | Block validation, difficulty adjustment, fork choice, VDF iterations, rewards, reorg contract | Touching chia/consensus/, block acceptance, reorgs |
| mempool.md | Transaction admission, eviction, fee logic, conflict detection, FF/DEDUP | Touching chia/full_node/mempool*.py, eligible_coin_spends.py, fee estimation |
| full-node.md | FullNode orchestration, sync, block processing pipeline, FullNodeStore, FullNodeAPI | Touching chia/full_node/full_node.py, full_node_api.py, full_node_store.py |
| server.md | WebSocket connections, rate limiting, peer discovery, TLS, address-manager behavior | Touching chia/server/, connection handling |
| protocols.md | Wire protocol message schemas, numeric IDs, sender authorization, reply maps, capabilities | Touching chia/protocols/, message definitions |
| apis.md | API stub metadata, request/reply declarations, protocol-visible method names | Touching chia/apis/*_stub.py, API decorators |
| types.md | Shared blockchain-format types, CLVM Program helpers, Coin/condition contracts, Rust boundary |
Touching chia/types/, serialization compatibility |
| wallet.md | Coin selection, wallet state manager, wallet node sync, sub-wallets, persistence, offers | Touching chia/wallet/ |
| clvm-execution.md | CLVM execution paths, resource limits, canonical serialization, generator resolution, AGG_SIG | Touching puzzle execution, spend validation, generator logic |
| farmer.md | Farmer proof flow, pool partial submission, reward targets, plot-sync receiver, solver management | Touching chia/farmer/ |
| harvester.md | Plot file management, PoS lookups, signage-point filter, plot sync | Touching chia/harvester/ |
| timelord.md | VDF scheduling, peak/unfinished-block selection, compact proof production | Touching chia/timelord/ |
| plotting.md | Plot creation, plot format, plot keys | Touching chia/plotting/ |
| plot-sync.md | Plot sync protocol, delta sync, sender/receiver state | Touching chia/plot_sync/ |
| pools.md | Pool NFT / pool singleton state, pool wallet transitions, pool protocol payloads | Touching chia/pools/ |
| daemon.md | Daemon routing, keychain/process authority, service launch | Touching chia/daemon/ |
| data-layer.md | DataLayer store mutations, root publication, mirror sync, proof verification | Touching chia/data_layer/ |
| rpc.md | RPC transport, error shapes, daemon websocket envelopes | Touching chia/rpc/ |
| ssl.md | Certificate generation, public/private CA material, SSL file permissions | Touching chia/ssl/ |
| simulator.md | Simulator block farming, reorg/revert helpers, BlockTools, service test harnesses | Touching chia/simulator/ |
| solver.md | V2 plot partial proof solving, solver service, farmer coupling | Touching chia/solver/ |
| seeder.md | Crawler peer discovery, DNS seed responses, bootstrap-peer publication | Touching chia/seeder/ |
| introducer.md | Introducer peer collection, TCP vetting, DNS fallback | Touching chia/introducer/ |
| cmds.md | CLI command handlers, service start/stop wiring | Touching chia/cmds/ |
| util.md | DB wrapper, streamable, keychain, bech32m, error enum, config, caching | Touching chia/util/ |
| benchmarks.md | Benchmark harness, benchmark scripts, performance measurement | Touching benchmarks/ |
| repo-tooling.md | Packaging, install scripts, CI workflows, build/release, GUI submodule, developer tools | Touching root config, build_scripts/, .github/, tools/, install scripts |
| global-invariants.md | Cross-module invariants, state dependencies, trust boundaries, workflow traces, fragility clusters | Cross-cutting changes, security review, reorg-related work |
Test guidance
Test harness selection and patterns live under .cursor/context/testing/ and
are routed by .cursor/rules/testing-guide.mdc. Read that rule when working in
chia/_tests/.
| File | Covers |
|---|---|
| testing/architecture.md | Test architecture, consensus modes, fixture authority, CI, cross-subsystem correlation |
| testing/patterns.md | Block creation, transaction submission, assertion patterns |
| testing/blockchain.md | Consensus/blockchain tests, reorg, overflow, fork invariants |
| testing/full-node.md | Full node sync, propagation, mempool-to-block, reorg tests |
| testing/mempool.md | Mempool acceptance/rejection, replacement, eviction |
| testing/data-layer.md | DataStore logic, wallet-backed RPC, singleton lifecycle |
| testing/server.md | Connection lifecycle, API errors, DoS/ban, rate limiting |
| testing/wallet.md | Wallet fixtures, wallet_environments, wallet RPC tests |
| testing/clvm.md | Direct CLVM execution vs SpendSim |
| testing/cmds.md | CLI harness, mock RPC boundaries |
| testing/infrastructure.md | Shared harness, setup_nodes, SpendSim, convergence helpers |
Quick reference — key files by size/complexity
| File | Lines | Role |
|---|---|---|
chia/full_node/full_node.py |
~3400 | Main orchestrator |
chia/wallet/wallet_state_manager.py |
~3330 | Wallet state |
chia/wallet/wallet_rpc_api.py |
~3610 | Wallet RPC surface |
chia/full_node/full_node_api.py |
~2080 | P2P message handlers |
chia/full_node/full_node_rpc_api.py |
~1170 | Full node RPC |
chia/consensus/blockchain.py |
~1090 | Chain state + add_block |
chia/consensus/block_header_validation.py |
~1060 | Header checks |
chia/full_node/weight_proof.py |
~1740 | Weight proof validation |
chia/full_node/mempool_manager.py |
~1160 | Mempool admission |
chia/full_node/mempool.py |
~810 | Mempool data structure |
chia/consensus/block_body_validation.py |
~580 | Body checks |
chia/consensus/difficulty_adjustment.py |
~410 | Difficulty/SSI |
chia/full_node/coin_store.py |
~680 | UTXO database |
chia/full_node/full_node_store.py |
~1060 | Signage points, unfinished blocks |
Consensus constants cheat-sheet
| Constant | Value | Note |
|---|---|---|
SLOT_BLOCKS_TARGET |
32 | Target blocks / sub-slot |
NUM_SPS_SUB_SLOT |
64 | Signage points / sub-slot |
SUB_SLOT_TIME_TARGET |
600 s | ~10 min / sub-slot |
EPOCH_BLOCKS |
4608 | Blocks / difficulty epoch |
SUB_EPOCH_BLOCKS |
384 | Blocks / sub-epoch |
MAX_BLOCK_COST_CLVM |
11 000 000 000 | Max CLVM cost / block |
COST_PER_BYTE |
12 000 | Generator byte cost |
MAX_BLOCK_COUNT_PER_REQUESTS |
32 | Max blocks / P2P request |
DIFFICULTY_CHANGE_MAX_FACTOR |
3 | Max epoch difficulty ratio |
MAX_FUTURE_TIME2 |
120 s | Max timestamp drift |
HARD_FORK_HEIGHT |
5 496 000 | June 2024 hard fork |
MEMPOOL_BLOCK_BUFFER |
10 | Mempool = 10× block cost |