Open a deal
Open a deal as its maker, send the link, follow it until it is done, cancelled or expired, and bring the proceeds back to your sealed balance.
A deal trades a block with one counterparty. You choose a side in the clear and seal a size, a minimum size and a limit. Your counterparty answers with a sealed size and limit of their own, and the cluster trades the two at the midpoint when they cross. This guide is the maker's half. The counterparty's half is Answer a deal, and the mechanism is in Deals.
Before you open
You need a funded sealed balance in the market that holds what the deal escrows: the base token to sell, the quote token to buy. Deposit and withdraw gets it there. Your terms are sealed with your reading key, so the app asks for Unlock first and the SDK takes the key as key. See The reading key.
The terms
| Term | On the surface | Meaning |
|---|---|---|
Market | Seen | The pair the deal trades. The deal settles between the two sealed balances of this market. |
Side | Seen | Sell or buy the base token. Your counterparty takes the other side, and the deal shows them which. |
Size | Sealed | The most the deal trades, in the base token. Above zero. |
Minimum size | Sealed | The smallest answer you accept, in the base token. At most the size. An answer below it is no deal, unless it takes all that is left of the deal. |
Limit | Sealed | Selling: the lowest price you accept. Buying: the highest price you pay. Above zero. |
Counterparty | Seen | One address, the only wallet that can answer, or none: then anyone holding the link can answer. It cannot be your own wallet. |
Attempts per taker | Seen | How many answers each wallet gets on this deal, so a limit cannot be found by probing. 3 unless you set another number. |
Expiry | Seen | When the deal stops accepting answers. It must lie in the future. |
In the SDK, sizes are in atoms and the limit is a price in the program's unit: see Units. The range of each value is in Integer ranges.
What is escrowed
Opening a deal moves its escrow out of your sealed balance and into the deal, where it stays until the deal is closed.
- Selling: the size, in the base token.
- Buying: the quote token that buys the size at your limit, rounded up, plus the deal fee on that amount. The rate is in Fees.
A deal trades at the midpoint of the two limits, so a buying maker usually pays less than the limit. What the escrow did not spend comes back when the deal is closed.
Open the deal
Go to Deals
Open Deals. The form Open a deal is on the right. Connect a wallet and press Unlock if the form asks for it. If you hold no sealed balance in the market, the button reads Deposit and leads to the portfolio.
Enter the terms
Choose the Market and the Side. Enter the Size and, if you accept partial answers, a Minimum size. Left empty, the minimum is the whole size. Enter the Limit: the field reads accept no less than when you sell and pay no more than when you buy.
Choose who can answer
Under Counterparty, keep Anyone with the link or choose One address and enter the wallet's address. Set Attempts per taker and choose an Expiry of 1 hour, 6 hours or 1 day.
Press Open deal
The form shows the fee each side pays if the deal trades and the sealed balance the escrow comes from. Press Open deal and sign. The stages run: sealed in your wallet, signed, computed by the cluster.
Opening, open or void
The transaction creates the deal with the status opening and queues one computation. The cluster checks your sealed balance against the escrow and the chain learns one thing: whether the balance covered it.
| Status | Meaning |
|---|---|
opening | The computation is in flight. The deal cannot be answered yet. |
open | The escrow left your sealed balance and the deal accepts answers. The app shows Deal open with the link. |
void | Nothing moved and the deal can never be answered. The balance did not cover the escrow, the size or the limit was zero, the minimum was above the size, or the escrow is beyond the integer range. The app shows: The deal is larger than its sealed balance, so it is void. |
After the computation, the receipt in your sealed balance has ok true for an open deal and false for a void one. To replace a void deal, deposit what is missing and open a new one.
A deal stuck opening
If the cluster does not finish the computation, the deal stays opening and nothing was escrowed. Once the release window has passed, release_deal makes the deal void and reclaim frees your sealed balance. Anyone may send either. Then open the deal again.
const released = await hadal.releaseDeal(deal)
const freed = await hadal.reclaim({ market })
await sendWithKeypairs(connection, [...released.instructions, ...freed.instructions], [signer])The release window is in Limits, and the lifecycle of a computation in Arcium.
Send the link
The deal's link is its address: /deals/<the Deal account's address> in the app.
Under Deal open, press Copy link and send the link to your counterparty. The same control is on the deal's own page, in the panel The link. The link opens the deal's page, which shows the market, your side, the counterparty, the expiry and the attempts left. It never shows your size, minimum or limit.
A deal with no named counterparty can be answered by every wallet that has the link, each with its own attempts, until the deal is filled.
Watch the deal
Deals lists the deal under Your deals with your terms, the counterparty, the attempts, the expiry and its status: Opening, Open, Void, Done, Cancelled or Expired, the program's own statuses. Press Open in its row for the deal's page.
| State | What it means and what to do |
|---|---|
Opening | The computation that escrows your size is in flight. The deal cannot be answered yet. |
Void | The deal never opened and holds nothing. Open a new one. |
Open | The deal accepts answers. An answer that traded less than the whole size leaves the deal open for the rest: each answer shows on the surface as done or no deal, never with its size. You can cancel. |
Done | Answers have traded the whole size. Your proceeds wait in the deal. Close it to bring them to your sealed balance. |
Expired | The expiry passed. No answer is accepted. Close the deal to bring back the escrow that is left and the proceeds of any answer that traded. |
Cancelled | You cancelled it. The escrow that was left and the proceeds are in your sealed balance. |
On chain an expired deal keeps the status open until it is closed, and then reads expired. The app shows Expired from the moment the expiry passes.
Cancel an open deal
Only the maker cancels a deal that is open and not expired.
Open the deal's page. In the panel Your deal, press Cancel deal and sign. The app confirms with Deal cancelled.
One computation returns to your sealed balance the escrow that is left and the proceeds of every answer that traded before the cancel. The deal's status becomes cancelled.
Close a filled or expired deal
What you receive from an answer stays in the deal until the deal is closed. Closing is the same instruction as cancelling, cancel_deal, and for a deal that is done or past its expiry any wallet may send it. The amounts always go to the maker's sealed balance.
Open the deal's page. For a deal that is done or expired, the panel Your deal shows Close deal. Press it and sign. The app confirms with Deal closed, and the panel then reads that nothing of the deal is held any longer.
After the computation, the receipt in your sealed balance reads:
| Field | Type | Meaning |
|---|---|---|
receipt.ok | boolean | true. |
receipt.filled | bigint | Base atoms credited. Selling: the escrow that did not trade. Buying: the base you bought. |
receipt.quote | bigint | Quote atoms credited. Selling: what the answers paid you, less your deal fee. Buying: the escrow that was not spent. |
A done deal keeps the status done. An expired one becomes expired. A deal is closed once: a second cancel_deal on it is refused with DealNotOpen. Closing also hands the deal's fees and volume to the market's pool, where the next sounding counts them.
Read your own terms
Your side is public. Your size, minimum size and limit are stored in the deal, sealed to your reading key.
With the reading key unlocked, Your deals shows them in the column Your terms, and the deal's page shows them in the row Maker's size, minimum and limit. For every other wallet that row stays sealed.
How much of the deal has traded is held in the deal's escrow, sealed to the cluster. You read it as amounts when the deal is closed.
Errors
The program refuses a transaction of this guide with one of these errors. Busy means your sealed balance, the deal or the market's book has a computation in flight: send again when it has landed.
| Error | Code | Raised when |
|---|---|---|
Busy | 6001 | The market's book, the balance or the deal the instruction needs already has a computation in flight. Also raised by process_order, by cancel_order on a pending order and by fund_market while the market has one. Send again once that computation lands, or release it after it expires. |
NotOwner | 6006 | The signer does not own what the instruction acts on: collect or cancel_order by a wallet other than the order's owner (before expiry, or on a pending order), cancel_deal of an open deal by a wallet other than the maker, open_pool by a wallet other than the market's creator, fund_market by a wallet other than the creator unless the market holds no funds and its claim window has passed. |
MarketNotReady | 6015 | The market's pool is not open yet. Raised by place_order, add_liquidity, remove_liquidity, open_deal and sound. |
EmptyBalance | 6019 | The sealed balance has never had a computation land on it. Raised by withdraw, place_order, add_liquidity, remove_liquidity, open_deal and take_deal. Deposit first. |
InvalidExpiry | 6021 | The expiry is not acceptable. A swap takes 0 for none or a future time. A dark order requires a future time at most one day ahead. A deal requires a future time. |
DealNotOpen | 6024 | take_deal was sent for a deal whose status is not open, or cancel_deal for a deal that is opening, void or already settled. |
InvalidCounterparty | 6027 | The maker tried to answer their own deal, or opened a deal naming themselves as counterparty. |
All program errors are in the program reference.