@ostium/builder-sdk 0.1.0 → 0.2.0

package/dist/cli.js

@@ -243,11 +243,20 @@ function getNetworkConfig(isTestnet = false) {
 // src/config.ts
 var DEFAULT_PIMLICO_URL = "https://builder.ostium.io/v1/pimlico/sponsor?chainId=42161";
 var DEFAULT_PIMLICO_URL_TESTNET = "https://builder.ostium.io/v1/pimlico/sponsor?chainId=421614";
-function isGasless(config) {
-  return !!config.pimlicoUrl;
+function hasPrivateKey(config) {
+  return typeof config.privateKey === "string" && config.privateKey.length > 0;
 }
-function isDelegated(config) {
-  return !!config.traderAddress;
+function resolveMode(config) {
+  if (config.mode) return config.mode;
+  if (config.privateKey) {
+    if (config.pimlicoUrl) return config.traderAddress ? "delegated-gasless" : "self-gasless";
+    return config.traderAddress ? "delegated-self" : "self-self";
+  }
+  if (config.safeAddress && config.delegateAddress && config.traderAddress) return "delegated-gasless";
+  if (config.safeAddress && config.traderAddress) return "self-gasless";
+  if (config.delegateAddress && config.traderAddress) return "delegated-self";
+  if (config.traderAddress) return "self-self";
+  throw new Error("Unable to infer client mode from config");
 }
 
 // src/errors.ts
@@ -2648,8 +2657,8 @@ var DelegatedSignerStrategy = class {
 };
 
 // src/signer/index.ts
-function createSigner(config, traderAddress, selfGasless = false) {
-  if (isDelegated(config) || selfGasless) {
+function createSigner(mode, traderAddress) {
+  if (mode !== "self-self") {
     return new DelegatedSignerStrategy(traderAddress);
   }
   return new SelfSignerStrategy(traderAddress);
@@ -2673,6 +2682,12 @@ var SelfSubmissionStrategy = class {
   effectiveSender;
   send;
   constructor(config, testnet) {
+    if (!config.privateKey) {
+      throw new OstiumError(
+        "privateKey is required for self-submission mode",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
     if (!config.rpcUrl) {
       throw new OstiumError(
         "rpcUrl is required for self-submission mode",
@@ -2738,6 +2753,12 @@ var GaslessSubmissionStrategy = class _GaslessSubmissionStrategy {
     this.effectiveSender = safeAccount.address;
   }
   static async create(config, testnet) {
+    if (!config.privateKey) {
+      throw new OstiumError(
+        "privateKey is required for gasless submission mode",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
     if (!config.pimlicoUrl) {
       throw new OstiumError(
         "pimlicoUrl is required for gasless mode",
@@ -2806,8 +2827,8 @@ var GaslessSubmissionStrategy = class _GaslessSubmissionStrategy {
 };
 
 // src/submitter/index.ts
-async function createSubmitter(config, testnet) {
-  if (isGasless(config)) {
+async function createSubmitter(config, testnet, mode) {
+  if (mode === "self-gasless" || mode === "delegated-gasless") {
     return GaslessSubmissionStrategy.create(config, testnet);
   }
   if (!config.rpcUrl) {
@@ -3199,10 +3220,11 @@ async function fetchLivePrices(builderApiUrl) {
   }
   return result;
 }
-function rawTickToPublic(item) {
+function rawTickToPublic(item, pairId) {
   const from = normalizePairName(item.from);
   const to = normalizePairName(item.to);
   return {
+    pairId,
     feedId: item.feed_id,
     pair: `${from}-${to}`,
     from,
@@ -3249,9 +3271,12 @@ var OstiumPriceStream = class _OstiumPriceStream {
   snapshotHandlers = /* @__PURE__ */ new Set();
   /** pairId (string) → raw "FROM-TO" name for the WS API. */
   pairRawNameCache;
-  constructor(ws, pairRawNameCache, initialSubscribeRawPairs) {
+  /** raw "FROM-TO" name → pairId (string) for mapping incoming ticks back to SDK ids. */
+  rawNamePairIdCache;
+  constructor(ws, pairRawNameCache, rawNamePairIdCache, initialSubscribeRawPairs) {
     this.ws = ws;
     this.pairRawNameCache = pairRawNameCache;
+    this.rawNamePairIdCache = rawNamePairIdCache;
     if (initialSubscribeRawPairs?.length) {
       ws.once("open", () => {
         ws.send(JSON.stringify({ type: "subscribe", pairs: initialSubscribeRawPairs }));
@@ -3265,10 +3290,13 @@ var OstiumPriceStream = class _OstiumPriceStream {
         return;
       }
       if (msg.type === "snapshot" && Array.isArray(msg.data)) {
-        const ticks = msg.data.map(rawTickToPublic);
+        const ticks = msg.data.map(
+          (item) => rawTickToPublic(item, this.rawNamePairIdCache.get(`${item.from}-${item.to}`))
+        );
         for (const h of this.snapshotHandlers) h(ticks);
       } else if (msg.type === "tick" && msg.data) {
-        const tick = rawTickToPublic(msg.data);
+        const item = msg.data;
+        const tick = rawTickToPublic(item, this.rawNamePairIdCache.get(`${item.from}-${item.to}`));
         for (const h of this.tickHandlers) h(tick);
       }
     });
@@ -3294,7 +3322,11 @@ var OstiumPriceStream = class _OstiumPriceStream {
     const ws = new WS(url, {
       headers: { "User-Agent": "ostium-sdk", "Accept": "*/*" }
     });
-    return new _OstiumPriceStream(ws, pairRawNameCache, initial);
+    const rawNamePairIdCache = /* @__PURE__ */ new Map();
+    for (const [pairId, rawName] of pairRawNameCache.entries()) {
+      rawNamePairIdCache.set(rawName, pairId);
+    }
+    return new _OstiumPriceStream(ws, pairRawNameCache, rawNamePairIdCache, initial);
   }
   /**
    * Register a callback that fires on every incoming price tick.
@@ -3370,6 +3402,37 @@ var OstiumPriceStream = class _OstiumPriceStream {
   }
 };
 
+// src/data/internal/aggregations.ts
+function aggregateMarginSummary(pairPositions) {
+  let accountValue = 0;
+  let totalCollateralUsed = 0;
+  let totalNtlPos = 0;
+  let totalRawPnlUsd = 0;
+  let totalCumRollover = 0;
+  let totalWithdrawable = 0;
+  for (const { position } of pairPositions) {
+    const collateral = parseFloat(position.collateralUsed) || 0;
+    const ntl = parseFloat(position.ntl) || 0;
+    const pnl = parseFloat(position.unrealizedPnl) || 0;
+    const rollover = parseFloat(position.cumRollover) || 0;
+    const withdrawable = parseFloat(position.maxWithdrawable) || 0;
+    accountValue += collateral + pnl;
+    totalCollateralUsed += collateral;
+    totalNtlPos += ntl;
+    totalRawPnlUsd += pnl;
+    totalCumRollover += rollover;
+    totalWithdrawable += withdrawable;
+  }
+  return {
+    accountValue: accountValue.toString(),
+    totalCollateralUsed: totalCollateralUsed.toString(),
+    totalNtlPos: totalNtlPos.toString(),
+    totalRawPnlUsd: totalRawPnlUsd.toString(),
+    totalCumRollover: totalCumRollover.toString(),
+    totalWithdrawable: totalWithdrawable.toString()
+  };
+}
+
 // src/data/internal/formatters.ts
 var MIN_NOTIONAL = "5.0";
 var MIN_NOTIONAL_NUM = 5;
@@ -3471,14 +3534,14 @@ function formatPosition(raw, price, pnl, maxLeverage) {
       returnOnEquity: roe.toString(),
       liquidationPx: pnl.liquidationPrice.toString(),
       collateralUsed: collateral.toString(),
-      cumRollover: pnl.rollover.toString(),
+      cumRollover: (pnl.rollover * -1).toString(),
       ...raw.takeProfitPrice && raw.takeProfitPrice !== "0" ? { tpPx: formatTokens(raw.takeProfitPrice).toString() } : {},
       ...raw.stopLossPrice && raw.stopLossPrice !== "0" ? { slPx: formatTokens(raw.stopLossPrice).toString() } : {},
       openTimestamp: parseInt(raw.timestamp || "0") * 1e3,
       isDayTrade: raw.isDayTrade ?? false,
-      maxLeverage: maxLeverage.toString()
-    },
-    maxWithdrawable: maxWithdrawForPosition(collateral, leverage, maxLeverage).toString()
+      maxLeverage: maxLeverage.toString(),
+      maxWithdrawable: maxWithdrawForPosition(collateral, leverage, maxLeverage).toString()
+    }
   };
 }
 function formatFill(raw) {
@@ -3555,6 +3618,131 @@ function formatOpenOrder(raw) {
     timestamp: parseInt(raw.initiatedAt || "0") * 1e3
   };
 }
+
+// src/data/internal/position-updates.ts
+function cloneResponse(response) {
+  return {
+    pairPositions: response.pairPositions.map((pairPos) => ({
+      position: { ...pairPos.position }
+    })),
+    marginSummary: { ...response.marginSummary },
+    time: response.time
+  };
+}
+function applyTickToPosition(position, tick) {
+  const size = parseFloat(position.szi) || 0;
+  const entry = parseFloat(position.entryPx) || 0;
+  const collateral = parseFloat(position.collateralUsed) || 0;
+  const maxLeverage = parseFloat(position.maxLeverage) || 0;
+  const rollover = parseFloat(position.cumRollover) || 0;
+  const isLong = position.side === "B";
+  const ntl = size * tick.mid;
+  const rawPnl = isLong ? (tick.mid - entry) * size : (entry - tick.mid) * size;
+  const netPnl = rawPnl + rollover;
+  const roe = collateral > 0 ? netPnl / collateral : 0;
+  const currentLeverage = collateral > 0 ? ntl / collateral : 0;
+  const maxWithdrawable = maxWithdrawForPosition(collateral, currentLeverage, maxLeverage);
+  return {
+    ...position,
+    ntl: ntl.toString(),
+    unrealizedPnl: netPnl.toString(),
+    returnOnEquity: roe.toString(),
+    maxWithdrawable: maxWithdrawable.toString()
+  };
+}
+function updateResponseWithTick(current, tick, timestampMs) {
+  if (!tick.pairId) return current;
+  let changed = false;
+  const pairPositions = current.pairPositions.map((pairPos) => {
+    if (String(pairPos.position.pairId) !== String(tick.pairId)) {
+      return pairPos;
+    }
+    changed = true;
+    return {
+      ...pairPos,
+      position: applyTickToPosition(pairPos.position, tick)
+    };
+  });
+  if (!changed) return current;
+  return {
+    pairPositions,
+    marginSummary: aggregateMarginSummary(pairPositions),
+    time: timestampMs
+  };
+}
+var OstiumPositionUpdatesStream = class {
+  priceStream;
+  updateHandlers = /* @__PURE__ */ new Set();
+  current;
+  trackedPairIds;
+  constructor(initial, trackedPairIds, priceStream) {
+    this.current = cloneResponse(initial);
+    this.priceStream = priceStream;
+    this.trackedPairIds = new Set(trackedPairIds);
+    if (!priceStream) return;
+    priceStream.onSnapshot((ticks) => {
+      this.ingestSnapshot(ticks);
+    });
+    priceStream.onTick((tick) => {
+      this.ingestTick(tick);
+    });
+  }
+  onUpdate(handler) {
+    this.updateHandlers.add(handler);
+    return () => {
+      this.updateHandlers.delete(handler);
+    };
+  }
+  onOpen(handler) {
+    this.priceStream?.onOpen(handler);
+    return this;
+  }
+  onError(handler) {
+    this.priceStream?.onError(handler);
+    return this;
+  }
+  onClose(handler) {
+    this.priceStream?.onClose(handler);
+    return this;
+  }
+  getCurrent() {
+    return cloneResponse(this.current);
+  }
+  /**
+   * Apply a single externally sourced price tick to the tracked positions.
+   *
+   * Use this when your app already has its own websocket connection and you want
+   * the SDK to handle only the position recalculation logic.
+   */
+  ingestTick(tick) {
+    if (!tick.pairId || !this.trackedPairIds.has(String(tick.pairId))) return;
+    const next = updateResponseWithTick(this.current, tick, tick.timestampSeconds * 1e3);
+    if (next !== this.current) {
+      this.current = next;
+      this.emit(next);
+    }
+  }
+  /**
+   * Apply a batch of externally sourced ticks, such as a websocket snapshot.
+   */
+  ingestSnapshot(ticks) {
+    let next = this.current;
+    for (const tick of ticks) {
+      if (!tick.pairId || !this.trackedPairIds.has(String(tick.pairId))) continue;
+      next = updateResponseWithTick(next, tick, tick.timestampSeconds * 1e3);
+    }
+    if (next !== this.current) {
+      this.current = next;
+      this.emit(next);
+    }
+  }
+  close() {
+    this.priceStream?.close();
+  }
+  emit(positions) {
+    for (const handler of this.updateHandlers) handler(cloneResponse(positions));
+  }
+};
 var EMPTY_RESULT = { long: [], short: [] };
 var ORDERBOOK_MAX_LEVELS = 20;
 function generateLogSpacedNotionals(levels, capacity) {
@@ -3750,20 +3938,16 @@ var OstiumSubgraphClient = class _OstiumSubgraphClient {
       }),
       this.fetchLivePricesSafe()
     ]);
-    let totalWithdrawable = 0;
     const pairPositions = trades.map((trade) => {
       const price = prices[`${trade.pair.from}/${trade.pair.to}`];
       const pnl = price && blockNumber ? getTradePnL(trade, price, blockNumber) : EMPTY_PNL;
       const maxLev = trade.isDayTrade ? formatLeverage(trade.pair.overnightMaxLeverage) : pairMaxLeverage(trade.pair);
-      const pairPos = formatPosition(trade, price, pnl, maxLev);
-      totalWithdrawable += parseFloat(pairPos.maxWithdrawable);
-      return pairPos;
+      return formatPosition(trade, price, pnl, maxLev);
     });
     const marginSummary = aggregateMarginSummary(pairPositions);
     return {
       pairPositions,
       marginSummary,
-      withdrawable: totalWithdrawable.toString(),
       time: Date.now()
     };
   }
@@ -4014,6 +4198,24 @@ var OstiumSubgraphClient = class _OstiumSubgraphClient {
     });
     return OstiumPriceStream.connect(this.builderApiUrl, rawNames, cache);
   }
+  /**
+   * Stream price-driven updates for an existing `getOpenPositions()` response.
+   *
+   * The SDK subscribes only to the unique pairs present in `initial.pairPositions`,
+   * recalculates price-sensitive fields for affected positions on each tick, and
+   * emits the full updated response.
+   *
+   * Pass an existing `priceStream` to reuse a websocket connection your app has
+   * already opened. Omit it to let the SDK open and manage a dedicated
+   * connection for the tracked pair ids.
+   */
+  streamPositionUpdates(initial, priceStream) {
+    const pairIds = [...new Set(initial.pairPositions.map(({ position }) => String(position.pairId)))];
+    if (pairIds.length === 0) {
+      return new OstiumPositionUpdatesStream(initial, []);
+    }
+    return new OstiumPositionUpdatesStream(initial, pairIds, priceStream ?? this.streamPrices(pairIds));
+  }
   // ─────────────────────────────────────────────────────────────────────────
   // Internal — fetchers, cache, query wrapper
   // ─────────────────────────────────────────────────────────────────────────
@@ -4072,43 +4274,28 @@ var OstiumSubgraphClient = class _OstiumSubgraphClient {
     }
   }
 };
-function aggregateMarginSummary(pairPositions) {
-  let accountValue = 0;
-  let totalCollateralUsed = 0;
-  let totalNtlPos = 0;
-  let totalRawPnlUsd = 0;
-  for (const { position } of pairPositions) {
-    const collateral = parseFloat(position.collateralUsed) || 0;
-    const ntl = parseFloat(position.ntl) || 0;
-    const pnl = parseFloat(position.unrealizedPnl) || 0;
-    accountValue += collateral + pnl;
-    totalCollateralUsed += collateral;
-    totalNtlPos += ntl;
-    totalRawPnlUsd += pnl;
-  }
-  return {
-    accountValue: accountValue.toString(),
-    totalCollateralUsed: totalCollateralUsed.toString(),
-    totalNtlPos: totalNtlPos.toString(),
-    totalRawPnlUsd: totalRawPnlUsd.toString()
-  };
-}
 
 // src/client.ts
 var HEX64_RE = /^0x[0-9a-fA-F]{64}$/;
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 function validateConfig(config) {
-  if (!HEX64_RE.test(config.privateKey)) {
+  if (config.privateKey && !HEX64_RE.test(config.privateKey)) {
     throw new OstiumError(
       "privateKey must be a 64-character hex string prefixed with 0x",
       "INVALID_CONFIG" /* INVALID_CONFIG */
     );
   }
-  if (config.traderAddress && !ADDRESS_RE.test(config.traderAddress)) {
-    throw new OstiumError(
-      "traderAddress must be a valid 42-character Ethereum address (0x + 40 hex chars)",
-      "INVALID_CONFIG" /* INVALID_CONFIG */
-    );
+  for (const [label, value] of [
+    ["traderAddress", config.traderAddress],
+    ["delegateAddress", config.delegateAddress],
+    ["safeAddress", config.safeAddress]
+  ]) {
+    if (value && !ADDRESS_RE.test(value)) {
+      throw new OstiumError(
+        `${label} must be a valid 42-character Ethereum address (0x + 40 hex chars)`,
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
   }
   if (config.slippageBps !== void 0 && (config.slippageBps < 0 || config.slippageBps > 500)) {
     throw new OstiumError(
@@ -4122,10 +4309,45 @@ function validateConfig(config) {
       "INVALID_CONFIG" /* INVALID_CONFIG */
     );
   }
+  let mode;
+  try {
+    mode = resolveMode(config);
+  } catch {
+    throw new OstiumError(
+      "Could not infer client mode from config. Provide the required addresses for the selected factory.",
+      "INVALID_CONFIG" /* INVALID_CONFIG */
+    );
+  }
+  if (mode === "self-self" && !config.privateKey && !config.traderAddress) {
+    throw new OstiumError(
+      "Self + Self mode requires traderPrivateKey for submission or traderAddress for build-only usage.",
+      "INVALID_CONFIG" /* INVALID_CONFIG */
+    );
+  }
+  if (mode === "self-gasless" && !config.privateKey && (!config.traderAddress || !config.safeAddress)) {
+    throw new OstiumError(
+      "Self + Gasless build-only mode requires traderAddress and safeAddress.",
+      "INVALID_CONFIG" /* INVALID_CONFIG */
+    );
+  }
+  if (mode === "delegated-self" && (!config.traderAddress || !config.privateKey && !config.delegateAddress)) {
+    throw new OstiumError(
+      "Delegated + Self mode requires traderAddress and either delegatePrivateKey or delegateAddress.",
+      "INVALID_CONFIG" /* INVALID_CONFIG */
+    );
+  }
+  if (mode === "delegated-gasless" && (!config.traderAddress || !config.privateKey && (!config.delegateAddress || !config.safeAddress))) {
+    throw new OstiumError(
+      "Delegated + Gasless mode requires traderAddress and either delegatePrivateKey or both delegateAddress and safeAddress.",
+      "INVALID_CONFIG" /* INVALID_CONFIG */
+    );
+  }
 }
 var OstiumClient = class _OstiumClient {
   signer;
   submitter;
+  traderAddress;
+  effectiveSender;
   contracts;
   publicClient;
   defaultSlippageBps;
@@ -4140,6 +4362,8 @@ var OstiumClient = class _OstiumClient {
   constructor(internals) {
     this.signer = internals.signer;
     this.submitter = internals.submitter;
+    this.traderAddress = internals.traderAddress;
+    this.effectiveSender = internals.effectiveSender;
     this.contracts = internals.contracts;
     this.publicClient = internals.publicClient;
     this.defaultSlippageBps = internals.defaultSlippageBps;
@@ -4164,17 +4388,20 @@ var OstiumClient = class _OstiumClient {
    * });
    * await client.openTrade({ ... });
    * ```
-   */
+  */
   static async createSelfAndSelf(params) {
-    return _OstiumClient._fromConfig({
-      privateKey: params.traderPrivateKey,
-      rpcUrl: params.rpcUrl,
+    const base = {
+      mode: "self-self",
       testnet: params.testnet,
       slippageBps: params.slippageBps,
       builder: params.builder,
       subgraphUrl: params.subgraphUrl,
-      builderApiUrl: params.builderApiUrl
-    });
+      builderApiUrl: params.builderApiUrl,
+      rpcUrl: params.rpcUrl
+    };
+    return _OstiumClient._fromConfig(
+      "traderPrivateKey" in params ? { ...base, privateKey: params.traderPrivateKey } : { ...base, traderAddress: params.traderAddress }
+    );
   }
   /**
    * **Self + Gasless** — your EOA owns everything; a Safe relays trades for free.
@@ -4198,17 +4425,27 @@ var OstiumClient = class _OstiumClient {
    */
   static async createSelfAndGasless(params) {
     const defaultUrl = params.testnet ? DEFAULT_PIMLICO_URL_TESTNET : DEFAULT_PIMLICO_URL;
-    return _OstiumClient._fromConfig({
-      privateKey: params.traderPrivateKey,
-      pimlicoUrl: params.pimlicoUrl ?? defaultUrl,
+    const base = {
+      mode: "self-gasless",
       rpcUrl: params.rpcUrl,
-      sponsorshipPolicyId: params.sponsorshipPolicyId,
       testnet: params.testnet,
       slippageBps: params.slippageBps,
       builder: params.builder,
       subgraphUrl: params.subgraphUrl,
       builderApiUrl: params.builderApiUrl
-    });
+    };
+    return _OstiumClient._fromConfig(
+      "traderPrivateKey" in params ? {
+        ...base,
+        privateKey: params.traderPrivateKey,
+        pimlicoUrl: params.pimlicoUrl ?? defaultUrl,
+        sponsorshipPolicyId: params.sponsorshipPolicyId
+      } : {
+        ...base,
+        traderAddress: params.traderAddress,
+        safeAddress: params.safeAddress
+      }
+    );
   }
   /**
    * **Delegated + Self** — a delegate EOA signs and pays gas on behalf of a trader address.
@@ -4228,8 +4465,8 @@ var OstiumClient = class _OstiumClient {
    * ```
    */
   static async createDelegatedAndSelf(params) {
-    return _OstiumClient._fromConfig({
-      privateKey: params.delegatePrivateKey,
+    const base = {
+      mode: "delegated-self",
       traderAddress: params.traderAddress,
       rpcUrl: params.rpcUrl,
       testnet: params.testnet,
@@ -4237,7 +4474,10 @@ var OstiumClient = class _OstiumClient {
       builder: params.builder,
       subgraphUrl: params.subgraphUrl,
       builderApiUrl: params.builderApiUrl
-    });
+    };
+    return _OstiumClient._fromConfig(
+      "delegatePrivateKey" in params ? { ...base, privateKey: params.delegatePrivateKey } : { ...base, delegateAddress: params.delegateAddress }
+    );
   }
   /**
    * **Delegated + Gasless** — a Safe derived from the delegate key submits sponsored
@@ -4258,18 +4498,28 @@ var OstiumClient = class _OstiumClient {
    */
   static async createDelegatedAndGasless(params) {
     const defaultUrl = params.testnet ? DEFAULT_PIMLICO_URL_TESTNET : DEFAULT_PIMLICO_URL;
-    return _OstiumClient._fromConfig({
-      privateKey: params.delegatePrivateKey,
+    const base = {
+      mode: "delegated-gasless",
       traderAddress: params.traderAddress,
-      pimlicoUrl: params.pimlicoUrl ?? defaultUrl,
       rpcUrl: params.rpcUrl,
-      sponsorshipPolicyId: params.sponsorshipPolicyId,
       testnet: params.testnet,
       slippageBps: params.slippageBps,
       builder: params.builder,
       subgraphUrl: params.subgraphUrl,
       builderApiUrl: params.builderApiUrl
-    });
+    };
+    return _OstiumClient._fromConfig(
+      "delegatePrivateKey" in params ? {
+        ...base,
+        privateKey: params.delegatePrivateKey,
+        pimlicoUrl: params.pimlicoUrl ?? defaultUrl,
+        sponsorshipPolicyId: params.sponsorshipPolicyId
+      } : {
+        ...base,
+        delegateAddress: params.delegateAddress,
+        safeAddress: params.safeAddress
+      }
+    );
   }
   /**
    * **Read-only client** — no signer, no submitter, no privateKey required.
@@ -4314,6 +4564,7 @@ var OstiumClient = class _OstiumClient {
   /** Internal factory shared by all public constructors. */
   static async _fromConfig(config) {
     validateConfig(config);
+    const mode = resolveMode(config);
     const testnet = config.testnet ?? false;
     const networkConfig = getNetworkConfig(testnet);
     const chain = testnet ? arbitrumSepolia : arbitrum;
@@ -4323,18 +4574,29 @@ var OstiumClient = class _OstiumClient {
       tradingStorage: networkConfig.contracts.tradingStorage,
       usdc: networkConfig.contracts.usdc
     };
-    const selfGasless = isGasless(config) && !isDelegated(config);
-    const submitter = await createSubmitter(config, testnet);
+    const selfGasless = mode === "self-gasless";
     let traderAddress;
-    if (isDelegated(config)) {
+    if (mode === "self-self" || mode === "self-gasless") {
+      traderAddress = config.traderAddress ?? privateKeyToAccount(config.privateKey).address;
+    } else {
       traderAddress = config.traderAddress;
+    }
+    const signer = createSigner(mode, traderAddress);
+    let submitter;
+    let effectiveSender;
+    if (hasPrivateKey(config)) {
+      submitter = await createSubmitter(config, testnet, mode);
+      effectiveSender = submitter.effectiveSender;
+    } else if (mode === "self-self") {
+      effectiveSender = traderAddress;
+    } else if (mode === "delegated-self") {
+      effectiveSender = config.delegateAddress;
     } else {
-      traderAddress = privateKeyToAccount(config.privateKey).address;
+      effectiveSender = config.safeAddress;
     }
-    const signer = createSigner(config, traderAddress, selfGasless);
     const publicRpc = testnet ? "https://sepolia-rollup.arbitrum.io/rpc" : "https://arb1.arbitrum.io/rpc";
-    const rpcUrl = config.rpcUrl ?? (isGasless(config) ? publicRpc : void 0);
-    if (!isGasless(config) && !config.rpcUrl) {
+    const rpcUrl = config.rpcUrl ?? publicRpc;
+    if (hasPrivateKey(config) && mode !== "self-gasless" && mode !== "delegated-gasless" && !config.rpcUrl) {
       throw new OstiumError(
         "rpcUrl is required for self-submission mode",
         "INVALID_CONFIG" /* INVALID_CONFIG */
@@ -4342,7 +4604,7 @@ var OstiumClient = class _OstiumClient {
     }
     const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
     let eoaSubmit;
-    if (selfGasless) {
+    if (selfGasless && hasPrivateKey(config)) {
       const eoaAccount = privateKeyToAccount(config.privateKey);
       const eoaRpcUrl = config.rpcUrl ?? publicRpc;
       const eoaWalletClient = createWalletClient({ account: eoaAccount, chain, transport: http(eoaRpcUrl) });
@@ -4364,11 +4626,13 @@ var OstiumClient = class _OstiumClient {
     return new _OstiumClient({
       signer,
       submitter,
+      traderAddress,
+      effectiveSender,
       contracts,
       publicClient,
       defaultSlippageBps,
-      delegated: isDelegated(config),
-      gasless: isGasless(config),
+      delegated: mode === "delegated-self" || mode === "delegated-gasless",
+      gasless: mode === "self-gasless" || mode === "delegated-gasless",
       selfGasless,
       eoaSubmit,
       builderAddress: config.builder?.address,
@@ -4386,17 +4650,25 @@ var OstiumClient = class _OstiumClient {
    * - Self + Gasless: EOA derived from privateKey (NOT the Safe — USDC lives here).
    */
   getTraderAddress() {
-    if (!this.signer) {
+    if (!this.traderAddress) {
       throw new OstiumError(
         "No connected trader \u2014 pass `user` explicitly or use one of the createSelfAnd*/createDelegatedAnd* factories.",
         "INVALID_CONFIG" /* INVALID_CONFIG */
       );
     }
-    return this.signer.traderAddress;
+    return this.traderAddress;
   }
-  /** True when the client was created via `createReadOnly` and cannot submit transactions. */
+  /** True when the client cannot submit transactions directly. */
   isReadOnly() {
-    return !this.signer || !this.submitter;
+    return !this.submitter;
+  }
+  /** True when the client can build mode-correct unsigned transaction requests. */
+  canBuildTransactions() {
+    return !!this.signer && !!this.effectiveSender;
+  }
+  /** True when the client has the credentials needed for SDK-managed submission. */
+  canSubmitTransactions() {
+    return !!this.submitter;
   }
   /**
    * Returns the Safe smart-account address used for gasless submission.
@@ -4408,7 +4680,7 @@ var OstiumClient = class _OstiumClient {
    * - Self + Self / Delegated + Self: returns undefined.
    */
   getSmartAccountAddress() {
-    return this.gasless && this.submitter ? this.submitter.effectiveSender : void 0;
+    return this.gasless ? this.effectiveSender : void 0;
   }
   // ─────────────────────────────────────────────────────────────────────────
   // Self + Gasless setup
@@ -4432,15 +4704,10 @@ var OstiumClient = class _OstiumClient {
    * ```
    */
   async setupGaslessDelegation() {
-    if (!this.selfGasless || !this.eoaSubmit || !this.submitter) {
-      throw new OstiumError(
-        "setupGaslessDelegation() is only available in Self + Gasless mode. Create the client with pimlicoUrl but without traderAddress.",
-        "INVALID_CONFIG" /* INVALID_CONFIG */
-      );
-    }
-    const safeAddress = this.submitter.effectiveSender;
-    const encoded = encodeSetDelegate(safeAddress, this.contracts.trading);
-    return this.submitDirectFromEoa(encoded);
+    return this.submitDirectEoa(this.getSetupGaslessDelegationEncoded());
+  }
+  getSetupGaslessDelegationTx() {
+    return this.buildDirectEoaTx(this.getSetupGaslessDelegationEncoded());
   }
   // ─────────────────────────────────────────────────────────────────────────
   // USDC helpers
@@ -4502,18 +4769,14 @@ var OstiumClient = class _OstiumClient {
    * @param amount USD amount as decimal string (e.g. "1000"), or "max" for MaxUint256.
    */
   async approveUsdc(amount) {
-    if (this.delegated) {
-      throw new OstiumError(
-        "approveUsdc is not available in delegated mode. The trader must approve USDC directly from their own account.",
-        "DELEGATION_FAILED" /* DELEGATION_FAILED */
-      );
-    }
-    const rawAmount = amount === "max" ? maxUint256 : parseUsdc(amount);
-    const encoded = encodeUsdcApprove(this.contracts.tradingStorage, rawAmount, this.contracts.usdc);
+    const encoded = this.getApproveUsdcEncoded(amount);
     if (this.selfGasless) {
-      return this.submitDirectFromEoa(encoded);
+      return this.submitDirectEoa(encoded);
     }
-    return this.requireWriter().submitter.submit(encoded);
+    return this.submitPrepared(encoded);
+  }
+  getApproveUsdcTx(amount) {
+    return this.buildDirectEoaTx(this.getApproveUsdcEncoded(amount));
   }
   // ─────────────────────────────────────────────────────────────────────────
   // Delegation helpers
@@ -4527,16 +4790,20 @@ var OstiumClient = class _OstiumClient {
    *   update the trader's delegation on their behalf.
    */
   async setDelegate(delegateAddress) {
-    const encoded = encodeSetDelegate(delegateAddress, this.contracts.trading);
-    return this.execute(encoded);
+    return this.submitPrepared(this.getSetDelegateEncoded(delegateAddress));
+  }
+  getSetDelegateTx(delegateAddress) {
+    return this.buildPreparedTx(this.getSetDelegateEncoded(delegateAddress));
   }
   /**
    * Remove the current delegate on the trading contract.
    * Follows the same delegation-wrapping rules as setDelegate().
    */
   async removeDelegate() {
-    const encoded = encodeRemoveDelegate(this.contracts.trading);
-    return this.execute(encoded);
+    return this.submitPrepared(this.getRemoveDelegateEncoded());
+  }
+  getRemoveDelegateTx() {
+    return this.buildPreparedTx(this.getRemoveDelegateEncoded());
   }
   // ─────────────────────────────────────────────────────────────────────────
   // Core trading methods
@@ -4549,6 +4816,12 @@ var OstiumClient = class _OstiumClient {
    * the current allowance.
    */
   async openTrade(params) {
+    return this.submitPrepared(this.getOpenTradeEncoded(params));
+  }
+  getOpenTradeTx(params) {
+    return this.buildPreparedTx(this.getOpenTradeEncoded(params));
+  }
+  getOpenTradeEncoded(params) {
     const collateralNum = parseFloat(params.collateral);
     if (collateralNum > MAX_COLLATERAL_USD) {
       throw new OstiumError(
@@ -4557,7 +4830,7 @@ var OstiumClient = class _OstiumClient {
       );
     }
     const apiOpen = {
-      a: params.pairIndex,
+      a: Number(params.pairId),
       b: params.buy,
       p: params.price,
       s: params.collateral,
@@ -4580,8 +4853,7 @@ var OstiumClient = class _OstiumClient {
     }
     const builderFee = buildBuilderFee(apiBuilder);
     const slippageP = params.type === "market" /* Market */ ? BigInt(this.resolveSlippage(params.slippage)) : 0n;
-    const encoded = encodeOpenTrade(trade, builderFee, orderType, slippageP, this.contracts.trading);
-    return this.execute(encoded);
+    return encodeOpenTrade(trade, builderFee, orderType, slippageP, this.contracts.trading);
   }
   /**
    * Close an open position (full or partial).
@@ -4596,6 +4868,12 @@ var OstiumClient = class _OstiumClient {
    * ```
    */
   async closeTrade(params) {
+    return this.submitPrepared(this.getCloseTradeEncoded(params));
+  }
+  getCloseTradeTx(params) {
+    return this.buildPreparedTx(this.getCloseTradeEncoded(params));
+  }
+  getCloseTradeEncoded(params) {
     try {
       validateCloseParams({
         a: Number(params.pairId),
@@ -4615,7 +4893,7 @@ var OstiumClient = class _OstiumClient {
     const closePercentage = BigInt(Math.round(params.closePercent * 100));
     const marketPrice = parsePrice(params.price);
     const slippageP = BigInt(this.resolveSlippage(params.slippage));
-    const encoded = encodeCloseTradeMarket(
+    return encodeCloseTradeMarket(
       pairIndex,
       index,
       closePercentage,
@@ -4623,7 +4901,6 @@ var OstiumClient = class _OstiumClient {
       slippageP,
       this.contracts.trading
     );
-    return this.execute(encoded);
   }
   /**
    * Cancel a pending order.
@@ -4646,6 +4923,12 @@ var OstiumClient = class _OstiumClient {
    * ```
    */
   async cancelOrder(params) {
+    return this.submitPrepared(this.getCancelOrderEncoded(params));
+  }
+  getCancelOrderTx(params) {
+    return this.buildPreparedTx(this.getCancelOrderEncoded(params));
+  }
+  getCancelOrderEncoded(params) {
     let encoded;
     if (params.type === "limit" /* Limit */) {
       const pairIdNum = Number(params.pairId);
@@ -4682,7 +4965,7 @@ var OstiumClient = class _OstiumClient {
       }
       encoded = encodeOpenTradeMarketTimeout(BigInt(params.orderId), this.contracts.trading);
     }
-    return this.execute(encoded);
+    return encoded;
   }
   /**
    * Modify an open trade or a pending limit order.
@@ -4707,6 +4990,12 @@ var OstiumClient = class _OstiumClient {
    * - Both `takeProfit` and `stopLoss` without `price` → throws (send two calls).
    */
   async modifyOrder(params) {
+    return this.submitPrepared(this.getModifyOrderEncoded(params));
+  }
+  getModifyOrderTx(params) {
+    return this.buildPreparedTx(this.getModifyOrderEncoded(params));
+  }
+  getModifyOrderEncoded(params) {
     try {
       validateModifyParams({
         a: Number(params.pairId),
@@ -4746,7 +5035,7 @@ var OstiumClient = class _OstiumClient {
         "VALIDATION_FAILED" /* VALIDATION_FAILED */
       );
     }
-    return this.execute(encoded);
+    return encoded;
   }
   /**
    * Update collateral on an open position (isolated margin).
@@ -4766,6 +5055,12 @@ var OstiumClient = class _OstiumClient {
    * Checks USDC allowance before top-up operations.
    */
   async updateCollateral(params) {
+    return this.submitPrepared(await this.getUpdateCollateralEncoded(params));
+  }
+  async getUpdateCollateralTx(params) {
+    return this.buildPreparedTx(await this.getUpdateCollateralEncoded(params));
+  }
+  async getUpdateCollateralEncoded(params) {
     const amount = parseFloat(params.amount);
     if (Number.isNaN(amount) || amount === 0) {
       throw new OstiumError(
@@ -4789,7 +5084,7 @@ var OstiumClient = class _OstiumClient {
     } else {
       encoded = encodeRemoveCollateral(pairIndex, index, absAmount, this.contracts.trading);
     }
-    return this.execute(encoded);
+    return encoded;
   }
   // ─────────────────────────────────────────────────────────────────────────
   // Subgraph reads (Hyperliquid-style API)
@@ -4917,31 +5212,104 @@ var OstiumClient = class _OstiumClient {
   streamPrices(pairIds) {
     return this.subgraph.streamPrices(pairIds);
   }
+  /**
+   * Stream price-driven updates for an existing `getOpenPositions()` response.
+   *
+   * Subscribes only to the unique pairs referenced by the response and emits the
+   * full updated positions payload on each relevant price update. Pass an
+   * existing `priceStream` to reuse a websocket your app already owns, or omit
+   * it to let the SDK create a dedicated connection.
+   */
+  streamPositionUpdates(initial, priceStream) {
+    return this.subgraph.streamPositionUpdates(initial, priceStream);
+  }
   // ─────────────────────────────────────────────────────────────────────────
   // Internal helpers
   // ─────────────────────────────────────────────────────────────────────────
-  /**
-   * Core execution pipeline:
-   * 1. signer.prepare()  — optionally wraps in delegatedAction.
-   * 2. submitter.submit() — sends via EOA walletClient or Pimlico UserOp.
-   */
-  async execute(encoded) {
-    const { signer, submitter } = this.requireWriter();
-    const prepared = signer.prepare(encoded);
-    return submitter.submit(prepared);
-  }
-  /** Throws if the client is read-only; otherwise returns the signer + submitter. */
-  requireWriter() {
-    if (!this.signer || !this.submitter) {
+  getSetupGaslessDelegationEncoded() {
+    if (!this.selfGasless || !this.effectiveSender) {
       throw new OstiumError(
-        "This client is read-only. Use one of the createSelfAnd*/createDelegatedAnd* factories to enable writes.",
+        "setupGaslessDelegation() is only available in Self + Gasless mode.",
         "INVALID_CONFIG" /* INVALID_CONFIG */
       );
     }
-    return { signer: this.signer, submitter: this.submitter };
+    return encodeSetDelegate(this.effectiveSender, this.contracts.trading);
+  }
+  getApproveUsdcEncoded(amount) {
+    if (this.delegated) {
+      throw new OstiumError(
+        "approveUsdc is not available in delegated mode. The trader must approve USDC directly from their own account.",
+        "DELEGATION_FAILED" /* DELEGATION_FAILED */
+      );
+    }
+    const rawAmount = amount === "max" ? maxUint256 : parseUsdc(amount);
+    return encodeUsdcApprove(this.contracts.tradingStorage, rawAmount, this.contracts.usdc);
+  }
+  getSetDelegateEncoded(delegateAddress) {
+    return encodeSetDelegate(delegateAddress, this.contracts.trading);
+  }
+  getRemoveDelegateEncoded() {
+    return encodeRemoveDelegate(this.contracts.trading);
+  }
+  prepareEncoded(encoded) {
+    const signer = this.requireBuildCapability();
+    return signer.prepare(encoded);
+  }
+  buildPreparedTx(encoded) {
+    return this.toBuiltTxRequest(this.prepareEncoded(encoded));
+  }
+  buildDirectEoaTx(encoded) {
+    if (!this.canBuildTransactions() || !this.traderAddress) {
+      throw new OstiumError(
+        "This client cannot build transactions. Use one of the createSelfAnd*/createDelegatedAnd* factories.",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
+    return {
+      kind: "eoa",
+      to: encoded.to,
+      data: encoded.data,
+      value: encoded.value,
+      from: this.traderAddress,
+      traderAddress: this.traderAddress
+    };
+  }
+  toBuiltTxRequest(encoded) {
+    if (!this.canBuildTransactions() || !this.traderAddress || !this.effectiveSender) {
+      throw new OstiumError(
+        "This client cannot build transactions. Use one of the createSelfAnd*/createDelegatedAnd* factories.",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
+    if (this.gasless) {
+      return {
+        kind: "safe",
+        safeAddress: this.effectiveSender,
+        traderAddress: this.traderAddress,
+        calls: [encoded]
+      };
+    }
+    return {
+      kind: "eoa",
+      to: encoded.to,
+      data: encoded.data,
+      value: encoded.value,
+      from: this.effectiveSender,
+      traderAddress: this.traderAddress
+    };
+  }
+  async submitPrepared(encoded) {
+    const submitter = this.requireSubmitCapability();
+    return submitter.submit(this.prepareEncoded(encoded));
   }
   /** Direct EOA submission — used only in Self + Gasless for approveUsdc and setupGaslessDelegation. */
-  async submitDirectFromEoa(encoded) {
+  async submitDirectEoa(encoded) {
+    if (!this.eoaSubmit) {
+      throw new OstiumError(
+        "This client cannot submit direct EOA transactions.",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
     try {
       return await this.eoaSubmit(encoded);
     } catch (err) {
@@ -4957,6 +5325,24 @@ var OstiumClient = class _OstiumClient {
       throw new OstiumError(`Transaction failed: ${msg}`, "SUBMISSION_FAILED" /* SUBMISSION_FAILED */, err);
     }
   }
+  requireBuildCapability() {
+    if (!this.signer) {
+      throw new OstiumError(
+        "This client cannot build transactions. Use one of the createSelfAnd*/createDelegatedAnd* factories.",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
+    return this.signer;
+  }
+  requireSubmitCapability() {
+    if (!this.submitter) {
+      throw new OstiumError(
+        "This client does not have submission credentials. Use the corresponding get*Tx() method or initialize with a private key.",
+        "INVALID_CONFIG" /* INVALID_CONFIG */
+      );
+    }
+    return this.submitter;
+  }
   resolveSlippage(override) {
     return override ?? this.defaultSlippageBps;
   }
@@ -5839,7 +6225,7 @@ async function actionOpenTrade(client2) {
   const result = await spin(
     "Submitting openTrade\u2026",
     () => client2.openTrade({
-      pairIndex: pairId,
+      pairId,
       buy: buy === "true",
       price,
       collateral,
@@ -5929,7 +6315,7 @@ async function actionCloseTrade(client2) {
 }
 async function actionCancelOrder(client2) {
   let cancelType = "limit" /* Limit */;
-  let pairIndex = "0";
+  let pairIdInput = "0";
   let orderIndex = "0";
   let orderId = "";
   let retry = false;
@@ -5948,12 +6334,12 @@ async function actionCancelOrder(client2) {
       }
       case 1: {
         if (cancelType === "limit" /* Limit */) {
-          const v = await wtext({ message: "Pair index", initialValue: pairIndex });
+          const v = await wtext({ message: "Pair ID", initialValue: pairIdInput });
           if (v === BACK) {
             step--;
             break;
           }
-          pairIndex = v;
+          pairIdInput = v;
           step++;
           break;
         } else {
@@ -6000,7 +6386,7 @@ async function actionCancelOrder(client2) {
       }
     }
   }
-  const cancelParams = cancelType === "limit" /* Limit */ ? { type: "limit" /* Limit */, pairId: parseInt(pairIndex), idx: parseInt(orderIndex) } : cancelType === "pendingClose" /* PendingClose */ ? { type: "pendingClose" /* PendingClose */, orderId: parseInt(orderId), retry } : { type: "pendingOpen" /* PendingOpen */, orderId: parseInt(orderId) };
+  const cancelParams = cancelType === "limit" /* Limit */ ? { type: "limit" /* Limit */, pairId: parseInt(pairIdInput), idx: parseInt(orderIndex) } : cancelType === "pendingClose" /* PendingClose */ ? { type: "pendingClose" /* PendingClose */, orderId: parseInt(orderId), retry } : { type: "pendingOpen" /* PendingOpen */, orderId: parseInt(orderId) };
   const result = await spin(
     "Submitting cancelOrder\u2026",
     () => client2.cancelOrder(cancelParams)
@@ -6010,7 +6396,7 @@ async function actionCancelOrder(client2) {
 async function actionModifyOrder(client2) {
   const fields = await p.group(
     {
-      pairIndex: () => p.text({ message: "Pair index", initialValue: "0" }),
+      pairIndex: () => p.text({ message: "Pair ID", initialValue: "0" }),
       index: () => p.text({ message: "Trade / order index", initialValue: "0" }),
       price: () => p.text({ message: "New limit price (optional)", placeholder: "leave blank to skip" }),
       tp: () => p.text({ message: "New take profit (optional)", placeholder: "leave blank to skip" }),
@@ -6033,7 +6419,7 @@ async function actionModifyOrder(client2) {
 async function actionUpdateCollateral(client2) {
   const fields = await p.group(
     {
-      pairIndex: () => p.text({ message: "Pair index", initialValue: "0" }),
+      pairIndex: () => p.text({ message: "Pair ID", initialValue: "0" }),
       index: () => p.text({ message: "Trade index", initialValue: "0" }),
       amount: () => p.text({
         message: "Amount (positive = add, negative = remove)",
@@ -6172,7 +6558,7 @@ async function actionViewPrices(client2) {
   }
 }
 async function actionViewPositions(client2) {
-  const { pairPositions, marginSummary, withdrawable } = await spin(
+  const { pairPositions, marginSummary } = await spin(
     "Fetching open positions\u2026",
     () => client2.getOpenPositions()
   );
@@ -6209,7 +6595,8 @@ async function actionViewPositions(client2) {
   p.log.info(`Total collateral: $${parseFloat(marginSummary.totalCollateralUsed).toFixed(4)}`);
   p.log.info(`Total notional:   $${parseFloat(marginSummary.totalNtlPos).toFixed(4)}`);
   p.log.info(`Unrealized PnL:   $${parseFloat(marginSummary.totalRawPnlUsd).toFixed(4)}`);
-  p.log.info(`Max withdrawable: $${parseFloat(withdrawable).toFixed(4)}`);
+  p.log.info(`Cum rollover:     $${parseFloat(marginSummary.totalCumRollover).toFixed(4)}`);
+  p.log.info(`Max withdrawable: $${parseFloat(marginSummary.totalWithdrawable).toFixed(4)}`);
 }
 async function actionViewFills(client2) {
   const limitRaw = await p.text({