Offer provisions

Summary

When an offer fails, the caller has wasted some gas. To compensate the caller, Mangrove gives them a bounty in native tokens. Offers must provision enough native token to maximize the chances that Mangrove can compensate the caller. In more details:

• Every maker contract that posted an offer has a balance in native token held by Mangrove. Funds can be freely added to or withdrawn from the balance.
• Whenever the contract creates or updates an offer, its balance is adjusted so that enough native tokens are locked as the offer's provision.
  • If the offer is retracted that provision can either stay on the offer or the logic can choose to have it credited back to the logic's account balance.
  • If the offer logic is executed and fails, part or all of the provision is sent as compensation, to the caller. We call that the bounty. The rest of the provision is credited back to the maker contract's account balance.

Funding an offer

There are three ways a maker contract can credit its balance on Mangrove:

1. the contract may either call the fund function,
2. make a call to the fallback function with some value, or
3. pay on the fly when a new offer is posted or updated.

Signature

function fund(address maker) public payable;

Events

// Offer Maker at address `maker` has been credited of `amount` wei
event Credit(address maker, uint amount);

Revert strings

"mgv/dead" // Mangrove contract is no longer live

Solidity

import {IMangrove} from "@mgv/src/IMangrove.sol";

//context 
// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv)); // Mangrove contract
address maker_contract; // address of the maker contract one is willing to provision

// funding maker_contract
mgv.fund{value: 0.1 ether}(maker_contract);

// if funding oneself one can use the overload:
mgv.fund{value: 0.1 ether}();
// which is equivalent to `msg.fund{value:0.1 ether}(address(this))

// to avoid erreoneous transfer of native tokens to Mangrove, the fallback function will also credit `msg.sender`:
(bool noRevert,) = address(mgv).call{value: amount}("");
require(noRevert, "transfer failed");

Inputs

• maker: the maker who will be credited with msg.value on Mangrove

danger

Do not use send or transfer to credit Mangrove

Upon receiving funds, Mangrove will credit the amount sent to maker (or msg.sender if the receive function was called). This involves writing to storage, which consumes more gas than the amount given by send and transfer.

Checking an account balance

function balanceOf(address maker) external view returns (uint balance);

Inputs

• maker is the account of which you want to read the balance.

Outputs

• balance is the available balance of maker.

Withdrawing

At any time, your available balance can be withdrawn. It may be less than what you deposited: Your balance adjusts every time you create/update/retract an offer.

Signature

function withdraw(uint amount) external returns (bool noRevert);

Events

event Debit(address maker, uint amount);

Revert strings

// Trying to withdraw unavailable funds
"mgv/insufficientProvision"

Solidity

import {IMangrove} from "@mgv/src/IMangrove.sol";

//context 
// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv)); // Mangrove contract

uint wei_balance = mgv.balanceOf(address(this));
require(mgv.withdraw(wei_balance), "Mangrove failed to transfer funds");

Inputs

• amount the amount of native token (in wei) one wishes to withdraw from Mangrove's provisions.

Outputs

• noRevert whether the transfer was successful.

Important points

• The account credited will be msg.sender.
• amount must be $\leq$ your available balance (available with balanceOf)

Provision calculation

The provision is calculated with the following formula (in wei):

$\textrm{provision} = \max(\textrm{gasprice}_{\textrm{mgv}},\textrm{gasprice}_{\textrm{ofr}}) \times (\textrm{gasreq} + \textrm{gasbase}_{\textrm{mgv}}) \times 10^6$​

• $\textrm{gasprice}_{\textrm{mgv}}$ is the gasprice global governance parameter (in Mwei per gas unit)
• $\textrm{gasprice}_{\textrm{ofr}}$ is the gasprice argument of the function being called (newOffer or updateOffer) also in Mwei per gas unit.
• $\textrm{gasreq}$ is the gasreq amount of gas units required to execute the offer.
• $\textrm{gasbase}_{\rm mgv}$ is the offer_gasbase local governance parameter.

Balance adjustment when creating/updating offers

Whenever an offer is created or updated, Mangrove uses the Provision formula to get the offer's required provision in wei.

Mangrove will adjust the balance of the caller to ensure that provision wei are available as bounty if the offer fails. If the offer was already provisioned, the adjustment may be small, and the balance may actually increase -- for instance, if the gasprice dropped recently.

Incentivized book cleaning

Provisions are calculated so that, within reasonable gas estimates, taking a failing offer should be profitable for the taker.

Gas optimization

If you frequently update your offers, we recommend using a consistent, high gasprice argument, above the actual expected gas prices. Not changing gasprice when you call updateOffer will make the call cheaper (you save one SSTORE).

Bounty calculation

The bounty is paid to the taker as compensation for spent gas. It depends on how much gas the offer uses before failing. It is calculated with the following formula, based on the provision previously calculated:

$\textrm{bounty} = \min(\textrm{offer.provision},(\textrm{gasused} + \textrm{gasbase}_{\textrm{mgv}}) \times \textrm{gasprice}_{\textrm{mgv}} \times 10^6)$

• $\textrm{offer.provision}$ is the provision amount calculated when the offer was posted.
• $\textrm{gasused}$ is the gasused amount of gas units actually used when executing the offer.
• $\textrm{gasbase}_{\textrm{mgv}}$ is the offer_gasbase local governance parameter.
• $\textrm{gasprice}_{\textrm{mgv}}$ is Mangrove's global gasprice at the time of offer execution.

Thus the bounty is capped at the offer's original provision.