MangroveOffer

It contains the mandatory interface expected by Mangrove (IOfferLogic is IMaker) and enforces additional functions implementations (via IOfferLogic).

Naming scheme:f() public: can be used, as is, in all descendants of this contract_f() internal: descendant of this contract should provide a public wrapper for this function, with necessary guards.__f__() virtual internal: descendant of this contract should override this function to specialize it to the needs of the strat.

MGV

contract IMangrove MGV

The Mangrove deployment that is allowed to call this for trade execution and posthook.

NO_ROUTER

contract AbstractRouter NO_ROUTER

constant for no router

REPOST_SUCCESS

bytes32 REPOST_SUCCESS

The offer was successfully reposted.

NEW_OFFER_SUCCESS

bytes32 NEW_OFFER_SUCCESS

New offer successfully created.

COMPLETE_FILL

bytes32 COMPLETE_FILL

The offer was completely filled.

Mgv

event Mgv(contract IMangrove mgv)

The Mangrove deployment that is allowed to call this for trade execution and posthook. By emitting this event, an indexer will be able to create a mapping from this contract address to the used Mangrove address.

Parameters

Name	Type	Description
mgv	contract IMangrove	The Mangrove deployment.

receive

receive() external payable virtual

Mandatory function to allow this to receive native tokens from Mangrove after a call to MGV.withdraw(...,deprovision:true)

override this function if this contract needs to handle local accounting of user funds.

constructor

constructor(contract IMangrove mgv) internal

MangroveOffer's constructor

Parameters

Name	Type	Description
mgv	contract IMangrove	The Mangrove deployment that is allowed to call this for trade execution and posthook.

router

function router() public view returns (contract AbstractRouter)

Contract's router getter.

if contract has a no router, function returns NO_ROUTER.

Return Values

Name	Type	Description
[0]	contract AbstractRouter	the router.

makerExecute

function makerExecute(struct MgvLib.SingleOrder order) external returns (bytes32 ret)

makerExecute is the callback function to execute all offers that were posted on Mangrove by this contract.

_it may not be overriden although it can be customized using __lastLook__, __put__ and __get__ hooks. NB #1: if makerExecute reverts, the offer will be considered to be refusing the trade. NB #2: makerExecute may return a bytes32 word to pass information to posthook w/o using storage reads/writes. NB #3: Reneging on trade will have the following effects:

• Offer is removed from the Offer List

• Offer bounty will be withdrawn from offer provision and sent to the offer taker. The remaining provision will be credited to this contract's account on Mangrove_

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	a data structure that recapitulates the taker order and the offer as it was posted on mangrove

Return Values

Name	Type	Description
ret	bytes32	a bytes32 word to pass information (if needed) to the posthook

makerPosthook

function makerPosthook(struct MgvLib.SingleOrder order, struct MgvLib.OrderResult result) external

makerPosthook is the callback function that is called by Mangrove after the offer execution. reverting during its execution will not renege on trade. Revert reason (casted to 32 bytes) is then logged by Mangrove in event PosthookFail.

It cannot be overridden but can be customized via the hooks __posthookSuccess__, __posthookFallback__ and __handleResidualProvision__ (see below).

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	a data structure that recapitulates the taker order and the offer as it was posted on mangrove
result	struct MgvLib.OrderResult	a data structure that gathers information about trade execution

logRepostStatus

function logRepostStatus(struct MgvLib.SingleOrder order, bytes32 makerData, bytes32 repostStatus) internal

takes care of status for reposting residual offer in case of a partial fill and logging of potential issues.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	a recap of the taker order
makerData	bytes32	generated during makerExecute so as to log it if necessary
repostStatus	bytes32	from the posthook that handles residual reposting

setRouter

function setRouter(contract AbstractRouter router_) public virtual

sets a new router to pull outbound tokens from contract's reserve to this and push inbound tokens to reserve.

new router needs to be approved by this to push funds to reserve (see activate function). It also needs to be approved by reserve to pull from it.

Parameters

Name	Type	Description
router_	contract AbstractRouter	the new router contract that this contract should use. Use NO_ROUTER for no router.

approve

function approve(contract IERC20 token, address spender, uint256 amount) public returns (bool)

Approves a spender to transfer a certain amount of tokens on behalf of this.

admin may use this function to revoke specific approvals of this that are set after a call to activate.

Parameters

Name	Type	Description
token	contract IERC20	the ERC20 token contract
spender	address	the approved spender
amount	uint256	the spending amount

Return Values

Name	Type	Description
[0]	bool	result of token approval.

activate

function activate(contract IERC20[] tokens) external

performs the required approvals so as to allow this to interact with Mangrove on a set of assets.

Parameters

Name	Type	Description
tokens	contract IERC20[]	the ERC20 this will approve to be able to trade on Mangrove's corresponding markets.

checkList

function checkList(contract IERC20[] tokens) external view

verifies that Mangrove is allowed to pull tokens from this contract.

throws with a reason if something (e.g. an approval) is missing.

Parameters

Name	Type	Description
tokens	contract IERC20[]	the list of tokens that are traded by this contract

activate

function __activate__(contract IERC20 token) internal virtual

override conservatively to define strat-specific additional activation steps.

Parameters

Name	Type	Description
token	contract IERC20	the ERC20 one wishes this contract to trade on.

checkList

function __checkList__(contract IERC20 token) internal view virtual

verifies that Mangrove is allowed to pull tokens from this contract and other strat specific verifications.

Parameters

Name	Type	Description
token	contract IERC20	a token that is traded by this contract

withdrawFromMangrove

function withdrawFromMangrove(uint256 amount, address payable receiver) public

withdraws native tokens from this balance on Mangrove.

Since a call is made to the receiver, this function is subject to reentrancy.

Parameters

Name	Type	Description
amount	uint256	the amount of WEI one wishes to withdraw.
receiver	address payable	the address of the receiver of the funds.

put

function __put__(uint256 amount, struct MgvLib.SingleOrder order) internal virtual returns (uint256 missingPut)

Hook that implements where the inbound token, which are brought by the Offer Taker, should go during Taker Order's execution.

if the last nested call to __put__ returns a non zero value, trade execution will revert

Parameters

Name	Type	Description
amount	uint256	of inbound tokens that are on this contract's balance and still need to be deposited somewhere
order	struct MgvLib.SingleOrder	is a recall of the taker order that is at the origin of the current trade.

Return Values

Name	Type	Description
missingPut	uint256	(<=amount) is the amount of inbound tokens whose deposit location has not been decided (possibly because of a failure) during this function execution

get

function __get__(uint256 amount, struct MgvLib.SingleOrder order) internal virtual returns (uint256 missingGet)

Hook that implements where the outbound token, which are promised to the taker, should be fetched from, during Taker Order's execution.

if the last nested call to __get__ returns a non zero value, trade execution will revert

Parameters

Name	Type	Description
amount	uint256	of outbound tokens that still needs to be brought to the balance of this contract when entering this function
order	struct MgvLib.SingleOrder	is a recall of the taker order that is at the origin of the current trade.

Return Values

Name	Type	Description
missingGet	uint256	(<=amount), which is the amount of outbound tokens still need to be fetched at the end of this function

lastLook

function __lastLook__(struct MgvLib.SingleOrder order) internal virtual returns (bytes32 data)

Hook that implements a last look check during Taker Order's execution.

lastLook should revert if trade is to be reneged on. If not, returned bytes32 are passed to makerPosthook in the makerData field.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	is a recall of the taker order that is at the origin of the current trade.

Return Values

Name	Type	Description
data	bytes32	is a message that will be passed to posthook provided makerExecute does not revert.

posthookFallback

function __posthookFallback__(struct MgvLib.SingleOrder order, struct MgvLib.OrderResult result) internal virtual returns (bytes32 data)

Post-hook that implements fallback behavior when Taker Order's execution failed unexpectedly.

result.mgvData is Mangrove's verdict about trade successresult.makerData either contains the first 32 bytes of revert reason if makerExecute reverted or the returned bytes32.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	is a recall of the taker order that is at the origin of the current trade.
result	struct MgvLib.OrderResult	contains information about trade.

Return Values

Name	Type	Description
data	bytes32	contains verdict and reason about the executed trade.

residualValues

function __residualValues__(struct MgvLib.SingleOrder order) internal virtual returns (uint256 newGives, Tick newTick)

Given the current taker order that (partially) consumes an offer, this hook is used to declare how much order.olKey.outbound_tkn the offer gives after it is reposted, while also allowing adjustment to the tick.

default is to require the original amount of tokens minus those that have been sent to the taker during trade execution and keep the tick.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	is a recall of the taker order that is being treated.

Return Values

Name	Type	Description
newGives	uint256	the new volume of outbound_tkn the offer will give if fully taken.
newTick	Tick	the new tick of the reposted offer.

handleResidualProvision

function __handleResidualProvision__(struct MgvLib.SingleOrder order) internal virtual

Hook that defines what needs to be done to the part of an offer provision that was added to the balance of this on Mangrove after an offer has failed.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	is a recall of the taker order that failed

posthookSuccess

function __posthookSuccess__(struct MgvLib.SingleOrder order, bytes32 makerData) internal virtual returns (bytes32 data)

Post-hook that implements default behavior when Taker Order's execution succeeded.

Parameters

Name	Type	Description
order	struct MgvLib.SingleOrder	is a recall of the taker order that is at the origin of the current trade.
makerData	bytes32	is the returned value of the __lastLook__ hook, triggered during trade execution. The special value "lastLook/retract" should be treated as an instruction not to repost the offer on the list.

Return Values

Name	Type	Description
data	bytes32	can be: * COMPLETE_FILL when offer was completely filled * returned data of _updateOffer signalling the status of the reposting attempt.

_updateOffer

function _updateOffer(struct IOfferLogic.OfferArgs args, uint256 offerId) internal virtual returns (bytes32)

Updates the offer specified by offerId on Mangrove with the parameters in args.

Parameters

Name	Type	Description
args	struct IOfferLogic.OfferArgs	A memory struct containing the offer parameters to update.
offerId	uint256	An unsigned integer representing the identifier of the offer to be updated.

Return Values

Name	Type	Description
[0]	bytes32	status a bytes32 value representing either REPOST_SUCCESS if the update is successful, or an error message if an error occurs and OfferArgs.noRevert is true. If OfferArgs.noRevert is false, the function reverts with the error message as the reason.

_provisionOf

function _provisionOf(struct OLKey olKey, uint256 offerId) internal view returns (uint256 provision)

computes the provision that can be redeemed if deprovisioning a certain offer

Parameters

Name	Type	Description
olKey	struct OLKey	the offer list key.
offerId	uint256	the id of the offer

Return Values

Name	Type	Description
provision	uint256	the provision that can be redeemed