# XDC Cross-Client Test Vectors (#84)

This directory contains byte-level consensus compatibility test vectors for the XDC Network.
All XDC clients (GP5/go-ethereum, Erigon-XDC, Nethermind-XDC, Reth-XDC) must produce
**identical output** for every vector in this suite.

## Format

Each vector file is a JSON document with the following structure:

```json
{
  "name": "human-readable test name",
  "description": "what this vector tests",
  "network": "mainnet|apothem",
  "input": { ... },
  "expected": { ... }
}
```

## Vector Categories

| File | Description |
|---|---|
| `extra_data_v1.json` | V1 ExtraData encode/decode round-trip |
| `extra_data_v2.json` | V2 ExtraData encode/decode round-trip |
| `vote_sig_hash.json` | Vote signing hash computation |
| `timeout_sig_hash.json` | Timeout signing hash computation |
| `qc_rlp.json` | QuorumCert RLP encoding |
| `tc_rlp.json` | TimeoutCert RLP encoding |
| `extract_addresses.json` | ExtractAddressesFromReturn ABI decoder |

## How to Add Vectors

1. Run the reference implementation (XDPoSChain v2.6.8) to produce expected outputs.
2. Add the vector JSON with both `input` and `expected` fields.
3. Run `go test -run TestCrossClientVectors ./consensus/XDPoS/...` to validate.

## Running the Suite

```bash
# Unit validation (always runs):
go test -run TestCrossClientVectors ./consensus/XDPoS/...

# Against a specific client RPC:
CROSS_CLIENT_RPC=http://erigon-xdc:8545 go test -run TestCrossClientVectors_Remote ./consensus/XDPoS/...
```