# 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 ```solidity contract IMangrove MGV ``` The Mangrove deployment that is allowed to call `this` for trade execution and posthook. ## NO\_ROUTER ```solidity contract AbstractRouter NO_ROUTER ``` constant for no router ## REPOST\_SUCCESS ```solidity bytes32 REPOST_SUCCESS ``` The offer was successfully reposted. ## NEW\_OFFER\_SUCCESS ```solidity bytes32 NEW_OFFER_SUCCESS ``` New offer successfully created. ## COMPLETE\_FILL ```solidity bytes32 COMPLETE_FILL ``` The offer was completely filled. ## Mgv ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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 ```solidity 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** ```solidity 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** ```solidity 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 ```solidity 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** ```solidity 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** ```solidity 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** ```solidity 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** ```solidity 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** ```solidity 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** ```solidity 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** ```solidity 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 ```solidity 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 ```solidity 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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mangrove.exchange/dev/strat-lib/technical-references/api-preferences/strats/src/strategies/mangroveoffer.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.