Views on offers

Mangrove provides a number of getter functions providing views on offers and %%offer lists|offer-list%%.

Public getters

best(OLKey memory olKey)

Info :

Returns the offerId of the best offer in the %%offer list|offer-list%%.

Solidity

import {IMangrove} from "@mgv/src/IMangrove.sol";
// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv));

// OLKey olkey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olkey = OLKey(address(base), address(quote), 1);

uint best = mgv.best(olkey);

offers() , offerDetails(), offerData(), and offerInfo()

• Mangrove.offers(OLKey memory olKey, uint offerId): get an offer in packed format.

• Mangrove.offerDetails(OLKey memory olKey, uint offerId): get an offer detail in packed format.

• Mangrove.offerData(OLKey memory olKey, uint offerId): get both offer and offer detail in packed format.

• MgvReader.offerInfo(OLKey memory olKey, uint offerId): get both offer and offer detail in unpacked format.

Info :

The data pertaining to a particular offer is contained in the OfferUnpacked and OfferDetailUnpacked structs, which are stored as packed custom types called, respectively, OfferPacked and OfferDetailPacked. For on-chain calls, Mangrove provides unpacking functions to extract a particular field out of a packed structure. For off-chain calls, Mangrove also provide direct getters for the unpacked structures.

Solidity

import {IMangrove} from "@mgv/src/IMangrove.sol";
import {MgvReader} from "@mgv/src/periphery/MgvReader.sol";
import "@mgv/src/core/MgvLib.sol";

// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mangroveAddress));

// MgvReader reader = MgvReader(<address of MgvReader>);
MgvReader reader = MgvReader(readerAddress);

// OLKey olKey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olKey = OLKey(address(base), address(quote), 1);

// Tick tick = TickLib.tickFromVolumes(<inbound amount>, <outbound amount>);
// ratio = <inbound amount> / <outbound amount>
Tick tick = TickLib.tickFromVolumes(5, 4);  // ratio = 5/4 = 1.25

// creates an offer at `tick` and store its ID in ofrId
// newOfferByTick(<offer list key>, <tick>, <gives>, <gasreq>, <gasprice>)
uint ofrId = mgv.newOfferByTick(olKey, tick, 1 ether, 10_000, 20);

// getting packed offer data
Offer offer = mgv.offers(olKey, ofrId);
OfferDetail detail = mgv.offerDetails(olKey, ofrId);
(offer, detail) = mgv.offerData(olKey, ofrId);

// for all fields f of OfferUnpacked
// offer.f == offer32.f()
// for all fields f of OfferDetailUnpacked
// offerDetail.f == offerDetail32.f()

// getting unpacked offer data
// MgvReader.offerInfo(<offer list key>, <offer ID>);
(OfferUnpacked memory offer, OfferDetailUnpacked memory offerDetail) =
  reader.offerInfo(olKey, offerId);

isLive(Offer offer)

Info :

An offer is live in a given Offer List if it can be matched during a market order. The view function isLive can be used to verify whether an ID identifies a live offer (i.e. gives is not zero) in its offer list.

Solidity

import {IMangrove} from "@mgv/src/IMangrove.sol";

// context of the call

// IMangrove mgv = IMangrove(payable(<address of Mangrove>));
IMangrove mgv = IMangrove(payable(mgv));

// OLKey olkey = OLKey(<address of outbound token>, <address of inbound token>, <tick spacing>);
OLKey memory olKey = OLKey(address(base), address(quote), 1);

// Tick tick = TickLib.tickFromVolumes(<inbound amount>, <outbound amount>);
// ratio = <inbound amount> / <outbound amount>
Tick tick = TickLib.tickFromVolumes(5, 4);  // ratio = 5/4 = 1.25

// creates an offer at `tick` and store its ID in ofrId
// newOfferByTick(<offer list key>, <tick>, <gives>, <gasreq>, <gasprice>)
uint ofrId = mgv.newOfferByTick(olKey, tick, 1 ether, 10_000, 20);

// checking whether the offer is live in the offer list
bool isLive = mgv.offers(olKey, ofrId).isLive();

Custom types

Info :

Offer data is split between OfferUnpacked and OfferDetailUnpacked for storage read/write optimisation (as both structs can be efficiently packed in storage).

OfferUnpacked

Field	Type	Comments
prev	uint	ID of the preceeding offer with the same tick (if the offer is live)
next	uint	ID of the next offer with the same tick (if the offer is live)
tick	Tick	The offer's "price" %%tick
gives	uint	The amount of outbound token the offer gives

OfferDetailUnpacked

Field	Type	Comments
maker	address	Address of the offer maker, either an EOA or a Maker contract
gasreq	uint	Gas required by the offer (in gas units)
kilo_offer_gasbase	uint	Mangrove's kilo_offer_gasbase at the time the offer was posted (in 1k gas units)
gasprice	uint	The gas price covered by the offer bounty (in Mwei per gas unit)