Skip to main content

nautilus_blockchain/contracts/
erc20.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use 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/// Represents the essential metadata information for an ERC20 token.
48#[derive(Debug, Clone)]
49pub struct TokenInfo {
50    /// The full name of the token.
51    pub name: String,
52    /// The ticker symbol of the token.
53    pub symbol: String,
54    /// The number of decimal places the token uses for representing fractional amounts.
55    pub decimals: u8,
56}
57
58/// Represents errors that can occur when interacting with a blockchain RPC client.
59#[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/// Interface for interacting with ERC20 token contracts on a blockchain.
84///
85/// This struct provides methods to fetch token metadata (name, symbol, decimals).
86/// From ERC20-compliant tokens on any EVM-compatible blockchain.
87#[derive(Debug)]
88pub struct Erc20Contract {
89    /// The base contract providing common RPC execution functionality.
90    base: BaseContract,
91    /// Whether to enforce that token name and symbol fields must be non-empty.
92    enforce_token_fields: bool,
93}
94
95impl Erc20Contract {
96    /// Creates a new ERC20 contract interface with the specified RPC client.
97    #[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    /// Creates a new ERC20 contract interface with the specified RPC client and a per-request
106    /// RPC timeout applied to its reads.
107    #[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    /// Fetches complete token information (name, symbol, decimals) from an ERC20 contract.
124    ///
125    /// # Errors
126    ///
127    /// Returns an error if:
128    /// - An RPC call fails.
129    /// - ABI decoding fails.
130    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    /// Fetches token information for multiple tokens in a single multicall.
187    ///
188    /// If the multicall fails (typically due to expired/broken contracts causing RPC "out of gas"),
189    /// automatically falls back to individual token fetches to isolate problematic contracts.
190    ///
191    /// # Errors
192    ///
193    /// Returns an error if the operation cannot proceed, and only in that case. Multicall failures
194    /// trigger automatic fallback to individual fetches. Individual token failures are captured in
195    /// the Result values of the returned `HashMap`.
196    pub async fn batch_fetch_token_info(
197        &self,
198        token_addresses: &[Address],
199    ) -> Result<HashMap<Address, Result<TokenInfo, TokenInfoError>>, BlockchainRpcClientError> {
200        // Build calls for all tokens (3 calls per token)
201        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, // Allow individual token failures
208                    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        // Try batch multicall first
224        let results = match self.base.execute_multicall(calls, None).await {
225            Ok(results) => results,
226            Err(e) => {
227                // Multicall failed (likely expired/broken contract causing RPC failure)
228                log::warn!(
229                    "Batch multicall failed: {}. Falling back to individual fetches for {} tokens",
230                    e,
231                    token_addresses.len()
232                );
233
234                // Fallback: fetch each token individually to isolate problematic contracts
235                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            // Check if we have all 3 results for this token.
259            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    /// Fetches the balance of a specific account for this ERC20 token.
280    ///
281    /// # Errors
282    ///
283    /// Returns an error if:
284    /// - An RPC call fails.
285    /// - ABI decoding fails.
286    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    /// Fetches the token decimal precision used to scale raw amounts.
312    ///
313    /// # Errors
314    ///
315    /// Returns an error if the contract call fails or its result cannot be decoded.
316    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    /// Fetches the exact allowance an owner has granted a spender for this ERC20 token.
336    ///
337    /// # Errors
338    ///
339    /// Returns an error if:
340    /// - An RPC call fails.
341    /// - ABI decoding fails.
342    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
374/// Generic parser for ERC20 string results (name, symbol)
375fn 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
403/// Generic parser for ERC20 decimals result
404fn 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
453/// Parses token information from a slice of 3 multicall results.
454///
455/// Expects results in order: name, symbol, decimals.
456/// Returns Ok(TokenInfo) if all three calls succeeded, or an Err with a
457/// descriptive error message if any call failed.
458fn 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        // Returns raw string bytes without ABI encoding - "Rico" as raw bytes
542        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        // Returns function selector instead of actual data
559        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        // Returns raw string bytes without ABI encoding - longer string example
571        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                // Raw bytes "Rico" without ABI encoding
712            }
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                // Example of longer non-ABI encoded string
773            }
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        // approve(address,uint256) selector 0x095ea7b3, spender word, amount word
788        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        // allowance(address,address) selector 0xdd62ed3e, owner word, spender word
802        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}