depositERC20

Function Type: external payable
Function Signature: depositERC20(address,address,uint256,bytes1)
Returns: void

Deposits ERC20 tokens from the external chain to EVVM through cross-chain protocols. This function transfers tokens from the user's wallet on the external chain and sends a cross-chain message to credit the recipient's EVVM balance.

Parameters

Parameter	Type	Description
toAddress	address	Recipient address for EVVM balance credit
token	address	ERC20 token contract address (cannot be address(0))
amount	uint256	Amount of tokens to deposit
protocolToExecute	bytes1	Cross-chain protocol identifier (0x01, 0x02, or 0x03)

Protocol Identifiers

Value	Protocol	Description
0x01	Hyperlane	Uses Hyperlane mailbox for cross-chain messaging
0x02	LayerZero	Uses LayerZero endpoint for omnichain transfers
0x03	Axelar	Uses Axelar gateway for decentralized cross-chain communication

Workflow

1. Payload Encoding

bytes memory payload = encodePayload(token, toAddress, amount);

Encodes the deposit information for cross-chain transmission.

2. Token Transfer Verification

verifyAndDepositERC20(token, amount);

Internal function that:

• Validates token != address(0)
• Checks sufficient allowance: IERC20(token).allowance(msg.sender, address(this)) >= amount
• Transfers tokens: IERC20(token).transferFrom(msg.sender, address(this), amount)

3. Protocol-Specific Cross-Chain Execution

Hyperlane (0x01)

uint256 quote = getQuoteHyperlane(toAddress, token, amount);
IMailbox(hyperlane.mailboxAddress).dispatch{value: quote}(
    hyperlane.hostChainStationDomainId,
    hyperlane.hostChainStationAddress,
    payload
);

• Gas Estimation: Calls getQuoteHyperlane() for required native tokens
• Message Dispatch: Sends payload to host chain station via Hyperlane
• Payment: msg.value must cover the quoted dispatch fee

LayerZero (0x02)

uint256 fee = quoteLayerZero(toAddress, token, amount);
_lzSend(
    layerZero.hostChainStationEid,
    payload,
    _options,
    MessagingFee(fee, 0),
    msg.sender
);

• Fee Calculation: Estimates LayerZero messaging fees
• Omnichain Send: Uses LayerZero's OApp framework
• Refund: Excess fees refunded to msg.sender

Axelar (0x03)

IAxelarGasService(axelar.gasServiceAddress).payNativeGasForContractCall{
    value: msg.value
}(
    address(this),
    axelar.hostChainStationChainName,
    axelar.hostChainStationAddress,
    payload,
    msg.sender
);
gateway().callContract(
    axelar.hostChainStationChainName,
    axelar.hostChainStationAddress,
    payload
);

• Gas Service: Pays for cross-chain execution
• Gateway Call: Initiates contract call through Axelar network
• Refund Recipient: Gas refunds directed to msg.sender

Token Requirements

ERC20 Approval

Before calling this function, users must approve the external chain station contract:

IERC20(token).approve(externalChainStationAddress, amount);

Allowance Validation

The function verifies sufficient allowance before attempting transfer:

if (IERC20(token).allowance(msg.sender, address(this)) < amount)
    revert ErrorsLib.InsufficientBalance();

Cross-Chain Message Processing

Payload Structure

payload = abi.encode(token, toAddress, amount);

Host Chain Processing

Upon message receipt, the host chain station will:

1. Decode the payload to extract (token, toAddress, amount)
2. Call Evvm(evvmAddress).addAmountToUser(toAddress, token, amount)
3. Credit the recipient's EVVM balance with the deposited tokens

Gas Requirements

Users must provide sufficient native tokens (msg.value) to cover cross-chain messaging costs:

• Hyperlane: Mailbox dispatch fees
• LayerZero: Endpoint messaging fees
• Axelar: Gas service payments for execution

Use the respective quote functions to estimate required amounts:

• getQuoteHyperlane(toAddress, token, amount)
• quoteLayerZero(toAddress, token, amount)

Security Features

Token Validation

• Non-zero Address: Rejects address(0) for token parameter
• Allowance Check: Verifies sufficient ERC20 allowance before transfer
• Transfer Verification: Uses transferFrom which reverts on failure

Cross-Chain Security

• Protocol Authentication: Each protocol validates message origin and sender
• Payload Integrity: Encoded data ensures accurate parameter transmission
• Address Binding: Messages tied to specific recipient addresses

Error Conditions

Error	Condition
InsufficientBalance	Insufficient ERC20 allowance or native tokens for gas
ERC20 Transfer Failure	Token transfer reverts (insufficient balance, paused token, etc.)
Protocol Revert	Unsupported protocolToExecute value
Cross-chain Failure	Insufficient gas payment for chosen protocol

Usage Example

// 1. Approve tokens
IERC20(tokenAddress).approve(externalChainStationAddress, depositAmount);

// 2. Get gas quote
uint256 gasRequired = getQuoteHyperlane(recipientAddress, tokenAddress, depositAmount);

// 3. Execute deposit
depositERC20{value: gasRequired}(
    recipientAddress,
    tokenAddress, 
    depositAmount,
    0x01 // Hyperlane
);

Integration with EVVM

The deposit flow connects external chain assets to EVVM balances:

1. External Chain: User transfers ERC20 tokens to external station
2. Cross-Chain: Message sent to host chain station
3. Host Chain: Host station receives message and credits EVVM balance
4. EVVM: Recipient can use tokens within the EVVM ecosystem

Gas Payment Required

Ensure sufficient native tokens are sent with the transaction to cover cross-chain messaging costs. Insufficient gas will cause transaction failure and potential token loss.

ERC20 Approval Required

Users must approve the external chain station contract before calling this function. The approval should cover at least the deposit amount.