1use std::fmt::Display;
17
18use alloy_primitives::U256;
19use nautilus_core::UnixNanos;
20use serde::{Deserialize, Serialize};
21use ustr::Ustr;
22
23use crate::defi::{
24 Blockchain,
25 hex::{
26 deserialize_hex_number, deserialize_hex_timestamp, deserialize_opt_hex_u64,
27 deserialize_opt_hex_u256,
28 },
29};
30
31#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
33pub struct BlockPosition {
34 pub number: u64,
36 pub transaction_hash: String,
38 pub transaction_index: u32,
40 pub log_index: u32,
42}
43
44impl BlockPosition {
45 #[must_use]
47 pub fn new(number: u64, transaction_hash: String, index: u32, log_index: u32) -> Self {
48 Self {
49 number,
50 transaction_hash,
51 transaction_index: index,
52 log_index,
53 }
54 }
55}
56
57#[derive(Debug, Clone, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase")]
60#[cfg_attr(
61 feature = "python",
62 pyo3::pyclass(module = "nautilus_trader.core.nautilus_pyo3.model", from_py_object)
63)]
64#[cfg_attr(
65 feature = "python",
66 pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.model")
67)]
68pub struct Block {
69 #[serde(skip)]
71 pub chain: Option<Blockchain>, pub hash: String,
74 #[serde(deserialize_with = "deserialize_hex_number")]
76 pub number: u64,
77 pub parent_hash: String,
79 pub miner: Ustr,
81 #[serde(deserialize_with = "deserialize_hex_number")]
83 pub gas_limit: u64,
84 #[serde(deserialize_with = "deserialize_hex_number")]
86 pub gas_used: u64,
87 #[serde(default, deserialize_with = "deserialize_opt_hex_u256")]
89 pub base_fee_per_gas: Option<U256>,
90 #[serde(default, deserialize_with = "deserialize_opt_hex_u256")]
92 pub blob_gas_used: Option<U256>,
93 #[serde(default, deserialize_with = "deserialize_opt_hex_u256")]
95 pub excess_blob_gas: Option<U256>,
96 #[serde(default, deserialize_with = "deserialize_opt_hex_u256")]
98 pub l1_gas_price: Option<U256>,
99 #[serde(default, deserialize_with = "deserialize_opt_hex_u64")]
101 pub l1_gas_used: Option<u64>,
102 #[serde(default, deserialize_with = "deserialize_opt_hex_u64")]
104 pub l1_fee_scalar: Option<u64>,
105 #[serde(deserialize_with = "deserialize_hex_timestamp")]
107 pub timestamp: UnixNanos,
108}
109
110impl Block {
111 #[expect(clippy::too_many_arguments)]
113 #[must_use]
114 pub fn new(
115 hash: String,
116 parent_hash: String,
117 number: u64,
118 miner: Ustr,
119 gas_limit: u64,
120 gas_used: u64,
121 timestamp: UnixNanos,
122 chain: Option<Blockchain>,
123 ) -> Self {
124 Self {
125 chain,
126 hash,
127 parent_hash,
128 number,
129 miner,
130 gas_used,
131 gas_limit,
132 timestamp,
133 base_fee_per_gas: None,
134 blob_gas_used: None,
135 excess_blob_gas: None,
136 l1_gas_price: None,
137 l1_gas_used: None,
138 l1_fee_scalar: None,
139 }
140 }
141
142 #[must_use]
148 pub fn chain(&self) -> Blockchain {
149 if let Some(chain) = self.chain {
150 chain
151 } else {
152 panic!("Must have the `chain` field set")
153 }
154 }
155
156 pub fn set_chain(&mut self, chain: Blockchain) {
157 self.chain = Some(chain);
158 }
159
160 #[must_use]
162 pub fn with_base_fee(mut self, fee: U256) -> Self {
163 self.base_fee_per_gas = Some(fee);
164 self
165 }
166
167 #[must_use]
169 pub fn with_blob_gas(mut self, used: U256, excess: U256) -> Self {
170 self.blob_gas_used = Some(used);
171 self.excess_blob_gas = Some(excess);
172 self
173 }
174
175 #[must_use]
177 pub fn with_l1_fee_components(mut self, price: U256, gas_used: u64, scalar: u64) -> Self {
178 self.l1_gas_price = Some(price);
179 self.l1_gas_used = Some(gas_used);
180 self.l1_fee_scalar = Some(scalar);
181 self
182 }
183}
184
185impl PartialEq for Block {
186 fn eq(&self, other: &Self) -> bool {
187 self.hash == other.hash
188 }
189}
190
191impl Eq for Block {}
192
193impl Display for Block {
194 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
195 write!(
196 f,
197 "Block(chain={}, number={}, timestamp={}, hash={})",
198 self.chain(),
199 self.number,
200 self.timestamp.to_rfc3339(),
201 self.hash
202 )
203 }
204}
205
206#[cfg(test)]
207mod tests {
208 use alloy_primitives::U256;
209 use chrono::{TimeZone, Utc};
210 use nautilus_core::UnixNanos;
211 use rstest::{fixture, rstest};
212 use ustr::Ustr;
213
214 use super::Block;
215 use crate::defi::{Blockchain, chain::chains, rpc::RpcNodeWssResponse};
216
217 #[fixture]
218 fn eth_rpc_block_response() -> String {
219 r#"{
221 "jsonrpc":"2.0",
222 "method":"eth_subscription",
223 "params":{
224 "subscription":"0xe06a2375238a4daa8ec823f585a0ef1e",
225 "result":{
226 "baseFeePerGas":"0x1862a795",
227 "blobGasUsed":"0xc0000",
228 "difficulty":"0x0",
229 "excessBlobGas":"0x4840000",
230 "extraData":"0x546974616e2028746974616e6275696c6465722e78797a29",
231 "gasLimit":"0x223b4a1",
232 "gasUsed":"0xde3909",
233 "hash":"0x71ece187051700b814592f62774e6ebd8ebdf5efbb54c90859a7d1522ce38e0a",
234 "miner":"0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97",
235 "mixHash":"0x43adbd4692459c8820b0913b0bc70e8a87bed2d40c395cc41059aa108a7cbe84",
236 "nonce":"0x0000000000000000",
237 "number":"0x1542e9f",
238 "parentBeaconBlockRoot":"0x58673bf001b31af805fb7634fbf3257dde41fbb6ae05c71799b09632d126b5c7",
239 "parentHash":"0x2abcce1ac985ebea2a2d6878a78387158f46de8d6db2cefca00ea36df4030a40",
240 "receiptsRoot":"0x35fead0b79338d4acbbc361014521d227874a1e02d24342ed3e84460df91f271",
241 "sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
242 "stateRoot":"0x99f29ee8ed6622c6a1520dca86e361029605f76d2e09aa7d3b1f9fc8b0268b13",
243 "timestamp":"0x6801f4bb",
244 "transactionsRoot":"0x9484b18d38886f25a44b465ad0136c792ef67dd5863b102cab2ab7a76bfb707d",
245 "withdrawalsRoot":"0x152f0040f4328639397494ef0d9c02d36c38b73f09588f304084e9f29662e9cb"
246 }
247 }
248 }"#.to_string()
249 }
250
251 #[fixture]
252 fn polygon_rpc_block_response() -> String {
253 r#"{
255 "jsonrpc": "2.0",
256 "method": "eth_subscription",
257 "params": {
258 "subscription": "0x20f7c54c468149ed99648fd09268c903",
259 "result": {
260 "baseFeePerGas": "0x19e",
261 "difficulty": "0x18",
262 "gasLimit": "0x1c9c380",
263 "gasUsed": "0x1270f14",
264 "hash": "0x38ca655a2009e1748097f5559a0c20de7966243b804efeb53183614e4bebe199",
265 "miner": "0x0000000000000000000000000000000000000000",
266 "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
267 "nonce": "0x0000000000000000",
268 "number": "0x43309ed",
269 "parentHash": "0xf25e108267e3d6e1e4aaf4e329872273f2b1ad6186a4a22e370623aa8d021c50",
270 "receiptsRoot": "0xfffb93a991d15b9689536e59f20564cc49c254ec41a222d988abe58d2869968c",
271 "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
272 "stateRoot": "0xe66a9bc516bde8fc7b8c1ba0b95bfea0f4574fc6cfe95c68b7f8ab3d3158278d",
273 "timestamp": "0x680250d5",
274 "totalDifficulty": "0x505bd180",
275 "transactionsRoot": "0xd9ebc2fd5c7ce6f69ab2e427da495b0b0dff14386723b8c07b347449fd6293a6"
276 }
277 }
278 }"#.to_string()
279 }
280
281 #[fixture]
282 fn base_rpc_block_response() -> String {
283 r#"{
284 "jsonrpc":"2.0",
285 "method":"eth_subscription",
286 "params":{
287 "subscription":"0xeb7d715d93964e22b2d99192791ca984",
288 "result":{
289 "baseFeePerGas":"0xaae54",
290 "blobGasUsed":"0x0",
291 "difficulty":"0x0",
292 "excessBlobGas":"0x0",
293 "extraData":"0x00000000fa00000002",
294 "gasLimit":"0x7270e00",
295 "gasUsed":"0x56fce26",
296 "hash":"0x14575c65070d455e6d20d5ee17be124917a33ce4437dd8615a56d29e8279b7ad",
297 "logsBloom":"0x02bcf67d7b87f2d884b8d56bbe3965f6becc9ed8f9637ffc67efdffcef446cf435ffec7e7ce8e4544fe782bb06ef37afc97687cbf3c7ee7e26dd12a8f1fd836bc17dd2fd64fce3ef03bc74d8faedb07dddafe6f2cedff3e6f5d8683cc2ef26f763dee76e7b6fdeeade8c8a7cec7a5fdca237be97be2efe67dc908df7ce3f94a3ce150b2a9f07776fa577d5c52dbffe5bfc38bbdfeefc305f0efaf37fba3a4cdabf366b17fcb3b881badbe571dfb2fd652e879fbf37e88dbedb6a6f9f4bb7aef528e81c1f3cda38f777cb0a2d6f0ddb8abcb3dda5d976541fa062dba6255a7b328b5fdf47e8d6fac2fc43d8bee5936e6e8f2bff33526fdf6637f3f2216d950fef",
298 "miner":"0x4200000000000000000000000000000000000011",
299 "mixHash":"0xeacd829463c5d21df523005d55f25a0ca20474f1310c5c7eb29ff2c479789e98",
300 "nonce":"0x0000000000000000",
301 "number":"0x1bca2ac",
302 "parentBeaconBlockRoot":"0xfe4c48425a274a6716c569dfa9c238551330fc39d295123b12bc2461e6f41834",
303 "parentHash":"0x9a6ad4ffb258faa47ecd5eea9e7a9d8fa1772aa6232bc7cb4bbad5bc30786258",
304 "receiptsRoot":"0x5fc932dd358c33f9327a704585c83aafbe0d25d12b62c1cd8282df8b328aac16",
305 "sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
306 "stateRoot":"0xd2d3a6a219fb155bfc5afbde11f3161f1051d931432ccf32c33affe54176bb18",
307 "timestamp":"0x6803a23b",
308 "transactionsRoot":"0x59726fb9afc101cd49199c70bbdbc28385f4defa02949cb6e20493e16035a59d",
309 "withdrawalsRoot":"0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
310 }
311 }
312 }"#.to_string()
313 }
314
315 #[fixture]
316 fn arbitrum_rpc_block_response() -> String {
317 r#"{
319 "jsonrpc":"2.0",
320 "method":"eth_subscription",
321 "params":{
322 "subscription":"0x0c5a0b38096440ef9a30a84837cf2012",
323 "result":{
324 "baseFeePerGas":"0x989680",
325 "difficulty":"0x1",
326 "extraData":"0xc66cd959dcdc1baf028efb61140d4461629c53c9643296cbda1c40723e97283b",
327 "gasLimit":"0x4000000000000",
328 "gasUsed":"0x17af4",
329 "hash":"0x724a0af4720fd7624976f71b16163de25f8532e87d0e7058eb0c1d3f6da3c1f8",
330 "miner":"0xa4b000000000000000000073657175656e636572",
331 "mixHash":"0x0000000000023106000000000154528900000000000000200000000000000000",
332 "nonce":"0x00000000001daa7c",
333 "number":"0x138d1ab4",
334 "parentHash":"0xe7176e201c2db109be479770074ad11b979de90ac850432ed38ed335803861b6",
335 "receiptsRoot":"0xefb382e3a4e3169e57920fa2367fc81c98bbfbd13611f57767dee07d3b3f96d4",
336 "sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
337 "stateRoot":"0x57e5475675abf1ec4c763369342e327a04321d17eeaa730a4ca20a9cafeee380",
338 "timestamp":"0x6803a606",
339 "totalDifficulty":"0x123a3d6c",
340 "transactionsRoot":"0x710b520177ecb31fa9092d16ee593b692070912b99ddd9fcf73eb4e9dd15193d"
341 }
342 }
343 }"#.to_string()
344 }
345
346 #[rstest]
347 fn test_block_set_chain() {
348 let mut block = Block::new(
349 "0x1234567890abcdef".to_string(),
350 "0xabcdef1234567890".to_string(),
351 12345,
352 Ustr::from("0x742E4422b21FB8B4dF463F28689AC98bD56c39e0"),
353 21000,
354 20000,
355 UnixNanos::from(1_640_995_200_000_000_000u64),
356 None,
357 );
358
359 assert!(block.chain.is_none());
360
361 let chain = Blockchain::Ethereum;
362 block.set_chain(chain);
363
364 assert_eq!(block.chain, Some(chain));
365 }
366
367 #[rstest]
368 fn test_ethereum_block_parsing(eth_rpc_block_response: String) {
369 let mut block =
370 match serde_json::from_str::<RpcNodeWssResponse<Block>>(ð_rpc_block_response) {
371 Ok(rpc_response) => rpc_response.params.result,
372 Err(e) => panic!("Failed to deserialize block response with error {e}"),
373 };
374 block.set_chain(Blockchain::Ethereum);
375
376 assert_eq!(
377 block.to_string(),
378 "Block(chain=Ethereum, number=22294175, timestamp=2025-04-18T06:44:11+00:00, hash=0x71ece187051700b814592f62774e6ebd8ebdf5efbb54c90859a7d1522ce38e0a)".to_string(),
379 );
380 assert_eq!(
381 block.hash,
382 "0x71ece187051700b814592f62774e6ebd8ebdf5efbb54c90859a7d1522ce38e0a"
383 );
384 assert_eq!(
385 block.parent_hash,
386 "0x2abcce1ac985ebea2a2d6878a78387158f46de8d6db2cefca00ea36df4030a40"
387 );
388 assert_eq!(block.number, 22_294_175);
389 assert_eq!(block.miner, "0x4838b106fce9647bdf1e7877bf73ce8b0bad5f97");
390 assert_eq!(
392 block.timestamp,
393 UnixNanos::from(Utc.with_ymd_and_hms(2025, 4, 18, 6, 44, 11).unwrap())
394 );
395 assert_eq!(block.gas_used, 14_563_593);
396 assert_eq!(block.gas_limit, 35_894_433);
397
398 assert_eq!(block.base_fee_per_gas, Some(U256::from(0x1862_a795_u64)));
399 assert_eq!(block.blob_gas_used, Some(U256::from(0xc0000u64)));
400 assert_eq!(block.excess_blob_gas, Some(U256::from(0x0484_0000_u64)));
401 }
402
403 #[rstest]
404 fn test_polygon_block_parsing(polygon_rpc_block_response: String) {
405 let mut block =
406 match serde_json::from_str::<RpcNodeWssResponse<Block>>(&polygon_rpc_block_response) {
407 Ok(rpc_response) => rpc_response.params.result,
408 Err(e) => panic!("Failed to deserialize block response with error {e}"),
409 };
410 block.set_chain(Blockchain::Polygon);
411
412 assert_eq!(
413 block.to_string(),
414 "Block(chain=Polygon, number=70453741, timestamp=2025-04-18T13:17:09+00:00, hash=0x38ca655a2009e1748097f5559a0c20de7966243b804efeb53183614e4bebe199)".to_string(),
415 );
416 assert_eq!(
417 block.hash,
418 "0x38ca655a2009e1748097f5559a0c20de7966243b804efeb53183614e4bebe199"
419 );
420 assert_eq!(
421 block.parent_hash,
422 "0xf25e108267e3d6e1e4aaf4e329872273f2b1ad6186a4a22e370623aa8d021c50"
423 );
424 assert_eq!(block.number, 70_453_741);
425 assert_eq!(block.miner, "0x0000000000000000000000000000000000000000");
426 assert_eq!(
428 block.timestamp,
429 UnixNanos::from(Utc.with_ymd_and_hms(2025, 4, 18, 13, 17, 9).unwrap())
430 );
431 assert_eq!(block.gas_used, 19_336_980);
432 assert_eq!(block.gas_limit, 30_000_000);
433 assert_eq!(block.base_fee_per_gas, Some(U256::from(0x19eu64)));
434 assert!(block.blob_gas_used.is_none()); assert!(block.excess_blob_gas.is_none()); }
437
438 #[rstest]
439 fn test_base_block_parsing(base_rpc_block_response: String) {
440 let mut block =
441 match serde_json::from_str::<RpcNodeWssResponse<Block>>(&base_rpc_block_response) {
442 Ok(rpc_response) => rpc_response.params.result,
443 Err(e) => panic!("Failed to deserialize block response with error {e}"),
444 };
445 block.set_chain(Blockchain::Base);
446
447 assert_eq!(
448 block.to_string(),
449 "Block(chain=Base, number=29139628, timestamp=2025-04-19T13:16:43+00:00, hash=0x14575c65070d455e6d20d5ee17be124917a33ce4437dd8615a56d29e8279b7ad)".to_string(),
450 );
451 assert_eq!(
452 block.hash,
453 "0x14575c65070d455e6d20d5ee17be124917a33ce4437dd8615a56d29e8279b7ad"
454 );
455 assert_eq!(
456 block.parent_hash,
457 "0x9a6ad4ffb258faa47ecd5eea9e7a9d8fa1772aa6232bc7cb4bbad5bc30786258"
458 );
459 assert_eq!(block.number, 29_139_628);
460 assert_eq!(block.miner, "0x4200000000000000000000000000000000000011");
461 assert_eq!(
463 block.timestamp,
464 UnixNanos::from(Utc.with_ymd_and_hms(2025, 4, 19, 13, 16, 43).unwrap())
465 );
466 assert_eq!(block.gas_used, 91_213_350);
467 assert_eq!(block.gas_limit, 120_000_000);
468
469 assert_eq!(block.base_fee_per_gas, Some(U256::from(0xaae54u64)));
470 assert_eq!(block.blob_gas_used, Some(U256::ZERO));
471 assert_eq!(block.excess_blob_gas, Some(U256::ZERO));
472 }
473
474 #[rstest]
475 fn test_arbitrum_block_parsing(arbitrum_rpc_block_response: String) {
476 let mut block =
477 match serde_json::from_str::<RpcNodeWssResponse<Block>>(&arbitrum_rpc_block_response) {
478 Ok(rpc_response) => rpc_response.params.result,
479 Err(e) => panic!("Failed to deserialize block response with error {e}"),
480 };
481 block.set_chain(Blockchain::Arbitrum);
482
483 assert_eq!(
484 block.to_string(),
485 "Block(chain=Arbitrum, number=328014516, timestamp=2025-04-19T13:32:54+00:00, hash=0x724a0af4720fd7624976f71b16163de25f8532e87d0e7058eb0c1d3f6da3c1f8)".to_string(),
486 );
487 assert_eq!(
488 block.hash,
489 "0x724a0af4720fd7624976f71b16163de25f8532e87d0e7058eb0c1d3f6da3c1f8"
490 );
491 assert_eq!(
492 block.parent_hash,
493 "0xe7176e201c2db109be479770074ad11b979de90ac850432ed38ed335803861b6"
494 );
495 assert_eq!(block.number, 328_014_516);
496 assert_eq!(block.miner, "0xa4b000000000000000000073657175656e636572");
497 assert_eq!(
499 block.timestamp,
500 UnixNanos::from(Utc.with_ymd_and_hms(2025, 4, 19, 13, 32, 54).unwrap())
501 );
502 assert_eq!(block.gas_used, 97012);
503 assert_eq!(block.gas_limit, 1_125_899_906_842_624);
504
505 assert_eq!(block.base_fee_per_gas, Some(U256::from(0x0098_9680_u64)));
506 assert!(block.blob_gas_used.is_none());
507 assert!(block.excess_blob_gas.is_none());
508 }
509
510 #[rstest]
511 fn test_block_builder_helpers() {
512 let block = Block::new(
513 "0xabc".into(),
514 "0xdef".into(),
515 1,
516 Ustr::from("0x0000000000000000000000000000000000000000"),
517 100_000,
518 50_000,
519 UnixNanos::from(1_700_000_000u64),
520 Some(Blockchain::Arbitrum),
521 );
522
523 let block = block
524 .with_base_fee(U256::from(1_000u64))
525 .with_blob_gas(U256::from(0x10u8), U256::from(0x20u8))
526 .with_l1_fee_components(U256::from(30_000u64), 1_234, 1_000_000);
527
528 assert_eq!(block.chain, Some(chains::ARBITRUM.name));
529 assert_eq!(block.base_fee_per_gas, Some(U256::from(1_000u64)));
530 assert_eq!(block.blob_gas_used, Some(U256::from(0x10u8)));
531 assert_eq!(block.excess_blob_gas, Some(U256::from(0x20u8)));
532 assert_eq!(block.l1_gas_price, Some(U256::from(30_000u64)));
533 assert_eq!(block.l1_gas_used, Some(1_234));
534 assert_eq!(block.l1_fee_scalar, Some(1_000_000));
535 }
536}