Orders and closes

​

The timing settings

import { Connection } from '@solana/web3.js';
import {
  configPda,
  decodeConfig,
  decodeGovTable,
  exitWindowSlots,
  fillDeadlineSlots,
  govTablePda,
  timingInForce,
} from '@rekt/1000x';

export async function readTiming(connection: Connection) {
  const [configInfo, govInfo] = await connection.getMultipleAccountsInfo(
    [configPda().address, govTablePda().address],
    'confirmed',
  );
  if (configInfo === null) throw new Error('the config account is missing');
  const config = decodeConfig(new Uint8Array(configInfo.data));
  const gov = govInfo === null ? null : decodeGovTable(new Uint8Array(govInfo.data));
  // `null` for a setting that is not in force. There is no default: do not invent one.
  const timing = timingInForce(config, gov);
  return {
    config,
    timing,
    fillDeadline: fillDeadlineSlots(timing), // d + T_fill, from the slot the order landed in
    firstExitWindowEnds: exitWindowSlots(timing), // d + W, from the slot the request landed in
  };
}

​

Opening: an order, then a fill

1. Send open. It carries no quote. Its remaining accounts are the market’s fee-terms account when the market has terms (priceAccountsFor(market, config, 'open')). When it lands, the stake is taken, the slot holds the order with entryPrice 0, and PositionOpened carries the sequence number. It is an order, not yet a position.
2. The entry price is the first price of the venue’s price feed at or after d slots from the slot in which the open landed. A listed filler writes it. Read it from the event EntryFilled (entryPrice, quoteSlot), or from a non-zero entryPrice on your own book.
3. Or the order is returned. The event is OpenVoided: cause, refundTotal, feeKept and delivered. An order is returned when the first price came too late or did not meet the venue’s quality rule, when the market closed, or when no filler landed inside d + T_fill slots of the order. refundTotal is the whole stake, and feeKept reads 0. delivered false means the payout destination could not receive the refund, and it is held on the book: claim it with claimPayout.
4. You cannot fill your own order (NotAListedFiller, 6205). You need not return it either: after d + T_fill slots anyone may send void_open, and the venue’s keepers do.

import { Connection, PublicKey } from '@solana/web3.js';
import { decodeTraderAccount, findBySeq, phase, traderPda, type Phase } from '@rekt/1000x';

/** Where an order stands: 'PendingOpen' until the fill, then the position's phase, or 'gone'. */
export async function orderState(
  connection: Connection,
  owner: PublicKey,
  seq: bigint,
): Promise<Phase | 'gone'> {
  const [info, nowSlot] = await Promise.all([
    connection.getAccountInfo(traderPda(owner).address, 'confirmed'),
    connection.getSlot('confirmed'),
  ]);
  if (info === null) return 'gone';
  const position = findBySeq(decodeTraderAccount(new Uint8Array(info.data)), seq);
  // Gone: returned (`OpenVoided`) or already settled. The events say which.
  if (position === null) return 'gone';
  // After the fill, `position.entryPrice` is the entry and `position.openedSlot` its slot.
  return phase(position, nowSlot);
}

​

Doubling down

• CollateralAdded. A filler priced the add at the first price at or after addTarget. It carries the new entry (entryPrice) and the entry before it (entryPriceBefore).
• AddReversed. The added stake is returned in full (refundTotal), as for a returned order. cause is one of the open’s causes, or 8 (the price was outside the position’s limits: at the add’s price the position was already at its barrier or its target) or 9 (the position was knocked out first).

• Until one of the two arrives, and then for M_add slots after the price of a filled add, a close request, a retarget, an expiry mark and a second add return AddPending (6211). closableFromSlotOf includes that time.
• A reversed add keeps the time it added to the timer. Its stake comes back.
• A knockout price from before the add still counts in that time. A price that breached the barrier of the entry in force at its slot can still prove the knockout. KnockoutBeforeAdd reports it, the position is knocked out on its old stake, and the added stake comes back (AddReversed, cause 9).
• A touch of the take-profit target while an add waits for its price cannot be stamped, and it is lost if the add is then filled.
• addCollateralForMode refuses to build an add while adds are off (AddsDisabled, 6212).

​

Closing: a request, then a settle

1. Send request_close, signed by the owner or a session key. It carries no quote, so it cannot fail on a stale price. CloseRequested.exitTarget is the slot d after the request.
2. The exit price is the first price of the venue’s price feed at or after exitTarget. The close is done when SettlementPriced and SettlementReceipt arrive.
3. Anyone may send that settle, and the venue’s keepers do. isPermissionless('voluntary', phase) is true once the phase is ExitRequested.
4. The window rule. If nobody settles inside W slots of the target, the price becomes the first price of the next window of W slots, and so on. SettlementReceipt.window is the count of windows that rolled: 0 for a close settled in its first window.
5. A request cannot be withdrawn. A second request returns ExitPending (6213): treat it as success.
6. SettlementPriced.unverified reads true while a market lists one price feed. A price from a single feed is unverified by construction; it does not mean the price was wrong. Do not show a warning or a badge from it.

import { PublicKey } from '@solana/web3.js';
import { assetId, configPda, ix, marketPda, toHex, traderPda } from '@rekt/1000x';

export function buildRequestClose(args: {
  owner: PublicKey;
  /** The owner, or a session key they authorised. */
  signer: PublicKey;
  /** `delegatePda(owner).address` when a session key signs, else null. */
  delegate: PublicKey | null;
  symbol: string;
  seq: bigint;
}) {
  return ix.requestClose(
    {
      authority: toHex(args.signer),
      config: toHex(configPda().address),
      // The position's own market: it carries the market's hold.
      market: toHex(marketPda(assetId(args.symbol)).address),
      positions: toHex(traderPda(args.owner).address),
      delegate: args.delegate === null ? null : toHex(args.delegate),
    },
    args.seq,
  );
}

​

The minimum hold

• The venue has one hold for every market: resolveMinHoldSlots(config.minHoldSlots). A market can have a longer one: market.closeHoldSlots (0 is none). The hold in force is the larger of the two (holdInForce).
• It counts from the entry price: EntryFilled.quoteSlot, and after a filled double-down from the add’s price, which is the position’s openedSlot on the book.
• A close request inside it returns MinimumHoldNotMet (6103) for the venue’s hold or MarketHoldNotMet (6236) for the market’s. Neither one is a failure of the position.
• “Can close in N seconds”, with no guess: closableFromSlotOf(position, config, market) is the first slot at which a request can land, from three public accounts. It is null while the position is an order or an add waits. slotsUntil(slot, nowSlot) counts the slots, and estimatedSecondsUntil(slots, slotMs) turns them into an estimate that you label as one.
• The request must land at or after that slot.
• A take-profit proof must also clear both holds, on the slot of its own price.
• A knockout is never held back. A market’s own hold never holds back a timer end.

​

Timers

• From the deadline, anyone may send mark_expiry with reason 3 (userExpiry) or 4 (tenorExpiry). ExpiryMarked.exitTarget is the slot d after the mark, and the exit price is the first price at or after it, by the same window rule as a close.
• A settle with an expiry reason on a position that has no exit target returns ExitNotAnchored (6214): mark it first.
• A wrapper such as Minute sends the mark and then its own settle from slot exitTarget on: two transactions, at least d slots apart.
• A timer is 0 or at least 26 seconds, at the open and after an add (TimerBelowFloor, 6225).

​

Knockouts and take-profits

• Anyone may prove a level with any signed price that is newer than the entry and at most W_ko slots old. So a position can be knocked out by a price up to W_ko slots old.
• After a close request or an expiry mark, only a price that is not later than the exit price can prove a level (ExitPending otherwise).
• While an add waits for its price, a touch of the take-profit target cannot be stamped, and it is lost if the add is then filled.
• After a take-profit retarget, only a price at least d slots after the retarget proves the new target (TakeProfitProofTooEarly, 6220).
• stamp_book records the level on the book; the settle that pays it follows. It is the only stamp that can prove a knockout with a price from before a filled double-down.

​

Settling or stamping for others

• A settle of a requested or marked exit needs the window quote: the first price of the venue’s price feed at or after the start of the current window, exitTarget + K × W, where K is the count of whole windows since the target. Any other quote returns NotWindowQuote (6217).
• stamp_book needs any signed price that breaches the level, inside the W_ko look-back.
• To obtain a quote, see Getting prices.

​

Three more rules

• Show “side full” before the tap when a limit is set. A market can carry a limit on the stake of one side: an amount, a share of the pool, or both, and the smaller one is in force. With no limit set, nothing refuses. sideRoom(direction, market, vault, vaultBalance) reads the room from the market’s two stake counters, its two limits and the pool’s assets. On a full side whoever lands first gets the room: there is no waiting list for it. A full side returns SideStakeCapReached (6224). (The queue of how a win is paid is a different thing: it orders payouts, not room.)
• A client may settle its own requested close in the first window, with the window quote. That keeps the first price. If nobody settles in W slots, the next window’s price applies, and a knockout price in between counts. The count of rolled exits is public: SettlementReceipt.window is not 0 for them.
• Read a position through the SDK’s accessors: phase, isUnfilled, pendingAdd, addTargetSlot, addMemo, memoIsLive, exitTargetSlot, exitReason and tpFloorSlot. The same raw bytes of a position mean different things in different states. See reading positions.

​

What a client must never assume

• That the price on screen at the tap is the entry or the exit. It is the next price after the delay.
• That a landed open is a position. It is an order until EntryFilled.
• That a landed request_close is a close. It is a close at SettlementPriced.
• That PositionOpened carries the entry. It has no price field. A position’s entryPrice on the book is 0 until EntryFilled. Take entries from EntryFilled and CollateralAdded, and returns from OpenVoided and AddReversed.
• That a price in one of Minute’s round events is a price. See integrating Minute.
• That a second transaction is safe after a timeout. Never sign a second order for the same intent inside one blockhash life. Send the same signed bytes again.
• That adds are on. addCollateralForMode refuses to build one while they are off.
• That a void or a reversal is an error. It is a normal outcome, and the stake comes back (refundTotal).
• That two events in one slot are in time order. Order by quoteSlot.

​

Events

​

Refusals a client can get