The Order Book

At the core of Mangrove's trading model are offer lists. Each offer list represents one side of the market, either asks or bids.

Hence, a full market will always feature two offer lists. For instance, in a WETH/DAI market:

• WETH-DAI offer list, the asks: offers giving WETH and wanting DAI

• DAI-WETH offer list, the bids: offers giving DAI and wanting WETH

Together, these two lists form the on-chain order book for the market.

Mangrove's SDK offers Market abstractions that allows liquidity providers and takers to interact with Mangrove using standard trading concepts such as order book, base, and quote.

Offer List Identification

Each offer list is uniquely identified by a struct called OLKey:

struct OLKey {
  address outbound_tkn;
  address inbound_tkn;
  uint tickSpacing;
}

• outbound_tkn – token given by the offer

• inbound_tkn – token wanted by the offer

• tickSpacing – defines which price ticks are valid for that market

For instance, in the WETH–DAI offer list: outbound_tkn = WETH, inbound_tkn = DAI, and tickSpacing = 1.

How Offers Are Stored

Offers are grouped by their tick, a discrete price level, and organized in a FIFO, doubly-linked list. Within a given tick, offers are ordered by insertion time, so the earliest posted offer at that tick will execute first.

Note : If you haven't done it yet, we strongly suggest that you first get familiar with the Ticks, ratios, and prices page.

Example: WETH/DAI market​

Let’s look at both sides of a WETH/DAI market with tickSpacing = 1.

WETH-DAI (Asks)​

Tick	Ratio (DAI/WETH)	Offer ID	Gives (WETH)	Gas required	Maker Contract	Offer Gas Price
75171	1838.53	42	0.7	220,000	0x2468xyz...	160
75171	1838.53	96	1.3	280,000	0x1357klm...	140
75200	1843.87	7	0.6	210,000	0x3287opq...	190

DAI-WETH (Bids)

Tick	Ratio (WETH/DAI)	Offer ID	Gives (DAI)	Gas required	Maker Contract	Offer Gas Price
-75103	0.0005476	77	925.26	250,000	0x5678def...	150
-75103	0.0005476	177	916.47	270,000	0x9101ghi...	170
-75041	0.0005510	42	871.76	300,000	0x1234abc...	200

For bids, the ratio is the inverse, WETH/DAI instead of DAI/WETH.

Here:

• tick represents the discrete price level

• ratio is the derived price at that tick (in quote/base units)

• gives is the amount of outbound token offered

• gasreq and gasprice determine execution cost and bounty behavior

Key Fields

Field	Meaning
Offer ID	Unique identifier of the offer within its offer list. Two offers may share the same ID if they belong to different lists. (see offerId 42)
Gas Required (gasreq)	The maximum gas the offer’s maker contract can consume when called by Mangrove.
Maker Contract	The address that manages the offer. It can be an EOA or a maker contract, implementing makerExecute and makerPosthook.
Gas Price (gasprice)	The gas price covered by the offer’s provision. Must be at least Mangrove’s current gas price when posted.

We display human-readable amounts in the examples for readability, but on-chain Mangrove only works with raw token values and never uses the decimals of a token.

For simplicity, the tokens used in these examples have the same number of decimals (18). When that's not the case, care must be taken to handle decimals, especially for ratios.

See the Ticks, ratios, and prices page for a detailed discussion on decimals.

Offer List Configuration and Gas Cost

Each offer list has configuration parameters controlling how new offers are inserted and how gas usage is calculated. Some parameters are global, while others are offer list specific (see Governance for details).

Because of Mangrove’s fixed tree structure for ticks, the gas cost of posting, updating, or retracting an offer is bounded and predictable. The details are described in the annotated code of the Mangrove protocol.