Read your receipts
What a receipt holds, what each action writes into it, and how to read it in the app, with the SDK and from the HTTP API.
A receipt is the result of one action, written by the computation that performed it and encrypted to your reading key. The chain stores it as ciphertext. Your browser or your script opens it with the key, and nobody else can.
Where a receipt lives
Your sealed balance in a market is one ledger: your base, your quote, your liquidity shares, and the receipt of the last action that computed on it. Every such action writes the whole ledger again, so the receipt in your balance is always the latest one.
An order keeps its own copy. When an order is processed, collected or cancelled, the ledger that computation produced is also stored on the order's account, so an order's receipt stays readable after later actions have replaced the one in the balance.
Each ledger is also carried, still as ciphertext, in the event of the computation that wrote it. The HTTP API serves those as your receipt history.
The fields
A ledger read with your key:
| Name | Type | Meaning |
|---|---|---|
base | bigint | Your sealed balance of the base token after the action, in atoms. |
quote | bigint | Your sealed balance of the quote token after the action, in atoms. |
shares | bigint | Your liquidity shares after the action. |
receipt | Receipt | The result of the action, below. |
The receipt, as it reads for an order:
| Name | Type | Meaning |
|---|---|---|
ok | boolean | False when the action was void or refused: the balance did not cover it, or a deal did not cross. Nothing moved. |
filled | bigint | Base atoms that traded. |
quote | bigint | Quote atoms paid for them (a buy) or received (a sell). |
crossed | bigint | Base atoms filled against resting orders at the pool's mid. |
swept | bigint | Base atoms filled on the pool's curve. |
rested | bigint | Base atoms left resting in the book. |
fee | bigint | The fee, in quote atoms. |
Atoms are told in Units. A receipt holds no price: the average price of a fill is quote divided by filled, and priceOf(receipt.quote, receipt.filled) gives it in the unit of a limit. For an order, filled is always crossed plus swept.
What each action writes
The same seven fields carry the result of every kind of action. For anything that is not a trade, filled and quote hold what was credited to the balance in base and in quote, and swept holds liquidity shares.
| Action | ok | filled | quote | crossed | swept | rested | fee |
|---|---|---|---|---|---|---|---|
| Swap or dark order, processed | false when void | base traded | quote paid or received | base crossed | base swept | base resting | fee in quote |
| Deposit | true | base deposited | quote deposited | 0 | 0 | 0 | 0 |
| Withdraw | true when paid, false when refused | 0 | 0 | 0 | 0 | 0 | 0 |
| Collect | true | base credited | quote credited | 0 | 0 | 0 | 0 |
| Cancel of a resting order | true | base credited | quote credited | 0 | 0 | 0 | 0 |
| Add liquidity | true when added | base put in the pool | quote put in the pool | 0 | shares received | 0 | 0 |
| Remove liquidity | true when removed | base returned | quote returned | 0 | shares given up | 0 | 0 |
| Create market, when its pool opens | true | 0 | 0 | 0 | shares received | 0 | 0 |
| Open deal | true when the escrow left the balance | 0 | 0 | 0 | 0 | 0 | 0 |
| Answer a deal | true when it traded | base traded | quote at the midpoint | base traded | 0 | 0 | the taker's deal fee |
| A deal closed, for its maker | true | base credited | quote credited | 0 | 0 | 0 | 0 |
When ok is false, every other field is zero and the balance is unchanged.
Some rows need a second look:
- Order.
quoteincludes the sweep fee and excludes the cross fee, andfeeis the two together. The guide to a swap shows how the balance moves. - Deposit. One of
filledandquoteis the amount, by the token deposited. - Collect and cancel. A sell is credited quote for what filled and, on a cancel, the base that never filled. A buy is credited base for what filled and, on a cancel, the quote lock that was not spent. See Place a dark order.
- Liquidity. Provide liquidity tells when a change is refused.
- Deals. An answer that does not trade writes
okfalse: that is a no deal. The maker's receipt is written when the deal is closed and holds the escrow that came back and the proceeds, by side as for a cancel. See Answer a deal and Open a deal.
A dark order that fills whole when it is processed, or is void, closes with the receipt of that computation. An order closed without a computation has no receipt: one cancelled while pending, one whose expiry passed before its turn, one whose owner's balance was busy, and a dark order that found the book full.
In the app
Receipts are read in your browser once you have unlocked. Locked, each place below shows Locked with an Unlock button.
| Place | Shows |
|---|---|
The order ticket | The result of the order you just placed, under the button: what filled and at what average price, what crossed at the mid, what swept the curve, what is resting, what returned to your balance, and the fee. |
Trade, Receipts tab | The latest 20 receipts, beside Open orders. |
Portfolio, Receipts | All of them. |
The two tables list the receipts of the orders you placed and the deals you answered in this browser, each read with your key when its computation landed. The Filled at placing column of Open orders comes from the same receipt. The history of every action, from any device, is the one the API serves.
Each row of a receipts table has these columns:
| Column | From the receipt |
|---|---|
Time | When the result was written, UTC. |
Order | Swap, Dark order or Deal, and Buy or Sell. |
Market | The pair. |
Filled | filled, in the base token. |
Average price | quote divided by filled. Empty when nothing filled. |
Crossed | crossed. |
Swept | swept. |
Fee | fee, in the quote token. |
Result | Filled, Partly filled, Returned unfilled, Expired, Cancelled or Failed. |
One order's receipt with the SDK
The samples assume hadal, payer, market and key as set up in the Quickstart, and order, the address a swap or darkOrder call returned as account.
const { status, receipt } = await hadal.order(order, key)
if (receipt) {
const { ok, filled, quote, crossed, swept, rested, fee } = receipt.receipt
}status is public: pending, resting or closed. receipt is the ledger stored on the order, or null while the order has none. Called without a key, order returns the status alone.
Your own order's sealed terms open the same way. They give the size you placed, from which the part that returned to your balance is the size less filled and rested:
import { nonceFromBigInt } from '@hadal/sdk'
const { account } = await hadal.order(order)
const sealer = await hadal.sealer(key)
const [buy, size, limit] = sealer.open({
ciphertexts: account.terms,
nonce: nonceFromBigInt(BigInt(account.nonce.toString())),
})buy is 1 for a buy and 0 for a sell. The terms hold two more values after these three: the two halves of the address the order was sealed for.
A wallet has one reading key. Read with any other key, a ledger or an order's terms decode to noise, not to an error.
The balance's last receipt
const ledger = await hadal.balance(market, key)
if (ledger) {
const { base, quote, shares, receipt } = ledger
}balance returns null when you have no balance in the market or nothing has landed in it yet. This is the receipt to read after a deposit, a withdrawal, a liquidity change or a deal, none of which has an order to keep it: read it when the action's computation has landed and before the next action on the balance replaces it.
The whole history from the API
GET /v1/wallets/:wallet/receipts returns one receipt for every computation that wrote your ledger: a deposit that landed, a withdrawal paid or refused, an order processed, a collect, a cancel of a resting order, a liquidity change, a market's pool opening, and a deal opened, answered or closed. Each item is the ledger exactly as that computation left it, as ciphertext, with public fields that say what it belongs to.
| Field | Type | Meaning |
|---|---|---|
id | string | The receipt. |
owner | string | The wallet it is sealed to. |
market | string | The market of the balance. |
balanceId | string | The address of the balance account the ledger belongs to. |
orderId | string | null | The order's address, when an order, a collect or a cancel wrote it. |
dealId | string | null | The deal's address, when opening, answering or closing a deal wrote it. |
transferId | string | null | The transfer, when a deposit or a withdrawal wrote it. |
time | number | When it was written: milliseconds since the Unix epoch, UTC. |
signature | string | The transaction of the callback that wrote it. |
slot | number | The slot of that transaction. |
layout | 'ledger-v1' | The ledger layout that Sealer.ledger decodes. |
values | Sealed | The ledger's ciphertexts and nonce, base64, and the public key they are sealed to. |
The API never holds your key. Sealer.ledger opens each item in your script.
type Item = {
market: string
orderId: string | null
dealId: string | null
transferId: string | null
time: number
values: { ciphertexts: string[]; nonce: string }
}
const bytes = (base64: string) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0))
const sealer = await hadal.sealer(key)
let cursor: string | null = null
do {
const url = new URL(`${api}/v1/wallets/${payer.publicKey.toBase58()}/receipts`)
url.searchParams.set('limit', '100')
if (cursor) url.searchParams.set('cursor', cursor)
const body: { items: Item[]; page: { nextCursor: string | null } } = await (await fetch(url)).json()
for (const item of body.items) {
const ledger = sealer.ledger({
ciphertexts: item.values.ciphertexts.map(bytes),
nonce: bytes(item.values.nonce),
})
console.log(new Date(item.time).toISOString(), item.orderId ?? item.dealId ?? item.transferId, ledger.receipt)
}
cursor = body.page.nextCursor
} while (cursor)api is the API's base URL. The ciphertexts and the nonce arrive as base64. values.encryptionKey is the public half of the reading key the ledger is sealed to: it equals your key.publicKey. Read the items with the receipt table in What each action writes: an item with an orderId is that order being processed, collected or cancelled, an item with a transferId is a deposit or a withdrawal, and an item with a dealId is a deal.