diff --git a/L1/coordinator-driven-execution-replay-milestone.md b/L1/coordinator-driven-execution-replay-milestone.md new file mode 100644 index 0000000..49f288f --- /dev/null +++ b/L1/coordinator-driven-execution-replay-milestone.md @@ -0,0 +1,45 @@ +# Coordinator-Driven Historical Execution Replay Milestone + +## Goal + +Replay every root-confirmed QuarkChain mainnet minor block from genesis through four `goshard` slaves, driven by a dedicated coordinator, with results identical to `pyquarkchain`. + +## Scope + +The milestone includes: + +- QKC data types, including blocks, transactions, receipts, logs, and state encoding. +- QuarkChain EVM compatibility. +- Multi-native-token state and execution. +- Minor-block execution, finalization, result validation, and state persistence. +- Cross-shard transaction generation, delivery, ordering, and execution. +- A replay coordinator for canonical input, branch routing, root advancement, barriers, and mismatch reporting. + +The milestone excludes: + +- Minor-block PoW/PoSW seal and difficulty validation. +- Root-chain fork choice and root-driven shard reorgs. +- Mining, txpool, live P2P sync, public RPC, and master compatibility. + +## Final Test + +1. Start four Go slaves with fresh databases, covering every historical mainnet branch, and establish their xshard connections. +2. Initialize the exact root and minor genesis state for every shard. +3. Read canonical root blocks in ascending order. For each committed minor header, load the full minor block and send it to the slave responsible for its branch. +4. Execute minor blocks serially within each branch. Different branches may run in parallel. +5. For each source minor block, the source slave must route a list, including an empty list, to every eligible destination shard. Each destination shard must persist the list before replay advances. +6. After all minor blocks and xshard lists for a root block are complete, broadcast that root block as the next trusted canonical root. Only then may later minor blocks consume its deposits. +7. For every minor block, compare the computed execution outputs with the values committed in the canonical block: + - state root; + - receipt root; + - bloom; + - total gas used; + - xshard receive gas used; + - xshard cursor; + - coinbase amount map. +8. Repeat selected ranges after restarts to verify persistence, idempotent xshard staging, and resumable replay. + +## Acceptance Criteria + +- Every root-confirmed canonical mainnet minor block is replayed from genesis, with all computed execution outputs matching the values committed in the canonical block. +- A mismatch stops replay and reports the root block, minor block, branch, height, and mismatched fields.