Program
The Hadal program's id, accounts, instructions, events, errors and status values.
Hadal is one Solana program built as an Arcium MXE. An instruction that changes sealed state queues a computation on the cluster and returns. The cluster's result arrives in a second transaction, the callback, which writes the new ciphertext to the accounts. The lifecycle is told in Arcium, and what each computation does with its inputs in Circuits.
Program id
| Program | Address |
|---|---|
hadal | Hb4CKfTCoERvV2sCATZcu337DK2j1pV2Xkj7sWwFeghE |
Arcium | Arcj82pX7HxYKLR92qvgZUAd7vGS1k4hQvAFcPATFdEQ |
The program is written with Anchor. Its IDL names every instruction, account, event and error on this page with the same spelling, in snake case for instructions and fields.
Accounts and seeds
Every account is a program derived address of the Hadal program. Seeds are the literal string, then the addresses in order. seq and id are u64 values in 8 little-endian bytes.
| Account | Seeds | Holds |
|---|---|---|
Config | ["config"] | The venue's settings: authority, keeper, fee recipient, the HADAL mint, the fee rates, the protocol's share of the sweep fee, the sounding interval and the default attempts per taker. |
Market | ["market", base_mint, quote_mint] | One pair of tokens: the sealed book (the pool and the resting orders), the mints and vaults, the creator and the slot it was created in, the order queue, which book slots are taken, the last sounding and the protocol fees owed. |
Vault | ["vault", market, mint] | A token account owned by the market that holds one of its two tokens. Each market has two. |
Balance | ["balance", market, owner] | A wallet's sealed balance in one market: base, quote, shares and the receipt of its last action, sealed to the owner's reading key. Also the public amount of a deposit or withdrawal in flight. |
Order | ["order", market, seq] | One sealed order: its sealed terms, kind, status, book slot, expiry, and the owner's ledger as the order's last computation left it, which holds its receipt. |
Deal | ["deal", maker, id] | One deal: the maker's public side, the maker's sealed terms, the sealed escrow, the counterparty, attempts per taker, status and expiry. A deal's link is this account's address. |
DealAttempts | ["attempts", deal, taker] | How many attempts one taker has used on one deal. |
A market is derived from its base mint and then its quote mint, so the same two mints in the other order are a different market.
Five sealed values live in these accounts. Each is an array of 32-byte ciphertexts with a nonce beside it.
| Sealed value | Where | Sealed to |
|---|---|---|
The book | Market.book, 11 ciphertexts | The cluster alone. It holds the pool and the resting orders. No key outside the cluster opens it. |
A ledger | Balance.ledger, 4 ciphertexts | The reading key in Balance.key, shared with the cluster. The owner reads it; the cluster computes on it. |
An order's terms | Order.terms, 5 ciphertexts | The reading key in Order.key, shared with the cluster. |
A deal's maker terms | Deal.terms, 5 ciphertexts | The maker's reading key in Deal.terms_key, shared with the cluster. A taker cannot open them. |
A deal's escrow | Deal.state, 3 ciphertexts | The cluster alone. |
The fields inside each sealed value are listed in Circuits. Every other field below is public.
Config
| Name | Type | Meaning |
|---|---|---|
authority | pubkey | The wallet that may change the settings. |
keeper | pubkey | A recorded address. The program gives it no right that other wallets lack. |
fee_recipient | pubkey | The wallet whose token accounts receive protocol fees in pay_fees. |
hadal_mint | pubkey | The mint of HADAL. The default address while not set. |
protocol_share_bps | u16 | The protocol's share of the sweep fee, in basis points of that fee, 0 to 10000. |
protocol_share_set | bool | Whether the share has been set. process_order is refused until it is. |
sweep_bps | u16 | The sweep fee in basis points. |
cross_bps | u16 | The cross fee each side pays, in basis points. |
deal_bps | u16 | The deal fee each side pays, in basis points. |
sounding_interval | u64 | Slots that must pass between two soundings of a market. |
default_attempts | u8 | Attempts each taker gets on a deal opened with attempts 0. |
bump | u8 | The bump of the address. |
The rates are told in Fees.
Market
| Name | Type | Meaning |
|---|---|---|
book | [[u8; 32]; 11] | Sealed to the cluster: the pool and the six resting orders. |
book_nonce | u128 | The nonce of the book ciphertext. |
base_mint | pubkey | The base token. |
quote_mint | pubkey | The quote token. |
base_vault | pubkey | The vault that holds the base token. |
quote_vault | pubkey | The vault that holds the quote token. |
base_token_program | pubkey | The token program of the base mint. |
quote_token_program | pubkey | The token program of the quote mint. |
base_decimals | u8 | Decimals of the base mint. |
quote_decimals | u8 | Decimals of the quote mint. |
creator | pubkey | The wallet that created the market, or the wallet that claimed it by funding it after the claim window. |
created_slot | u64 | The slot the market was created in. The claim window counts from it. |
ready | bool | True once the pool is open. |
pending | pubkey | The computation account in flight on the book. The default address when none. |
pending_since | u64 | The slot that computation was queued in. |
head | u64 | The sequence of the next order to process. |
tail | u64 | The sequence the next placed order receives. |
slots | [u64; 6] | For each book slot, the sequence plus 1 of the dark order resting there, or 0 when the slot is free. |
seed_base | u64 | The creator's first liquidity in base atoms. |
seed_quote | u64 | The creator's first liquidity in quote atoms. |
first_price | u64 | seed_quote times 2^32 divided by seed_base. |
last_sound_slot | u64 | The slot of the last sounding, or of the pool opening before the first. |
last_price | u64 | The pool's price at the last sounding. |
last_crossed | u64 | Crossed volume of the last sounding, in quote atoms. |
last_swept | u64 | Swept volume of the last sounding, in quote atoms. |
soundings | u64 | How many soundings the market has had. |
fees_owed_base | u64 | Protocol fees revealed by soundings and not yet paid, in base atoms. |
fees_owed_quote | u64 | The same in quote atoms. |
bump | u8 | The bump of the address. |
Prices and amounts use the units in Limits.
Balance
| Name | Type | Meaning |
|---|---|---|
ledger | [[u8; 32]; 4] | Sealed to the owner's reading key: base, quote, shares and the receipt of the last action. |
key | [u8; 32] | The owner's reading key (the x25519 public key) the ledger is sealed to. |
nonce | u128 | The nonce of the ledger ciphertext. |
market | pubkey | The market. |
owner | pubkey | The wallet. |
fresh | bool | True until the first computation writes the ledger. |
pending | pubkey | The computation account in flight on the balance. The default address when none. |
pending_since | u64 | The slot that computation was queued in. |
pending_base | u64 | Base atoms of a deposit waiting for its computation. |
pending_quote | u64 | Quote atoms of a deposit waiting for its computation. |
withdraw_base | u64 | Base atoms of a withdrawal waiting for its computation. |
withdraw_quote | u64 | Quote atoms of a withdrawal waiting for its computation. |
bump | u8 | The bump of the address. |
Order
| Name | Type | Meaning |
|---|---|---|
terms | [[u8; 32]; 5] | Sealed to the owner's reading key: side, size, limit, and the owner's address in two parts. |
key | [u8; 32] | The reading key the terms are sealed with. |
nonce | u128 | The nonce of the terms. |
market | pubkey | The market. |
owner | pubkey | The wallet that placed it. |
seq | u64 | The order's sequence in the market's queue. |
kind | u8 | 0 swap, 1 dark. |
status | u8 | 0 pending, 1 resting, 2 closed. |
slot | u8 | The book slot a dark order was given, 0 to 5. The order holds it only while its status is resting. |
closing | bool | True while a cancel of the resting order is in flight. |
expiry | i64 | Unix seconds. An order still pending after it is closed unprocessed, and a resting order can be cancelled by anyone after it. 0 for none, on a swap only. |
placed_at | i64 | Unix seconds when it was placed. |
receipt | [[u8; 32]; 4] | The owner's ledger as the order's last computation left it, sealed to the owner's reading key. Its receipt is the order's result. |
receipt_nonce | u128 | The nonce of that ledger. |
bump | u8 | The bump of the address. |
Deal
| Name | Type | Meaning |
|---|---|---|
state | [[u8; 32]; 3] | Sealed to the cluster: the deal's escrow. |
state_nonce | u128 | The nonce of the escrow. |
terms | [[u8; 32]; 5] | Sealed to the maker's reading key: size, minimum size, limit, and the maker's address in two parts, as the maker sealed them. |
terms_key | [u8; 32] | The maker's reading key. |
terms_nonce | u128 | The nonce of the terms. |
market | pubkey | The market. |
maker | pubkey | The wallet that opened it. |
taker | pubkey | The one counterparty, or the default address when any wallet holding the link may answer. |
buy | bool | The maker's side, public: true when the maker buys the base token. A taker trades the other side. |
id | u64 | The maker's number for the deal, part of its address. |
attempts | u8 | Attempts each taker gets. |
status | u8 | 0 opening, 1 open, 2 done, 3 cancelled, 4 expired, 5 void. |
expiry | i64 | Unix seconds after which the deal takes no answers. |
created_at | i64 | Unix seconds when it was opened. |
settled | bool | True once the escrow and proceeds are back in the maker's sealed balance, or when the deal is void. |
closing | u8 | The status a settlement in flight leaves the deal in. |
pending | pubkey | The computation account in flight on the deal. The default address when none. |
pending_since | u64 | The slot that computation was queued in. |
bump | u8 | The bump of the address. |
A deal's link carries the address of this account. Whoever opens the link reads the public fields above and answers with take_deal.
DealAttempts
| Name | Type | Meaning |
|---|---|---|
deal | pubkey | The deal. |
taker | pubkey | The taker. |
used | u8 | Attempts the taker has used. |
bump | u8 | The bump of the address. |
One computation at a time
A market's book, a balance and a deal each carry pending, the computation in flight on that account. An instruction that queues a computation sets pending on every account its circuit writes, and is refused with Busy when one of them is already set. The callback clears it. A callback whose computation is not the pending one is refused with StaleComputation.
| Instruction | Accounts it holds until the callback |
|---|---|
deposit, withdraw | The balance. |
sound | The market's book. |
open_pool, process_order, collect, cancel_order, add_liquidity, remove_liquidity | The market's book and the balance. |
open_deal, take_deal | The deal and the balance. |
cancel_deal | The deal, the maker's balance and the market's book. |
Orders of one market are therefore processed one after another, in the order of their seq. No order can hold the queue: process_order closes the head order without a computation when it cannot run.
Arcium accounts of a queue instruction
Every instruction that queues a computation takes computation_offset as its first argument and these twelve accounts first, in this order. The sections below list only what follows them.
| Account | Signer, writable | Meaning |
|---|---|---|
payer | signer, writable | The wallet that sends the instruction. It pays the computation. The sections below give its name in each instruction: owner, creator, maker, taker, signer or payer. |
sign_pda_account | writable | The address of the Hadal program with the seed ArciumSignerAccount. Created by the first instruction that needs it. |
mxe_account | | Hadal's MXE account in the Arcium program. |
mempool_account | writable | The cluster's mempool. |
executing_pool | writable | The cluster's executing pool. |
computation_account | writable | The account of this computation, derived from computation_offset. |
comp_def_account | | The computation definition of the circuit the instruction queues. |
cluster_account | writable | The cluster. |
pool_account | writable | Arcium's fee pool, G2sRWJvi3xoyh5k2gY49eG9L8YhAEWQPtNb1zb1GXTtC. |
clock_account | writable | Arcium's clock, 7EbMUTLo5DjdzbN7s8BXeZwXzEwNQb1hScfRvWg8a6ot. |
system_program | | The system program. |
arcium_program | | The Arcium program. |
computation_offset is a u64 the sender chooses, new for each computation. It decides the address of the computation account, and that address is what pending holds. The @arcium-hq/client package derives each address: getArciumSignerAccAddress, getMXEAccAddress, getMempoolAccAddress, getExecutingPoolAccAddress, getComputationAccAddress, getCompDefAccAddress, getClusterAccAddress, getFeePoolAccAddress and getClockAccAddress. The SDK fills all of them.
A callback is sent by the cluster through the Arcium program. It verifies the output against the cluster and the computation account, and fails with AbortedComputation when the output does not verify.
Instructions
| Instruction | Circuit | Who may send it, and what it does |
|---|---|---|
create_market | | Anyone. Creates the market account and the two vaults for a pair of mints. The signer becomes the market's creator. |
fund_market | | The market's creator, before the pool opens, or any wallet when the market still holds no funds after its claim window, which makes that wallet the creator. Moves the first liquidity from the wallet to the vaults. The two amounts are public and set the first price. |
open_pool | init_market | The market's creator, once. Opens the pool with the first liquidity and credits sealed shares to the creator's balance. |
open_balance | | Any wallet, once per market. Creates the wallet's sealed balance in the market, sealed to the reading key it passes. |
deposit | deposit | The balance's owner. Moves tokens from the wallet to the vault at once. The sealed balance adds them when the computation lands. |
withdraw | withdraw | The balance's owner. Asks for tokens back. The callback pays the wallet if the sealed balance covers the amount, otherwise nothing moves. |
place_order | | The balance's owner. Puts a sealed order (side, size, limit) at the tail of the market's queue. Its kind, swap or dark, and its expiry are public. A dark order needs an expiry at most one day ahead. |
process_order | process_order | Anyone. Runs the order at the head of the market's queue: cross at the pool's mid, then sweep (a swap) or rest (a dark order). Closes it without a computation when it was cancelled, its expiry has passed, its owner's balance is busy, or it is dark and the book is full. |
collect | settle_slot | The order's owner. Moves a resting order's proceeds to the owner's sealed balance. The order keeps resting. |
cancel_order | settle_slot | The order's owner, or anyone once the order's expiry has passed. A pending order closes at once with no computation, while the market has no computation in flight. A resting order returns what it still has locked and its proceeds, and frees its book slot. |
add_liquidity | add_liquidity | The owner of a funded balance. Moves sealed amounts of both tokens from the sealed balance to the pool, in the pool's ratio, for sealed shares. |
remove_liquidity | remove_liquidity | The owner of a funded balance. Turns a sealed number of shares back into both tokens in the sealed balance. |
open_deal | open_deal | The maker. Opens a deal on a public side with sealed size, minimum size and limit, for one named counterparty or for anyone holding its link. The escrow leaves the maker's sealed balance. |
take_deal | take_deal | The named counterparty, or any wallet other than the maker when the deal names none. Answers the deal with a sealed size and limit. Uses one attempt. |
cancel_deal | settle_deal | The maker for an open deal; anyone for a filled deal or one past its expiry. Closes the deal and returns its remaining escrow and its proceeds to the maker's sealed balance. |
sound | sound | Anyone, once the sounding interval has passed since the market's last sounding. Takes a sounding of the market. |
pay_fees | | Anyone. Pays the protocol fees that soundings revealed from the vaults to the fee recipient's token accounts. |
reclaim | | Anyone. Releases a balance whose computation expired, and refunds a deposit that was waiting on it to the owner's token account. |
release_market | | Anyone. Releases a market's book whose computation expired. |
release_deal | | Anyone. Releases a deal whose computation expired. A deal that was still opening becomes void. |
Sealed arguments are 32-byte ciphertexts made with the sender's reading key and a fresh nonce; the instruction also takes that key (the x25519 public key) and the nonce as a u128. How to seal is told in The reading key.
Every sealed argument ends with the address of the wallet it was sealed for, as two u128 values: bytes 0 to 15 and bytes 16 to 31 of the address, each little-endian. They are written owner_lo and owner_hi below. The circuit compares them with the wallet the instruction acts for, and an argument sealed for another address makes the action void. The SDK's ownerLimbs computes the pair.
create_market
Takes no arguments.
| Account | Signer, writable | Meaning |
|---|---|---|
creator | signer, writable | Pays for the three accounts and becomes Market.creator. |
base_mint | | The base token. |
quote_mint | | The quote token. Must differ from base_mint. |
market | writable | Created at ["market", base_mint, quote_mint]. |
base_vault | writable | Created at ["vault", market, base_mint], a token account whose authority is the market. |
quote_vault | writable | Created at ["vault", market, quote_mint]. |
base_token_program | | The token program of base_mint. |
quote_token_program | | The token program of quote_mint. |
system_program | | The system program. |
Checks both mints against the supported mints and records the mints, vaults, token programs, decimals, creator and the current slot. Emits MarketCreated.
Errors: SameMint, UnsupportedMint.
fund_market
| Argument | Type | Meaning |
|---|---|---|
base_amount | u64 | Base atoms to move to the base vault. Greater than 0. |
quote_amount | u64 | Quote atoms to move to the quote vault. Greater than 0. |
| Account | Signer, writable | Meaning |
|---|---|---|
creator | signer, writable | The market's creator, or any wallet when the market holds no funds and the claim window has passed. |
market | writable | The market, not yet open. |
base_mint | | The market's base mint. |
quote_mint | | The market's quote mint. |
base_vault | writable | The market's base vault. |
quote_vault | writable | The market's quote vault. |
creator_base | writable | The creator's token account of the base mint. |
creator_quote | writable | The creator's token account of the quote mint. |
base_token_program | | Market.base_token_program. |
quote_token_program | | Market.quote_token_program. |
Moves both amounts from the signer's token accounts to the vaults, adds them to seed_base and seed_quote, and sets first_price to seed_quote * 2^32 / seed_base. Both amounts are public. It emits no event. Sent more than once before the pool opens, the amounts add up.
The first price must be greater than 0 and inside the first price range. A signer who is not the creator is accepted only when the market holds no first liquidity (seed_base and seed_quote are both 0) and the claim window has passed since the market was created. That signer becomes Market.creator.
Errors: InvalidAmount, NotOwner (the signer is not the creator, and the market is funded or the claim window has not passed), Busy (the market's open_pool computation is in flight), PriceOutOfRange, MarketAlreadyOpen, WrongVault.
open_pool
Argument: computation_offset (u64). Queues init_market.
| Account | Signer, writable | Meaning |
|---|---|---|
creator | signer, writable | The payer: the market's creator. |
market | writable | The market, funded and not yet open. |
creator_balance | writable | The signer's balance in this market, at ["balance", market, creator]. Open it with open_balance first. |
The signer must be Market.creator: the wallet that created the market, or the one that claimed it with fund_market. The instruction passes seed_base and seed_quote to the circuit in plaintext. The callback writes the book, sets ready, sets last_price to first_price and last_sound_slot to the current slot, writes the creator's ledger with the shares, and emits MarketReady.
Errors: NotOwner (the signer is not the creator), MarketAlreadyOpen, NotFunded, Busy.
open_balance
| Argument | Type | Meaning |
|---|---|---|
key | [u8; 32] | The owner's reading key (x25519 public key). Every ledger of this balance is sealed to it. |
| Account | Signer, writable | Meaning |
|---|---|---|
owner | signer, writable | The wallet. Pays for the account. |
market | | The market. |
balance | writable | Created at ["balance", market, owner]. |
system_program | | The system program. |
Creates the balance with fresh true and emits BalanceOpened. A wallet has one balance per market. The balance holds nothing until a deposit lands.
deposit
| Argument | Type | Meaning |
|---|---|---|
computation_offset | u64 | See the Arcium accounts above. |
side | u8 | 0 for the base token, 1 for the quote token. |
amount | u64 | Atoms to deposit. Greater than 0. Public. |
| Account | Signer, writable | Meaning |
|---|---|---|
owner | signer, writable | The payer: the balance's owner. |
market | writable | The market. |
balance | writable | At ["balance", market, owner]. |
vault | writable | The market's vault for the side. |
mint | | The market's mint for the side. |
owner_token | writable | The owner's token account of that mint. |
token_program | | The token program of that mint. |
Moves amount from owner_token to the vault in this transaction, records it in pending_base or pending_quote, emits DepositQueued and queues deposit with the amount in plaintext. The callback clears the pending amount, writes the ledger and emits DepositLanded. If the computation expires, reclaim sends the tokens back.
Errors: InvalidAmount, InvalidSide, WrongVault, Busy.
withdraw
Arguments: computation_offset, side and amount, as in deposit. Queues withdraw. Accounts: the same seven as deposit.
Records the amount in withdraw_base or withdraw_quote, emits WithdrawQueued and queues the circuit with the amount in plaintext. No token moves in this transaction. The callback writes the ledger and, when the circuit reveals that the sealed balance covered the amount, moves amount from the vault to owner_token. It emits WithdrawDone with paid true or false. When paid is false nothing moved and the sealed balance is unchanged.
Errors: InvalidAmount, InvalidSide, WrongVault, EmptyBalance, Busy.
place_order
| Argument | Type | Meaning |
|---|---|---|
terms | [[u8; 32]; 5] | Sealed: side (1 buy, 0 sell), size in base atoms, limit as a price, owner_lo, owner_hi. |
key | [u8; 32] | The reading key the terms are sealed with. |
nonce | u128 | The nonce the terms are sealed under. |
kind | u8 | 0 swap, 1 dark. Public. |
expiry | i64 | Unix seconds, public. A dark order requires one, in the future and at most one day ahead. A swap takes 0 for none, or a future time. |
| Account | Signer, writable | Meaning |
|---|---|---|
owner | signer, writable | The wallet. Pays for the order account. |
market | writable | The market. |
balance | | At ["balance", market, owner]. |
order | writable | Created at ["order", market, seq] where seq is Market.tail. |
system_program | | The system program. |
Stores the sealed terms, gives the order the sequence Market.tail, sets its status to pending, advances tail and emits OrderPlaced. It queues no computation and takes no Arcium accounts: the order waits for process_order. The order's address is derived from tail as it is when the transaction runs. A transaction built on an earlier tail fails the address check of the order account; read the market again and rebuild it.
An order that is still pending when its expiry passes is closed by process_order without being run. A dark order that rests can be cancelled by anyone after its expiry, so no order holds a book slot longer than the resting time.
Errors: InvalidKind, InvalidExpiry (a dark order with no expiry, a past one, or one more than a day ahead; a swap with a past one), MarketNotReady, EmptyBalance.
process_order
Argument: computation_offset. Queues process_order.
| Account | Signer, writable | Meaning |
|---|---|---|
payer | signer, writable | Any wallet. |
config | | At ["config"]. |
market | writable | The market. |
order | writable | The order whose seq equals Market.head. |
balance | writable | The balance of the order's owner, at ["balance", market, order.owner]. |
The order must be at the head of the queue, and the market must have no computation in flight. The instruction then takes the first case that applies:
- The order was cancelled while pending:
headadvances and nothing else happens. - The order has an expiry and the current time is past it: the order closes,
headadvances andOrderReturnedis emitted with reason 2. - The owner's balance has another computation in flight: the order closes,
headadvances andOrderReturnedis emitted with reason 3. - The order is dark and all six book slots are taken: the order closes,
headadvances andOrderReturnedis emitted with reason 0. - Otherwise the instruction picks the first free slot for a dark order and queues the circuit with the order's terms, the owner's ledger, the book, and in plaintext the owner's address, whether the order sweeps or rests, the slot, and the three fee rates from
Config.
An order returned with reason 0, 2 or 3 ran no computation: its sealed balance is untouched and it has no receipt. Place it again.
The callback writes the book and the owner's ledger, copies that ledger to Order.receipt, and advances head. The circuit reveals whether a dark order rests. When it does, the order becomes resting and its sequence plus 1 is written to its slot in Market.slots. A dark order with nothing left to rest, and every swap, becomes closed and holds no slot. The callback emits OrderProcessed.
Errors: ProtocolShareUnset, NotQueueHead, Busy (the market has a computation in flight), WrongMarket.
collect
Argument: computation_offset. Queues settle_slot with close false.
| Account | Signer, writable | Meaning |
|---|---|---|
signer | signer, writable | The payer: the order's owner. |
market | writable | The market. |
order | writable | The resting order. |
balance | writable | The owner's balance, at ["balance", market, order.owner]. |
The callback writes the book and the ledger, copies the ledger to Order.receipt and emits OrderSettled with closed false. The order stays resting in its slot.
Errors: NotOwner, NotResting, WrongMarket, Busy.
cancel_order
Argument: computation_offset. Accounts: the same as collect, and signer may be any wallet once the order's expiry has passed.
- A pending order, cancelled by its owner: the status becomes closed in this transaction and
OrderReturnedis emitted with reason 1. No computation is queued, though the instruction still takes the Arcium accounts. It is refused withBusywhile the market has a computation in flight, because that computation may be this order's: send it again once the callback has landed. - A resting order, cancelled by its owner, or by anyone when
expiryis not 0 and the current time is past it: queuessettle_slotwithclosetrue. The callback writes the book and the ledger, frees the slot inMarket.slots, closes the order and emitsOrderSettledwithclosedtrue.
Errors: NotOwner (not the owner, and the order has no expiry or has not reached it; or a pending order cancelled by another wallet), NotResting (the order is already closed), WrongMarket, Busy.
add_liquidity
| Argument | Type | Meaning |
|---|---|---|
computation_offset | u64 | See the Arcium accounts above. |
amounts | [[u8; 32]; 4] | Sealed: the most base atoms and the most quote atoms to add, owner_lo, owner_hi. |
key | [u8; 32] | The reading key the amounts are sealed with. |
nonce | u128 | The nonce the amounts are sealed under. |
| Account | Signer, writable | Meaning |
|---|---|---|
owner | signer, writable | The payer: the balance's owner. |
market | writable | The market. |
balance | writable | At ["balance", market, owner]. |
Emits LiquidityQueued with adding true and queues add_liquidity. The callback writes the book and the ledger and emits LiquidityChanged.
Errors: MarketNotReady, EmptyBalance, Busy.
remove_liquidity
Arguments: computation_offset, shares ([[u8; 32]; 3], sealed: the shares to give back, owner_lo, owner_hi), key, nonce. Accounts: the same three as add_liquidity. Queues remove_liquidity.
Emits LiquidityQueued with adding false. The callback writes the book and the ledger and emits LiquidityChanged.
Errors: MarketNotReady, EmptyBalance, Busy.
open_deal
| Argument | Type | Meaning |
|---|---|---|
computation_offset | u64 | See the Arcium accounts above. |
id | u64 | A number the maker chooses, unique among the maker's deals. Part of the deal's address. |
buy | bool | The maker's side, public: true to buy the base token, false to sell it. |
terms | [[u8; 32]; 5] | Sealed: size in base atoms, minimum size in base atoms, limit as a price, owner_lo, owner_hi. |
key | [u8; 32] | The maker's reading key. |
nonce | u128 | The nonce the terms are sealed under. |
taker | pubkey | The one counterparty, or the default address for anyone holding the link. Not the maker. |
attempts | u8 | Attempts each taker gets. 0 takes Config.default_attempts. |
expiry | i64 | Unix seconds after which the deal takes no answers. In the future. |
| Account | Signer, writable | Meaning |
|---|---|---|
maker | signer, writable | The payer. Pays for the deal account. |
config | | At ["config"]. |
market | | The market. |
balance | writable | The maker's balance, at ["balance", market, maker]. |
deal | writable | Created at ["deal", maker, id]. |
Stores the side and the sealed terms with status opening, emits DealOpened and queues open_deal with the terms, the maker's ledger, and in plaintext the side, the deal fee rate and the maker's address. The callback writes the escrow and the ledger. When the circuit reveals that the sealed balance covered the escrow the status becomes open; otherwise it becomes void, settled is set and nothing left the balance. It emits DealReady.
Errors: MarketNotReady, InvalidExpiry, EmptyBalance, InvalidCounterparty (taker is the maker), Busy.
take_deal
| Argument | Type | Meaning |
|---|---|---|
computation_offset | u64 | See the Arcium accounts above. |
answer | [[u8; 32]; 4] | Sealed: size in base atoms, limit as a price, owner_lo, owner_hi. The taker trades the side opposite to Deal.buy. |
key | [u8; 32] | The taker's reading key. |
nonce | u128 | The nonce the answer is sealed under. |
| Account | Signer, writable | Meaning |
|---|---|---|
taker | signer, writable | The payer. Pays for the attempts account the first time. |
config | | At ["config"]. |
deal | writable | The deal, at ["deal", deal.maker, deal.id]. |
balance | writable | The taker's balance in the deal's market, at ["balance", deal.market, taker]. |
attempts | writable | At ["attempts", deal, taker]. Created on the taker's first answer. |
The deal must be open and not past its expiry, the signer must not be the maker, and when the deal names a counterparty the signer must be it. The instruction adds one to the taker's used attempts, emits DealTaken and queues take_deal with the answer, the taker's ledger, the escrow, the deal fee rate and the taker's address. The attempt is used when the instruction lands, whatever the computation returns.
The callback writes the escrow and the taker's ledger and emits DealAnswered with done (the answer traded) and filled (the deal has nothing left). When filled is true the status becomes done. A deal that traded part of its size stays open for further answers. The maker's proceeds stay in the escrow until cancel_deal settles the deal.
Errors: DealNotOpen, DealExpired, InvalidCounterparty (the signer is the maker), NotCounterparty, EmptyBalance, OutOfAttempts, Busy.
cancel_deal
Argument: computation_offset. Queues settle_deal.
| Account | Signer, writable | Meaning |
|---|---|---|
signer | signer, writable | The payer. The maker for an open deal before its expiry; any wallet otherwise. |
market | writable | The deal's market. |
deal | writable | The deal. |
balance | writable | The maker's balance, at ["balance", deal.market, deal.maker]. |
Settles a deal that is not yet settled. The status the settlement ends in depends on the deal:
| Deal | Who | Ends as |
|---|---|---|
done | anyone | done (2) |
open, past its expiry | anyone | expired (4) |
open, before its expiry | the maker | cancelled (3) |
The callback writes the book and the maker's ledger, sets the status, sets settled and emits DealSettled. The book is written because the deal's fees and volume join the market's figures for the next sounding.
Errors: DealNotOpen (the deal is opening, void or already settled), NotOwner, WrongMarket, Busy.
sound
Argument: computation_offset. Queues sound.
| Account | Signer, writable | Meaning |
|---|---|---|
payer | signer, writable | Any wallet. |
config | | At ["config"]. |
market | writable | The market. |
Requires the current slot to be at least last_sound_slot + sounding_interval. The callback writes the book, sets last_sound_slot, last_price, last_crossed and last_swept, adds the revealed protocol fees to fees_owed_base and fees_owed_quote, adds one to soundings and emits Sounding. The interval is told in Soundings.
Errors: MarketNotReady, TooEarly, Busy.
pay_fees
Takes no arguments and queues nothing.
| Account | Signer, writable | Meaning |
|---|---|---|
signer | signer | Any wallet. |
config | | At ["config"]. |
market | writable | The market. |
base_vault | writable | The market's base vault. |
quote_vault | writable | The market's quote vault. |
base_mint | | The market's base mint. |
quote_mint | | The market's quote mint. |
recipient_base | writable | A token account of the base mint owned by Config.fee_recipient. |
recipient_quote | writable | A token account of the quote mint owned by Config.fee_recipient. |
base_token_program | | Market.base_token_program. |
quote_token_program | | Market.quote_token_program. |
Moves fees_owed_base and fees_owed_quote from the vaults to the recipient's token accounts, sets both to 0 and emits FeesPaid. What the fees are used for is told in The token.
Errors: WrongVault.
Release instructions
A computation the cluster does not run expires, and its callback never arrives. The accounts it held stay marked with pending until a release instruction clears them. Each release instruction can be sent by any wallet, takes no arguments, and succeeds only once the release threshold has passed since pending_since.
| After an expired | Send |
|---|---|
deposit, withdraw | reclaim for the balance. |
sound | release_market. |
open_pool, process_order, collect, cancel_order, add_liquidity, remove_liquidity | release_market, and reclaim for the balance. |
open_deal, take_deal | release_deal, and reclaim for the balance. |
cancel_deal | release_deal, release_market, and reclaim for the maker's balance. |
No sealed value changed, because no callback wrote one. After the release the action is sent again: an order is still pending at the head of the queue and process_order runs it; a resting order can be collected or cancelled again; a deal that was being settled can be settled again. A deal whose open_deal expired is made void by release_deal, and its escrow never left the maker's balance: open a new deal under another id. An attempt used by an expired take_deal stays used.
Errors of all three: NothingPending, ComputationStillLive.
reclaim
| Account | Signer, writable | Meaning |
|---|---|---|
signer | signer | Any wallet. |
market | | The balance's market. |
balance | writable | The balance to release. |
vault | writable | The market's vault of the token a waiting deposit was made in. |
mint | | The mint of that token. |
owner_token | writable | A token account of that mint owned by Balance.owner. |
token_program | | The token program of that mint. |
Clears pending, and clears the waiting deposit and withdrawal amounts. When a deposit was waiting, its amount moves from the vault back to owner_token. It emits DepositRefunded with the amount refunded, which is 0 when no deposit was waiting. The refund goes to the balance's owner whoever signs.
Further errors: WrongMarket, WrongVault.
release_market
Accounts: signer (signer) and market (writable). Clears Market.pending and emits ComputationReleased with the market's address.
release_deal
Accounts: signer (signer) and deal (writable). Clears Deal.pending and emits ComputationReleased with the deal's address. A deal whose status is still opening becomes void with settled true.
Events
Events are written to the transaction's logs in Anchor's event encoding. The middle column is the instruction or callback that emits each one.
| Event | Emitted by | Fields |
|---|---|---|
ConfigChanged | set_config | The venue's settings after a change: fee_recipient, keeper, hadal_mint, protocol_share_bps, protocol_share_set, sounding_interval. |
MarketCreated | create_market | A market exists: market, base_mint, quote_mint, creator. |
MarketReady | init_market_callback | The market's pool is open: market, first_price, creator, and the creator's sealed ledger. |
BalanceOpened | open_balance | A wallet opened a sealed balance: balance, market, owner. |
DepositQueued | deposit | Tokens entered a vault: balance, market, owner, mint, amount. |
DepositLanded | deposit_callback | The deposit is in the sealed balance: balance, and the owner's sealed ledger. |
DepositRefunded | reclaim | A balance was released after its computation expired: balance, mint, and the amount refunded, 0 when no deposit was waiting. |
WithdrawQueued | withdraw | A withdrawal was asked for: balance, market, owner, mint, amount. |
WithdrawDone | withdraw_callback | The withdrawal was decided: balance, mint, amount, paid (true when the tokens moved, false when the sealed balance did not cover the amount), and the owner's sealed ledger. |
ComputationReleased | release_market, release_deal | A market or a deal was released after its computation expired: account. |
OrderPlaced | place_order | A wallet placed a sealed order: order, market, owner, seq, kind, expiry. Nothing of its side, size or limit. |
OrderProcessed | process_order_callback | The order's computation landed: order, market, owner, status (1 when a dark order rests, 2 otherwise), slot, and the owner's sealed ledger with the receipt. |
OrderReturned | process_order, cancel_order | An order closed without a computation: order, reason (0 the book was full, 1 the owner cancelled it while pending, 2 its expiry passed before it was processed, 3 its owner's balance was busy with another computation). |
OrderSettled | settle_slot_callback | A collect or a cancel of a resting order landed: order, closed (true for a cancel), and the owner's sealed ledger. |
LiquidityQueued | add_liquidity, remove_liquidity | A wallet asked to change its liquidity: balance, market, adding. |
LiquidityChanged | add_liquidity_callback, remove_liquidity_callback | The liquidity computation landed: balance, adding, and the owner's sealed ledger. |
DealOpened | open_deal | A wallet opened a deal: deal, market, maker, taker, buy (the maker's side), id, attempts, expiry. |
DealReady | open_deal_callback | The deal's escrow was decided: deal, open (true when the maker's sealed balance covered the escrow, false when the deal is void), and the maker's sealed ledger. |
DealTaken | take_deal | A wallet answered a deal: deal, taker, attempts_used. |
DealAnswered | take_deal_callback | The answer was decided: deal, taker, done (whether it traded), filled (whether the deal has nothing left), and the taker's sealed ledger. |
DealSettled | settle_deal_callback | The deal closed and its escrow and proceeds returned to the maker: deal, status, and the maker's sealed ledger. |
Sounding | sound_callback | A sounding: market, index, slot, unix_time, price, crossed, swept, fee_base, fee_quote. |
FeesPaid | pay_fees | Protocol fees left the vaults for the fee recipient: market, base, quote. |
Field types: an address is a pubkey; amount, seq, id, index, slot, price, crossed, swept, fee_base, fee_quote, base, quote, first_price and sounding_interval are u64; expiry and unix_time are i64 in Unix seconds, UTC; kind, status, reason, attempts and attempts_used are u8; protocol_share_bps is u16; paid, adding, open, done, filled, closed, buy and protocol_share_set are bool.
In a Sounding, price is the pool's price, crossed and swept are in quote atoms, fee_base is in base atoms and fee_quote in quote atoms, and index counts the market's soundings from 1.
A sealed ledger travels in an event as SealedLedger:
| Name | Type | Meaning |
|---|---|---|
ciphertexts | [[u8; 32]; 4] | The owner's ledger after the computation, sealed to the owner's reading key. |
nonce | [u8; 16] | The nonce of that ciphertext, little-endian. |
It is the same value the callback wrote to Balance.ledger. Its receipt is the result of the action. Reading it is told in the receipts guide.
Errors
The program's own errors, with their numbers. A transaction the program refuses carries the number as a custom program error.
| Error | Code | Raised when |
|---|---|---|
AbortedComputation | 6000 | A callback received an output that does not verify against the cluster and the computation account. Nothing is written. |
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. |
StaleComputation | 6002 | A callback arrived for a computation that is not the one pending on the account, for example after the account was released. |
NothingPending | 6003 | reclaim, release_market or release_deal was sent for an account with no computation in flight. |
ComputationStillLive | 6004 | reclaim, release_market or release_deal was sent before the release threshold had passed since the computation was queued. |
NotAuthority | 6005 | The signer of a setup call is not the venue's authority, or the signer of initialize is not the program's upgrade authority. |
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. |
InvalidConfig | 6007 | A setting is out of range: a sounding interval of 0, or a protocol share above 10000 bps. |
ProtocolShareUnset | 6008 | process_order was sent while the protocol's share of the sweep fee has not been set in Config. |
UnsupportedMint | 6009 | create_market was given a Token-2022 mint with one of the refused extensions: transfer fee, transfer hook, permanent delegate, default account state or pausable. |
SameMint | 6010 | create_market was given the same mint as base and quote. |
InvalidAmount | 6011 | An amount of 0 was passed to deposit, withdraw or fund_market. |
InvalidSide | 6012 | The side of deposit or withdraw is neither 0 (base) nor 1 (quote). |
WrongVault | 6013 | A vault or mint account passed is not the market's vault or mint for that side. |
WrongMarket | 6014 | The order, balance or deal passed belongs to a market other than the market account passed. |
MarketNotReady | 6015 | The market's pool is not open yet. Raised by place_order, add_liquidity, remove_liquidity, open_deal and sound. |
MarketAlreadyOpen | 6016 | fund_market or open_pool was sent for a market whose pool is already open. |
NotFunded | 6017 | open_pool was sent before fund_market put both tokens in the vaults. |
PriceOutOfRange | 6018 | fund_market would set a first price of 0 or of 2^32 quote atoms per base atom or more. |
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. |
InvalidKind | 6020 | The kind of place_order is neither 0 (swap) nor 1 (dark). |
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. |
NotQueueHead | 6022 | process_order was given an order that is not at the head of the market's queue. |
NotResting | 6023 | collect was sent for an order that is not resting, or cancel_order for an order that is already closed. |
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. |
DealExpired | 6025 | take_deal was sent after the deal's expiry. |
NotCounterparty | 6026 | take_deal was signed by a wallet other than the counterparty the deal names. |
InvalidCounterparty | 6027 | The maker tried to answer their own deal, or opened a deal naming themselves as counterparty. |
OutOfAttempts | 6028 | The taker has used every attempt the deal gives each taker. |
TooEarly | 6029 | sound was sent before the sounding interval had passed since the market's last sounding. |
A refusal that is decided inside a circuit is not an error of the program. An order, an answer or a liquidity change that the sealed balance does not cover lands as a callback that succeeds, and its receipt says the action was void. See Circuits.
Status and kind values
| Field | Value | Meaning |
|---|---|---|
Order.kind 0 | swap | Crosses the book, then sweeps the pool. |
Order.kind 1 | dark | Crosses the book, then rests. |
Order.status 0 | pending | In the market's queue, not yet processed. |
Order.status 1 | resting | A dark order, processed, with size resting in a book slot. |
Order.status 2 | closed | Finished: a processed swap, a processed dark order with nothing left to rest, a cancelled order, or an order returned unprocessed. |
Deal.status 0 | opening | The escrow computation has not landed. |
Deal.status 1 | open | Takes answers. |
Deal.status 2 | done | Its whole size traded. |
Deal.status 3 | cancelled | The maker cancelled it and it is settled. |
Deal.status 4 | expired | It passed its expiry and it is settled. |
Deal.status 5 | void | The maker's sealed balance did not cover the escrow, the terms were not valid, or the opening computation expired. Nothing moved. |
side 0 | base | In deposit and withdraw: the base token. |
side 1 | quote | In deposit and withdraw: the quote token. |
OrderReturned.reason 0 | book full | A dark order found no free slot. |
OrderReturned.reason 1 | cancelled | The owner cancelled the order while it was pending. |
OrderReturned.reason 2 | expired | The order reached the head of the queue after its expiry. |
OrderReturned.reason 3 | balance busy | The owner's balance had another computation in flight when the order reached the head of the queue. |
Deal.buy true | maker buys | The maker buys the base token and a taker sells it. |
Deal.buy false | maker sells | The maker sells the base token and a taker buys it. |
Setup calls
These are sent by the venue and by no one else.
| Instruction | Signer | Does |
|---|---|---|
initialize | the program's upgrade authority | Creates Config with fee_recipient, keeper and sounding_interval, and makes the signer its authority. |
set_config | Config.authority | Changes any of authority, keeper, fee_recipient, hadal_mint, protocol_share_bps and sounding_interval. Emits ConfigChanged. |
init_<circuit>_comp_def | Config.authority | One per circuit, eleven in all. Registers the circuit with Arcium, with its hash compiled into the program. |
Errors: NotAuthority, InvalidConfig.