Overview

Introduction

This section provides a technical overview of the Mangrove protocol, the core architecture, the roles of it's key participants, and the ideas that make Mangrove distinct from other decentralized exchanges.

Mangrove is an EVM-compatible order book DEX, build around the idea that liquidity should be programmable. Rather than requiring participants to lock tokens on-chain, Mangrove allows offers in its order book to represent promises to trade. (Commitments that can be fulfilled just-in-time through smart contracts execution.) This design makes liquidity reactive, composable, and more capital-efficient than traditional approaches.

Core Architecture

At the center of the Mangrove protocol is the Mangrove contract, which maintains on-chain order books called offer lists. Each market is represented by two offer lists, one for bids and one for asks. Each offer in an offer list is a record describing a proposed trade: its price, volume, and the address responsible for fulfilling it. When a taker places a market order, the Mangrove contract matches it against existing offers and coordinates the token transfers and callbacks needed to complete the trade. The diagram below illustrates this architecture, showing the four primary actors and how they interact with the Mangrove contract:

• Offer makers add liquidity promises to Mangrove.

• Takers find and consume liquidity by executing market orders, thereby executing offers published on Mangrove.

• Cleaners identify offers that fail to deliver the promised liquidity and remove them from the order book in exchange for a bounty.

• Governance manages protocol parameters such as fees and market configurations.

What Makes Mangrove Unique

The most fundamental difference between Mangrove and traditional DEXs lies in its treatment of liquidity. In Mangrove, liquidity is not locked; it is promised. This enables a range of new behaviors that are not possible in conventional AMM or order-book models.

Smart offers allow liquidity providers to react to market conditions at the exact moment of execution. When an offer is taken, the maker’s smart contract is called to determine how to settle the trade. The maker may fetch liquidity from another protocol, rebalance internally, or even decide not to trade if conditions have changed, a mechanism known as “last look.”

This approach allows makers to deploy capital efficiently across multiple venues without fragmenting liquidity. It also opens the door to fully automated strategies that behave more like programs than static limit orders.

To maintain integrity, the system introduces incentives for self-correction. If a smart offer fails to deliver on its promise (for instance, because the maker contract reverts), a third party can remove it from the order book and earn a bounty in return. This cleaning process keeps the book reliable and ensures that only executable offers remain visible to takers.

The Primary Actors

The Mangrove ecosystem revolves around four primary roles: makers, takers, cleaners, and governance.

Makers are the suppliers of liquidity. They own offers listed in the order book and are responsible for delivering tokens when their offers are taken. A maker can operate directly from an externally owned account (EOA), posting static offers backed by available tokens, or through smart offers, a dedicated maker contract that implements custom logic. The maker contract exposes two key callback functions: makerExecute, called when an offer is matched, and makerPosthook, called after the trade has been settled. These hooks allow a maker to provide liquidity on demand, manage inventory, or repost offers automatically.

Takers consume liquidity by executing market orders against the available offers. They query Mangrove’s order books, often through the TypeScript SDK or a web interface, and submit transactions to buy or sell at the best available price. Since the state of the book may evolve between query and execution, takers can define slippage limits and even simulate their trades locally before broadcasting them.

The diagram below summarizes the call sequence induced by a market order. Notice that first the makerExecute functions is executed for all offers, and only subsequently are the makerPosthook functions of the offers executed.

Cleaners are network participants that help maintain the health of the order book. Their role is to identify and remove failing offers, those that would revert if taken. When a cleaner successfully removes such an offer, they receive a bounty funded by the offer’s provision. This mechanism aligns incentives to keep the order book accurate without requiring centralized oversight.

Governance manages global and market-specific parameters of the Mangrove protocol. It can adjust fees, open or close trading pairs, and set limits or incentives that affect the behavior of the system. Governance ensures that Mangrove evolves in a controlled and transparent way, maintaining its decentralization and economic soundness.

Navigating the Technical Reference

The rest of the Technical Reference builds on the ideas introduced in this overview.

• Fundamentals introduces the core concepts — ticks, ratios, and prices — and explains the public data structures and parameters that define the Mangrove contract.

• Order Book & Offer Model describes how offers are represented and managed on-chain, including their lifecycle from creation to expiry and cleanup.

• Makers focuses on the maker side of the protocol, detailing how offers are created, updated, and executed through smart contracts, as well as how provisions and gas requirements are handled.

• Takers covers how market orders are formed and executed, how delegation works, and how the call sequence unfolds when an offer is taken.

• Maintenance & Safety explains the mechanisms that preserve the integrity of the order book, such as cleaning failed offers and adjusting governance parameters.

• Periphery presents supporting components like MgvReader, MgvOracle, and the Strat library, along with tools for integrating Mangrove through the TypeScript SDK.

• Literate Source Code provides a readable, annotated version of the core protocol’s source, following the principles of literate programming.