Settling a position

import { CLOSE_REASON_BY_CODE, CLOSE_REASON_CODE, isPermissionless } from '@rekt/1000x';

export const codeOf = CLOSE_REASON_CODE; // name -> on-chain discriminant
export const nameOf = CLOSE_REASON_BY_CODE; // discriminant -> name
export const permissionless = isPermissionless; // everything except an unrequested `voluntary`

import { settlePreview, type ConfigView, type PositionView } from '@rekt/1000x';

export function chooseReason(
  position: PositionView,
  config: ConfigView,
  exitPrice: bigint,
  nowUnix: bigint,
  submitter: string,
  owner: string,
) {
  const preview = settlePreview(position, config, exitPrice, nowUnix, submitter, owner);

  // null when nothing is legal yet: that is a wait, not a failure.
  const reason = preview.suggested;
  const row = preview.reasons.find((r) => r.reason === reason) ?? null;

  return { preview, reason, payouts: row?.payouts ?? null, capped: row?.capped ?? false };
}

import {
  settleGates,
  type ConfigView,
  type GateReport,
  type MarketView,
  type Payouts,
  type PositionView,
  type QuoteView,
  type SettlePreview,
} from '@rekt/1000x';

/**
 * What LEAVES the vault when this position closes: the quantity the program's solvency guard
 * compares against the position's reserve. `poolDelta` stays inside the vault. `p.liquidator` reads
 * 0n on every settlement; keep it in the sum so this is the program's arithmetic, and never render
 * it as money a submitter receives.
 */
const totalOutflow = (p: Payouts): bigint => p.trader + p.liquidator + p.insurance + p.protocol;

export function gatesForSettle(args: {
  config: ConfigView;
  market: MarketView;
  marketAddress: string;
  position: PositionView;
  quotes: QuoteView[];
  preview: SettlePreview;
  reason: string;
  ownerIsSubmitter: boolean;
}): GateReport {
  const row = args.preview.reasons.find((r) => r.reason === args.reason) ?? null;

  return settleGates({
    config: args.config,
    market: args.market,
    // The market the SUBMITTER intends to use, passed deliberately so a caller that has two
    // markets confused is caught by the first gate rather than by the chain.
    marketAddress: args.marketAddress,
    position: args.position,
    quotes: args.quotes,
    outflow: row?.payouts ? totalOutflow(row.payouts) : null,
    // Always false: no settlement pays a submitter.
    liquidatorPaid: false,
    liquidatorTokenNamed: false,
    ownerIsSubmitter: args.ownerIsSubmitter,
    // Pass the reason. Omit it and you get no row for the one thing most likely to be wrong.
    reason: {
      name: args.reason,
      legal: row?.legal ?? false,
      why: row?.why ?? 'the engine names no such reason',
    },
  });
}

import { PublicKey } from '@solana/web3.js';
import {
  CLOSE_REASON_CODE,
  assetId,
  configPda,
  ix,
  lastResortTableRemaining,
  marketPda,
  priceAccountsFor,
  toHex,
  traderPda,
  vaultPda,
  withCapitalRiders,
  withFeeTermsTable,
  type BuiltInstruction,
  type CloseReasonName,
  type ConfigView,
  type MarketView,
  type TraderAccountView,
} from '@rekt/1000x';

export function buildSettle(args: {
  /** The decoded config, read for this request. */
  config: ConfigView;
  symbol: string;
  market: MarketView;
  /** True when the pool is on: `capitalActive(vaultBytes, capitalStateBytes)`. */
  poolOn: boolean;
  submitter: PublicKey;
  owner: PublicKey;
  /** The owner's book, decoded: the payout destination is read from it. */
  book: TraderAccountView;
  seq: bigint;
  reason: CloseReasonName;
  protocolToken: PublicKey;
  vaultToken: PublicKey;
  /** The session key's `TradeDelegate` PDA, or null when the OWNER is closing. */
  delegate: PublicKey | null;
}): BuiltInstruction {
  const built = ix.settle(
    {
      submitter: toHex(args.submitter),
      config: toHex(configPda().address),
      market: toHex(marketPda(assetId(args.symbol)).address),
      positions: toHex(traderPda(args.owner).address),
      vault: toHex(vaultPda().address),
      vault_token: toHex(args.vaultToken),
      // The book's recorded payout destination, and nothing else. Any other account is not paid:
      // the payout is held on the book instead.
      owner_token: args.book.payoutDestination,
      protocol_token: toHex(args.protocolToken),
      // Optional as a pair: both or neither. Pass neither.
      insurance: null,
      insurance_token: null,
      delegate: args.delegate ? toHex(args.delegate) : null,
    },
    args.seq, // the handle, never the slot index
    CLOSE_REASON_CODE[args.reason],
    args.reason === 'lastResort'
      ? // No quote and no sysvar: the governance table (it is how the program asks the dark arm),
        // then the market's fee-terms account, which rides writable.
        withFeeTermsTable(lastResortTableRemaining(), args.market, args.config, 'last_resort')
      : // A priced reason carries the Instructions sysvar, the governance table, and the market's
        // fee-terms account when it has terms. Without the table the program refuses the settle
        // (`GovTableRequired`, 6221).
        priceAccountsFor(args.market, args.config, 'settle'),
  );
  // The pool's accounts come last: `CapitalState` and the queue ring, both writable.
  return withCapitalRiders(built, 'settle', args.poolOn);
}

import { Connection, Keypair, PublicKey } from '@solana/web3.js';
import {
  SenderRefusal,
  computeUnitLimit,
  submitBenchmarkQuoted,
  type BuiltInstruction,
  type GateReport,
  type MarketView,
  type PostedQuote,
  type SubmitOutcome,
} from '@rekt/1000x';

/** A signed quote for one market, as the send needs it. */
export interface SignedQuote {
  /** The quote's assembled ed25519 instruction data, hex, exactly as it arrived. */
  ed25519InstructionDataHex: string;
  /** The ed25519 program id the quote names. */
  ed25519ProgramId: PublicKey;
  /** What the signed payload decodes to: price, publish slot, distinct signers. */
  quote: PostedQuote;
}

export async function sendSettle(args: {
  connection: Connection;
  payer: Keypair;
  built: BuiltInstruction;
  signed: SignedQuote;
  market: MarketView;
  protocolGates: GateReport;
  priorityFeeMicroLamports: number;
  /** Leave true until you have watched this path work. It sends nothing. */
  dryRun: boolean;
}): Promise<SubmitOutcome> {
  try {
    const out = await submitBenchmarkQuoted({
      connection: args.connection,
      commitment: 'confirmed',
      ed25519InstructionDataHex: args.signed.ed25519InstructionDataHex,
      ed25519ProgramId: args.signed.ed25519ProgramId,
      quote: args.signed.quote,
      built: args.built,
      payer: args.payer,
      signers: [args.payer],
      priorityFeeMicroLamports: args.priorityFeeMicroLamports,
      protocolGates: args.protocolGates,
      minSignatures: args.market.minSignatures,
      dryRun: args.dryRun,
    });

    console.log(
      `${args.built.name}: ${out.bytes} bytes, ${out.simulatedCu} CU of ${computeUnitLimit(args.built.name)} declared`,
    );
    // Read `confirmation` before `revert`: a send the cluster never confirmed (`expired`,
    // `unconfirmed`) also carries `revert: null`. Read the chain before you send it again.
    if (out.signature === null) console.log('dry run: nothing was sent');
    else if (out.confirmation !== 'confirmed') console.log(`sent ${out.signature}, ${out.confirmation}`);
    else if (out.revert !== null) console.log(`reverted ${out.signature}: ${JSON.stringify(out.revert)}`);
    else console.log(`landed ${out.signature}`);
    return out;
  } catch (e) {
    // A refusal before signing: a failed gate, a short quote, or a packet that does not fit.
    if (e instanceof SenderRefusal) console.error(`refused before signing: ${e.message}`);
    throw e;
  }
}

import { isConserving, type Payouts, type PositionView } from '@rekt/1000x';

export function assertConserved(payouts: Payouts, position: PositionView): void {
  // poolDelta === collateral - (every leg that leaves the vault)
  if (!isConserving(payouts, position.collateral)) {
    throw new Error('the settlement legs do not conserve: do not send another trade until this is explained');
  }
}

import { Connection, PublicKey } from '@solana/web3.js';
import {
  closedTradesInTransaction,
  confirmSignature,
  connectionSignatureReader,
  receiptOf,
  type ConfigView,
} from '@rekt/1000x';

export async function closeResult(
  conn: Connection,
  signature: string,
  lastValidBlockHeight: number,
  owner: PublicKey,
  mint: PublicKey,
  config: ConfigView,
  seq: bigint,
) {
  const out = await confirmSignature(connectionSignatureReader(conn), signature, lastValidBlockHeight, {
    waitMs: 12_000,
  });
  // `unconfirmed` may still land: look the signature up again before you send anything else.
  if (out.confirmation !== 'confirmed') return { verdict: out.confirmation } as const;
  if (out.err !== null) return { verdict: 'reverted', err: out.err } as const;
  if (out.landed === null) return { verdict: 'landed' } as const;
  const receipt = receiptOf(out.landed, { tokenOwners: [owner.toBase58()], mint: mint.toBase58() });
  // Match the seq: one transaction can settle several of the owner's positions (a keeper batch).
  const trade = closedTradesInTransaction(out.landed, owner, config).find((t) => t.seq === seq) ?? null;
  // `receipt.ownerDelta` is what reached the owner's token accounts in this transaction.
  return { verdict: 'landed', trade, paidToOwner: receipt.ownerDelta, complete: receipt.complete } as const;
}

import { connectionReader, readSettlementForSeq } from '@rekt/1000x';

// `minContextSlot`: the slot of the read that showed the position gone.
const [trade] = await readSettlementForSeq(connectionReader(conn), owner, [seq], config, { minContextSlot });

import { connectionReader, memoReader, readTradeHistory } from '@rekt/1000x';

const reader = memoReader(connectionReader(conn)); // keep it for the life of the process
const first = await readTradeHistory(reader, owner, config); // 1 list + one read per transaction
const again = await readTradeHistory(reader, owner, config); // 1 list call when nothing is new