node/exts/evm-sync: Add Arbitrum One, Arbitrum Sepolia and Hardhat chain support with StartBlock configuration

[sapience]

Description

This PR adds support for Arbitrum One, Arbitrum Sepolia and Hardhat chains to the EVM sync extension, and introduces a StartBlock configuration option to specify the starting block number for chain synchronization. Additionally, it includes several bug fixes and improvements to the listener implementation.

Key Changes:

• Added hardhat chain (chain ID: 31337) with 12 required confirmations
• Added arbitrum_one chain (chain ID: 42161) with 4 required confirmations
• Added arbitrum_sepolia chain (chain ID: 421614) with 2 required confirmations
• Added StartBlock configuration option to ERC20BridgeConfig for per-chain starting block configuration
• Fixed BlockSyncChuckSize to use the actual chain parameter instead of hardcoded Ethereum reference
• Fixed processEvents to update last seen height even when no logs are found
• Changed "received new block" log level from Info to Debug to reduce log verbosity

Motivation and Context

This change is required to:

1. Support additional EVM chains: Enable kwil-db to sync with Arbitrum One, Arbitrum Sepolia testnet and Hardhat local development networks, expanding the supported chain ecosystem.

2. Flexible sync configuration: The StartBlock configuration allows operators to specify a custom starting block for initial synchronization or recovery scenarios, rather than always starting from block 0. This is particularly useful when:

   • Setting up a new instance and wanting to skip historical blocks
   • Recovering from a sync issue and needing to resume from a specific block
   • The eventstore has no last seen height (returns 0)

3. Bug fixes: Addresses issues where chain-specific configurations were incorrectly hardcoded and where the last seen height wasn't updated in certain edge cases.

How Has This Been Tested?

• Unit tests pass: task test:unit
• Acceptance tests pass: task test:act
• Code formatted: task fmt
• Linting passes: task lint
• Manual testing with Hardhat local network
• Manual testing with Arbitrum Sepolia testnet
• Verified StartBlock configuration works correctly when eventstore has no last seen height

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update (including inline docs)
• Other (please describe):

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

Checklist Explanation:

• Documentation: The StartBlock configuration option is documented inline in the code with a comment. If there's external documentation that needs updating, please let me know.
• Tests: Additional tests should be added to verify the new chain support and StartBlock functionality. This should include:
  • Unit tests for chain validation
  • Integration tests for StartBlock configuration
  • Tests for the bug fixes (BlockSyncChuckSize chain-specific behavior, last seen height update)

How to Review this PR:

Review Order:

1. config/config.go: Review the new StartBlock configuration field and its TOML comment
2. node/exts/evm-sync/chains/chains.go: Verify the new chain definitions (Hardhat and Arbitrum Sepolia) and chain validation logic
3. node/exts/evm-sync/listener.go: Focus on:
   • The StartBlock configuration parsing and validation logic
   • The bug fix for BlockSyncChuckSize (line ~124: changed from hardcoded chains.Ethereum.String() to chain.String())
   • The bug fix for updating last seen height when no logs are found
   • The StartBlock fallback logic when eventstore returns 0
   • Log level change from Info to Debug

Key Design Decisions:

• StartBlock defaults to 0 if not configured, maintaining backward compatibility
• StartBlock is only used when eventstore has no last seen height (returns 0), ensuring it doesn't override existing sync state
• Chain-specific configurations now properly use the chain parameter instead of hardcoded values

Additional Information:

Configuration Example:

[erc20_bridge]
start_block = { hardhat = "1000", arbitrum_sepolia = "50000" }
rpc = { hardhat = "http://localhost:8545", arbitrum_sepolia = "https://sepolia-rollup.arbitrum.io/rpc" }

Summary by CodeRabbit

• New Features
  • Added support for Hardhat (ID 31337) and Arbitrum Sepolia (ID 421614) blockchain networks.
  • Enabled per-chain block synchronization configuration with customizable starting block positions for each supported network.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds three chains (Hardhat, Arbitrum Sepolia, Arbitrum One), enables per-chain BlockSyncChunkSize and StartBlock configuration, propagates StartBlock into chainConfig, changes block/log logging level, and updates last-seen height even when no logs are found.

Changes

Cohort / File(s)	Summary
Chain definitions node/exts/evm-sync/chains/chains.go	Added Hardhat (31337, 12 confirmations), ArbitrumSepolia (421614, 2 confirmations), and ArbitrumOne (42161, 4 confirmations); extended chain constants and Valid() handling.
Configuration schema config/config.go	Added StartBlock map[string]string field to ERC20BridgeConfig for per-chain start block configuration (toml:"start_block").
Listener and sync logic node/exts/evm-sync/listener.go	getChainConf now selects BlockSyncChunkSize by per-chain key; parses/validates per-chain StartBlock (default "0", non-negative, converted to int64) and stores it in chainConfig; logs starting block and lowers per-block log level to debug; processEvents updates last-seen height even when zero logs are found.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Inspect StartBlock parsing and non-negative validation in listener.go.
• Verify getChainConf uses consistent chain identifier keys for per-chain settings.
• Review processEvents change that updates last-seen height on zero-log batches and the logging level change.

Poem

🐰 I nibble config lines so neat,
Three chains hop in — what a treat!
StartBlocks set for each small track,
Last-seen moves forward, never back.
Carrots for sync, and code in my hat 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes all three major changes: adding Arbitrum One, Arbitrum Sepolia, and Hardhat chain support, plus the StartBlock configuration feature.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

node/exts/evm-sync/chains/chains.go (1)

57-62: Consider naming consistency for chain identifiers.

The ArbitrumSepolia constant uses "arbitrumsepolia" (no separator) while BaseSepolia uses "base-sepolia" (hyphen). While this doesn't break functionality, consistent naming conventions improve clarity. Consider using either "arbitrum-sepolia" or updating BaseSepolia to "basesepolia" for consistency.

node/exts/evm-sync/listener.go (1)

199-203: Consider clarifying the log message for better debugging.

Line 199 logs "StartBlock" but actually logs the startBlock variable from eventstore (before applying the configured StartBlock). Consider logging after the StartBlock logic is applied, or clarifying the message to indicate it's the "initial startBlock from eventstore" to avoid confusion during debugging.

Apply this diff to improve clarity:

 	startBlock, err := getLastSeenHeight(ctx, eventstore, i.orderedSyncTopic)
 	if err != nil {
 		return fmt.Errorf("failed to get last seen height: %w", err)
 	}
-	logger.Infof("StartBlock of %s: %d", i.orderedSyncTopic, startBlock)
 	// If eventstore has no last seen height (returns 0), use StartBlock from config if configured
 	if startBlock == 0 && i.chainConf.StartBlock > 0 {
 		startBlock = i.chainConf.StartBlock
 	}
+	logger.Infof("Starting sync for %s from block: %d", i.orderedSyncTopic, startBlock)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d43bfe5 and 0617c97.

📒 Files selected for processing (3)

• config/config.go (1 hunks)
• node/exts/evm-sync/chains/chains.go (3 hunks)
• node/exts/evm-sync/listener.go (6 hunks)

🔇 Additional comments (8)

config/config.go (1)

619-619: LGTM! StartBlock field addition is well-structured.

The new field is properly annotated with TOML tags and includes a clear comment explaining its purpose and format. The validation is appropriately handled at the usage site in listener.go.

node/exts/evm-sync/chains/chains.go (2)

38-47: LGTM! New chain definitions are correctly configured.

Both Hardhat (local development chain) and Arbitrum Sepolia (L2 testnet) are properly defined with accurate chain IDs and appropriate confirmation requirements.

---

68-75: LGTM! Valid() method correctly includes new chains.

The validation logic properly recognizes Hardhat and ArbitrumSepolia as valid chains.

node/exts/evm-sync/listener.go (5)

124-124: Excellent fix! BlockSyncChunkSize now correctly uses per-chain configuration.

This change ensures each chain uses its own configured chunk size rather than a hardcoded key, which is essential for supporting chains with different block production rates and history sizes.

---

138-149: LGTM! StartBlock parsing and validation is robust.

The implementation properly reads the per-chain StartBlock configuration, provides sensible defaults, validates the value, and includes clear error messages with chain context.

---

169-171: LGTM! StartBlock field is well-documented.

The field addition includes clear documentation explaining its purpose and default behavior.

---

254-254: LGTM! Log level change reduces noise.

Changing the "received new block" message to Debug level is appropriate since block receipts are frequent and don't require Info-level visibility during normal operation.

---

280-282: Excellent bug fix! Progress tracking now works correctly for empty block ranges.

This change ensures the last seen height is updated even when no logs are found in a block range. Without this fix, the listener could repeatedly process the same empty range, stalling progress and wasting resources. This is particularly important for chains or time periods with sparse events.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
@sapience	❌ Missing	-	⚠️ Submit time	-

[MicBun]

Hi @sapience, thank you for contributing! I can see from the PR description what you're trying to fix. Since this involves both adding a feature and fixing a bug, could you create a GitHub issue with more details? That way we can have a proper discussion about it.

Also, if the PR is still in progress, please mark it as a draft since I see you're still actively committing changes.