MevETH Contracts

As the name suggests, contacts are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your contacts. On this page, we'll dive into the different contact endpoints you can use to manage contacts programmatically. We'll look at how to query, create, update, and delete contacts.

State Variables

stakingPaused

Inidicates if staking is paused.

bool public stakingPaused;

initialized

Indicates if contract is initialized.

bool public initialized;

feeDenominator

withdraw fee denominator

uint16 internal constant feeDenominator = 10_000;

pendingStakingModuleCommittedTimestamp

Timestamp when pending staking module update can be finalized.

uint64 public pendingStakingModuleCommittedTimestamp;

pendingMevEthShareVaultCommittedTimestamp

Timestamp when pending mevEthShareVault update can be finalized.

uint64 public pendingMevEthShareVaultCommittedTimestamp;

MODULE_UPDATE_TIME_DELAY

Time delay before staking module or share vault can be finalized.

uint64 internal constant MODULE_UPDATE_TIME_DELAY = 7 days;

MAX_DEPOSIT

Max amount of ETH that can be deposited.

uint128 internal constant MAX_DEPOSIT = type(uint128).max;

MIN_DEPOSIT

Min amount of ETH that can be deposited.

uint128 public constant MIN_DEPOSIT = 0.01 ether;

mevEthShareVault

The address of the MevEthShareVault.

address public mevEthShareVault;

pendingMevEthShareVault

The address of the pending MevEthShareVault when a new vault has been comitted but not finalized.

address public pendingMevEthShareVault;

stakingModule

The staking module used to stake Ether.

IStakingModule public stakingModule;

pendingStakingModule

The pending staking module when a new module has been comitted but not finalized.

IStakingModule public pendingStakingModule;

WETH9

WETH Implementation used by MevEth.

WETH public immutable WETH9;

lastRewards

Last rewards payment by block number

uint256 internal lastRewards;

fraction

Struct used to accounting the ETH staked within MevEth.

Fraction public fraction;

CREAM_TO_MEV_ETH_PERCENT

The percent out of 1000 crETH2 can be redeemed for as mevEth

Taken from https://twitter.com/dcfgod/status/1682295466774634496 , should likely be updated before prod

uint256 public constant CREAM_TO_MEV_ETH_PERCENT = 1130;

creamToken

The canonical address of the crETH2 address

ERC20 public constant creamToken = ERC20(0x49D72e3973900A195A155a46441F0C08179FdB64);

lastDeposit

Sandwich protection mapping of last user deposits by block number

mapping(address => uint256) lastDeposit;

queueLength

The length of the withdrawal queue.

uint256 public queueLength;

requestsFinalisedUntil

mark the latest withdrawal request that was finalised

uint256 public requestsFinalisedUntil;

withdrawalAmountQueued

Withdrawal amount queued

uint256 public withdrawalAmountQueued;

withdrawalQueue

The mapping representing the withdrawal queue.

The index in the queue is the key, and the value is the WithdrawalTicket.

mapping(uint256 ticketNumber => WithdrawalTicket ticket) public withdrawalQueue;

Functions

constructor

Construction creates mevETH token, sets authority and weth address.

Pending staking module and committed timestamp will both be zero on deployment.

constructor(address authority, address weth, address layerZeroEndpoint) OFTWithFee("Mev Liquid Staked Ether", "mevETH", 18, 8, authority, layerZeroEndpoint);

Parameters

calculateNeededEtherBuffer

Calculate the needed Ether buffer required when creating a new validator.

function calculateNeededEtherBuffer() public view returns (uint256);

Returns

init

Initializes the MevEth contract, setting the staking module and share vault addresses.

This function can only be called once and is protected by the onlyAdmin modifier.

function init(address initialShareVault, address initialStakingModule) external onlyAdmin;

Parameters

_stakingUnpaused

Ensures that staking is not paused when invoking a specific function.

This check is used on the createValidator, deposit and mint functions.

function _stakingUnpaused() internal view;

pauseStaking

Pauses staking on the MevEth contract.

This function is only callable by addresses with the admin role.

function pauseStaking() external onlyAdmin;

unpauseStaking

Unauses staking on the MevEth contract.

This function is only callable by addresses with the admin role.

function unpauseStaking() external onlyAdmin;

commitUpdateStakingModule

Starts the process to update the staking module. To finalize the update, the MODULE_UPDATE_TIME_DELAY must elapse and the finalizeUpdateStakingModule function must be called.

This function is only callable by addresses with the admin role.

function commitUpdateStakingModule(IStakingModule newModule) external onlyAdmin;

Parameters

finalizeUpdateStakingModule

Finalizes the staking module update if a pending staking module exists.

This function is only callable by addresses with the admin role.

function finalizeUpdateStakingModule() external onlyAdmin;

cancelUpdateStakingModule

Cancels a pending staking module update.

This function is only callable by addresses with the admin role.

function cancelUpdateStakingModule() external onlyAdmin;

commitUpdateMevEthShareVault

Starts the process to update the share vault. To finalize the update, the MODULE_UPDATE_TIME_DELAY must elapse and the finalizeUpdateStakingModule function must be called.

This function is only callable by addresses with the admin role

function commitUpdateMevEthShareVault(address newMevEthShareVault) external onlyAdmin;

Parameters

finalizeUpdateMevEthShareVault

Finalizes the share vault update if a pending share vault exists.

This function is only callable by addresses with the admin role.

function finalizeUpdateMevEthShareVault(bool isMultisig) external onlyAdmin;

cancelUpdateMevEthShareVault

Cancels a pending share vault update.

This function is only callable by addresses with the admin role.

function cancelUpdateMevEthShareVault() external onlyAdmin;

createValidator

This function passes through the needed Ether to the Staking module, and the assosiated credentials with it

This function is only callable by addresses with the operator role and if staking is unpaused

function createValidator(IStakingModule.ValidatorData calldata newData, bytes32 latestDepositRoot) external onlyOperator;

Parameters

grantRewards

Grants rewards updating the fraction.elastic.

called from validator rewards updates

function grantRewards() external payable;

grantValidatorWithdraw

Allows the MevEthShareVault or the staking module to withdraw validator funds from the contract.

Before updating the fraction, the withdrawal queue is processed, which pays out any pending withdrawals.

This function is only callable by the MevEthShareVault or the staking module.

function grantValidatorWithdraw() external payable;

claim

Claim Finalised Withdrawal Ticket

function claim(uint256 withdrawalId) external;

Parameters

processWithdrawalQueue

Processes the withdrawal queue, reserving any pending withdrawals with the contract's available balance.

function processWithdrawalQueue(uint256 newRequestsFinalisedUntil) external onlyOperator;

asset

The underlying asset of the mevEth contract

function asset() external view returns (address assetTokenAddress);

Returns

totalAssets

The total amount of assets controlled by the mevEth contract

function totalAssets() external view returns (uint256 totalManagedAssets);

Returns

convertToShares

Function to convert a specified amount of assets to shares based on the elastic and base.

function convertToShares(uint256 assets) public view returns (uint256 shares);

Parameters

Returns

convertToAssets

Function to convert a specified amount of shares to assets based on the elastic and base.

function convertToAssets(uint256 shares) public view returns (uint256 assets);

Parameters

Returns

maxDeposit

Function to indicate the maximum deposit possible.

function maxDeposit(address) external view returns (uint256 maxAssets);

Returns

previewDeposit

Function to simulate the amount of shares that would be minted for a given deposit at the current ratio.

function previewDeposit(uint256 assets) external view returns (uint256 shares);

Parameters

Returns

_deposit

internal deposit function to process Weth or Eth deposits

function _deposit(address receiver, uint256 assets, uint256 shares) internal;

Parameters

deposit

Function to deposit assets into the mevEth contract

function deposit(uint256 assets, address receiver) external payable returns (uint256 shares);

Parameters

Returns

maxMint

Function to indicate the maximum amount of shares that can be minted at the current ratio.

function maxMint(address) external view returns (uint256 maxShares);

Returns

previewMint

Function to simulate the amount of assets that would be required to mint a given amount of shares at the current ratio.

function previewMint(uint256 shares) external view returns (uint256 assets);

Parameters

Returns

mint

Function to mint shares of the mevEth contract

function mint(uint256 shares, address receiver) external payable returns (uint256 assets);

Parameters

Returns

maxWithdraw

Function to indicate the maximum amount of assets that can be withdrawn at the current state.

function maxWithdraw(address owner) public view returns (uint256 maxAssets);

Parameters

Returns

previewWithdraw

Function to simulate the amount of shares that would be allocated for a specified amount of assets.

function previewWithdraw(uint256 assets) external view returns (uint256 shares);

Parameters

Returns

_withdraw

Function to withdraw assets from the mevEth contract

function _withdraw(bool useQueue, address receiver, address owner, uint256 assets, uint256 shares) internal;

Parameters

_updateAllowance

internal function to update allowance for withdraws if necessary

function _updateAllowance(address owner, uint256 shares) internal;

Parameters

withdraw

Withdraw assets if balance is available

function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);

Parameters

Returns

withdrawQueue

Withdraw assets or open queue ticket for claim depending on balance available

function withdrawQueue(uint256 assets, address receiver, address owner) external returns (uint256 shares);

Parameters

Returns

maxRedeem

Function to simulate the maximum amount of shares that can be redeemed by the owner.

function maxRedeem(address owner) external view returns (uint256 maxShares);

Parameters

Returns

previewRedeem

Function to simulate the amount of assets that would be withdrawn for a specified amount of shares.

function previewRedeem(uint256 shares) external view returns (uint256 assets);

Parameters

Returns

redeem

Function to redeem shares from the mevEth contract

function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets);

Parameters

Returns

max

Returns the largest of two numbers.

function max(uint256 a, uint256 b) internal pure returns (uint256);

min

Returns the smallest of two numbers.

function min(uint256 a, uint256 b) internal pure returns (uint256);

_isZero

Gas efficient zero check

function _isZero(uint256 value) internal pure returns (bool boolValue);

redeemCream

Redeem Cream staked eth tokens for mevETH at a fixed ratio

function redeemCream(uint256 creamAmount) external;

Parameters

receive

Only Weth withdraw is defined for the behaviour. Deposits should be directed to deposit / mint. Rewards via grantRewards and validator withdraws via grantValidatorWithdraw.

receive() external payable;

Events

MevEthInitialized

Event emitted when the MevEth is successfully initialized.

event MevEthInitialized(address indexed mevEthShareVault, address indexed stakingModule);

StakingPaused

Emitted when staking is paused.

event StakingPaused();

StakingUnpaused

Emitted when staking is unpaused.

event StakingUnpaused();

StakingModuleUpdateCommitted

Event emitted when a new staking module is committed. The MODULE_UPDATE_TIME_DELAY must elapse before the staking module update can be finalized.

event StakingModuleUpdateCommitted(address indexed oldModule, address indexed pendingModule, uint64 indexed eligibleForFinalization);

StakingModuleUpdateFinalized

Event emitted when a new staking module is finalized.

event StakingModuleUpdateFinalized(address indexed oldModule, address indexed newModule);

StakingModuleUpdateCanceled

Event emitted when a new pending module update is canceled.

event StakingModuleUpdateCanceled(address indexed oldModule, address indexed pendingModule);

MevEthShareVaultUpdateCommitted

Event emitted when a new share vault is committed. To finalize the update, the MODULE_UPDATE_TIME_DELAY must elapse and the finalizeUpdateMevEthShareVault function must be called.

event MevEthShareVaultUpdateCommitted(address indexed oldVault, address indexed pendingVault, uint64 indexed eligibleForFinalization);

MevEthShareVaultUpdateFinalized

Event emitted when a new share vault is finalized.

event MevEthShareVaultUpdateFinalized(address indexed oldVault, address indexed newVault);

MevEthShareVaultUpdateCanceled

Event emitted when a new pending share vault update is canceled.

event MevEthShareVaultUpdateCanceled(address indexed oldVault, address indexed newVault);

ValidatorCreated

Event emitted when a new validator is created

event ValidatorCreated(address indexed stakingModule, IStakingModule.ValidatorData newValidator);

Rewards

Event emitted when rewards are granted.

event Rewards(address sender, uint256 amount);

ValidatorWithdraw

Emitted when validator withdraw funds are received.

event ValidatorWithdraw(address sender, uint256 amount);

WithdrawalQueueOpened

Event emitted when a withdrawal ticket is added to the queue.

event WithdrawalQueueOpened(address indexed recipient, uint256 indexed withdrawalId, uint256 assets);

WithdrawalQueueClosed

event WithdrawalQueueClosed(address indexed recipient, uint256 indexed withdrawalId, uint256 assets);

CreamRedeemed

event CreamRedeemed(address indexed redeemer, uint256 creamAmount, uint256 mevEthAmount);

Structs

Fraction

Central struct used for share accounting + math.

struct Fraction {
    uint128 elastic;
    uint128 base;
}

WithdrawalTicket

Struct representing a withdrawal ticket which is added to the withdrawal queue.

struct WithdrawalTicket {
    bool claimed;
    address receiver;
    uint128 amount;
    uint128 accumulatedAmount;
}

The contact model

The contact model contains all the information about your contacts, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the contact and information about when they were last active on Protocol.

Properties

List all contacts

curl -G https://docs.meveth.org/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

{
  "has_more": false,
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      "username": "FrankMcCallister",
      "phone_number": "1-800-759-3000",
      "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
      "display_name": null,
      "conversation_id": "xgQQXg3hrtjh7AvZ",
      "last_active_at": 705103200,
      "created_at": 692233200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

Create a contact

curl https://docs.meveth.org/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d username="FrankMcCallister" \
  -d phone_number="1-800-759-3000" \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": null,
  "created_at": 692233200
}

Retrieve a contact

curl https://docs.meveth.org/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}

Update a contact

curl -X PUT https://docs.meveth.org/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d display_name="UncleFrank"

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": "UncleFrank",
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}

Delete a contact

curl -X DELETE https://docs.meveth.org/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"