MgvReader

The MgvReader contract collects a number of view and pure functions that provide convenient views on Mangrove's state and various utilities for interacting with Mangrove.

Configuration view functions

Functions for reading the Mangrove global and local configurations as ABI compatible structs instead of the packed configurations used in Mangrove itself.

See the Governance Parameters section for more details.

function configInfo(olKey)

Returns both the global configuration for Mangrove and the configuration of the given offer list in ABI compatible structs.

function configInfo(OLKey memory olKey)
    external view
    returns (GlobalUnpacked memory _global, LocalUnpacked memory _local);

function globalUnpacked()

Returns the global configuration for Mangrove in an ABI compatible struct.

function globalUnpacked()
    external view
    returns (GlobalUnpacked memory);

function localUnpacked(olKey)

Returns the configuration of the given offer list in an ABI compatible struct.

function localUnpacked(OLKey memory olKey)
    external view
    returns (LocalUnpacked memory);

Offer view functions

function offerInfo(olKey, offerId)

Returns information about an offer in ABI compatible structs.

function offerInfo(OLKey memory olKey, uint offerId)
    external view
    returns (OfferUnpacked memory offer, OfferDetailUnpacked memory offerDetail);

Offer list view functions

Function isEmptyOB(olKey)

Returns true if the given offer list is empty.

function isEmptyOB(OLKey memory olKey)
    external view
    returns (bool);

Function offerListEndPoints(olKey, fromId, maxOffers)

Returns two uints (startId, length):

startId is either:

• fromId, if the offer with that is live,

• the id of the best live offer, or

• 0 if the offer list is empty.

length is 0 if startId == 0. Otherwhise, it is the number of live offers as good or worse than the offer with id startId, though it can max be maxOffers as the function will not traverse more than maxOffers before returning.

function offerListEndPoints(OLKey memory olKey, uint fromId, uint maxOffers)
    external view
    returns (uint startId, uint length);

Function packedOfferList(olKey, fromId, maxOffers)

Returns up to max number of offers from the given offer list, optionally starting from a certain offer ID, in packed form:

(uint nextOfferId, uint[] memory offerIds, Offer[] memory offers, OfferDetail[] memory offerDetails)

• nextOfferId is the id of next offer (0 means this is the last offer)

• offerIds is an array of offerIds in the order book

• offers (as bytes32) hold the core price volume information on offers

• offerDetails (as bytes32) holds maker address and provision/penalty-related info for offers.

The array will be of size min(# of offers in out/in list, maxOffers).

Refer to the Literate Source Code for Mangrove for more information on the structs used in Mangrove core.

function packedOfferList(OLKey memory olKey, uint fromId, uint maxOffers)
    external view
    returns (uint, uint[] memory, Offer[] memory, OfferDetail[] memory);

Function offerList(olKey, fromId, maxOffers)

As packedOfferList but returns the offers in ABI compatible structs:

function offerList(OLKey memory olKey, uint fromId, uint maxOffers)
    external view
    returns (uint, uint[] memory, OfferUnpacked[] memory, OfferDetailUnpacked[] memory);

function nextOfferIdById(olKey, offerId)

Get the ID of the offer after a given offer, given its id.

function nextOfferIdById(OLKey memory olKey, uint offerId)
    external view
    returns (uint);

function nextOfferId(olKey, offer)

Get the ID of the offer after a given offer.

function nextOfferId(OLKey memory olKey, Offer offer)
    external view
    returns (uint);

function prevOfferIdById(olKey, offerId)

Get the ID of the offer before a given offer, given its id.

function nextOfferId(OLKey memory olKey, Offer offer)
    external view
    returns (uint);

function prevOfferId(olKey, offer)

Get the ID of the offer before a given offer.

function prevOfferIdById(OLKey memory olKey, uint offerId)
    external view
    returns (uint);

Offer list utility functions

Function minVolume(olKey, gasreq)

Returns the minimum outbound_tkn volume that satisfies the %%density|density%% of the given offer list for an offer that requires gasreq gas.

function minVolume(OLKey memory olKey, uint gasreq)
    external view
    returns (uint);

Function getProvision(olKey, gasreq, gasprice)

Returns the provision necessary to post an offer that requires gasreq gas at gasprice on the given offer list. You can set gasprice=0 or use the next overload to use Mangrove's internal gasprice estimate.

function getProvision(OLKey memory olKey, uint gasreq, uint gasprice)
    external view
    returns (uint);

Function getProvision(olKey, gasreq)

Returns the provision necessary to post an offer that requires gasreq gas at Mangrove's internal gasprice estimate on the given offer list.

function getProvisionWithDefaultGasPrice(OLKey memory olKey, uint gasreq)
    external view
    returns (uint);

Function getFee(olKey, outVolume)

Returns the fee that would be extracted from the given volume of outbound_tkn tokens on the given offer list.

function getFee(OLKey memory olKey, uint outVolume)
    external view
    returns (uint);

Function minusFee(olKey, outVolume)

Returns the given amount of outbound_tkn tokens minus the fee on the given offer list.

function minusFee(OLKey memory olKey, uint outVolume)
    external view
    returns (uint);

Simulation functions

These functions are a cheaper way to approximate the results of a market order than by actually executing it and reverting.

The marketOrderBy* functions simulate a market order on Mangrove and returns the cumulative totalGot, totalGave and totalGasreq for each offer traversed:

struct VolumeData {
  uint totalGot;
  uint totalGave;
  uint totalGasreq;
}

In the simulation, it is assumed that offer execution is successful and uses exactly its gasreq.

The simulation does not account for gasbase. Furthermore:

• Calling this from an EOA will give you an estimate of the volumes you will receive, but you may as well eth_call Mangrove.

• Calling this from a contract will let the contract choose what to do after receiving a response.

Please refer to the section Market orders for more information on market orders and the function parameters.

Function simulateMarketOrderByTick(olKey, maxTick, fillVolume, fillWants)

Simulate a call to Mangrove.marketOrderByTick. Parameters are the same.

function simulateMarketOrderByTick(
    OLKey memory olKey, 
    Tick maxTick, 
    uint fillVolume, 
    bool fillWants
)
    external view
    returns (VolumeData[] memory);

Function simulateMarketOrderByTick(olKey, maxTick, fillVolume, fillWants, accumulate)

As the previous function, but optionally only return the total cumulative volume:

• If accumulate is false, only return the total cumulative volume.

• If accumulate is true, return the cumulative totalGot, totalGave, and totalGasreq for each offer traversed.

function simulateMarketOrderByTick(
    OLKey memory olKey, 
    Tick maxTick, 
    uint fillVolume, 
    bool fillWants,
    bool accumulate
)
    external view
    returns (VolumeData[] memory);

Function simulateMarketOrderByVolume(olKey, takerWants, takerGives, fillWants)

Simulate a call to Mangrove.marketOrderByVolume. Parameters are the same.

function simulateMarketOrderByVolume(
    OLKey memory olKey,
    uint takerWants,
    uint takerGives,
    bool fillWants
)
    external view
    returns (VolumeData[] memory);

Function simulateMarketOrderByVolume(olKey, takerWants, takerGives, fillWants, accumulate)

As the previous function, but optionally only return the total cumulative volume:

• If accumulate is false, only return the total cumulative volume.

• If accumulate is true, return the cumulative totalGot, totalGave, and totalGasreq for each offer traversed.

function simulateMarketOrderByVolume(
    OLKey memory olKey,
    uint takerWants,
    uint takerGives,
    bool fillWants,
    bool accumulate
)
    external view
    returns (VolumeData[] memory);

Open markets tracking

Mangrove itself does not provide a way to enumerate the currently open offer lists. Instead, open markets can be tracked by off-chain indexing of the SetActive event or by using the following functions in MgvReader.

MgvReader holds an array of open markets and this array can be permissionlessly updated using the updateMarket function. Mangrove governance will normally do this whenever a market is opened or closed.

Note that (contrary to Mangrove itself) these functions track markets, not just single offer lists. A market is modelled with this struct:

struct Market {
  address tkn0;
  address tkn1;
  uint tickSpacing;
}

This struct represents both offer lists of the market: (tkn0, tkn1, tickSpacing) and (tkn1, tkn0, tickSpacing).

Note that Market is non-oriented offer lists, ie. there is no base/quote orientation and Market(tkn0, tkn1, tickSpacing) is equivalent to Market(tkn1, tkn0, tickSpacing).

Functions that return the configuration of a market, returns the following struct which contains the configuration of both of the offer lists:

struct MarketConfig {
  LocalUnpacked config01;
  LocalUnpacked config10;
}

function numOpenMarkets()

Returns the number of open markets.

function numOpenMarkets()
    external view
    returns (uint);

function openMarkets()

Returns all open markets on Mangrove and their configurations.

If the $i$th market is (tkn0,tkn1,tickSpacing), then the $i$th config will be a MarketConfig where config01 is the config for the (tkn0,tkn1,tickSpacing) offer list, and config10 is the config for the (tkn1,tkn0,tickSpacing) offer list.

function openMarkets()
    external view
    returns (Market[] memory, MarketConfig[] memory);

function openMarkets(withConfig)

As openMarkets() but can optionally skip querying Mangrove for all the market configurations (in which case the returned configuration array will be empty).

function openMarkets(bool withConfig)
    external view
    returns (Market[] memory, MarketConfig[] memory);

function openMarkets(from, maxLen)

Get a slice of open markets, with accompanying market configs. The from parameter is an index into MgvReader's internal array of open markets.

function openMarkets(uint from, uint maxLen)
    external view
    returns (Market[] memory markets, MarketConfig[] memory configs)

function openMarkets(from, maxLen, withConfig)

As openMarkets(from, maxLen) but can optionally skip querying Mangrove for all the market configurations (in which case the returned configuration array will be empty).

function openMarkets(uint from, uint maxLen, bool withConfig)
    external view
    returns (Market[] memory markets, MarketConfig[] memory configs);

function isMarketOpen(market)

Returns true if market is open; otherwise, false.

NB: May not reflect the true state of the market on Mangrove if updateMarket was not called recently enough.

function isMarketOpen(Market memory market)
    external view
    returns (bool);

function marketConfig(market)

Return the configuration for the given market.

In the returned config struct, config01 and config10 follow the order given in arguments. I.e, config01 is the configuration for the (tkn0, tkn1, tickSpacing) offer list.

This function queries Mangrove so all the returned info is up-to-date.

function marketConfig(Market memory market)
    external view
    returns (MarketConfig memory config);

function updateMarket(market)

Permissionless update of MgvReader's state to reflect whether the given market is open or closed. Will consider a market open iff either of the offer lists identified by market are open on Mangrove.

Normally called by governance when a market is opened or closed.

function updateMarket(Market memory market)
    external;

Source Code

The MgvReader source is available.