feat(anvil): support celo transfer precompile (#11491)

* anvil: Add --celo flag

* Implement Celo transfer precompile

* Fix link in docs

* install celo precompile for call evn

---------

Co-authored-by: Karl Bartel <[email protected]>

Author: mattsse

crates/anvil/src/cmd.rs

@@ -279,6 +279,7 @@ impl NodeArgs {
             .with_max_persisted_states(self.max_persisted_states)
             .with_optimism(self.evm.optimism)
             .with_odyssey(self.evm.odyssey)
+            .with_celo(self.evm.celo)
             .with_disable_default_create2_deployer(self.evm.disable_default_create2_deployer)
             .with_disable_pool_balance_checks(self.evm.disable_pool_balance_checks)
             .with_slots_in_an_epoch(self.slots_in_an_epoch)
@@ -604,6 +605,10 @@ pub struct AnvilEvmArgs {
     /// Enable Odyssey features
     #[arg(long, alias = "alphanet")]
     pub odyssey: bool,
+
+    /// Run a Celo chain
+    #[arg(long)]
+    pub celo: bool,
 }
 
 /// Resolves an alias passed as fork-url to the matching url defined in the rpc_endpoints section

crates/anvil/src/config.rs

@@ -196,6 +196,8 @@ pub struct NodeConfig {
     pub precompile_factory: Option<Arc<dyn PrecompileFactory>>,
     /// Enable Odyssey features.
     pub odyssey: bool,
+    /// Enable Celo features.
+    pub celo: bool,
     /// Do not print log messages.
     pub silent: bool,
     /// The path where states are cached.
@@ -492,6 +494,7 @@ impl Default for NodeConfig {
             memory_limit: None,
             precompile_factory: None,
             odyssey: false,
+            celo: false,
             silent: false,
             cache_path: None,
         }
@@ -1017,6 +1020,17 @@ impl NodeConfig {
         self
     }
 
+    /// Sets whether to enable Celo support
+    #[must_use]
+    pub fn with_celo(mut self, celo: bool) -> Self {
+        self.celo = celo;
+        if celo {
+            // Celo requires Optimism support
+            self.enable_optimism = true;
+        }
+        self
+    }
+
     /// Makes the node silent to not emit anything on stdout
     #[must_use]
     pub fn silent(self) -> Self {
@@ -1071,6 +1085,7 @@ impl NodeConfig {
                 ..Default::default()
             },
             self.enable_optimism,
+            self.celo,
         );
 
         let fees = FeeManager::new(

crates/anvil/src/eth/backend/env.rs

@@ -10,12 +10,19 @@ pub struct Env {
     pub evm_env: EvmEnv,
     pub tx: OpTransaction<TxEnv>,
     pub is_optimism: bool,
+    pub is_celo: bool,
 }
 
 /// Helper container type for [`EvmEnv`] and [`OpTransaction<TxEnv>`].
 impl Env {
-    pub fn new(cfg: CfgEnv, block: BlockEnv, tx: OpTransaction<TxEnv>, is_optimism: bool) -> Self {
-        Self { evm_env: EvmEnv { cfg_env: cfg, block_env: block }, tx, is_optimism }
+    pub fn new(
+        cfg: CfgEnv,
+        block: BlockEnv,
+        tx: OpTransaction<TxEnv>,
+        is_optimism: bool,
+        is_celo: bool,
+    ) -> Self {
+        Self { evm_env: EvmEnv { cfg_env: cfg, block_env: block }, tx, is_optimism, is_celo }
     }
 }
 

crates/anvil/src/eth/backend/executor.rs

@@ -11,6 +11,7 @@ use crate::{
         error::InvalidTransactionError,
         pool::transactions::PoolTransaction,
     },
+    evm::celo_precompile,
     inject_precompiles,
     mem::inspector::AnvilInspector,
 };
@@ -127,6 +128,7 @@ pub struct TransactionExecutor<'a, Db: ?Sized, V: TransactionValidator> {
     pub enable_steps_tracing: bool,
     pub odyssey: bool,
     pub optimism: bool,
+    pub celo: bool,
     pub print_logs: bool,
     pub print_traces: bool,
     /// Recorder used for decoding traces, used together with print_traces
@@ -272,7 +274,7 @@ impl<DB: Db + ?Sized, V: TransactionValidator> TransactionExecutor<'_, DB, V> {
             tx_env.enveloped_tx = Some(alloy_rlp::encode(&tx.transaction.transaction).into());
         }
 
-        Env::new(self.cfg_env.clone(), self.block_env.clone(), tx_env, self.optimism)
+        Env::new(self.cfg_env.clone(), self.block_env.clone(), tx_env, self.optimism, self.celo)
     }
 }
 
@@ -348,6 +350,13 @@ impl<DB: Db + ?Sized, V: TransactionValidator> Iterator for &mut TransactionExec
                 inject_precompiles(&mut evm, vec![(P256VERIFY, P256VERIFY_BASE_GAS_FEE)]);
             }
 
+            if self.celo {
+                evm.precompiles_mut()
+                    .apply_precompile(&celo_precompile::CELO_TRANSFER_ADDRESS, move |_| {
+                        Some(celo_precompile::precompile())
+                    });
+            }
+
             if let Some(factory) = &self.precompile_factory {
                 inject_precompiles(&mut evm, factory.precompiles());
             }

crates/anvil/src/eth/backend/mem/mod.rs

@@ -27,6 +27,7 @@ use crate::{
         pool::transactions::PoolTransaction,
         sign::build_typed_transaction,
     },
+    evm::celo_precompile,
     inject_precompiles,
     mem::{
         inspector::AnvilInspector,
@@ -837,6 +838,11 @@ impl Backend {
         self.env.read().is_optimism
     }
 
+    /// Returns true if Celo features are active
+    pub fn is_celo(&self) -> bool {
+        self.env.read().is_celo
+    }
+
     /// Returns [`BlobParams`] corresponding to the current spec.
     pub fn blob_params(&self) -> BlobParams {
         let spec_id = self.env.read().evm_env.cfg_env.spec;
@@ -1177,6 +1183,13 @@ impl Backend {
             inject_precompiles(&mut evm, vec![(P256VERIFY, P256VERIFY_BASE_GAS_FEE)]);
         }
 
+        if self.is_celo() {
+            evm.precompiles_mut()
+                .apply_precompile(&celo_precompile::CELO_TRANSFER_ADDRESS, move |_| {
+                    Some(celo_precompile::precompile())
+                });
+        }
+
         if let Some(factory) = &self.precompile_factory {
             inject_precompiles(&mut evm, factory.precompiles());
         }
@@ -1279,6 +1292,7 @@ impl Backend {
             precompile_factory: self.precompile_factory.clone(),
             odyssey: self.odyssey,
             optimism: self.is_optimism(),
+            celo: self.is_celo(),
             blob_params: self.blob_params(),
             cheats: self.cheats().clone(),
         };
@@ -1369,6 +1383,7 @@ impl Backend {
                     odyssey: self.odyssey,
                     precompile_factory: self.precompile_factory.clone(),
                     optimism: self.is_optimism(),
+                    celo: self.is_celo(),
                     blob_params: self.blob_params(),
                     cheats: self.cheats().clone(),
                 };
@@ -2723,6 +2738,7 @@ impl Backend {
             precompile_factory: self.precompile_factory.clone(),
             odyssey: self.odyssey,
             optimism: self.is_optimism(),
+            celo: self.is_celo(),
             blob_params: self.blob_params(),
             cheats: self.cheats().clone(),
         };

crates/anvil/src/evm.rs

@@ -9,6 +9,8 @@ use op_revm::OpContext;
 use revm::{Inspector, precompile::Precompile};
 use std::fmt::Debug;
 
+pub mod celo_precompile;
+
 /// Object-safe trait that enables injecting extra precompiles when using
 /// `anvil` as a library.
 pub trait PrecompileFactory: Send + Sync + Unpin + Debug {
@@ -152,6 +154,7 @@ mod tests {
                 ..Default::default()
             },
             is_optimism: true,
+            is_celo: false,
         };
 
         let mut chain = L1BlockInfo::default();

crates/anvil/src/evm/celo_precompile.rs

@@ -0,0 +1,95 @@
+//! Celo precompile implementation for token transfers.
+//!
+//! This module implements the Celo transfer precompile that enables native token transfers from an
+//! EVM contract. The precompile is part of Celo's token duality system, allowing transfer of
+//! native tokens via ERC20.
+//!
+//! For more details, see: <https://specs.celo.org/token_duality.html#the-transfer-precompile>
+//!
+//! The transfer precompile is deployed at address 0xfd and accepts 96 bytes of input:
+//! - from address (32 bytes, left-padded)
+//! - to address (32 bytes, left-padded)
+//! - value (32 bytes, big-endian U256)
+
+use alloy_evm::precompiles::{DynPrecompile, PrecompileInput};
+use alloy_primitives::{Address, U256, address};
+use revm::precompile::{PrecompileError, PrecompileId, PrecompileOutput, PrecompileResult};
+
+pub const CELO_TRANSFER_ADDRESS: Address = address!("0x00000000000000000000000000000000000000fd");
+
+/// Gas cost for Celo transfer precompile
+const CELO_TRANSFER_GAS_COST: u64 = 9000;
+
+/// Returns the celo native transfer
+pub fn precompile() -> DynPrecompile {
+    DynPrecompile::new_stateful(PrecompileId::custom("celo transfer"), celo_transfer_precompile)
+}
+
+/// Celo transfer precompile implementation.
+///
+/// Uses load_account to modify balances directly, making it compatible with PrecompilesMap.
+pub fn celo_transfer_precompile(input: PrecompileInput<'_>) -> PrecompileResult {
+    // Check minimum gas requirement
+    if input.gas < CELO_TRANSFER_GAS_COST {
+        return Err(PrecompileError::OutOfGas);
+    }
+
+    // Validate input length (must be exactly 96 bytes: 32 + 32 + 32)
+    if input.data.len() != 96 {
+        return Err(PrecompileError::Other(format!(
+            "Invalid input length for Celo transfer precompile: expected 96 bytes, got {}",
+            input.data.len()
+        )));
+    }
+
+    // Parse input: from (bytes 12-32), to (bytes 44-64), value (bytes 64-96)
+    let from_bytes = &input.data[12..32];
+    let to_bytes = &input.data[44..64];
+    let value_bytes = &input.data[64..96];
+
+    let from_address = Address::from_slice(from_bytes);
+    let to_address = Address::from_slice(to_bytes);
+    let value = U256::from_be_slice(value_bytes);
+
+    // Perform the transfer using load_account to modify balances directly
+    let mut internals = input.internals;
+
+    // Load and check the from account balance first
+    {
+        let from_account = match internals.load_account(from_address) {
+            Ok(account) => account,
+            Err(e) => {
+                return Err(PrecompileError::Other(format!("Failed to load from account: {e:?}")));
+            }
+        };
+
+        // Check if from account has sufficient balance
+        if from_account.data.info.balance < value {
+            return Err(PrecompileError::Other("Insufficient balance".into()));
+        }
+
+        // Deduct balance from the from account
+        from_account.data.info.balance -= value;
+    }
+
+    // Load and update the to account
+    {
+        let to_account = match internals.load_account(to_address) {
+            Ok(account) => account,
+            Err(e) => {
+                return Err(PrecompileError::Other(format!("Failed to load to account: {e:?}")));
+            }
+        };
+
+        // Check for overflow in to account
+        if to_account.data.info.balance.checked_add(value).is_none() {
+            return Err(PrecompileError::Other("Balance overflow in to account".into()));
+        }
+
+        // Add balance to the to account
+        to_account.data.info.balance += value;
+    }
+
+    // No output data for successful transfer
+    Ok(PrecompileOutput::new(CELO_TRANSFER_GAS_COST, alloy_primitives::Bytes::new()))
+}