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

Swap

Place a swap, follow it through the queue, and read each outcome it can end in.

A swap is the sealed order that trades now. When its turn comes it crosses the opposite resting orders in the book at the pool's mid, then sweeps the pool's curve for what is left, inside your limit. Whatever it does not fill stays in your sealed balance: a swap never rests. The mechanism is told in Sealed orders.

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, its quote token is what you pay or receive.
SideyouBuy or sell the base token.
SizeyouHow much of the base token.
LimityouThe worst price you accept, in quote per base. A buy pays no more than it, a sell accepts no less.

Side, size and limit are encrypted in your wallet before the order leaves it, together with your wallet's address: the cluster checks that the order was sealed by the wallet that placed it. The chain shows that your wallet placed a swap in this market, and nothing about it.

The balance must cover the order's worst case before anything trades. A sell needs its size in the base token. A buy needs its size at the limit in the quote token, plus 0.3% of that for the fee. An order the balance does not cover is void.

The limit does two things. The order crosses the book only while the pool's mid is inside it. And the remainder sweeps the curve only if the average price of that sweep, fee included, is inside it: the sweep takes all of the remainder or none of it.

The estimate

The ticket has a row that begins Estimate at the and names the time of the market's last sounding in UTC. Its figure is your size times that sounding's price. Under it is the fee at its highest, Fee, at most 0.30%, which is that estimate times the sweep rate.

The estimate is built from the last sounding because that is the newest price the chain has. The pool's reserves and the book are sealed, so nobody can quote the fill ahead of it. The order fills at the pool's mid and on its curve as they stand when the order is processed, and the receipt holds the real figures. The ticket fills the limit in from the same sounding, 0.5% above it for a buy and 0.5% below it for a sell, until you type your own.

With the SDK, the last sounding's price is in GET /v1/markets/:market. The rates are in Fees.

Place the swap

  1. Pick the market

    Open Trade and choose the pair in the market picker above the chart.

  2. Fill the ticket

    Keep Swap selected. Choose Buy or Sell, enter the Size in the base token, and set the limit: Limit: pay no more than for a buy, Limit: accept no less than for a sell. The ticket shows your sealed balances of both tokens. Max fills in the size your balance covers at the limit, the fee included, and a larger size is marked with what the balance covers.

  3. Press Swap and sign

    Press Swap and sign once. The ticket follows the order: Sealing in your wallet, Waiting for your signature, In the queue with its position, The cluster is computing, then the result.

If the ticket shows Unlock, unlock first. If it shows Deposit, your balance in this market is empty: the button leads to the deposit form.

Placing is one transaction. It creates the order's account, for which your wallet pays the rent, and gives the order the next place in the market's queue. It queues no computation and moves no balance.

The order's address is derived from the market's next queue sequence at the moment the SDK builds the instruction. If another order takes that sequence before yours is confirmed, your transaction is refused: build the action again and send it.

The program refuses the transaction with EmptyBalance when nothing has ever landed in your balance in this market, and with MarketNotReady when the market's pool has not opened.

The queue

Orders in a market are processed one at a time, in the order they were placed. While yours waits, its status is pending.

The ticket shows In the queue with position N. The order is also listed under Open orders with the same status and a Cancel button, and the bar shows how many of your orders are in the queue.

Cancel while pending

A pending order can be cancelled by its owner. It closes in the cancelling transaction itself, with no computation: nothing was taken from the balance, and the order has no receipt.

Press Cancel on the order's row under Open orders and sign. The app confirms Order cancelled.

While the market has a computation in flight, the cancel of a pending order is refused with Busy, because the order may be the one being computed. Send it again a moment later.

Outcomes

When the order has been processed its status is closed and its receipt says how it ended. A swap ends in one of four ways.

OutcomeReceiptWhat happened and what to do
Filledfilled equals the sizeThe whole size traded: crossed is what met resting orders at the mid, swept is what traded on the curve. Your balance holds the result.
Partly filledfilled below the size, swept 0Part crossed the book at the mid. The curve could not fill the remainder inside your limit, so the remainder stayed in your balance. Place a new swap for it, with a wider limit if you want it filled now.
Returned unfilledok true, filled 0The limit was not met: the mid was outside it, or nothing crossed and the sweep was outside it. Nothing moved. Place it again with another limit, or as a dark order that waits at your price.
Voidok falseThe balance did not cover the worst case of the order, or an amount in it does not fit the integer range. Nothing moved. Deposit, or place a smaller order.

The integer ranges are in Limits and measured figures.

The ticket shows the result under the button: Filled, Partly filled or Returned unfilled, with the rows Filled (amount and average price), Crossed at the mid, Swept the curve, Returned to your balance and Fee. A void order shows Order void and the reason. The receipt then stays under Receipts on Trade and on Portfolio.

Orders closed without a computation

So that no order can hold a market's queue, the order at its head is closed without being computed in these cases. Nothing moves, the order's status becomes closed, and it has no receipt.

CaseWhat to do
CancelledYou cancelled it while it was pending.
Balance busyWhen its turn came, your balance in the market was held by another computation: a deposit, a withdrawal, a collect, a liquidity change or a deal still in flight. Wait for that to land, then place the order again.
Expiry passedA dark order whose expiry passed before its turn. A swap has no expiry.
Book fullA dark order that found every place in the book taken.

The chain shows that the order was returned and which case it was, as the reason of the OrderReturned event: see the program reference.

The ticket ends in Not placed, the order leaves Open orders, and no row is added to Receipts.

The receipt of a swap

FieldUnitMeaning for a swap
okbooleanFalse when the order was void.
filledbase atomsWhat traded: crossed plus swept.
quotequote atomsWhat the fill paid (a buy) or received (a sell). The sweep fee is inside this figure. The cross fee is not.
crossedbase atomsThe part that met resting orders, at the pool's mid.
sweptbase atomsThe part that traded on the curve.
restedbase atomsAlways 0 for a swap.
feequote atomsThe cross fee on what crossed plus the sweep fee on what swept.

The average price is quote divided by filled: priceOf(receipt.quote, receipt.filled) gives it in the unit of a limit. A buy takes quote plus the cross fee out of your quote balance and adds filled to your base balance. A sell takes filled out of your base balance and adds quote less the cross fee to your quote balance. Read your receipts covers the receipt in full.

When a computation expires

Processing an order is a computation on the cluster. If the cluster does not take it up within 180 slots, the computation expires and nothing has changed: no balance moved and the order has no receipt. The order is still pending at the head of the queue, and the market's book and your balance stay held by the expired computation until each is released, after the release window.

What happens next depends on the order of the releases. When your balance has been released (reclaim) by the time the order is run again, the order is processed as if for the first time. When only the market has been released, the order finds your balance still held and is closed without a computation, as a balance busy order: place it again.

The order stays under Open orders as In the queue while it is pending, and leaves the list if it is closed. There is nothing to sign again unless you place a new order.

The lifecycle of a computation is told in Arcium and the trust model, and which release follows which expired computation in Release instructions.

Next