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

Deals

A deal is a sealed order addressed to one counterparty, traded at the midpoint of two sealed limits.

A deal is a sealed order addressed to one counterparty, or to anyone holding its link. The maker opens it on a public side, buying or selling, and seals a size, a minimum size and a limit. A taker answers on the opposite side with a sealed size and a sealed limit. When the limits do not cross, nothing but "No deal" is revealed. A filled deal trades at the midpoint of the two limits, which the taker's receipt shows.

Maker accepts from here upTaker pays up to hereThe midpoint is the price
A maker selling and a taker buying. The limits overlap, so the answer trades at their midpoint.

To do it step by step, see Open a deal and Answer a deal.

The maker's terms

A deal has three sealed terms and five public ones.

Sealed termUnitMeaning
sizebase atomsThe most the deal trades. Greater than zero.
minimum sizebase atomsThe least one answer may take. At most the size.
limitpriceThe lowest price a selling maker accepts, or the highest a buying maker pays. Greater than zero.
Public termTypeMeaning
marketaddressThe market whose two tokens the deal trades. Its pool must be open, or the deal is refused with MarketNotReady.
sidebuy or sellWhether the maker buys or sells the base token. Public, so a counterparty knows what they answer.
takeraddress or noneThe one wallet that may answer. With none, any wallet but the maker may answer: this is a deal for anyone holding its link. Naming the maker is refused with InvalidCounterparty.
attempts1 to 255How many answers each taker may send. When the maker sets none, 3.
expiryUnix seconds, UTCThe last moment an answer is accepted. It must be in the future when the deal is opened, or the deal is refused with InvalidExpiry.

Amounts are in atoms and a limit is a price in the program's unit: see Units.

A deal's link is the address of its Deal account: /deals/ followed by that address. The account is derived from the maker's wallet and an id the maker picks for the deal, so it is known before the deal is opened. The link shows the market, the maker, the maker's side, the counterparty, the expiry and the attempts left. It never shows the size, the minimum size or the limit.

The escrow

Opening a deal moves its escrow out of the maker's sealed balance and into the deal, where only the cluster computes on it.

Maker's sideEscrow
SellThe size, in the base token.
BuyThe size at the maker's limit, plus the deal fee on that amount, in the quote token. Each is rounded up to a whole atom.

The maker must have deposited to the market before opening a deal: a balance that has never been funded is refused with EmptyBalance.

The computation that opens the deal reveals one thing: whether the escrow was taken. When it was, the deal's status becomes open. Otherwise the deal becomes void: nothing leaves the balance, and the receipt in the maker's balance reads not ok. The escrow is not taken when:

  • the sealed balance does not cover it,
  • the size or the limit is zero, or the minimum size is above the size,
  • the escrow amount does not fit the program's integer range (see Integer ranges),
  • the terms were sealed for an address other than the maker's (see Sealed inputs are bound to their sender).

A void deal cannot be answered or closed. Open a new one.

An answer

An answer is two sealed values: a size in base atoms and a limit. It carries no side: the taker trades the side opposite the maker's. When the maker sells, the taker buys and the limit is the most the taker pays. When the maker buys, the taker sells and the limit is the least the taker accepts.

The program accepts an answer when all of these hold.

RuleRefused with
The deal's status is open.DealNotOpen
The time is at or before the deal's expiry.DealExpired
The taker is not the maker.InvalidCounterparty
The deal names no taker, or names this wallet.NotCounterparty
The taker has deposited to the deal's market.EmptyBalance
The taker has attempts left on this deal.OutOfAttempts
No other computation is in flight on the deal or on the taker's balance.Busy

When an answer trades

The cluster compares the answer with the deal's sealed terms. It trades when all three hold:

  1. The limits cross. With a selling maker, the taker's limit is at or above the maker's. With a buying maker, it is at or below.
  2. The size meets the minimum. The size that would trade is the smaller of the answer's size and what is left of the deal. It must be greater than zero, and at least the maker's minimum size or all that is left when less than the minimum is left.
  3. The taker's sealed balance covers it. A buying taker holds the quote for the trade plus the fee. A selling taker holds the base.

An answer sealed for an address other than the taker's, or whose quote amount does not fit the program's integer range, does not trade.

Price, size and fee

QuantityHow it is set
PriceThe midpoint of the two limits: their sum divided by two, rounded down.
SizeThe smaller of the answer's size and what is left of the deal.
Quote tradedThe size at the price, rounded down to a whole quote atom.
FeeThe deal fee on the quote traded, charged to each side in the quote token. The buyer pays the quote traded plus the fee. The seller receives the quote traded less the fee.

The deal fee is 0.05% a side. Where it goes is told in Fees.

The trade moves between the taker's sealed balance and the deal. The taker's side settles at once: the tokens are in the taker's sealed balance when the answer lands. The maker's side stays in the deal as proceeds until the deal is closed.

Partial fills

An answer smaller than what is left trades its own size and leaves the deal open with the remainder. Further answers, from the same taker or another, trade against what is left under the same terms. When an answer takes all that is left, the deal becomes done.

What an answer reveals

An answer puts two facts on chain:

  • Traded or not. Deal done, or no deal.
  • Filled or not. Whether the deal has anything left.

When the limits do not cross, nothing but "No deal" is revealed. Neither limit and neither size reaches the chain, the maker or the taker. An answer under the minimum size, and an answer the taker's balance does not cover, read as the same "No deal".

A filled deal trades at the midpoint of the two limits, which the taker's receipt shows. The receipt is in the taker's sealed balance and holds the size filled, the quote traded and the fee. The chain shows that the deal was done. The size and the price stay between the two sealed balances.

The public fields and events of each step are listed in What is sealed and what is seen.

Attempts per taker

Every answer tells its taker one fact about the maker's limit: whether the taker's limit crossed it. The attempts set how many such facts one wallet can collect, so a limit cannot be found by probing.

The count is kept per taker per deal and is public. An attempt is counted when the answer is sent, whether or not it trades. A deal for anyone holding its link gives every wallet that answers its own count.

Statuses

StatusMeaning and what follows
openingThe deal exists and the computation that takes its escrow has not landed. It becomes open or void.
openThe escrow is in the deal and answers are accepted until the expiry. It becomes done when an answer takes all that is left, cancelled when the maker closes it, expired when it is closed after its expiry.
doneThe whole size traded. The maker's proceeds are in the deal until it is closed. Closing leaves the status done.
cancelledThe maker closed it while it was open. What was left of the escrow, and the proceeds of any partial fills, are back in the maker's sealed balance.
expiredIt was closed after its expiry. The same amounts are back in the maker's sealed balance.
voidThe escrow was not taken. Nothing left the maker's balance.

On chain a deal past its expiry keeps the status open until someone closes it. Answers are refused from the expiry on. The HTTP API gives the same status as the account, with the deal's expiry beside it: see GET /v1/deals/:id.

If the computation that opens a deal does not finish, the deal waits in opening with no escrow. Once the release window has passed, release_deal (releaseDeal in the SDK) makes it void, and reclaim frees the maker's balance. Any wallet may send either. Then open a new deal. See When a computation does not finish.

Closing a deal

Closing is one computation. In the app it is Cancel deal on an open deal and Close deal on a done or expired one. In the SDK it is cancelDeal for all three.

The deal isWho may close itStatus after
open, before its expiryThe maker. Anyone else is refused with NotOwner.cancelled
open, after its expiryAnyoneexpired
doneAnyonedone

Closing returns two amounts to the maker's sealed balance, whoever sends it: what is left of the escrow, and the proceeds of every fill. For a buying maker the escrow left includes the difference between the maker's limit and the midpoints the deal traded at. The receipt in the maker's balance holds the base and the quote returned.

Closing is also when the deal reaches the market's pool: the fees both sides paid and the quote volume of its fills are added to the pool's figures for the current interval, and appear in the next sounding as protocol fees and crossed volume. A deal that traded and is not yet closed is in no sounding.

A deal closes once. Closing it again, or closing an opening or void deal, is refused with DealNotOpen. Closing waits its turn behind any computation on the deal, the maker's balance or the market's book, and is refused with Busy while one is in flight.

Reading your own terms

The maker's three sealed terms are stored on the deal as ciphertext sealed to the maker's reading key. The maker reads them back at any time. A taker, the API and the cluster's nodes cannot. The side is public and anyone reads it.

ts
const { status, side, terms } = await client.deal(deal, key)
if (terms) {
  console.log(status, side, terms.size, terms.minSize, terms.limit)
}

client is a HadalClient whose owner is the maker, deal is the deal's address and key is the maker's reading key. terms is null for any wallet but the maker. status is one of the six statuses above.

The escrow inside the deal (what is left, what is locked, the proceeds) is sealed to the cluster alone. The maker follows a deal's progress from its public answers, each marked traded or not and filled or not, and reads the totals in the receipt when the deal is closed.