Hidden-Size Limit Orders
Place, fill, cancel, and expire hidden-size limit orders backed by PrivateEscrowOrder PDAs in /trade and @mera/sdk.
Hidden-size limit orders let a maker post limit liquidity without revealing order size to the market. When you place an order, place_hidden_order spends your input CommitmentNote into a PrivateEscrowOrder PDA and publishes only the pair, side, price band (+/- 0.2% around limitPrice), expirySlot, and 32-byte sizeCommitment on the public book (GET /v1/orders).
Order lifecycle
- Open (`status = "open"`, on-chain `0`). Maker locks encrypted size into
PrivateEscrowOrderPDA (["escrow", ring, maker, SHA-256(orderId)]).ShieldedVault.total_locked_escrowincreases by the locked amount. - Filled (`status = "filled"`, on-chain `1`). A counterparty calls
fill_hidden_orderbeforeexpiry_slot. The taker's input note is spent, the protocol fee (FEE_BPS) is transferred from the taker's vault toProtocolConfig.fee_recipient, both sides receive newCommitmentNoteoutputs,total_locked_escrowdecreases, and anRfqSettlementRecordwith TVK receipt is emitted. - Cancelled (`status = "cancelled"`, on-chain `2`). Maker calls
cancel_hidden_orderat any time while open.0bps fee is charged,total_locked_escrowdecreases, and a new refundCommitmentNotereturns the full locked amount to the maker. - Expired (`status = "expired"`, on-chain `3`). Once Solana reaches
clock.slot >= expiry_slot, either the maker or Mera's keeper callscancel_hidden_order(expire-escrowsruns every 10 seconds), returning the full locked amount to a new refundCommitmentNoteowned by the maker with0bps fee.
Placing a hidden-size limit order
In /trade
- Open Terminal and select the Hidden Order tab.
- Choose pair, side (
selllocks base asset;buylocks quote asset), limit price, hidden size, and expiry in slots (default1200slots, valid range50to500,000). - Press Place Hidden Order and sign the transaction. Your order appears in the public order book with its price band and
sizeCommitmenthash, and in your private Active Hidden Orders table with your plaintext size.
With @mera/sdk
ts
import { createMeraClient, keypairSigner } from '@mera/sdk'
const mera = createMeraClient({
apiUrl: 'http://127.0.0.1:36102',
signer: keypairSigner(makerKeypair),
})
// Lock 5 SOL at a $190.50 limit sell price for 1200 slots
const { orderId, submission } = await mera.placeHiddenOrder({
ringId: 'ring-default',
pairId: 'SOL-USDC',
side: 'sell',
limitPrice: 190.5,
size: '5000000000',
expirySlots: 1200,
})
console.log('Order ID:', orderId, 'Signature:', submission.signature)Reading the public book vs your own orders
mera.getHiddenOrders({ ringId: 'ring-default', pairId: 'SOL-USDC', status: 'open' })returns paginatedPublicHiddenOrderentries withpriceBand,limitPrice,sizeCommitment, andexpirySlot, withoutplaintextSizeormaker.mera.getMyHiddenOrders(wallet, 'ring-default')returns your ownMyHiddenOrderentries includingplaintextSize,baseSymbol,quoteSymbol, andbaseDecimals.
Filling a hidden-size limit order
Any wallet with access to the Ring and sufficient shielded counterparty balance can fill an open order before expirySlot:
ts
const fill = await mera.fillHiddenOrder(
orderId,
{}, // optional counterpartyAmount; defaults to exact limitPrice * order size
keypairSigner(takerKeypair),
)
console.log('Filled in:', fill.finalityMs, 'ms')
console.log('Settlement ID:', fill.settlementId)
console.log('TVK receipt:', fill.tvk)Cancelling an open order
Only the maker can cancel an order before expirySlot. After expirySlot, any caller (including Mera's keeper) can trigger expiry refund to the maker.
ts
const cancelled = await mera.cancelHiddenOrder(orderId, keypairSigner(makerKeypair))
console.log('Cancelled and refunded:', cancelled.signature)Failure cases
ORDER_NOT_OPEN(409/ on-chain6010): The order was already filled, cancelled, or expired.OrderExpired(6011):fill_hidden_orderwas submitted at or afterexpiry_slot, orplace_hidden_ordersupplied anexpiry_slot <= clock.slot.INSUFFICIENT_SHIELDED_BALANCE(400/ on-chain6007): Maker lacks an unspent note coveringsize, or taker lacks an unspent note covering the counterparty amount.Unauthorized(6008): A non-maker attempted to cancel an order beforeexpiry_slot.