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
Guides

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:

NameTypeMeaning
basebigintYour sealed balance of the base token after the action, in atoms.
quotebigintYour sealed balance of the quote token after the action, in atoms.
sharesbigintYour liquidity shares after the action.
receiptReceiptThe result of the action, below.

The receipt, as it reads for an order:

NameTypeMeaning
okbooleanFalse when the action was void or refused: the balance did not cover it, or a deal did not cross. Nothing moved.
filledbigintBase atoms that traded.
quotebigintQuote atoms paid for them (a buy) or received (a sell).
crossedbigintBase atoms filled against resting orders at the pool's mid.
sweptbigintBase atoms filled on the pool's curve.
restedbigintBase atoms left resting in the book.
feebigintThe 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.

Actionokfilledquotecrossedsweptrestedfee
Swap or dark order, processedfalse when voidbase tradedquote paid or receivedbase crossedbase sweptbase restingfee in quote
Deposittruebase depositedquote deposited0000
Withdrawtrue when paid, false when refused000000
Collecttruebase creditedquote credited0000
Cancel of a resting ordertruebase creditedquote credited0000
Add liquiditytrue when addedbase put in the poolquote put in the pool0shares received00
Remove liquiditytrue when removedbase returnedquote returned0shares given up00
Create market, when its pool openstrue000shares received00
Open dealtrue when the escrow left the balance000000
Answer a dealtrue when it tradedbase tradedquote at the midpointbase traded00the taker's deal fee
A deal closed, for its makertruebase creditedquote credited0000

When ok is false, every other field is zero and the balance is unchanged.

Some rows need a second look:

  • Order. quote includes the sweep fee and excludes the cross fee, and fee is the two together. The guide to a swap shows how the balance moves.
  • Deposit. One of filled and quote is 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 ok false: 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.

PlaceShows
The order ticketThe 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 tabThe latest 20 receipts, beside Open orders.
Portfolio, ReceiptsAll 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:

ColumnFrom the receipt
TimeWhen the result was written, UTC.
OrderSwap, Dark order or Deal, and Buy or Sell.
MarketThe pair.
Filledfilled, in the base token.
Average pricequote divided by filled. Empty when nothing filled.
Crossedcrossed.
Sweptswept.
Feefee, in the quote token.
ResultFilled, 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.

ts
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:

ts
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

ts
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.

FieldTypeMeaning
idstringThe receipt.
ownerstringThe wallet it is sealed to.
marketstringThe market of the balance.
balanceIdstringThe address of the balance account the ledger belongs to.
orderIdstring | nullThe order's address, when an order, a collect or a cancel wrote it.
dealIdstring | nullThe deal's address, when opening, answering or closing a deal wrote it.
transferIdstring | nullThe transfer, when a deposit or a withdrawal wrote it.
timenumberWhen it was written: milliseconds since the Unix epoch, UTC.
signaturestringThe transaction of the callback that wrote it.
slotnumberThe slot of that transaction.
layout'ledger-v1'The ledger layout that Sealer.ledger decodes.
valuesSealedThe 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.

ts
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.

Next