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
Guides

Provide liquidity

Add both tokens of a market to its pool from your sealed balance, hold shares, earn the sweep fee, and remove the shares for both tokens.

A market's pool prices every trade in it and fills what the book cannot. You supply the pool from your sealed balance and hold shares in return. The shares live in the same sealed balance, beside the two tokens, and only you read how many you hold. What a pool is and how it prices is in Liquidity.

Before you add

You need a funded sealed balance in the market that holds both tokens: liquidity enters the pool in the ratio of its two reserves. A balance that has never been funded is refused with EmptyBalance. Deposit and withdraw gets them there. The amounts you add are sealed with your reading key, so the app asks for Unlock first and the SDK takes the key as key.

Add liquidity

  1. Go to Pools

    Open Pools. The panel on the right is set to Add. Choose the Market. If your sealed balance in it lacks one of the two tokens, the button reads Deposit and leads to the portfolio.

  2. Enter the amount

    Enter the Amount in the base token, or press the maximum your sealed balance covers. The row With it, in the pool's ratio shows the quote token that goes in beside it, at the price of the last sounding. The app sends the two amounts as the most to add. Below are your sealed balance of each token and Your shares.

  3. Press Add liquidity

    Press Add liquidity and sign. The stages run: sealed in your wallet, signed, computed by the cluster. The app confirms with Liquidity added, and Your shares shows the new total.

Amounts outside the ratio

The two amounts are upper bounds. The cluster computes, against the pool's sealed reserves and share total:

text
shares     = min( base  × total shares / base reserve,
                  quote × total shares / quote reserve )   each rounded down
used base  = shares × base reserve  / total shares         rounded up
used quote = shares × quote reserve / total shares         rounded up

The token that buys fewer shares sets the result. Only used base and used quote leave your sealed balance. Whatever you offered beyond them of the other token stays in your sealed balance, untouched.

The reserves are sealed, so the ratio you add at is the ratio at the moment the computation runs. It follows the pool's price, which the last sounding shows.

The receipt of an add

FieldTypeMeaning
okbooleantrue when liquidity was added. false when the add was void.
filledbigintBase atoms that entered the pool.
quotebigintQuote atoms that entered the pool.
sweptbigintShares received.

The surface shows that your wallet changed its liquidity in this market. The amounts and the shares are sealed: see What is sealed and what is seen.

What the position is worth

Each share is a claim on the same fraction of both reserves. Your position is worth

text
base  = your shares × base reserve  / total shares
quote = your shares × quote reserve / total shares

The reserves and the share total are sealed, so the app shows an estimate made from your own sealed shares and the price of the last sounding:

text
quote = your shares / 2
base  = quote / price of the last sounding

It counts a share as it was issued when the pool opened, two shares for each quote atom, with half of the position in each token. The estimate is on Pools in the column Your share is worth, and on Portfolio in the columns Liquidity shares and Shares are worth, as an amount of the base token plus an amount of the quote token. The same estimate fills the row Returns, at the last sounding when you remove. All of it reads as sealed cells until you press Unlock. The exact amounts are the ones a removal credits.

From the SDK, the share count is in your sealed balance:

ts
const ledger = await hadal.balance(market, key)
const shares = ledger ? ledger.shares : 0n

What the position earns

The pool earns the sweep fee: the fee an order pays on the part it trades against the pool's curve. The fee stays in the pool's reserves, less the protocol's share of it, so every share's claim on the reserves grows with each sweep. Nothing is paid out separately and nothing needs collecting: what was earned comes back with the tokens when you remove.

Crosses in the book and deals do not trade against the pool and pay it no fee. The rates and the protocol's share are in Fees.

The Pools table shows, per market, the volume crossed and swept over 24 hours and Fees to LPs, last sounding.

Remove liquidity

  1. Switch the panel to Remove

    On Pools, choose Remove and the Market.

  2. Enter the shares

    Enter the Shares to remove, or press the maximum for all you hold. The row Returns, at the last sounding shows both amounts at that price.

  3. Press Remove liquidity

    Press Remove liquidity and sign. The app confirms with Liquidity removed. Both tokens are in your sealed balance, with the fees earned.

The cluster credits your sealed balance with

text
base  = shares × base reserve  / total shares     rounded down
quote = shares × quote reserve / total shares     rounded down

and takes the shares out of it. The receipt holds the base atoms credited in filled, the quote atoms credited in quote and the shares removed in swept. From the sealed balance, withdraw moves the tokens to your wallet.

Void adds and removals

An add or a removal that cannot be carried out is void. Nothing moves, the pool is unchanged, and the receipt in your sealed balance has ok false and every amount zero. The surface shows the same as for one that went through.

ActionVoid when
AddYour sealed balance holds less than the used base or the used quote, the amounts are too small to buy one share, or the share count is beyond the integer range.
RemoveThe shares are zero, more than your sealed balance holds, or all the shares the pool has. A pool is never emptied: its last holder keeps at least one share in it.

In the app a void add reads The sealed balance does not cover both amounts. Nothing moved. and a void removal More shares than the sealed balance holds. Nothing moved. Before signing, the form flags an amount above what your sealed balance covers and a share count above what you hold.

From the SDK, check receipt.ok after every add and removal:

ts
const ledger = await hadal.balance(market, key)
if (!ledger!.receipt.ok) {
  // void: nothing moved
}

Errors

The program refuses the transaction itself in these cases. Busy means your sealed balance or the market's book has a computation in flight: send again when it has landed.

ErrorCodeRaised when
Busy6001The market's book, the balance or the deal the instruction needs already has a computation in flight. Also raised by process_order, by cancel_order on a pending order and by fund_market while the market has one. Send again once that computation lands, or release it after it expires.
MarketNotReady6015The market's pool is not open yet. Raised by place_order, add_liquidity, remove_liquidity, open_deal and sound.
EmptyBalance6019The sealed balance has never had a computation land on it. Raised by withdraw, place_order, add_liquidity, remove_liquidity, open_deal and take_deal. Deposit first.

If the cluster does not finish the computation, nothing moved and awaitComputation throws at its timeout. The market and your balance are freed as told in Release instructions. The lifecycle of a computation is in Arcium.

Next