# Target — what the agent may modify

The agent may freely edit these files in the patient repo. Edits should be surgical (minimal diff), match the reference's behavior, and pass `./measure.sh` afterward.

## Wrapper consensus engine

- `consensus/XDPoS/xdpos.go` — wrapper methods (Author, Prepare, Finalize, Seal, etc.); `EngineV2Iface` declaration.

## V2 engine

- `consensus/XDPoS/engines/engine_v2/engine.go` — main engine, `initial`, `Prepare`, `Seal`, `Finalize`, `Author`, `getSnapshot`, `repairSnapshot`, `getEpochSwitchInfo`, `IsEpochSwitch`, `calcMasternodes`, `GetMasternodesFromEpochSwitchHeader`.
- `consensus/XDPoS/engines/engine_v2/verifyHeader.go` — header validation including bulk-sync fallback.
- `consensus/XDPoS/engines/engine_v2/snapshot.go` — `SnapshotV2` struct, load/store/new.
- `consensus/XDPoS/engines/engine_v2/utils.go` — sigHash, ecrecover, helpers.
- `consensus/XDPoS/engines/engine_v2/timeout.go` — timeout / TC handling.
- `consensus/XDPoS/engines/engine_v2/vote.go` — vote handling, QC formation.
- `consensus/XDPoS/engines/engine_v2/epochSwitch.go` — epoch switch logic.
- `consensus/XDPoS/engines/engine_v2/forensics.go` — byzantine detection (dormant in both — leave dormant).

## Hooks

- `eth/hooks/hooks.go`
- `eth/hooks/engine_v2_hooks.go` — note: `eth/backend.go:315-433` is the LIVE V2 HookPenalty; the file at `eth/hooks/engine_v2_hooks.go` may have a dead duplicate that should be deleted.

## Network handlers (BFT message wire)

- `eth/handler_eth.go` — inbound VotePacket / TimeoutPacket / SyncInfoPacket dispatch.
- `eth/handler_xdc.go` — outbound BroadcastVote / BroadcastTimeout / BroadcastSyncInfo.
- `eth/protocols/eth/protocol.go` — protocol constants (touch with care; affects wire compat).
- May need to create `eth/bft/handler.go` (port of `XDPoSChain/eth/bft/bft_handler.go`).

## Chain config

- `params/config.go` — specifically the placeholder Apothem genesis hash at line 40.

## Miner / sealing trigger

- `miner/worker.go` — geth-1.17 worker pipeline.
- May need to create `miner/xdc_agent.go` — port of v2.6.8's `miner/agent.go` for sealing-driven mode.

## Off-limits

- `consensus/XDPoS/engines/engine_v1/*.go` — V1 path is for already-mined blocks. Changes here can re-divergence the historical chain.
- `core/types/block.go` — header RLP layout. Don't touch unless you're sure of the consequences (consensus-critical bytes).
- `XDPoSChain/` — read-only reference.
- `xdpos-autoresearch/` — except `progress.md` and `log/`.
- `CONSENSUS_PARITY_AUDIT_v3.md`, `VALIDATION_PLAYBOOK_v2.md`, `.audit-v3-drafts/` — historical / human-edited docs.
- `.pr-reviews/` — historical PR review records.

## Worktree convention

For each iteration, create a temp branch from `xdc-network`:

```bash
cd /Users/anilchinchawale/github/XDCNetwork/XDC-Geth
git worktree add /tmp/xdpos-iter-$(date +%s) xdc-network
cd /tmp/xdpos-iter-*
# make changes
# run measure.sh from xdpos-autoresearch
# if good, cherry-pick back to a feature branch on xdc-network
# clean up: git worktree remove /tmp/xdpos-iter-*
```

This keeps the main worktree clean.