Treasury

Important

This preserved section contains legacy technical specifications.

A full architectural overhaul of this documentation is actively being developed.

The Treasury holds the MATE Metaprotocol collateral (TVL) and also acts as one entry point of liquidity to bridge between Ethereum Mainnet and the MATE Metaprotocol. This contract allows users to deposit and withdraw funds to and from the Mate metaprotocol. Some of the functions a user can utilize are as follows:

• deposit: Allows a user to deposit funds using cross-chain functions.
• fisherDepositETH & fisherDepositERC20: Allows a user to deposit funds using fishers as the cross-chain executor.
• withdraw: Allows a fisher or a cross-chain executor to execute a withdrawal for a user from the MATE Metaprotocol to the Ethereum network.
• getMaxAmountToDeposit: Returns the maximum amount in wei that a user can deposit, this can be capped during the beta.
• getNextFisherDepositNonce: Returns the next nonce that a user can use to deposit funds using a fisher.
• getNextFisherWithdrawalNonce: Returns the next nonce that a user can use to withdraw funds using a fisher or cross-chain executor.
• getIfTokenIsWhitelisted: Returns a boolean indicating if a token that a user wants to deposit is on the whitelist.
• getTokensWhitelistPool: Returns the address of the Uniswap v3 pool for the token whitelist.

Permissionless Deposit functions

This function allows a user to deposit funds to the MATE Metaprotocol using the following cross-chain protocols:

• Chainlink's CCIP (Cross-Chain Interoperability Protocol).
• Axelar
• Hyperlane
• Layer zero

The function has the following parameters:

• addressToReceive (address): The address of the user or contract who will receive the funds in the MATE metaprotocol.

• token (address): The address of the token to use in the MATE Metaprotocol. If is ETH, the address must be address(0).

• amount (uint256): The amount of tokens/ETH to make available in the MATE Metaprotocol. All ERC20 tokens and ETH must be defined in their units.

• solutionId (uint8): The permissionless bridging solution id of the fisher who will execute the deposit.

  Solution Id	Protocol
  1	Axelar
  2	CCIP
  3	Hyperlane
  4	LayerZero

• options (bytes): The options of the deposit (for LayerZero only).

The deposit function has the following steps:

ERC20 scenario

The user wants to deposit an ERC20 token to the MATE metaprotocol.

1. The user can verify if their ERC20 token is on the whitelist using the getIfTokenIsWhitelisted function.
2. If the user wants to deposit an ERC20 token, they must approve the Treasury contract to transfer the tokens.
3. The user can execute the deposit using the deposit function with the parameters defined above and a quantity of ETH for the cross-chain execution fee.
4. The contract uses the information from the Token/ETH Uniswap pool to calculate the amount in ETH to be deposited. If it exceeds the maximum amount (capped for security reasons during the beta launch), the transaction will revert.
5. The cross-chain executor will execute the deposit, and the user will receive the funds in the MATE Metaprotocol.

ETH scenario

The user wants to deposit ETH to the MATE Metaprotocol.

1. The user can execute the deposit using the deposit function with the parameters defined above and a quantity of ETH for the cross-chain execution fee plus the amount of ETH to be deposited.
2. The contract checks if the amount of ETH to be deposited exceeds the maximum amount. If it does, the transaction will revert.
3. The cross-chain executor will execute the deposit, and the user will receive the funds in the Mate metaprotocol.

Because the deposit function is the function that allows all the cross-chain protocol operations, each type of execution has its own function message sender. If you want to see the corresponding function message sender, please check the official documentation:

• Chainlink's CCIP (Cross-Chain Interoperability Protocol)
• Axelar
• Hyperlane
• Layer zero

Fisher Deposit functions

The fisher deposit functions allow a user to add tokens (deposit) to the MATE metaprotocol using fishers. There are two functions available:

fisherDepositETH

This function allows a user to use ETH in the MATE metaprotocol by using fishers. The function has the following parameters:

• addressToReceive (address): The address of the user or contract who will receive the funds in the Mate metaprotocol.
• priorityFee (uint256): The priority fee to be paid in ETH to the fisher, optional as a tip.
• signature (bytes): The ERC-191 signature of the user who wants to execute the deposit, you can find the signature structure below.

Important: Because the nextFisherDepositNonce is syncronous (during the beta), the version of the nonce is inside the signature verification, so the user must use the getNextFisherDepositNonce function to get the next nonce to use.

The function has the following steps:

1. The user can execute the deposit using the fisherDepositETH function with the parameters defined above and a the amount of ETH to be deposited plus the optional priority fee as a tip.
2. The contract checks if the ERC-191 signature is valid, if it is not, the transaction will revert.
3. The contract verifies if the amount of ETH to be deposited is equal to the amount of ETH to be deposited plus the priority fee. If it is not, the transaction will revert.
4. The contract verifies if the amount of ETH to be deposited, excluding the priority fee, exceeds the maximum amount (temporary capped for the beta purposes). If it does, the transaction will revert.
5. A event is emitted with the information of the deposit.
6. A Fisher catches the event and process it, the Fisher who executes it in the MATE Metaprotocol will receive the priority fee and the MATE reward, while the user or destinatary will be acredited with the tokens in the MATE Metaprotocol.

fisherDepositETH signature structure

The signature of fisherDepositETH is a string signed using ERC-191. The signature has the following variables:

• addressToReceive (address): The address of the user or contract who will receive the funds in the Mate metaprotocol.
• nonce (uint256): The nonce of the user who wants to execute the deposit.
• priorityFee (uint256): The priority fee to be paid in ETH to the Fisher as a tip.
• amount (uint256): The amount of ETH to be deposited.

By using the following structure:

string.concat(
  addressToString(_addressToReceive),
  ",",
  Strings.toString(_nonce),
  ",",
  Strings.toString(_priorityFee),
  ",",
  Strings.toString(_amount)
);

The string.concat function is a function that concatenates all the parameters.

All parameters are concatenated using a comma , as a separator. The addressToString and function is a function that converts an address to a string and set all the characters to lowercase. The Strings.toString function is a function that converts a uint256 to a string.

Example of a signature:

0x63c3774531EF83631111Fe2Cf01520Fb3F5A68F7,420,000069000000000000,100000000000000000

This string, signed by the user, indicates that the user wants to execute a deposit to the MATE Metaprotocol using fishers. The user wants to deposit 0.1 ETH and pay 0.000069 ETH as a priority fee. The deposit will be executed using a sync nonce of 420.

fisherDepositERC20

This function allows a user to make an ERC20 token available in the MATE Metaprotocol by using fishers. The function has the following parameters:

address addressToReceive, address tokenAddress, uint256 amount, uint256 priorityFee, bytes memory signature

• user (address): The address of the user who executes the deposit.
• addressToReceive (address): The address of the user or contract who will receive the funds in the MATE Metaprotocol.
• tokenAddress (address): The address of the token to use.
• amount (uint256): The amount of tokens to transfer.
• priorityFee (uint256): The priority fee to be paid in the token defined in tokenAddress to the fisher, optionally as a tip.
• signature (bytes): The ERC-191 signature of the user who wants to execute the deposit, you can find the signature structure below.

Important: Because the nextFisherDepositNonce is syncronous (during the beta), the version of the nonce is inside the signature verification, so the user must use the getNextFisherDepositNonce function to get the next nonce to use.

The function has the following steps:

1. The user or dApp can verify if some ERC20 token is on the whitelist using the getIfTokenIsWhitelisted function.
2. The user allows the Treasury contract to transfer the tokens.
3. The user can execute the deposit using the fisherDepositERC20 function with the parameters defined above.
4. The contract checks if the ERC-191 signature is valid, if it is not, the transaction will revert.
5. The contract verifies if the token to be deposited is on the whitelist, if it is not, the transaction will revert.
6. The contract verifies if the amount of tokens to be deposited, excluding the priority fee, exceeds the maximum amount (temporary capped for the beta purposes). If it does, the transaction will revert.
7. The token contract performs the transfer of tokens to the Treasury contract, if the transfer fails, the transaction will revert.
8. A event is emitted with the information of the deposit to be captured by the fishers.
9. The fishers catches the event and processes the action. The fisher who executes the action in the EVVM will receive the priority fee (as a tip), and the user will be able to use the funds in the MATE Metaprotocol.

fisherDepositERC20 signature structure

The signature of fisherDepositERC20 is a string signed using ERC-191. The signature has the following variables:

• addressToReceive (address): The address of the user or contract who will receive the funds in the MATE Metaprotocol.
• nonce (uint256): The nonce of the user who wants to execute the deposit.
• tokenAddress (address): The address of the token to be transferred.
• priorityFee (uint256): The priority fee to be paid in the token defined in tokenAddress to the fisher, optionally, as a tip.
• amount (uint256): The amount of tokens to be transferred.

The signature is created using the following structure:

string.concat(
  addressToString(_addressToReceive),
  ",",
  Strings.toString(_nonce),
  ",",
  addressToString(_tokenAddress),
  ",",
  Strings.toString(_priorityFee),
  ",",
  Strings.toString(_amount)
);

The string.concat function is a function that concatenates all the parameters.

All parameters are concatenated using a comma , as a separator. The addressToString and function is a function that converts an address to a string and set all the characters to lowercase. The Strings.toString function is a function that converts a number to a string.

Example of a signature:

0x63c3774531EF83631111Fe2Cf01520Fb3F5A68F7,420,0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48,69000,100000000

This string to be signed by the user, indicates that the user wants to execute a deposit to the Mate metaprotocol using a fisher. The user wants to deposit 1000 USDC and pay 0.069 USDC as a priority fee. The deposit will be executed using a sync nonce of 420.

Withdraw function

This function only allows the fishers or a permissionless cross-chain executor contract to perform a withdrawal for some user from the MATE Metaprotocol to the Ethereum network. The main function parameters are:

• user (address): The address of the user or contract who receives the funds in the Ethereum network.
• token (address): The address of the token to be transferred. If is ETH, the address must be address(0).
• amount (uint256): The amount of tokens/ETH to be transferred. All ERC20 tokens and ETH must be defined in their units.

Because withdraw is the function that allows all the bridge operations, each type of execution has its own fuction message receiver, excluding the fishers, if you want to see the corresponding function message receiver, please check the oficial documentation

• Chainlink's CCIP (Cross-Chain Interoperability Protocol)
• Axelar
• Hyperlane
• Layer zero

fisherWithdrawalReceiver

This function allows the fishers to perform a withdrawal for a user from the MATE Metaprotocol to the Ethereum network. The function has the following parameters:

• user (address): The address of the user who wants to execute the withdraw.
• addressToReceive (address): The address of the user or contract who will receive the withdraw in the Ethereum network.
• token (address): The address of the token to be transferred, if is ETH, the address must be address(0).
• amount (uint256): The amount of tokens to be transferred.
• priorityFee (uint256): The priority fee to be paid to the fisher, optionally, as a tip.
• nonce (uint256): The nonce of the user who wants to execute the withdraw.
• signature (bytes): The signature of the user who wants to execute the withdraw.

Important: Because the nextFisherWithdrawalNonce is syncronous (during the beta), the version of the nonce is inside the signature verification, so the user must use the getNextFisherWithdrawalNonce in EVVM to get the next nonce to use.

The function has the following steps:

• The user call the fisherWithdrawal function in the EVVM.
• The contract checks if the ERC-191 signature is valid, if it is not, the transaction will revert.
• Using the withdraw function allows the fishers to perform the withdraw.

---

Because the execution of the withdraw function is done in the EVVM, on this section we will not cover the full process of the withdraw, if you want to see the full process, please check the withdraw function in the EVVM documentation.

---