Offer provisions

How taker compensation for failing offers works.

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 ethers to maximize the chances that Mangrove can compensate the caller. In more details:

• Every offer logic that posted an offer has a balance in ethers held by Mangrove. Funds can be freely added to or withdrawn from the balance.

• Whenever the logic 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 is credited back to the logic's account balance.

  • If the offer 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 offer logic's account balance.

Balance funding & withdrawal

Funding an offer

There are three ways an offer logic can credit its balance on Mangrove. (1) The logic may either call the fund function, or (2) make a call to the fallback function with some value, or (3) pay on the fly when a new offer is posted.

Signature

function fund(address maker) public payable;

Events

Revert string

Solidity

ethers.js

Inputs

• maker the offer logic's balance on Mangrove to credit

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 who) external view returns (uint balance);

Inputs

• who The account of which you want to read the balance.

Outputs

• balance The available balance of who.

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 an offer.

Signature

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

Events

Revert strings

Solidity

Inputs

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

Outputs

• noRevert whether the ether transfer was successful.

Important points

• The account credited will be msg.sender.

• amount must be $\leq$ your available balance (available with balanceOf)

Balance adjustment when creating/updating offers

Whenever an offer is created or updated, Mangrove applies to following formula to get the offer's required provision in wei:

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

• $\textrm{gasprice}_{\textrm{mgv}}$ is the gasprice global governance parameter (in gwei per gas units)

• $\textrm{gasprice}_{\textrm{ofr}}$ is the gasprice argument of the function being called (newOffer or updateOffer) also in gwei per gas units.

• $\textrm{gasreq}$ is the gasreq argument of the function being called (in gas units).

• $\textrm{gasbase}_{\rm mgv}$is the offer_gasbase local governance parameter.

Mangrove will adjust the balance of the caller to ensure that $\textrm{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).

Provision and offer bounty

Solidity snippet

getProvision.sol

import "src/IMangrove.sol";
import {MgvStructs} from "src/MgvLib.sol";
//context 
IMangrove mgv;
address outbound_tkn;
address inbound_tkn;
uint offer_gasreq;
(MgvStructs.GlobalPacked global32, MgvStructs.LocalPacked local32) = mgv.config(outbound_tkn, inbound_tkn);

// computing minimal provision to cover an offer requiring `offer_gasreq` gas units 
uint provision = (offer_gasreq + local32.offer_gasbase()) * global32.gasprice() * 10 ** 9;

with ethers.js

Applied bounty

Suppose an offer requires $g_{\mathsf{ofr}}$​ gas units to execute. As explained above, Mangrove will require the logic posting the offer to provision $\beta$ WEI. Suppo se the offer is executed during a Taker Order and fails after $g_{\mathsf{used}}$gas units ($g_\mathsf{used}<g_\mathsf{ofr}$). The portion of the bounty that will be transferred to the Offer Taker's account is $\dot G*(\dot g_0/n+\dot g_1+g_\mathsf{used})$ where $\dot G$​, $\dot g_0$, $n$ and $\dot g_1$are respectively the global.gasprice, local.overhead_gasbase, the number of offers executed during the take order, and the local.offer_gasbase values at the time the offer is taken (which may differ from their values at the time the offer was posted, as a consequence of some parameter changes by the governance).