Margin Pool

The MarginPool is a shared object that manages liquidity for a specific asset, enabling lenders to supply assets and margin traders to borrow them. Each margin pool tracks supply and borrow positions, accrues interest over time, and enforces risk parameters to maintain system health.

Margin pools use a shares-based accounting system where suppliers receive shares representing their proportion of the total supply. Interest accrues continuously, increasing the value of these shares over time. Borrowers can only borrow from pools that have enabled their specific DeepBook trading pool. The pool's current interest and risk settings, such as interest_rate, max_utilization_rate, protocol_spread, and min_borrow, are readable through the pool's read endpoints, and the pool emits InterestParamsUpdated when those interest rate parameters change.

What is a margin pool?

A margin pool is a shared, asset-specific liquidity contract on Sui. Lenders deposit assets into the pool and receive supply shares in return. Those shares increase in value as borrowers pay interest. Margin traders draw from the pool to fund leveraged positions on DeepBook.

Each pool enforces a set of risk parameters:

Supply cap: The maximum total amount of assets the pool accepts.
Max utilization rate: The maximum fraction of supplied assets that borrowers can use at one time. Keeping some assets liquid protects lenders who want to withdraw.
Min borrow: The smallest borrow amount the pool permits, preventing dust positions.
Protocol spread: The portion of interest income that goes to the protocol rather than suppliers.

How does interest accrual work?

Interest accrues based on the pool's utilization rate, which is the ratio of total borrowed assets to total supplied assets. As utilization rises, the interest rate increases. This incentivizes lenders to supply more capital and discourages over-borrowing.

Suppliers do not receive interest as direct token transfers. Instead, the value of each supply share increases over time. When you withdraw, you receive more tokens than you originally deposited because your shares are worth more.

The protocol captures a portion of the interest income as fees, set by the pool's protocol spread. These fees accumulate separately and split between the protocol, the pool maintainer, and supply referrals: 25% to the protocol, 25% to the maintainer, and 50% to supply referrals pro rata to referred shares. When a pool has no referred shares, that last half goes to the protocol and the maintainer instead.

How do borrowers access a margin pool?

A margin pool must explicitly allow a DeepBook trading pool (the DeepBook market for a specific trading pair) before traders can borrow from it. The pool records them in its allowed_deepbook_pools field, and deepbook_pool_allowed checks one. This design lets pool administrators control which markets can access the liquidity, limiting exposure to specific trading pairs.

Common workflow

The typical workflow for a lender interacting with a margin pool:

Mint a SupplierCap using mint_supplier_cap. The cap is a capability object: you pass it to supply and withdraw, and the pool tracks your position against it. One cap works across multiple pools.
Call supply with your SupplierCap and the assets you want to deposit. The pool records your shares. The referral parameter is an Option<ID>: pass some(id) to credit a referral with its pro rata share of the 50% referral split, or none if you have no referral.
Monitor the pool's interest rate and utilization rate using the read endpoints.
Call withdraw when you want to reclaim your assets plus accrued interest. The amount parameter is an Option<u64> denominated in tokens, not shares. Pass some(amount) to take a specific amount, or none to withdraw everything the cap holds.

Two things can cap a withdrawal below what your shares are worth. The pool's withdrawal rate limiter aborts with ERateLimitExceeded when recent withdrawals have used up the amount the limiter currently allows, so check get_available_withdrawal before you submit. The pool's vault also has to hold the assets: if borrowers have drawn them down, the call aborts with ENotEnoughAssetInPool until utilization falls.

API

Following are the different public functions that the MarginPool exposes.

Click to open

Mint a SupplierCap

Create a new SupplierCap that can be used to supply and withdraw from margin pools. One SupplierCap can be used across multiple margin pools. The system emits a SupplierCapMinted event when you mint a new supplier cap. Minting one emits a SupplierCapMinted event, and per-cap positions are readable through the user_supply_shares and user_supply_amount endpoints.