Skip to main content

fnzero_safe_evm_services/
lib.rs

1//! Shared EVM wallet, asset, payment, and dApp signing services.
2//!
3//! EVM support is intentionally chain-generic: a chain is data (`chain_id`,
4//! RPC URL, explorer URL, and native symbol), while wallet, ERC-20, gas, and
5//! signing logic is shared by every EVM network.
6
7use aes_gcm::{
8    aead::{Aead, AeadCore, KeyInit, OsRng as AeadOsRng, Payload},
9    Aes256Gcm,
10};
11use argon2::{Algorithm, Argon2, Params, Version as Argon2Version};
12use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
13use bip39::{Language, Mnemonic};
14use fnzero_safe_chain_core::{
15    capabilities, capability_ids, families, validate_derivation_path_input,
16    validate_mnemonic_input, ChainAdapter, ChainDescriptor, ChainEndpoint, ChainError, ChainFamily,
17    ChainId, ChainResult, DerivedAccount, NativeAsset, SupportLevel,
18};
19use k256::{
20    ecdsa::{RecoveryId, Signature, SigningKey},
21    elliptic_curve::rand_core::OsRng,
22};
23use serde::{Deserialize, Serialize};
24use sha3::{Digest, Keccak256};
25use std::io::Read;
26use std::str::FromStr;
27use std::time::{Duration, SystemTime, UNIX_EPOCH};
28use thiserror::Error;
29use zeroize::{Zeroize, Zeroizing};
30
31const DEFAULT_EVM_DERIVATION_PATH: &str = "m/44'/60'/0'/0/0";
32const LEGACY_KEYSTORE_VERSION: u8 = 1;
33const KEYSTORE_VERSION: u8 = 2;
34const KEYSTORE_SECRET_MNEMONIC: &str = "mnemonic";
35const KEYSTORE_SECRET_PRIVATE_KEY: &str = "private_key";
36const KEYSTORE_KDF: &str = "argon2id";
37const KEYSTORE_CIPHER: &str = "aes-256-gcm";
38const KEYSTORE_AAD_DOMAIN: &[u8] = b"fnzero-safe-evm-keystore";
39const KEYSTORE_SALT_BYTES: usize = 16;
40const KEYSTORE_NONCE_BYTES: usize = 12;
41const KEYSTORE_TAG_BYTES: usize = 16;
42const MAX_KEYSTORE_JSON_BYTES: usize = 128 * 1024;
43const MAX_KEYSTORE_SECRET_BYTES: usize = 1024;
44const MAX_KEYSTORE_PASSWORD_BYTES: usize = 1024;
45const PRIVATE_KEY_BYTES: usize = 32;
46const ARGON2_MEMORY_KIB: u32 = 64 * 1024;
47const ARGON2_ITERATIONS: u32 = 3;
48const ARGON2_PARALLELISM: u32 = 1;
49const JSON_RPC_TIMEOUT_SECS: u64 = 10;
50const JSON_RPC_FAILOVER_DELAY_MS: u64 = 150;
51const TOKEN_METADATA_TIMEOUT_SECS: u64 = 4;
52const ERC20_TRANSFER_SELECTOR: [u8; 4] = [0xa9, 0x05, 0x9c, 0xbb];
53const ERC20_BALANCE_OF_SELECTOR: [u8; 4] = [0x70, 0xa0, 0x82, 0x31];
54const ERC20_DECIMALS_SELECTOR: [u8; 4] = [0x31, 0x3c, 0xe5, 0x67];
55const ERC20_SYMBOL_SELECTOR: [u8; 4] = [0x95, 0xd8, 0x9b, 0x41];
56const ERC20_NAME_SELECTOR: [u8; 4] = [0x06, 0xfd, 0xde, 0x03];
57const DEFAULT_PRIORITY_FEE_WEI: &str = "1500000000";
58const ARC_MIN_FEE_WEI: &str = "20000000000";
59const ARC_USDC_CONTRACT: &str = "0x3600000000000000000000000000000000000000";
60
61fn is_arc(chain_id: u64) -> bool {
62    matches!(chain_id, 5_042 | 5_042_002)
63}
64
65fn is_native_token_alias(chain_id: u64, address: &str) -> bool {
66    is_arc(chain_id) && address.eq_ignore_ascii_case(ARC_USDC_CONTRACT)
67}
68
69fn validate_arc_recipient(chain_id: u64, recipient: &str, amount: &str) -> EvmResult<()> {
70    if is_arc(chain_id)
71        && address_eq(recipient, "0x0000000000000000000000000000000000000000")
72        && decimal_cmp(amount, "0")? == std::cmp::Ordering::Greater
73    {
74        return Err(EvmServiceError::InvalidInput(
75            "Arc does not allow USDC transfers to the zero address".to_string(),
76        ));
77    }
78    Ok(())
79}
80
81fn arc_fee_floor(chain_id: u64, fee: String) -> EvmResult<String> {
82    if is_arc(chain_id) && decimal_cmp(&fee, ARC_MIN_FEE_WEI)? == std::cmp::Ordering::Less {
83        return Ok(ARC_MIN_FEE_WEI.to_string());
84    }
85    Ok(fee)
86}
87const ETHERSCAN_API_KEY_ENV: &str = "FNZERO_SAFE_ETHERSCAN_API_KEY";
88const MAX_ETHERSCAN_RESPONSE_BYTES: usize = 1024 * 1024;
89const MAX_TOKEN_METADATA_RESPONSE_BYTES: usize = 1024 * 1024;
90const MAX_TOKEN_LIST_RESPONSE_BYTES: usize = 2 * 1024 * 1024;
91const MAX_TOKEN_METADATA_BATCH_SIZE: usize = 30;
92
93#[derive(Debug, Error)]
94pub enum EvmServiceError {
95    #[error("{0}")]
96    InvalidInput(String),
97    #[error("wrong password")]
98    WrongPassword,
99    #[error("unsupported chain")]
100    UnsupportedChain,
101    #[error("EVM RPC request failed")]
102    RpcUnavailable,
103    #[error("gas estimation failed")]
104    GasEstimateFailed,
105    #[error("insufficient funds")]
106    InsufficientFunds,
107    #[error("invalid chain id")]
108    InvalidChainId,
109    #[error("user rejected the signing request")]
110    UserRejected,
111    #[error("invalid typed data")]
112    InvalidTypedData,
113    #[error("transaction history is unavailable")]
114    HistoryUnavailable,
115}
116
117pub type EvmResult<T> = Result<T, EvmServiceError>;
118
119#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
120pub struct EvmChainConfig {
121    pub chain_id: u64,
122    pub name: String,
123    pub native_symbol: String,
124    pub rpc_url: String,
125    pub explorer_url: Option<String>,
126    pub testnet: bool,
127}
128
129/// Adapts one EVM network to the chain-agnostic registry.
130pub struct EvmChainAdapter {
131    descriptor: ChainDescriptor,
132}
133
134impl EvmChainAdapter {
135    pub fn new(chain: EvmChainConfig) -> ChainResult<Self> {
136        let history_api_key = etherscan_api_key();
137        Self::new_with_history_api_key(chain, history_api_key.as_deref().map(String::as_str))
138    }
139
140    fn new_with_history_api_key(
141        chain: EvmChainConfig,
142        history_api_key: Option<&str>,
143    ) -> ChainResult<Self> {
144        let chain_id = ChainId::new("eip155", &chain.chain_id.to_string())?;
145        validate_chain(&chain).map_err(|error| match error {
146            EvmServiceError::InvalidChainId => {
147                ChainError::InvalidChainId(format!("eip155:{}", chain.chain_id))
148            }
149            error => ChainError::InvalidDescriptor {
150                chain_id: chain_id.clone(),
151                reason: error.to_string(),
152            },
153        })?;
154        let mut chain_capabilities = capability_ids(&[
155            capabilities::ACCOUNT_DERIVATION,
156            capabilities::ADDRESS_VALIDATION,
157            capabilities::PRIVATE_KEY_IMPORT,
158            capabilities::NATIVE_BALANCE,
159            capabilities::FUNGIBLE_TOKENS,
160            capabilities::TRANSFER,
161            capabilities::STATUS,
162            capabilities::MESSAGE_SIGNING,
163            capabilities::DAPP_CONNECT,
164        ])?;
165        if etherscan_history_available(&chain, history_api_key) {
166            chain_capabilities.push(fnzero_safe_chain_core::CapabilityId::new(
167                capabilities::HISTORY,
168            )?);
169        }
170        Ok(Self {
171            descriptor: ChainDescriptor {
172                chain_id,
173                family: ChainFamily::new(families::EVM)?,
174                name: chain.name,
175                network: if chain.testnet { "testnet" } else { "mainnet" }.to_string(),
176                testnet: chain.testnet,
177                native_asset: NativeAsset {
178                    symbol: chain.native_symbol.clone(),
179                    name: chain.native_symbol,
180                    decimals: 18,
181                },
182                default_derivation_path: DEFAULT_EVM_DERIVATION_PATH.to_string(),
183                address_formats: vec!["hex20".to_string()],
184                capabilities: chain_capabilities,
185                endpoints: vec![ChainEndpoint {
186                    kind: "ethereum-json-rpc".to_string(),
187                    url: chain.rpc_url,
188                }],
189                explorer_url: chain.explorer_url,
190                support_level: SupportLevel::Beta,
191            },
192        })
193    }
194}
195
196impl ChainAdapter for EvmChainAdapter {
197    fn descriptor(&self) -> &ChainDescriptor {
198        &self.descriptor
199    }
200
201    fn normalize_address(&self, address: &str) -> ChainResult<String> {
202        crate::normalize_address(address, "address")
203            .map_err(|error| ChainError::InvalidAddress(error.to_string()))
204    }
205
206    fn derive_account(
207        &self,
208        mnemonic: &str,
209        derivation_path: Option<&str>,
210    ) -> ChainResult<DerivedAccount> {
211        let path = derivation_path
212            .map(str::trim)
213            .filter(|value| !value.is_empty())
214            .unwrap_or(DEFAULT_EVM_DERIVATION_PATH);
215        validate_evm_adapter_path(path)?;
216        let address = address_from_mnemonic(mnemonic, Some(path))
217            .map_err(|error| ChainError::DerivationFailed(error.to_string()))?;
218        DerivedAccount::new(
219            self.descriptor.chain_id.clone(),
220            address,
221            path.to_string(),
222            None,
223        )
224    }
225}
226
227#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
228pub struct EvmWalletSummary {
229    pub id: String,
230    pub name: String,
231    pub address: String,
232    pub derivation_path: Option<String>,
233}
234
235#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
236pub struct EvmWalletKeystore {
237    pub wallet: EvmWalletSummary,
238    pub keystore_json: String,
239}
240
241#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
242pub struct EvmCreateWalletRequest {
243    pub name: String,
244    pub password: String,
245}
246
247#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
248pub struct EvmImportPrivateKeyRequest {
249    pub name: String,
250    pub private_key_hex: String,
251    pub password: String,
252}
253
254#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
255pub struct EvmImportMnemonicRequest {
256    pub name: String,
257    pub mnemonic: String,
258    pub derivation_path: Option<String>,
259    pub password: String,
260}
261
262#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
263pub struct EvmImportKeystoreRequest {
264    pub name: String,
265    pub keystore_json: String,
266    pub password: String,
267}
268
269#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
270pub struct EvmUnlockWalletRequest {
271    pub keystore_json: String,
272    pub password: String,
273}
274
275#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
276pub struct EvmExportPrivateKeyRequest {
277    pub keystore_json: String,
278    pub password: String,
279}
280
281#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
282pub struct EvmExportPrivateKeyResponse {
283    pub address: String,
284    pub private_key_hex: String,
285}
286
287#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
288pub struct EvmTokenQuery {
289    pub contract_address: String,
290}
291
292#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
293pub struct EvmAssetQueryRequest {
294    pub chain: EvmChainConfig,
295    pub wallet_address: String,
296    pub tokens: Vec<EvmTokenQuery>,
297}
298
299#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
300pub struct EvmTokenAsset {
301    pub contract_address: String,
302    pub symbol: String,
303    pub name: String,
304    pub balance: String,
305    pub decimals: u8,
306    pub logo_uri: Option<String>,
307}
308
309#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
310pub struct EvmAssetSnapshot {
311    pub chain: EvmChainConfig,
312    pub wallet_address: String,
313    pub native_balance_wei: String,
314    pub tokens: Vec<EvmTokenAsset>,
315    pub recent_transactions: Vec<EvmTransactionHistoryEntry>,
316    pub history_status: String,
317    pub history_message: Option<String>,
318    pub refreshed_at_ms: u64,
319}
320
321#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
322pub struct EvmTransactionHistoryEntry {
323    pub hash: String,
324    pub block_number: Option<u64>,
325    pub status: String,
326}
327
328#[derive(Debug, Deserialize)]
329struct EtherscanHistoryResponse {
330    status: Option<String>,
331    message: Option<String>,
332    result: serde_json::Value,
333}
334
335#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
336#[serde(rename_all = "snake_case")]
337pub enum EvmTransferKind {
338    Native,
339    Erc20,
340}
341
342#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
343pub struct EvmPaymentPreviewRequest {
344    pub chain: EvmChainConfig,
345    pub wallet_address: String,
346    pub recipient: String,
347    pub amount_wei_or_units: String,
348    pub token_contract: Option<String>,
349    pub memo: Option<String>,
350}
351
352#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
353pub struct EvmPaymentPreview {
354    pub preview_id: String,
355    pub chain: EvmChainConfig,
356    pub wallet_address: String,
357    pub recipient: String,
358    pub token_contract: Option<String>,
359    pub amount_wei_or_units: String,
360    pub gas_limit: String,
361    pub gas_price_wei: String,
362    pub max_fee_per_gas_wei: Option<String>,
363    pub max_priority_fee_per_gas_wei: Option<String>,
364    pub fee_model: String,
365    pub nonce: String,
366    pub estimated_fee_wei: String,
367    pub summary: String,
368    pub warnings: Vec<String>,
369}
370
371#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
372pub struct EvmPaymentSubmitRequest {
373    pub preview_id: String,
374    pub approved: bool,
375    pub chain: EvmChainConfig,
376    pub wallet_address: String,
377    pub keystore_json: String,
378    pub password: String,
379    pub recipient: String,
380    pub amount_wei_or_units: String,
381    pub token_contract: Option<String>,
382    pub gas_limit: Option<String>,
383    pub gas_price_wei: Option<String>,
384    pub max_fee_per_gas_wei: Option<String>,
385    pub max_priority_fee_per_gas_wei: Option<String>,
386    pub nonce: Option<String>,
387}
388
389#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
390pub struct EvmTransactionSubmitResult {
391    pub transaction_hash: String,
392    pub chain: EvmChainConfig,
393    pub submitted_at: String,
394    pub status: String,
395    pub block_number: Option<u64>,
396}
397
398#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
399pub struct EvmTransactionStatusRequest {
400    pub chain: EvmChainConfig,
401    pub transaction_hash: String,
402}
403
404#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
405pub struct EvmTransactionStatus {
406    pub transaction_hash: String,
407    pub chain: EvmChainConfig,
408    pub block_number: Option<u64>,
409    pub status: String,
410    pub gas_used: Option<String>,
411    pub effective_gas_price_wei: Option<String>,
412}
413
414#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
415pub struct EvmDappSignPreviewRequest {
416    pub chain: EvmChainConfig,
417    pub wallet_address: String,
418    pub app_name: String,
419    pub app_url: String,
420    pub method: String,
421    pub payload_json: String,
422}
423
424#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
425pub struct EvmDappSignPreview {
426    pub preview_id: String,
427    pub chain: EvmChainConfig,
428    pub wallet_address: String,
429    pub app_name: String,
430    pub app_url: String,
431    pub method: String,
432    pub summary: String,
433    pub warnings: Vec<String>,
434}
435
436#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
437pub struct EvmDappSignSubmitRequest {
438    pub preview_id: String,
439    pub approved: bool,
440    pub chain: EvmChainConfig,
441    pub wallet_address: String,
442    pub app_name: String,
443    pub app_url: String,
444    pub keystore_json: String,
445    pub password: String,
446    pub method: String,
447    pub payload_json: String,
448}
449
450#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
451pub struct EvmDappSignSubmitResult {
452    pub signature: Option<String>,
453    pub signed_transaction: Option<String>,
454    pub transaction: Option<EvmTransactionSubmitResult>,
455    pub status: String,
456}
457
458macro_rules! zeroize_fields_on_drop {
459    ($type:ty, $($field:ident),+ $(,)?) => {
460        impl Drop for $type {
461            fn drop(&mut self) {
462                $(self.$field.zeroize();)+
463            }
464        }
465    };
466}
467
468zeroize_fields_on_drop!(EvmCreateWalletRequest, password);
469zeroize_fields_on_drop!(EvmImportPrivateKeyRequest, private_key_hex, password);
470zeroize_fields_on_drop!(EvmImportMnemonicRequest, mnemonic, password);
471zeroize_fields_on_drop!(EvmImportKeystoreRequest, keystore_json, password);
472zeroize_fields_on_drop!(EvmUnlockWalletRequest, keystore_json, password);
473zeroize_fields_on_drop!(EvmExportPrivateKeyRequest, keystore_json, password);
474zeroize_fields_on_drop!(EvmExportPrivateKeyResponse, private_key_hex);
475zeroize_fields_on_drop!(EvmPaymentSubmitRequest, keystore_json, password);
476zeroize_fields_on_drop!(EvmDappSignSubmitRequest, keystore_json, password);
477
478#[derive(Debug, Deserialize, Serialize)]
479struct EvmKeystore {
480    version: u8,
481    wallet_family: String,
482    #[serde(default = "default_keystore_secret_type")]
483    secret_type: String,
484    address: String,
485    derivation_path: Option<String>,
486    crypto: EvmKeystoreCrypto,
487    metadata: EvmKeystoreMetadata,
488}
489
490struct DecryptedEvmKeystore {
491    signing_key: SigningKey,
492    keystore: EvmKeystore,
493}
494
495#[derive(Debug, Deserialize, Serialize)]
496struct EvmKeystoreCrypto {
497    kdf: String,
498    kdf_params: EvmKeystoreKdfParams,
499    cipher: String,
500    nonce: String,
501    ciphertext: String,
502}
503
504#[derive(Debug, Deserialize, Serialize)]
505struct EvmKeystoreKdfParams {
506    memory_kib: u32,
507    iterations: u32,
508    parallelism: u32,
509    salt: String,
510}
511
512#[derive(Debug, Deserialize, Serialize)]
513struct EvmKeystoreMetadata {
514    wallet_name: String,
515}
516
517fn default_keystore_secret_type() -> String {
518    KEYSTORE_SECRET_PRIVATE_KEY.to_string()
519}
520
521#[derive(Debug, Deserialize)]
522struct JsonRpcResponse {
523    result: Option<serde_json::Value>,
524    error: Option<JsonRpcError>,
525}
526
527#[derive(Debug, Deserialize)]
528struct JsonRpcError {
529    message: String,
530}
531
532pub fn builtin_chains() -> Vec<EvmChainConfig> {
533    vec![
534        chain(
535            1,
536            "Ethereum",
537            "ETH",
538            "https://ethereum-rpc.publicnode.com",
539            Some("https://etherscan.io"),
540            false,
541        ),
542        chain(
543            56,
544            "BNB Smart Chain",
545            "BNB",
546            "https://bsc-rpc.publicnode.com",
547            Some("https://bscscan.com"),
548            false,
549        ),
550        chain(
551            137,
552            "Polygon",
553            "POL",
554            "https://polygon-bor-rpc.publicnode.com",
555            Some("https://polygonscan.com"),
556            false,
557        ),
558        chain(
559            42161,
560            "Arbitrum One",
561            "ETH",
562            "https://arb1.arbitrum.io/rpc",
563            Some("https://arbiscan.io"),
564            false,
565        ),
566        chain(
567            10,
568            "Optimism",
569            "ETH",
570            "https://optimism-rpc.publicnode.com",
571            Some("https://optimistic.etherscan.io"),
572            false,
573        ),
574        chain(
575            8453,
576            "Base",
577            "ETH",
578            "https://mainnet.base.org",
579            Some("https://basescan.org"),
580            false,
581        ),
582        chain(
583            43114,
584            "Avalanche C-Chain",
585            "AVAX",
586            "https://api.avax.network/ext/bc/C/rpc",
587            Some("https://snowtrace.io"),
588            false,
589        ),
590        chain(
591            250,
592            "Fantom Opera",
593            "FTM",
594            "https://rpcapi.fantom.network",
595            Some("https://ftmscan.com"),
596            false,
597        ),
598        chain(
599            59144,
600            "Linea",
601            "ETH",
602            "https://rpc.linea.build",
603            Some("https://lineascan.build"),
604            false,
605        ),
606        chain(
607            534352,
608            "Scroll",
609            "ETH",
610            "https://rpc.scroll.io",
611            Some("https://scrollscan.com"),
612            false,
613        ),
614        chain(
615            324,
616            "zkSync Era",
617            "ETH",
618            "https://mainnet.era.zksync.io",
619            Some("https://explorer.zksync.io"),
620            false,
621        ),
622        chain(
623            4663,
624            "Robinhood Chain",
625            "ETH",
626            "https://rpc.mainnet.chain.robinhood.com",
627            Some("https://robinscan.io"),
628            false,
629        ),
630        chain(
631            5042,
632            "Arc",
633            "USDC",
634            "https://rpc.mainnet.arc.io",
635            Some("https://explorer.arc.io"),
636            false,
637        ),
638        chain(
639            5042002,
640            "Arc Testnet",
641            "USDC",
642            "https://rpc.testnet.arc.io",
643            Some("https://explorer.testnet.arc.io"),
644            true,
645        ),
646        chain(
647            11155111,
648            "Ethereum Sepolia",
649            "ETH",
650            "https://ethereum-sepolia-rpc.publicnode.com",
651            Some("https://sepolia.etherscan.io"),
652            true,
653        ),
654        chain(
655            97,
656            "BSC Testnet",
657            "tBNB",
658            "https://bsc-testnet-rpc.publicnode.com",
659            Some("https://testnet.bscscan.com"),
660            true,
661        ),
662        chain(
663            80002,
664            "Polygon Amoy",
665            "POL",
666            "https://polygon-amoy-bor-rpc.publicnode.com",
667            Some("https://amoy.polygonscan.com"),
668            true,
669        ),
670        chain(
671            84532,
672            "Base Sepolia",
673            "ETH",
674            "https://sepolia.base.org",
675            Some("https://sepolia.basescan.org"),
676            true,
677        ),
678    ]
679}
680
681pub fn builtin_chain_adapters() -> ChainResult<Vec<EvmChainAdapter>> {
682    builtin_chains()
683        .into_iter()
684        .map(EvmChainAdapter::new)
685        .collect()
686}
687
688pub fn create_wallet(req: EvmCreateWalletRequest) -> EvmResult<EvmWalletKeystore> {
689    let name = require_non_empty(&req.name, "wallet name")?;
690    require_non_empty(&req.password, "wallet password")?;
691    let signing_key = SigningKey::random(&mut OsRng);
692    wallet_from_signing_key(name, signing_key, &req.password, None)
693}
694
695pub fn import_private_key(req: EvmImportPrivateKeyRequest) -> EvmResult<EvmWalletKeystore> {
696    let name = require_non_empty(&req.name, "wallet name")?;
697    require_non_empty(&req.password, "wallet password")?;
698    let signing_key = signing_key_from_hex(&req.private_key_hex)?;
699    wallet_from_signing_key(name, signing_key, &req.password, None)
700}
701
702pub fn import_mnemonic(req: EvmImportMnemonicRequest) -> EvmResult<EvmWalletKeystore> {
703    let name = require_non_empty(&req.name, "wallet name")?;
704    require_non_empty(&req.password, "wallet password")?;
705    let mnemonic = Zeroizing::new(normalize_mnemonic_phrase(&req.mnemonic)?);
706    let derivation_path = req
707        .derivation_path
708        .as_deref()
709        .map(str::trim)
710        .filter(|value| !value.is_empty())
711        .unwrap_or(DEFAULT_EVM_DERIVATION_PATH)
712        .to_string();
713    let signing_key = signing_key_from_mnemonic(&mnemonic, &derivation_path)?;
714    let address = address_from_signing_key(&signing_key);
715    let keystore_json = encrypt_keystore(
716        &signing_key,
717        mnemonic.as_bytes(),
718        KEYSTORE_SECRET_MNEMONIC,
719        &req.password,
720        &name,
721        Some(derivation_path.clone()),
722    )?;
723    Ok(EvmWalletKeystore {
724        wallet: wallet_summary(name, address, Some(derivation_path)),
725        keystore_json,
726    })
727}
728
729pub fn address_from_mnemonic(mnemonic: &str, derivation_path: Option<&str>) -> EvmResult<String> {
730    let mnemonic = Zeroizing::new(normalize_mnemonic_phrase(mnemonic)?);
731    let derivation_path = derivation_path
732        .map(str::trim)
733        .filter(|value| !value.is_empty())
734        .unwrap_or(DEFAULT_EVM_DERIVATION_PATH);
735    let signing_key = signing_key_from_mnemonic(&mnemonic, derivation_path)?;
736    Ok(address_from_signing_key(&signing_key))
737}
738
739pub fn import_keystore(req: EvmImportKeystoreRequest) -> EvmResult<EvmWalletKeystore> {
740    let name = require_non_empty(&req.name, "wallet name")?;
741    let DecryptedEvmKeystore {
742        signing_key,
743        mut keystore,
744    } = decrypt_keystore(&req.keystore_json, &req.password)?;
745    keystore.metadata.wallet_name = name.clone();
746    let address = address_from_signing_key(&signing_key);
747    let keystore_json = serde_json::to_string(&keystore).map_err(|_| {
748        EvmServiceError::InvalidInput("Failed to encode EVM keystore JSON".to_string())
749    })?;
750    Ok(EvmWalletKeystore {
751        wallet: wallet_summary(name, address, keystore.derivation_path),
752        keystore_json,
753    })
754}
755
756pub fn unlock_wallet(req: EvmUnlockWalletRequest) -> EvmResult<EvmWalletSummary> {
757    unlock_signing_key(&req).map(|(wallet, _)| wallet)
758}
759
760/// Unlocks an EVM keystore for trusted in-process callers.
761///
762/// The returned private key is zeroized on drop and must never cross an IPC or
763/// serialization boundary.
764pub fn unlock_private_key(
765    req: EvmUnlockWalletRequest,
766) -> EvmResult<(EvmWalletSummary, Zeroizing<Vec<u8>>)> {
767    let (wallet, signing_key) = unlock_signing_key(&req)?;
768    let private_key = Zeroizing::new(signing_key.to_bytes().to_vec());
769    Ok((wallet, private_key))
770}
771
772/// Resolve a standalone EVM keystore **or** a FnzSafe universal mnemonic
773/// keystore that embeds `metadata.evm_keystore_json`.
774///
775/// Bot / deploy tooling can pass the exported `.json` file contents directly.
776pub fn resolve_evm_keystore_json(document_json: &str) -> EvmResult<String> {
777    if document_json.len() > MAX_KEYSTORE_JSON_BYTES {
778        return Err(EvmServiceError::InvalidInput(
779            "Keystore JSON is too large".to_string(),
780        ));
781    }
782    require_non_empty(document_json, "keystore json")?;
783    let doc: serde_json::Value = serde_json::from_str(document_json)
784        .map_err(|_| EvmServiceError::InvalidInput("Invalid keystore JSON".to_string()))?;
785    if doc
786        .get("wallet_family")
787        .and_then(serde_json::Value::as_str)
788        == Some("evm")
789    {
790        return Ok(document_json.to_string());
791    }
792    if let Some(nested) = doc
793        .pointer("/metadata/evm_keystore_json")
794        .and_then(serde_json::Value::as_str)
795    {
796        // Validate nested document parses before returning.
797        let nested_doc: serde_json::Value = serde_json::from_str(nested).map_err(|_| {
798            EvmServiceError::InvalidInput("Invalid nested EVM keystore JSON".to_string())
799        })?;
800        if nested_doc
801            .get("wallet_family")
802            .and_then(serde_json::Value::as_str)
803            != Some("evm")
804        {
805            return Err(EvmServiceError::InvalidInput(
806                "Nested metadata.evm_keystore_json is not an EVM keystore".to_string(),
807            ));
808        }
809        return Ok(nested.to_string());
810    }
811    Err(EvmServiceError::InvalidInput(
812        "Document is neither an EVM keystore nor a universal keystore with metadata.evm_keystore_json"
813            .to_string(),
814    ))
815}
816
817/// Unlock from a universal or EVM keystore document (file contents).
818pub fn unlock_private_key_from_document(
819    document_json: &str,
820    password: &str,
821) -> EvmResult<(EvmWalletSummary, Zeroizing<Vec<u8>>)> {
822    let keystore_json = resolve_evm_keystore_json(document_json)?;
823    unlock_private_key(EvmUnlockWalletRequest {
824        keystore_json,
825        password: password.to_string(),
826    })
827}
828
829fn unlock_signing_key(req: &EvmUnlockWalletRequest) -> EvmResult<(EvmWalletSummary, SigningKey)> {
830    let DecryptedEvmKeystore {
831        signing_key,
832        keystore,
833    } = decrypt_keystore(&req.keystore_json, &req.password)?;
834    let address = address_from_signing_key(&signing_key);
835    let wallet = wallet_summary(
836        keystore.metadata.wallet_name,
837        address,
838        keystore.derivation_path,
839    );
840    Ok((wallet, signing_key))
841}
842
843pub fn export_private_key(
844    req: EvmExportPrivateKeyRequest,
845) -> EvmResult<EvmExportPrivateKeyResponse> {
846    let signing_key = decrypt_keystore(&req.keystore_json, &req.password)?.signing_key;
847    Ok(EvmExportPrivateKeyResponse {
848        address: address_from_signing_key(&signing_key),
849        private_key_hex: format!("0x{}", hex::encode(signing_key.to_bytes())),
850    })
851}
852
853pub fn load_asset_snapshot(req: EvmAssetQueryRequest) -> EvmResult<EvmAssetSnapshot> {
854    load_asset_snapshot_with_history(req, true)
855}
856
857pub fn load_asset_snapshot_without_history(
858    req: EvmAssetQueryRequest,
859) -> EvmResult<EvmAssetSnapshot> {
860    load_asset_snapshot_with_history(req, false)
861}
862
863fn load_asset_snapshot_with_history(
864    req: EvmAssetQueryRequest,
865    include_history: bool,
866) -> EvmResult<EvmAssetSnapshot> {
867    validate_chain(&req.chain)?;
868    validate_rpc_chain_id(&req.chain)?;
869    let wallet_address = normalize_address(&req.wallet_address, "wallet address")?;
870    let native_balance_wei = rpc_call(
871        &req.chain,
872        "eth_getBalance",
873        serde_json::json!([wallet_address, "latest"]),
874    )
875    .and_then(rpc_hex_quantity_to_decimal)
876    .map_err(|_| EvmServiceError::RpcUnavailable)?;
877
878    let mut tokens = Vec::new();
879    for query in req.tokens {
880        if is_native_token_alias(req.chain.chain_id, query.contract_address.trim()) {
881            continue;
882        }
883        tokens.push(load_token_asset(
884            &req.chain,
885            &wallet_address,
886            &query.contract_address,
887        )?);
888    }
889    enrich_token_metadata(&req.chain, &mut tokens);
890
891    let (recent_transactions, history_status, history_message) = if include_history {
892        load_recent_transactions(&req.chain, &wallet_address)
893    } else {
894        (Vec::new(), "not_requested".to_string(), None)
895    };
896
897    Ok(EvmAssetSnapshot {
898        chain: req.chain,
899        wallet_address,
900        native_balance_wei,
901        tokens,
902        recent_transactions,
903        history_status,
904        history_message,
905        refreshed_at_ms: now_ms(),
906    })
907}
908
909pub fn preview_payment(req: EvmPaymentPreviewRequest) -> EvmResult<EvmPaymentPreview> {
910    validate_chain(&req.chain)?;
911    validate_rpc_chain_id(&req.chain)?;
912    let wallet_address = normalize_address(&req.wallet_address, "wallet address")?;
913    let recipient = normalize_address(&req.recipient, "recipient")?;
914    let amount = normalize_decimal(&req.amount_wei_or_units, "amount")?;
915    let token_contract = req
916        .token_contract
917        .as_deref()
918        .map(|value| normalize_address(value, "token contract"))
919        .transpose()?;
920
921    if token_contract
922        .as_deref()
923        .is_none_or(|contract| is_native_token_alias(req.chain.chain_id, contract))
924    {
925        validate_arc_recipient(req.chain.chain_id, &recipient, &amount)?;
926    }
927
928    let data = token_contract
929        .as_deref()
930        .map(|_| erc20_transfer_calldata(&recipient, &amount))
931        .transpose()?
932        .unwrap_or_default();
933    let to = token_contract.clone().unwrap_or_else(|| recipient.clone());
934    let value = if token_contract.is_some() {
935        "0"
936    } else {
937        amount.as_str()
938    };
939    let nonce = rpc_call(
940        &req.chain,
941        "eth_getTransactionCount",
942        serde_json::json!([wallet_address, "pending"]),
943    )
944    .and_then(rpc_hex_quantity_to_decimal)
945    .map_err(|_| EvmServiceError::RpcUnavailable)?;
946    let fee_quote = load_fee_quote(&req.chain)?;
947    let gas_limit = estimate_gas(&req.chain, &wallet_address, &to, value, &data)?;
948    let estimated_fee_wei = decimal_mul(&fee_quote.max_fee_per_gas_wei(), &gas_limit)?;
949
950    let preview_id = payment_preview_id(&PaymentPreviewIdInput {
951        chain: &req.chain,
952        wallet_address: &wallet_address,
953        recipient: &recipient,
954        token_contract: token_contract.as_deref(),
955        amount_wei_or_units: &amount,
956        gas_limit: &gas_limit,
957        gas_price_wei: &fee_quote.gas_price_wei,
958        max_fee_per_gas_wei: fee_quote.max_fee_per_gas_wei.as_deref(),
959        max_priority_fee_per_gas_wei: fee_quote.max_priority_fee_per_gas_wei.as_deref(),
960        nonce: &nonce,
961    });
962
963    Ok(EvmPaymentPreview {
964        preview_id,
965        chain: req.chain,
966        wallet_address,
967        recipient,
968        token_contract,
969        amount_wei_or_units: amount,
970        gas_limit,
971        gas_price_wei: fee_quote.gas_price_wei.clone(),
972        max_fee_per_gas_wei: fee_quote.max_fee_per_gas_wei,
973        max_priority_fee_per_gas_wei: fee_quote.max_priority_fee_per_gas_wei,
974        fee_model: fee_quote.fee_model,
975        nonce,
976        estimated_fee_wei,
977        summary: "Prepare EVM transfer".to_string(),
978        warnings: vec![
979            "Review chain id, recipient, token, gas, and dApp origin before signing.".to_string(),
980        ],
981    })
982}
983
984pub fn submit_payment(req: EvmPaymentSubmitRequest) -> EvmResult<EvmTransactionSubmitResult> {
985    submit_payment_with_key_loader(&req, || {
986        decrypt_keystore(&req.keystore_json, &req.password).map(|decrypted| decrypted.signing_key)
987    })
988}
989
990pub fn submit_payment_with_private_key(
991    req: EvmPaymentSubmitRequest,
992    private_key: &[u8],
993) -> EvmResult<EvmTransactionSubmitResult> {
994    submit_payment_with_key_loader(&req, || signing_key_from_bytes(private_key))
995}
996
997pub fn submit_payment_with_private_key_loader<F>(
998    req: EvmPaymentSubmitRequest,
999    load_private_key: F,
1000) -> EvmResult<EvmTransactionSubmitResult>
1001where
1002    F: FnOnce() -> Result<Zeroizing<Vec<u8>>, String>,
1003{
1004    submit_payment_with_key_loader(&req, || {
1005        let private_key = load_private_key().map_err(EvmServiceError::InvalidInput)?;
1006        signing_key_from_bytes(private_key.as_slice())
1007    })
1008}
1009
1010fn submit_payment_with_key_loader<F>(
1011    req: &EvmPaymentSubmitRequest,
1012    load_signing_key: F,
1013) -> EvmResult<EvmTransactionSubmitResult>
1014where
1015    F: FnOnce() -> EvmResult<SigningKey>,
1016{
1017    require_non_empty(&req.preview_id, "preview id")?;
1018    if !req.approved {
1019        return Err(EvmServiceError::UserRejected);
1020    }
1021    validate_chain(&req.chain)?;
1022    let wallet_address = normalize_address(&req.wallet_address, "wallet address")?;
1023    let recipient = normalize_address(&req.recipient, "recipient")?;
1024    let amount = normalize_decimal(&req.amount_wei_or_units, "amount")?;
1025    let token_contract = req
1026        .token_contract
1027        .as_deref()
1028        .map(|value| normalize_address(value, "token contract"))
1029        .transpose()?;
1030    if token_contract
1031        .as_deref()
1032        .is_none_or(|contract| is_native_token_alias(req.chain.chain_id, contract))
1033    {
1034        validate_arc_recipient(req.chain.chain_id, &recipient, &amount)?;
1035    }
1036    let data = token_contract
1037        .as_deref()
1038        .map(|_| erc20_transfer_calldata(&recipient, &amount))
1039        .transpose()?
1040        .unwrap_or_default();
1041    let to = token_contract.clone().unwrap_or_else(|| recipient.clone());
1042    let value = if data.is_empty() {
1043        amount.as_str()
1044    } else {
1045        "0"
1046    };
1047    let nonce = required_decimal_option(req.nonce.as_deref(), "nonce")?;
1048    let gas_limit = required_decimal_option(req.gas_limit.as_deref(), "gas limit")?;
1049    let gas_price_wei = required_decimal_option(req.gas_price_wei.as_deref(), "gas price")?;
1050    let max_fee_per_gas_wei = req
1051        .max_fee_per_gas_wei
1052        .as_deref()
1053        .map(|value| normalize_decimal(value, "max fee per gas"))
1054        .transpose()?;
1055    let max_priority_fee_per_gas_wei = req
1056        .max_priority_fee_per_gas_wei
1057        .as_deref()
1058        .map(|value| normalize_decimal(value, "max priority fee per gas"))
1059        .transpose()?;
1060    if max_fee_per_gas_wei.is_some() != max_priority_fee_per_gas_wei.is_some() {
1061        return Err(EvmServiceError::InvalidInput(
1062            "EIP-1559 fee fields must be submitted together".to_string(),
1063        ));
1064    }
1065    let expected_preview_id = payment_preview_id(&PaymentPreviewIdInput {
1066        chain: &req.chain,
1067        wallet_address: &wallet_address,
1068        recipient: &recipient,
1069        token_contract: token_contract.as_deref(),
1070        amount_wei_or_units: &amount,
1071        gas_limit: &gas_limit,
1072        gas_price_wei: &gas_price_wei,
1073        max_fee_per_gas_wei: max_fee_per_gas_wei.as_deref(),
1074        max_priority_fee_per_gas_wei: max_priority_fee_per_gas_wei.as_deref(),
1075        nonce: &nonce,
1076    });
1077    if req.preview_id != expected_preview_id {
1078        return Err(EvmServiceError::InvalidInput(
1079            "EVM payment preview is stale or mismatched".to_string(),
1080        ));
1081    }
1082    let signing_key = load_signing_key()?;
1083    let from = address_from_signing_key(&signing_key);
1084    if !address_eq(&from, &wallet_address) {
1085        return Err(EvmServiceError::InvalidInput(
1086            "EVM signing key does not match preview wallet address".to_string(),
1087        ));
1088    }
1089    let current_nonce = load_nonce(&req.chain, &wallet_address)?;
1090    ensure_preview_nonce_is_current(&nonce, &current_nonce)?;
1091    let raw_tx = sign_evm_transaction(&EvmTxSigningInput {
1092        signing_key: &signing_key,
1093        chain_id: req.chain.chain_id,
1094        nonce: &nonce,
1095        gas_limit: &gas_limit,
1096        to: &to,
1097        value,
1098        data: &data,
1099        gas_price_wei: &gas_price_wei,
1100        max_fee_per_gas_wei: max_fee_per_gas_wei.as_deref(),
1101        max_priority_fee_per_gas_wei: max_priority_fee_per_gas_wei.as_deref(),
1102    })?;
1103    let tx_hash = send_raw_transaction(&req.chain, &raw_tx)?;
1104
1105    Ok(EvmTransactionSubmitResult {
1106        transaction_hash: tx_hash,
1107        chain: req.chain.clone(),
1108        submitted_at: submitted_at(),
1109        status: format!("broadcast from {from}; awaiting confirmation"),
1110        block_number: None,
1111    })
1112}
1113
1114pub fn preview_dapp_signing(req: EvmDappSignPreviewRequest) -> EvmResult<EvmDappSignPreview> {
1115    validate_chain(&req.chain)?;
1116    let wallet_address = normalize_address(&req.wallet_address, "wallet address")?;
1117    let app_name = require_non_empty(&req.app_name, "dApp name")?;
1118    let app_url = require_non_empty(&req.app_url, "dApp URL")?;
1119    let method = require_non_empty(&req.method, "dApp method")?;
1120    let payload_json = require_non_empty(&req.payload_json, "dApp payload")?;
1121    let preview_id = dapp_sign_preview_id(&DappSignPreviewIdInput {
1122        chain: &req.chain,
1123        wallet_address: &wallet_address,
1124        app_name: &app_name,
1125        app_url: &app_url,
1126        method: &method,
1127        payload_json: &payload_json,
1128    });
1129    Ok(EvmDappSignPreview {
1130        preview_id,
1131        chain: req.chain,
1132        wallet_address,
1133        app_name,
1134        app_url: app_url.clone(),
1135        method: method.clone(),
1136        summary: format!("{app_url} requested {method}"),
1137        warnings: vec!["Only approve EVM dApp requests from sites you trust.".to_string()],
1138    })
1139}
1140
1141pub fn submit_dapp_signing(req: EvmDappSignSubmitRequest) -> EvmResult<EvmDappSignSubmitResult> {
1142    submit_dapp_signing_with_key_loader(&req, || {
1143        decrypt_keystore(&req.keystore_json, &req.password).map(|decrypted| decrypted.signing_key)
1144    })
1145}
1146
1147pub fn submit_dapp_signing_with_private_key(
1148    req: EvmDappSignSubmitRequest,
1149    private_key: &[u8],
1150) -> EvmResult<EvmDappSignSubmitResult> {
1151    submit_dapp_signing_with_key_loader(&req, || signing_key_from_bytes(private_key))
1152}
1153
1154pub fn submit_dapp_signing_with_private_key_loader<F>(
1155    req: EvmDappSignSubmitRequest,
1156    load_private_key: F,
1157) -> EvmResult<EvmDappSignSubmitResult>
1158where
1159    F: FnOnce() -> Result<Zeroizing<Vec<u8>>, String>,
1160{
1161    submit_dapp_signing_with_key_loader(&req, || {
1162        let private_key = load_private_key().map_err(EvmServiceError::InvalidInput)?;
1163        signing_key_from_bytes(private_key.as_slice())
1164    })
1165}
1166
1167fn submit_dapp_signing_with_key_loader<F>(
1168    req: &EvmDappSignSubmitRequest,
1169    load_signing_key: F,
1170) -> EvmResult<EvmDappSignSubmitResult>
1171where
1172    F: FnOnce() -> EvmResult<SigningKey>,
1173{
1174    require_non_empty(&req.preview_id, "preview id")?;
1175    if !req.approved {
1176        return Err(EvmServiceError::UserRejected);
1177    }
1178    validate_chain(&req.chain)?;
1179    let wallet_address = normalize_address(&req.wallet_address, "wallet address")?;
1180    let app_name = require_non_empty(&req.app_name, "dApp name")?;
1181    let app_url = require_non_empty(&req.app_url, "dApp URL")?;
1182    let method = require_non_empty(&req.method, "dApp method")?;
1183    let payload_json = require_non_empty(&req.payload_json, "dApp payload")?;
1184    let expected_preview_id = dapp_sign_preview_id(&DappSignPreviewIdInput {
1185        chain: &req.chain,
1186        wallet_address: &wallet_address,
1187        app_name: &app_name,
1188        app_url: &app_url,
1189        method: &method,
1190        payload_json: &payload_json,
1191    });
1192    if req.preview_id != expected_preview_id {
1193        return Err(EvmServiceError::InvalidInput(
1194            "EVM dApp preview is stale or mismatched".to_string(),
1195        ));
1196    }
1197    let signing_key = load_signing_key()?;
1198    let signing_address = address_from_signing_key(&signing_key);
1199    if !address_eq(&signing_address, &wallet_address) {
1200        return Err(EvmServiceError::InvalidInput(
1201            "EVM signing key does not match preview wallet address".to_string(),
1202        ));
1203    }
1204    match method.as_str() {
1205        "personal_sign" | "eth_sign" => {
1206            let message = evm_message_from_payload(&payload_json, &wallet_address)?;
1207            Ok(EvmDappSignSubmitResult {
1208                signature: Some(sign_personal_message(&signing_key, &message)?),
1209                signed_transaction: None,
1210                transaction: None,
1211                status: "signed".to_string(),
1212            })
1213        }
1214        "eth_signTypedData" | "eth_signTypedData_v4" => {
1215            let digest = typed_data_digest(&payload_json)?;
1216            Ok(EvmDappSignSubmitResult {
1217                signature: Some(sign_hash(&signing_key, &digest)?),
1218                signed_transaction: None,
1219                transaction: None,
1220                status: "signed".to_string(),
1221            })
1222        }
1223        "eth_sendTransaction" | "eth_signTransaction" => {
1224            let from = address_from_signing_key(&signing_key);
1225            let tx = parse_dapp_transaction(&req.chain, &from, &payload_json)?;
1226            let raw_tx = sign_evm_transaction(&EvmTxSigningInput {
1227                signing_key: &signing_key,
1228                chain_id: req.chain.chain_id,
1229                nonce: &tx.nonce,
1230                gas_limit: &tx.gas_limit,
1231                to: &tx.to,
1232                value: &tx.value,
1233                data: &tx.data,
1234                gas_price_wei: &tx.gas_price_wei,
1235                max_fee_per_gas_wei: tx.max_fee_per_gas_wei.as_deref(),
1236                max_priority_fee_per_gas_wei: tx.max_priority_fee_per_gas_wei.as_deref(),
1237            })?;
1238            if method == "eth_signTransaction" {
1239                return Ok(EvmDappSignSubmitResult {
1240                    signature: None,
1241                    signed_transaction: Some(raw_tx),
1242                    transaction: None,
1243                    status: "signed".to_string(),
1244                });
1245            }
1246            let tx_hash = send_raw_transaction(&req.chain, &raw_tx)?;
1247            Ok(EvmDappSignSubmitResult {
1248                signature: Some(tx_hash.clone()),
1249                signed_transaction: None,
1250                transaction: Some(EvmTransactionSubmitResult {
1251                    transaction_hash: tx_hash,
1252                    chain: req.chain.clone(),
1253                    submitted_at: submitted_at(),
1254                    status: "submitted".to_string(),
1255                    block_number: None,
1256                }),
1257                status: "submitted".to_string(),
1258            })
1259        }
1260        _ => Err(EvmServiceError::InvalidInput(
1261            "Unsupported EVM dApp signing method".to_string(),
1262        )),
1263    }
1264}
1265
1266pub fn transaction_status(req: EvmTransactionStatusRequest) -> EvmResult<EvmTransactionStatus> {
1267    validate_chain(&req.chain)?;
1268    validate_rpc_chain_id(&req.chain)?;
1269    let transaction_hash = normalize_tx_hash(&req.transaction_hash)?;
1270    let receipt = rpc_call(
1271        &req.chain,
1272        "eth_getTransactionReceipt",
1273        serde_json::json!([transaction_hash]),
1274    )?;
1275    if receipt.is_null() {
1276        return Ok(EvmTransactionStatus {
1277            transaction_hash,
1278            chain: req.chain,
1279            block_number: None,
1280            status: "pending".to_string(),
1281            gas_used: None,
1282            effective_gas_price_wei: None,
1283        });
1284    }
1285    let block_number = receipt
1286        .get("blockNumber")
1287        .and_then(serde_json::Value::as_str)
1288        .and_then(|value| hex_quantity_to_u64(value).ok());
1289    let status = match receipt.get("status").and_then(serde_json::Value::as_str) {
1290        Some("0x1") => "confirmed",
1291        Some("0x0") => "failed",
1292        _ => "unknown",
1293    }
1294    .to_string();
1295    let gas_used = receipt
1296        .get("gasUsed")
1297        .and_then(serde_json::Value::as_str)
1298        .and_then(|value| hex_quantity_to_decimal(value).ok());
1299    let effective_gas_price_wei = receipt
1300        .get("effectiveGasPrice")
1301        .and_then(serde_json::Value::as_str)
1302        .and_then(|value| hex_quantity_to_decimal(value).ok());
1303
1304    Ok(EvmTransactionStatus {
1305        transaction_hash,
1306        chain: req.chain,
1307        block_number,
1308        status,
1309        gas_used,
1310        effective_gas_price_wei,
1311    })
1312}
1313
1314pub fn erc20_transfer_calldata(recipient: &str, amount_units: &str) -> EvmResult<String> {
1315    let recipient = normalize_address(recipient, "recipient")?;
1316    let amount = decimal_to_32_bytes(amount_units)?;
1317    let mut bytes = Vec::with_capacity(68);
1318    bytes.extend_from_slice(&ERC20_TRANSFER_SELECTOR);
1319    bytes.extend_from_slice(&[0u8; 12]);
1320    bytes.extend_from_slice(&address_bytes(&recipient)?);
1321    bytes.extend_from_slice(&amount);
1322    Ok(format!("0x{}", hex::encode(bytes)))
1323}
1324
1325pub fn sign_personal_message(signing_key: &SigningKey, message: &[u8]) -> EvmResult<String> {
1326    let prefix = format!("\x19Ethereum Signed Message:\n{}", message.len());
1327    let mut hasher = Keccak256::new();
1328    hasher.update(prefix.as_bytes());
1329    hasher.update(message);
1330    let digest = hasher.finalize();
1331    sign_hash(signing_key, digest.as_slice())
1332}
1333
1334fn chain(
1335    chain_id: u64,
1336    name: &str,
1337    native_symbol: &str,
1338    rpc_url: &str,
1339    explorer_url: Option<&str>,
1340    testnet: bool,
1341) -> EvmChainConfig {
1342    EvmChainConfig {
1343        chain_id,
1344        name: name.to_string(),
1345        native_symbol: native_symbol.to_string(),
1346        rpc_url: rpc_url.to_string(),
1347        explorer_url: explorer_url.map(str::to_string),
1348        testnet,
1349    }
1350}
1351
1352fn require_non_empty(value: &str, field: &'static str) -> EvmResult<String> {
1353    let trimmed = value.trim();
1354    if trimmed.is_empty() {
1355        return Err(EvmServiceError::InvalidInput(format!(
1356            "{field} is required"
1357        )));
1358    }
1359    Ok(trimmed.to_string())
1360}
1361
1362fn required_decimal_option(value: Option<&str>, field: &'static str) -> EvmResult<String> {
1363    let value = value.ok_or_else(|| {
1364        EvmServiceError::InvalidInput(format!("{field} is required from the approved preview"))
1365    })?;
1366    normalize_decimal(value, field)
1367}
1368
1369fn validate_chain(chain: &EvmChainConfig) -> EvmResult<()> {
1370    if chain.chain_id == 0 {
1371        return Err(EvmServiceError::InvalidChainId);
1372    }
1373    validate_chain_label(&chain.name, "chain name", 128)?;
1374    validate_chain_label(&chain.native_symbol, "native symbol", 32)?;
1375    let rpc_url = require_non_empty(&chain.rpc_url, "RPC URL")?;
1376    if rpc_url.len() > 2_048 {
1377        return Err(EvmServiceError::InvalidInput(
1378            "EVM RPC URL must not exceed 2048 bytes".to_string(),
1379        ));
1380    }
1381    let parsed = reqwest::Url::parse(&rpc_url).map_err(|_| {
1382        EvmServiceError::InvalidInput("EVM RPC URL must be a valid HTTP(S) URL".to_string())
1383    })?;
1384    let host = parsed.host_str().ok_or_else(|| {
1385        EvmServiceError::InvalidInput("EVM RPC URL must include a host".to_string())
1386    })?;
1387    let local_http = parsed.scheme() == "http" && is_loopback_host(host);
1388    if rpc_url != chain.rpc_url
1389        || (parsed.scheme() != "https" && !local_http)
1390        || !parsed.username().is_empty()
1391        || parsed.password().is_some()
1392        || parsed.fragment().is_some()
1393    {
1394        return Err(EvmServiceError::InvalidInput(
1395            "EVM RPC URL must use HTTPS (or loopback HTTP) without whitespace, credentials, or a fragment".to_string(),
1396        ));
1397    }
1398    if let Some(explorer_url) = chain.explorer_url.as_deref() {
1399        validate_explorer_origin(explorer_url)?;
1400    }
1401    Ok(())
1402}
1403
1404fn validate_chain_label(value: &str, field: &'static str, max_bytes: usize) -> EvmResult<()> {
1405    let trimmed = require_non_empty(value, field)?;
1406    if trimmed != value || value.len() > max_bytes {
1407        return Err(EvmServiceError::InvalidInput(format!(
1408            "{field} must not contain surrounding whitespace or exceed {max_bytes} bytes"
1409        )));
1410    }
1411    Ok(())
1412}
1413
1414fn is_loopback_host(host: &str) -> bool {
1415    host.eq_ignore_ascii_case("localhost")
1416        || std::net::IpAddr::from_str(host.trim_matches(['[', ']']))
1417            .is_ok_and(|address| address.is_loopback())
1418}
1419
1420fn validate_explorer_origin(explorer_url: &str) -> EvmResult<()> {
1421    if explorer_url.is_empty() || explorer_url.len() > 2_048 || explorer_url.trim() != explorer_url
1422    {
1423        return Err(EvmServiceError::InvalidInput(
1424            "EVM explorer URL must be a bounded HTTPS origin".to_string(),
1425        ));
1426    }
1427    let parsed = reqwest::Url::parse(explorer_url).map_err(|_| {
1428        EvmServiceError::InvalidInput("EVM explorer URL must be a valid HTTPS origin".to_string())
1429    })?;
1430    if parsed.scheme() != "https"
1431        || parsed.host_str().is_none()
1432        || !parsed.username().is_empty()
1433        || parsed.password().is_some()
1434        || !matches!(parsed.path(), "" | "/")
1435        || parsed.query().is_some()
1436        || parsed.fragment().is_some()
1437    {
1438        return Err(EvmServiceError::InvalidInput(
1439            "EVM explorer URL must be an HTTPS origin without credentials, path, query, or fragment"
1440                .to_string(),
1441        ));
1442    }
1443    Ok(())
1444}
1445
1446fn validate_evm_adapter_path(path_text: &str) -> ChainResult<()> {
1447    validate_derivation_path_input(path_text)?;
1448    let path = bip32::DerivationPath::from_str(path_text)
1449        .map_err(|error| ChainError::InvalidDerivationPath(error.to_string()))?;
1450    let components = path.as_ref();
1451    let valid = components.len() == 5
1452        && components[0].is_hardened()
1453        && components[0].index() == 44
1454        && components[1].is_hardened()
1455        && components[1].index() == 60
1456        && components[2].is_hardened()
1457        && !components[3].is_hardened()
1458        && matches!(components[3].index(), 0 | 1)
1459        && !components[4].is_hardened();
1460    if !valid {
1461        return Err(ChainError::InvalidDerivationPath(
1462            "expected EVM BIP44 path m/44'/60'/account'/change/index".to_string(),
1463        ));
1464    }
1465    Ok(())
1466}
1467
1468fn wallet_from_signing_key(
1469    name: String,
1470    signing_key: SigningKey,
1471    password: &str,
1472    derivation_path: Option<String>,
1473) -> EvmResult<EvmWalletKeystore> {
1474    let address = address_from_signing_key(&signing_key);
1475    let private_key = signing_key.to_bytes();
1476    let keystore_json = encrypt_keystore(
1477        &signing_key,
1478        private_key.as_slice(),
1479        KEYSTORE_SECRET_PRIVATE_KEY,
1480        password,
1481        &name,
1482        derivation_path.clone(),
1483    )?;
1484    Ok(EvmWalletKeystore {
1485        wallet: wallet_summary(name, address, derivation_path),
1486        keystore_json,
1487    })
1488}
1489
1490fn wallet_summary(
1491    name: String,
1492    address: String,
1493    derivation_path: Option<String>,
1494) -> EvmWalletSummary {
1495    EvmWalletSummary {
1496        id: format!(
1497            "evm-{}",
1498            address.trim_start_matches("0x").to_ascii_lowercase()
1499        ),
1500        name,
1501        address,
1502        derivation_path,
1503    }
1504}
1505
1506fn normalize_mnemonic_phrase(phrase: &str) -> EvmResult<String> {
1507    validate_mnemonic_input(phrase).map_err(|_| {
1508        EvmServiceError::InvalidInput("Mnemonic must contain at most 1024 bytes".to_string())
1509    })?;
1510    let normalized = phrase.split_whitespace().collect::<Vec<_>>().join(" ");
1511    if normalized.is_empty() {
1512        return Err(EvmServiceError::InvalidInput(
1513            "Mnemonic is required".to_string(),
1514        ));
1515    }
1516    Mnemonic::parse_in_normalized(Language::English, &normalized).map_err(|_| {
1517        EvmServiceError::InvalidInput(
1518            "Mnemonic checksum failed; check the words and order".to_string(),
1519        )
1520    })?;
1521    Ok(normalized)
1522}
1523
1524fn signing_key_from_mnemonic(mnemonic: &str, derivation_path: &str) -> EvmResult<SigningKey> {
1525    validate_derivation_path_input(derivation_path).map_err(|_| {
1526        EvmServiceError::InvalidInput(
1527            "Derivation path must contain between 1 and 256 bytes".to_string(),
1528        )
1529    })?;
1530    let mnemonic = Mnemonic::parse_in_normalized(Language::English, mnemonic)
1531        .map_err(|_| EvmServiceError::InvalidInput("Mnemonic checksum failed".to_string()))?;
1532    let path = bip32::DerivationPath::from_str(derivation_path).map_err(|error| {
1533        EvmServiceError::InvalidInput(format!("Invalid derivation path: {error}"))
1534    })?;
1535    let seed = Zeroizing::new(mnemonic.to_seed(""));
1536    let xprv = bip32::XPrv::derive_from_path(seed.as_slice(), &path).map_err(|error| {
1537        EvmServiceError::InvalidInput(format!("Failed to derive EVM key: {error}"))
1538    })?;
1539    let bytes = xprv.private_key().to_bytes();
1540    SigningKey::from_slice(bytes.as_slice())
1541        .map_err(|_| EvmServiceError::InvalidInput("Derived EVM key is invalid".to_string()))
1542}
1543
1544fn signing_key_from_hex(private_key_hex: &str) -> EvmResult<SigningKey> {
1545    let normalized = private_key_hex.trim().trim_start_matches("0x");
1546    if normalized.len() != 64 {
1547        return Err(EvmServiceError::InvalidInput(
1548            "EVM private key must be 32 bytes hex".to_string(),
1549        ));
1550    }
1551    let mut bytes =
1552        Zeroizing::new(hex::decode(normalized).map_err(|_| {
1553            EvmServiceError::InvalidInput("Private key must be valid hex".to_string())
1554        })?);
1555    let signing_key = SigningKey::from_slice(bytes.as_slice())
1556        .map_err(|_| EvmServiceError::InvalidInput("EVM private key is invalid".to_string()))?;
1557    bytes.zeroize();
1558    Ok(signing_key)
1559}
1560
1561fn signing_key_from_bytes(private_key: &[u8]) -> EvmResult<SigningKey> {
1562    SigningKey::from_slice(private_key)
1563        .map_err(|_| EvmServiceError::InvalidInput("EVM private key bytes are invalid".to_string()))
1564}
1565
1566fn address_from_signing_key(signing_key: &SigningKey) -> String {
1567    let verifying_key = signing_key.verifying_key();
1568    let encoded = verifying_key.to_encoded_point(false);
1569    let public_key = encoded.as_bytes();
1570    let hash = keccak256(&public_key[1..]);
1571    format!("0x{}", hex::encode(&hash[12..]))
1572}
1573
1574fn normalize_address(address: &str, field: &'static str) -> EvmResult<String> {
1575    let normalized = address.trim();
1576    let hex_part = normalized.strip_prefix("0x").unwrap_or(normalized);
1577    if hex_part.len() != 40 || !hex_part.chars().all(|ch| ch.is_ascii_hexdigit()) {
1578        return Err(EvmServiceError::InvalidInput(format!(
1579            "{field} must be a 20-byte EVM address"
1580        )));
1581    }
1582    let has_lowercase = hex_part.bytes().any(|byte| byte.is_ascii_lowercase());
1583    let has_uppercase = hex_part.bytes().any(|byte| byte.is_ascii_uppercase());
1584    if has_lowercase && has_uppercase && !has_valid_eip55_checksum(hex_part) {
1585        return Err(EvmServiceError::InvalidInput(format!(
1586            "{field} has an invalid EIP-55 checksum"
1587        )));
1588    }
1589    Ok(format!("0x{}", hex_part.to_ascii_lowercase()))
1590}
1591
1592fn has_valid_eip55_checksum(address: &str) -> bool {
1593    let lowercase = address.to_ascii_lowercase();
1594    let hash = hex::encode(keccak256(lowercase.as_bytes()));
1595    address
1596        .bytes()
1597        .zip(hash.bytes())
1598        .all(|(address_byte, hash_byte)| {
1599            !address_byte.is_ascii_alphabetic()
1600                || address_byte.is_ascii_uppercase() == (hash_byte >= b'8')
1601        })
1602}
1603
1604fn address_eq(left: &str, right: &str) -> bool {
1605    matches!(
1606        (
1607            normalize_address(left, "address"),
1608            normalize_address(right, "address")
1609        ),
1610        (Ok(left), Ok(right)) if left == right
1611    )
1612}
1613
1614fn address_bytes(address: &str) -> EvmResult<[u8; 20]> {
1615    let address = normalize_address(address, "address")?;
1616    let bytes = hex::decode(address.trim_start_matches("0x"))
1617        .map_err(|_| EvmServiceError::InvalidInput("Address must be valid hex".to_string()))?;
1618    bytes
1619        .try_into()
1620        .map_err(|_| EvmServiceError::InvalidInput("Address must be 20 bytes".to_string()))
1621}
1622
1623fn encrypt_keystore(
1624    signing_key: &SigningKey,
1625    secret: &[u8],
1626    secret_type: &str,
1627    password: &str,
1628    wallet_name: &str,
1629    derivation_path: Option<String>,
1630) -> EvmResult<String> {
1631    require_non_empty(password, "wallet password")?;
1632    let address = address_from_signing_key(signing_key);
1633    let mut salt = [0u8; KEYSTORE_SALT_BYTES];
1634    let mut rng = AeadOsRng;
1635    aes_gcm::aead::rand_core::RngCore::fill_bytes(&mut rng, &mut salt);
1636    let nonce = Aes256Gcm::generate_nonce(&mut rng);
1637    let key = derive_key(password, &salt)?;
1638    let cipher = Aes256Gcm::new_from_slice(key.as_slice()).map_err(|_| {
1639        EvmServiceError::InvalidInput("AES-256-GCM initialization failed".to_string())
1640    })?;
1641    let aad = keystore_aad_v2(&address, secret_type, derivation_path.as_deref());
1642    let ciphertext = cipher
1643        .encrypt(
1644            &nonce,
1645            Payload {
1646                msg: secret,
1647                aad: &aad,
1648            },
1649        )
1650        .map_err(|_| EvmServiceError::InvalidInput("EVM keystore encryption failed".to_string()))?;
1651    serde_json::to_string(&EvmKeystore {
1652        version: KEYSTORE_VERSION,
1653        wallet_family: "evm".to_string(),
1654        secret_type: secret_type.to_string(),
1655        address,
1656        derivation_path,
1657        crypto: EvmKeystoreCrypto {
1658            kdf: KEYSTORE_KDF.to_string(),
1659            kdf_params: EvmKeystoreKdfParams {
1660                memory_kib: ARGON2_MEMORY_KIB,
1661                iterations: ARGON2_ITERATIONS,
1662                parallelism: ARGON2_PARALLELISM,
1663                salt: BASE64.encode(salt),
1664            },
1665            cipher: KEYSTORE_CIPHER.to_string(),
1666            nonce: BASE64.encode(nonce),
1667            ciphertext: BASE64.encode(ciphertext),
1668        },
1669        metadata: EvmKeystoreMetadata {
1670            wallet_name: wallet_name.to_string(),
1671        },
1672    })
1673    .map_err(|_| EvmServiceError::InvalidInput("Failed to encode EVM keystore JSON".to_string()))
1674}
1675
1676fn decrypt_keystore(keystore_json: &str, password: &str) -> EvmResult<DecryptedEvmKeystore> {
1677    if keystore_json.len() > MAX_KEYSTORE_JSON_BYTES {
1678        return Err(EvmServiceError::InvalidInput(
1679            "EVM keystore JSON is too large".to_string(),
1680        ));
1681    }
1682    require_non_empty(keystore_json, "keystore json")?;
1683    require_non_empty(password, "wallet password")?;
1684    let document: serde_json::Value = serde_json::from_str(keystore_json)
1685        .map_err(|_| EvmServiceError::InvalidInput("Invalid EVM keystore JSON".to_string()))?;
1686    let has_explicit_secret_type = document
1687        .get("secret_type")
1688        .and_then(serde_json::Value::as_str)
1689        .is_some();
1690    let keystore: EvmKeystore = serde_json::from_value(document)
1691        .map_err(|_| EvmServiceError::InvalidInput("Invalid EVM keystore JSON".to_string()))?;
1692    if !matches!(keystore.version, LEGACY_KEYSTORE_VERSION | KEYSTORE_VERSION)
1693        || keystore.wallet_family != "evm"
1694    {
1695        return Err(EvmServiceError::InvalidInput(
1696            "Unsupported EVM keystore version".to_string(),
1697        ));
1698    }
1699    if keystore.version == KEYSTORE_VERSION && !has_explicit_secret_type {
1700        return Err(EvmServiceError::InvalidInput(
1701            "EVM v2 keystore is missing secret_type".to_string(),
1702        ));
1703    }
1704    if keystore.version == LEGACY_KEYSTORE_VERSION
1705        && keystore.secret_type != KEYSTORE_SECRET_PRIVATE_KEY
1706    {
1707        return Err(EvmServiceError::InvalidInput(
1708            "Legacy EVM keystore must contain a private key".to_string(),
1709        ));
1710    }
1711    if keystore.secret_type != KEYSTORE_SECRET_PRIVATE_KEY
1712        && keystore.secret_type != KEYSTORE_SECRET_MNEMONIC
1713    {
1714        return Err(EvmServiceError::InvalidInput(
1715            "Unsupported EVM keystore secret type".to_string(),
1716        ));
1717    }
1718    if keystore.crypto.kdf != KEYSTORE_KDF || keystore.crypto.cipher != KEYSTORE_CIPHER {
1719        return Err(EvmServiceError::InvalidInput(
1720            "Unsupported EVM keystore crypto".to_string(),
1721        ));
1722    }
1723    if keystore.crypto.kdf_params.memory_kib != ARGON2_MEMORY_KIB
1724        || keystore.crypto.kdf_params.iterations != ARGON2_ITERATIONS
1725        || keystore.crypto.kdf_params.parallelism != ARGON2_PARALLELISM
1726    {
1727        return Err(EvmServiceError::InvalidInput(
1728            "Unsupported EVM keystore KDF parameters".to_string(),
1729        ));
1730    }
1731    let salt: [u8; KEYSTORE_SALT_BYTES] = BASE64
1732        .decode(keystore.crypto.kdf_params.salt.as_bytes())
1733        .map_err(|_| EvmServiceError::InvalidInput("Keystore salt is invalid".to_string()))?
1734        .try_into()
1735        .map_err(|_| {
1736            EvmServiceError::InvalidInput("Keystore salt length is invalid".to_string())
1737        })?;
1738    let nonce_bytes: [u8; KEYSTORE_NONCE_BYTES] = BASE64
1739        .decode(keystore.crypto.nonce.as_bytes())
1740        .map_err(|_| EvmServiceError::InvalidInput("Keystore nonce is invalid".to_string()))?
1741        .try_into()
1742        .map_err(|_| {
1743            EvmServiceError::InvalidInput("Keystore nonce length is invalid".to_string())
1744        })?;
1745    let ciphertext = BASE64
1746        .decode(keystore.crypto.ciphertext.as_bytes())
1747        .map_err(|_| EvmServiceError::InvalidInput("Keystore ciphertext is invalid".to_string()))?;
1748    if ciphertext.len() <= KEYSTORE_TAG_BYTES
1749        || ciphertext.len() > MAX_KEYSTORE_SECRET_BYTES + KEYSTORE_TAG_BYTES
1750    {
1751        return Err(EvmServiceError::InvalidInput(
1752            "Keystore ciphertext length is invalid".to_string(),
1753        ));
1754    }
1755    let key = derive_key(password, &salt)?;
1756    let cipher = Aes256Gcm::new_from_slice(key.as_slice()).map_err(|_| {
1757        EvmServiceError::InvalidInput("AES-256-GCM initialization failed".to_string())
1758    })?;
1759    let aad = if keystore.version == LEGACY_KEYSTORE_VERSION {
1760        keystore_aad_v1(&keystore.address)
1761    } else {
1762        keystore_aad_v2(
1763            &keystore.address,
1764            &keystore.secret_type,
1765            keystore.derivation_path.as_deref(),
1766        )
1767    };
1768    let nonce = aes_gcm::Nonce::from(nonce_bytes);
1769    let plaintext = Zeroizing::new(
1770        cipher
1771            .decrypt(
1772                &nonce,
1773                Payload {
1774                    msg: &ciphertext,
1775                    aad: &aad,
1776                },
1777            )
1778            .map_err(|_| EvmServiceError::WrongPassword)?,
1779    );
1780    let signing_key = if keystore.secret_type == KEYSTORE_SECRET_PRIVATE_KEY {
1781        if plaintext.len() != PRIVATE_KEY_BYTES {
1782            return Err(EvmServiceError::WrongPassword);
1783        }
1784        SigningKey::from_slice(plaintext.as_slice()).map_err(|_| EvmServiceError::WrongPassword)?
1785    } else {
1786        let mnemonic = std::str::from_utf8(plaintext.as_slice()).map_err(|_| {
1787            EvmServiceError::InvalidInput("Decrypted mnemonic is not valid UTF-8".to_string())
1788        })?;
1789        let derivation_path = keystore.derivation_path.as_deref().ok_or_else(|| {
1790            EvmServiceError::InvalidInput(
1791                "Mnemonic keystore is missing its derivation path".to_string(),
1792            )
1793        })?;
1794        signing_key_from_mnemonic(mnemonic, derivation_path)?
1795    };
1796    let derived_address = address_from_signing_key(&signing_key);
1797    if !address_eq(&derived_address, &keystore.address) {
1798        return Err(EvmServiceError::InvalidInput(
1799            "Keystore address does not match decrypted secret".to_string(),
1800        ));
1801    }
1802    Ok(DecryptedEvmKeystore {
1803        signing_key,
1804        keystore,
1805    })
1806}
1807
1808fn derive_key(password: &str, salt: &[u8; KEYSTORE_SALT_BYTES]) -> EvmResult<Zeroizing<[u8; 32]>> {
1809    if password.len() > MAX_KEYSTORE_PASSWORD_BYTES {
1810        return Err(EvmServiceError::InvalidInput(
1811            "EVM keystore password is too long".to_string(),
1812        ));
1813    }
1814    let params = Params::new(
1815        ARGON2_MEMORY_KIB,
1816        ARGON2_ITERATIONS,
1817        ARGON2_PARALLELISM,
1818        Some(32),
1819    )
1820    .map_err(|_| EvmServiceError::InvalidInput("Invalid Argon2id parameters".to_string()))?;
1821    let argon2 = Argon2::new(Algorithm::Argon2id, Argon2Version::V0x13, params);
1822    let mut key = Zeroizing::new([0u8; 32]);
1823    argon2
1824        .hash_password_into(password.as_bytes(), salt, key.as_mut())
1825        .map_err(|_| EvmServiceError::InvalidInput("Argon2id key derivation failed".to_string()))?;
1826    Ok(key)
1827}
1828
1829fn keystore_aad_v1(address: &str) -> Vec<u8> {
1830    let mut aad = Vec::with_capacity(KEYSTORE_AAD_DOMAIN.len() + address.len() + 2);
1831    aad.extend_from_slice(KEYSTORE_AAD_DOMAIN);
1832    aad.push(0);
1833    aad.extend_from_slice(address.as_bytes());
1834    aad
1835}
1836
1837fn keystore_aad_v2(address: &str, secret_type: &str, derivation_path: Option<&str>) -> Vec<u8> {
1838    let derivation_path = derivation_path.unwrap_or_default();
1839    let mut aad = Vec::with_capacity(
1840        KEYSTORE_AAD_DOMAIN.len() + address.len() + secret_type.len() + derivation_path.len() + 8,
1841    );
1842    aad.extend_from_slice(KEYSTORE_AAD_DOMAIN);
1843    aad.push(0);
1844    aad.push(KEYSTORE_VERSION);
1845    aad.push(0);
1846    aad.extend_from_slice(b"evm");
1847    aad.push(0);
1848    aad.extend_from_slice(address.as_bytes());
1849    aad.push(0);
1850    aad.extend_from_slice(secret_type.as_bytes());
1851    aad.push(0);
1852    aad.extend_from_slice(derivation_path.as_bytes());
1853    aad
1854}
1855
1856fn rpc_call_url(
1857    rpc_url: &str,
1858    method: &str,
1859    params: serde_json::Value,
1860) -> EvmResult<serde_json::Value> {
1861    let client = reqwest::blocking::Client::builder()
1862        .timeout(Duration::from_secs(JSON_RPC_TIMEOUT_SECS))
1863        .build()
1864        .map_err(|_| EvmServiceError::RpcUnavailable)?;
1865    let response = client
1866        .post(rpc_url)
1867        .json(&serde_json::json!({
1868            "jsonrpc": "2.0",
1869            "id": 1,
1870            "method": method,
1871            "params": params,
1872        }))
1873        .send()
1874        .map_err(|_| EvmServiceError::RpcUnavailable)?;
1875    let rpc: JsonRpcResponse = response
1876        .json()
1877        .map_err(|_| EvmServiceError::RpcUnavailable)?;
1878    if let Some(error) = rpc.error {
1879        let lower = error.message.to_ascii_lowercase();
1880        if lower.contains("insufficient") || lower.contains("fund") {
1881            return Err(EvmServiceError::InsufficientFunds);
1882        }
1883        if lower.contains("gas") {
1884            return Err(EvmServiceError::GasEstimateFailed);
1885        }
1886        return Err(EvmServiceError::RpcUnavailable);
1887    }
1888    rpc.result.ok_or(EvmServiceError::RpcUnavailable)
1889}
1890
1891fn builtin_rpc_fallbacks(chain_id: u64) -> &'static [&'static str] {
1892    match chain_id {
1893        1 => &["https://eth.drpc.org"],
1894        10 => &["https://mainnet.optimism.io", "https://optimism.drpc.org"],
1895        56 => &["https://bsc-dataseed1.bnbchain.org", "https://bsc.drpc.org"],
1896        97 => &["https://data-seed-prebsc-1-s1.bnbchain.org:8545"],
1897        137 => &["https://polygon.drpc.org"],
1898        250 => &["https://fantom.drpc.org"],
1899        324 => &["https://zksync.drpc.org"],
1900        4_663 => &[
1901            "https://robinhood-rpc.publicnode.com",
1902            "https://rpc.ordofi.network",
1903        ],
1904        5_042 => &[
1905            "https://rpc.drpc.mainnet.arc.io",
1906            "https://rpc.quicknode.mainnet.arc.io",
1907        ],
1908        5_042_002 => &[
1909            "https://rpc.drpc.testnet.arc.io",
1910            "https://rpc.quicknode.testnet.arc.io",
1911        ],
1912        8_453 => &[
1913            "https://base-rpc.publicnode.com",
1914            "https://developer-access-mainnet.base.org",
1915        ],
1916        42_161 => &["https://arbitrum-one-rpc.publicnode.com"],
1917        43_114 => &["https://avalanche-c-chain-rpc.publicnode.com"],
1918        59_144 => &["https://linea-rpc.publicnode.com"],
1919        80_002 => &[
1920            "https://rpc-amoy.polygon.technology",
1921            "https://polygon-amoy.drpc.org",
1922        ],
1923        84_532 => &["https://base-sepolia-rpc.publicnode.com"],
1924        534_352 => &["https://scroll-rpc.publicnode.com"],
1925        11_155_111 => &[
1926            "https://sepolia.gateway.tenderly.co",
1927            "https://rpc.sepolia.ethpandaops.io",
1928            "https://1rpc.io/sepolia",
1929        ],
1930        _ => &[],
1931    }
1932}
1933
1934fn rpc_candidates(chain: &EvmChainConfig) -> Vec<&str> {
1935    let mut candidates = Vec::with_capacity(1 + builtin_rpc_fallbacks(chain.chain_id).len());
1936    candidates.push(chain.rpc_url.as_str());
1937    for fallback in builtin_rpc_fallbacks(chain.chain_id) {
1938        if !candidates.iter().any(|candidate| candidate == fallback) {
1939            candidates.push(fallback);
1940        }
1941    }
1942    candidates
1943}
1944
1945fn rpc_call(
1946    chain: &EvmChainConfig,
1947    method: &str,
1948    params: serde_json::Value,
1949) -> EvmResult<serde_json::Value> {
1950    let candidates = rpc_candidates(chain);
1951    rpc_call_candidates(chain.chain_id, &candidates, method, params)
1952}
1953
1954fn rpc_call_candidates(
1955    chain_id: u64,
1956    candidates: &[&str],
1957    method: &str,
1958    params: serde_json::Value,
1959) -> EvmResult<serde_json::Value> {
1960    let mut last_error = EvmServiceError::RpcUnavailable;
1961    for (index, rpc_url) in candidates.iter().enumerate() {
1962        let chain_id_result =
1963            rpc_call_url(rpc_url, "eth_chainId", serde_json::json!([])).and_then(|reported| {
1964                validate_reported_chain_id(chain_id, &reported)?;
1965                Ok(reported)
1966            });
1967        match chain_id_result {
1968            Ok(reported) if method == "eth_chainId" => return Ok(reported),
1969            Ok(_) => {}
1970            Err(error) => {
1971                last_error = error;
1972                if index + 1 < candidates.len() {
1973                    std::thread::sleep(Duration::from_millis(
1974                        JSON_RPC_FAILOVER_DELAY_MS.saturating_mul(1_u64 << index.min(3)),
1975                    ));
1976                }
1977                continue;
1978            }
1979        }
1980
1981        match rpc_call_url(rpc_url, method, params.clone()) {
1982            Ok(value) => return Ok(value),
1983            Err(error @ EvmServiceError::InsufficientFunds)
1984            | Err(error @ EvmServiceError::GasEstimateFailed) => return Err(error),
1985            Err(error) => last_error = error,
1986        }
1987        if index + 1 < candidates.len() {
1988            std::thread::sleep(Duration::from_millis(
1989                JSON_RPC_FAILOVER_DELAY_MS.saturating_mul(1_u64 << index.min(3)),
1990            ));
1991        }
1992    }
1993    Err(last_error)
1994}
1995
1996pub fn validate_rpc_chain_id(chain: &EvmChainConfig) -> EvmResult<()> {
1997    validate_chain(chain)?;
1998    let reported = rpc_call(chain, "eth_chainId", serde_json::json!([]))?;
1999    validate_reported_chain_id(chain.chain_id, &reported)
2000}
2001
2002fn validate_reported_chain_id(expected: u64, reported: &serde_json::Value) -> EvmResult<()> {
2003    let reported = reported
2004        .as_str()
2005        .ok_or(EvmServiceError::InvalidChainId)
2006        .and_then(hex_quantity_to_u64)?;
2007    if reported != expected {
2008        return Err(EvmServiceError::InvalidChainId);
2009    }
2010    Ok(())
2011}
2012
2013fn load_recent_transactions(
2014    chain: &EvmChainConfig,
2015    wallet_address: &str,
2016) -> (Vec<EvmTransactionHistoryEntry>, String, Option<String>) {
2017    if chain.explorer_url.is_none() {
2018        return (
2019            Vec::new(),
2020            "unsupported".to_string(),
2021            Some("No EVM explorer API is configured for this chain".to_string()),
2022        );
2023    }
2024
2025    match load_etherscan_compatible_history(chain, wallet_address) {
2026        Ok(entries) => (entries, "ok".to_string(), None),
2027        Err(EvmServiceError::HistoryUnavailable) => (
2028            Vec::new(),
2029            "unsupported".to_string(),
2030            Some("The configured explorer does not expose account history".to_string()),
2031        ),
2032        Err(_) => (
2033            Vec::new(),
2034            "unavailable".to_string(),
2035            Some("EVM transaction history is temporarily unavailable".to_string()),
2036        ),
2037    }
2038}
2039
2040fn load_etherscan_compatible_history(
2041    chain: &EvmChainConfig,
2042    wallet_address: &str,
2043) -> EvmResult<Vec<EvmTransactionHistoryEntry>> {
2044    let api_key = etherscan_api_key().ok_or(EvmServiceError::HistoryUnavailable)?;
2045    let api_url = etherscan_compatible_api_url(chain, wallet_address, &api_key)?;
2046    let client = reqwest::blocking::Client::builder()
2047        .timeout(Duration::from_secs(JSON_RPC_TIMEOUT_SECS))
2048        .build()
2049        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2050    let response = client
2051        .get(api_url)
2052        .send()
2053        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2054    if !response.status().is_success() {
2055        return Err(EvmServiceError::RpcUnavailable);
2056    }
2057    let body = read_etherscan_response(response)?;
2058    parse_etherscan_history_response(&body)
2059}
2060
2061fn read_etherscan_response(reader: impl Read) -> EvmResult<String> {
2062    let mut body = Vec::new();
2063    reader
2064        .take((MAX_ETHERSCAN_RESPONSE_BYTES + 1) as u64)
2065        .read_to_end(&mut body)
2066        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2067    if body.len() > MAX_ETHERSCAN_RESPONSE_BYTES {
2068        return Err(EvmServiceError::RpcUnavailable);
2069    }
2070    String::from_utf8(body).map_err(|_| EvmServiceError::RpcUnavailable)
2071}
2072
2073fn etherscan_compatible_api_url(
2074    chain: &EvmChainConfig,
2075    wallet_address: &str,
2076    api_key: &str,
2077) -> EvmResult<String> {
2078    let wallet_address = normalize_address(wallet_address, "wallet address")?;
2079    let explorer_url = chain
2080        .explorer_url
2081        .as_deref()
2082        .ok_or(EvmServiceError::HistoryUnavailable)?;
2083    if etherscan_chain_id(explorer_url) != Some(chain.chain_id) || !valid_etherscan_api_key(api_key)
2084    {
2085        return Err(EvmServiceError::HistoryUnavailable);
2086    }
2087    let mut url = reqwest::Url::parse("https://api.etherscan.io/v2/api")
2088        .map_err(|_| EvmServiceError::HistoryUnavailable)?;
2089    url.query_pairs_mut()
2090        .append_pair("chainid", &chain.chain_id.to_string())
2091        .append_pair("module", "account")
2092        .append_pair("action", "txlist")
2093        .append_pair("address", &wallet_address)
2094        .append_pair("page", "1")
2095        .append_pair("offset", "10")
2096        .append_pair("sort", "desc")
2097        .append_pair("apikey", api_key);
2098    Ok(url.into())
2099}
2100
2101fn etherscan_chain_id(explorer_url: &str) -> Option<u64> {
2102    validate_explorer_origin(explorer_url).ok()?;
2103    let url = reqwest::Url::parse(explorer_url.trim()).ok()?;
2104    match url.host_str()? {
2105        "etherscan.io" => Some(1),
2106        "sepolia.etherscan.io" => Some(11_155_111),
2107        "optimistic.etherscan.io" => Some(10),
2108        "bscscan.com" => Some(56),
2109        "testnet.bscscan.com" => Some(97),
2110        "polygonscan.com" => Some(137),
2111        "amoy.polygonscan.com" => Some(80_002),
2112        "arbiscan.io" => Some(42_161),
2113        "basescan.org" => Some(8_453),
2114        "sepolia.basescan.org" => Some(84_532),
2115        "snowtrace.io" => Some(43_114),
2116        "ftmscan.com" => Some(250),
2117        "lineascan.build" => Some(59_144),
2118        "scrollscan.com" => Some(534_352),
2119        _ => None,
2120    }
2121}
2122
2123fn etherscan_api_key() -> Option<Zeroizing<String>> {
2124    std::env::var(ETHERSCAN_API_KEY_ENV)
2125        .ok()
2126        .filter(|value| valid_etherscan_api_key(value))
2127        .map(Zeroizing::new)
2128}
2129
2130fn valid_etherscan_api_key(value: &str) -> bool {
2131    !value.is_empty()
2132        && value.len() <= 256
2133        && value
2134            .bytes()
2135            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
2136}
2137
2138fn etherscan_history_available(chain: &EvmChainConfig, api_key: Option<&str>) -> bool {
2139    chain
2140        .explorer_url
2141        .as_deref()
2142        .is_some_and(|explorer| etherscan_chain_id(explorer) == Some(chain.chain_id))
2143        && api_key.is_some_and(valid_etherscan_api_key)
2144}
2145
2146fn parse_etherscan_history_response(body: &str) -> EvmResult<Vec<EvmTransactionHistoryEntry>> {
2147    let response: EtherscanHistoryResponse =
2148        serde_json::from_str(body).map_err(|_| EvmServiceError::RpcUnavailable)?;
2149    if matches!(response.result, serde_json::Value::String(_)) {
2150        let message = response
2151            .message
2152            .as_deref()
2153            .unwrap_or_default()
2154            .to_ascii_lowercase();
2155        if response.status.as_deref() == Some("0")
2156            && (message.contains("no transactions") || message.contains("ok"))
2157        {
2158            return Ok(Vec::new());
2159        }
2160        return Err(EvmServiceError::HistoryUnavailable);
2161    }
2162    if response.status.as_deref() != Some("1") {
2163        return Err(EvmServiceError::HistoryUnavailable);
2164    }
2165    let items = response
2166        .result
2167        .as_array()
2168        .ok_or(EvmServiceError::HistoryUnavailable)?;
2169    items.iter().map(etherscan_history_entry).take(10).collect()
2170}
2171
2172fn etherscan_history_entry(value: &serde_json::Value) -> EvmResult<EvmTransactionHistoryEntry> {
2173    let hash = value
2174        .get("hash")
2175        .and_then(serde_json::Value::as_str)
2176        .ok_or(EvmServiceError::HistoryUnavailable)
2177        .and_then(normalize_tx_hash)
2178        .map_err(|_| EvmServiceError::HistoryUnavailable)?;
2179    let block_number = value
2180        .get("blockNumber")
2181        .and_then(serde_json::Value::as_str)
2182        .and_then(|value| value.parse::<u64>().ok());
2183    let status = value
2184        .get("txreceipt_status")
2185        .or_else(|| value.get("status"))
2186        .and_then(serde_json::Value::as_str)
2187        .map(|value| match value {
2188            "1" => "confirmed",
2189            "0" => "failed",
2190            other => other,
2191        })
2192        .unwrap_or("unknown")
2193        .to_string();
2194
2195    Ok(EvmTransactionHistoryEntry {
2196        hash,
2197        block_number,
2198        status,
2199    })
2200}
2201
2202fn estimate_gas(
2203    chain: &EvmChainConfig,
2204    from: &str,
2205    to: &str,
2206    value_decimal: &str,
2207    data: &str,
2208) -> EvmResult<String> {
2209    let value = decimal_to_hex_quantity(value_decimal)?;
2210    let data = if data.is_empty() { "0x" } else { data };
2211    let params = serde_json::json!([{
2212        "from": from,
2213        "to": to,
2214        "value": &value,
2215        "data": data,
2216    }]);
2217
2218    for attempt in 0..3 {
2219        match rpc_call(chain, "eth_estimateGas", params.clone())
2220            .and_then(rpc_hex_quantity_to_decimal)
2221        {
2222            Ok(gas_limit) => return Ok(gas_limit),
2223            Err(EvmServiceError::InsufficientFunds) => {
2224                return Err(EvmServiceError::InsufficientFunds);
2225            }
2226            Err(_) if attempt < 2 => {
2227                std::thread::sleep(Duration::from_millis(120 * (attempt + 1) as u64));
2228            }
2229            Err(_) => break,
2230        }
2231    }
2232
2233    // Arc can reject EOA transfers through runtime USDC restrictions.
2234    if is_arc(chain.chain_id) {
2235        return Err(EvmServiceError::GasEstimateFailed);
2236    }
2237
2238    // A plain transfer to an account with no bytecode always consumes the
2239    // protocol intrinsic gas. Never apply this fallback to contracts or tokens.
2240    let recipient_code = rpc_call(chain, "eth_getCode", serde_json::json!([to, "latest"]))
2241        .ok()
2242        .and_then(|value| value.as_str().map(str::to_owned));
2243    if recipient_code
2244        .as_deref()
2245        .is_some_and(|code| can_use_intrinsic_gas_fallback(to, data, code))
2246    {
2247        return Ok("21000".to_string());
2248    }
2249
2250    Err(EvmServiceError::GasEstimateFailed)
2251}
2252
2253fn can_use_intrinsic_gas_fallback(to: &str, data: &str, recipient_code: &str) -> bool {
2254    let Some(address) = to.strip_prefix("0x") else {
2255        return false;
2256    };
2257    let is_low_system_address =
2258        address.len() == 40 && address.as_bytes()[..38].iter().all(|byte| *byte == b'0');
2259    data == "0x"
2260        && recipient_code.eq_ignore_ascii_case("0x")
2261        && address.len() == 40
2262        && !is_low_system_address
2263}
2264
2265fn load_token_asset(
2266    chain: &EvmChainConfig,
2267    wallet_address: &str,
2268    token_contract: &str,
2269) -> EvmResult<EvmTokenAsset> {
2270    let contract_address = normalize_address(token_contract, "token contract")?;
2271    let balance_data = erc20_balance_of_calldata(wallet_address)?;
2272    let balance = eth_call(chain, &contract_address, &balance_data)
2273        .and_then(|value| hex_word_to_decimal(&value))
2274        .unwrap_or_else(|_| "0".to_string());
2275    let decimals = eth_call(
2276        chain,
2277        &contract_address,
2278        &selector_data(ERC20_DECIMALS_SELECTOR),
2279    )
2280    .and_then(|value| hex_word_to_u8(&value))
2281    .unwrap_or(18);
2282    let symbol = eth_call(
2283        chain,
2284        &contract_address,
2285        &selector_data(ERC20_SYMBOL_SELECTOR),
2286    )
2287    .and_then(|value| decode_erc20_string(&value))
2288    .unwrap_or_else(|_| "ERC20".to_string());
2289    let name = eth_call(
2290        chain,
2291        &contract_address,
2292        &selector_data(ERC20_NAME_SELECTOR),
2293    )
2294    .and_then(|value| decode_erc20_string(&value))
2295    .unwrap_or_else(|_| format!("Token {}", short_address(&contract_address)));
2296
2297    Ok(EvmTokenAsset {
2298        contract_address,
2299        symbol,
2300        name,
2301        balance,
2302        decimals,
2303        logo_uri: None,
2304    })
2305}
2306
2307#[derive(Debug, Default)]
2308struct ExternalTokenMetadata {
2309    name: Option<String>,
2310    symbol: Option<String>,
2311    logo_uri: Option<String>,
2312}
2313
2314fn enrich_token_metadata(chain: &EvmChainConfig, tokens: &mut [EvmTokenAsset]) {
2315    if let Some(chain_slug) = coingecko_chain_slug(chain.chain_id) {
2316        if let Ok(metadata) = load_coingecko_token_metadata(chain_slug) {
2317            apply_external_token_metadata(tokens, &metadata);
2318        }
2319    }
2320    if !tokens.iter().any(token_needs_external_metadata) {
2321        return;
2322    }
2323    let Some(chain_slug) = dexscreener_chain_slug(chain.chain_id) else {
2324        return;
2325    };
2326    for chunk in tokens.chunks_mut(MAX_TOKEN_METADATA_BATCH_SIZE) {
2327        let addresses = chunk
2328            .iter()
2329            .map(|token| token.contract_address.as_str())
2330            .collect::<Vec<_>>()
2331            .join(",");
2332        let Ok(metadata) = load_dexscreener_token_metadata(chain_slug, &addresses) else {
2333            continue;
2334        };
2335        apply_external_token_metadata(chunk, &metadata);
2336    }
2337}
2338
2339fn token_needs_external_metadata(token: &EvmTokenAsset) -> bool {
2340    token.logo_uri.is_none() || token.symbol == "ERC20" || token.name.starts_with("Token 0x")
2341}
2342
2343fn apply_external_token_metadata(
2344    tokens: &mut [EvmTokenAsset],
2345    metadata: &std::collections::HashMap<String, ExternalTokenMetadata>,
2346) {
2347    for token in tokens {
2348        let Some(external) = metadata.get(&token.contract_address) else {
2349            continue;
2350        };
2351        if token.symbol == "ERC20" {
2352            if let Some(symbol) = external.symbol.as_ref() {
2353                token.symbol = symbol.clone();
2354            }
2355        }
2356        if token.name.starts_with("Token 0x") {
2357            if let Some(name) = external.name.as_ref() {
2358                token.name = name.clone();
2359            }
2360        }
2361        if token.logo_uri.is_none() {
2362            token.logo_uri = external.logo_uri.clone();
2363        }
2364    }
2365}
2366
2367fn coingecko_chain_slug(chain_id: u64) -> Option<&'static str> {
2368    match chain_id {
2369        1 => Some("ethereum"),
2370        10 => Some("optimism"),
2371        56 => Some("binance-smart-chain"),
2372        137 => Some("polygon-pos"),
2373        250 => Some("fantom"),
2374        324 => Some("zksync"),
2375        4_663 => Some("robinhood"),
2376        8_453 => Some("base"),
2377        42_161 => Some("arbitrum-one"),
2378        43_114 => Some("avalanche"),
2379        59_144 => Some("linea"),
2380        534_352 => Some("scroll"),
2381        _ => None,
2382    }
2383}
2384
2385fn load_coingecko_token_metadata(
2386    chain_slug: &str,
2387) -> EvmResult<std::collections::HashMap<String, ExternalTokenMetadata>> {
2388    let mut url = reqwest::Url::parse("https://tokens.coingecko.com/")
2389        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2390    url.path_segments_mut()
2391        .map_err(|_| EvmServiceError::RpcUnavailable)?
2392        .push(chain_slug)
2393        .push("all.json");
2394    let client = reqwest::blocking::Client::builder()
2395        .timeout(Duration::from_secs(TOKEN_METADATA_TIMEOUT_SECS))
2396        .build()
2397        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2398    let response = client
2399        .get(url)
2400        .send()
2401        .and_then(reqwest::blocking::Response::error_for_status)
2402        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2403    let mut body = Vec::new();
2404    response
2405        .take((MAX_TOKEN_LIST_RESPONSE_BYTES + 1) as u64)
2406        .read_to_end(&mut body)
2407        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2408    if body.len() > MAX_TOKEN_LIST_RESPONSE_BYTES {
2409        return Err(EvmServiceError::RpcUnavailable);
2410    }
2411    parse_coingecko_token_metadata(&body)
2412}
2413
2414fn parse_coingecko_token_metadata(
2415    body: &[u8],
2416) -> EvmResult<std::collections::HashMap<String, ExternalTokenMetadata>> {
2417    let response: serde_json::Value =
2418        serde_json::from_slice(body).map_err(|_| EvmServiceError::RpcUnavailable)?;
2419    let tokens = response
2420        .get("tokens")
2421        .and_then(serde_json::Value::as_array)
2422        .ok_or(EvmServiceError::RpcUnavailable)?;
2423    let mut metadata = std::collections::HashMap::new();
2424    for token in tokens {
2425        let Some(address) = token
2426            .get("address")
2427            .and_then(serde_json::Value::as_str)
2428            .and_then(|value| normalize_address(value, "token address").ok())
2429        else {
2430            continue;
2431        };
2432        metadata.insert(
2433            address,
2434            ExternalTokenMetadata {
2435                name: token
2436                    .get("name")
2437                    .and_then(serde_json::Value::as_str)
2438                    .and_then(|value| clean_token_metadata_text(value, 128)),
2439                symbol: token
2440                    .get("symbol")
2441                    .and_then(serde_json::Value::as_str)
2442                    .and_then(|value| clean_token_metadata_text(value, 32)),
2443                logo_uri: token
2444                    .get("logoURI")
2445                    .and_then(serde_json::Value::as_str)
2446                    .and_then(validate_token_logo_uri),
2447            },
2448        );
2449    }
2450    Ok(metadata)
2451}
2452
2453fn dexscreener_chain_slug(chain_id: u64) -> Option<&'static str> {
2454    match chain_id {
2455        1 | 11_155_111 => Some("ethereum"),
2456        10 => Some("optimism"),
2457        56 | 97 => Some("bsc"),
2458        137 | 80_002 => Some("polygon"),
2459        250 => Some("fantom"),
2460        324 => Some("zksync"),
2461        4_663 | 46_630 => Some("robinhood"),
2462        8_453 | 84_532 => Some("base"),
2463        42_161 | 421_614 => Some("arbitrum"),
2464        43_114 | 43_113 => Some("avalanche"),
2465        59_144 => Some("linea"),
2466        534_352 => Some("scroll"),
2467        _ => None,
2468    }
2469}
2470
2471fn load_dexscreener_token_metadata(
2472    chain_slug: &str,
2473    addresses: &str,
2474) -> EvmResult<std::collections::HashMap<String, ExternalTokenMetadata>> {
2475    let mut url = reqwest::Url::parse("https://api.dexscreener.com/latest/dex/tokens/")
2476        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2477    url.path_segments_mut()
2478        .map_err(|_| EvmServiceError::RpcUnavailable)?
2479        .push(addresses);
2480    let client = reqwest::blocking::Client::builder()
2481        .timeout(Duration::from_secs(TOKEN_METADATA_TIMEOUT_SECS))
2482        .build()
2483        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2484    let response = client
2485        .get(url)
2486        .send()
2487        .and_then(reqwest::blocking::Response::error_for_status)
2488        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2489    let mut body = Vec::new();
2490    response
2491        .take((MAX_TOKEN_METADATA_RESPONSE_BYTES + 1) as u64)
2492        .read_to_end(&mut body)
2493        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2494    if body.len() > MAX_TOKEN_METADATA_RESPONSE_BYTES {
2495        return Err(EvmServiceError::RpcUnavailable);
2496    }
2497    parse_dexscreener_token_metadata(chain_slug, &body)
2498}
2499
2500fn parse_dexscreener_token_metadata(
2501    chain_slug: &str,
2502    body: &[u8],
2503) -> EvmResult<std::collections::HashMap<String, ExternalTokenMetadata>> {
2504    let response: serde_json::Value =
2505        serde_json::from_slice(body).map_err(|_| EvmServiceError::RpcUnavailable)?;
2506    let pairs = response
2507        .get("pairs")
2508        .and_then(serde_json::Value::as_array)
2509        .ok_or(EvmServiceError::RpcUnavailable)?;
2510    let mut metadata = std::collections::HashMap::new();
2511    for pair in pairs {
2512        if pair.get("chainId").and_then(serde_json::Value::as_str) != Some(chain_slug) {
2513            continue;
2514        }
2515        let base = pair.get("baseToken");
2516        let quote = pair.get("quoteToken");
2517        for (token, may_use_pair_logo) in [(base, true), (quote, false)] {
2518            let Some(token) = token else { continue };
2519            let Some(address) = token
2520                .get("address")
2521                .and_then(serde_json::Value::as_str)
2522                .and_then(|value| normalize_address(value, "token address").ok())
2523            else {
2524                continue;
2525            };
2526            let entry = metadata
2527                .entry(address)
2528                .or_insert_with(ExternalTokenMetadata::default);
2529            if entry.name.is_none() {
2530                entry.name = token
2531                    .get("name")
2532                    .and_then(serde_json::Value::as_str)
2533                    .and_then(|value| clean_token_metadata_text(value, 128));
2534            }
2535            if entry.symbol.is_none() {
2536                entry.symbol = token
2537                    .get("symbol")
2538                    .and_then(serde_json::Value::as_str)
2539                    .and_then(|value| clean_token_metadata_text(value, 32));
2540            }
2541            if may_use_pair_logo && entry.logo_uri.is_none() {
2542                entry.logo_uri = pair
2543                    .get("info")
2544                    .and_then(|info| info.get("imageUrl"))
2545                    .and_then(serde_json::Value::as_str)
2546                    .and_then(validate_token_logo_uri);
2547            }
2548        }
2549    }
2550    Ok(metadata)
2551}
2552
2553fn clean_token_metadata_text(value: &str, max_bytes: usize) -> Option<String> {
2554    let value = value.trim();
2555    if value.is_empty() || value.len() > max_bytes || value.chars().any(char::is_control) {
2556        return None;
2557    }
2558    Some(value.to_string())
2559}
2560
2561fn validate_token_logo_uri(value: &str) -> Option<String> {
2562    if value.len() > 2_048 || value.trim() != value {
2563        return None;
2564    }
2565    let url = reqwest::Url::parse(value).ok()?;
2566    let trusted_host = matches!(
2567        url.host_str(),
2568        Some("assets.coingecko.com" | "cdn.dexscreener.com" | "dd.dexscreener.com")
2569    );
2570    if url.scheme() != "https"
2571        || !trusted_host
2572        || !url.username().is_empty()
2573        || url.password().is_some()
2574        || url.fragment().is_some()
2575    {
2576        return None;
2577    }
2578    Some(url.to_string())
2579}
2580
2581fn eth_call(chain: &EvmChainConfig, to: &str, data: &str) -> EvmResult<String> {
2582    rpc_call(
2583        chain,
2584        "eth_call",
2585        serde_json::json!([{"to": to, "data": data}, "latest"]),
2586    )
2587    .and_then(|value| {
2588        value
2589            .as_str()
2590            .map(str::to_string)
2591            .ok_or(EvmServiceError::RpcUnavailable)
2592    })
2593}
2594
2595fn rpc_hex_quantity_to_decimal(value: serde_json::Value) -> EvmResult<String> {
2596    let quantity = value.as_str().ok_or(EvmServiceError::RpcUnavailable)?;
2597    hex_quantity_to_decimal(quantity)
2598}
2599
2600fn selector_data(selector: [u8; 4]) -> String {
2601    format!("0x{}", hex::encode(selector))
2602}
2603
2604fn erc20_balance_of_calldata(wallet_address: &str) -> EvmResult<String> {
2605    let mut bytes = Vec::with_capacity(36);
2606    bytes.extend_from_slice(&ERC20_BALANCE_OF_SELECTOR);
2607    bytes.extend_from_slice(&[0u8; 12]);
2608    bytes.extend_from_slice(&address_bytes(wallet_address)?);
2609    Ok(format!("0x{}", hex::encode(bytes)))
2610}
2611
2612#[derive(Debug, Clone)]
2613struct EvmFeeQuote {
2614    fee_model: String,
2615    gas_price_wei: String,
2616    max_fee_per_gas_wei: Option<String>,
2617    max_priority_fee_per_gas_wei: Option<String>,
2618}
2619
2620impl EvmFeeQuote {
2621    fn max_fee_per_gas_wei(&self) -> String {
2622        self.max_fee_per_gas_wei
2623            .clone()
2624            .unwrap_or_else(|| self.gas_price_wei.clone())
2625    }
2626}
2627
2628#[derive(Debug, Clone)]
2629struct DappTransactionRequest {
2630    to: String,
2631    value: String,
2632    data: String,
2633    gas_limit: String,
2634    gas_price_wei: String,
2635    max_fee_per_gas_wei: Option<String>,
2636    max_priority_fee_per_gas_wei: Option<String>,
2637    nonce: String,
2638}
2639
2640struct EvmTxSigningInput<'a> {
2641    signing_key: &'a SigningKey,
2642    chain_id: u64,
2643    nonce: &'a str,
2644    gas_limit: &'a str,
2645    to: &'a str,
2646    value: &'a str,
2647    data: &'a str,
2648    gas_price_wei: &'a str,
2649    max_fee_per_gas_wei: Option<&'a str>,
2650    max_priority_fee_per_gas_wei: Option<&'a str>,
2651}
2652
2653struct PaymentPreviewIdInput<'a> {
2654    chain: &'a EvmChainConfig,
2655    wallet_address: &'a str,
2656    recipient: &'a str,
2657    token_contract: Option<&'a str>,
2658    amount_wei_or_units: &'a str,
2659    gas_limit: &'a str,
2660    gas_price_wei: &'a str,
2661    max_fee_per_gas_wei: Option<&'a str>,
2662    max_priority_fee_per_gas_wei: Option<&'a str>,
2663    nonce: &'a str,
2664}
2665
2666struct DappSignPreviewIdInput<'a> {
2667    chain: &'a EvmChainConfig,
2668    wallet_address: &'a str,
2669    app_name: &'a str,
2670    app_url: &'a str,
2671    method: &'a str,
2672    payload_json: &'a str,
2673}
2674
2675struct LegacyTxSigningInput<'a> {
2676    signing_key: &'a SigningKey,
2677    chain_id: u64,
2678    nonce: &'a str,
2679    gas_price_wei: &'a str,
2680    gas_limit: &'a str,
2681    to: &'a str,
2682    value: &'a str,
2683    data: &'a str,
2684}
2685
2686fn payment_preview_id(input: &PaymentPreviewIdInput<'_>) -> String {
2687    let material = serde_json::json!({
2688        "scope": "fnzero-safe-evm-payment-preview-v1",
2689        "chain_id": input.chain.chain_id,
2690        "rpc_url": input.chain.rpc_url,
2691        "wallet_address": input.wallet_address,
2692        "recipient": input.recipient,
2693        "token_contract": input.token_contract,
2694        "amount_wei_or_units": input.amount_wei_or_units,
2695        "gas_limit": input.gas_limit,
2696        "gas_price_wei": input.gas_price_wei,
2697        "max_fee_per_gas_wei": input.max_fee_per_gas_wei,
2698        "max_priority_fee_per_gas_wei": input.max_priority_fee_per_gas_wei,
2699        "nonce": input.nonce,
2700    });
2701    format!(
2702        "evm-payment:{}",
2703        hex::encode(keccak256(material.to_string().as_bytes()))
2704    )
2705}
2706
2707fn dapp_sign_preview_id(input: &DappSignPreviewIdInput<'_>) -> String {
2708    let material = serde_json::json!({
2709        "scope": "fnzero-safe-evm-dapp-preview-v1",
2710        "chain_id": input.chain.chain_id,
2711        "rpc_url": input.chain.rpc_url,
2712        "wallet_address": input.wallet_address,
2713        "app_name": input.app_name,
2714        "app_url": input.app_url,
2715        "method": input.method,
2716        "payload_json": input.payload_json,
2717    });
2718    format!(
2719        "evm-dapp:{}",
2720        hex::encode(keccak256(material.to_string().as_bytes()))
2721    )
2722}
2723
2724fn load_nonce(chain: &EvmChainConfig, wallet_address: &str) -> EvmResult<String> {
2725    rpc_call(
2726        chain,
2727        "eth_getTransactionCount",
2728        serde_json::json!([wallet_address, "pending"]),
2729    )
2730    .and_then(rpc_hex_quantity_to_decimal)
2731    .map_err(|_| EvmServiceError::RpcUnavailable)
2732}
2733
2734fn ensure_preview_nonce_is_current(preview_nonce: &str, current_nonce: &str) -> EvmResult<()> {
2735    if normalize_decimal(preview_nonce, "preview nonce")?
2736        != normalize_decimal(current_nonce, "current nonce")?
2737    {
2738        return Err(EvmServiceError::InvalidInput(
2739            "EVM account nonce changed after preview; review the transaction again".to_string(),
2740        ));
2741    }
2742    Ok(())
2743}
2744
2745fn load_fee_quote(chain: &EvmChainConfig) -> EvmResult<EvmFeeQuote> {
2746    let gas_price_wei = rpc_call(chain, "eth_gasPrice", serde_json::json!([]))
2747        .and_then(rpc_hex_quantity_to_decimal)
2748        .map_err(|_| EvmServiceError::RpcUnavailable)?;
2749    let gas_price_wei = arc_fee_floor(chain.chain_id, gas_price_wei)?;
2750    let latest_block = rpc_call(
2751        chain,
2752        "eth_getBlockByNumber",
2753        serde_json::json!(["latest", false]),
2754    )
2755    .ok();
2756    let base_fee_wei = latest_block
2757        .as_ref()
2758        .and_then(|value| value.get("baseFeePerGas"))
2759        .and_then(serde_json::Value::as_str)
2760        .and_then(|value| hex_quantity_to_decimal(value).ok());
2761    let Some(base_fee_wei) = base_fee_wei else {
2762        return Ok(EvmFeeQuote {
2763            fee_model: "legacy".to_string(),
2764            gas_price_wei,
2765            max_fee_per_gas_wei: None,
2766            max_priority_fee_per_gas_wei: None,
2767        });
2768    };
2769
2770    let priority_fee_wei = rpc_call(chain, "eth_maxPriorityFeePerGas", serde_json::json!([]))
2771        .and_then(rpc_hex_quantity_to_decimal)
2772        .unwrap_or_else(|_| DEFAULT_PRIORITY_FEE_WEI.to_string());
2773    let doubled_base_fee = decimal_mul_u64(&base_fee_wei, 2)?;
2774    let mut max_fee_per_gas_wei = decimal_add(&doubled_base_fee, &priority_fee_wei)?;
2775    if decimal_cmp(&max_fee_per_gas_wei, &gas_price_wei)? == std::cmp::Ordering::Less {
2776        max_fee_per_gas_wei = gas_price_wei.clone();
2777    }
2778    let max_fee_per_gas_wei = arc_fee_floor(chain.chain_id, max_fee_per_gas_wei)?;
2779
2780    Ok(EvmFeeQuote {
2781        fee_model: "eip1559".to_string(),
2782        gas_price_wei,
2783        max_fee_per_gas_wei: Some(max_fee_per_gas_wei),
2784        max_priority_fee_per_gas_wei: Some(priority_fee_wei),
2785    })
2786}
2787
2788fn send_raw_transaction(chain: &EvmChainConfig, raw_tx: &str) -> EvmResult<String> {
2789    validate_rpc_chain_id(chain)?;
2790    let expected_hash = raw_transaction_hash(raw_tx)?;
2791    let returned_hash = rpc_call(chain, "eth_sendRawTransaction", serde_json::json!([raw_tx]))
2792        .and_then(|value| {
2793            value
2794                .as_str()
2795                .map(normalize_tx_hash)
2796                .ok_or(EvmServiceError::RpcUnavailable)
2797        });
2798    let returned_hash = match returned_hash {
2799        Ok(Ok(hash)) => hash,
2800        Ok(Err(error)) => return Err(error),
2801        Err(submit_error) => {
2802            // A node can accept the raw transaction and then time out before
2803            // returning its hash. Finding the locally-derived hash proves broadcast.
2804            for attempt in 0..2 {
2805                if attempt > 0 {
2806                    std::thread::sleep(Duration::from_millis(JSON_RPC_FAILOVER_DELAY_MS * 2));
2807                }
2808                if rpc_call(
2809                    chain,
2810                    "eth_getTransactionByHash",
2811                    serde_json::json!([&expected_hash]),
2812                )
2813                .is_ok_and(|transaction| !transaction.is_null())
2814                {
2815                    return Ok(expected_hash);
2816                }
2817            }
2818            return Err(submit_error);
2819        }
2820    };
2821    if returned_hash != expected_hash {
2822        return Err(EvmServiceError::RpcUnavailable);
2823    }
2824    Ok(returned_hash)
2825}
2826
2827fn raw_transaction_hash(raw_tx: &str) -> EvmResult<String> {
2828    let encoded = raw_tx.strip_prefix("0x").ok_or_else(|| {
2829        EvmServiceError::InvalidInput("Raw EVM transaction must start with 0x".to_string())
2830    })?;
2831    if encoded.is_empty() || encoded.len() % 2 != 0 {
2832        return Err(EvmServiceError::InvalidInput(
2833            "Raw EVM transaction is invalid".to_string(),
2834        ));
2835    }
2836    let bytes = hex::decode(encoded)
2837        .map_err(|_| EvmServiceError::InvalidInput("Raw EVM transaction is invalid".to_string()))?;
2838    Ok(format!("0x{}", hex::encode(keccak256(&bytes))))
2839}
2840
2841fn sign_evm_transaction(input: &EvmTxSigningInput<'_>) -> EvmResult<String> {
2842    validate_arc_recipient(input.chain_id, input.to, input.value)?;
2843    if is_arc(input.chain_id)
2844        && input.max_fee_per_gas_wei.is_some() != input.max_priority_fee_per_gas_wei.is_some()
2845    {
2846        return Err(EvmServiceError::InvalidInput(
2847            "Arc EIP-1559 fee fields must be supplied together".to_string(),
2848        ));
2849    }
2850    let fee = input.max_fee_per_gas_wei.unwrap_or(input.gas_price_wei);
2851    if is_arc(input.chain_id) && decimal_cmp(fee, ARC_MIN_FEE_WEI)? == std::cmp::Ordering::Less {
2852        return Err(EvmServiceError::InvalidInput(
2853            "Arc requires a fee cap of at least 20 Gwei (in native USDC units)".to_string(),
2854        ));
2855    }
2856    match (
2857        input.max_fee_per_gas_wei,
2858        input.max_priority_fee_per_gas_wei,
2859    ) {
2860        (Some(max_fee_per_gas_wei), Some(max_priority_fee_per_gas_wei)) => {
2861            sign_type2_transaction(&Type2TxSigningInput {
2862                signing_key: input.signing_key,
2863                chain_id: input.chain_id,
2864                nonce: input.nonce,
2865                max_priority_fee_per_gas_wei,
2866                max_fee_per_gas_wei,
2867                gas_limit: input.gas_limit,
2868                to: input.to,
2869                value: input.value,
2870                data: input.data,
2871            })
2872        }
2873        _ => sign_legacy_transaction(&LegacyTxSigningInput {
2874            signing_key: input.signing_key,
2875            chain_id: input.chain_id,
2876            nonce: input.nonce,
2877            gas_price_wei: input.gas_price_wei,
2878            gas_limit: input.gas_limit,
2879            to: input.to,
2880            value: input.value,
2881            data: input.data,
2882        }),
2883    }
2884}
2885
2886fn sign_legacy_transaction(input: &LegacyTxSigningInput<'_>) -> EvmResult<String> {
2887    let signing_key = input.signing_key;
2888    let chain_id = input.chain_id;
2889    let nonce = input.nonce;
2890    let gas_price_wei = input.gas_price_wei;
2891    let gas_limit = input.gas_limit;
2892    let to = input.to;
2893    let value = input.value;
2894    let data = input.data;
2895    if chain_id == 0 {
2896        return Err(EvmServiceError::InvalidChainId);
2897    }
2898    let to = address_bytes(to)?;
2899    let data = hex_data_to_bytes(data)?;
2900    let unsigned_items = vec![
2901        rlp_bytes(&decimal_to_be_bytes(nonce)?),
2902        rlp_bytes(&decimal_to_be_bytes(gas_price_wei)?),
2903        rlp_bytes(&decimal_to_be_bytes(gas_limit)?),
2904        rlp_bytes(&to),
2905        rlp_bytes(&decimal_to_be_bytes(value)?),
2906        rlp_bytes(&data),
2907        rlp_bytes(&u64_to_be_bytes(chain_id)),
2908        rlp_bytes(&[]),
2909        rlp_bytes(&[]),
2910    ];
2911    let signing_payload = rlp_list(&unsigned_items);
2912    let digest = keccak256(&signing_payload);
2913    let (signature, recovery_id) = sign_digest(signing_key, &digest)?;
2914    let v = u128::from(chain_id)
2915        .checked_mul(2)
2916        .and_then(|value| value.checked_add(35 + u128::from(recovery_id.to_byte())))
2917        .ok_or(EvmServiceError::InvalidChainId)?;
2918    let sig_bytes = signature.to_bytes();
2919    let r = trim_leading_zeroes(&sig_bytes[..32]);
2920    let s = trim_leading_zeroes(&sig_bytes[32..]);
2921    let signed_items = vec![
2922        rlp_bytes(&decimal_to_be_bytes(nonce)?),
2923        rlp_bytes(&decimal_to_be_bytes(gas_price_wei)?),
2924        rlp_bytes(&decimal_to_be_bytes(gas_limit)?),
2925        rlp_bytes(&to),
2926        rlp_bytes(&decimal_to_be_bytes(value)?),
2927        rlp_bytes(&data),
2928        rlp_bytes(&u128_to_be_bytes(v)),
2929        rlp_bytes(r),
2930        rlp_bytes(s),
2931    ];
2932    Ok(format!("0x{}", hex::encode(rlp_list(&signed_items))))
2933}
2934
2935struct Type2TxSigningInput<'a> {
2936    signing_key: &'a SigningKey,
2937    chain_id: u64,
2938    nonce: &'a str,
2939    max_priority_fee_per_gas_wei: &'a str,
2940    max_fee_per_gas_wei: &'a str,
2941    gas_limit: &'a str,
2942    to: &'a str,
2943    value: &'a str,
2944    data: &'a str,
2945}
2946
2947fn sign_type2_transaction(input: &Type2TxSigningInput<'_>) -> EvmResult<String> {
2948    if input.chain_id == 0 {
2949        return Err(EvmServiceError::InvalidChainId);
2950    }
2951    let to = address_bytes(input.to)?;
2952    let data = hex_data_to_bytes(input.data)?;
2953    let access_list = rlp_list(&[]);
2954    let unsigned_items = vec![
2955        rlp_bytes(&u64_to_be_bytes(input.chain_id)),
2956        rlp_bytes(&decimal_to_be_bytes(input.nonce)?),
2957        rlp_bytes(&decimal_to_be_bytes(input.max_priority_fee_per_gas_wei)?),
2958        rlp_bytes(&decimal_to_be_bytes(input.max_fee_per_gas_wei)?),
2959        rlp_bytes(&decimal_to_be_bytes(input.gas_limit)?),
2960        rlp_bytes(&to),
2961        rlp_bytes(&decimal_to_be_bytes(input.value)?),
2962        rlp_bytes(&data),
2963        access_list.clone(),
2964    ];
2965    let unsigned_payload = rlp_list(&unsigned_items);
2966    let mut signing_payload = Vec::with_capacity(1 + unsigned_payload.len());
2967    signing_payload.push(0x02);
2968    signing_payload.extend_from_slice(&unsigned_payload);
2969    let digest = keccak256(&signing_payload);
2970    let (signature, recovery_id) = sign_digest(input.signing_key, &digest)?;
2971    let sig_bytes = signature.to_bytes();
2972    let signed_items = vec![
2973        rlp_bytes(&u64_to_be_bytes(input.chain_id)),
2974        rlp_bytes(&decimal_to_be_bytes(input.nonce)?),
2975        rlp_bytes(&decimal_to_be_bytes(input.max_priority_fee_per_gas_wei)?),
2976        rlp_bytes(&decimal_to_be_bytes(input.max_fee_per_gas_wei)?),
2977        rlp_bytes(&decimal_to_be_bytes(input.gas_limit)?),
2978        rlp_bytes(&to),
2979        rlp_bytes(&decimal_to_be_bytes(input.value)?),
2980        rlp_bytes(&data),
2981        access_list,
2982        rlp_bytes(&u64_to_be_bytes(u64::from(recovery_id.to_byte()))),
2983        rlp_bytes(trim_leading_zeroes(&sig_bytes[..32])),
2984        rlp_bytes(trim_leading_zeroes(&sig_bytes[32..])),
2985    ];
2986    let mut raw = Vec::new();
2987    raw.push(0x02);
2988    raw.extend_from_slice(&rlp_list(&signed_items));
2989    Ok(format!("0x{}", hex::encode(raw)))
2990}
2991
2992fn sign_hash(signing_key: &SigningKey, digest: &[u8]) -> EvmResult<String> {
2993    let (signature, recovery_id) = sign_digest(signing_key, digest)?;
2994    let mut bytes = Vec::with_capacity(65);
2995    bytes.extend_from_slice(signature.to_bytes().as_slice());
2996    bytes.push(recovery_id.to_byte() + 27);
2997    Ok(format!("0x{}", hex::encode(bytes)))
2998}
2999
3000fn sign_digest(signing_key: &SigningKey, digest: &[u8]) -> EvmResult<(Signature, RecoveryId)> {
3001    if digest.len() != 32 {
3002        return Err(EvmServiceError::InvalidInput(
3003            "Signing digest must be 32 bytes".to_string(),
3004        ));
3005    }
3006    signing_key
3007        .sign_prehash_recoverable(digest)
3008        .map_err(|_| EvmServiceError::InvalidInput("EVM signing failed".to_string()))
3009}
3010
3011fn evm_message_from_payload(payload_json: &str, wallet_address: &str) -> EvmResult<Vec<u8>> {
3012    let value: serde_json::Value = serde_json::from_str(payload_json)
3013        .map_err(|_| EvmServiceError::InvalidInput("EVM dApp payload must be JSON".to_string()))?;
3014    if let Some(message) = value.get("message").and_then(serde_json::Value::as_str) {
3015        return evm_message_bytes(message);
3016    }
3017    if let Some(params) = value.get("params").and_then(serde_json::Value::as_array) {
3018        for item in params {
3019            if let Some(message) = item.as_str() {
3020                if normalize_address(message, "signing account").is_ok() {
3021                    if !address_eq(message, wallet_address) {
3022                        return Err(EvmServiceError::InvalidInput(
3023                            "EVM signing account does not match the selected wallet".to_string(),
3024                        ));
3025                    }
3026                    continue;
3027                }
3028                return evm_message_bytes(message);
3029            }
3030        }
3031    }
3032    Err(EvmServiceError::InvalidInput(
3033        "EVM message payload must include a message string".to_string(),
3034    ))
3035}
3036
3037fn evm_message_bytes(value: &str) -> EvmResult<Vec<u8>> {
3038    let bytes = if let Some(hex_value) = value.strip_prefix("0x") {
3039        if hex_value.len() % 2 != 0 {
3040            return Err(EvmServiceError::InvalidInput(
3041                "EVM message hex must contain complete bytes".to_string(),
3042            ));
3043        }
3044        hex::decode(hex_value).map_err(|_| {
3045            EvmServiceError::InvalidInput("EVM message contains invalid hex".to_string())
3046        })?
3047    } else {
3048        value.as_bytes().to_vec()
3049    };
3050    if bytes.is_empty() || bytes.len() > 16 * 1024 {
3051        return Err(EvmServiceError::InvalidInput(
3052            "EVM message must contain between 1 and 16384 bytes".to_string(),
3053        ));
3054    }
3055    Ok(bytes)
3056}
3057
3058fn parse_dapp_transaction(
3059    chain: &EvmChainConfig,
3060    signer_address: &str,
3061    payload_json: &str,
3062) -> EvmResult<DappTransactionRequest> {
3063    let value: serde_json::Value = serde_json::from_str(payload_json)
3064        .map_err(|_| EvmServiceError::InvalidInput("EVM dApp payload must be JSON".to_string()))?;
3065    let tx = extract_dapp_transaction_value(&value)?;
3066    let from = tx
3067        .get("from")
3068        .and_then(serde_json::Value::as_str)
3069        .map(|value| normalize_address(value, "transaction from"))
3070        .transpose()?;
3071    if let Some(from) = from {
3072        if !address_eq(&from, signer_address) {
3073            return Err(EvmServiceError::InvalidInput(
3074                "Transaction from does not match the selected EVM wallet".to_string(),
3075            ));
3076        }
3077    }
3078    let to = tx
3079        .get("to")
3080        .and_then(serde_json::Value::as_str)
3081        .ok_or_else(|| EvmServiceError::InvalidInput("EVM transaction to is required".to_string()))
3082        .and_then(|value| normalize_address(value, "transaction to"))?;
3083    let value = evm_quantity_field(tx.get("value"), "transaction value")?
3084        .unwrap_or_else(|| "0".to_string());
3085    validate_arc_recipient(chain.chain_id, &to, &value)?;
3086    let data = evm_data_field(
3087        tx.get("data")
3088            .or_else(|| tx.get("input"))
3089            .and_then(serde_json::Value::as_str),
3090    )?;
3091    let gas_limit = match tx
3092        .get("gas")
3093        .or_else(|| tx.get("gasLimit"))
3094        .and_then(serde_json::Value::as_str)
3095    {
3096        Some(value) => evm_quantity_to_decimal(value, "gas limit")?,
3097        None => estimate_gas(chain, signer_address, &to, &value, &data)?,
3098    };
3099    let nonce = match tx.get("nonce").and_then(serde_json::Value::as_str) {
3100        Some(value) => evm_quantity_to_decimal(value, "nonce")?,
3101        None => load_nonce(chain, signer_address)?,
3102    };
3103    let provided_gas_price_wei = tx
3104        .get("gasPrice")
3105        .and_then(serde_json::Value::as_str)
3106        .map(|value| evm_quantity_to_decimal(value, "gas price"))
3107        .transpose()?;
3108    let provided_max_fee_per_gas_wei = tx
3109        .get("maxFeePerGas")
3110        .and_then(serde_json::Value::as_str)
3111        .map(|value| evm_quantity_to_decimal(value, "max fee per gas"))
3112        .transpose()?;
3113    let provided_max_priority_fee_per_gas_wei = tx
3114        .get("maxPriorityFeePerGas")
3115        .and_then(serde_json::Value::as_str)
3116        .map(|value| evm_quantity_to_decimal(value, "max priority fee per gas"))
3117        .transpose()?;
3118    let fee_quote = if provided_gas_price_wei.is_none()
3119        && (provided_max_fee_per_gas_wei.is_none()
3120            || provided_max_priority_fee_per_gas_wei.is_none())
3121    {
3122        Some(load_fee_quote(chain)?)
3123    } else {
3124        None
3125    };
3126    let gas_price_wei = provided_gas_price_wei
3127        .or_else(|| fee_quote.as_ref().map(|quote| quote.gas_price_wei.clone()))
3128        .unwrap_or_else(|| "0".to_string());
3129    let max_fee_per_gas_wei = provided_max_fee_per_gas_wei.or_else(|| {
3130        fee_quote
3131            .as_ref()
3132            .and_then(|quote| quote.max_fee_per_gas_wei.clone())
3133    });
3134    let max_priority_fee_per_gas_wei = provided_max_priority_fee_per_gas_wei.or_else(|| {
3135        fee_quote
3136            .as_ref()
3137            .and_then(|quote| quote.max_priority_fee_per_gas_wei.clone())
3138    });
3139
3140    Ok(DappTransactionRequest {
3141        to,
3142        value,
3143        data,
3144        gas_limit,
3145        gas_price_wei,
3146        max_fee_per_gas_wei,
3147        max_priority_fee_per_gas_wei,
3148        nonce,
3149    })
3150}
3151
3152fn extract_dapp_transaction_value(
3153    value: &serde_json::Value,
3154) -> EvmResult<&serde_json::Map<String, serde_json::Value>> {
3155    if let Some(params) = value.get("params") {
3156        if let Some(items) = params.as_array() {
3157            if let Some(first) = items.first().and_then(serde_json::Value::as_object) {
3158                return Ok(first);
3159            }
3160        }
3161        if let Some(object) = params.as_object() {
3162            if let Some(tx) = object
3163                .get("transaction")
3164                .or_else(|| object.get("tx"))
3165                .and_then(serde_json::Value::as_object)
3166            {
3167                return Ok(tx);
3168            }
3169            if object.contains_key("to")
3170                || object.contains_key("data")
3171                || object.contains_key("value")
3172            {
3173                return Ok(object);
3174            }
3175        }
3176    }
3177    if let Some(tx) = value
3178        .get("transaction")
3179        .or_else(|| value.get("tx"))
3180        .and_then(serde_json::Value::as_object)
3181    {
3182        return Ok(tx);
3183    }
3184    value
3185        .as_object()
3186        .filter(|object| object.contains_key("to"))
3187        .ok_or_else(|| {
3188            EvmServiceError::InvalidInput(
3189                "EVM dApp transaction payload is missing a transaction object".to_string(),
3190            )
3191        })
3192}
3193
3194fn evm_quantity_field(
3195    value: Option<&serde_json::Value>,
3196    field: &'static str,
3197) -> EvmResult<Option<String>> {
3198    match value {
3199        Some(serde_json::Value::String(value)) => evm_quantity_to_decimal(value, field).map(Some),
3200        Some(serde_json::Value::Number(value)) => {
3201            evm_quantity_to_decimal(&value.to_string(), field).map(Some)
3202        }
3203        Some(_) => Err(EvmServiceError::InvalidInput(format!(
3204            "{field} must be a hex or decimal quantity"
3205        ))),
3206        None => Ok(None),
3207    }
3208}
3209
3210fn evm_quantity_to_decimal(value: &str, field: &'static str) -> EvmResult<String> {
3211    let value = require_non_empty(value, field)?;
3212    if value.starts_with("0x") {
3213        return hex_quantity_to_decimal(&value);
3214    }
3215    normalize_decimal(&value, field)
3216}
3217
3218fn evm_data_field(value: Option<&str>) -> EvmResult<String> {
3219    let data = value
3220        .map(str::trim)
3221        .filter(|value| !value.is_empty())
3222        .unwrap_or("0x");
3223    hex_data_to_bytes(data)?;
3224    Ok(data.to_string())
3225}
3226
3227fn typed_data_digest(payload_json: &str) -> EvmResult<[u8; 32]> {
3228    let value: serde_json::Value =
3229        serde_json::from_str(payload_json).map_err(|_| EvmServiceError::InvalidTypedData)?;
3230    let typed_data = extract_typed_data(&value)?;
3231    let domain_separator = hash_typed_struct("EIP712Domain", typed_data.domain(), &typed_data)?;
3232    let primary_type = typed_data.primary_type()?;
3233    let message_hash = hash_typed_struct(primary_type, typed_data.message(), &typed_data)?;
3234    let mut payload = Vec::with_capacity(66);
3235    payload.extend_from_slice(b"\x19\x01");
3236    payload.extend_from_slice(&domain_separator);
3237    payload.extend_from_slice(&message_hash);
3238    Ok(keccak256(&payload))
3239}
3240
3241struct TypedData {
3242    value: serde_json::Value,
3243}
3244
3245impl TypedData {
3246    fn types(&self) -> EvmResult<&serde_json::Map<String, serde_json::Value>> {
3247        self.value
3248            .get("types")
3249            .and_then(serde_json::Value::as_object)
3250            .ok_or(EvmServiceError::InvalidTypedData)
3251    }
3252
3253    fn primary_type(&self) -> EvmResult<&str> {
3254        self.value
3255            .get("primaryType")
3256            .and_then(serde_json::Value::as_str)
3257            .ok_or(EvmServiceError::InvalidTypedData)
3258    }
3259
3260    fn domain(&self) -> &serde_json::Value {
3261        self.value.get("domain").unwrap_or(&serde_json::Value::Null)
3262    }
3263
3264    fn message(&self) -> &serde_json::Value {
3265        self.value
3266            .get("message")
3267            .unwrap_or(&serde_json::Value::Null)
3268    }
3269
3270    fn fields(&self, type_name: &str) -> EvmResult<Vec<TypedField>> {
3271        let fields = self
3272            .types()?
3273            .get(type_name)
3274            .and_then(serde_json::Value::as_array)
3275            .ok_or(EvmServiceError::InvalidTypedData)?;
3276        fields
3277            .iter()
3278            .map(|field| {
3279                let field = field.as_object().ok_or(EvmServiceError::InvalidTypedData)?;
3280                let name = field
3281                    .get("name")
3282                    .and_then(serde_json::Value::as_str)
3283                    .ok_or(EvmServiceError::InvalidTypedData)?;
3284                let ty = field
3285                    .get("type")
3286                    .and_then(serde_json::Value::as_str)
3287                    .ok_or(EvmServiceError::InvalidTypedData)?;
3288                Ok(TypedField {
3289                    name: name.to_string(),
3290                    ty: ty.to_string(),
3291                })
3292            })
3293            .collect()
3294    }
3295
3296    fn has_type(&self, type_name: &str) -> bool {
3297        self.types()
3298            .ok()
3299            .is_some_and(|types| types.contains_key(type_name))
3300    }
3301}
3302
3303#[derive(Debug, Clone)]
3304struct TypedField {
3305    name: String,
3306    ty: String,
3307}
3308
3309fn extract_typed_data(value: &serde_json::Value) -> EvmResult<TypedData> {
3310    if value.get("types").is_some() && value.get("primaryType").is_some() {
3311        return Ok(TypedData {
3312            value: value.clone(),
3313        });
3314    }
3315    if let Some(params) = value.get("params").and_then(serde_json::Value::as_array) {
3316        for item in params.iter().rev() {
3317            if item.get("types").is_some() && item.get("primaryType").is_some() {
3318                return Ok(TypedData {
3319                    value: item.clone(),
3320                });
3321            }
3322            if let Some(raw) = item.as_str() {
3323                let parsed: serde_json::Value =
3324                    serde_json::from_str(raw).map_err(|_| EvmServiceError::InvalidTypedData)?;
3325                if parsed.get("types").is_some() && parsed.get("primaryType").is_some() {
3326                    return Ok(TypedData { value: parsed });
3327                }
3328            }
3329        }
3330    }
3331    if let Some(raw) = value.get("typedData").and_then(serde_json::Value::as_str) {
3332        let parsed: serde_json::Value =
3333            serde_json::from_str(raw).map_err(|_| EvmServiceError::InvalidTypedData)?;
3334        return Ok(TypedData { value: parsed });
3335    }
3336    if let Some(typed_data) = value.get("typedData") {
3337        return Ok(TypedData {
3338            value: typed_data.clone(),
3339        });
3340    }
3341    Err(EvmServiceError::InvalidTypedData)
3342}
3343
3344fn hash_typed_struct(
3345    type_name: &str,
3346    data: &serde_json::Value,
3347    typed_data: &TypedData,
3348) -> EvmResult<[u8; 32]> {
3349    let mut encoded = Vec::with_capacity(32);
3350    encoded.extend_from_slice(&keccak256(encode_type(type_name, typed_data)?.as_bytes()));
3351    let object = data.as_object();
3352    for field in typed_data.fields(type_name)? {
3353        let value = object.and_then(|object| object.get(&field.name));
3354        encoded.extend_from_slice(&encode_typed_value(&field.ty, value, typed_data)?);
3355    }
3356    Ok(keccak256(&encoded))
3357}
3358
3359fn encode_type(type_name: &str, typed_data: &TypedData) -> EvmResult<String> {
3360    let mut deps = Vec::new();
3361    collect_type_dependencies(type_name, typed_data, &mut deps)?;
3362    deps.retain(|dep| dep != type_name);
3363    deps.sort();
3364    deps.dedup();
3365    let mut ordered = vec![type_name.to_string()];
3366    ordered.extend(deps);
3367    ordered
3368        .into_iter()
3369        .map(|name| {
3370            let fields = typed_data.fields(&name)?;
3371            let args = fields
3372                .into_iter()
3373                .map(|field| format!("{} {}", field.ty, field.name))
3374                .collect::<Vec<_>>()
3375                .join(",");
3376            Ok(format!("{name}({args})"))
3377        })
3378        .collect::<EvmResult<Vec<_>>>()
3379        .map(|parts| parts.join(""))
3380}
3381
3382fn collect_type_dependencies(
3383    type_name: &str,
3384    typed_data: &TypedData,
3385    deps: &mut Vec<String>,
3386) -> EvmResult<()> {
3387    if deps.iter().any(|dep| dep == type_name) {
3388        return Ok(());
3389    }
3390    if !typed_data.has_type(type_name) {
3391        return Ok(());
3392    }
3393    deps.push(type_name.to_string());
3394    for field in typed_data.fields(type_name)? {
3395        let base_type = eip712_base_type(&field.ty);
3396        if typed_data.has_type(&base_type) {
3397            collect_type_dependencies(&base_type, typed_data, deps)?;
3398        }
3399    }
3400    Ok(())
3401}
3402
3403fn encode_typed_value(
3404    ty: &str,
3405    value: Option<&serde_json::Value>,
3406    typed_data: &TypedData,
3407) -> EvmResult<[u8; 32]> {
3408    if ty.ends_with(']') {
3409        let item_type = ty
3410            .split_once('[')
3411            .map(|(item, _)| item)
3412            .ok_or(EvmServiceError::InvalidTypedData)?;
3413        let values = value
3414            .and_then(serde_json::Value::as_array)
3415            .ok_or(EvmServiceError::InvalidTypedData)?;
3416        let mut encoded = Vec::with_capacity(values.len() * 32);
3417        for item in values {
3418            encoded.extend_from_slice(&encode_typed_value(item_type, Some(item), typed_data)?);
3419        }
3420        return Ok(keccak256(&encoded));
3421    }
3422    if typed_data.has_type(ty) {
3423        return hash_typed_struct(ty, value.unwrap_or(&serde_json::Value::Null), typed_data);
3424    }
3425    let value = value.ok_or(EvmServiceError::InvalidTypedData)?;
3426    match ty {
3427        "string" => value
3428            .as_str()
3429            .map(|value| keccak256(value.as_bytes()))
3430            .ok_or(EvmServiceError::InvalidTypedData),
3431        "bytes" => value
3432            .as_str()
3433            .ok_or(EvmServiceError::InvalidTypedData)
3434            .and_then(hex_data_to_bytes)
3435            .map(|bytes| keccak256(&bytes)),
3436        "address" => {
3437            let address = value
3438                .as_str()
3439                .ok_or(EvmServiceError::InvalidTypedData)
3440                .and_then(|value| normalize_address(value, "typed data address"))?;
3441            let mut output = [0u8; 32];
3442            output[12..].copy_from_slice(&address_bytes(&address)?);
3443            Ok(output)
3444        }
3445        "bool" => {
3446            let mut output = [0u8; 32];
3447            output[31] = u8::from(value.as_bool().ok_or(EvmServiceError::InvalidTypedData)?);
3448            Ok(output)
3449        }
3450        _ if ty.starts_with("bytes") => encode_fixed_bytes(ty, value),
3451        _ if ty.starts_with("uint") => encode_typed_uint(ty, value),
3452        _ if ty.starts_with("int") => encode_typed_int(ty, value),
3453        _ => Err(EvmServiceError::InvalidTypedData),
3454    }
3455}
3456
3457fn encode_fixed_bytes(ty: &str, value: &serde_json::Value) -> EvmResult<[u8; 32]> {
3458    let size = ty
3459        .strip_prefix("bytes")
3460        .and_then(|value| value.parse::<usize>().ok())
3461        .filter(|size| (1..=32).contains(size))
3462        .ok_or(EvmServiceError::InvalidTypedData)?;
3463    let bytes = value
3464        .as_str()
3465        .ok_or(EvmServiceError::InvalidTypedData)
3466        .and_then(hex_data_to_bytes)?;
3467    if bytes.len() != size {
3468        return Err(EvmServiceError::InvalidTypedData);
3469    }
3470    let mut output = [0u8; 32];
3471    output[..bytes.len()].copy_from_slice(&bytes);
3472    Ok(output)
3473}
3474
3475fn encode_typed_uint(ty: &str, value: &serde_json::Value) -> EvmResult<[u8; 32]> {
3476    validate_integer_type(ty, "uint")?;
3477    let decimal = typed_json_integer_to_decimal(value)?;
3478    decimal_to_32_bytes(&decimal)
3479}
3480
3481fn encode_typed_int(ty: &str, value: &serde_json::Value) -> EvmResult<[u8; 32]> {
3482    validate_integer_type(ty, "int")?;
3483    let decimal = typed_json_integer_to_decimal(value)?;
3484    decimal_to_32_bytes(&decimal)
3485}
3486
3487fn validate_integer_type(ty: &str, prefix: &str) -> EvmResult<()> {
3488    let bits = ty.strip_prefix(prefix).unwrap_or_default();
3489    let bits = if bits.is_empty() {
3490        256
3491    } else {
3492        bits.parse::<usize>()
3493            .map_err(|_| EvmServiceError::InvalidTypedData)?
3494    };
3495    if bits == 0 || bits > 256 || bits % 8 != 0 {
3496        return Err(EvmServiceError::InvalidTypedData);
3497    }
3498    Ok(())
3499}
3500
3501fn typed_json_integer_to_decimal(value: &serde_json::Value) -> EvmResult<String> {
3502    match value {
3503        serde_json::Value::String(value) => evm_quantity_to_decimal(value, "typed data integer"),
3504        serde_json::Value::Number(value) => {
3505            normalize_decimal(&value.to_string(), "typed data integer")
3506        }
3507        _ => Err(EvmServiceError::InvalidTypedData),
3508    }
3509}
3510
3511fn eip712_base_type(ty: &str) -> String {
3512    ty.split_once('[')
3513        .map(|(base, _)| base)
3514        .unwrap_or(ty)
3515        .to_string()
3516}
3517
3518fn hex_data_to_bytes(data: &str) -> EvmResult<Vec<u8>> {
3519    let data = data.trim();
3520    if data.is_empty() || data == "0x" {
3521        return Ok(Vec::new());
3522    }
3523    let hex = data
3524        .strip_prefix("0x")
3525        .ok_or_else(|| EvmServiceError::InvalidInput("Hex data must start with 0x".to_string()))?;
3526    if hex.len() % 2 != 0 {
3527        return Err(EvmServiceError::InvalidInput(
3528            "Hex data length must be even".to_string(),
3529        ));
3530    }
3531    hex::decode(hex).map_err(|_| EvmServiceError::InvalidInput("Hex data is invalid".to_string()))
3532}
3533
3534fn normalize_decimal(value: &str, field: &'static str) -> EvmResult<String> {
3535    let value = require_non_empty(value, field)?;
3536    if !value.chars().all(|ch| ch.is_ascii_digit()) {
3537        return Err(EvmServiceError::InvalidInput(format!(
3538            "{field} must be a decimal integer in base units"
3539        )));
3540    }
3541    let trimmed = value.trim_start_matches('0');
3542    Ok(if trimmed.is_empty() {
3543        "0".to_string()
3544    } else {
3545        trimmed.to_string()
3546    })
3547}
3548
3549fn decimal_to_hex_quantity(value: &str) -> EvmResult<String> {
3550    let bytes = decimal_to_be_bytes(value)?;
3551    if bytes.is_empty() {
3552        Ok("0x0".to_string())
3553    } else {
3554        Ok(format!("0x{}", hex::encode(bytes)))
3555    }
3556}
3557
3558fn hex_quantity_to_decimal(value: &str) -> EvmResult<String> {
3559    let value = if value == "0x" { "0x0" } else { value };
3560    let hex = value.strip_prefix("0x").ok_or_else(|| {
3561        EvmServiceError::InvalidInput("Hex quantity must start with 0x".to_string())
3562    })?;
3563    if !hex.chars().all(|ch| ch.is_ascii_hexdigit()) {
3564        return Err(EvmServiceError::InvalidInput(
3565            "Hex quantity is invalid".to_string(),
3566        ));
3567    }
3568    let padded;
3569    let hex = if hex.len() % 2 == 0 {
3570        hex
3571    } else {
3572        padded = format!("0{hex}");
3573        &padded
3574    };
3575    let bytes = hex::decode(hex)
3576        .map_err(|_| EvmServiceError::InvalidInput("Hex quantity is invalid".to_string()))?;
3577    Ok(be_bytes_to_decimal(&bytes))
3578}
3579
3580fn hex_quantity_to_u64(value: &str) -> EvmResult<u64> {
3581    let decimal = hex_quantity_to_decimal(value)?;
3582    decimal
3583        .parse::<u64>()
3584        .map_err(|_| EvmServiceError::InvalidInput("Hex quantity exceeds u64".to_string()))
3585}
3586
3587fn normalize_tx_hash(value: &str) -> EvmResult<String> {
3588    let value = require_non_empty(value, "transaction hash")?;
3589    let hex = value.strip_prefix("0x").unwrap_or(&value);
3590    if hex.len() != 64 || !hex.chars().all(|ch| ch.is_ascii_hexdigit()) {
3591        return Err(EvmServiceError::InvalidInput(
3592            "Transaction hash must be 32 bytes hex".to_string(),
3593        ));
3594    }
3595    Ok(format!("0x{}", hex.to_ascii_lowercase()))
3596}
3597
3598fn hex_word_to_decimal(value: &str) -> EvmResult<String> {
3599    hex_quantity_to_decimal(value)
3600}
3601
3602fn hex_word_to_u8(value: &str) -> EvmResult<u8> {
3603    let decimal = hex_word_to_decimal(value)?;
3604    decimal
3605        .parse::<u8>()
3606        .map_err(|_| EvmServiceError::InvalidInput("ERC-20 decimals is invalid".to_string()))
3607}
3608
3609fn decode_erc20_string(value: &str) -> EvmResult<String> {
3610    let bytes = hex_data_to_bytes(value)?;
3611    if bytes.is_empty() {
3612        return Err(EvmServiceError::InvalidInput(
3613            "ERC-20 string is empty".to_string(),
3614        ));
3615    }
3616    if bytes.len() == 32 {
3617        let trimmed = bytes
3618            .into_iter()
3619            .take_while(|byte| *byte != 0)
3620            .collect::<Vec<_>>();
3621        return String::from_utf8(trimmed).map_err(|_| {
3622            EvmServiceError::InvalidInput("ERC-20 bytes32 string is invalid".to_string())
3623        });
3624    }
3625    if bytes.len() >= 64 {
3626        let offset = be_bytes_to_decimal(&bytes[..32])
3627            .parse::<usize>()
3628            .map_err(|_| {
3629                EvmServiceError::InvalidInput("ERC-20 string offset is invalid".to_string())
3630            })?;
3631        let length_end = offset.checked_add(32).ok_or_else(|| {
3632            EvmServiceError::InvalidInput("ERC-20 string offset is invalid".to_string())
3633        })?;
3634        if offset % 32 != 0 || offset < 32 || length_end > bytes.len() {
3635            return Err(EvmServiceError::InvalidInput(
3636                "ERC-20 string offset is invalid".to_string(),
3637            ));
3638        }
3639        let len = be_bytes_to_decimal(&bytes[offset..length_end])
3640            .parse::<usize>()
3641            .map_err(|_| {
3642                EvmServiceError::InvalidInput("ERC-20 dynamic string length is invalid".to_string())
3643            })?;
3644        let end = length_end.checked_add(len).ok_or_else(|| {
3645            EvmServiceError::InvalidInput("ERC-20 dynamic string length is invalid".to_string())
3646        })?;
3647        if end > bytes.len() || len > 128 {
3648            return Err(EvmServiceError::InvalidInput(
3649                "ERC-20 dynamic string length is invalid".to_string(),
3650            ));
3651        }
3652        return String::from_utf8(bytes[length_end..end].to_vec()).map_err(|_| {
3653            EvmServiceError::InvalidInput("ERC-20 dynamic string is invalid".to_string())
3654        });
3655    }
3656    Err(EvmServiceError::InvalidInput(
3657        "ERC-20 string response is invalid".to_string(),
3658    ))
3659}
3660
3661fn decimal_mul(left: &str, right: &str) -> EvmResult<String> {
3662    let left = normalize_decimal(left, "left")?;
3663    let right = normalize_decimal(right, "right")?;
3664    let mut digits = vec![0u8; left.len() + right.len()];
3665    for (i, lb) in left.bytes().rev().enumerate() {
3666        for (j, rb) in right.bytes().rev().enumerate() {
3667            digits[i + j] += (lb - b'0') * (rb - b'0');
3668        }
3669    }
3670    for index in 0..digits.len() {
3671        if digits[index] >= 10 {
3672            let carry = digits[index] / 10;
3673            digits[index] %= 10;
3674            if index + 1 == digits.len() {
3675                digits.push(carry);
3676            } else {
3677                digits[index + 1] += carry;
3678            }
3679        }
3680    }
3681    while digits.len() > 1 && digits.last() == Some(&0) {
3682        digits.pop();
3683    }
3684    Ok(digits
3685        .into_iter()
3686        .rev()
3687        .map(|digit| char::from(b'0' + digit))
3688        .collect())
3689}
3690
3691fn decimal_mul_u64(left: &str, right: u64) -> EvmResult<String> {
3692    decimal_mul(left, &right.to_string())
3693}
3694
3695fn decimal_add(left: &str, right: &str) -> EvmResult<String> {
3696    let left = normalize_decimal(left, "left")?;
3697    let right = normalize_decimal(right, "right")?;
3698    let left = left.as_bytes();
3699    let right = right.as_bytes();
3700    let mut carry = 0u8;
3701    let mut output = Vec::with_capacity(left.len().max(right.len()) + 1);
3702    let mut i = 0usize;
3703    while i < left.len() || i < right.len() || carry > 0 {
3704        let l = left
3705            .len()
3706            .checked_sub(1 + i)
3707            .and_then(|index| left.get(index))
3708            .map(|byte| byte - b'0')
3709            .unwrap_or(0);
3710        let r = right
3711            .len()
3712            .checked_sub(1 + i)
3713            .and_then(|index| right.get(index))
3714            .map(|byte| byte - b'0')
3715            .unwrap_or(0);
3716        let sum = l + r + carry;
3717        output.push(char::from(b'0' + (sum % 10)));
3718        carry = sum / 10;
3719        i += 1;
3720    }
3721    Ok(output.into_iter().rev().collect())
3722}
3723
3724fn decimal_cmp(left: &str, right: &str) -> EvmResult<std::cmp::Ordering> {
3725    let left = normalize_decimal(left, "left")?;
3726    let right = normalize_decimal(right, "right")?;
3727    Ok(left.len().cmp(&right.len()).then_with(|| left.cmp(&right)))
3728}
3729
3730fn decimal_to_32_bytes(value: &str) -> EvmResult<[u8; 32]> {
3731    let bytes = decimal_to_be_bytes(value)?;
3732    if bytes.len() > 32 {
3733        return Err(EvmServiceError::InvalidInput(
3734            "Integer exceeds uint256".to_string(),
3735        ));
3736    }
3737    let mut output = [0u8; 32];
3738    output[32 - bytes.len()..].copy_from_slice(&bytes);
3739    Ok(output)
3740}
3741
3742fn decimal_to_be_bytes(value: &str) -> EvmResult<Vec<u8>> {
3743    let value = normalize_decimal(value, "decimal")?;
3744    if value == "0" {
3745        return Ok(Vec::new());
3746    }
3747    let mut bytes = vec![0u8];
3748    for digit in value.bytes() {
3749        let digit = digit - b'0';
3750        let mut carry = u16::from(digit);
3751        for byte in bytes.iter_mut().rev() {
3752            let next = u16::from(*byte) * 10 + carry;
3753            *byte = (next & 0xff) as u8;
3754            carry = next >> 8;
3755        }
3756        while carry > 0 {
3757            bytes.insert(0, (carry & 0xff) as u8);
3758            carry >>= 8;
3759        }
3760    }
3761    Ok(trim_leading_zeroes(&bytes).to_vec())
3762}
3763
3764fn be_bytes_to_decimal(bytes: &[u8]) -> String {
3765    let mut digits = vec![0u8];
3766    for byte in trim_leading_zeroes(bytes) {
3767        let mut carry = *byte as u16;
3768        for digit in digits.iter_mut().rev() {
3769            let next = u16::from(*digit) * 256 + carry;
3770            *digit = (next % 10) as u8;
3771            carry = next / 10;
3772        }
3773        while carry > 0 {
3774            digits.insert(0, (carry % 10) as u8);
3775            carry /= 10;
3776        }
3777    }
3778    digits
3779        .into_iter()
3780        .map(|digit| char::from(b'0' + digit))
3781        .collect()
3782}
3783
3784fn u64_to_be_bytes(value: u64) -> Vec<u8> {
3785    trim_leading_zeroes(&value.to_be_bytes()).to_vec()
3786}
3787
3788fn u128_to_be_bytes(value: u128) -> Vec<u8> {
3789    trim_leading_zeroes(&value.to_be_bytes()).to_vec()
3790}
3791
3792fn trim_leading_zeroes(bytes: &[u8]) -> &[u8] {
3793    let first_non_zero = bytes
3794        .iter()
3795        .position(|byte| *byte != 0)
3796        .unwrap_or(bytes.len());
3797    &bytes[first_non_zero..]
3798}
3799
3800fn rlp_bytes(bytes: &[u8]) -> Vec<u8> {
3801    if bytes.len() == 1 && bytes[0] < 0x80 {
3802        return bytes.to_vec();
3803    }
3804    if bytes.len() <= 55 {
3805        let mut output = Vec::with_capacity(1 + bytes.len());
3806        output.push(0x80 + bytes.len() as u8);
3807        output.extend_from_slice(bytes);
3808        return output;
3809    }
3810    let len = u64_to_be_bytes(bytes.len() as u64);
3811    let mut output = Vec::with_capacity(1 + len.len() + bytes.len());
3812    output.push(0xb7 + len.len() as u8);
3813    output.extend_from_slice(&len);
3814    output.extend_from_slice(bytes);
3815    output
3816}
3817
3818fn rlp_list(items: &[Vec<u8>]) -> Vec<u8> {
3819    let payload_len: usize = items.iter().map(Vec::len).sum();
3820    let mut payload = Vec::with_capacity(payload_len);
3821    for item in items {
3822        payload.extend_from_slice(item);
3823    }
3824    if payload.len() <= 55 {
3825        let mut output = Vec::with_capacity(1 + payload.len());
3826        output.push(0xc0 + payload.len() as u8);
3827        output.extend_from_slice(&payload);
3828        return output;
3829    }
3830    let len = u64_to_be_bytes(payload.len() as u64);
3831    let mut output = Vec::with_capacity(1 + len.len() + payload.len());
3832    output.push(0xf7 + len.len() as u8);
3833    output.extend_from_slice(&len);
3834    output.extend_from_slice(&payload);
3835    output
3836}
3837
3838fn now_ms() -> u64 {
3839    SystemTime::now()
3840        .duration_since(UNIX_EPOCH)
3841        .map(|duration| duration.as_millis().min(u128::from(u64::MAX)) as u64)
3842        .unwrap_or(0)
3843}
3844
3845fn submitted_at() -> String {
3846    now_ms().to_string()
3847}
3848
3849fn keccak256(data: &[u8]) -> [u8; 32] {
3850    let mut hasher = Keccak256::new();
3851    hasher.update(data);
3852    hasher.finalize().into()
3853}
3854
3855fn short_address(address: &str) -> String {
3856    if address.len() >= 10 {
3857        format!("{}...{}", &address[..6], &address[address.len() - 4..])
3858    } else {
3859        address.to_string()
3860    }
3861}
3862
3863#[cfg(test)]
3864mod tests {
3865    use super::*;
3866    use std::io::Write as _;
3867    use std::net::TcpListener;
3868
3869    const DEV_PRIVATE_KEY: &str =
3870        "0x0000000000000000000000000000000000000000000000000000000000000001";
3871    const DEV_MNEMONIC: &str =
3872        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
3873
3874    fn spawn_rpc_server(expected_requests: usize) -> (String, std::thread::JoinHandle<()>) {
3875        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
3876        let address = listener.local_addr().unwrap();
3877        let handle = std::thread::spawn(move || {
3878            for _ in 0..expected_requests {
3879                let (mut stream, _) = listener.accept().unwrap();
3880                let mut request = [0_u8; 4_096];
3881                let length = stream.read(&mut request).unwrap();
3882                let request = String::from_utf8_lossy(&request[..length]);
3883                let result = if request.contains("eth_chainId") {
3884                    "\"0x539\""
3885                } else {
3886                    "\"0x2a\""
3887                };
3888                let body = format!("{{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{result}}}");
3889                let response = format!(
3890                    "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
3891                    body.len(),
3892                    body,
3893                );
3894                stream.write_all(response.as_bytes()).unwrap();
3895            }
3896        });
3897        (format!("http://{address}"), handle)
3898    }
3899
3900    #[test]
3901    fn every_builtin_chain_has_a_distinct_rpc_fallback() {
3902        for chain in builtin_chains() {
3903            let candidates = rpc_candidates(&chain);
3904            assert!(candidates.len() >= 2, "{} has no RPC fallback", chain.name);
3905            let unique = candidates.iter().collect::<std::collections::HashSet<_>>();
3906            assert_eq!(
3907                unique.len(),
3908                candidates.len(),
3909                "{} has duplicate RPCs",
3910                chain.name
3911            );
3912            assert!(candidates.iter().all(|url| url.starts_with("https://")));
3913        }
3914    }
3915
3916    fn arc_test_rpc(expected_requests: usize) -> (EvmChainConfig, std::thread::JoinHandle<()>) {
3917        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
3918        let rpc_url = format!("http://{}", listener.local_addr().unwrap());
3919        let server = std::thread::spawn(move || {
3920            for _ in 0..expected_requests {
3921                let (mut stream, _) = listener.accept().unwrap();
3922                let mut request = [0u8; 4096];
3923                let length = stream.read(&mut request).unwrap();
3924                let request = String::from_utf8_lossy(&request[..length]);
3925                let body = if request.contains("eth_estimateGas") {
3926                    serde_json::json!({"jsonrpc": "2.0", "id": 1, "error": {"code": -32000, "message": "gas estimation failed"}})
3927                } else {
3928                    let result = if request.contains("eth_chainId") {
3929                        serde_json::json!("0x13b2")
3930                    } else if request.contains("eth_getBalance") {
3931                        serde_json::json!("0xde0b6b3a7640000")
3932                    } else if request.contains("eth_getBlockByNumber") {
3933                        serde_json::json!({"baseFeePerGas": "0x1"})
3934                    } else {
3935                        serde_json::json!("0x1")
3936                    };
3937                    serde_json::json!({"jsonrpc": "2.0", "id": 1, "result": result})
3938                }.to_string();
3939                let response = format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}", body.len(), body);
3940                stream.write_all(response.as_bytes()).unwrap();
3941            }
3942        });
3943        (
3944            chain(
3945                5042,
3946                "Arc",
3947                "USDC",
3948                &rpc_url,
3949                Some("https://explorer.arc.io"),
3950                false,
3951            ),
3952            server,
3953        )
3954    }
3955
3956    #[test]
3957    fn arc_networks_use_native_usdc_and_share_evm_accounts() {
3958        let ethereum_address = address_from_mnemonic(DEV_MNEMONIC, None).unwrap();
3959        for (id, testnet) in [(5042, false), (5042002, true)] {
3960            let config = builtin_chains()
3961                .into_iter()
3962                .find(|chain| chain.chain_id == id)
3963                .unwrap();
3964            assert_eq!(config.testnet, testnet);
3965            let adapter =
3966                EvmChainAdapter::new_with_history_api_key(config, Some("test-api-key")).unwrap();
3967            assert_eq!(adapter.descriptor().native_asset.symbol, "USDC");
3968            assert_eq!(adapter.descriptor().native_asset.decimals, 18);
3969            assert!(adapter.descriptor().supports(capabilities::TRANSFER));
3970            assert!(!adapter.descriptor().supports(capabilities::HISTORY));
3971            assert_eq!(
3972                adapter.derive_account(DEV_MNEMONIC, None).unwrap().address,
3973                ethereum_address
3974            );
3975            assert_eq!(arc_fee_floor(id, "1".to_string()).unwrap(), ARC_MIN_FEE_WEI);
3976            assert_eq!(
3977                arc_fee_floor(id, "30000000000".to_string()).unwrap(),
3978                "30000000000"
3979            );
3980        }
3981        assert_eq!(arc_fee_floor(1, "1".to_string()).unwrap(), "1");
3982        assert!(!is_native_token_alias(1, ARC_USDC_CONTRACT));
3983    }
3984
3985    #[test]
3986    fn arc_asset_snapshot_keeps_one_native_usdc_balance() {
3987        let (chain, server) = arc_test_rpc(3);
3988        let snapshot = load_asset_snapshot_without_history(EvmAssetQueryRequest {
3989            chain,
3990            wallet_address: "0x1111111111111111111111111111111111111111".to_string(),
3991            tokens: vec![EvmTokenQuery {
3992                contract_address: ARC_USDC_CONTRACT.to_string(),
3993            }],
3994        })
3995        .unwrap();
3996        server.join().unwrap();
3997        assert_eq!(snapshot.native_balance_wei, "1000000000000000000");
3998        assert!(snapshot.tokens.is_empty());
3999    }
4000
4001    #[test]
4002    fn arc_fee_quotes_enforce_the_mempool_floor() {
4003        let (chain, server) = arc_test_rpc(6);
4004        let quote = load_fee_quote(&chain).unwrap();
4005        server.join().unwrap();
4006        assert_eq!(quote.fee_model, "eip1559");
4007        assert_eq!(quote.max_fee_per_gas_wei.as_deref(), Some(ARC_MIN_FEE_WEI));
4008    }
4009
4010    #[test]
4011    fn arc_failed_estimation_never_uses_eoa_intrinsic_gas() {
4012        let (chain, server) = arc_test_rpc(6);
4013        let result = estimate_gas(
4014            &chain,
4015            "0x1111111111111111111111111111111111111111",
4016            "0x2222222222222222222222222222222222222222",
4017            "1",
4018            "0x",
4019        );
4020        server.join().unwrap();
4021        assert!(matches!(result, Err(EvmServiceError::GasEstimateFailed)));
4022    }
4023
4024    #[test]
4025    fn arc_signing_rejects_low_fees_and_nonzero_value_to_zero_address() {
4026        let key = signing_key_from_hex(DEV_PRIVATE_KEY).unwrap();
4027        for id in [5042, 5042002] {
4028            let mut input = EvmTxSigningInput {
4029                signing_key: &key,
4030                chain_id: id,
4031                nonce: "0",
4032                gas_limit: "21000",
4033                to: "0x1111111111111111111111111111111111111111",
4034                value: "1",
4035                data: "0x",
4036                gas_price_wei: "1",
4037                max_fee_per_gas_wei: Some("1"),
4038                max_priority_fee_per_gas_wei: Some("0"),
4039            };
4040            assert!(sign_evm_transaction(&input).is_err());
4041            input.max_fee_per_gas_wei = Some(ARC_MIN_FEE_WEI);
4042            assert!(sign_evm_transaction(&input).unwrap().starts_with("0x02"));
4043            input.to = "0x0000000000000000000000000000000000000000";
4044            assert!(sign_evm_transaction(&input).is_err());
4045            input.value = "0";
4046            assert!(sign_evm_transaction(&input).is_ok());
4047            input.max_fee_per_gas_wei = None;
4048            input.max_priority_fee_per_gas_wei = None;
4049            assert!(sign_evm_transaction(&input).is_err());
4050        }
4051    }
4052
4053    #[test]
4054    fn rpc_call_retries_the_next_endpoint_after_transport_failure() {
4055        let (backup, server) = spawn_rpc_server(2);
4056        let result = rpc_call_candidates(
4057            1_337,
4058            &["http://127.0.0.1:1", &backup],
4059            "eth_getBalance",
4060            serde_json::json!(["0x0000000000000000000000000000000000000001", "latest"]),
4061        )
4062        .unwrap();
4063        assert_eq!(result, serde_json::json!("0x2a"));
4064        server.join().unwrap();
4065    }
4066
4067    fn legacy_private_key_keystore(password: &str) -> String {
4068        let signing_key = signing_key_from_hex(DEV_PRIVATE_KEY).unwrap();
4069        let address = address_from_signing_key(&signing_key);
4070        let mut salt = [0u8; KEYSTORE_SALT_BYTES];
4071        let mut rng = AeadOsRng;
4072        aes_gcm::aead::rand_core::RngCore::fill_bytes(&mut rng, &mut salt);
4073        let nonce = Aes256Gcm::generate_nonce(&mut rng);
4074        let key = derive_key(password, &salt).unwrap();
4075        let cipher = Aes256Gcm::new_from_slice(key.as_slice()).unwrap();
4076        let private_key = signing_key.to_bytes();
4077        let ciphertext = cipher
4078            .encrypt(
4079                &nonce,
4080                Payload {
4081                    msg: private_key.as_slice(),
4082                    aad: &keystore_aad_v1(&address),
4083                },
4084            )
4085            .unwrap();
4086        serde_json::json!({
4087            "version": LEGACY_KEYSTORE_VERSION,
4088            "wallet_family": "evm",
4089            "address": address,
4090            "derivation_path": null,
4091            "crypto": {
4092                "kdf": KEYSTORE_KDF,
4093                "kdf_params": {
4094                    "memory_kib": ARGON2_MEMORY_KIB,
4095                    "iterations": ARGON2_ITERATIONS,
4096                    "parallelism": ARGON2_PARALLELISM,
4097                    "salt": BASE64.encode(salt),
4098                },
4099                "cipher": KEYSTORE_CIPHER,
4100                "nonce": BASE64.encode(nonce),
4101                "ciphertext": BASE64.encode(ciphertext),
4102            },
4103            "metadata": { "wallet_name": "Legacy EVM" },
4104        })
4105        .to_string()
4106    }
4107
4108    #[test]
4109    fn adapter_rejects_non_evm_derivation_paths() {
4110        let adapter = EvmChainAdapter::new(builtin_chains()[0].clone()).unwrap();
4111        assert!(adapter
4112            .derive_account(DEV_MNEMONIC, Some("m/44'/195'/0'/0/0"))
4113            .is_err());
4114        assert!(adapter
4115            .derive_account(DEV_MNEMONIC, Some("m/44'/60'/0'/2/0"))
4116            .is_err());
4117        assert!(adapter
4118            .derive_account(DEV_MNEMONIC, Some("m/44'/60'/7'/1/42"))
4119            .is_ok());
4120        assert!(matches!(
4121            adapter.derive_account(DEV_MNEMONIC, Some(&"m".repeat(257))),
4122            Err(ChainError::InvalidDerivationPath(_))
4123        ));
4124        assert!(adapter
4125            .derive_account(&"word ".repeat(1_025), None)
4126            .is_err());
4127    }
4128
4129    #[test]
4130    fn adapters_only_advertise_history_when_the_backend_supports_it() {
4131        let mut chains = builtin_chains().into_iter();
4132        let ethereum =
4133            EvmChainAdapter::new_with_history_api_key(chains.next().unwrap(), Some("test-api-key"))
4134                .unwrap();
4135        let zksync = EvmChainAdapter::new_with_history_api_key(
4136            chains
4137                .find(|chain| chain.chain_id == 324)
4138                .expect("zkSync must remain in the built-in catalog"),
4139            Some("test-api-key"),
4140        )
4141        .unwrap();
4142
4143        assert!(ethereum.descriptor().supports(capabilities::HISTORY));
4144        assert!(!zksync.descriptor().supports(capabilities::HISTORY));
4145
4146        let unsupported = EvmChainAdapter::new_with_history_api_key(
4147            chain(
4148                999_999,
4149                "Unknown EVM",
4150                "ETH",
4151                "https://rpc.example.com",
4152                Some("https://explorer.example.com"),
4153                true,
4154            ),
4155            Some("test-api-key"),
4156        )
4157        .unwrap();
4158        assert!(!unsupported.descriptor().supports(capabilities::HISTORY));
4159
4160        let without_key =
4161            EvmChainAdapter::new_with_history_api_key(builtin_chains()[0].clone(), None).unwrap();
4162        assert!(!without_key.descriptor().supports(capabilities::HISTORY));
4163    }
4164
4165    #[test]
4166    fn rpc_chain_id_must_match_the_configured_chain() {
4167        assert!(validate_reported_chain_id(1, &serde_json::json!("0x1")).is_ok());
4168        assert!(matches!(
4169            validate_reported_chain_id(1, &serde_json::json!("0xa")),
4170            Err(EvmServiceError::InvalidChainId)
4171        ));
4172        assert!(matches!(
4173            validate_reported_chain_id(1, &serde_json::json!(1)),
4174            Err(EvmServiceError::InvalidChainId)
4175        ));
4176    }
4177
4178    #[test]
4179    fn intrinsic_gas_fallback_only_accepts_plain_eoa_transfers() {
4180        let eoa = "0xcf310a2ada52ba0d93feb888239233447e864b8d";
4181        assert!(can_use_intrinsic_gas_fallback(eoa, "0x", "0x"));
4182        assert!(!can_use_intrinsic_gas_fallback(eoa, "0xa9059cbb", "0x"));
4183        assert!(!can_use_intrinsic_gas_fallback(eoa, "0x", "0x60016000"));
4184        assert!(!can_use_intrinsic_gas_fallback(
4185            "0x0000000000000000000000000000000000000001",
4186            "0x",
4187            "0x",
4188        ));
4189        assert!(!can_use_intrinsic_gas_fallback(
4190            "not-an-address",
4191            "0x",
4192            "0x"
4193        ));
4194    }
4195
4196    #[test]
4197    fn stale_payment_nonce_is_rejected_before_signing() {
4198        assert!(ensure_preview_nonce_is_current("42", "00042").is_ok());
4199        let error = ensure_preview_nonce_is_current("42", "43").unwrap_err();
4200        assert!(
4201            matches!(error, EvmServiceError::InvalidInput(message) if message.contains("nonce changed"))
4202        );
4203    }
4204
4205    #[test]
4206    fn hashes_the_exact_signed_transaction_bytes() {
4207        assert_eq!(
4208            raw_transaction_hash("0x02c0").unwrap(),
4209            "0xcace66b6a82a5dc496a5b21a4032eb58baf223ea6f142a01593a5d105d5ee150"
4210        );
4211        assert!(raw_transaction_hash("02c0").is_err());
4212        assert!(raw_transaction_hash("0x2").is_err());
4213    }
4214
4215    #[test]
4216    fn chain_configuration_rejects_malformed_or_ambiguous_rpc_urls() {
4217        let mut config = builtin_chains()[0].clone();
4218        for rpc_url in [
4219            "https://",
4220            " https://ethereum-rpc.publicnode.com",
4221            "https://user:secret@example.com",
4222            "https://example.com/#ignored-fragment",
4223            "http://example.com",
4224            "ftp://example.com",
4225        ] {
4226            config.rpc_url = rpc_url.to_string();
4227            assert!(validate_chain(&config).is_err(), "accepted {rpc_url}");
4228        }
4229
4230        config.rpc_url = "http://127.0.0.1:8545".to_string();
4231        assert!(validate_chain(&config).is_ok());
4232        config.rpc_url = "http://[::1]:8545".to_string();
4233        assert!(validate_chain(&config).is_ok());
4234    }
4235
4236    #[test]
4237    fn adapter_preserves_chain_id_errors_and_classifies_other_config_errors() {
4238        let mut config = builtin_chains()[0].clone();
4239        config.chain_id = 0;
4240        assert!(matches!(
4241            EvmChainAdapter::new(config),
4242            Err(ChainError::InvalidChainId(_))
4243        ));
4244
4245        let mut config = builtin_chains()[0].clone();
4246        config.name = " Ethereum ".to_string();
4247        assert!(matches!(
4248            EvmChainAdapter::new(config),
4249            Err(ChainError::InvalidDescriptor { .. })
4250        ));
4251    }
4252
4253    #[test]
4254    fn chain_configuration_rejects_ambiguous_explorer_urls() {
4255        let mut config = builtin_chains()[0].clone();
4256        for explorer_url in [
4257            "http://etherscan.io",
4258            "https://user@etherscan.io",
4259            "https://etherscan.io/address/0x1",
4260            "https://etherscan.io?network=mainnet",
4261            "https://etherscan.io/#mainnet",
4262        ] {
4263            config.explorer_url = Some(explorer_url.to_string());
4264            assert!(validate_chain(&config).is_err(), "accepted {explorer_url}");
4265            assert!(etherscan_chain_id(explorer_url).is_none());
4266        }
4267    }
4268
4269    #[test]
4270    fn invalid_addresses_never_compare_equal() {
4271        assert!(!address_eq("not-an-address", "also-invalid"));
4272    }
4273
4274    #[test]
4275    fn mixed_case_addresses_require_a_valid_eip55_checksum() {
4276        let checksummed = "0x5AEDA56215b167893e80B4fE645BA6d5Bab767DE";
4277        assert_eq!(
4278            normalize_address(checksummed, "address").unwrap(),
4279            checksummed.to_ascii_lowercase()
4280        );
4281        assert!(
4282            normalize_address("0x5AEDA56215b167893e80B4fE645BA6d5Bab767De", "address").is_err()
4283        );
4284        assert!(
4285            normalize_address("0X5AEDA56215b167893e80B4fE645BA6d5Bab767DE", "address").is_err()
4286        );
4287    }
4288
4289    #[test]
4290    fn includes_robinhood_chain_mainnet() {
4291        let robinhood = builtin_chains()
4292            .into_iter()
4293            .find(|chain| chain.chain_id == 4663)
4294            .expect("Robinhood Chain mainnet should be built in");
4295        assert_eq!(robinhood.name, "Robinhood Chain");
4296        assert_eq!(robinhood.native_symbol, "ETH");
4297        assert!(!robinhood.testnet);
4298    }
4299
4300    #[test]
4301    fn decodes_standard_and_bytes32_erc20_strings() {
4302        let dynamic = concat!(
4303            "0x0000000000000000000000000000000000000000000000000000000000000020",
4304            "0000000000000000000000000000000000000000000000000000000000000003",
4305            "5a5a5a0000000000000000000000000000000000000000000000000000000000"
4306        );
4307        assert_eq!(decode_erc20_string(dynamic).unwrap(), "ZZZ");
4308        assert_eq!(
4309            decode_erc20_string(
4310                "0x5553444700000000000000000000000000000000000000000000000000000000"
4311            )
4312            .unwrap(),
4313            "USDG"
4314        );
4315    }
4316
4317    #[test]
4318    fn rejects_malformed_erc20_dynamic_strings() {
4319        let bad_offset = concat!(
4320            "0x0000000000000000000000000000000000000000000000000000000000000041",
4321            "0000000000000000000000000000000000000000000000000000000000000000",
4322            "0000000000000000000000000000000000000000000000000000000000000000"
4323        );
4324        let out_of_bounds = concat!(
4325            "0x0000000000000000000000000000000000000000000000000000000000000020",
4326            "0000000000000000000000000000000000000000000000000000000000000081",
4327            "0000000000000000000000000000000000000000000000000000000000000000"
4328        );
4329        assert!(decode_erc20_string(bad_offset).is_err());
4330        assert!(decode_erc20_string(out_of_bounds).is_err());
4331    }
4332
4333    #[test]
4334    fn parses_chain_scoped_dexscreener_metadata_and_trusted_logo() {
4335        let body = serde_json::json!({
4336            "pairs": [{
4337                "chainId": "robinhood",
4338                "baseToken": {
4339                    "address": "0x7dbf38976f6D3b9c529e7D9484A71898B409eE6a",
4340                    "name": "ZZZ",
4341                    "symbol": "ZZZ"
4342                },
4343                "quoteToken": {
4344                    "address": "0x0000000000000000000000000000000000000000",
4345                    "name": "Ether",
4346                    "symbol": "ETH"
4347                },
4348                "info": {
4349                    "imageUrl": "https://cdn.dexscreener.com/cms/images/token?width=800"
4350                }
4351            }, {
4352                "chainId": "ethereum",
4353                "baseToken": {
4354                    "address": "0x7dbf38976f6D3b9c529e7D9484A71898B409eE6a",
4355                    "name": "Wrong chain",
4356                    "symbol": "WRONG"
4357                }
4358            }]
4359        });
4360        let parsed =
4361            parse_dexscreener_token_metadata("robinhood", body.to_string().as_bytes()).unwrap();
4362        let token = parsed
4363            .get("0x7dbf38976f6d3b9c529e7d9484a71898b409ee6a")
4364            .unwrap();
4365        assert_eq!(token.name.as_deref(), Some("ZZZ"));
4366        assert_eq!(token.symbol.as_deref(), Some("ZZZ"));
4367        assert_eq!(
4368            token.logo_uri.as_deref(),
4369            Some("https://cdn.dexscreener.com/cms/images/token?width=800")
4370        );
4371        assert!(validate_token_logo_uri("https://evil.example/token.png").is_none());
4372        assert!(validate_token_logo_uri("http://cdn.dexscreener.com/token.png").is_none());
4373    }
4374
4375    #[test]
4376    fn parses_coingecko_token_list_metadata() {
4377        let body = serde_json::json!({
4378            "name": "CoinGecko",
4379            "tokens": [{
4380                "chainId": 4663,
4381                "address": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
4382                "name": "Global Dollar",
4383                "symbol": "USDG",
4384                "decimals": 6,
4385                "logoURI": "https://assets.coingecko.com/coins/images/51281/thumb/usdg.png"
4386            }, {
4387                "chainId": 4663,
4388                "address": "invalid",
4389                "name": "Invalid",
4390                "symbol": "BAD",
4391                "logoURI": "https://evil.example/token.png"
4392            }]
4393        });
4394        let parsed = parse_coingecko_token_metadata(body.to_string().as_bytes()).unwrap();
4395        let token = parsed
4396            .get("0x5fc5360d0400a0fd4f2af552add042d716f1d168")
4397            .unwrap();
4398        assert_eq!(token.name.as_deref(), Some("Global Dollar"));
4399        assert_eq!(token.symbol.as_deref(), Some("USDG"));
4400        assert_eq!(
4401            token.logo_uri.as_deref(),
4402            Some("https://assets.coingecko.com/coins/images/51281/thumb/usdg.png")
4403        );
4404        assert_eq!(parsed.len(), 1);
4405    }
4406
4407    #[test]
4408    fn polygon_networks_use_pol_as_the_native_symbol() {
4409        let chains = builtin_chains();
4410        for chain_id in [137, 80002] {
4411            let polygon = chains
4412                .iter()
4413                .find(|chain| chain.chain_id == chain_id)
4414                .expect("Polygon network should be built in");
4415            assert_eq!(polygon.native_symbol, "POL");
4416        }
4417        let polygon_mainnet = chains
4418            .iter()
4419            .find(|chain| chain.chain_id == 137)
4420            .expect("Polygon mainnet should be built in");
4421        assert_eq!(
4422            polygon_mainnet.rpc_url,
4423            "https://polygon-bor-rpc.publicnode.com"
4424        );
4425    }
4426
4427    #[test]
4428    fn derives_known_evm_address_from_private_key() {
4429        let key = signing_key_from_hex(DEV_PRIVATE_KEY).unwrap();
4430        assert_eq!(
4431            address_from_signing_key(&key),
4432            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf"
4433        );
4434    }
4435
4436    #[test]
4437    fn encrypts_and_unlocks_evm_keystore() {
4438        let created = import_private_key(EvmImportPrivateKeyRequest {
4439            name: "EVM".to_string(),
4440            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4441            password: "strong-password".to_string(),
4442        })
4443        .unwrap();
4444        let document: serde_json::Value = serde_json::from_str(&created.keystore_json).unwrap();
4445        assert_eq!(document.get("secret_type").unwrap(), "private_key");
4446        let unlocked = unlock_wallet(EvmUnlockWalletRequest {
4447            keystore_json: created.keystore_json,
4448            password: "strong-password".to_string(),
4449        })
4450        .unwrap();
4451        assert_eq!(
4452            unlocked.address,
4453            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf"
4454        );
4455    }
4456
4457    #[test]
4458    fn unlocks_nested_evm_keystore_from_universal_document() {
4459        let created = import_private_key(EvmImportPrivateKeyRequest {
4460            name: "EVM".to_string(),
4461            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4462            password: "strong-password".to_string(),
4463        })
4464        .unwrap();
4465        let universal = serde_json::json!({
4466            "version": 3,
4467            "secret_type": "mnemonic",
4468            "encryption_type": "password_only",
4469            "metadata": {
4470                "evm_keystore_json": created.keystore_json,
4471                "evm_address": created.wallet.address,
4472            }
4473        });
4474        let (wallet, sk) =
4475            unlock_private_key_from_document(&universal.to_string(), "strong-password").unwrap();
4476        assert_eq!(wallet.address, created.wallet.address);
4477        assert_eq!(sk.len(), 32);
4478    }
4479
4480    #[test]
4481    fn mnemonic_keystore_restores_the_derived_account() {
4482        const MNEMONIC: &str = "test test test test test test test test test test test junk";
4483        let created = import_mnemonic(EvmImportMnemonicRequest {
4484            name: "Mnemonic EVM".to_string(),
4485            mnemonic: MNEMONIC.to_string(),
4486            derivation_path: None,
4487            password: "strong-password".to_string(),
4488        })
4489        .unwrap();
4490        assert!(!created.keystore_json.contains(MNEMONIC));
4491        let document: serde_json::Value = serde_json::from_str(&created.keystore_json).unwrap();
4492        assert_eq!(document.get("version").unwrap(), KEYSTORE_VERSION);
4493        assert_eq!(document.get("secret_type").unwrap(), "mnemonic");
4494
4495        let restored = import_keystore(EvmImportKeystoreRequest {
4496            name: "Restored EVM".to_string(),
4497            keystore_json: created.keystore_json,
4498            password: "strong-password".to_string(),
4499        })
4500        .unwrap();
4501        assert_eq!(restored.wallet.address, created.wallet.address);
4502        assert_eq!(
4503            restored.wallet.derivation_path.as_deref(),
4504            Some(DEFAULT_EVM_DERIVATION_PATH)
4505        );
4506        let restored_document: serde_json::Value =
4507            serde_json::from_str(&restored.keystore_json).unwrap();
4508        assert_eq!(restored_document.get("secret_type").unwrap(), "mnemonic");
4509    }
4510
4511    #[test]
4512    fn mnemonic_keystore_rejects_authenticated_metadata_tampering() {
4513        const MNEMONIC: &str = "test test test test test test test test test test test junk";
4514        let created = import_mnemonic(EvmImportMnemonicRequest {
4515            name: "Mnemonic EVM".to_string(),
4516            mnemonic: MNEMONIC.to_string(),
4517            derivation_path: None,
4518            password: "strong-password".to_string(),
4519        })
4520        .unwrap();
4521        let mut document: serde_json::Value = serde_json::from_str(&created.keystore_json).unwrap();
4522
4523        document["derivation_path"] = serde_json::Value::String("m/44'/60'/0'/0/1".to_string());
4524        assert!(export_private_key(EvmExportPrivateKeyRequest {
4525            keystore_json: document.to_string(),
4526            password: "strong-password".to_string(),
4527        })
4528        .is_err());
4529
4530        let mut document: serde_json::Value = serde_json::from_str(&created.keystore_json).unwrap();
4531        document["secret_type"] = serde_json::Value::String("private_key".to_string());
4532        assert!(unlock_wallet(EvmUnlockWalletRequest {
4533            keystore_json: document.to_string(),
4534            password: "strong-password".to_string(),
4535        })
4536        .is_err());
4537    }
4538
4539    #[test]
4540    fn private_key_keystore_without_secret_type_remains_compatible() {
4541        let unlocked = unlock_wallet(EvmUnlockWalletRequest {
4542            keystore_json: legacy_private_key_keystore("strong-password"),
4543            password: "strong-password".to_string(),
4544        })
4545        .unwrap();
4546        assert_eq!(
4547            unlocked.address,
4548            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf"
4549        );
4550    }
4551
4552    #[test]
4553    fn legacy_keystore_rejects_mnemonic_type_confusion() {
4554        let mut document: serde_json::Value =
4555            serde_json::from_str(&legacy_private_key_keystore("strong-password")).unwrap();
4556        document["secret_type"] = serde_json::Value::String("mnemonic".to_string());
4557        document["derivation_path"] =
4558            serde_json::Value::String(DEFAULT_EVM_DERIVATION_PATH.to_string());
4559
4560        assert!(matches!(
4561            decrypt_keystore(&document.to_string(), "strong-password"),
4562            Err(EvmServiceError::InvalidInput(message))
4563                if message == "Legacy EVM keystore must contain a private key"
4564        ));
4565    }
4566
4567    #[test]
4568    fn rejects_oversized_keystore_passwords_before_kdf() {
4569        let created = import_private_key(EvmImportPrivateKeyRequest {
4570            name: "EVM".to_string(),
4571            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4572            password: "strong-password".to_string(),
4573        })
4574        .unwrap();
4575        let oversized = "x".repeat(MAX_KEYSTORE_PASSWORD_BYTES + 1);
4576
4577        assert!(matches!(
4578            decrypt_keystore(&created.keystore_json, &oversized),
4579            Err(EvmServiceError::InvalidInput(message))
4580                if message == "EVM keystore password is too long"
4581        ));
4582        assert!(matches!(
4583            import_private_key(EvmImportPrivateKeyRequest {
4584                name: "EVM".to_string(),
4585                private_key_hex: DEV_PRIVATE_KEY.to_string(),
4586                password: oversized,
4587            }),
4588            Err(EvmServiceError::InvalidInput(message))
4589                if message == "EVM keystore password is too long"
4590        ));
4591    }
4592
4593    #[test]
4594    fn rejects_oversized_keystore_json_before_parsing() {
4595        let oversized = " ".repeat(MAX_KEYSTORE_JSON_BYTES + 1);
4596        assert!(matches!(
4597            decrypt_keystore(&oversized, "strong-password"),
4598            Err(EvmServiceError::InvalidInput(message))
4599                if message == "EVM keystore JSON is too large"
4600        ));
4601    }
4602
4603    #[test]
4604    fn rejects_unapproved_keystore_kdf_parameters() {
4605        let created = import_private_key(EvmImportPrivateKeyRequest {
4606            name: "EVM".to_string(),
4607            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4608            password: "strong-password".to_string(),
4609        })
4610        .unwrap();
4611
4612        for (field, value) in [
4613            ("memory_kib", ARGON2_MEMORY_KIB + 1),
4614            ("iterations", ARGON2_ITERATIONS + 1),
4615            ("parallelism", ARGON2_PARALLELISM + 1),
4616        ] {
4617            let mut document: serde_json::Value =
4618                serde_json::from_str(&created.keystore_json).unwrap();
4619            document["crypto"]["kdf_params"][field] = serde_json::json!(value);
4620            assert!(matches!(
4621                decrypt_keystore(&document.to_string(), "strong-password"),
4622                Err(EvmServiceError::InvalidInput(message))
4623                    if message == "Unsupported EVM keystore KDF parameters"
4624            ));
4625        }
4626    }
4627
4628    #[test]
4629    fn rejects_invalid_keystore_ciphertext_lengths() {
4630        let created = import_private_key(EvmImportPrivateKeyRequest {
4631            name: "EVM".to_string(),
4632            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4633            password: "strong-password".to_string(),
4634        })
4635        .unwrap();
4636
4637        for ciphertext in [
4638            vec![0; KEYSTORE_TAG_BYTES],
4639            vec![0; MAX_KEYSTORE_SECRET_BYTES + KEYSTORE_TAG_BYTES + 1],
4640        ] {
4641            let mut document: serde_json::Value =
4642                serde_json::from_str(&created.keystore_json).unwrap();
4643            document["crypto"]["ciphertext"] = serde_json::Value::String(BASE64.encode(ciphertext));
4644            assert!(matches!(
4645                decrypt_keystore(&document.to_string(), "strong-password"),
4646                Err(EvmServiceError::InvalidInput(message))
4647                    if message == "Keystore ciphertext length is invalid"
4648            ));
4649        }
4650    }
4651
4652    #[test]
4653    fn unlock_private_key_returns_zeroizing_material_for_the_same_address() {
4654        let created = import_private_key(EvmImportPrivateKeyRequest {
4655            name: "EVM".to_string(),
4656            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4657            password: "strong-password".to_string(),
4658        })
4659        .unwrap();
4660        let expected_address = created.wallet.address.clone();
4661        let (wallet, private_key) = unlock_private_key(EvmUnlockWalletRequest {
4662            keystore_json: created.keystore_json,
4663            password: "strong-password".to_string(),
4664        })
4665        .unwrap();
4666
4667        assert_eq!(wallet.address, expected_address);
4668        assert_eq!(
4669            private_key.as_slice(),
4670            &hex::decode(DEV_PRIVATE_KEY.trim_start_matches("0x")).unwrap()
4671        );
4672    }
4673
4674    #[test]
4675    fn builds_erc20_transfer_calldata() {
4676        let calldata = erc20_transfer_calldata(
4677            "0x000000000000000000000000000000000000dead",
4678            "1000000000000000000",
4679        )
4680        .unwrap();
4681        assert!(calldata.starts_with("0xa9059cbb"));
4682        assert!(
4683            calldata.contains("000000000000000000000000000000000000000000000000000000000000dead")
4684        );
4685    }
4686
4687    #[test]
4688    fn rejects_wrong_evm_password() {
4689        let created = import_private_key(EvmImportPrivateKeyRequest {
4690            name: "EVM".to_string(),
4691            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4692            password: "strong-password".to_string(),
4693        })
4694        .unwrap();
4695        assert!(matches!(
4696            unlock_wallet(EvmUnlockWalletRequest {
4697                keystore_json: created.keystore_json,
4698                password: "wrong-password".to_string(),
4699            }),
4700            Err(EvmServiceError::WrongPassword)
4701        ));
4702    }
4703
4704    #[test]
4705    fn hashes_eip712_mail_example() {
4706        let payload = serde_json::json!({
4707            "types": {
4708                "EIP712Domain": [
4709                    {"name": "name", "type": "string"},
4710                    {"name": "version", "type": "string"},
4711                    {"name": "chainId", "type": "uint256"},
4712                    {"name": "verifyingContract", "type": "address"}
4713                ],
4714                "Person": [
4715                    {"name": "name", "type": "string"},
4716                    {"name": "wallet", "type": "address"}
4717                ],
4718                "Mail": [
4719                    {"name": "from", "type": "Person"},
4720                    {"name": "to", "type": "Person"},
4721                    {"name": "contents", "type": "string"}
4722                ]
4723            },
4724            "primaryType": "Mail",
4725            "domain": {
4726                "name": "Ether Mail",
4727                "version": "1",
4728                "chainId": 1,
4729                "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"
4730            },
4731            "message": {
4732                "from": {
4733                    "name": "Cow",
4734                    "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"
4735                },
4736                "to": {
4737                    "name": "Bob",
4738                    "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"
4739                },
4740                "contents": "Hello, Bob!"
4741            }
4742        });
4743        let digest = typed_data_digest(&payload.to_string()).unwrap();
4744        assert_eq!(
4745            hex::encode(digest),
4746            "be609aee343fb3c4b28e1df9e632fca64fcfaede20f02e86244efddf30957bd2"
4747        );
4748    }
4749
4750    #[test]
4751    fn signs_standard_eip1559_transaction() {
4752        let key = signing_key_from_hex(DEV_PRIVATE_KEY).unwrap();
4753        let raw = sign_evm_transaction(&EvmTxSigningInput {
4754            signing_key: &key,
4755            chain_id: 11155111,
4756            nonce: "0",
4757            gas_limit: "21000",
4758            to: "0x000000000000000000000000000000000000dead",
4759            value: "1",
4760            data: "0x",
4761            gas_price_wei: "1000000000",
4762            max_fee_per_gas_wei: Some("2000000000"),
4763            max_priority_fee_per_gas_wei: Some("1000000000"),
4764        })
4765        .unwrap();
4766        assert_eq!(
4767            raw,
4768            concat!(
4769                "0x02f86d83aa36a780843b9aca00847735940082520894000000000000000000000000000000000000dead0180c080",
4770                "a02f13b8d85ea9156a13b3e264d15745152ab8dd2ffd713248b9a96eab02356dde",
4771                "a0403ee61e225cb0e5f0d0c44d91f3324be30ea84fb92d3d3b587aa70994ca514e"
4772            )
4773        );
4774    }
4775
4776    #[test]
4777    fn payment_submit_rejects_keystore_for_different_preview_wallet() {
4778        let created = import_private_key(EvmImportPrivateKeyRequest {
4779            name: "EVM".to_string(),
4780            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4781            password: "strong-password".to_string(),
4782        })
4783        .unwrap();
4784        let chain = chain(
4785            11155111,
4786            "Sepolia",
4787            "ETH",
4788            "http://127.0.0.1:8545",
4789            None,
4790            true,
4791        );
4792        let wallet_address = "0x000000000000000000000000000000000000dead";
4793        let recipient = "0x000000000000000000000000000000000000beef";
4794        let preview_id = payment_preview_id(&PaymentPreviewIdInput {
4795            chain: &chain,
4796            wallet_address,
4797            recipient,
4798            token_contract: None,
4799            amount_wei_or_units: "1",
4800            gas_limit: "21000",
4801            gas_price_wei: "1000000000",
4802            max_fee_per_gas_wei: None,
4803            max_priority_fee_per_gas_wei: None,
4804            nonce: "0",
4805        });
4806
4807        let error = submit_payment(EvmPaymentSubmitRequest {
4808            preview_id,
4809            approved: true,
4810            chain,
4811            wallet_address: wallet_address.to_string(),
4812            keystore_json: created.keystore_json,
4813            password: "strong-password".to_string(),
4814            recipient: recipient.to_string(),
4815            amount_wei_or_units: "1".to_string(),
4816            token_contract: None,
4817            gas_limit: Some("21000".to_string()),
4818            gas_price_wei: Some("1000000000".to_string()),
4819            max_fee_per_gas_wei: None,
4820            max_priority_fee_per_gas_wei: None,
4821            nonce: Some("0".to_string()),
4822        })
4823        .unwrap_err();
4824
4825        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
4826        assert!(!error.to_string().contains("strong-password"));
4827        assert!(!error.to_string().contains(DEV_PRIVATE_KEY));
4828    }
4829
4830    #[test]
4831    fn payment_submit_rejects_mismatched_preview_id_before_sending() {
4832        let created = import_private_key(EvmImportPrivateKeyRequest {
4833            name: "EVM".to_string(),
4834            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4835            password: "strong-password".to_string(),
4836        })
4837        .unwrap();
4838        let chain = chain(
4839            11155111,
4840            "Sepolia",
4841            "ETH",
4842            "http://127.0.0.1:8545",
4843            None,
4844            true,
4845        );
4846
4847        let error = submit_payment(EvmPaymentSubmitRequest {
4848            preview_id: "evm-payment:stale".to_string(),
4849            approved: true,
4850            chain,
4851            wallet_address: created.wallet.address,
4852            keystore_json: created.keystore_json,
4853            password: "strong-password".to_string(),
4854            recipient: "0x000000000000000000000000000000000000beef".to_string(),
4855            amount_wei_or_units: "1".to_string(),
4856            token_contract: None,
4857            gas_limit: Some("21000".to_string()),
4858            gas_price_wei: Some("1000000000".to_string()),
4859            max_fee_per_gas_wei: None,
4860            max_priority_fee_per_gas_wei: None,
4861            nonce: Some("0".to_string()),
4862        })
4863        .unwrap_err();
4864
4865        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
4866        assert!(error.to_string().contains("stale or mismatched"));
4867    }
4868
4869    #[test]
4870    fn payment_submit_rejects_mismatched_preview_id_before_decrypting() {
4871        let created = import_private_key(EvmImportPrivateKeyRequest {
4872            name: "EVM".to_string(),
4873            private_key_hex: DEV_PRIVATE_KEY.to_string(),
4874            password: "strong-password".to_string(),
4875        })
4876        .unwrap();
4877        let chain = chain(
4878            11155111,
4879            "Sepolia",
4880            "ETH",
4881            "http://127.0.0.1:8545",
4882            None,
4883            true,
4884        );
4885
4886        let error = submit_payment(EvmPaymentSubmitRequest {
4887            preview_id: "evm-payment:stale".to_string(),
4888            approved: true,
4889            chain,
4890            wallet_address: created.wallet.address,
4891            keystore_json: created.keystore_json,
4892            password: "wrong-password".to_string(),
4893            recipient: "0x000000000000000000000000000000000000beef".to_string(),
4894            amount_wei_or_units: "1".to_string(),
4895            token_contract: None,
4896            gas_limit: Some("21000".to_string()),
4897            gas_price_wei: Some("1000000000".to_string()),
4898            max_fee_per_gas_wei: None,
4899            max_priority_fee_per_gas_wei: None,
4900            nonce: Some("0".to_string()),
4901        })
4902        .unwrap_err();
4903
4904        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
4905        assert!(error.to_string().contains("stale or mismatched"));
4906        assert!(!matches!(error, EvmServiceError::WrongPassword));
4907    }
4908
4909    #[test]
4910    fn payment_submit_with_private_key_rejects_a_different_wallet_before_sending() {
4911        let chain = chain(
4912            11155111,
4913            "Sepolia",
4914            "ETH",
4915            "http://127.0.0.1:8545",
4916            None,
4917            true,
4918        );
4919        let wallet_address = "0x000000000000000000000000000000000000dead";
4920        let recipient = "0x000000000000000000000000000000000000beef";
4921        let preview_id = payment_preview_id(&PaymentPreviewIdInput {
4922            chain: &chain,
4923            wallet_address,
4924            recipient,
4925            token_contract: None,
4926            amount_wei_or_units: "1",
4927            gas_limit: "21000",
4928            gas_price_wei: "1000000000",
4929            max_fee_per_gas_wei: None,
4930            max_priority_fee_per_gas_wei: None,
4931            nonce: "0",
4932        });
4933        let request = EvmPaymentSubmitRequest {
4934            preview_id,
4935            approved: true,
4936            chain,
4937            wallet_address: wallet_address.to_string(),
4938            keystore_json: String::new(),
4939            password: String::new(),
4940            recipient: recipient.to_string(),
4941            amount_wei_or_units: "1".to_string(),
4942            token_contract: None,
4943            gas_limit: Some("21000".to_string()),
4944            gas_price_wei: Some("1000000000".to_string()),
4945            max_fee_per_gas_wei: None,
4946            max_priority_fee_per_gas_wei: None,
4947            nonce: Some("0".to_string()),
4948        };
4949        let private_key = hex::decode(DEV_PRIVATE_KEY.trim_start_matches("0x")).unwrap();
4950
4951        let error = submit_payment_with_private_key(request, &private_key).unwrap_err();
4952        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
4953        assert!(error.to_string().contains("does not match preview"));
4954    }
4955
4956    #[test]
4957    fn private_key_loader_is_not_called_for_a_stale_payment_preview() {
4958        use std::cell::Cell;
4959
4960        let chain = chain(
4961            11155111,
4962            "Sepolia",
4963            "ETH",
4964            "http://127.0.0.1:8545",
4965            None,
4966            true,
4967        );
4968        let loader_called = Cell::new(false);
4969        let error = submit_payment_with_private_key_loader(
4970            EvmPaymentSubmitRequest {
4971                preview_id: "evm-payment:stale".to_string(),
4972                approved: true,
4973                chain,
4974                wallet_address: "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf".to_string(),
4975                keystore_json: String::new(),
4976                password: String::new(),
4977                recipient: "0x000000000000000000000000000000000000beef".to_string(),
4978                amount_wei_or_units: "1".to_string(),
4979                token_contract: None,
4980                gas_limit: Some("21000".to_string()),
4981                gas_price_wei: Some("1000000000".to_string()),
4982                max_fee_per_gas_wei: None,
4983                max_priority_fee_per_gas_wei: None,
4984                nonce: Some("0".to_string()),
4985            },
4986            || {
4987                loader_called.set(true);
4988                Ok(Zeroizing::new(vec![0_u8; PRIVATE_KEY_BYTES]))
4989            },
4990        )
4991        .unwrap_err();
4992
4993        assert!(!loader_called.get());
4994        assert!(error.to_string().contains("stale or mismatched"));
4995    }
4996
4997    #[test]
4998    fn payment_preview_id_uses_normalized_token_contract() {
4999        let chain = chain(
5000            11155111,
5001            "Sepolia",
5002            "ETH",
5003            "http://127.0.0.1:8545",
5004            None,
5005            true,
5006        );
5007        let token = normalize_address(
5008            "0xABCDEFABCDEFABCDEFABCDEFABCDEFABCDEFABCD",
5009            "token contract",
5010        )
5011        .unwrap();
5012        let preview_id = payment_preview_id(&PaymentPreviewIdInput {
5013            chain: &chain,
5014            wallet_address: "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5015            recipient: "0x000000000000000000000000000000000000beef",
5016            token_contract: Some(&token),
5017            amount_wei_or_units: "1",
5018            gas_limit: "65000",
5019            gas_price_wei: "1000000000",
5020            max_fee_per_gas_wei: None,
5021            max_priority_fee_per_gas_wei: None,
5022            nonce: "0",
5023        });
5024        let submit_preview_id = payment_preview_id(&PaymentPreviewIdInput {
5025            chain: &chain,
5026            wallet_address: "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5027            recipient: "0x000000000000000000000000000000000000beef",
5028            token_contract: Some(token.as_str()),
5029            amount_wei_or_units: "1",
5030            gas_limit: "65000",
5031            gas_price_wei: "1000000000",
5032            max_fee_per_gas_wei: None,
5033            max_priority_fee_per_gas_wei: None,
5034            nonce: "0",
5035        });
5036
5037        assert_eq!(preview_id, submit_preview_id);
5038    }
5039
5040    #[test]
5041    fn rpc_hex_quantity_rejects_malformed_values() {
5042        assert_eq!(
5043            rpc_hex_quantity_to_decimal(serde_json::json!("0x2a")).unwrap(),
5044            "42"
5045        );
5046        assert!(matches!(
5047            rpc_hex_quantity_to_decimal(serde_json::json!(0)),
5048            Err(EvmServiceError::RpcUnavailable)
5049        ));
5050        assert!(matches!(
5051            rpc_hex_quantity_to_decimal(serde_json::json!("42")),
5052            Err(EvmServiceError::InvalidInput(_))
5053        ));
5054    }
5055
5056    #[test]
5057    fn dapp_submit_rejects_keystore_for_different_preview_wallet() {
5058        let created = import_private_key(EvmImportPrivateKeyRequest {
5059            name: "EVM".to_string(),
5060            private_key_hex: DEV_PRIVATE_KEY.to_string(),
5061            password: "strong-password".to_string(),
5062        })
5063        .unwrap();
5064        let chain = chain(
5065            11155111,
5066            "Sepolia",
5067            "ETH",
5068            "http://127.0.0.1:8545",
5069            None,
5070            true,
5071        );
5072        let wallet_address = "0x000000000000000000000000000000000000dead";
5073        let payload_json = serde_json::json!(["hello"]).to_string();
5074        let preview_id = dapp_sign_preview_id(&DappSignPreviewIdInput {
5075            chain: &chain,
5076            wallet_address,
5077            app_name: "Test dApp",
5078            app_url: "https://example.com",
5079            method: "personal_sign",
5080            payload_json: &payload_json,
5081        });
5082
5083        let error = submit_dapp_signing(EvmDappSignSubmitRequest {
5084            preview_id,
5085            approved: true,
5086            chain,
5087            wallet_address: wallet_address.to_string(),
5088            app_name: "Test dApp".to_string(),
5089            app_url: "https://example.com".to_string(),
5090            keystore_json: created.keystore_json,
5091            password: "strong-password".to_string(),
5092            method: "personal_sign".to_string(),
5093            payload_json,
5094        })
5095        .unwrap_err();
5096
5097        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
5098        assert!(!error.to_string().contains("strong-password"));
5099        assert!(!error.to_string().contains(DEV_PRIVATE_KEY));
5100    }
5101
5102    #[test]
5103    fn dapp_submit_rejects_mismatched_preview_id_before_signing() {
5104        let created = import_private_key(EvmImportPrivateKeyRequest {
5105            name: "EVM".to_string(),
5106            private_key_hex: DEV_PRIVATE_KEY.to_string(),
5107            password: "strong-password".to_string(),
5108        })
5109        .unwrap();
5110        let chain = chain(
5111            11155111,
5112            "Sepolia",
5113            "ETH",
5114            "http://127.0.0.1:8545",
5115            None,
5116            true,
5117        );
5118
5119        let error = submit_dapp_signing(EvmDappSignSubmitRequest {
5120            preview_id: "evm-dapp:stale".to_string(),
5121            approved: true,
5122            chain,
5123            wallet_address: created.wallet.address,
5124            app_name: "Test dApp".to_string(),
5125            app_url: "https://example.com".to_string(),
5126            keystore_json: created.keystore_json,
5127            password: "strong-password".to_string(),
5128            method: "personal_sign".to_string(),
5129            payload_json: serde_json::json!(["hello"]).to_string(),
5130        })
5131        .unwrap_err();
5132
5133        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
5134        assert!(error.to_string().contains("stale or mismatched"));
5135        assert!(!error.to_string().contains("strong-password"));
5136    }
5137
5138    #[test]
5139    fn dapp_submit_rejects_mismatched_preview_id_before_decrypting() {
5140        let created = import_private_key(EvmImportPrivateKeyRequest {
5141            name: "EVM".to_string(),
5142            private_key_hex: DEV_PRIVATE_KEY.to_string(),
5143            password: "strong-password".to_string(),
5144        })
5145        .unwrap();
5146        let chain = chain(
5147            11155111,
5148            "Sepolia",
5149            "ETH",
5150            "http://127.0.0.1:8545",
5151            None,
5152            true,
5153        );
5154
5155        let error = submit_dapp_signing(EvmDappSignSubmitRequest {
5156            preview_id: "evm-dapp:stale".to_string(),
5157            approved: true,
5158            chain,
5159            wallet_address: created.wallet.address,
5160            app_name: "Test dApp".to_string(),
5161            app_url: "https://example.com".to_string(),
5162            keystore_json: created.keystore_json,
5163            password: "wrong-password".to_string(),
5164            method: "personal_sign".to_string(),
5165            payload_json: serde_json::json!(["hello"]).to_string(),
5166        })
5167        .unwrap_err();
5168
5169        assert!(matches!(error, EvmServiceError::InvalidInput(_)));
5170        assert!(error.to_string().contains("stale or mismatched"));
5171        assert!(!matches!(error, EvmServiceError::WrongPassword));
5172    }
5173
5174    #[test]
5175    fn dapp_submit_signs_with_in_memory_private_key() {
5176        let chain = chain(
5177            11155111,
5178            "Sepolia",
5179            "ETH",
5180            "http://127.0.0.1:8545",
5181            None,
5182            true,
5183        );
5184        let wallet_address = "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf";
5185        let payload_json = serde_json::json!({ "message": "hello" }).to_string();
5186        let preview_id = dapp_sign_preview_id(&DappSignPreviewIdInput {
5187            chain: &chain,
5188            wallet_address,
5189            app_name: "Test dApp",
5190            app_url: "https://example.com",
5191            method: "personal_sign",
5192            payload_json: &payload_json,
5193        });
5194        let private_key = hex::decode(DEV_PRIVATE_KEY.trim_start_matches("0x")).unwrap();
5195        let result = submit_dapp_signing_with_private_key(
5196            EvmDappSignSubmitRequest {
5197                preview_id,
5198                approved: true,
5199                chain,
5200                wallet_address: wallet_address.to_string(),
5201                app_name: "Test dApp".to_string(),
5202                app_url: "https://example.com".to_string(),
5203                keystore_json: String::new(),
5204                password: String::new(),
5205                method: "personal_sign".to_string(),
5206                payload_json,
5207            },
5208            &private_key,
5209        )
5210        .unwrap();
5211
5212        assert_eq!(result.status, "signed");
5213        assert!(result
5214            .signature
5215            .as_deref()
5216            .is_some_and(|value| value.starts_with("0x")));
5217    }
5218
5219    #[test]
5220    fn dapp_message_payload_decodes_hex_and_binds_the_selected_account() {
5221        let wallet_address = "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf";
5222        let payload = serde_json::json!({
5223            "params": ["0x68656c6c6f", wallet_address]
5224        })
5225        .to_string();
5226        assert_eq!(
5227            evm_message_from_payload(&payload, wallet_address).unwrap(),
5228            b"hello"
5229        );
5230
5231        let mismatched = serde_json::json!({
5232            "params": [
5233                "0x000000000000000000000000000000000000dead",
5234                "0x68656c6c6f"
5235            ]
5236        })
5237        .to_string();
5238        let error = evm_message_from_payload(&mismatched, wallet_address).unwrap_err();
5239        assert!(error.to_string().contains("does not match"));
5240    }
5241
5242    #[test]
5243    fn parses_dapp_transaction_payload() {
5244        let chain = chain(
5245            11155111,
5246            "Sepolia",
5247            "ETH",
5248            "http://127.0.0.1:8545",
5249            None,
5250            true,
5251        );
5252        let payload = serde_json::json!({
5253            "method": "eth_signTransaction",
5254            "params": [{
5255                "from": "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5256                "to": "0x000000000000000000000000000000000000dead",
5257                "value": "0x1",
5258                "gas": "0x5208",
5259                "gasPrice": "0x3b9aca00",
5260                "nonce": "0x0"
5261            }]
5262        });
5263        let tx = parse_dapp_transaction(
5264            &chain,
5265            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5266            &payload.to_string(),
5267        )
5268        .unwrap();
5269        assert_eq!(tx.value, "1");
5270        assert_eq!(tx.gas_limit, "21000");
5271        assert_eq!(tx.gas_price_wei, "1000000000");
5272    }
5273
5274    #[test]
5275    fn derives_known_etherscan_api_urls() {
5276        let sepolia_chain = builtin_chains()
5277            .into_iter()
5278            .find(|chain| chain.chain_id == 11_155_111)
5279            .unwrap();
5280        let sepolia = etherscan_compatible_api_url(
5281            &sepolia_chain,
5282            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5283            "test-api-key",
5284        )
5285        .unwrap();
5286        assert!(sepolia.starts_with("https://api.etherscan.io/v2/api?chainid=11155111&"));
5287        assert!(sepolia.ends_with("apikey=test-api-key"));
5288
5289        let optimism_chain = builtin_chains()
5290            .into_iter()
5291            .find(|chain| chain.chain_id == 10)
5292            .unwrap();
5293        let optimism = etherscan_compatible_api_url(
5294            &optimism_chain,
5295            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5296            "test-api-key",
5297        )
5298        .unwrap();
5299        assert!(optimism.contains("chainid=10"));
5300
5301        let mut mismatched = builtin_chains()[0].clone();
5302        mismatched.explorer_url = Some("https://bscscan.com".to_string());
5303        assert!(etherscan_compatible_api_url(
5304            &mismatched,
5305            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5306            "test-api-key",
5307        )
5308        .is_err());
5309        mismatched.explorer_url = Some("http://etherscan.io".to_string());
5310        assert!(etherscan_compatible_api_url(
5311            &mismatched,
5312            "0x7e5f4552091a69125d5dfcb7b8c2659029395bdf",
5313            "test-api-key",
5314        )
5315        .is_err());
5316    }
5317
5318    #[test]
5319    fn parses_etherscan_compatible_history() {
5320        let body = serde_json::json!({
5321            "status": "1",
5322            "message": "OK",
5323            "result": [{
5324                "hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
5325                "blockNumber": "123456",
5326                "txreceipt_status": "1"
5327            }, {
5328                "hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
5329                "blockNumber": "123455",
5330                "txreceipt_status": "0"
5331            }]
5332        });
5333        let entries = parse_etherscan_history_response(&body.to_string()).unwrap();
5334        assert_eq!(entries.len(), 2);
5335        assert_eq!(entries[0].block_number, Some(123456));
5336        assert_eq!(entries[0].status, "confirmed");
5337        assert_eq!(entries[1].status, "failed");
5338    }
5339
5340    #[test]
5341    fn parses_empty_etherscan_history_as_ok() {
5342        let body = serde_json::json!({
5343            "status": "0",
5344            "message": "No transactions found",
5345            "result": "No transactions found"
5346        });
5347        let entries = parse_etherscan_history_response(&body.to_string()).unwrap();
5348        assert!(entries.is_empty());
5349    }
5350
5351    #[test]
5352    fn rejects_unsuccessful_or_malformed_etherscan_history() {
5353        let unsuccessful = serde_json::json!({
5354            "status": "0",
5355            "message": "NOTOK",
5356            "result": [],
5357        });
5358        assert!(matches!(
5359            parse_etherscan_history_response(&unsuccessful.to_string()),
5360            Err(EvmServiceError::HistoryUnavailable)
5361        ));
5362
5363        let malformed = serde_json::json!({
5364            "status": "1",
5365            "message": "OK",
5366            "result": [{ "hash": "not-a-transaction-hash", "blockNumber": "1" }],
5367        });
5368        assert!(matches!(
5369            parse_etherscan_history_response(&malformed.to_string()),
5370            Err(EvmServiceError::HistoryUnavailable)
5371        ));
5372    }
5373
5374    #[test]
5375    fn bounds_etherscan_history_response_bodies() {
5376        let oversized = std::io::Cursor::new(vec![b'x'; MAX_ETHERSCAN_RESPONSE_BYTES + 1]);
5377        assert!(matches!(
5378            read_etherscan_response(oversized),
5379            Err(EvmServiceError::RpcUnavailable)
5380        ));
5381    }
5382}