@depthhq/sdk 0.1.0 → 0.1.1

package/dist/account/discovery.d.ts

@@ -1,5 +1,6 @@
 import * as anchor from "@anchor-lang/core";
 import { Connection, PublicKey } from "@solana/web3.js";
+import { type ReceiptTransaction } from "../chain/transaction.js";
 export type PendingKind = "deposit" | "allocation" | "release" | "withdrawal" | "trade" | "risk";
 export type PendingItem = {
     id: PublicKey;
@@ -11,6 +12,9 @@ export type PendingPage = {
     items: PendingItem[];
     nextCursor?: string;
 };
+export type ReceiptDetail = ReceiptTransaction & {
+    amount?: bigint;
+};
 export type UnpairedAllocation = {
     id: PublicKey;
     nonce: bigint;
@@ -23,6 +27,8 @@ export declare class FundingDiscovery {
     private readonly connection;
     private readonly owner;
     constructor(program: anchor.Program, connection: Connection, owner: PublicKey);
+    transaction(item: PendingItem): Promise<ReceiptDetail>;
+    detail(item: PendingItem): Promise<ReceiptDetail>;
     unpairedAllocations(options?: {
         cursor?: string;
         limit?: number;

package/dist/chain/settlement.d.ts

@@ -0,0 +1,15 @@
+import * as anchor from "@anchor-lang/core";
+import type { Connection, PublicKey, VersionedTransactionResponse } from "@solana/web3.js";
+export type SettlementTransaction = {
+    signature: string;
+    slot: number;
+    orderId: PublicKey;
+    timestamp?: number;
+};
+export declare function settlementOrder(transaction: VersionedTransactionResponse, program: anchor.Program): PublicKey | undefined;
+export declare function settlementTransaction(connection: Connection, program: anchor.Program, address: PublicKey, match: {
+    orderId: PublicKey;
+} | {
+    trader: PublicKey;
+    market: PublicKey;
+}): Promise<SettlementTransaction>;

package/dist/chain/transaction.d.ts

@@ -0,0 +1,12 @@
+import * as anchor from "@anchor-lang/core";
+import type { Connection, PublicKey, VersionedTransactionResponse } from "@solana/web3.js";
+export type ReceiptTransaction = {
+    signature: string;
+    slot: number;
+    timestamp?: number;
+};
+export declare function depthInstructions(transaction: VersionedTransactionResponse, program: anchor.Program): {
+    definition: anchor.IdlInstruction;
+    accounts: (anchor.web3.PublicKey | undefined)[];
+}[];
+export declare function receiptTransaction(connection: Connection, program: anchor.Program, address: PublicKey, names?: readonly string[]): Promise<ReceiptTransaction>;

package/dist/client/client.d.ts

@@ -7,6 +7,7 @@ import { FundingDiscovery } from "../account/discovery.js";
 import { FundingClient } from "../account/funding.js";
 import { DepthOperation } from "../operation/operation.js";
 import { DepthRecovery } from "../recovery/recovery.js";
+import { ExecutionHistory } from "../history/history.js";
 import type { AmountSelector } from "../trade/amount.js";
 import { TradeFlow } from "../trade/flow.js";
 import { DepthView } from "../view/view.js";
@@ -24,6 +25,8 @@ export declare class DepthClient {
     get funding(): FundingClient;
     get app(): AppAdmin;
     get recovery(): DepthRecovery;
+    private historyClient?;
+    get history(): ExecutionHistory;
     private constructor();
     static create(options: DepthOptions): Promise<DepthClient>;
     private verifyDeployment;
@@ -48,6 +51,8 @@ export declare class DepthClient {
     private withdrawRequest;
     private accountActions;
     readonly account: (() => {
+        detail: (item: Parameters<FundingDiscovery["detail"]>[0]) => Promise<import("../account/discovery.js").ReceiptDetail>;
+        transaction: (item: Parameters<FundingDiscovery["transaction"]>[0]) => Promise<import("../account/discovery.js").ReceiptDetail>;
         history: (options?: Parameters<FundingDiscovery["history"]>[0]) => Promise<import("../account/discovery.js").PendingPage>;
         pending: (options?: Parameters<FundingDiscovery["pending"]>[0]) => Promise<import("../account/discovery.js").PendingPage>;
         cancelOpen: () => Promise<string>;
@@ -73,6 +78,8 @@ export declare class DepthClient {
             pollMs?: number;
         }) => Promise<BalanceSnapshot>;
     }) & {
+        detail: (item: Parameters<FundingDiscovery["detail"]>[0]) => Promise<import("../account/discovery.js").ReceiptDetail>;
+        transaction: (item: Parameters<FundingDiscovery["transaction"]>[0]) => Promise<import("../account/discovery.js").ReceiptDetail>;
         history: (options?: Parameters<FundingDiscovery["history"]>[0]) => Promise<import("../account/discovery.js").PendingPage>;
         pending: (options?: Parameters<FundingDiscovery["pending"]>[0]) => Promise<import("../account/discovery.js").PendingPage>;
         cancelOpen: () => Promise<string>;

package/dist/client/types.d.ts

@@ -98,5 +98,8 @@ export type OrderState = {
     status: Record<string, unknown>;
     kind: Record<string, unknown>;
     trader: PublicKey;
+    maker?: PublicKey;
     market: PublicKey;
+    traderVersion: anchor.BN;
+    fundingIndex: anchor.BN;
 };

package/dist/history/history.d.ts

@@ -0,0 +1,26 @@
+import * as anchor from "@anchor-lang/core";
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { DepthView, FillSnapshot } from "../view/view.js";
+import { type SettlementTransaction } from "../chain/settlement.js";
+import type { PositionPnl } from "../position/pnl.js";
+export type ExecutionDetail = {
+    id: PublicKey;
+    fill: FillSnapshot;
+    pnl?: PositionPnl;
+    transaction: SettlementTransaction;
+};
+export declare class ExecutionHistory {
+    private readonly program;
+    private readonly connection;
+    private readonly owner;
+    private readonly requestView;
+    private readonly views;
+    private readonly fills;
+    private readonly transactions;
+    constructor(program: anchor.Program, connection: Connection, owner: PublicKey, requestView: (id: PublicKey) => Promise<DepthView>);
+    private orderAddress;
+    fill(id: PublicKey): Promise<FillSnapshot>;
+    execution(nonce: bigint): Promise<ExecutionDetail>;
+    private settlement;
+    private scan;
+}

package/dist/history/replay.d.ts

@@ -0,0 +1,13 @@
+import type { FillSnapshot } from "../view/view.js";
+import { type PositionPnl } from "../position/pnl.js";
+export type ReplayState = {
+    position: bigint;
+    entryPriceE8: bigint;
+    fundingCheckpoint: bigint;
+    collateral?: bigint;
+};
+export declare function replayFill(state: ReplayState, fill: FillSnapshot, fundingIndex: bigint, maker?: boolean): {
+    state: ReplayState;
+    pnl?: PositionPnl;
+};
+export declare function replayMargin(state: ReplayState, amount: bigint, toMarket: boolean): ReplayState;

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { DepthClient, createDepth, createDepth as create_depth, } from "./client/client.js";
 export { DepthOperation } from "./operation/operation.js";
+export { ExecutionHistory } from "./history/history.js";
+export type { ExecutionDetail } from "./history/history.js";
+export type { PositionPnl } from "./position/pnl.js";
+export { positionPnl } from "./position/pnl.js";
+export type { SettlementTransaction } from "./chain/settlement.js";
+export type { ReceiptTransaction } from "./chain/transaction.js";
 export { TradeFlow } from "./trade/flow.js";
 export type { TradeFlowSnapshot } from "./trade/flow.js";
 export { MarketCatalog } from "./catalog/catalog.js";
@@ -9,6 +15,7 @@ export type { DataOptions, CandleQuery } from "./catalog/data.js";
 export type { Candle, CandleInterval, CandlePage, PublicMarket, PublicApp, } from "@depthhq/schema";
 export { AppAdmin, AppRegistration, AppUpdate } from "./app/app.js";
 export { FundingDiscovery } from "./account/discovery.js";
+export type { ReceiptDetail } from "./account/discovery.js";
 export type { PendingItem, PendingKind, PendingPage, UnpairedAllocation, } from "./account/discovery.js";
 export type { AppSummary } from "./app/app.js";
 export { DepthRecovery } from "./recovery/recovery.js";

package/dist/index.js

@@ -18122,7 +18122,7 @@ https://github.com/browserify/crypto-browserify`);
 
 // src/client/client.ts
 init_buffer();
-import * as anchor6 from "@anchor-lang/core";
+import * as anchor8 from "@anchor-lang/core";
 
 // ../../node_modules/@noble/hashes/esm/crypto.js
 var crypto2 = typeof globalThis === "object" && "crypto" in globalThis ? globalThis.crypto : undefined;
@@ -43623,12 +43623,12 @@ import {
   computationName,
   DEPTH_IDL as DEPTH_IDL3,
   DEPTH_PROGRAM_ID as DEPTH_PROGRAM_ID7,
-  marketAddress as marketAddress6,
+  marketAddress as marketAddress7,
   protocolAddress as protocolAddress4,
   recoveryConfigAddress as recoveryConfigAddress2,
   SOL_USD_MARKET_ID as SOL_USD_MARKET_ID3
 } from "@depthhq/bindings";
-import { PublicKey as PublicKey8 } from "@solana/web3.js";
+import { PublicKey as PublicKey9 } from "@solana/web3.js";
 
 // src/chain/random.ts
 function randomBytes3(length) {
@@ -44625,7 +44625,7 @@ async function upgradeAuthority(connection) {
   if (!program?.executable || !program.owner.equals(loader) || program.data.length !== 36 || program.data.readUInt32LE(0) !== 2) {
     throw unavailable("Depth program is not deployed as an upgradeable program");
   }
-  const data = await connection.getAccountInfo(new PublicKey3(program.data.subarray(4)), "confirmed");
+  const data = await connection.getAccountInfo(new PublicKey3(program.data.subarray(4)), { commitment: "confirmed", dataSlice: { offset: 0, length: 45 } });
   if (!data?.owner.equals(loader) || data.data.length < 45 || data.data.readUInt32LE(0) !== 3 || data.data[12] !== 1) {
     throw unavailable("Depth deployment has no verifiable upgrade authority");
   }
@@ -44999,6 +44999,124 @@ import {
   withdrawalAddress
 } from "@depthhq/bindings";
 import { PublicKey as PublicKey4 } from "@solana/web3.js";
+
+// src/chain/transaction.ts
+init_buffer();
+import * as anchor4 from "@anchor-lang/core";
+function depthInstructions(transaction, program) {
+  if (!transaction.meta || transaction.meta.err)
+    return [];
+  const keys = transaction.transaction.message.getAccountKeys({
+    accountKeysFromLookups: transaction.meta.loadedAddresses
+  });
+  const instructions2 = [
+    ...transaction.transaction.message.compiledInstructions.map((ix) => ({
+      programIdIndex: ix.programIdIndex,
+      accounts: ix.accountKeyIndexes,
+      data: Buffer2.from(ix.data)
+    })),
+    ...(transaction.meta.innerInstructions ?? []).flatMap((group) => group.instructions.map((ix) => ({
+      programIdIndex: ix.programIdIndex,
+      accounts: ix.accounts,
+      data: Buffer2.from(anchor4.utils.bytes.bs58.decode(ix.data))
+    })))
+  ];
+  return instructions2.flatMap((ix) => {
+    if (!keys.get(ix.programIdIndex)?.equals(program.programId))
+      return [];
+    let definition = program.idl.instructions.find((item) => ix.data.subarray(0, 8).equals(Buffer2.from(item.discriminator)));
+    if (!definition && ix.data.subarray(0, 8).equals(Buffer2.from("057da1a57b4b7ec6", "hex"))) {
+      const current = program.idl.instructions.find((item) => item.name === "debitMarketV2Callback");
+      if (current)
+        definition = { ...current, name: "debitMarketCallback" };
+    }
+    return definition ? [{ definition, accounts: ix.accounts.map((index) => keys.get(index)) }] : [];
+  });
+}
+async function receiptTransaction(connection, program, address2, names) {
+  let before;
+  for (let page = 0;page < 10; page++) {
+    const signatures = await connection.getSignaturesForAddress(address2, { before, limit: 50 }, "confirmed");
+    for (const signature of signatures) {
+      if (signature.err)
+        continue;
+      const transaction = await connection.getTransaction(signature.signature, {
+        commitment: "confirmed",
+        maxSupportedTransactionVersion: 0
+      });
+      if (!transaction)
+        throw new Error("Transaction history is unavailable; retry with an archival RPC");
+      const changed = depthInstructions(transaction, program).some((ix) => (!names || names.includes(ix.definition.name)) && ix.definition.accounts.some((account, index) => ("writable" in account) && account.writable && ix.accounts[index]?.equals(address2)));
+      if (changed)
+        return {
+          signature: signature.signature,
+          slot: signature.slot,
+          ...transaction.blockTime == null ? {} : { timestamp: transaction.blockTime }
+        };
+    }
+    if (signatures.length < 50)
+      break;
+    before = signatures.at(-1).signature;
+  }
+  throw new Error(`Receipt transaction for ${address2.toBase58()} was not found in recent history`);
+}
+
+// src/chain/settlement.ts
+function settlementOrder(transaction, program) {
+  const instruction = depthInstructions(transaction, program).find((ix) => ix.definition.name === "sealClearingCallback");
+  if (!instruction)
+    return;
+  const orderIndex = instruction.definition.accounts.findIndex((account) => account.name === "order");
+  if (orderIndex < 0)
+    throw new Error("Settlement callback has no order account");
+  return instruction.accounts[orderIndex];
+}
+async function settlementTransaction(connection, program, address2, match) {
+  let before;
+  for (let page = 0;page < 10; page++) {
+    const signatures = await connection.getSignaturesForAddress(address2, { before, limit: 50 }, "confirmed");
+    for (const signature of signatures) {
+      if (signature.err)
+        continue;
+      const transaction = await connection.getTransaction(signature.signature, {
+        commitment: "confirmed",
+        maxSupportedTransactionVersion: 0
+      });
+      if (!transaction)
+        throw new Error("Transaction history is unavailable; retry with an archival RPC");
+      const orderId = settlementOrder(transaction, program);
+      if (!orderId)
+        continue;
+      if ("orderId" in match) {
+        if (orderId.equals(match.orderId))
+          return {
+            signature: signature.signature,
+            slot: signature.slot,
+            orderId,
+            ...transaction.blockTime == null ? {} : { timestamp: transaction.blockTime }
+          };
+      } else {
+        const info = await connection.getAccountInfo(orderId, "confirmed");
+        if (!info?.owner.equals(program.programId))
+          throw new Error("Settlement receipt is unavailable");
+        const order = program.coder.accounts.decode("orderRecord", info.data);
+        if (order.trader.equals(match.trader) && order.market.equals(match.market) && "trade" in order.kind && "filled" in order.status)
+          return {
+            signature: signature.signature,
+            slot: signature.slot,
+            orderId,
+            ...transaction.blockTime == null ? {} : { timestamp: transaction.blockTime }
+          };
+      }
+    }
+    if (signatures.length < 50)
+      break;
+    before = signatures.at(-1).signature;
+  }
+  throw new Error("Settlement transaction was not found in recent history");
+}
+
+// src/account/discovery.ts
 function status(state) {
   return Object.keys(state.status)[0] ?? "unknown";
 }
@@ -45012,6 +45130,28 @@ class FundingDiscovery {
     this.connection = connection;
     this.owner = owner;
   }
+  async transaction(item) {
+    return this.detail(item);
+  }
+  async detail(item) {
+    const name2 = item.kind === "deposit" ? "depositReceipt" : item.kind === "withdrawal" ? "withdrawalReceipt" : item.kind === "allocation" || item.kind === "release" ? "marginTransfer" : "orderRecord";
+    const info = await this.connection.getAccountInfo(item.id, "confirmed");
+    if (!info?.owner.equals(this.program.programId))
+      throw new Error("Receipt is unavailable");
+    const state = this.program.coder.accounts.decode(name2, info.data);
+    const canonical = this.project(name2, item.id, state, true);
+    if (!canonical || canonical.kind !== item.kind || canonical.nonce !== item.nonce)
+      throw new Error("Receipt does not match this wallet and operation");
+    if ((canonical.kind === "trade" || canonical.kind === "risk") && canonical.status === "filled")
+      return settlementTransaction(this.connection, this.program, item.id, {
+        orderId: item.id
+      });
+    const transaction = await receiptTransaction(this.connection, this.program, item.id);
+    return {
+      ...transaction,
+      ...state.amount === undefined ? {} : { amount: BigInt(state.amount.toString()) }
+    };
+  }
   async unpairedAllocations(options = {}) {
     const limit = options.limit ?? 20;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
@@ -45216,7 +45356,7 @@ class FundingDiscovery {
 }
 
 // src/account/funding.ts
-import * as anchor5 from "@anchor-lang/core";
+import * as anchor6 from "@anchor-lang/core";
 import {
   balanceAddress,
   depositAddress as depositAddress2,
@@ -45246,7 +45386,7 @@ async function confirmReceipt(id, status2, advance, options = {}) {
 }
 
 // src/trade/input.ts
-import * as anchor4 from "@anchor-lang/core";
+import * as anchor5 from "@anchor-lang/core";
 function encodeSide(direction) {
   if (direction !== "long" && direction !== "short")
     throw new RangeError("Direction must be long or short");
@@ -45256,12 +45396,12 @@ function u64(value2, name2) {
   if (typeof value2 !== "bigint" || value2 < 0n || value2 > (1n << 64n) - 1n) {
     throw new RangeError(`${name2} must be an unsigned 64-bit bigint`);
   }
-  return new anchor4.BN(value2.toString());
+  return new anchor5.BN(value2.toString());
 }
 
 // src/account/funding.ts
 function offset() {
-  return new anchor5.BN(randomBytes3(8), "le");
+  return new anchor6.BN(randomBytes3(8), "le");
 }
 function status2(value2) {
   return Object.keys(value2)[0] ?? "unknown";
@@ -45770,6 +45910,42 @@ import {
   SOL_USD_MARKET_ID as SOL_USD_MARKET_ID2
 } from "@depthhq/bindings";
 import { PublicKey as PublicKey6 } from "@solana/web3.js";
+
+// src/position/pnl.ts
+var scale = 100000000000n;
+function positionPnl(position, priceE8, fundingIndex, fill) {
+  if (position.status !== "ready" || position.position === undefined || position.position === 0n || position.entryPriceE8 === undefined || position.fundingCheckpoint === undefined || position.collateral !== undefined && position.collateral < 0n || priceE8 <= 0n)
+    throw new Error("A ready open position and a positive price are required");
+  const size = position.position < 0n ? -position.position : position.position;
+  const sign = position.position > 0n ? 1n : -1n;
+  let closing = size;
+  let fee = 0n;
+  let state = "open";
+  if (fill) {
+    if (fill.status !== "ready" || fill.side !== -sign || fill.size === undefined || fill.size <= 0n || fill.executionPriceE8 !== priceE8 || fill.fee === undefined || fill.fee < 0n)
+      throw new Error("A ready opposite-side execution is required");
+    closing = fill.size < size ? fill.size : size;
+    fee = fill.fee;
+    state = fill.size === size ? "closed" : fill.size < size ? "reduced" : "reversed";
+  }
+  const gross = sign * closing * (priceE8 - position.entryPriceE8) / scale;
+  const funding = position.position * (fundingIndex - position.fundingCheckpoint) / scale;
+  const net = gross - funding - fee;
+  return {
+    side: sign > 0n ? "long" : "short",
+    state,
+    entryPriceE8: position.entryPriceE8,
+    priceE8,
+    collateral: position.collateral ?? null,
+    gross,
+    funding,
+    fee,
+    net,
+    returnBps: position.collateral !== undefined && position.collateral > 0n ? net * 10000n / position.collateral : null
+  };
+}
+
+// src/operation/operation.ts
 function enumName(value2) {
   return Object.keys(value2)[0] ?? "unknown";
 }
@@ -45780,15 +45956,40 @@ class DepthOperation {
   program;
   connection;
   requestFillView;
+  priorPosition;
+  historicalPnl;
   viewPromise;
   view;
   fill;
-  constructor(id, signature, program, connection, requestFillView) {
+  settlement;
+  constructor(id, signature, program, connection, requestFillView, priorPosition, historicalPnl) {
     this.id = id;
     this.signature = signature;
     this.program = program;
     this.connection = connection;
     this.requestFillView = requestFillView;
+    this.priorPosition = priorPosition;
+    this.historicalPnl = historicalPnl;
+  }
+  async transaction() {
+    if (this.settlement)
+      return this.settlement;
+    const snapshot = await this.status();
+    if (snapshot.status !== "finalized" || snapshot.outcome !== "filled")
+      throw new Error("Confirm the trade before reading its settlement transaction");
+    this.settlement = await settlementTransaction(this.connection, this.program, this.id, { orderId: this.id });
+    return this.settlement;
+  }
+  async pnl() {
+    if (!this.priorPosition && this.historicalPnl)
+      return this.historicalPnl();
+    const { order } = await this.readOrder();
+    if (!this.priorPosition || this.priorPosition.version !== BigInt(order.traderVersion.toString()))
+      throw new Error("The private position before this execution is unavailable");
+    const fill = await this.privateResult();
+    if (fill.executionPriceE8 === undefined)
+      throw new Error("Execution price is unavailable");
+    return positionPnl(this.priorPosition, fill.executionPriceE8, BigInt(order.fundingIndex.toString()), fill);
   }
   async readOrder() {
     const response = await this.connection.getAccountInfoAndContext(this.id, "confirmed");
@@ -46066,6 +46267,240 @@ class DepthRecovery {
   }
 }
 
+// src/history/history.ts
+init_buffer();
+import * as anchor7 from "@anchor-lang/core";
+import {
+  accountOffsets as accountOffsets2,
+  marketAddress as marketAddress6,
+  transferAddress as transferAddress3
+} from "@depthhq/bindings";
+import { PublicKey as PublicKey8 } from "@solana/web3.js";
+
+// src/history/replay.ts
+function replayFill(state, fill, fundingIndex, maker = false) {
+  if (fill.status !== "ready" || fill.side !== 1n && fill.side !== -1n || fill.size === undefined || fill.size <= 0n || fill.executionPriceE8 === undefined || fill.executionPriceE8 <= 0n || fill.fee === undefined || fill.fee < 0n || maker && (fill.makerRebate === undefined || fill.makerRebate < 0n))
+    throw new Error("A complete private execution is required for history");
+  const side = maker ? -fill.side : fill.side;
+  const delta = side * fill.size;
+  const old = state.position;
+  const next = old + delta;
+  const absolute = (value2) => value2 < 0n ? -value2 : value2;
+  const closing = old !== 0n && old > 0n !== delta > 0n;
+  const size = closing ? fill.size < absolute(old) ? fill.size : absolute(old) : 0n;
+  const gross = (old > 0n ? 1n : -1n) * size * (fill.executionPriceE8 - state.entryPriceE8) / 100000000000n;
+  const funding = old * (fundingIndex - state.fundingCheckpoint) / 100000000000n;
+  const fee = maker ? -fill.makerRebate : fill.fee;
+  const cash = gross - funding - fee;
+  const collateral = state.collateral === undefined ? undefined : state.collateral + cash;
+  if (collateral !== undefined && collateral < 0n)
+    throw new Error("Execution history does not conserve collateral");
+  const entryPriceE8 = next === 0n ? 0n : old === 0n || old > 0n !== next > 0n ? fill.executionPriceE8 : closing ? state.entryPriceE8 : (absolute(old) * state.entryPriceE8 + fill.size * fill.executionPriceE8) / absolute(next);
+  let pnl;
+  if (closing) {
+    const position = {
+      id: "history",
+      status: "ready",
+      slot: fill.slot,
+      version: 0n,
+      ...state
+    };
+    pnl = positionPnl(position, fill.executionPriceE8, fundingIndex, {
+      ...fill,
+      side,
+      fee: maker ? 0n : fee
+    });
+    if (maker) {
+      pnl = {
+        ...pnl,
+        fee,
+        net: cash,
+        returnBps: state.collateral !== undefined && state.collateral > 0n ? cash * 10000n / state.collateral : null
+      };
+    }
+  }
+  return {
+    state: {
+      position: next,
+      entryPriceE8,
+      fundingCheckpoint: fundingIndex,
+      collateral
+    },
+    pnl
+  };
+}
+function replayMargin(state, amount, toMarket) {
+  if (amount < 0n)
+    throw new Error("Margin history contains a negative amount");
+  const collateral = state.collateral === undefined ? undefined : state.collateral + (toMarket ? amount : -amount);
+  if (collateral !== undefined && collateral < 0n)
+    throw new Error("Margin history does not conserve collateral");
+  return { ...state, collateral };
+}
+
+// src/history/history.ts
+class ExecutionHistory {
+  program;
+  connection;
+  owner;
+  requestView;
+  views = new Map;
+  fills = new Map;
+  transactions = new Map;
+  constructor(program, connection, owner, requestView) {
+    this.program = program;
+    this.connection = connection;
+    this.owner = owner;
+    this.requestView = requestView;
+  }
+  orderAddress(trader, nonce) {
+    return PublicKey8.findProgramAddressSync([
+      Buffer2.from("order"),
+      marketAddress6(this.program.programId).toBuffer(),
+      trader.toBuffer(),
+      nonce.toArrayLike(Buffer2, "le", 8)
+    ], this.program.programId)[0];
+  }
+  async fill(id) {
+    const key = id.toBase58();
+    if (this.fills.has(key) && !this.views.has(key))
+      return this.fills.get(key);
+    if (!this.views.has(key))
+      this.views.set(key, this.requestView(id));
+    let view;
+    try {
+      view = await this.views.get(key);
+    } catch (error) {
+      this.views.delete(key);
+      throw error;
+    }
+    const result = this.fills.get(key) ?? await view.wait({ timeoutMs: 180000 });
+    if (result.status === "stale") {
+      await view.close();
+      this.views.delete(key);
+      throw new Error("Historical private execution changed; retry with the same wallet");
+    }
+    if (result.status !== "ready")
+      throw new Error("Historical private execution is still pending; retry with the same wallet");
+    this.fills.set(key, result);
+    try {
+      await view.close();
+    } catch (error) {
+      if (await this.connection.getAccountInfo(view.id, "confirmed"))
+        throw error;
+    }
+    this.views.delete(key);
+    return result;
+  }
+  async execution(nonce) {
+    if (nonce < 0n || nonce > (1n << 64n) - 1n)
+      throw new RangeError("Trade nonce is invalid");
+    const target = this.orderAddress(this.owner, new anchor7.BN(nonce.toString()));
+    const market = marketAddress6(this.program.programId);
+    const scans = await Promise.all([
+      this.scan("orderRecord", accountOffsets2.OrderRecord.trader),
+      this.scan("orderRecord", accountOffsets2.OrderRecord.maker),
+      this.scan("marginTransfer", accountOffsets2.MarginTransfer.owner)
+    ]);
+    const orders = new Map;
+    for (const account of [...scans[0], ...scans[1]]) {
+      const state2 = this.program.coder.accounts.decode("orderRecord", account.account.data);
+      if (!state2.market.equals(market) || !state2.trader.equals(this.owner) && !state2.maker.equals(this.owner) || !account.pubkey.equals(this.orderAddress(state2.trader, state2.nonce)))
+        throw new Error("Historical order identity is invalid");
+      if ("filled" in state2.status)
+        orders.set(account.pubkey.toBase58(), { id: account.pubkey, state: state2 });
+    }
+    const selected = orders.get(target.toBase58());
+    if (!selected || !("trade" in selected.state.kind) || !selected.state.trader.equals(this.owner))
+      throw new Error("Historical trade is not a filled execution by this wallet");
+    const targetTx = await this.settlement(target);
+    const events2 = [];
+    for (const order of orders.values()) {
+      const version = order.state.trader.equals(this.owner) ? order.state.traderVersion : order.state.makerVersion;
+      if (version && selected.state.traderVersion && version.gt(selected.state.traderVersion))
+        continue;
+      const transaction = order.id.equals(target) ? targetTx : await this.settlement(order.id);
+      if (transaction.slot <= targetTx.slot)
+        events2.push({ id: order.id, order: order.state, transaction });
+    }
+    for (const account of scans[2]) {
+      const state2 = this.program.coder.accounts.decode("marginTransfer", account.account.data);
+      if (!state2.owner.equals(this.owner) || !state2.market.equals(market) || !account.pubkey.equals(transferAddress3(this.owner, BigInt(state2.nonce.toString()), this.program.programId)))
+        throw new Error("Historical margin identity is invalid");
+      if (!("settled" in state2.status) && (state2.toMarket || !("escrow" in state2.status) && !("crediting" in state2.status)) || state2.amount.isZero())
+        continue;
+      const key = account.pubkey.toBase58();
+      const transaction = this.transactions.get(key) ?? await receiptTransaction(this.connection, this.program, account.pubkey, state2.toMarket ? ["creditMarketCallback"] : ["debitMarketV2Callback", "debitMarketCallback"]);
+      this.transactions.set(key, transaction);
+      if (transaction.slot <= targetTx.slot)
+        events2.push({ id: account.pubkey, transfer: state2, transaction });
+    }
+    const indexes = new Map;
+    const counts = new Map;
+    for (const event of events2)
+      counts.set(event.transaction.slot, (counts.get(event.transaction.slot) ?? 0) + 1);
+    for (const [slot, count] of counts)
+      if (count > 1) {
+        const block = await this.connection.getBlockSignatures(slot, "confirmed");
+        if (!block)
+          throw new Error("Block ordering is unavailable; use an archival RPC for execution history");
+        indexes.set(slot, new Map(block.signatures.map((signature, index) => [signature, index])));
+        if (events2.some((event) => event.transaction.slot === slot && !indexes.get(slot).has(event.transaction.signature)))
+          throw new Error("Historical transaction is missing from its canonical block");
+      }
+    events2.sort((a, b) => a.transaction.slot - b.transaction.slot || (indexes.get(a.transaction.slot)?.get(a.transaction.signature) ?? 0) - (indexes.get(b.transaction.slot)?.get(b.transaction.signature) ?? 0));
+    let state = {
+      position: 0n,
+      entryPriceE8: 0n,
+      fundingCheckpoint: 0n,
+      collateral: 0n
+    };
+    for (const event of events2) {
+      if ("transfer" in event) {
+        state = replayMargin(state, BigInt(event.transfer.amount.toString()), event.transfer.toMarket);
+        continue;
+      }
+      if ("liquidation" in event.order.kind) {
+        if (!event.order.trader.equals(this.owner))
+          throw new Error("Historical backstop exposure requires an authorized historical position view");
+        state = {
+          position: 0n,
+          entryPriceE8: 0n,
+          fundingCheckpoint: BigInt(event.order.fundingIndex.toString())
+        };
+        continue;
+      }
+      const fill = await this.fill(event.id);
+      const result = replayFill(state, fill, BigInt(event.order.fundingIndex.toString()), event.order.maker.equals(this.owner));
+      state = result.state;
+      if (event.id.equals(target))
+        return { id: target, fill, pnl: result.pnl, transaction: targetTx };
+    }
+    throw new Error("Historical execution could not be reconciled");
+  }
+  async settlement(id) {
+    const key = id.toBase58();
+    const cached = this.transactions.get(key);
+    if (cached)
+      return { ...cached, orderId: id };
+    const result = await settlementTransaction(this.connection, this.program, id, { orderId: id });
+    this.transactions.set(key, result);
+    return result;
+  }
+  async scan(name2, offset2) {
+    const accounts2 = await this.connection.getProgramAccounts(this.program.programId, {
+      commitment: "confirmed",
+      filters: [
+        { memcmp: this.program.coder.accounts.memcmp(name2) },
+        { memcmp: { offset: offset2, bytes: this.owner.toBase58() } }
+      ]
+    });
+    if (accounts2.some((item) => !item.account.owner.equals(this.program.programId)))
+      throw new Error("History account owner is invalid");
+    return accounts2;
+  }
+}
+
 // src/trade/amount.ts
 function resolveAmount(selector, available, name2) {
   u64(available, "available");
@@ -46119,7 +46554,7 @@ function tradeLimit(input, direction, oraclePriceE8) {
 }
 
 // src/trade/flow.ts
-import { transferAddress as transferAddress3 } from "@depthhq/bindings";
+import { transferAddress as transferAddress4 } from "@depthhq/bindings";
 
 class TradeFlow {
   client;
@@ -46133,7 +46568,7 @@ class TradeFlow {
       throw new RangeError("clientNonce must be an unsigned 64-bit bigint");
     }
     this.id = client.trade.operation(nonce).id;
-    this.allocationId = transferAddress3(client.options.wallet.publicKey, nonce, client.program.programId);
+    this.allocationId = transferAddress4(client.options.wallet.publicKey, nonce, client.program.programId);
   }
   async status() {
     const [order, allocation] = await this.client.options.connection.getMultipleAccountsInfo([this.id, this.allocationId], "confirmed");
@@ -46329,10 +46764,10 @@ class DepthView {
 
 // src/client/client.ts
 function pda(seeds, programId = DEPTH_PROGRAM_ID7) {
-  return PublicKey8.findProgramAddressSync(seeds, programId)[0];
+  return PublicKey9.findProgramAddressSync(seeds, programId)[0];
 }
 function nonce() {
-  return new anchor6.BN(randomBytes3(8), "le");
+  return new anchor8.BN(randomBytes3(8), "le");
 }
 function enumName2(value2) {
   return Object.keys(value2)[0] ?? "unknown";
@@ -46343,7 +46778,7 @@ class DepthClient {
   program;
   provider;
   position;
-  marketAddress = marketAddress6();
+  marketAddress = marketAddress7();
   protocolAddress = protocolAddress4();
   mxeAddress = getMXEAccAddress(DEPTH_PROGRAM_ID7);
   get catalog() {
@@ -46358,17 +46793,21 @@ class DepthClient {
   get recovery() {
     return new DepthRecovery(this.program, this.options.connection, this.options.wallet.publicKey);
   }
+  historyClient;
+  get history() {
+    return this.historyClient ??= new ExecutionHistory(this.program, this.options.connection, this.options.wallet.publicKey, (id) => this.requestFillView(id));
+  }
   constructor(options) {
     this.options = options;
     this.provider = new DepthProvider(options.connection, options.wallet, {
       commitment: "confirmed",
       preflightCommitment: "confirmed"
     });
-    this.program = new anchor6.Program(DEPTH_IDL3, this.provider);
+    this.program = new anchor8.Program(DEPTH_IDL3, this.provider);
     this.position = this.positionActions();
   }
   static async create(options) {
-    const appId = typeof options.appId === "string" ? new PublicKey8(options.appId) : options.appId;
+    const appId = typeof options.appId === "string" ? new PublicKey9(options.appId) : options.appId;
     const resolved = {
       ...options,
       ...await resolveConnection(options),
@@ -46472,7 +46911,7 @@ class DepthClient {
   }
   async requestFillView(order) {
     const record = await this.read("OrderRecord", order);
-    if (!record.trader.equals(this.options.wallet.publicKey) || !record.market.equals(this.marketAddress) || enumName2(record.kind) !== "trade" || enumName2(record.status) !== "filled")
+    if (!record.trader.equals(this.options.wallet.publicKey) && !record.maker?.equals(this.options.wallet.publicKey) || !record.market.equals(this.marketAddress) || enumName2(record.kind) !== "trade" || enumName2(record.status) !== "filled")
       throw new Error("Filled trade does not belong to this wallet and market");
     const viewNonce = nonce();
     const view = pda([
@@ -46586,7 +47025,7 @@ class DepthClient {
     return this.funding.release(amount, clientNonce ?? BigInt(nonce().toString()));
   }
   async depositRequest(sourceOrAmount, amount, clientNonce) {
-    if (sourceOrAmount instanceof PublicKey8) {
+    if (sourceOrAmount instanceof PublicKey9) {
       if (amount === undefined || clientNonce === undefined)
         throw new RangeError("Source deposits require amount and client nonce");
       return this.funding.deposit(sourceOrAmount, amount, clientNonce);
@@ -46597,7 +47036,7 @@ class DepthClient {
     return this.funding.deposit(source, sourceOrAmount, amount ?? BigInt(nonce().toString()));
   }
   async withdrawRequest(destinationOrAmount, amount, clientNonce) {
-    if (destinationOrAmount instanceof PublicKey8) {
+    if (destinationOrAmount instanceof PublicKey9) {
       if (amount === undefined || clientNonce === undefined)
         throw new RangeError("Destination withdrawals require amount and client nonce");
       return this.funding.withdraw(destinationOrAmount, amount, clientNonce);
@@ -46612,6 +47051,8 @@ class DepthClient {
   }
   accountActions() {
     const actions = {
+      detail: (item) => new FundingDiscovery(this.program, this.options.connection, this.options.wallet.publicKey).detail(item),
+      transaction: (item) => new FundingDiscovery(this.program, this.options.connection, this.options.wallet.publicKey).transaction(item),
       history: (options) => new FundingDiscovery(this.program, this.options.connection, this.options.wallet.publicKey).history(options),
       pending: (options) => new FundingDiscovery(this.program, this.options.connection, this.options.wallet.publicKey).pending(options),
       cancelOpen: () => this.funding.cancelOpenBalance(),
@@ -46646,6 +47087,23 @@ class DepthClient {
       addMargin: (amount, clientNonce) => typeof amount === "bigint" && clientNonce !== undefined ? this.funding.allocate(amount, clientNonce) : this.allocateRequest({ marketId: SOL_USD_MARKET_ID3, amount }, clientNonce),
       removeMargin: (amount, clientNonce) => typeof amount === "bigint" && clientNonce !== undefined ? this.funding.release(amount, clientNonce) : this.releaseRequest({ marketId: SOL_USD_MARKET_ID3, amount }, clientNonce),
       open: async () => this.funding.openMarket(),
+      transaction: () => settlementTransaction(this.options.connection, this.program, address2, {
+        trader: this.options.wallet.publicKey,
+        market: this.marketAddress
+      }),
+      pnl: async () => {
+        const position = await this.positionActions(id).summary();
+        const [market, account] = await Promise.all([
+          this.market(),
+          this.read("MarketAccount", address2)
+        ]);
+        const age = Math.floor(Date.now() / 1000) - market.state.oracleTimestamp.toNumber();
+        if (age < 0 || age > market.state.config.maxOracleAgeSeconds)
+          throw new Error("A fresh oracle price is required to value this position");
+        if (position.version !== BigInt(account.version.toString()) || enumName2(account.status) !== "ready")
+          throw new Error("The position changed during valuation; refresh its private view");
+        return positionPnl(position, BigInt(market.state.oraclePriceE8.toString()), BigInt(market.state.fundingIndex.toString()));
+      },
       summary: async (options = {
         timeoutMs: 180000
       }) => {
@@ -46700,7 +47158,12 @@ class DepthClient {
     reduce: (input) => this.submitTrade(input, "reduce"),
     close: (input) => this.submitTrade(input, "close"),
     reverse: (input) => this.submitTrade(input, "reverse"),
-    operation: (clientNonce) => new DepthOperation(this.orderAddress(clientNonce), undefined, this.program, this.options.connection, (order) => this.requestFillView(order)),
+    operation: (clientNonce) => new DepthOperation(this.orderAddress(clientNonce), undefined, this.program, this.options.connection, (order) => this.requestFillView(order), undefined, async () => {
+      const detail = await this.history.execution(clientNonce);
+      if (!detail.pnl)
+        throw new Error("This execution does not close any exposure");
+      return detail.pnl;
+    }),
     flow: (clientNonce) => new TradeFlow(this, clientNonce),
     unpairedAllocations: (options) => new FundingDiscovery(this.program, this.options.connection, this.options.wallet.publicKey).unpairedAllocations(options)
   };
@@ -46852,7 +47315,7 @@ class DepthClient {
     }), inputNonce);
     const offset2 = nonce();
     const queue = await this.queue("match_order", offset2);
-    const signature = await this.program.methods.submitOrder(offset2, orderNonce, appId, app.feeBps, app.version, new anchor6.BN(deadline), market.state.revision, market.state.oracleTimestamp, ciphertexts, Array.from(inputKey), new anchor6.BN(inputNonce, "le")).accountsPartial({
+    const signature = await this.program.methods.submitOrder(offset2, orderNonce, appId, app.feeBps, app.version, new anchor8.BN(deadline), market.state.revision, market.state.oracleTimestamp, ciphertexts, Array.from(inputKey), new anchor8.BN(inputNonce, "le")).accountsPartial({
       ...queue,
       trader: this.options.wallet.publicKey,
       protocol: this.protocolAddress,
@@ -46873,7 +47336,7 @@ class DepthClient {
         isWritable: true
       }
     ]).rpc({ commitment: "confirmed" }).catch((error) => submissionError(order.toBase58(), error));
-    return new DepthOperation(order, signature, this.program, this.options.connection, (id) => this.requestFillView(id));
+    return new DepthOperation(order, signature, this.program, this.options.connection, (id) => this.requestFillView(id), position);
   }
   validateTrade(market, protocol, account, app, appId, intent = "increase", deadline) {
     const now = Math.floor(Date.now() / 1000);
@@ -47043,6 +47506,7 @@ export {
   verifyDeployment,
   resolveConnection,
   resolveAmount,
+  positionPnl,
   manifestBytes,
   create_depth_data,
   createDepth as create_depth,
@@ -47056,6 +47520,7 @@ export {
   MarketCatalog,
   FundingDiscovery,
   FundingClient,
+  ExecutionHistory,
   DepthView,
   DepthRecovery,
   DepthProvider,

package/dist/operation/operation.d.ts

@@ -1,17 +1,24 @@
 import * as anchor from "@anchor-lang/core";
 import type { OperationSnapshot } from "@depthhq/schema";
 import { Connection, PublicKey } from "@solana/web3.js";
-import type { DepthView, FillSnapshot } from "../view/view.js";
+import type { DepthView, FillSnapshot, PositionSnapshot } from "../view/view.js";
+import { type PositionPnl } from "../position/pnl.js";
+import { type SettlementTransaction } from "../chain/settlement.js";
 export declare class DepthOperation {
     readonly id: PublicKey;
     readonly signature: string | undefined;
     private readonly program;
     private readonly connection;
     private readonly requestFillView?;
+    private readonly priorPosition?;
+    private readonly historicalPnl?;
     private viewPromise?;
     private view?;
     private fill?;
-    constructor(id: PublicKey, signature: string | undefined, program: anchor.Program, connection: Connection, requestFillView?: ((order: PublicKey) => Promise<DepthView>) | undefined);
+    private settlement?;
+    constructor(id: PublicKey, signature: string | undefined, program: anchor.Program, connection: Connection, requestFillView?: ((order: PublicKey) => Promise<DepthView>) | undefined, priorPosition?: PositionSnapshot | undefined, historicalPnl?: (() => Promise<PositionPnl>) | undefined);
+    transaction(): Promise<SettlementTransaction>;
+    pnl(): Promise<PositionPnl>;
     private readOrder;
     status(): Promise<OperationSnapshot>;
     cancel(): Promise<OperationSnapshot>;

package/dist/position/pnl.d.ts

@@ -0,0 +1,14 @@
+import type { FillSnapshot, PositionSnapshot } from "../view/view.js";
+export type PositionPnl = {
+    side: "long" | "short";
+    state: "open" | "closed" | "reduced" | "reversed";
+    entryPriceE8: bigint;
+    priceE8: bigint;
+    collateral: bigint | null;
+    gross: bigint;
+    funding: bigint;
+    fee: bigint;
+    net: bigint;
+    returnBps: bigint | null;
+};
+export declare function positionPnl(position: PositionSnapshot, priceE8: bigint, fundingIndex: bigint, fill?: FillSnapshot): PositionPnl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depthhq/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,13 +39,13 @@
   "dependencies": {
     "@anchor-lang/core": "1.0.2",
     "@arcium-hq/client": "0.13.2",
-    "@depthhq/bindings": "0.1.0",
-    "@depthhq/schema": "0.1.0",
     "@noble/ciphers": "1.3.0",
     "@noble/ed25519": "1.7.5",
     "@noble/hashes": "1.8.0",
     "@solana/web3.js": "1.99.0",
-    "buffer": "6.0.3"
+    "buffer": "6.0.3",
+    "@depthhq/schema": "0.1.1",
+    "@depthhq/bindings": "0.1.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs sdk",