Block Synchronization Guide¶

Overview¶

This document provides solutions for block synchronization. All documented issues have been resolved and work out-of-the-box in the current release.

Quick Reference¶

Scenario	Solution	Status
ForkId mismatch at block 0	Pure EIP-2124 validation — genesis ForkId is spec-correct	✅ Resolved
Peers disconnect after handshake	Automatic — bootstrap checkpoints enabled	✅ Fixed
Zero stable peers	Check firewall + manual connections available	✅ Documented

How It Works¶

Fukuii automatically handles ForkId compatibility during initial synchronization. No configuration is needed for new installations.

Comparison with Core-Geth Implementation¶

After comparing with the core-geth reference implementation, the issue has been identified:

Core-Geth ForkID Test Cases for ETC Classic:

// From core-geth core/forkid/forkid_test.go
{19_250_000, 0, ID{Hash: checksumToBytes(0xbe46d57c), Next: 0}}, // Spiral fork and beyond

Our Configuration Analysis:

✅ Genesis Hash: Correct (d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3)

✅ Fork Blocks Configured (from src/main/resources/conf/base/chains/etc-chain.conf): - Homestead: 1,150,000 - EIP-150: 2,500,000 - EIP-155/160: 3,000,000 - Atlantis: 8,772,000 - Agharta: 9,573,000 - Phoenix: 10,500,839 - ECIP-1099: 11,700,000 - Magneto: 13,189,133 - Mystique: 14,525,000 - Spiral: 19,250,000 ✅

✅ Code Implementation: ForkId calculation logic matches core-geth (CRC32 of genesis + fork blocks)

Root Cause: Synced Block Height vs ForkId¶

The ForkId 0xfc64ec04 with next: 1150000 indicates: - Our node is at block 0 (unsynced) - Next fork is Homestead at block 1,150,000 - This matches core-geth's expected behavior for an unsynced node

From core-geth test cases:

{0, 0, ID{Hash: checksumToBytes(0xfc64ec04), Next: 1150000}}, // Unsynced - MATCHES OUR NODE

The peers with ForkID 0xbe46d57c, Next: 0 are fully synced (beyond block 19,250,000).

The issue is NOT a configuration error - our ForkId is correct for block 0!

Why Peers Disconnect¶

Peers may be disconnecting due to:

Overly Strict ForkId Validation: Some peer implementations may reject nodes that are "too far behind"
Configuration Mismatch Detection: Peers might be detecting subtle differences in fork configuration
Network Segmentation: Temporary network conditions causing validation failures

Option 1: Verify ForkId Calculation Matches Core-Geth¶

The configuration is already correct. To verify the ForkId calculation at various block heights:

# Expected ForkIds at different sync stages (from core-geth):
Block 0:          0xfc64ec04, next: 1150000    (Frontier)
Block 1,150,000:  0x97c2c34c, next: 2500000    (Homestead)
Block 2,500,000:  0x250c3c6a, next: 3000000    (EIP-150)
Block 3,000,000:  0x43ea6b9e, next: 8772000    (EIP-155/160)
Block 8,772,000:  0x13d96d70, next: 9573000    (Atlantis)
Block 9,573,000:  0xef35b156, next: 10500839   (Agharta)
Block 10,500,839: 0x9007bfcc, next: 11700000   (Phoenix)
Block 11,700,000: 0xdb63a1ca, next: 13189133   (ECIP-1099)
Block 13,189,133: 0x0f6bf187, next: 14525000   (Magneto)
Block 14,525,000: 0x7fd1bb25, next: 19250000   (Mystique)
Block 19,250,000: 0xbe46d57c, next: 0          (Spiral - fully synced)

Option 2: Investigate Peer Compatibility¶

Since our ForkId is correct for block 0, investigate why peers reject us:

Check Peer Implementation: Verify the peer software versions accepting connections
Network Conditions: Ensure stable network connectivity to bootstrap nodes
Firewall Rules: Verify TCP/UDP ports 30303 and 30303 are properly configured
DNS Resolution: Ensure bootstrap node addresses resolve correctly

Option 3: Alternative Bootstrap Strategy¶

If ForkId validation is overly strict on some peers:

Targeted Peering: Connect to known-compatible peers explicitly
Bootstrap Nodes: Ensure fukuii.pw bootstrap nodes are accessible
Peer Selection: May need to implement retry logic for peer selection

Option 4: Enable Fast Sync¶

Consider enabling fast/snap sync to quickly advance past block 0: - This would change ForkId from 0xfc64ec04 to a later value - May improve peer acceptance rates - Check use-bootstrap-checkpoints = true in configuration

Verification Steps¶

After updating configuration:

Check ForkId at Startup:
```
./bin/fukuii etc 2>&1 | grep -A 2 "Sending status"
```
At block 0, should show: forkId=ForkId(0xfc64ec04, Some(1150000)) for ETC mainnet; the ForkId advances per EIP-2124 as the node syncs
Monitor Peer Connections:
```
./bin/fukuii etc 2>&1 | grep -E "handshaked|disconnect"
```
Should see sustained peer connections, not immediate disconnects

Verify Sync Progress:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' http://localhost:8546

Additional Notes¶

The message "Unknown network message type: 16" in logs is harmless - it's the normal decoder chain trying NetworkMessageDecoder first, then falling back to ETH68MessageDecoder for Status (code 0x10)
The Warning "Peer sent uncompressed RLP data despite p2pVersion >= 4" is a protocol deviation by the peer but doesn't cause disconnection
Disconnect reason 0x10 specifically means ForkId incompatibility in practice, though spec says "other subprotocol reason"
Our ForkId 0xfc64ec04 is CORRECT for block 0 - it matches core-geth's expected value for unsynced nodes
The issue may be that some peers overly strict ForkId validation rejecting nodes "too far behind"

Core-Geth Comparison¶

Full fork list comparison with core-geth params/config_classic.go:

Fork	Block Number	Core-Geth	Fukuii
Homestead (EIP-2/7)	1,150,000	✅	✅
EIP-150	2,500,000	✅	✅
EIP-155/160	3,000,000	✅	✅
ECIP-1010 Pause	3,000,000	✅	✅
ECIP-1017	5,000,000	✅	✅
Disposal	5,900,000	✅	✅
Atlantis (EIP-158/161/170)	8,772,000	✅	✅
Agharta (Constantinople)	9,573,000	✅	✅
Phoenix (Istanbul)	10,500,839	✅	✅
ECIP-1099 (Etchash)	11,700,000	✅	✅
Magneto (Berlin)	13,189,133	✅	✅
Mystique (London partial)	14,525,000	✅	✅
Spiral (Shanghai partial)	19,250,000	✅	✅

Result: Configuration matches core-geth perfectly. ForkId calculation is correct.

Current Behavior: Pure EIP-2124 ForkId Validation¶

Fukuii implements pure EIP-2124 ForkId validation with no workarounds. The ForkId is always calculated from the node's actual chain head (ForkId.create() in src/main/scala/com/chipprbots/ethereum/forkid/ForkId.scala):

At block 0 (unsynced), ETC mainnet reports ForkId(0xfc64ec04, Some(1150000)) — the CRC32 of the genesis hash, with Homestead (1,150,000) as the next fork. This matches core-geth's expected value for an unsynced node.
As the node syncs past each fork block, the ForkId hash and next value advance per EIP-2124.
A fully synced ETC mainnet node (past Spiral at 19,250,000) reports ForkId(0xbe46d57c, None).

Per EIP-2124, remote peers must accept a node advertising the genesis ForkId as a stale-but-compatible peer that can still sync. No configuration is required.

Understanding the Issue (Historical Context)¶

The ForkId mismatch issue occurred because: 1. Our node (at block 0) technically should report ForkId 0xfc64ec04, next: 1150000 per EIP-2124 2. Peer nodes (at block 19,250,000+) report ForkId 0xbe46d57c, next: None 3. Peers disconnected with reason code 0x10 due to perceived incompatibility

This was a peer-side strictness issue. Our ForkId was (and is) correct per EIP-2124; some peer implementations were observed disconnecting nodes that were far behind, despite the spec requiring acceptance of stale-but-compatible peers.

Optional Measures¶

The following measures are not required for ForkId compatibility, but may still be useful in some situations:

Bootstrap Checkpoints¶

Bootstrap checkpoints are still recommended for faster initial sync:

# In etc-chain.conf (already enabled by default)
use-bootstrap-checkpoints = true

Manual Peer Connections (Optional)¶

If you experience connection issues, you can still add known-stable peers:

# In application.conf
fukuii.network.peer {
  manual-connections = [
    "enode://fbcd6fc04fa7ea897558c3f5edf1cd192e3b2c3b5b9b3d00be179b2e9d04e623e017ed6ce6a1369fff126661afa1c5caa12febce92dcb70ff1352b86e9ebb44f@18.193.251.235:30303?discport=30303",
    "enode://1619217a01fb87a745bb104872aa84314a2d42d99c7b915cd187245bfd898d679cbf78b3ea950c32051db860e2c4e3fe7d6329107587be33ab37541ca65046f91@18.198.165.189:30303?discport=30303",
  ]
}

Current Status¶

Issue: RESOLVED ✅

Fukuii reports the spec-correct EIP-2124 ForkId at every block height, including block 0. No configuration changes required.

Verification¶

To verify ForkId reporting:

Check ForkId at Startup:
```
./bin/fukuii etc 2>&1 | grep "Sending status"
```
At block 0, should show: forkId=ForkId(0xfc64ec04, Some(1150000)) for ETC mainnet (the genesis ForkId per EIP-2124)
Monitor Peer Connections:
```
./bin/fukuii etc 2>&1 | grep -E "handshaked|disconnect"
```
Should see sustained peer connections without immediate 0x10 disconnects