Withdrawal Functions (Mate Staking)

This section provides information about functions within the EVVM contract designed for withdrawing tokens to an external network requiring the transaction executor (msg.sender) to be an sMATE staker. Consequently, the executor receives MATE rewards and the specified priorityFee for processing these withdrawals.

These functions facilitate transferring tokens held within the EVVM system's internal balances to a recipient address on another blockchain network, utilizing integrated bridging solutions (like Axelar, CCIP, Hyperlane, LayerZero).

The functions are divided based on nonce type: withdrawalMateStaking_sync (using the synchronous nonce mechanism) and withdrawalMateStaking_async.

Nonce Types

For more details on synchronous and asynchronous nonces within the EVVM contract, refer to the Nonce Types section.

withdrawalMateStaking_sync

Function Type: external
Function Signature: withdrawalMateStaking_sync(address,address,address,uint256,uint256,bytes,uint8,bytes)
Function Selector: ``

Initiates a synchronous withdrawal of tokens for a user (from) to an external network address (addressToReceive) via a specified bridging solution. This version uses the synchronous nonce system for the from user. It requires the executor (msg.sender) to be an sMATE staker and provides MATE rewards and the specified priorityFee to the executor.

Parameters

Parameter Name	Type	Description
from	address	The address of the user whose funds (internal EVVM balance) are being withdrawn.
addressToReceive	address	The destination address on the external network where the tokens should be received.
token	address	The contract address of the token being withdrawn.
amount	uint256	The quantity of token to withdraw and bridge.
priorityFee	uint256	A fee specified by the from user, included in the signature. Note: In this MateStaking function, this fee is paid to the executor (msg.sender) as part of their reward.
signature	bytes	The EIP-191 signature from the from user authorizing this specific withdrawal action (signing details like recipient, token, amount, fee, bridge solution, and sync nonce).
_solutionId	uint8	Identifier for the bridging solution to use: 1=Axelar, 2=CCIP, 3=Hyperlane, 4=LayerZero.
_options	bytes	Bridge-specific parameters encoded as bytes (for LayerZero execution only).

Signature Structure Reference

For details on how the signature is constructed, refer to the Withdrawal Signature Structure section. Ensure the synchronous identifier (52896a1f) is used.

Execution Methods

This function must be executed by an address (msg.sender) that is an sMATE staker.

Fisher Execution

When the executor is the fisher:

1. The user sends the payment request to the fishing spot
2. The fisher captures the transaction and validates all parameters
3. The fisher submits the transaction to the contract for processing

Direct Execution

When the executor is the user or a service:

1. The user/service submits their transaction directly to the contract

Workflow

Failure at validation steps typically reverts the transaction. The steps execute in the specified order.

1. Signature and Nonce Verification: Verifies the signature provided by the from user using an internal function ( verifyMessageSignedForWithdrawal). This process validates the signature against the expected withdrawal data and implicitly checks that the user's current synchronous nonce (nextSyncUsedNonce[from]) matches the nonce covered by the signature. Reverts if the signature is invalid or the nonce does not match.
2. Token Verification: Verifies that the token address provided is not the address of the native MATE token. Reverts if attempting to withdraw the native token via this method.
3. Staker Verification: Verifies that the executor (msg.sender) is an sMATE staker by checking the isMateStaker() function. Reverts if the executor is not a staker.
4. Balance Verification: Verifies that the internal EVVM balance of the from address for the specified token is sufficient to cover the amount. Reverts if the balance is insufficient.
5. Limit Verification: Checks the withdrawal amount against predefined limits for the from user:
   • If the token is ETH (or WETH representing native ETH), verifies the amount does not exceed a specific limit (1 ETH). Reverts if the ETH limit is exceeded.
   • If the token is an ERC20 token, uses an oracle or DEX pool ( UniswapV3 via estimateAmountUsingUniswapV3Pool) to estimate the amount's value in ETH and verifies this value does not exceed the general withdrawal limit (maxAmountToWithdraw.actual). Reverts if the value limit is exceeded.
6. Reducing User Balance: Reduces the from user's internal EVVM balance for the specified token.
7. Rewards Distribution: Transfers the priorityFee (in the specified token) and grants 1 MATE token reward to the executor (msg.sender). This likely uses internal balance update functions ( _updateBalance for the fee, _giveMateReward for the MATE reward).
8. Message Construction: Constructs the data payload for the cross-chain message using abi.encode. The encoded parameters are:
   • Recipient: Uses addressToReceive if it's not address(0), otherwise defaults to the from address.
   • Token: The token address being withdrawn.
   • Amount: The amount being withdrawn.

   bytes memory messagePayload = abi.encode(
       (addressToReceive == address(0) ? from : addressToReceive),
       token,
       amount
   );
9. Calling the Bridging Solution: Calls the internal makeCallCrossChain function, providing the _solutionId and necessary parameters (like addressToReceive, token, amount, _options). This initiates the cross-chain message/transfer via the selected bridge provider. Reverts if the makeCallCrossChain function itself fails.

---

withdrawalMateStaking_async

Function Type: external
Function Signature: withdrawalMateStaking_sync(address,address,address,uint256,uint256,bytes,uint8,bytes)
Function Selector: ``

Initiates an asynchronous withdrawal of tokens for a user (from) to an external network address (addressToReceive) via a specified bridging solution. This version uses the asynchronous nonce system (requiring an explicit nonce parameter) for the from user. It requires the executor (msg.sender) to be an sMATE staker and provides MATE rewards and the specified priorityFee to the executor.

Parameters

Parameter Name	Type	Description
from	address	The address of the user whose funds (internal EVVM balance) are being withdrawn.
addressToReceive	address	The destination address on the external network where the tokens should be received.
token	address	The contract address of the token being withdrawn.
amount	uint256	The quantity of token to withdraw and bridge.
priorityFee	uint256	A fee specified by the from user, included in the signature. Note: In this MateStaking function, this fee is paid to the executor (msg.sender) as part of their reward.
nonce	uint256	The specific asynchronous nonce provided by the from user for this transaction's replay protection. Must be unique and unused for this user's async transactions.
signature	bytes	The EIP-191 signature from the from user authorizing this specific withdrawal action (signing details like recipient, token, amount, fee, bridge solution, and sync nonce).
_solutionId	uint8	Identifier for the bridging solution to use: 1=Axelar, 2=CCIP, 3=Hyperlane, 4=LayerZero.
_options	bytes	Bridge-specific parameters encoded as bytes (for LayerZero execution only).

Execution Methods

This function must be executed by an address (msg.sender) that is an sMATE staker.

Fisher Execution

When the executor is the fisher:

1. The user sends the payment request to the fishing spot
2. The fisher captures the transaction and validates all parameters
3. The fisher submits the transaction to the contract for processing

Direct Execution

When the executor is the user or a service:

1. The user/service submits their transaction directly to the contract

Workflow

Failure at validation steps typically reverts the transaction. The steps execute in the specified order.

1. Signature Verification: Verifies the signature provided by the from user using an internal function ( verifyMessageSignedForWithdrawal). Reverts if the signature is invalid.
2. Nonce Verification: Verifies that the explicit nonce provided in the parameters has not already been used by the from address by checking the asyncUsedNonce[from][nonce] mapping. Reverts if the nonce has already been marked as used.
3. Token Verification: Verifies that the token address provided is not the address of the native MATE token. Reverts if attempting to withdraw the native token via this method.
4. Staker Verification: Verifies that the executor (msg.sender) is an sMATE staker by checking the isMateStaker() function. Reverts if the executor is not a staker.
5. Balance Verification: Verifies that the internal EVVM balance of the from address for the specified token is sufficient to cover the amount plus the priorityFee. Reverts if the balance is insufficient.
6. Limit Verification: Checks the withdrawal amount against predefined limits for the from user:
   • If the token is ETH (or WETH representing native ETH), verifies the amount does not exceed a specific limit (1 ETH). Reverts if the ETH limit is exceeded.
   • If the token is an ERC20 token, uses an oracle or DEX pool ( UniswapV3 via estimateAmountUsingUniswapV3Pool) to estimate the amount's value in ETH and verifies this value does not exceed the general withdrawal limit (maxAmountToWithdraw.actual). Reverts if the value limit is exceeded.
7. Reducing User Balance: Reduces the from user's internal EVVM balance for the specified token.
8. Rewards Distribution: Transfers the priorityFee (in the specified token) and grants 1 MATE token reward to the executor (msg.sender). This likely uses internal balance update functions (_updateBalance for the fee, _giveMateReward for the MATE reward).
9. Message Construction: Constructs the data payload for the cross-chain message using abi.encode. The encoded parameters are:
   • Recipient: Uses addressToReceive if it's not address(0), otherwise defaults to the from address.
   • Token: The token address being withdrawn.
   • Amount: The amount being withdrawn.

   bytes memory messagePayload = abi.encode(
       (addressToReceive == address(0) ? from : addressToReceive),
       token,
       amount
   );
10. Calling the Bridging Solution: Calls the internal makeCallCrossChain function, providing the _solutionId and necessary parameters (like addressToReceive, token, amount, _options). This initiates the cross-chain message/transfer via the selected bridge provider. Reverts if the makeCallCrossChain function itself fails.