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
The Mangrove deployment that is allowed to call this for trade execution and posthook.
NO_ROUTER
constant for no router
REPOST_SUCCESS
The offer was successfully reposted.
NEW_OFFER_SUCCESS
New offer successfully created.
COMPLETE_FILL
The offer was completely filled.
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
mgv
contract IMangrove
The Mangrove deployment.
receive
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
MangroveOffer's constructor
Parameters
mgv
contract IMangrove
The Mangrove deployment that is allowed to call this for trade execution and posthook.
router
Contract's router getter.
if contract has a no router, function returns NO_ROUTER.
Return Values
[0]
contract AbstractRouter
the router.
makerExecute
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
thiscontract's account on Mangrove_
Parameters
order
struct MgvLib.SingleOrder
a data structure that recapitulates the taker order and the offer as it was posted on mangrove
Return Values
ret
bytes32
a bytes32 word to pass information (if needed) to the posthook
makerPosthook
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
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
takes care of status for reposting residual offer in case of a partial fill and logging of potential issues.
Parameters
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
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
router_
contract AbstractRouter
the new router contract that this contract should use. Use NO_ROUTER for no router.
approve
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
token
contract IERC20
the ERC20 token contract
spender
address
the approved spender
amount
uint256
the spending amount
Return Values
[0]
bool
result of token approval.
activate
performs the required approvals so as to allow this to interact with Mangrove on a set of assets.
Parameters
tokens
contract IERC20[]
the ERC20 this will approve to be able to trade on Mangrove's corresponding markets.
checkList
verifies that Mangrove is allowed to pull tokens from this contract.
throws with a reason if something (e.g. an approval) is missing.
Parameters
tokens
contract IERC20[]
the list of tokens that are traded by this contract
activate
override conservatively to define strat-specific additional activation steps.
Parameters
token
contract IERC20
the ERC20 one wishes this contract to trade on.
checkList
verifies that Mangrove is allowed to pull tokens from this contract and other strat specific verifications.
Parameters
token
contract IERC20
a token that is traded by this contract
withdrawFromMangrove
withdraws native tokens from this balance on Mangrove.
Since a call is made to the receiver, this function is subject to reentrancy.
Parameters
amount
uint256
the amount of WEI one wishes to withdraw.
receiver
address payable
the address of the receiver of the funds.
put
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
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
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
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
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
missingGet
uint256
(<=amount), which is the amount of outbound tokens still need to be fetched at the end of this function
lastLook
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
order
struct MgvLib.SingleOrder
is a recall of the taker order that is at the origin of the current trade.
Return Values
data
bytes32
is a message that will be passed to posthook provided makerExecute does not revert.
posthookFallback
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
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
data
bytes32
contains verdict and reason about the executed trade.
residualValues
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
order
struct MgvLib.SingleOrder
is a recall of the taker order that is being treated.
Return Values
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
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
order
struct MgvLib.SingleOrder
is a recall of the taker order that failed
posthookSuccess
Post-hook that implements default behavior when Taker Order's execution succeeded.
Parameters
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
data
bytes32
can be: * COMPLETE_FILL when offer was completely filled * returned data of _updateOffer signalling the status of the reposting attempt.
_updateOffer
Updates the offer specified by offerId on Mangrove with the parameters in args.
Parameters
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
[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
computes the provision that can be redeemed if deprovisioning a certain offer
Parameters
olKey
struct OLKey
the offer list key.
offerId
uint256
the id of the offer
Return Values
provision
uint256
the provision that can be redeemed