1use std::{collections::HashMap, sync::Arc};
17
18use alloy::{
19 primitives::{Address, Bytes, U256},
20 sol,
21 sol_types::SolCall,
22};
23use strum::Display;
24use thiserror::Error;
25
26use super::base::{BaseContract, ContractCall, Multicall3};
27use crate::rpc::{error::BlockchainRpcClientError, http::BlockchainHttpRpcClient};
28
29sol! {
30 contract ERC20 {
31 function name() external view returns (string);
32 function symbol() external view returns (string);
33 function decimals() external view returns (uint8);
34 function balanceOf(address account) external view returns (uint256);
35 function allowance(address owner, address spender) external view returns (uint256);
36 function approve(address spender, uint256 amount) external returns (bool);
37 }
38}
39
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Display)]
41pub enum Erc20Field {
42 Name,
43 Symbol,
44 Decimals,
45}
46
47#[derive(Debug, Clone)]
49pub struct TokenInfo {
50 pub name: String,
52 pub symbol: String,
54 pub decimals: u8,
56}
57
58#[derive(Debug, Error)]
60pub enum TokenInfoError {
61 #[error("RPC error: {0}")]
62 RpcError(#[from] BlockchainRpcClientError),
63 #[error("Token {field} is empty for address {address}")]
64 EmptyTokenField { field: Erc20Field, address: Address },
65 #[error("Multicall returned unexpected number of results: expected {expected}, was {actual}")]
66 UnexpectedResultCount { expected: usize, actual: usize },
67 #[error("Call failed for {field} at address {address}: {reason} (raw data: {raw_data})")]
68 CallFailed {
69 field: String,
70 address: Address,
71 reason: String,
72 raw_data: String,
73 },
74 #[error("Failed to decode {field} for address {address}: {reason} (raw data: {raw_data})")]
75 DecodingError {
76 field: String,
77 address: Address,
78 reason: String,
79 raw_data: String,
80 },
81}
82
83#[derive(Debug)]
88pub struct Erc20Contract {
89 base: BaseContract,
91 enforce_token_fields: bool,
93}
94
95impl Erc20Contract {
96 #[must_use]
98 pub fn new(client: Arc<BlockchainHttpRpcClient>, enforce_token_fields: bool) -> Self {
99 Self {
100 base: BaseContract::new(client),
101 enforce_token_fields,
102 }
103 }
104
105 #[must_use]
108 pub fn new_with_timeout(
109 client: Arc<BlockchainHttpRpcClient>,
110 rpc_timeout_secs: Option<u64>,
111 enforce_token_fields: bool,
112 ) -> Self {
113 Self {
114 base: BaseContract::new_with_multicall_limit_and_timeout(
115 client,
116 super::base::DEFAULT_MULTICALL_CALLS_PER_RPC_REQUEST,
117 rpc_timeout_secs,
118 ),
119 enforce_token_fields,
120 }
121 }
122
123 pub async fn fetch_token_info(
131 &self,
132 token_address: &Address,
133 ) -> Result<TokenInfo, TokenInfoError> {
134 let calls = vec![
135 ContractCall {
136 target: *token_address,
137 allow_failure: true,
138 call_data: ERC20::nameCall.abi_encode(),
139 },
140 ContractCall {
141 target: *token_address,
142 allow_failure: true,
143 call_data: ERC20::symbolCall.abi_encode(),
144 },
145 ContractCall {
146 target: *token_address,
147 allow_failure: true,
148 call_data: ERC20::decimalsCall.abi_encode(),
149 },
150 ];
151
152 let results = self.base.execute_multicall(calls, None).await?;
153
154 if results.len() != 3 {
155 return Err(TokenInfoError::UnexpectedResultCount {
156 expected: 3,
157 actual: results.len(),
158 });
159 }
160
161 let name = parse_erc20_string_result(&results[0], Erc20Field::Name, token_address)?;
162 let symbol = parse_erc20_string_result(&results[1], Erc20Field::Symbol, token_address)?;
163 let decimals = parse_erc20_decimals_result(&results[2], token_address)?;
164
165 if self.enforce_token_fields && name.is_empty() {
166 return Err(TokenInfoError::EmptyTokenField {
167 field: Erc20Field::Name,
168 address: *token_address,
169 });
170 }
171
172 if self.enforce_token_fields && symbol.is_empty() {
173 return Err(TokenInfoError::EmptyTokenField {
174 field: Erc20Field::Symbol,
175 address: *token_address,
176 });
177 }
178
179 Ok(TokenInfo {
180 name,
181 symbol,
182 decimals,
183 })
184 }
185
186 pub async fn batch_fetch_token_info(
197 &self,
198 token_addresses: &[Address],
199 ) -> Result<HashMap<Address, Result<TokenInfo, TokenInfoError>>, BlockchainRpcClientError> {
200 let mut calls = Vec::with_capacity(token_addresses.len() * 3);
202
203 for token_address in token_addresses {
204 calls.extend([
205 ContractCall {
206 target: *token_address,
207 allow_failure: true, call_data: ERC20::nameCall.abi_encode(),
209 },
210 ContractCall {
211 target: *token_address,
212 allow_failure: true,
213 call_data: ERC20::symbolCall.abi_encode(),
214 },
215 ContractCall {
216 target: *token_address,
217 allow_failure: true,
218 call_data: ERC20::decimalsCall.abi_encode(),
219 },
220 ]);
221 }
222
223 let results = match self.base.execute_multicall(calls, None).await {
225 Ok(results) => results,
226 Err(e) => {
227 log::warn!(
229 "Batch multicall failed: {}. Falling back to individual fetches for {} tokens",
230 e,
231 token_addresses.len()
232 );
233
234 let mut token_infos = HashMap::with_capacity(token_addresses.len());
236 for token_address in token_addresses {
237 match self.fetch_token_info(token_address).await {
238 Ok(info) => {
239 token_infos.insert(*token_address, Ok(info));
240 }
241 Err(e) => {
242 log::debug!(
243 "Token {token_address} failed individual fetch (likely expired/broken): {e}"
244 );
245 token_infos.insert(*token_address, Err(e));
246 }
247 }
248 }
249
250 return Ok(token_infos);
251 }
252 };
253
254 let mut token_infos = HashMap::with_capacity(token_addresses.len());
255 for (i, token_address) in token_addresses.iter().enumerate() {
256 let base_idx = i * 3;
257
258 if base_idx + 2 >= results.len() {
260 log::error!("Incomplete results from multicall for token {token_address}");
261 token_infos.insert(
262 *token_address,
263 Err(TokenInfoError::UnexpectedResultCount {
264 expected: 3,
265 actual: results.len().saturating_sub(base_idx),
266 }),
267 );
268 continue;
269 }
270
271 let token_info =
272 parse_batch_token_results(&results[base_idx..base_idx + 3], token_address);
273 token_infos.insert(*token_address, token_info);
274 }
275
276 Ok(token_infos)
277 }
278
279 pub async fn balance_of(
287 &self,
288 token_address: &Address,
289 account: &Address,
290 ) -> Result<U256, BlockchainRpcClientError> {
291 self.balance_of_with_block(token_address, account, None)
292 .await
293 }
294
295 async fn balance_of_with_block(
296 &self,
297 token_address: &Address,
298 account: &Address,
299 block: Option<u64>,
300 ) -> Result<U256, BlockchainRpcClientError> {
301 let call_data = ERC20::balanceOfCall { account: *account }.abi_encode();
302 let result = self
303 .base
304 .execute_call(token_address, &call_data, block)
305 .await?;
306
307 ERC20::balanceOfCall::abi_decode_returns(&result)
308 .map_err(|e| BlockchainRpcClientError::AbiDecodingError(e.to_string()))
309 }
310
311 pub async fn decimals(&self, token_address: &Address) -> Result<u8, BlockchainRpcClientError> {
317 self.decimals_with_block(token_address, None).await
318 }
319
320 async fn decimals_with_block(
321 &self,
322 token_address: &Address,
323 block: Option<u64>,
324 ) -> Result<u8, BlockchainRpcClientError> {
325 let call_data = ERC20::decimalsCall {}.abi_encode();
326 let result = self
327 .base
328 .execute_call(token_address, &call_data, block)
329 .await?;
330
331 ERC20::decimalsCall::abi_decode_returns(&result)
332 .map_err(|e| BlockchainRpcClientError::AbiDecodingError(e.to_string()))
333 }
334
335 pub async fn allowance(
343 &self,
344 token_address: &Address,
345 owner: &Address,
346 spender: &Address,
347 ) -> Result<U256, BlockchainRpcClientError> {
348 self.allowance_with_block(token_address, owner, spender, None)
349 .await
350 }
351
352 async fn allowance_with_block(
353 &self,
354 token_address: &Address,
355 owner: &Address,
356 spender: &Address,
357 block: Option<u64>,
358 ) -> Result<U256, BlockchainRpcClientError> {
359 let call_data = ERC20::allowanceCall {
360 owner: *owner,
361 spender: *spender,
362 }
363 .abi_encode();
364 let result = self
365 .base
366 .execute_call(token_address, &call_data, block)
367 .await?;
368
369 ERC20::allowanceCall::abi_decode_returns(&result)
370 .map_err(|e| BlockchainRpcClientError::AbiDecodingError(e.to_string()))
371 }
372}
373
374fn parse_erc20_string_result(
376 result: &Multicall3::Result,
377 field_name: Erc20Field,
378 token_address: &Address,
379) -> Result<String, TokenInfoError> {
380 let data = validate_multicall_result(result, field_name, token_address)?;
381
382 match field_name {
383 Erc20Field::Name => ERC20::nameCall::abi_decode_returns(data),
384 Erc20Field::Symbol => ERC20::symbolCall::abi_decode_returns(data),
385 Erc20Field::Decimals => {
386 return Err(TokenInfoError::DecodingError {
387 field: field_name.to_string(),
388 address: *token_address,
389 reason: "Expected Name or Symbol for parse_erc20_string_result function argument"
390 .to_string(),
391 raw_data: data.to_string(),
392 });
393 }
394 }
395 .map_err(|e| TokenInfoError::DecodingError {
396 field: field_name.to_string(),
397 address: *token_address,
398 reason: e.to_string(),
399 raw_data: result.returnData.to_string(),
400 })
401}
402
403fn parse_erc20_decimals_result(
405 result: &Multicall3::Result,
406 token_address: &Address,
407) -> Result<u8, TokenInfoError> {
408 let data = validate_multicall_result(result, Erc20Field::Decimals, token_address)?;
409
410 ERC20::decimalsCall::abi_decode_returns(data).map_err(|e| TokenInfoError::DecodingError {
411 field: "decimals".to_string(),
412 address: *token_address,
413 reason: e.to_string(),
414 raw_data: result.returnData.to_string(),
415 })
416}
417
418fn validate_multicall_result<'a>(
419 result: &'a Multicall3::Result,
420 field: Erc20Field,
421 token_address: &Address,
422) -> Result<&'a Bytes, TokenInfoError> {
423 if !result.success {
424 return Err(TokenInfoError::CallFailed {
425 field: match field {
426 Erc20Field::Decimals => "decimals".to_string(),
427 _ => field.to_string(),
428 },
429 address: *token_address,
430 reason: decode_revert_reason(&result.returnData),
431 raw_data: result.returnData.to_string(),
432 });
433 }
434
435 if result.returnData.is_empty() {
436 return Err(TokenInfoError::EmptyTokenField {
437 field,
438 address: *token_address,
439 });
440 }
441
442 Ok(&result.returnData)
443}
444
445fn decode_revert_reason(data: &Bytes) -> String {
446 if data.is_empty() {
447 "Call failed without revert data".to_string()
448 } else {
449 format!("Call failed with data: {data}")
450 }
451}
452
453fn parse_batch_token_results(
459 results: &[Multicall3::Result],
460 token_address: &Address,
461) -> Result<TokenInfo, TokenInfoError> {
462 if results.len() != 3 {
463 return Err(TokenInfoError::UnexpectedResultCount {
464 expected: 3,
465 actual: results.len(),
466 });
467 }
468
469 let name = parse_erc20_string_result(&results[0], Erc20Field::Name, token_address)?;
470 let symbol = parse_erc20_string_result(&results[1], Erc20Field::Symbol, token_address)?;
471 let decimals = parse_erc20_decimals_result(&results[2], token_address)?;
472
473 Ok(TokenInfo {
474 name,
475 symbol,
476 decimals,
477 })
478}
479
480#[cfg(test)]
481mod tests {
482 use alloy::primitives::{Bytes, address};
483 use nautilus_core::hex;
484 use rstest::{fixture, rstest};
485
486 use super::*;
487 use crate::rpc::http::tests::mock::{MockRpcState, start_mock_rpc_server};
488
489 const CALL_BALANCE: &str = include_str!("../../test_data/execution/rpc_eth_call_balance.json");
490 const CALL_ALLOWANCE: &str =
491 include_str!("../../test_data/execution/rpc_eth_call_allowance.json");
492 #[fixture]
493 fn token_address() -> Address {
494 address!("25b76A90E389bD644a29db919b136Dc63B174Ec7")
495 }
496
497 #[fixture]
498 fn successful_name_result() -> Multicall3::Result {
499 Multicall3::Result {
500 success: true,
501 returnData: Bytes::from(hex::decode("00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000007546f6b656e204100000000000000000000000000000000000000000000000000").unwrap()),
502 }
503 }
504
505 #[fixture]
506 fn successful_symbol_result() -> Multicall3::Result {
507 Multicall3::Result {
508 success: true,
509 returnData: Bytes::from(hex::decode("0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000776546f6b656e4100000000000000000000000000000000000000000000000000").unwrap()),
510 }
511 }
512
513 #[fixture]
514 fn failed_name_result() -> Multicall3::Result {
515 Multicall3::Result {
516 success: false,
517 returnData: Bytes::from(vec![]),
518 }
519 }
520
521 #[fixture]
522 fn failed_token_address() -> Address {
523 address!("00000000049084A92F8964B76845ab6DE54EB229")
524 }
525
526 #[fixture]
527 fn success_but_empty_result() -> Multicall3::Result {
528 Multicall3::Result {
529 success: true,
530 returnData: Bytes::from(vec![]),
531 }
532 }
533
534 #[fixture]
535 fn empty_token_address() -> Address {
536 address!("a5b00cEc63694319495d605AA414203F9714F47E")
537 }
538
539 #[fixture]
540 fn non_abi_encoded_string_result() -> Multicall3::Result {
541 Multicall3::Result {
543 success: true,
544 returnData: Bytes::from(
545 hex::decode("5269636f00000000000000000000000000000000000000000000000000000000")
546 .unwrap(),
547 ),
548 }
549 }
550
551 #[fixture]
552 fn non_abi_encoded_token_address() -> Address {
553 address!("5374EcC160A4bd68446B43B5A6B132F9c001C54C")
554 }
555
556 #[fixture]
557 fn non_standard_selector_result() -> Multicall3::Result {
558 Multicall3::Result {
560 success: true,
561 returnData: Bytes::from(
562 hex::decode("06fdde0300000000000000000000000000000000000000000000000000000000")
563 .unwrap(),
564 ),
565 }
566 }
567
568 #[fixture]
569 fn non_abi_encoded_long_string_result() -> Multicall3::Result {
570 Multicall3::Result {
572 success: true,
573 returnData: Bytes::from(
574 hex::decode("5269636f62616e6b205269736b20536861726500000000000000000000000000")
575 .unwrap(),
576 ),
577 }
578 }
579
580 #[rstest]
581 fn test_parse_erc20_string_result_name_success(
582 successful_name_result: Multicall3::Result,
583 token_address: Address,
584 ) {
585 let result =
586 parse_erc20_string_result(&successful_name_result, Erc20Field::Name, &token_address);
587 assert!(result.is_ok());
588 assert_eq!(result.unwrap(), "Token A");
589 }
590
591 #[rstest]
592 fn test_parse_erc20_string_result_symbol_success(
593 successful_symbol_result: Multicall3::Result,
594 token_address: Address,
595 ) {
596 let result = parse_erc20_string_result(
597 &successful_symbol_result,
598 Erc20Field::Symbol,
599 &token_address,
600 );
601 assert!(result.is_ok());
602 assert_eq!(result.unwrap(), "vTokenA");
603 }
604
605 #[rstest]
606 fn test_parse_erc20_string_result_name_failed_with_specific_address(
607 failed_name_result: Multicall3::Result,
608 failed_token_address: Address,
609 ) {
610 let result =
611 parse_erc20_string_result(&failed_name_result, Erc20Field::Name, &failed_token_address);
612 assert!(result.is_err());
613 match result.unwrap_err() {
614 TokenInfoError::CallFailed {
615 field,
616 address,
617 reason,
618 raw_data: _,
619 } => {
620 assert_eq!(field, "Name");
621 assert_eq!(address, failed_token_address);
622 assert_eq!(reason, "Call failed without revert data");
623 }
624 _ => panic!("Expected DecodingError"),
625 }
626 }
627
628 #[rstest]
629 fn test_parse_erc20_string_result_success_but_empty_name(
630 success_but_empty_result: Multicall3::Result,
631 empty_token_address: Address,
632 ) {
633 let result = parse_erc20_string_result(
634 &success_but_empty_result,
635 Erc20Field::Name,
636 &empty_token_address,
637 );
638 assert!(result.is_err());
639 match result.unwrap_err() {
640 TokenInfoError::EmptyTokenField { field, address } => {
641 assert!(matches!(field, Erc20Field::Name));
642 assert_eq!(address, empty_token_address);
643 }
644 _ => panic!("Expected EmptyTokenField error"),
645 }
646 }
647
648 #[rstest]
649 fn test_parse_erc20_decimals_result_failed(
650 failed_name_result: Multicall3::Result,
651 failed_token_address: Address,
652 ) {
653 let result = parse_erc20_decimals_result(&failed_name_result, &failed_token_address);
654 match result.unwrap_err() {
655 TokenInfoError::CallFailed {
656 field,
657 address,
658 reason,
659 raw_data,
660 } => {
661 assert_eq!(field, "decimals");
662 assert_eq!(address, failed_token_address);
663 assert_eq!(reason, "Call failed without revert data");
664 assert_eq!(raw_data, "0x");
665 }
666 _ => panic!("Expected CallFailed"),
667 }
668 }
669
670 #[rstest]
671 fn test_parse_erc20_decimals_result_success_but_empty(
672 success_but_empty_result: Multicall3::Result,
673 empty_token_address: Address,
674 ) {
675 let result = parse_erc20_decimals_result(&success_but_empty_result, &empty_token_address);
676 assert!(result.is_err());
677 match result.unwrap_err() {
678 TokenInfoError::EmptyTokenField { field, address } => {
679 assert!(matches!(field, Erc20Field::Decimals));
680 assert_eq!(address, empty_token_address);
681 }
682 _ => panic!("Expected EmptyTokenField error"),
683 }
684 }
685
686 #[rstest]
687 fn test_parse_non_abi_encoded_string(
688 non_abi_encoded_string_result: Multicall3::Result,
689 non_abi_encoded_token_address: Address,
690 ) {
691 let result = parse_erc20_string_result(
692 &non_abi_encoded_string_result,
693 Erc20Field::Name,
694 &non_abi_encoded_token_address,
695 );
696 assert!(result.is_err());
697 match result.unwrap_err() {
698 TokenInfoError::DecodingError {
699 field,
700 address,
701 reason,
702 raw_data,
703 } => {
704 assert_eq!(field, "Name");
705 assert_eq!(address, non_abi_encoded_token_address);
706 assert!(reason.contains("type check failed"));
707 assert_eq!(
708 raw_data,
709 "0x5269636f00000000000000000000000000000000000000000000000000000000"
710 );
711 }
713 _ => panic!("Expected DecodingError"),
714 }
715 }
716
717 #[rstest]
718 fn test_parse_non_standard_selector_return(
719 non_standard_selector_result: Multicall3::Result,
720 token_address: Address,
721 ) {
722 let result = parse_erc20_string_result(
723 &non_standard_selector_result,
724 Erc20Field::Name,
725 &token_address,
726 );
727 assert!(result.is_err());
728 match result.unwrap_err() {
729 TokenInfoError::DecodingError {
730 field,
731 address,
732 reason,
733 raw_data,
734 } => {
735 assert_eq!(field, "Name");
736 assert_eq!(address, token_address);
737 assert!(reason.contains("type check failed"));
738 assert_eq!(
739 raw_data,
740 "0x06fdde0300000000000000000000000000000000000000000000000000000000"
741 );
742 }
743 _ => panic!("Expected DecodingError"),
744 }
745 }
746
747 #[rstest]
748 fn test_parse_non_abi_encoded_long_string(
749 non_abi_encoded_long_string_result: Multicall3::Result,
750 non_abi_encoded_token_address: Address,
751 ) {
752 let result = parse_erc20_string_result(
753 &non_abi_encoded_long_string_result,
754 Erc20Field::Name,
755 &non_abi_encoded_token_address,
756 );
757 assert!(result.is_err());
758 match result.unwrap_err() {
759 TokenInfoError::DecodingError {
760 field,
761 address,
762 reason,
763 raw_data,
764 } => {
765 assert_eq!(field, "Name");
766 assert_eq!(address, non_abi_encoded_token_address);
767 assert!(reason.contains("type check failed"));
768 assert_eq!(
769 raw_data,
770 "0x5269636f62616e6b205269736b20536861726500000000000000000000000000"
771 );
772 }
774 _ => panic!("Expected DecodingError"),
775 }
776 }
777
778 #[rstest]
779 fn test_approve_calldata_matches_known_vector() {
780 let spender = address!("E592427A0AEce92De3Edee1F18E0157C05861564");
781 let calldata = ERC20::approveCall {
782 spender,
783 amount: U256::from(1_000_000_000_000_000_000u64),
784 }
785 .abi_encode();
786
787 let expected = format!(
789 "095ea7b3{:0>64}{:0>64}",
790 "e592427a0aece92de3edee1f18e0157c05861564", "0de0b6b3a7640000"
791 );
792 assert_eq!(hex::encode(&calldata), expected);
793 }
794
795 #[rstest]
796 fn test_allowance_calldata_matches_known_vector() {
797 let owner = address!("f39Fd6e51aad88F6F4ce6aB8827279cffFb92266");
798 let spender = address!("E592427A0AEce92De3Edee1F18E0157C05861564");
799 let calldata = ERC20::allowanceCall { owner, spender }.abi_encode();
800
801 let expected = format!(
803 "dd62ed3e{:0>64}{:0>64}",
804 "f39fd6e51aad88f6f4ce6ab8827279cfffb92266", "e592427a0aece92de3edee1f18e0157c05861564"
805 );
806 assert_eq!(hex::encode(&calldata), expected);
807 }
808
809 async fn erc20_contract_against(state: MockRpcState) -> (Erc20Contract, MockRpcState) {
810 let addr = start_mock_rpc_server(state.clone()).await;
811 let rpc_client =
812 Arc::new(BlockchainHttpRpcClient::new(format!("http://{addr}"), None, None).unwrap());
813 (Erc20Contract::new(rpc_client, true), state)
814 }
815
816 #[tokio::test]
817 async fn test_balance_of_against_mock_rpc() {
818 let state = MockRpcState::default().with_call_response("0x70a08231", CALL_BALANCE);
819 let (contract, state) = erc20_contract_against(state).await;
820
821 let balance = contract
822 .balance_of(
823 &address!("82aF49447D8a07e3bd95BD0d56f35241523fBab1"),
824 &address!("f39Fd6e51aad88F6F4ce6aB8827279cffFb92266"),
825 )
826 .await
827 .unwrap();
828
829 assert_eq!(balance, U256::from(500_000_000_000_000_000u64));
830 let requests = state.recorded_requests();
831 assert_eq!(requests.len(), 1);
832 assert_eq!(requests[0]["params"][1], "latest");
833 }
834
835 #[tokio::test]
836 async fn test_allowance_against_mock_rpc() {
837 let state = MockRpcState::default().with_call_response("0xdd62ed3e", CALL_ALLOWANCE);
838 let (contract, state) = erc20_contract_against(state).await;
839
840 let allowance = contract
841 .allowance(
842 &address!("82aF49447D8a07e3bd95BD0d56f35241523fBab1"),
843 &address!("f39Fd6e51aad88F6F4ce6aB8827279cffFb92266"),
844 &address!("E592427A0AEce92De3Edee1F18E0157C05861564"),
845 )
846 .await
847 .unwrap();
848
849 assert_eq!(allowance, U256::from(1_000_000_000_000_000_000u64));
850 let requests = state.recorded_requests();
851 assert_eq!(requests.len(), 1);
852 assert_eq!(requests[0]["params"][1], "latest");
853 }
854}