# XDPoS Parity Auto-Research

You are an AI agent working on consensus parity between XDC GP5 (geth-1.17 fork) and XDC 2.6.8 (legacy reference). Your job is to iteratively close the gap until GP5 produces the same blocks v2.6.8 produces, byte-for-byte.

This file is your only persistent instruction set. Everything else — what to read, what to change, how to score progress — is in this directory.

## The loop

```
1. Read progress.md          — what's the current parity score, what was tried last
2. Run ./measure.sh          — get the current score and per-check breakdown
3. Pick the lowest-scoring check that you can address with code changes
4. Read the corresponding check script under checks/ to understand what it tests
5. Read the patient + reference code at the relevant location
6. Propose a fix; write it to a temp branch via worktree
7. Run ./measure.sh on the worktree
8. If score improved: commit, update progress.md, append to log/
9. If score did not improve or regressed: discard, log why
10. Repeat
```

That's the entire program. No further instructions.

## Repos

- **Patient (under porting):** `/Users/anilchinchawale/github/XDCNetwork/XDC-Geth` branch `xdc-network`
- **Reference (immutable, source of truth):** `/Users/anilchinchawale/github/XDCNetwork/XDPoSChain`

You modify only the patient. Reference is read-only.

## The metric

`./measure.sh` computes a **parity score from 0 to 100**. Higher is better. The score is a weighted sum of structural checks under `checks/`. Each check is a small bash script that returns its weight if the patient is aligned with the reference on that specific concern, or 0 if not.

The full check list is in `checks/`; high-level groupings:

- **Sync-side operational fixes** (30 points total): C1.1 walk-back, C12 singleflight, bulk-sync soundness, genesis hash placeholder.
- **Mining-side wrapper dispatch** (35 points): each of `Author`, `Prepare`, `Finalize`, `FinalizeAndAssemble`, `Seal`, `CalcDifficulty`, `SealHash`, `Authorize` dispatches by `BlockConsensusVersion`.
- **BFT message wiring** (20 points): inbound vote/timeout/syncinfo handlers reach `EngineV2.*Handler`; outbound broadcasts call `p2p.Send`.
- **Sealing trigger pathway** (10 points): some path in `miner/` calls `engine.Seal` for V2 blocks.
- **Cross-cutting hygiene** (5 points): dead-code removed, comments match code, etc.

The score is fast to compute (<10 seconds; pure grep/file existence checks; no chain replay). This is by design — you should iterate ~10-50 times per hour, not 1-2.

For the much-more-expensive correctness gate (does the resulting code actually produce byte-identical blocks?), there's a separate `validate.sh` you can run after a successful iteration. That runs Stage 5 of `VALIDATION_PLAYBOOK_v2.md` and takes hours, not seconds. Don't run it in the inner loop.

## What you may modify

The complete list is in `target.md`. Briefly:

- `consensus/XDPoS/xdpos.go` — wrapper engine
- `consensus/XDPoS/engines/engine_v2/*.go` — V2 engine
- `eth/handler_eth.go`, `eth/handler_xdc.go` — message handlers
- `eth/hooks/*.go` — penalty/reward hooks
- `params/config.go` — chain config (specifically the genesis hash placeholder)
- `miner/*.go` — sealing trigger pathway (touch with care)
- `core/types/block.go` — header type (touch with extreme care; RLP layout is consensus-critical)

Do not modify:

- Anything under `consensus/XDPoS/engines/engine_v1/` — V1 path is for backward compat with already-mined blocks. Changes here can re-divergence the historical chain.
- Anything in `XDPoSChain/` — that's the reference, read-only.
- This directory (`xdpos-autoresearch/`) — except `progress.md` and `log/`.

If you find yourself wanting to modify something not in the allowed list to satisfy a check, **stop and write a note in `log/<timestamp>/blocked.md`** explaining what you wanted to do. Don't expand scope unilaterally.

## Iteration discipline

- **One concern per iteration.** Don't bundle "fix C1.1" with "wire BFT handlers". Reviewers grade per-iteration; small diffs are reversible.
- **Always run measure.sh before AND after.** A patch that reduces score by mistake (e.g., introduces a syntax error, breaks a previously-passing check) must be discarded.
- **Log every iteration, including failures.** A failed attempt teaches the next iteration what NOT to try. Future iterations should grep `log/` to avoid repeating dead ends.
- **Prefer surgical diffs.** A 5-line fix is reviewable; a 200-line refactor is not. If a check requires structural change (e.g., widening `EngineV2Iface`), break it into multiple iterations: first widen the interface (no behavior change), then dispatch one method (small behavior change), then dispatch the next, etc.
- **No new dependencies.** No new Go modules, no new tools. Use what's already in `go.mod`.
- **Compile every diff.** `go build ./consensus/...` must succeed before measure.sh runs. Add to your iteration loop.

## Where to find context

- **Current parity audit (the canonical source of truth):** `/Users/anilchinchawale/github/XDCNetwork/XDC-Geth/CONSENSUS_PARITY_AUDIT_v3.md`. Read this first if you're starting fresh.
- **Detail appendices:** `/Users/anilchinchawale/github/XDCNetwork/XDC-Geth/.audit-v3-drafts/{part1_phases_1-8.md, part2_phases_9-12.md, playbook_extensions.md}`. Cite these in your iteration logs.
- **Companion skills (Claude Code / Hermes):** `/Users/anilchinchawale/github/XDCNetwork/XDC-Geth/skills/consensus-parity-{audit,review,fix}/`. The procedural / classification / verification references are useful even when running here without invoking the skill explicitly.
- **PR review history:** `/Users/anilchinchawale/github/XDCNetwork/XDC-Geth/.pr-reviews/` — what previous PRs got wrong, why they were rejected.

If a check seems "obvious" but you can't see how to fix it, read the audit's per-finding dossier. The audit explains the *why*; the checks just measure the *what*.

## What "done" looks like

`measure.sh` returns a score of 100. At which point:

- All operational fixes landed (sync-side parity is byte-exact for canonical replay).
- All mining-side wrapper methods dispatch by version.
- BFT message wire is bidirectional: inbound packets reach the V2 engine, outbound broadcasts reach peers.
- A sealing trigger pathway exists; geth's miner can drive a V2 block to seal.

Score 100 unlocks the validation gate: run `./validate.sh` to confirm the structural alignment translates to byte-identical block production. That's Stage 5 of the playbook (deterministic mining harness) plus Stage 6 phase 6A (Apothem read-only canary). Both must PASS before declaring GP5 ready for masternode deployment.

## When in doubt

If you're unsure whether a change is correct:

1. Read the equivalent code in `XDPoSChain/` (the reference). Cite `path:line` in both repos in your log.
2. Diff the two functions. The patient should match the reference's behavior on the relevant input.
3. If the diff has more than ~30 lines of change, you're probably trying to do too much in one iteration. Split it.

If the score regresses unexpectedly:

1. `git diff` to see what you actually changed.
2. Read the failing check's script under `checks/` to understand what it's looking for.
3. Most "score regressed by 1 point" failures are due to a check pattern matching too strictly (e.g., grep for `c.EngineV2.Author(header)` and your patch wrote `c.EngineV2.Author( header )`). The fix is either: match the reference style exactly, or update the check to be more flexible. Prefer the former.

## Don't

- **Don't run anything in production.** All work happens against local clones. The `validate.sh` may eventually need xdc07 access, but the inner iteration loop must be local-only.
- **Don't push to remote.** This is a research framework. Commits stay local until a human reviews them and explicitly pushes.
- **Don't disable checks to make the score go up.** That's measurement gaming, not progress. A check that's too strict should be fixed in the check, not bypassed.
- **Don't modify `program.md`** (this file). The human edits this; you read it. If you think this file should change, propose a diff in `log/<timestamp>/program_md_proposal.diff` and explain why.
- **Don't claim "100% parity" without `./validate.sh`.** Score 100 from `measure.sh` is necessary; it is not sufficient. Mining shadow validation is the real gate.

## Logging format

After every iteration, write to `log/<YYYY-MM-DD-HHMM>-<short-slug>/`:

- `attempt.md` — what you tried and why
- `diff.patch` — the actual code change (`git diff > diff.patch`)
- `before.json` — measure.sh output before
- `after.json` — measure.sh output after
- `verdict.md` — kept / discarded, with one-sentence rationale

Append a one-line summary to `progress.md` so the next iteration knows the current state.

That's it. Run `./measure.sh` to see where you stand, then start the loop.