Creating & Updating offers
How to write Mangrovian offers
Posting a new offer
New offers should mostly be posted by contracts able to source liquidity when asked by Mangrove.
function newOffer(
address outboundTkn,
address inboundTkn,
uint wants, // amount of inbound Tokens
uint gives, // amount of outbound Tokens
uint gasreq,
uint gasprice,
uint pivotId
) external payable returns (uint offerId);
Inputs
outbound_tkn
address of the outbound token (that the offer will provide).inbound_tkn
address of the inbound token (that the offer will receive).wants
amount of inbound tokens requested by the offer. Must fit in auint96
.gives
amount of outbound **** tokens promised by the offer. Must fit in auint96
and be strictly positive. Must provide enough volume w.r.t togasreq
and offer list's density parameter.gasreq
amount of gas that will be given to the offer's account. Must fit in auint24
and be lower than gasmax. Should be sufficient to cover all calls to the offer logic posting the offer (makerExecute
andmakerPosthook
). Must be compatible with the offered volumegives
and the offer list's density parameter.gasprice
gas price override used to compute the order provision (see offer bounties). Any value lower than Mangrove's current gasprice will be ignored (thus 0 means "use Mangrove's current gasprice"). Must fit in auint16
.pivotId
where to start the insertion process in the offer list. IfpivotId
is not in the offer list at the time the transaction is processed, the new offer will be inserted starting from the offer list's best offer. Should be the id of the existing live offer with the price closest to the price of the offer being posted.
Outputs
offerId
the id of the newly created offer. Note that offer ids are scoped to offer lists, so many offers can share the same id.
Provisioning
Since offers can fail, Mangrove requires each offer to be provisioned in ETH. If an offer fails, part of that provision will be sent to the caller that executed the offer, as compensation.
Make sure that your offer is well-provisioned before calling newOffer
, otherwise the call will fail. The easiest way to go is to send a comfortable amount of ETH to Mangrove from your offer-posting contract. Mangrove will remember your ETH balance and use it when necessary.
Offer execution
If the offer account is a contract, it should implement the IMaker interface. At the very least, it must have a function with signature
makerExecute(MgvLib.SingleOrder calldata order)
or it will systematically revert when called by Mangrove.gives
andgasreq
are subject to density constraints on the amount of outbound token provided per gas spent.The offer account will need to give Mangrove a high enough allowance in outbound tokens since Mangrove will use the ERC20 standard's
transferFrom
function to source your tokens.
Updating an existing offer
Offers are updated through the aptly-named updateOffer
function described below (source code is here).
function updateOffer(
address outboundToken,
address inboundToken,
uint wants,
uint gives,
uint gasreq,
uint gasprice,
uint pivotId,
uint offerId
) external;
Inputs
offerId
is the offer id of the offer to be updated.For the other parameters, see above.
Outputs
None.
Reusing offers
After being executed or retracted, an offer is moved out of the offer list. It can still be updated and reinserted in the offer list. We recommend updating offers instead of creating new ones, as it costs much less gas.
Retracting an offer
An offer can be withdrawn from the order book via the retractOffer
function described below.
function retractOffer(
address outboundToken,
address inboundToken,
uint offerId,
bool deprovision
) external;
Inputs
offerId
is the offer id of the offer to be updated.deprovision
if true, will free the offer's ETH provision so that you can withdraw them. Otherwise, will leave the provision in the offer.For the other parameters, see above.
Outputs
None.
Last updated