fix(rpc): serialize numeric fields as hex strings

qj0r9j0vc2 · qj0r9j0vc2 · commit 1140ac3ed0e1 · 2026-01-25T15:15:43.000+09:00
diff --git a/crates/rpc/Cargo.toml b/crates/rpc/Cargo.toml
@@ -27,6 +27,7 @@ alloy-rlp = "0.3"
 alloy-rpc-types = { workspace = true }
 alloy-rpc-types-eth = { workspace = true }
 alloy-consensus = { workspace = true }
+alloy-serde = "1"
 
 # Reth primitives for Ethereum compatibility
 reth-primitives = { workspace = true }
diff --git a/crates/rpc/src/adapters.rs b/crates/rpc/src/adapters.rs
@@ -1815,70 +1815,16 @@ impl NetworkApi for StubNetworkApi {
 ///
 /// This is a standalone function for use by the node when broadcasting
 /// new blocks to WebSocket subscribers via `eth_subscribe("newHeads")`.
+///
+/// Returns an `RpcBlock` which serializes all numeric fields as hex strings
+/// following the Ethereum JSON-RPC specification. This ensures compatibility
+/// with block explorers like Blockscout that require strict hex encoding.
 pub fn storage_block_to_rpc_block(
     storage_block: cipherbft_storage::blocks::Block,
-    full_txs: bool,
-) -> Block {
-    use alloy_primitives::{Bloom, B64};
-
-    // Convert transaction hashes to B256
-    let tx_hashes: Vec<B256> = storage_block
-        .transaction_hashes
-        .iter()
-        .map(|h| B256::from(*h))
-        .collect();
-
-    // Build transactions field based on full_txs flag
-    let transactions = if full_txs {
-        // TODO: In the future, this should return full Transaction objects
-        BlockTransactions::Hashes(tx_hashes)
-    } else {
-        BlockTransactions::Hashes(tx_hashes)
-    };
-
-    // Build the consensus header
-    let consensus_header = alloy_consensus::Header {
-        parent_hash: B256::from(storage_block.parent_hash),
-        ommers_hash: B256::from(storage_block.ommers_hash),
-        beneficiary: Address::from(storage_block.beneficiary),
-        state_root: B256::from(storage_block.state_root),
-        transactions_root: B256::from(storage_block.transactions_root),
-        receipts_root: B256::from(storage_block.receipts_root),
-        logs_bloom: Bloom::from_slice(&storage_block.logs_bloom),
-        difficulty: U256::from_be_bytes(storage_block.difficulty),
-        number: storage_block.number,
-        gas_limit: storage_block.gas_limit,
-        gas_used: storage_block.gas_used,
-        timestamp: storage_block.timestamp,
-        extra_data: Bytes::from(storage_block.extra_data.clone()),
-        mix_hash: B256::from(storage_block.mix_hash),
-        nonce: B64::from(storage_block.nonce),
-        base_fee_per_gas: storage_block.base_fee_per_gas,
-        withdrawals_root: None,
-        blob_gas_used: None,
-        excess_blob_gas: None,
-        parent_beacon_block_root: None,
-        requests_hash: None,
-    };
-
-    // Build the RPC header with hash and total difficulty
-    let block_hash = B256::from(storage_block.hash);
-    let total_difficulty = U256::from_be_bytes(storage_block.total_difficulty);
-
-    let rpc_header = Header {
-        hash: block_hash,
-        inner: consensus_header,
-        total_difficulty: Some(total_difficulty),
-        size: None,
-    };
-
-    // Build the final RPC block
-    Block {
-        header: rpc_header,
-        uncles: Vec::new(),
-        transactions,
-        withdrawals: None,
-    }
+    _full_txs: bool,
+) -> crate::types::RpcBlock {
+    // Use the RpcBlock's from_storage constructor for proper hex serialization
+    crate::types::RpcBlock::from_storage(storage_block)
 }
 
 #[cfg(test)]
diff --git a/crates/rpc/src/lib.rs b/crates/rpc/src/lib.rs
@@ -151,6 +151,7 @@ pub mod pubsub;
 pub mod server;
 pub mod traits;
 pub mod txpool;
+pub mod types;
 pub mod web3;
 
 // Core types
@@ -170,6 +171,9 @@ pub use adapters::{EvmExecutionApi, MdbxRpcStorage, PoolMempoolApi, ProviderBase
 // Block conversion utilities for subscription broadcasting
 pub use adapters::storage_block_to_rpc_block;
 
+// Custom RPC types with proper hex serialization
+pub use types::RpcBlock;
+
 // RPC server traits (for method registration)
 pub use eth::EthRpcServer;
 pub use net::NetRpcServer;
diff --git a/crates/rpc/src/pubsub.rs b/crates/rpc/src/pubsub.rs
@@ -12,7 +12,9 @@ use tokio::sync::broadcast;
 use tracing::{debug, trace, warn};
 
 use alloy_primitives::B256;
-use alloy_rpc_types_eth::{Block, Filter, Log, SyncStatus, Transaction};
+use alloy_rpc_types_eth::{Filter, Log, SyncStatus, Transaction};
+
+use crate::types::RpcBlock;
 
 use crate::error::RpcError;
 
@@ -88,7 +90,7 @@ pub struct Subscription {
 #[derive(Debug, Clone)]
 pub enum SubscriptionEvent {
     /// New block header.
-    NewHead(Box<Block>),
+    NewHead(Box<RpcBlock>),
     /// New log entry.
     Log(Box<Log>),
     /// New pending transaction hash.
@@ -106,7 +108,7 @@ pub struct SubscriptionManager {
     /// Counter for generating unique subscription IDs.
     next_id: AtomicU64,
     /// Broadcast channel for new block headers.
-    block_tx: broadcast::Sender<Box<Block>>,
+    block_tx: broadcast::Sender<Box<RpcBlock>>,
     /// Broadcast channel for logs.
     log_tx: broadcast::Sender<Box<Log>>,
     /// Broadcast channel for pending transaction hashes.
@@ -164,7 +166,7 @@ impl SubscriptionManager {
     }
 
     /// Broadcast a new block header to all newHeads subscribers.
-    pub fn broadcast_block(&self, block: Block) {
+    pub fn broadcast_block(&self, block: RpcBlock) {
         let _ = self.block_tx.send(Box::new(block));
     }
 
@@ -184,7 +186,7 @@ impl SubscriptionManager {
     }
 
     /// Subscribe to new block headers channel.
-    pub fn subscribe_blocks(&self) -> broadcast::Receiver<Box<Block>> {
+    pub fn subscribe_blocks(&self) -> broadcast::Receiver<Box<RpcBlock>> {
         self.block_tx.subscribe()
     }
 
diff --git a/crates/rpc/src/types.rs b/crates/rpc/src/types.rs
@@ -0,0 +1,236 @@
+//! Custom RPC types with Ethereum-compatible hex serialization.
+//!
+//! This module provides custom block and header types that serialize numeric fields
+//! as hex strings (e.g., `"0x1fd"` instead of `509`) to comply with the Ethereum
+//! JSON-RPC specification and ensure compatibility with block explorers like Blockscout.
+//!
+//! # Why Custom Types?
+//!
+//! The standard `alloy_consensus::Header` uses `U64HexOrNumber` for numeric fields,
+//! which serializes as integers. While this is valid for deserializing, it causes
+//! compatibility issues with Elixir-based clients (like Blockscout) that expect
+//! strict Ethereum JSON-RPC format with hex-encoded quantities.
+
+use alloy_primitives::{Address, Bloom, Bytes, B256, B64, U256};
+use serde::{Deserialize, Serialize};
+
+/// RPC Block representation with proper hex serialization.
+///
+/// All numeric fields are serialized as hex strings following the Ethereum
+/// JSON-RPC "quantity" format (e.g., `"0x1fd"` for 509).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RpcBlock {
+    /// Block hash
+    pub hash: B256,
+    /// Parent block hash
+    pub parent_hash: B256,
+    /// Ommers/uncles hash (always empty hash in PoS)
+    #[serde(rename = "sha3Uncles")]
+    pub ommers_hash: B256,
+    /// Coinbase/miner address
+    pub miner: Address,
+    /// State root
+    pub state_root: B256,
+    /// Transactions root
+    pub transactions_root: B256,
+    /// Receipts root
+    pub receipts_root: B256,
+    /// Logs bloom filter
+    pub logs_bloom: Bloom,
+    /// Difficulty (always 0 in PoS)
+    #[serde(serialize_with = "serialize_u256_quantity")]
+    pub difficulty: U256,
+    /// Block number
+    #[serde(serialize_with = "alloy_serde::quantity::serialize")]
+    pub number: u64,
+    /// Gas limit
+    #[serde(serialize_with = "alloy_serde::quantity::serialize")]
+    pub gas_limit: u64,
+    /// Gas used
+    #[serde(serialize_with = "alloy_serde::quantity::serialize")]
+    pub gas_used: u64,
+    /// Block timestamp
+    #[serde(serialize_with = "alloy_serde::quantity::serialize")]
+    pub timestamp: u64,
+    /// Extra data
+    pub extra_data: Bytes,
+    /// Mix hash (used in PoW, random value in PoS)
+    pub mix_hash: B256,
+    /// Nonce (always zero bytes in PoS)
+    pub nonce: B64,
+    /// Total difficulty (sum of all block difficulties)
+    #[serde(serialize_with = "serialize_u256_quantity")]
+    pub total_difficulty: U256,
+    /// Base fee per gas (EIP-1559)
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        serialize_with = "alloy_serde::quantity::opt::serialize"
+    )]
+    pub base_fee_per_gas: Option<u64>,
+    /// Block size in bytes (optional)
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        serialize_with = "alloy_serde::quantity::opt::serialize"
+    )]
+    pub size: Option<u64>,
+    /// Withdrawals root (EIP-4895)
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub withdrawals_root: Option<B256>,
+    /// Blob gas used (EIP-4844)
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        serialize_with = "alloy_serde::quantity::opt::serialize"
+    )]
+    pub blob_gas_used: Option<u64>,
+    /// Excess blob gas (EIP-4844)
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        serialize_with = "alloy_serde::quantity::opt::serialize"
+    )]
+    pub excess_blob_gas: Option<u64>,
+    /// Parent beacon block root (EIP-4788)
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub parent_beacon_block_root: Option<B256>,
+    /// Block transactions (hashes or full transactions)
+    pub transactions: Vec<B256>,
+    /// Uncle block hashes (always empty in PoS)
+    pub uncles: Vec<B256>,
+    /// Withdrawals (EIP-4895)
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub withdrawals: Option<Vec<()>>,
+}
+
+/// Serialize U256 as a hex quantity string.
+///
+/// This follows the Ethereum JSON-RPC "quantity" format:
+/// - Values are encoded as hex with "0x" prefix
+/// - Leading zeros are removed (except for 0 which is "0x0")
+fn serialize_u256_quantity<S>(value: &U256, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: serde::Serializer,
+{
+    // Use alloy_primitives built-in serialization which already formats as hex
+    value.serialize(serializer)
+}
+
+impl RpcBlock {
+    /// Create a new RpcBlock from storage block data.
+    ///
+    /// This is the primary constructor for converting internal storage format
+    /// to the RPC-compatible format with proper hex serialization.
+    pub fn from_storage(storage_block: cipherbft_storage::blocks::Block) -> Self {
+        Self {
+            hash: B256::from(storage_block.hash),
+            parent_hash: B256::from(storage_block.parent_hash),
+            ommers_hash: B256::from(storage_block.ommers_hash),
+            miner: Address::from(storage_block.beneficiary),
+            state_root: B256::from(storage_block.state_root),
+            transactions_root: B256::from(storage_block.transactions_root),
+            receipts_root: B256::from(storage_block.receipts_root),
+            logs_bloom: Bloom::from_slice(&storage_block.logs_bloom),
+            difficulty: U256::from_be_bytes(storage_block.difficulty),
+            number: storage_block.number,
+            gas_limit: storage_block.gas_limit,
+            gas_used: storage_block.gas_used,
+            timestamp: storage_block.timestamp,
+            extra_data: Bytes::from(storage_block.extra_data),
+            mix_hash: B256::from(storage_block.mix_hash),
+            nonce: B64::from(storage_block.nonce),
+            total_difficulty: U256::from_be_bytes(storage_block.total_difficulty),
+            base_fee_per_gas: storage_block.base_fee_per_gas,
+            size: None,
+            withdrawals_root: None,
+            blob_gas_used: None,
+            excess_blob_gas: None,
+            parent_beacon_block_root: None,
+            transactions: storage_block
+                .transaction_hashes
+                .iter()
+                .map(|h| B256::from(*h))
+                .collect(),
+            uncles: Vec::new(),
+            withdrawals: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_block_serializes_numbers_as_hex() {
+        let block = RpcBlock {
+            hash: B256::ZERO,
+            parent_hash: B256::ZERO,
+            ommers_hash: B256::ZERO,
+            miner: Address::ZERO,
+            state_root: B256::ZERO,
+            transactions_root: B256::ZERO,
+            receipts_root: B256::ZERO,
+            logs_bloom: Bloom::ZERO,
+            difficulty: U256::ZERO,
+            number: 509,
+            gas_limit: 30_000_000,
+            gas_used: 21000,
+            timestamp: 1706163600,
+            extra_data: Bytes::new(),
+            mix_hash: B256::ZERO,
+            nonce: B64::ZERO,
+            total_difficulty: U256::ZERO,
+            base_fee_per_gas: Some(1_000_000_000),
+            size: None,
+            withdrawals_root: None,
+            blob_gas_used: None,
+            excess_blob_gas: None,
+            parent_beacon_block_root: None,
+            transactions: Vec::new(),
+            uncles: Vec::new(),
+            withdrawals: None,
+        };
+
+        let json = serde_json::to_string(&block).unwrap();
+
+        // Verify numeric fields are hex-encoded
+        assert!(
+            json.contains("\"number\":\"0x1fd\""),
+            "number should be hex: {}",
+            json
+        );
+        assert!(
+            json.contains("\"gasLimit\":\"0x1c9c380\""),
+            "gasLimit should be hex: {}",
+            json
+        );
+        assert!(
+            json.contains("\"gasUsed\":\"0x5208\""),
+            "gasUsed should be hex: {}",
+            json
+        );
+        // 1706163600 = 0x65b1fd90
+        assert!(
+            json.contains("\"timestamp\":\"0x65b1fd90\""),
+            "timestamp should be hex: {}",
+            json
+        );
+        assert!(
+            json.contains("\"baseFeePerGas\":\"0x3b9aca00\""),
+            "baseFeePerGas should be hex: {}",
+            json
+        );
+
+        // Verify hash fields remain as full hex strings with 0x prefix
+        assert!(
+            json.contains(
+                "\"hash\":\"0x0000000000000000000000000000000000000000000000000000000000000000\""
+            ),
+            "hash should be full hex: {}",
+            json
+        );
+    }
+}
