Hadal
Start trading
  • OverviewStart
  • QuickstartStart
  • What is sealed and what is seenStart
  • Sealed balancesConcepts
  • Sealed ordersConcepts
  • The book and the pool's midConcepts
  • DealsConcepts
  • SoundingsConcepts
Concepts

Liquidity

The constant-product pool of a market, how shares are issued and redeemed, what a liquidity provider earns, and when a change is void.

Every market has one pool: two reserves, base and quote, and a total of shares. The pool sets the mid every cross uses and trades against whatever a swap could not cross. Its reserves and its share total are sealed. A liquidity provider holds shares in a sealed balance and adds or removes with sealed amounts.

The curve

The pool is a constant-product curve. A sweep trades against it so that the product of the two reserves, before the fee, does not fall:

text
a buy of rem base pays      ceil(pool_quote * rem / (pool_base - rem))    quote
a sell of net base receives floor(pool_quote * net / (pool_base + net))   quote

Rounding is always in the pool's favour. The sweep fee comes on top for a buy and is taken from the base first for a sell. The whole sweep, with its limit check, is in Sealed orders.

Shares

Shares are the unit of ownership of the pool. Your shares over the pool's total is your part of both reserves.

The first shares

The creator of a market supplies the first liquidity from their wallet. Those two amounts are public and set the first price. When the pool opens, the creator's balance receives:

text
shares = 2 * quote

where quote is the quote atoms of that first liquidity. The first price, quote atoms per base atom, must be greater than zero and under 2^32, or the funding is refused with PriceOutOfRange. See Create a market.

Adding

Add liquidity takes two sealed amounts, base and quote, as the most you offer of each. The computation issues the shares both amounts can pay for and uses exactly the amounts those shares cost in the pool's ratio:

text
shares     = min(floor(base * total / pool_base), floor(quote * total / pool_quote))
used_base  = ceil(shares * pool_base / total)
used_quote = ceil(shares * pool_quote / total)

used_base and used_quote leave your balance and enter the reserves, and shares is added to your balance and to the total. Whatever you offered beyond the used amounts stays in your balance: offering more of one token than the ratio needs costs nothing.

The receipt holds filled = used_base, quote = used_quote and swept = shares.

ts
const add = await hadal.addLiquidity({ market, base: baseAtoms, quote: quoteAtoms, key })
// sign and send add.instructions with the wallet
await hadal.awaitComputation(add.computation!)
const ledger = await hadal.balance(market, key)

Removing

Remove liquidity takes one sealed amount, the shares to redeem. Both tokens return to your sealed balance:

text
out_base  = floor(shares * pool_base / total)
out_quote = floor(shares * pool_quote / total)

The shares leave your balance and the total. The receipt holds filled = out_base, quote = out_quote and swept = shares. To take the tokens to your wallet, Withdraw them from the balance afterwards.

When a change is void

A void change moves nothing: the pool and the balance are unchanged and the receipt has ok false.

Adding is void when any of these holds:

  • The amounts buy no share: shares computes to zero.
  • shares does not fit 64 bits. The products are taken in 128 bits, and a result too large for a share count voids the change.
  • used_base is more than the balance's base, or used_quote more than its quote.
  • The amounts were sealed for another address.

Removing is void when any of these holds:

  • shares is zero.
  • shares is more than the balance holds.
  • shares is the pool's whole total. The pool always keeps at least one share outstanding.
  • The shares were sealed for another address.

The sealed amounts and shares carry the address they were sealed for, and the computation compares it with the wallet that sent them. The SDK seals them with your own address, so this case is met only by ciphertext copied from someone else's transaction.

Before the computation, the program refuses either with MarketNotReady when the pool is not open, with EmptyBalance when your balance in the market has never been written, and with Busy while another computation is in flight on the market's book or on your balance. A balance is first written by a deposit landing or, for a market's creator, by the pool opening. See One computation at a time.

What is sealed

Adding and removing never touch a token account. Tokens move between your sealed balance and the sealed reserves inside one computation, and the amounts and the shares are ciphertext from the wallet onward. The chain shows that a wallet added or removed liquidity in a market. It does not show how much, and it does not show the reserves, the share total or anyone's shares.

What a liquidity provider earns

The sweep fee is paid into the pool. On every sweep the fee, less the protocol's share of it, stays in the reserves: in quote when the order bought, in base when it sold. No shares are issued for it, so each share redeems for more of both tokens than before. Rates and the exact amounts are in Fees.

Earnings are not paid out separately. They are in the reserves, and Remove liquidity returns them with the principal through out_base and out_quote.

Cross fees and deal fees are protocol fees and do not enter the reserves.

The pool under the book

The pool is what the book stands on.

  • It prices the book. Every cross trades at the pool's mid, so resting orders need no quote of their own.
  • It fills what the book cannot. A swap's remainder after the cross sweeps the curve inside its limit, so a swap does not depend on a resting order being there.
  • Its depth sets the price impact of that remainder. Crosses have none.

Next