Skip to main content

Offer provisions


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.
function fund(address maker) public payable;


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

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);


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


  • balance is the available balance of maker.


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.

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


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


  • 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):

provision=max⁑(gaspricemgv,gaspriceofr)Γ—(gasreq+gasbasemgv)Γ—106\textrm{provision} = \max(\textrm{gasprice}_{\textrm{mgv}},\textrm{gasprice}_{\textrm{ofr}}) \times (\textrm{gasreq} + \textrm{gasbase}_{\textrm{mgv}}) \times 10^6​

  • gaspricemgv\textrm{gasprice}_{\textrm{mgv}} is the gasprice global governance parameter (in Mwei per gas unit)
  • gaspriceofr\textrm{gasprice}_{\textrm{ofr}} is the gasprice argument of the function being called (newOffer or updateOffer) also in Mwei per gas unit.
  • gasreq\textrm{gasreq} is the gasreq amount of gas units required to execute the offer.
  • gasbasemgv\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:

bounty=min⁑(offer.provision,(gasused+gasbasemgv)Γ—gaspricemgvΓ—106)\textrm{bounty} = \min(\textrm{offer.provision},(\textrm{gasused} + \textrm{gasbase}_{\textrm{mgv}}) \times \textrm{gasprice}_{\textrm{mgv}} \times 10^6)

  • offer.provision\textrm{offer.provision} is the provision amount calculated when the offer was posted.
  • gasused\textrm{gasused} is the gasused amount of gas units actually used when executing the offer.
  • gasbasemgv\textrm{gasbase}_{\textrm{mgv}} is the offer_gasbase local governance parameter.
  • gaspricemgv\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.