Synchronize balances between Linera and the EVM. #4274

MathieuDutSik · 2025-07-24T19:38:12Z

Motivation

Linera has its native-token (do we call it lineras?), and we need to have synchronicity between it and the balance
of the EVM. This is harder to achieve

Fixes #3756

Proposal

In the EVM world, there is complete identity between transferring ethers and calling a function. This is not so in Linera.

Therefore, some changes have to be made for it to work:

Linera amounts are on 128 bits while EVM ethers are on 256 bits. But that is not a problem since, in effect, only 85 bits are ever used. But this introduces a conversion function.
Now the transact_commit takes an amount being transmitted and the function call. Just like in the EVM world.
We introduce a get_mutation function that takes an amount, an operation, and encapsulates it into a single Vec<u8>.
This is followed when operations are transmitted to another function.
Currently, the fn transfer function works in the sense that the beneficiary receives the ethers on the next block. Since the beneficiaries of transfers are on the same chain as the source, we can make it sync.
When instantiating a new contract, we can start with some value. But this is only for the creator chain. For other chains, nothing is received.

Other changes being made:

Better tracking of occurring errors.
A type EvmInstantiation is introduced that contains the native token at instantiation and the command for instantiating.
Move some code into inputs.rs.

Further needed work:

The beneficiary of a transfer operation can be an Externally Owned Account or a Smart Contract. The problem is in distinguishing between the two. In this PR we use it by the size of the operation; if null, then it is an EOA. But this is not strictly exact. What matters in the end is whether the corresponding blob exists, since if we call an application that does not yet exist but has a blob, then it is instantiated and executed.

Test Plan

The CI.
The test that demonstrates the functionality is test_evm_end_to_end_balance_and_transfer.

Release Plan

Nothing to do / These changes follow the usual release cycle.

Links

None.

afck

Would it be possible to extract the general change in system.rs to its own PR, separate from the EVM-specific changes?

linera-base/src/data_types.rs

linera-base/src/identifiers.rs

linera-execution/src/evm/database.rs

linera-execution/src/evm/inputs.rs

linera-execution/src/evm/mod.rs

linera-execution/src/system.rs

MathieuDutSik · 2025-08-12T12:06:03Z

Would it be possible to extract the general change in system.rs to its own PR, separate from the EVM-specific changes?

Yes and this is already done in the PR #4268

afck

Some more nit-picks; but maybe someone with a better understanding of EVM can give the approval?

linera-base/src/data_types.rs

linera-base/src/identifiers.rs

linera-execution/src/evm/inputs.rs

afck · 2025-08-14T10:19:35Z

linera-execution/src/evm/inputs.rs

+
+pub(crate) fn get_revm_instantiation_bytes(value: Vec<u8>) -> Vec<u8> {
+    use alloy_primitives::Bytes;
+    use alloy_sol_types::{sol, SolCall};


Let's move these to the top and also remove them from the functions below.

It is not that easy. But I arranged the code in a reasonable way I think.

I'm curious, why is it not easy? I mean, I believe you 😅 But it looks like it's just about moving imports, so it shouldn't cause issues?

linera-execution/src/evm/revm.rs

linera-service/tests/fixtures/evm_balance_and_transfer.sol

linera-execution/src/evm/revm.rs

afck · 2025-08-14T10:49:46Z

linera-execution/src/evm/revm.rs

+            //
+            // So, the correct way is instead to test the existence of the application
+            // given the application_id. So, we need following function in BaseRuntime:
+            //  fn is_existing_application(&mut self, application_id: ApplicationId) -> Result<bool, ExecutionError>;


Ideally we'd also handle the case where the application has not yet been used on this chain, but will be. So we'd transfer the balance to the account as if it were a user account, but then, if the application is later used, it should have the correct balance. Or is that already the case?

Yes, I can handle that case in a different way. Will see later.

linera-execution/src/evm/revm.rs

afck · 2025-08-14T13:09:58Z

linera-execution/src/evm/inputs.rs

+
+    fn generic_application_id_to_internal_generic_application_id(
+        generic_application_id: GenericApplicationId,
+    ) -> InternalGenericApplicationId {


Should these be From implementations?

I don't think so.
We might have a larger usage of this kind of conversion to sol types. But right now, the LineraType.StreamUpdate[] is a single example of such code.
So, we may reconsider this issue later if this kind of code grows.

linera-base/src/identifiers.rs

linera-base/src/vm.rs

linera-service/tests/linera_net_tests.rs

ma2bd · 2025-09-01T19:53:38Z

linera-base/src/vm.rs

+}
+
+/// Creates an internal mutation from value and argument data
+pub fn get_evm_mutation(


Can we just add a constructor new and write this?
bcs::to_bytes(&EvmOperation::new(value, argument))

Is this possible?

impl EvmOperation { fn new(value: Amount, argument: <something for abi_encode()>) -> ... { ... } }

It is not easy to make this pass with the Wasm code.

ma2bd · 2025-09-04T02:39:00Z

linera-base/src/vm.rs

+}
+
+/// Creates an operation from value and argument data.
+pub fn get_evm_operation(


We can do better than this.

use crate::data_types::Amount; impl EvmOperation { fn new(amount: Amount, argument: Vec<u8>) -> Self { Self { ... } } fn to_bytes(&self) -> Result<Vec<u8>, bcs::Error> { ... } }

Longer explanation:

Even if one suspects that get_evm_operation might not be the same as EvmOperation::new, it still sounds like it should return a value of type EvmOperation.

Top-level pub fn definitions should be rare.

Ok, done.
But top-level fn functions ought to be ok for test code?

bart-linera · 2025-10-08T13:36:01Z

linera-base/src/vm.rs

+/// The instantiation argument to EVM smart contracts.
+/// `value` is the amount being transferred.
+#[derive(Default, Serialize, Deserialize)]
+pub struct EvmInstantiation {
+    /// The initial value put in the instantiation of the contract.
+    pub value: alloy_primitives::U256,
+    /// The input to the `fn instantiate` of the EVM smart contract.
+    pub argument: Vec<u8>,
 }


Is it important to have this as a separate type? Could instantiation simply be considered a specific kind of operation?

Yes, we can.
However, Linera does allow the separation between the Operation and Instantiation types. We take advantage of it.
So, of course, we could identify the type, but we would gain nothing from doing that. Only losing clarity.

bart-linera · 2025-10-08T13:39:51Z

linera-execution/src/evm/database.rs

 {
    type Error = ExecutionError;

+    /// The `basic_ref` is the function for reading the state of


The comment seems to be incomplete 😅

bart-linera · 2025-10-08T13:47:43Z

linera-execution/src/evm/database.rs

        let mut batch = Batch::new();
        for (address, account) in &self.changes {
+            if address == &FAUCET_ADDRESS {
+                // We do not write the faucet address nor expect any coherency from it.


Some explanation why could be useful (unless it is already explained elsewhere?).

bart-linera · 2025-10-16T09:09:23Z

linera-execution/src/evm/database.rs

    pub contract_address: Address,
+    /// The caller to the smart contract
+    pub caller: Address,
+    /// The value of the smart contract


It's unclear to me what this means. Is this the amount bundled with the call, maybe? Or with the instantiation? Could be helpful to elaborate a bit.

To answer: Yes, the amount is bundled with the call. It is also bundled with the instantiation.

However, in the case in question, that is DatabaseRuntime, it is the contract state.
Therefore, here call and instantiation are not relevant.

bart-linera · 2025-10-16T09:11:38Z

linera-execution/src/evm/database.rs

        if !self.changes.is_empty() {
-            let account = self.changes.get(&address).unwrap();
-            return Ok(Some(account.info.clone()));
+            // This is the case of service calls with empty storage.


Is it possible that self.changes is not empty (so there are uncommitted changes), but storage is not empty as well? Shouldn't we try to read from the storage as well, if self.changes.get returns None?

No.
The self.changes are needed for the service calls.
There are two scenarios for the service calls:

The contract already exists. Then we access the storage and run the service query.

The contract does not exist. We need to first instantiate the contract before being able to call it (for the service). However, since the service is not allowed to write to storage, we put the result of the storage initialization to self.changes.

bart-linera · 2025-10-16T09:18:08Z

linera-execution/src/evm/inputs.rs

+
+pub(crate) fn get_revm_instantiation_bytes(value: Vec<u8>) -> Vec<u8> {
+    use alloy_primitives::Bytes;
+    use alloy_sol_types::{sol, SolCall};


I'm curious, why is it not easy? I mean, I believe you 😅 But it looks like it's just about moving imports, so it shouldn't cause issues?

bart-linera · 2025-10-16T09:22:18Z

linera-execution/src/evm/revm.rs

+    ensure!(
+        inputs.call_value == U256::ZERO,
+        EvmExecutionError::NoTransferInRuntimeCall
+    );


I'm slightly confused here - this seems to ensure that the value is zero, but the error variant seems to indicate that we want the value to not be zero? Shouldn't this be inputs.call_value != U256::ZERO, then?

bart-linera · 2025-10-16T09:22:28Z

linera-execution/src/evm/revm.rs

+    ensure!(
+        get_value(&inputs.value)? == U256::ZERO,
+        EvmExecutionError::NoTransferInServices
+    );


Same as above.

Service calls carry no transfer by construction.

bart-linera · 2025-10-16T09:36:49Z

linera-execution/src/evm/revm.rs

+            let application_description = ApplicationDescription {
+                module_id,
+                creator_chain_id: chain_id,
+                block_height,
+                application_index,
+                parameters: parameters.clone(),
+                required_application_ids: Vec::new(),
+            };


Maybe we should just have a method like next_application_id on the runtime? (And, if possible, use it within create_application, too - so that the logic is not duplicated.)

afck · 2025-10-21T11:06:40Z

linera-base/src/data_types.rs

+/// Converting amount from `U256` to Amount can fail since
+/// `Amount` is a `u128`.


Suggested change

/// Converting amount from `U256` to Amount can fail since

/// `Amount` is a `u128`.

/// Error converting from `U256` to `Amount`.

/// This can fail since `Amount` is a `u128`.

(Or we just use ArithmeticError::Overflow?)

Thank you.
I prefer to have a specific error for the conversion.

linera-base/src/data_types.rs

linera-execution/src/evm/database.rs

linera-execution/src/lib.rs

MathieuDutSik changed the title ~~Synchronicity of balances between Linera and the EVM.~~ WIP: Synchronicity of balances between Linera and the EVM. Jul 24, 2025

MathieuDutSik changed the title ~~WIP: Synchronicity of balances between Linera and the EVM.~~ WIP on synchronicity of balances between Linera and the EVM. Jul 24, 2025

MathieuDutSik force-pushed the balance_access branch 2 times, most recently from 2c3de1a to aced5dc Compare August 11, 2025 08:28

MathieuDutSik changed the title ~~WIP on synchronicity of balances between Linera and the EVM.~~ Synchronicity of balances between Linera and the EVM. Aug 12, 2025

MathieuDutSik marked this pull request as ready for review August 12, 2025 08:40

afck reviewed Aug 12, 2025

View reviewed changes

ma2bd changed the title ~~Synchronicity of balances between Linera and the EVM.~~ Synchronize balances between Linera and the EVM. Aug 13, 2025

MathieuDutSik force-pushed the balance_access branch 2 times, most recently from a3a6559 to 33e5f62 Compare August 14, 2025 08:23

afck reviewed Aug 14, 2025

View reviewed changes

MathieuDutSik force-pushed the balance_access branch from ca1da82 to a764c30 Compare August 15, 2025 07:21

MathieuDutSik requested a review from deuszx August 19, 2025 09:14

MathieuDutSik force-pushed the balance_access branch 2 times, most recently from 742c08c to 3b594da Compare August 26, 2025 14:17

ma2bd reviewed Sep 1, 2025

View reviewed changes

linera-base/src/identifiers.rs Show resolved Hide resolved

linera-base/src/vm.rs Outdated Show resolved Hide resolved

MathieuDutSik commented Sep 1, 2025

View reviewed changes

linera-service/tests/linera_net_tests.rs Outdated Show resolved Hide resolved

ma2bd reviewed Sep 1, 2025

View reviewed changes

MathieuDutSik force-pushed the balance_access branch 6 times, most recently from d90c1a4 to 2b4c1db Compare September 3, 2025 18:26

ma2bd reviewed Sep 4, 2025

View reviewed changes

ma2bd added the enhancement New feature or request label Oct 16, 2025

ma2bd added this to VM Integrations Oct 16, 2025

ma2bd added this to the Testnet #4 milestone Oct 16, 2025

ma2bd requested a review from bart-linera October 16, 2025 02:14

bart-linera reviewed Oct 16, 2025

View reviewed changes

MathieuDutSik force-pushed the balance_access branch from ceb0eff to f2e0c9f Compare October 21, 2025 10:19

Introduce the management of balances within Ethereum contracts.

87b7f6f

MathieuDutSik force-pushed the balance_access branch from f2e0c9f to 87b7f6f Compare October 21, 2025 10:54

afck reviewed Oct 21, 2025

View reviewed changes

Corrections after rebase.

0c78838

		/// Converting amount from `U256` to Amount can fail since
		/// `Amount` is a `u128`.

Synchronize balances between Linera and the EVM. #4274

Are you sure you want to change the base?

Synchronize balances between Linera and the EVM. #4274

Uh oh!

Conversation

MathieuDutSik commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Proposal

Test Plan

Release Plan

Links

Uh oh!

afck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MathieuDutSik commented Aug 12, 2025

Uh oh!

afck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

afck Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ma2bd Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ma2bd Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MathieuDutSik commented Jul 24, 2025 •

edited

Loading

afck Aug 14, 2025 •

edited

Loading

ma2bd Sep 1, 2025 •

edited

Loading

ma2bd Sep 4, 2025 •

edited

Loading