# 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 |