@solard/sdk 0.2.25 → 0.2.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/sdk",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Public Solard SDK for wallets, trading, history, live market subscriptions and token metadata.",
   "type": "module",
   "main": "./src/index.ts",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@solana/web3.js": "^1.98.4",
-    "@solard/core": "0.2.25"
+    "@solard/core": "0.2.27"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.browser.json",

package/src/client.ts

@@ -16,6 +16,15 @@ import {
   type ReplayItem,
   type ReplayOptions,
   type ReplayEventsOptions,
+  type RecordConfirmedTradeInput,
+  type SendReceipt,
+  type SenderId,
+  type SolardDecodedTransaction,
+  type SolardTransactionOptions,
+  type SolardPosition,
+  type SolardPositionQuery,
+  type SolardTrade,
+  type SolardTradeQuery,
   type TokenHolderSnapshot,
   type TokenHolderSnapshotOptions,
   type TokenRef,
@@ -49,6 +58,38 @@ export type SolardEventsApi = {
   merge(streams: readonly ReplayEventSubscription[]): MergedReplayEventStream;
 };
 
+export type SolardBuyInput = {
+  wallet: WalletRef;
+  token: TokenRef;
+  amount: HumanAmount | string | number;
+  slippageBps?: number;
+};
+
+export type SolardSellInput = {
+  wallet: WalletRef;
+  token: TokenRef;
+  amount?: "all" | { bps: number };
+  slippageBps?: number;
+};
+
+export type SolardTradeExecutionOptions = {
+  waitForConfirmation?: boolean;
+  via?: SenderId;
+  skipSimulation?: boolean;
+  skipPreflight?: boolean;
+};
+
+export type SolardTradeExecutionResult = {
+  executionId: number;
+  signature: string;
+  sender: string;
+  status: SendReceipt["status"];
+  slot: number | null;
+  error: string | null;
+  feeLamports?: number;
+  computeUnitsConsumed?: number;
+};
+
 export type Solard = {
   close(): void;
   history: SolardHistoryApi;
@@ -81,7 +122,7 @@ export type Solard = {
   importWallet: ReturnType<typeof createCoreSolard>["importWallet"];
   listWallets: ReturnType<typeof createCoreSolard>["listWallets"];
   walletAddress(wallet: WalletRef): string;
-  exportWalletPrivateKey(
+  exportPrivateKey(
     wallet: WalletRef,
     format?: WalletPrivateKeyFormat,
   ): WalletPrivateKeyExport;
@@ -93,16 +134,106 @@ export type Solard = {
     options?: Omit<TokenHolderSnapshotOptions, "token">,
   ): Promise<TokenHolderSnapshot>;
   walletBalances: ReturnType<typeof createCoreSolard>["walletBalances"];
+  recordConfirmedTrade(input: RecordConfirmedTradeInput): Promise<SolardTrade>;
+  trades(options?: SolardTradeQuery): Promise<SolardTrade[]>;
+  position(options: SolardPositionQuery): Promise<SolardPosition>;
+  getTransaction(
+    signature: string,
+    options?: SolardTransactionOptions,
+  ): Promise<SolardDecodedTransaction | null>;
   samplePrice(token: TokenRef): Promise<MarketPrice>;
   buy(
-    token: TokenRef,
-    wallet: WalletRef,
-    amount: HumanAmount,
-    options?: Parameters<ReturnType<typeof createCoreSolard>["buy"]>[3],
-  ): ReturnType<ReturnType<typeof createCoreSolard>["buy"]>;
-  sell: ReturnType<typeof createCoreSolard>["sell"];
+    input: SolardBuyInput,
+    options?: SolardTradeExecutionOptions,
+  ): Promise<SolardTradeExecutionResult>;
+  sell(
+    input: SolardSellInput,
+    options?: SolardTradeExecutionOptions,
+  ): Promise<SolardTradeExecutionResult>;
 };
 
+function tradeAmount(value: HumanAmount | string | number): HumanAmount {
+  return typeof value === "string" || typeof value === "number"
+    ? { sol: value }
+    : value;
+}
+
+function sellBps(value: SolardSellInput["amount"]): number {
+  if (value == null || value === "all") return 10_000;
+  const bps = Math.trunc(value.bps);
+  if (!(bps > 0 && bps <= 10_000))
+    throw new Error("sell amount.bps must be between 1 and 10000");
+  return bps;
+}
+
+function pumpSwap6040(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    message.includes("Simulation failed") &&
+    (message.includes("BuySlippageBelowMinBaseAmountOut") ||
+      message.includes("Error Number: 6040") ||
+      /["']?Custom["']?\s*[:=]\s*6040/.test(message))
+  );
+}
+
+async function executeTrade(
+  core: ReturnType<typeof createCoreSolard>,
+  side: "buy" | "sell",
+  input: SolardBuyInput | SolardSellInput,
+  options: SolardTradeExecutionOptions = {},
+): Promise<SolardTradeExecutionResult> {
+  const via = options.via ?? "rpc";
+  const buildAndSubmit = async () => {
+    const composer = core.tx(input.wallet);
+    if (side === "buy") {
+      const buy = input as SolardBuyInput;
+      composer.buy(buy.token, tradeAmount(buy.amount), {
+        slippageBps: buy.slippageBps,
+      });
+    } else {
+      const sell = input as SolardSellInput;
+      composer.sell(sell.token, {
+        bps: sellBps(sell.amount),
+        slippageBps: sell.slippageBps,
+      });
+    }
+    const plan = await composer.build();
+    return await core.submitPlan(plan, via, side, {
+      skipSimulation: options.skipSimulation,
+      skipPreflight: options.skipPreflight,
+    });
+  };
+  let submission;
+  try {
+    submission = await buildAndSubmit();
+  } catch (error) {
+    if (side !== "buy" || options.skipSimulation || !pumpSwap6040(error))
+      throw error;
+    submission = await buildAndSubmit();
+  }
+  if (options.waitForConfirmation === false) {
+    return {
+      executionId: submission.executionId,
+      signature: submission.signature,
+      sender: submission.sender,
+      status: "submitted",
+      slot: null,
+      error: null,
+    };
+  }
+  const receipt = await core.settleSubmission(submission);
+  return {
+    executionId: submission.executionId,
+    signature: receipt.signature,
+    sender: receipt.sender,
+    status: receipt.status,
+    slot: receipt.slot,
+    error: receipt.error ?? null,
+    feeLamports: receipt.feeLamports,
+    computeUnitsConsumed: receipt.computeUnitsConsumed,
+  };
+}
+
 export function createSolard(options: SolardOptions = {}): Solard {
   const core = createCoreSolard(options);
   const history: SolardHistoryApi = Object.freeze({
@@ -135,14 +266,20 @@ export function createSolard(options: SolardOptions = {}): Solard {
     importWallet: core.importWallet.bind(core),
     listWallets: core.listWallets.bind(core),
     walletAddress: core.walletAddress.bind(core),
-    exportWalletPrivateKey: core.exportWalletPrivateKey.bind(core),
+    exportPrivateKey: core.exportWalletPrivateKey.bind(core),
     addToken: core.addToken.bind(core),
     resolveToken: core.resolveToken.bind(core),
     tokenAccounts: core.tokenAccounts.bind(core),
     snapshotHolders: core.snapshotHolders.bind(core),
     walletBalances: core.walletBalances.bind(core),
+    recordConfirmedTrade: core.recordConfirmedTrade.bind(core),
+    trades: core.trades.bind(core),
+    position: core.position.bind(core),
+    getTransaction: core.getTransaction.bind(core),
     samplePrice: core.samplePrice.bind(core),
-    buy: core.buy.bind(core),
-    sell: core.sell.bind(core),
+    buy: (input, executionOptions) =>
+      executeTrade(core, "buy", input, executionOptions),
+    sell: (input, executionOptions) =>
+      executeTrade(core, "sell", input, executionOptions),
   });
 }

package/src/default.ts

@@ -1,5 +1,18 @@
+import { getSolUsdPrice } from "@solard/core";
+import {
+  listenTrades,
+  subscribeLaunches,
+  subscribeMigrations,
+} from "./live.ts";
 import { createSolard, type Solard } from "./client.ts";
 
+type DefaultSolard = Solard & {
+  getSolUsdPrice: typeof getSolUsdPrice;
+  listenTrades: typeof listenTrades;
+  subscribeLaunches: typeof subscribeLaunches;
+  subscribeMigrations: typeof subscribeMigrations;
+};
+
 let instance: Solard | undefined;
 
 function client(): Solard {
@@ -7,7 +20,14 @@ function client(): Solard {
   return instance;
 }
 
-const slrd = new Proxy({} as Solard, {
+const operations = {
+  getSolUsdPrice,
+  listenTrades,
+  subscribeLaunches,
+  subscribeMigrations,
+} as const;
+
+const slrd = new Proxy({} as DefaultSolard, {
   get(_target, key) {
     if (key === "close") {
       return () => {
@@ -16,6 +36,9 @@ const slrd = new Proxy({} as Solard, {
         current?.close();
       };
     }
+    if (typeof key === "string" && key in operations) {
+      return operations[key as keyof typeof operations];
+    }
     const current = client();
     const value = Reflect.get(current as object, key, current);
     return typeof value === "function" ? value.bind(current) : value;

package/src/export-surface.test.ts

@@ -6,6 +6,7 @@ const source = readFileSync(join(import.meta.dir, "index.ts"), "utf8");
 const client = readFileSync(join(import.meta.dir, "client.ts"), "utf8");
 const protocol = readFileSync(join(import.meta.dir, "protocol.ts"), "utf8");
 const defaultClient = readFileSync(join(import.meta.dir, "default.ts"), "utf8");
+const live = readFileSync(join(import.meta.dir, "live.ts"), "utf8");
 
 function exportedNames(value: string) {
   const values: string[] = [];
@@ -30,13 +31,14 @@ describe("sdk membrane", () => {
     expect(exportedNames(source)).toEqual({
       values: [
         "createSolard",
+        "default",
         "fetchTokenMetadata",
         "formatRaw",
         "getSolUsdPrice",
         "publicTokenMetadataUrl",
         "subscribeLaunches",
         "subscribeMigrations",
-        "subscribeTrades",
+        "listenTrades",
         "sol",
         "tokenAmount",
       ].sort(),
@@ -65,6 +67,9 @@ describe("sdk membrane", () => {
         "MarketPrice",
         "SolUsdPrice",
         "SolUsdSource",
+        "SubscribeLaunchesOptions",
+        "SubscribeMigrationsOptions",
+        "ListenTradesOptions",
         "MergedReplayEventStream",
         "QuoteAsset",
         "ReplayCoverage",
@@ -75,15 +80,30 @@ describe("sdk membrane", () => {
         "ReplayOptions",
         "ReplayPayout",
         "ReplayTransaction",
+        "RecordConfirmedTradeInput",
         "SendReceipt",
         "SenderId",
         "SimulationResult",
+        "SolardDecodedTransaction",
+        "SolardPosition",
+        "SolardPositionQuery",
+        "SolardTransactionNativeBalance",
+        "SolardTransactionOptions",
+        "SolardTransactionTokenBalance",
+        "SolardTrade",
+        "SolardTradeQuery",
+        "SolardTradeSide",
+        "SolardTradeStatus",
         "TradeEvent",
         "TradeMarket",
         "TradeSide",
-        "TradeSubscription",
+        "TradeListener",
         "TradeVenue",
         "Solard",
+        "SolardBuyInput",
+        "SolardSellInput",
+        "SolardTradeExecutionOptions",
+        "SolardTradeExecutionResult",
         "SolardCanonicalEvent",
         "SolardClaimAttribution",
         "SolardClaimEvent",
@@ -138,7 +158,16 @@ describe("sdk membrane", () => {
     expect(source).toContain('export { default } from "./default.ts"');
     expect(defaultClient).toContain("instance ??= createSolard()");
     expect(defaultClient).toContain('if (key === "close")');
+    expect(defaultClient).toContain("getSolUsdPrice");
+    expect(defaultClient).toContain("listenTrades");
+    expect(defaultClient).toContain("subscribeLaunches");
+    expect(defaultClient).toContain("subscribeMigrations");
     expect(defaultClient).not.toContain("export default createSolard()");
+    expect(live).toContain("process.env.RPC_ENDPOINT");
+    expect(live).not.toContain("SOLANA_RPC_URL");
+    expect(live).not.toContain("HELIUS_RPC_URL");
+    expect(live).not.toContain("SOLANA_WS_URL");
+    expect(live).not.toContain("HELIUS_WS_URL");
   });
 
   test("does not create persistence at module import", () => {
@@ -147,6 +176,10 @@ describe("sdk membrane", () => {
     expect(client.indexOf("createCoreSolard(options)")).toBeGreaterThan(
       client.indexOf("export function createSolard"),
     );
+    expect(client).toContain(
+      "recordConfirmedTrade: core.recordConfirmedTrade.bind(core)",
+    );
+    expect(client).toContain("trades: core.trades.bind(core)");
   });
 
   test("does not expose core repositories or secret-bearing handles", () => {

package/src/index.ts

@@ -2,9 +2,13 @@ export { default } from "./default.ts";
 export { createSolard } from "./client.ts";
 export type {
   Solard,
+  SolardBuyInput,
   SolardEventsApi,
   SolardHistoryApi,
   SolardOptions,
+  SolardSellInput,
+  SolardTradeExecutionOptions,
+  SolardTradeExecutionResult,
 } from "./client.ts";
 
 export { formatRaw, sol, tokenAmount } from "@solard/core";
@@ -33,9 +37,20 @@ export type {
   ReplayOptions,
   ReplayPayout,
   ReplayTransaction,
+  RecordConfirmedTradeInput,
   SendReceipt,
   SenderId,
   SimulationResult,
+  SolardDecodedTransaction,
+  SolardPosition,
+  SolardPositionQuery,
+  SolardTransactionNativeBalance,
+  SolardTransactionOptions,
+  SolardTransactionTokenBalance,
+  SolardTrade,
+  SolardTradeQuery,
+  SolardTradeSide,
+  SolardTradeStatus,
   SolardCanonicalEvent,
   SolardClaimAttribution,
   SolardClaimEvent,
@@ -56,10 +71,18 @@ export {
   fetchTokenMetadata,
   getSolUsdPrice,
   publicTokenMetadataUrl,
+} from "@solard/core";
+export {
+  listenTrades,
   subscribeLaunches,
   subscribeMigrations,
-  subscribeTrades,
-} from "@solard/core";
+} from "./live.ts";
+export type {
+  ListenTradesOptions,
+  SubscribeLaunchesOptions,
+  SubscribeMigrationsOptions,
+  TradeListener,
+} from "./live.ts";
 export type {
   LaunchEvent,
   LaunchSubscription,
@@ -74,7 +97,6 @@ export type {
   TradeEvent,
   TradeMarket,
   TradeSide,
-  TradeSubscription,
   TradeVenue,
   FetchTokenMetadataOptions,
   TokenMetadata,

package/src/live.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { deriveWebSocketEndpoint, redactRpcEndpoint } from "./live.ts";
+
+describe("sdk live endpoint", () => {
+  test("derives websocket from the one RPC endpoint", () => {
+    expect(
+      deriveWebSocketEndpoint(
+        "https://mainnet.helius-rpc.com/?api-key=secret-value",
+      ),
+    ).toBe("wss://mainnet.helius-rpc.com/?api-key=secret-value");
+  });
+
+  test("redacts API credentials in diagnostics", () => {
+    expect(
+      redactRpcEndpoint(
+        "https://mainnet.helius-rpc.com/?api-key=secret-value&foo=bar",
+      ),
+    ).toBe("https://mainnet.helius-rpc.com/?api-key=<redacted>&foo=bar");
+  });
+});

package/src/live.ts

@@ -0,0 +1,332 @@
+import { Connection } from "@solana/web3.js";
+import {
+  subscribeLaunches as subscribeCoreLaunches,
+  subscribeMigrations as subscribeCoreMigrations,
+  subscribeTrades as subscribeCoreTrades,
+  type TradeEvent,
+  type TradeSubscription,
+} from "@solard/core";
+
+export type SubscribeLaunchesOptions = Omit<
+  Parameters<typeof subscribeCoreLaunches>[0],
+  "connection"
+>;
+export type SubscribeMigrationsOptions = Omit<
+  Parameters<typeof subscribeCoreMigrations>[0],
+  "connection"
+>;
+export type SubscribeTradesOptions = Omit<
+  Parameters<typeof subscribeCoreTrades>[0],
+  "connection"
+>;
+
+export type ListenTradesOptions = Omit<SubscribeTradesOptions, "onTrade">;
+
+export type TradeListener = {
+  add(tokens: string | readonly string[]): Promise<void>;
+  remove(tokens: string | readonly string[]): Promise<void>;
+  has(token: string): boolean;
+  list(): string[];
+  onTrade(callback: (event: TradeEvent) => void | Promise<void>): () => void;
+  close(): Promise<void>;
+  readonly closed: Promise<void>;
+};
+
+type LiveConnection = {
+  endpoint: string;
+  websocketEndpoint: string;
+  connection: Connection;
+};
+
+let shared: LiveConnection | null = null;
+let readiness: { endpoint: string; promise: Promise<void> } | null = null;
+
+function endpointFromEnv(): string {
+  const endpoint = process.env.RPC_ENDPOINT?.trim();
+  if (!endpoint)
+    throw new Error(
+      "Missing RPC_ENDPOINT. Set one Solana RPC URL in RPC_ENDPOINT; Solard derives WebSocket access from the same endpoint.",
+    );
+  let parsed: URL;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new Error("RPC_ENDPOINT must be a valid http:// or https:// URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    throw new Error("RPC_ENDPOINT must use http:// or https://.");
+  return endpoint;
+}
+
+export function deriveWebSocketEndpoint(endpoint: string): string {
+  const url = new URL(endpoint);
+  if (url.protocol === "https:") url.protocol = "wss:";
+  else if (url.protocol === "http:") url.protocol = "ws:";
+  else throw new Error("RPC endpoint must use http:// or https://.");
+  return url.toString();
+}
+
+export function redactRpcEndpoint(endpoint: string): string {
+  try {
+    const url = new URL(endpoint);
+    const keys: string[] = [];
+    url.searchParams.forEach((_value, key) => keys.push(key));
+    for (const key of keys) {
+      if (/key|token|secret|auth/i.test(key))
+        url.searchParams.set(key, "<redacted>");
+    }
+    return url.toString().replaceAll("%3Credacted%3E", "<redacted>");
+  } catch {
+    return endpoint.replace(
+      /([?&](?:api-?key|api_key|apikey|key|token|secret|auth)=)[^&]+/gi,
+      "$1<redacted>",
+    );
+  }
+}
+
+function providerName(endpoint: string): string {
+  try {
+    return new URL(endpoint).hostname.endsWith("helius-rpc.com")
+      ? "Helius"
+      : "Solana RPC provider";
+  } catch {
+    return "Solana RPC provider";
+  }
+}
+
+function safeMessage(error: unknown): string {
+  const value = error instanceof Error ? error.message : String(error);
+  return value
+    .replace(
+      /([?&](?:api-?key|api_key|apikey|key|token|secret|auth)=)[^&\s]+/gi,
+      "$1<redacted>",
+    )
+    .slice(0, 400);
+}
+
+function rpcFailure(endpoint: string, detail: string): Error {
+  return new Error(
+    `${providerName(endpoint)} rejected RPC_ENDPOINT ${redactRpcEndpoint(endpoint)}. Check the API key, credits/quota, rate limits, and account status. ${detail}`,
+  );
+}
+
+function websocketFailure(endpoint: string, detail: string): Error {
+  return new Error(
+    `${providerName(endpoint)} rejected WebSocket access derived from RPC_ENDPOINT ${redactRpcEndpoint(endpoint)}. Check the API key, credits/quota, rate limits, and WebSocket connection limits. ${detail}`,
+  );
+}
+
+async function preflightRpc(endpoint: string): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 6_000);
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getHealth" }),
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      const label =
+        response.status === 401 || response.status === 403
+          ? "Authentication failed."
+          : response.status === 402
+            ? "Billing or credits are unavailable."
+            : response.status === 429
+              ? "Rate limit or quota was exceeded."
+              : `HTTP ${response.status}.`;
+      throw rpcFailure(endpoint, label);
+    }
+    const body = (await response.json()) as {
+      result?: unknown;
+      error?: { code?: unknown; message?: unknown };
+    };
+    if (body.error) {
+      const code =
+        body.error.code == null ? "" : `code ${String(body.error.code)}: `;
+      throw rpcFailure(
+        endpoint,
+        `${code}${String(body.error.message ?? "RPC error")}`,
+      );
+    }
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.includes("rejected RPC_ENDPOINT")
+    )
+      throw error;
+    if (controller.signal.aborted)
+      throw rpcFailure(endpoint, "Connection timed out.");
+    throw rpcFailure(endpoint, safeMessage(error));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function preflightWebSocket(endpoint: string): Promise<void> {
+  const websocketEndpoint = deriveWebSocketEndpoint(endpoint);
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let socket: WebSocket | null = null;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error && socket) {
+        try {
+          socket.close();
+        } catch {}
+      }
+      if (error) reject(error);
+      else resolve();
+    };
+    const timer = setTimeout(
+      () =>
+        finish(websocketFailure(endpoint, "WebSocket handshake timed out.")),
+      6_000,
+    );
+    try {
+      socket = new WebSocket(websocketEndpoint);
+    } catch (error) {
+      finish(websocketFailure(endpoint, safeMessage(error)));
+      return;
+    }
+    socket.addEventListener(
+      "open",
+      () => {
+        try {
+          socket?.close(1000);
+        } catch {}
+        finish();
+      },
+      { once: true },
+    );
+    socket.addEventListener(
+      "error",
+      (event) => {
+        const detail = safeMessage(
+          (event as { error?: unknown }).error ??
+            "WebSocket handshake was rejected.",
+        );
+        finish(websocketFailure(endpoint, detail));
+      },
+      { once: true },
+    );
+    socket.addEventListener(
+      "close",
+      (event) => {
+        if (settled) return;
+        const detail = event.reason
+          ? `WebSocket closed during handshake: ${event.reason}`
+          : `WebSocket closed during handshake with code ${event.code}.`;
+        finish(websocketFailure(endpoint, detail));
+      },
+      { once: true },
+    );
+  });
+}
+
+async function ensureReady(endpoint: string): Promise<void> {
+  if (readiness?.endpoint === endpoint) return await readiness.promise;
+  const promise = Promise.all([
+    preflightRpc(endpoint),
+    preflightWebSocket(endpoint),
+  ]).then(() => undefined);
+  readiness = { endpoint, promise };
+  try {
+    await promise;
+  } catch (error) {
+    if (readiness?.promise === promise) readiness = null;
+    throw error;
+  }
+}
+
+async function liveConnection(): Promise<LiveConnection> {
+  const endpoint = endpointFromEnv();
+  await ensureReady(endpoint);
+  if (shared?.endpoint === endpoint) return shared;
+  shared = {
+    endpoint,
+    websocketEndpoint: deriveWebSocketEndpoint(endpoint),
+    connection: new Connection(endpoint, "confirmed"),
+  };
+  return shared;
+}
+
+function notifyReady(
+  options: {
+    onStatus?: (event: string, data?: Record<string, unknown>) => void;
+  },
+  live: LiveConnection,
+): void {
+  try {
+    options.onStatus?.("rpc-ready", {
+      rpc: redactRpcEndpoint(live.endpoint),
+      websocket: redactRpcEndpoint(live.websocketEndpoint),
+    });
+  } catch {}
+}
+
+export async function subscribeTrades(options: SubscribeTradesOptions) {
+  const live = await liveConnection();
+  notifyReady(options, live);
+  return await subscribeCoreTrades({ ...options, connection: live.connection });
+}
+
+export async function subscribeLaunches(options: SubscribeLaunchesOptions) {
+  const live = await liveConnection();
+  notifyReady(options, live);
+  return await subscribeCoreLaunches({
+    ...options,
+    connection: live.connection,
+  });
+}
+
+export async function subscribeMigrations(options: SubscribeMigrationsOptions) {
+  const live = await liveConnection();
+  notifyReady(options, live);
+  return await subscribeCoreMigrations({
+    ...options,
+    connection: live.connection,
+  });
+}
+export async function listenTrades(
+  options: ListenTradesOptions,
+): Promise<TradeListener> {
+  const callbacks = new Set<(event: TradeEvent) => void | Promise<void>>();
+  const pending: TradeEvent[] = [];
+  let subscription: TradeSubscription;
+  const dispatch = async (event: TradeEvent) => {
+    if (callbacks.size === 0) {
+      pending.push(event);
+      if (pending.length > 1_000) pending.shift();
+      return;
+    }
+    await Promise.all(
+      [...callbacks].map(async (callback) => {
+        await callback(event);
+      }),
+    );
+  };
+  subscription = await subscribeTrades({ ...options, onTrade: dispatch });
+  return {
+    add: (tokens) => subscription.addTokens(tokens),
+    remove: (tokens) => subscription.removeTokens(tokens),
+    has: (token) => subscription.hasToken(token),
+    list: () => subscription.listTokens(),
+    onTrade(callback) {
+      callbacks.add(callback);
+      if (pending.length) {
+        const rows = pending.splice(0);
+        void Promise.resolve().then(async () => {
+          for (const event of rows) await callback(event);
+        });
+      }
+      return () => callbacks.delete(callback);
+    },
+    close: () => subscription.close(),
+    get closed() {
+      return subscription.closed;
+    },
+  };
+}

package/src/operator-api.architecture.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const client = readFileSync(join(import.meta.dir, "client.ts"), "utf8");
+const live = readFileSync(join(import.meta.dir, "live.ts"), "utf8");
+const index = readFileSync(join(import.meta.dir, "index.ts"), "utf8");
+const core = readFileSync(
+  join(import.meta.dir, "../../core/src/core/solard.ts"),
+  "utf8",
+);
+
+describe("operator api", () => {
+  test("uses one object-form trade api", () => {
+    expect(client).toContain("input: SolardBuyInput");
+    expect(client).toContain("input: SolardSellInput");
+    expect(client).toContain("waitForConfirmation?: boolean");
+    expect(client).toContain("exportPrivateKey");
+    expect(client).toContain("getTransaction(");
+  });
+
+  test("uses one dynamic live trade listener api", () => {
+    expect(index).toContain("listenTrades");
+    expect(index).not.toContain("subscribeTrades");
+    expect(live).toContain("onTrade(callback)");
+    expect(live).toContain("add: (tokens)");
+    expect(live).toContain("remove: (tokens)");
+  });
+
+  test("persists the signed signature before safe rebroadcast", () => {
+    expect(core).toContain("const signature = signedPlanSignature(plan)");
+    expect(core).toContain(
+      "waitForSignatureSeen(this.connection(), signature)",
+    );
+    expect(core).toContain("await broadcast(true)");
+    expect(core).toContain("cacheParsedTransaction");
+  });
+
+  test("default trades settle inside Solard rather than leaking submitted state", () => {
+    expect(client).toContain("core.settleSubmission(");
+    expect(core).toContain("async settleSubmission(");
+    expect(core).toContain("submission.plan.lastValidBlockHeight");
+  });
+});