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
| Choice | Seen by | Meaning |
|---|---|---|
Market | the chain | The pair. Its base token is what you buy or sell. |
Side | you | Buy or sell the base token. |
Size | you | How much of the base token. |
Limit | you | The 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. |
Expiry | the chain | Required. 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
Pick the market
Open Trade and choose the pair in the market picker.
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.
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.
| Field | Unit | After the order is processed |
|---|---|---|
ok | boolean | False when the order was void. |
filled | base atoms | What crossed at once against orders already resting. |
crossed | base atoms | The same amount: a dark order fills only by crossing. |
quote | quote atoms | What that fill paid (a buy) or received (a sell), before the cross fee. |
rested | base atoms | What now waits in the book. |
fee | quote atoms | The 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:
restingwhen part of the size is left:restedis above zero.closedwhen 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:
| Field | A sell | A buy |
|---|---|---|
filled | 0 | Base atoms bought since the last collect |
quote | Quote atoms received since the last collect, net of the cross fee | 0 |
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:
| Field | A sell | A buy |
|---|---|---|
filled | Base atoms returned: the size that never filled | Base atoms bought and not yet collected |
quote | Quote atoms received and not yet collected | Quote 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
| State | Status | What it means and what to do |
|---|---|---|
In the queue | pending | Waiting for its turn. Nothing is locked. You can cancel it. |
Resting | resting | Part of it is in the book. Collect to take proceeds and read fills, cancel to close it. |
Filled at once | closed | The 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. |
Void | closed | The balance did not cover the order: ok is false and nothing moved. Deposit, or place a smaller order. |
Cancelled | closed | Closed by a cancel. A resting order returned its lock and proceeds. |
Closed without a computation | closed | Its 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.