depositCoin

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

Deposits native coins from the external chain to EVVM through cross-chain protocols. This function accepts native currency from the user 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
amount	uint256	Amount of native coins 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. Balance Verification

if (msg.value < amount) revert ErrorsLib.InsufficientBalance();

Ensures the user sent at least the deposit amount in native currency.

2. Payload Encoding

bytes memory payload = encodePayload(address(0), toAddress, amount);

Encodes the deposit with address(0) representing native coins.

3. Protocol-Specific Cross-Chain Execution

Hyperlane (0x01)

uint256 quote = getQuoteHyperlane(toAddress, address(0), amount);
if (msg.value < quote + amount)
    revert ErrorsLib.InsufficientBalance();
    
IMailbox(hyperlane.mailboxAddress).dispatch{value: quote}(
    hyperlane.hostChainStationDomainId,
    hyperlane.hostChainStationAddress,
    payload
);

• Total Requirement: msg.value >= amount + gas_quote
• Amount Allocation: amount for deposit, quote for gas
• Gas Payment: Uses quote value for Hyperlane dispatch

LayerZero (0x02)

uint256 fee = quoteLayerZero(toAddress, address(0), amount);
if (msg.value < fee + amount)
    revert ErrorsLib.InsufficientBalance();
    
_lzSend(
    layerZero.hostChainStationEid,
    payload,
    _options,
    MessagingFee(fee, 0),
    msg.sender
);

• Total Requirement: msg.value >= amount + fee
• Amount Allocation: amount for deposit, fee for LayerZero messaging
• Refund: Excess fees refunded to msg.sender

Axelar (0x03)

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

• Gas Allocation: msg.value - amount for gas service
• Amount Isolation: amount reserved for deposit
• Refund Recipient: Gas refunds directed to msg.sender

Native Coin Handling

Value Distribution

The msg.value is split between:

1. Deposit Amount: The actual coins being deposited to EVVM
2. Gas Fees: Native tokens required for cross-chain messaging

Protocol-Specific Requirements

• Hyperlane & LayerZero: Explicit validation of msg.value >= amount + gas_cost
• Axelar: Gas service receives msg.value - amount

Cross-Chain Message Processing

Payload Structure

payload = abi.encode(address(0), toAddress, amount);

The address(0) indicates native coin transfer.

Host Chain Processing

Upon message receipt, the host chain station will:

1. Decode payload: (address(0), toAddress, amount)
2. Call Evvm(evvmAddress).addAmountToUser(toAddress, address(0), amount)
3. Credit recipient's EVVM balance with native coin equivalent

Gas Estimation

Before calling this function, estimate total required value:

Hyperlane

uint256 gasQuote = getQuoteHyperlane(toAddress, address(0), amount);
uint256 totalRequired = amount + gasQuote;

LayerZero

uint256 layerZeroFee = quoteLayerZero(toAddress, address(0), amount);
uint256 totalRequired = amount + layerZeroFee;

Axelar

For Axelar, provide sufficient value to cover both deposit and gas service:

uint256 totalRequired = amount + estimatedAxelarGas;

Security Features

Value Validation

• Minimum Requirement: msg.value >= amount
• Protocol-Specific: Additional validation for gas coverage
• Atomic Operations: Deposit and gas payment processed together

Cross-Chain Security

• Protocol Authentication: Message origin and sender validation
• Native Coin Representation: address(0) convention for native assets
• Balance Integrity: Exact amount credited to EVVM balance

Error Conditions

Error	Condition
InsufficientBalance	msg.value < amount or insufficient gas coverage
Protocol Revert	Unsupported protocolToExecute value
Cross-chain Failure	Insufficient gas payment for chosen protocol

Usage Examples

Hyperlane Deposit

// 1. Get gas quote
uint256 gasRequired = getQuoteHyperlane(recipientAddress, address(0), depositAmount);
uint256 totalValue = depositAmount + gasRequired;

// 2. Execute deposit
depositCoin{value: totalValue}(
    recipientAddress,
    depositAmount,
    0x01 // Hyperlane
);

LayerZero Deposit

// 1. Get fee quote
uint256 layerZeroFee = quoteLayerZero(recipientAddress, address(0), depositAmount);
uint256 totalValue = depositAmount + layerZeroFee;

// 2. Execute deposit
depositCoin{value: totalValue}(
    recipientAddress,
    depositAmount,
    0x02 // LayerZero
);

Axelar Deposit

// 1. Estimate total (deposit + gas)
uint256 totalValue = depositAmount + estimatedAxelarGas;

// 2. Execute deposit
depositCoin{value: totalValue}(
    recipientAddress,
    depositAmount,
    0x03 // Axelar
);

Integration Flow

1. External Chain: User sends native coins to external station
2. Value Split: Coins divided between deposit amount and gas fees
3. Cross-Chain: Message sent to host chain station with deposit details
4. Host Chain: Host station credits EVVM balance with native coin equivalent
5. EVVM: Recipient can use deposited coins within EVVM ecosystem

Sufficient Value Required

Ensure msg.value covers both the deposit amount and cross-chain messaging fees. Each protocol has different gas requirements that must be satisfied for successful execution.

Native Coin Representation

Native coins are represented as address(0) in EVVM balances, consistent with the standard convention for native currency handling.