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.
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 term | Unit | Meaning |
|---|---|---|
size | base atoms | The most the deal trades. Greater than zero. |
minimum size | base atoms | The least one answer may take. At most the size. |
limit | price | The lowest price a selling maker accepts, or the highest a buying maker pays. Greater than zero. |
| Public term | Type | Meaning |
|---|---|---|
market | address | The market whose two tokens the deal trades. Its pool must be open, or the deal is refused with MarketNotReady. |
side | buy or sell | Whether the maker buys or sells the base token. Public, so a counterparty knows what they answer. |
taker | address or none | The 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. |
attempts | 1 to 255 | How many answers each taker may send. When the maker sets none, 3. |
expiry | Unix seconds, UTC | The 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.
The link
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 side | Escrow |
|---|---|
| Sell | The size, in the base token. |
| Buy | The 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.
| Rule | Refused 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:
- 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.
- 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.
- 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
| Quantity | How it is set |
|---|---|
Price | The midpoint of the two limits: their sum divided by two, rounded down. |
Size | The smaller of the answer's size and what is left of the deal. |
Quote traded | The size at the price, rounded down to a whole quote atom. |
Fee | The 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
| Status | Meaning and what follows |
|---|---|
opening | The deal exists and the computation that takes its escrow has not landed. It becomes open or void. |
open | The 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. |
done | The whole size traded. The maker's proceeds are in the deal until it is closed. Closing leaves the status done. |
cancelled | The 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. |
expired | It was closed after its expiry. The same amounts are back in the maker's sealed balance. |
void | The 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 is | Who may close it | Status after |
|---|---|---|
open, before its expiry | The maker. Anyone else is refused with NotOwner. | cancelled |
open, after its expiry | Anyone | expired |
done | Anyone | done |
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.
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.