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

Place a dark order

Rest size in the sealed book, learn what has filled, collect the proceeds, and cancel or let the order expire.

A dark order fills only by crossing: it meets opposite orders at the pool's mid and never touches the curve, so it moves no price. What does not cross when it is processed rests in the market's sealed book and waits there for later orders, for a day at the most. The mechanism is told in Sealed orders and the price in The book and the pool's mid.

You need a sealed balance in the market that covers the order: see Deposit and withdraw. The SDK samples assume hadal, connection, payer, market and key as set up in the Quickstart.

The order

ChoiceSeen byMeaning
Marketthe chainThe pair. Its base token is what you buy or sell.
SideyouBuy or sell the base token.
SizeyouHow much of the base token.
LimityouThe order fills only while the pool's mid is inside it: at or below it for a buy, at or above it for a sell. The fill price is the mid, not the limit.
Expirythe chainRequired. A time in the future, at most one day after the order is placed. After it, anyone may cancel the order.

Side, size and limit are encrypted in your wallet, together with your wallet's address. The chain shows that your wallet placed a dark order in this market, its expiry, and later whether it rests.

What is locked

When the order is processed, the part that rests is locked: it leaves your sealed balance and is held with the order in the book.

  • A sell locks the resting size in the base token.
  • A buy locks the resting size at the limit in the quote token, plus the cross fee on that amount.

As the order fills, the lock is spent. A buy fills at the mid, which is at or below its limit, so a filled buy still holds the difference: it comes back when the order is cancelled.

Before anything is locked the balance must cover the whole order: its size in base for a sell, its size at the limit plus 0.3% in quote for a buy. An order the balance does not cover is void and locks nothing.

Place the order

  1. Pick the market

    Open Trade and choose the pair in the market picker.

  2. Fill the ticket

    Select Dark order. Choose Buy or Sell, enter the Size and the Limit. The ticket starts the limit at the last sounding's price and reminds you: Fills only when the pool's mid is inside your limit. Choose the Expiry: 1 hour, 6 hours or 1 day.

  3. Press Place order and sign

    Press Place order and sign once. The ticket follows the order through In the queue and The cluster is computing, then shows the result: Resting in the book, Partly filled, the rest is resting, or Filled when the whole size crossed at once.

Placing is one transaction that creates the order's account and gives it the next place in the market's queue, exactly as for a swap. The program refuses it with InvalidExpiry when the expiry is not in the future or is more than one day ahead of the chain's clock.

The order is pending until its turn. The queue shows how to read its position, and how to cancel it while it is pending.

After the order is processed

The order's receipt holds what happened at that moment.

FieldUnitAfter the order is processed
okbooleanFalse when the order was void.
filledbase atomsWhat crossed at once against orders already resting.
crossedbase atomsThe same amount: a dark order fills only by crossing.
quotequote atomsWhat that fill paid (a buy) or received (a sell), before the cross fee.
restedbase atomsWhat now waits in the book.
feequote atomsThe cross fee on what crossed at once.

What crossed at once is settled in your sealed balance by the same computation. What rests is locked with the order.

A dark order takes a place in the book only while something of it rests there. The computation reveals one thing, whether the order rests, and the order's public status follows it:

  • resting when part of the size is left: rested is above zero.
  • closed when nothing is left to rest: the whole size crossed at once, or the order was void.

A resting order is listed under Open orders on Trade and under Resting and pending orders on Portfolio. Its row shows the order, the market, its Size, its Limit, Filled at placing and the status Resting, with the buttons Collect and Cancel.

Filled at placing is what crossed when the order was processed. The table has no figure for fills since then: press Collect to learn them.

Fills while resting

A resting order fills when a later order on the other side is processed, the pool's mid is inside both limits, and the later order still has size left. The trade happens at the mid. Each side pays the cross fee: see Fees.

The fill is written into the book, which is sealed to the cluster alone. It adds to the order's proceeds, held with the order: quote for a sell, net of the cross fee, and base for a buy. Nothing on chain changes that anyone can read, you included: the order's public status stays resting, your sealed balance is not touched, and the order's receipt is still the one from the moment it was processed.

You learn how much has filled when a computation of your own writes a new receipt for the order. There are two: Collect and Cancel.

Collect

Collect moves the order's proceeds into your sealed balance and leaves the order resting with whatever size it still has. It is also how you read what has filled so far.

Press Collect on the order's row and sign. Every resting order has the button, whether or not anything has filled. The app confirms Collected: the proceeds are in your sealed balance.

The receipt of a collect holds what was credited:

FieldA sellA buy
filled0Base atoms bought since the last collect
quoteQuote atoms received since the last collect, net of the cross fee0

For a buy, filled is exactly the size that has filled since the last collect. For a sell, quote is what those fills paid you. Both are zero when nothing has crossed. The other fields of the receipt are zero and ok is true. A collect replaces the order's earlier receipt, so read the first one before you collect if you need what it rested.

Only the order's owner can collect, and only while the order is resting: on any other order the program answers NotResting. A collect is a computation, paid for by the wallet that sends it: see Measured figures. What awaitComputation reports is told in Deposit and withdraw.

A resting order whose whole size has filled since it was placed keeps its status resting and its place in the book until it is cancelled.

Cancel

Press Cancel on the order's row and sign. A pending order and a resting order both have the button. The app confirms Order cancelled: the remainder and the proceeds are back in your sealed balance.

What a cancel does depends on where the order is.

A pending order closes in the cancelling transaction itself, with no computation. Nothing was locked yet, so nothing returns, and the order has no receipt. Only its owner can cancel it, and the cancel is refused with Busy while the market has a computation in flight.

A resting order is closed by a computation that returns what is still locked and any proceeds not yet collected to the owner's sealed balance, and frees the order's place in the book. Its receipt holds what was credited:

FieldA sellA buy
filledBase atoms returned: the size that never filledBase atoms bought and not yet collected
quoteQuote atoms received and not yet collectedQuote atoms returned: the lock that was not spent

For a sell, what filled while resting is rested from the first receipt less the base returned here.

Expiry

Every dark order has an expiry, and it is public. What it does depends on where the order is when it passes.

  • Still pending. An order whose expiry has passed when its turn comes is closed without a computation. Nothing moved and it has no receipt.
  • Resting. Once the expiry has passed, anyone may send the cancel for the order, and what it returns goes to the owner's sealed balance, never to the sender. Until that cancel lands, the order is still resting and can still fill.

States of a dark order

StateStatusWhat it means and what to do
In the queuependingWaiting for its turn. Nothing is locked. You can cancel it.
RestingrestingPart of it is in the book. Collect to take proceeds and read fills, cancel to close it.
Filled at onceclosedThe whole size crossed when it was processed. The fill is in your balance and the receipt holds it. It took no place in the book.
VoidclosedThe balance did not cover the order: ok is false and nothing moved. Deposit, or place a smaller order.
CancelledclosedClosed by a cancel. A resting order returned its lock and proceeds.
Closed without a computationclosedIts expiry passed before its turn, your balance was held by another computation when its turn came, or every place in the book was taken. Nothing left your balance and it has no receipt. Place it again.

The cases of the last row, and how the app and the SDK show them, are told in Orders closed without a computation. The number of places in a book is in Book slots.

If the computation that processes the order expires, the order is still pending at the head of the queue: what follows is told for a swap. If the computation of a collect or a cancel expires, nothing has moved and the order is unchanged: send it again once the market's book and your balance have been released.

Next