Principal hooks

Customizing makerExecute​

Last look before trade​

Last look before trade

/// @notice Hook that implements a last look check during Taker Order's execution.
/// @param order is a recall of the taker order that is at the origin of the current trade.
/// @return data is a message that will be passed to posthook provided `makerExecute` does not revert.
/// @dev __lastLook__ should revert if trade is to be reneged on. If not, returned `bytes32` are passed to `makerPosthook` in the `makerData` field.
/// @custom:hook overrides of this hook should be conservative and call `super.__lastLook__(order)`.
function __lastLook__(MgvLib.SingleOrder calldata order) internal virtual returns (bytes32 data) {
  order; //shh
  data = bytes32(0);
}

See entire file on GitHub

• Input: taker order's recap data.

• Output: data to be passed to makerPosthook if the call does not throw.

• Default behavior: returns "mgvOffer/proceed".

• Usage: override to insert requirements so as to renege on trade prior to transferring funds, as lastLook is the first hook being called during an offer logic's execution

Managing taker's payment​

Managing taker's payment

///@notice Hook that implements where the inbound token, which are brought by the Offer Taker, should go during Taker Order's execution.
///@param amount of `inbound` tokens that are on `this` contract's balance and still need to be deposited somewhere
///@param order is a recall of the taker order that is at the origin of the current trade.
///@return missingPut (<=`amount`) is the amount of `inbound` tokens whose deposit location has not been decided (possibly because of a failure) during this function execution
///@dev if the last nested call to `__put__` returns a non zero value, trade execution will revert
///@custom:hook overrides of this hook should be conservative and call `super.__put__(missing, order)`
function __put__(uint amount, MgvLib.SingleOrder calldata order) internal virtual returns (uint missingPut);

See entire file on GitHub

• Inputs:

  • amount of inbound token received by the logic and that can still be relocated at the beginning of this hook.

  • taker order's recap data.

• Output: missingPut is the amount of inbound tokens whose location are not yet determined at the end of this hook's execution.

• Default behavior: leaves all inbound tokens allocated to the balance of the maker contract and returns 0.

• Usage: override to change the location where taker's payment should be deposited. Override this only if this is important for outbound tokens delivery (for instance if inbound tokens are used to borrow).

Sourcing liquidity​

Sourcing liquidity

///@notice Hook that implements where the outbound token, which are promised to the taker, should be fetched from, during Taker Order's execution.
///@param amount of `outbound` tokens that still needs to be brought to the balance of `this` contract when entering this function
///@param order is a recall of the taker order that is at the origin of the current trade.
///@return missingGet (<=`amount`), which is the amount of `outbound` tokens still need to be fetched at the end of this function
///@dev if the last nested call to `__get__` returns a non zero value, trade execution will revert
///@custom:hook overrides of this hook should be conservative and call `super.__get__(missing, order)`
function __get__(uint amount, MgvLib.SingleOrder calldata order) internal virtual returns (uint missingGet);

See entire file on GitHub

• Input:

  • amount of outbound tokens that needs to be brought to the balance of the maker contract at the beginning of this hook's execution (in order to comply with the taker's order).

  • taker order's recap data.

• Output: missingGet is the amount of outbound tokens that still need to be brought to the balance of the maker contract at the end of this hook's execution.

• Default behavior: returns the difference between the outbound token balance of the maker contract and amount if positive and 0 otherwise.

• Usage: override this hook to define a more complex strategy for sourcing liquidity (for instance redeem from a lender, transfer outbound token from an EOA etc.). This hook is used to call the logic's router if any.

Customizing makerPosthook​

Posthook after trade success​

Posthook after trade success

///@notice Post-hook that implements default behavior when Taker Order's execution succeeded.
///@param order is a recall of the taker order that is at the origin of the current trade.
///@param makerData 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 data can be:
/// * `COMPLETE_FILL` when offer was completely filled
/// * returned data of `_updateOffer` signalling the status of the reposting attempt.
/// @custom:hook overrides of this hook should be conservative and call `super.__posthookSuccess__(order, maker_data)`
function __posthookSuccess__(MgvLib.SingleOrder calldata order, bytes32 makerData)
  internal
  virtual
  returns (bytes32 data)

See entire file on GitHub

• Input:

  • taker order's recap data.

  • maker_data either the message returned by makerExecute's last look if trade execution did not revert, or the revert reason (truncated to its first 32 bytes).

• Output: a bytes32 makerData that can be passed to the overridden hook and ignored otherwise.

• Default behavior: reposts offer residual in case of a partial fill, adapting what the offer gives to match the original price of the offer.

• Usage: this hook is only reached in the offer logic if trade was settled correctly by Mangrove. Override this hook to customize what should be done after the maker offer was taken (market makers would post an offer on the other side of the spread for instance).

Posthook after trade failure​

Posthook after trade failure

///@notice Post-hook that implements fallback behavior when Taker Order's execution failed unexpectedly.
///@param order is a recall of the taker order that is at the origin of the current trade.
///@param result contains information about trade.
///@return data contains verdict and reason about the executed trade.
///@dev `result.mgvData` is Mangrove's verdict about trade success
///@dev `result.makerData` either contains the first 32 bytes of revert reason if `makerExecute` reverted or the returned `bytes32`.
/// @custom:hook overrides of this hook should be conservative and call `super.__posthookFallback__(order, result)`
function __posthookFallback__(MgvLib.SingleOrder calldata order, MgvLib.OrderResult calldata result)
  internal
  virtual
  returns (bytes32 data)

See entire file on GitHub

• Input:

  • taker order's recap data.

  • result Mangrove recap of failed trade data result

• Output: a bytes32 data that can be passed to the overridden hook and ignored otherwise.

• Default behavior: Skipped.

• Usage: this hook is only reached in the offer logic if trade was not settled correctly by Mangrove. Override this hook to customize what should be done after the maker offer has failed. Note that if this hook is reached during offer logic's execution, maker contract has already emitted the following log:

Offer logic's incident log

///@notice Log incident (during post trade execution)
///@param olKeyHash the hash of the offer list key. This is indexed so that RPC calls can filter on it.
///@param offerId the Mangrove offer id. This is indexed so that RPC calls can filter on it.
///@param makerData from the maker.
///@param mgvData from Mangrove.
///@notice By emitting this data, an indexer can keep track of what incidents has happened.
event LogIncident(bytes32 indexed olKeyHash, uint indexed offerId, bytes32 makerData, bytes32 mgvData);

See entire file on GitHub