MangroveOffer
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
thiscontract'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 success
result.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 |