# GP5 Fork vs XDPoSChain v2.6.8: Critical Consensus Divergences

## Summary

Comprehensive line-by-line comparison between official XinFin **XDPoSChain v2.6.8** and our **GP5 xdc-network** fork reveals **4 CRITICAL**, **5 HIGH**, **4 MEDIUM**, and **3 LOW** severity divergences. Several are consensus-critical and could cause forks, state root mismatches, or security vulnerabilities.

**Full Report:** See `RESEARCH_V2_6_8_COMPARISON.md` (1,124 lines, 44KB) in this repo for complete file-by-file analysis.

---

## CRITICAL Issues (Must Fix Before Mainnet)

### 1. `yourturn` Leader Index Calculation Wrong
- **v2.6.8:** `round % Epoch % len(masterNodes)`
- **Our fork:** `round % len(masternodes)` (missing `Epoch` mod!)
- **Impact:** For round ≥ 900, produces **different block proposers** → consensus fork
- **Example:** Epoch=900, len=52, round=1000:
  - v2.6.8: `1000 % 900 % 52 = 48`
  - Our fork: `1000 % 52 = 12`

### 2. `yourturn` Missing Epoch Switch Detection
- **v2.6.8:** Calls `calcMasternodes()` at epoch switches; `GetMasternodes()` otherwise
- **Our fork:** Always uses `snap.NextEpochCandidates` — never recomputes penalties at epoch boundaries
- **Impact:** Epoch switch blocks mined with **wrong validator set**

### 3. `calcMasternodes` First-Epoch Heuristic Fallback
- **v2.6.8:** Uses snapshot candidates for first V2 epoch
- **Our fork:** Overrides with switch block masternodes if candidates < 20 (heuristic)
- **Impact:** **State root divergence** if v2.6.8 and our fork process same first-epoch gap block

### 4. verifyHeader Proposer Check Can Be Skipped
- **v2.6.8:** Always validates proposer; no fallback
- **Our fork:** Falls back to `GetMasternodes` on `calcMasternodes` failure; sets `masternodes = nil` if empty → **skips proposer check entirely**
- **Impact:** Invalid epoch switch blocks could be accepted during sync

---

## HIGH Issues

### 5. Snapshot JSON Tag Mismatch
- **v2.6.8:** `"masterNodes"`
- **Our fork:** `"nextEpochCandidates"`
- **Impact:** Snapshots stored by v2.6.8 **cannot be loaded** by our fork (DB incompatibility)

### 6. Snapshot DB Key Mismatch
- **v2.6.8:** `"XDPoS-V2-" + hash[:]`
- **Our fork:** `"xdpos-v2-snapshot-" + hash.Hex()`
- **Impact:** Completely separate snapshot namespaces — cannot share snapshot data

### 7. `GetCurrentEpochSwitchBlock` Missing `+SwitchEpoch`
- **v2.6.8:** `epochNum = SwitchEpoch + round/Epoch`
- **Our fork:** `epochNum = round/Epoch`
- **Impact:** Wrong epoch numbers for all V2 epochs (off by ~89,300)

### 8. `getEpochSwitchInfo` Missing Penalties/Standbynodes
- **v2.6.8:** Computes and stores `Penalties` and `Standbynodes` in `EpochSwitchInfo`
- **Our fork:** Does NOT populate these fields
- **Impact:** Breaks any RPC/internal logic depending on penalties/standby nodes

### 9. P1 Checkpoint Trie Commit Uses Cached Root
- **v2.6.8:** Commits `header.Root()` directly
- **Our fork:** Commits `XdcGetCachedStateRoot()` (GP5's locally computed root)
- **Impact:** Trie committed under **different root** than block header claims

---

## MEDIUM Issues

10. Missing validator signature length check (≠ 65 accepted)
11. Missing coinbase/validator mismatch check
12. Engine singleton pattern prevents re-initialization
13. `UpdateMasternodes` returns nil silently on non-gap blocks
14. XDCx/lending state verification not ported

## LOW Issues

15. Missing forensics processor (double-signing detection)
16. Missing `GetPenalties` / `GetStandbynodes` RPC endpoints
17. `sigHash` extra hash encoding order differs slightly

---

## Recommended Fix Order

### Phase 1 (P0 — Consensus Critical)
1. Fix `yourturn` leader index: restore `round % Epoch % len`
2. Fix `yourturn` epoch switch: add `isEpochSwitchAtRound` check
3. Fix `calcMasternodes` heuristic: remove or narrow fallback
4. Fix verifyHeader: remove fallback, fail hard on error
5. Fix `GetCurrentEpochSwitchBlock`: add `+ SwitchEpoch`

### Phase 2 (P1 — High Priority)
6. Fix snapshot JSON tag: `"masterNodes"`
7. Fix snapshot DB key: `"XDPoS-V2-"`
8. Fix `getEpochSwitchInfo`: add penalties/standbynodes
9. Review `repairSnapshot`: ensure v2.6.8-compatible output

### Phase 3 (P2 — Medium Priority)
10. Add validator length check
11. Add coinbase/validator mismatch check
12. Remove singleton or add reset capability

---

## References

- **Official v2.6.8:** XinFinOrg/XDPoSChain@`v2.6.8` (commit `146252a`)
- **Our fork:** XDCIndia/go-ethereum@`xdc-network` (commit `37aa211da`)
- **Full research report:** `RESEARCH_V2_6_8_COMPARISON.md` in this repo

---

*Report generated by automated deep research comparing 17+ source files across both codebases.*