Mera
ExecutionInstant confidential swapsClear from encrypted balances in one 150ms slot.Hidden-size limit ordersLock encrypted size in a private escrow PDA.Sealed RFQ block tradesRequest signed quotes without leaking size.
Vault & AuditShielded vault & keysDeposit SOL, SPL, or Token-2022 into a Ring.Viewing key verifierDecrypt and prove a single settled fill.
Docs/Guides
3 min read

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

  1. Open (`status = "open"`, on-chain `0`). Maker locks encrypted size into PrivateEscrowOrder PDA (["escrow", ring, maker, SHA-256(orderId)]). ShieldedVault.total_locked_escrow increases by the locked amount.
  2. Filled (`status = "filled"`, on-chain `1`). A counterparty calls fill_hidden_order before expiry_slot. The taker's input note is spent, the protocol fee (FEE_BPS) is transferred from the taker's vault to ProtocolConfig.fee_recipient, both sides receive new CommitmentNote outputs, total_locked_escrow decreases, and an RfqSettlementRecord with TVK receipt is emitted.
  3. Cancelled (`status = "cancelled"`, on-chain `2`). Maker calls cancel_hidden_order at any time while open. 0 bps fee is charged, total_locked_escrow decreases, and a new refund CommitmentNote returns the full locked amount to the maker.
  4. Expired (`status = "expired"`, on-chain `3`). Once Solana reaches clock.slot >= expiry_slot, either the maker or Mera's keeper calls cancel_hidden_order (expire-escrows runs every 10 seconds), returning the full locked amount to a new refund CommitmentNote owned by the maker with 0 bps fee.

Placing a hidden-size limit order

In /trade

  1. Open Terminal and select the Hidden Order tab.
  2. Choose pair, side (sell locks base asset; buy locks quote asset), limit price, hidden size, and expiry in slots (default 1200 slots, valid range 50 to 500,000).
  3. Press Place Hidden Order and sign the transaction. Your order appears in the public order book with its price band and sizeCommitment hash, 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 paginated PublicHiddenOrder entries with priceBand, limitPrice, sizeCommitment, and expirySlot, without plaintextSize or maker.
  • mera.getMyHiddenOrders(wallet, 'ring-default') returns your own MyHiddenOrder entries including plaintextSize, baseSymbol, quoteSymbol, and baseDecimals.

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-chain 6010): The order was already filled, cancelled, or expired.
  • OrderExpired (6011): fill_hidden_order was submitted at or after expiry_slot, or place_hidden_order supplied an expiry_slot <= clock.slot.
  • INSUFFICIENT_SHIELDED_BALANCE (400 / on-chain 6007): Maker lacks an unspent note covering size, or taker lacks an unspent note covering the counterparty amount.
  • Unauthorized (6008): A non-maker attempted to cancel an order before expiry_slot.