Overview of EVM to Everscale Transfer Mechanics ​

1. Locking or Burning Target Tokens Based on Their Type:

   • To initiate a transfer on the EVM network, deposit the desired amount of the target token into the MultiVault contract on the EVM network. Please note that if the token is an Alien token (e.g., DAI, USDT, WBTC, etc.), the token owner must approve the MultiVault contract before making the deposit. For detailed instructions, refer to the guide on Approving Alien Tokens.

   • Once the deposit is complete, the MultiVault contract will handle the burning or locking of the token based on its type. Native tokens will be burned while Alien tokens will be locked.

2. Emitting Events:

   • During this process, two events will be emitted, the Deposit event and either the AlienTransfer or NativeTransfer event, depending on the token type.

   Transactions and logs examples can be found below:

   Details

   • Deposit Event Example Transaction
   • Deposit Event Example Log

   

   • AlienTransfer Event Example Transaction
   • AlienTransfer Event Example Log

   

   • NativeTransfer Event Example Transaction
   • NativeTransfer Event Example Log

   

3. Deploying and Confirming the Event Contract:

   • After the events are emitted by the MultiVault contract, it is necessary to deploy an event contract on the Everscale network.

   • Relayers will then vote on the event contract to confirm the deposit on the EVM network, it will take blocksToConfirm blocks for relayers to confirm the event contract.

   • Methods for deploying the Event contract:

   3.1 Paying Everscale Operations Gas Fees with EVM Gas Tokens: ​

   • If Everscale operations gas fees are paid with EVM gas tokens, the user must attach enough gas tokens to the transaction. The Credit Modules will deploy the event contract on Everscale. Afterward, tokens will be automatically minted or released on Everscale. To perform this operation, besides attaching sufficient EVM gas tokens to the transaction, the expected_evers parameter must be set to a certain amount.

   3.2 Paying Everscale Operations Gas Fees with EVER:

   • If Everscale operations gas fees are paid with EVER, the user can proceed without attaching enough EVM gas tokens and set expected_evers to zero. At this point, the user needs to manually deploy the event contract by calling the deployEvent function on the EthereumEverscaleEventConfiguration contract. This will deploy an Event contract, and after exceeding the quorum of confirm votes by relayers, the token will be released if it's a Native token and minted if it's an Alien token.

4. At this point the tokens must be deposited to the recipient EVER Wallet.

Step-by-Step Guide: EVM to Everscale Transfer ​

Alien & Native Token Transfer ​

• Alien
  

• Native
  

1. If the the target token was an Alien or a Native token we must use the deposit function on MultiVault contract, but if the token was an Alien token, we must approve MultiVault for the desired token amount before depositing the tokens.
   Once approved, the deposit function can be called.

Notice that if the token was a Native token the approval is not needed.

Function ​

function deposit(depositParams memory d) external payable override;

struct DepositParams {
    IEverscale.EverscaleAddress recipient;
    address token;
    uint amount;
    uint expected_Evers;
    bytes payload;
}

1. Now it's time to deploy the event contract which can be accomplished in two ways:

• 2.1: See Overview of Everscale to EVM transfer mechanics: 3.1..
• 2.2: Deploy the event contract manually by calling the deployEvent function on the EthereumEverscaleEventConfiguration contract:

Function ​

function deployEvent(IEthereumEverscaleEvent.EthereumEverscaleEventVoteData eventVoteData) external override;

struct EthereumEverscaleEventVoteData {
    uint eventTransaction;
    uint32 eventIndex;
    TvmCell eventData;
    uint32 eventBlockNumber;
    uint eventBlock;
}

EVM Gas Token Transfer ​

1. If the target token was the EVM network gas token, we must use the depositByNativeToken function on the MultiVault contract and attach the desired amount of the gas token equal to the amount value parameter of the function call to the transaction:

NOTE : In the MultiVault contract the EVM gas token will be converted to its wrapped version and become an ERC20 token, then the rest of the operation will be resumed.

Function ​

function depositByNativeToken(DepositNativeTokenParams memory d) external payable override;

struct DepositNativeTokenParams {
    IEverscale.EverscaleAddress recipient;
    uint amount;
    uint expected_Evers;
    bytes payload;
}

2. Now it's time to deploy the event contract which can be accomplished in two ways:

• 2.1: See Overview of Everscale to EVM transfer mechanics: 3.1.

• 2.2: Deploy the event contract manually by calling the deployEvent function on the EthereumEverscaleEventConfiguration contract:

Function ​

function deployEvent(IEthereumEverscaleEvent.EthereumEverscaleEventVoteData eventVoteData) external override;

struct EthereumEverscaleEventVoteData {
    uint eventTransaction;
    uint32 eventIndex;
    TvmCell eventData;
    uint32 eventBlockNumber;
    uint eventBlock;
}

Interactive code samples related to examples above can be found here

The addresses of all the referenced contracts and tokens can be found at Links.