@solard/sdk 0.2.26 → 0.2.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/sdk",
-  "version": "0.2.26",
+  "version": "0.2.29",
   "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.26"
+    "@solard/core": "0.2.29"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.browser.json",

package/src/client.trade-fees.test.ts

@@ -0,0 +1,60 @@
+import { expect, spyOn, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Keypair } from "@solana/web3.js";
+import { Solard } from "../../core/src/core/solard.ts";
+import { TransactionComposer } from "../../core/src/tx/composer.ts";
+import type { PlannedTransaction, TransactionDraft } from "../../core/src/tx/types.ts";
+import { createSolard } from "./client.ts";
+
+test("SDK buy rebuild and sell preserve custom fees in immediate submitted results", async () => {
+  const directory = mkdtempSync(join(tmpdir(), "solard-sdk-fees-"));
+  const drafts: Array<TransactionDraft> = [];
+  // A sentinel plan is never compiled, signed, or broadcast in this test.
+  const payer = Keypair.generate();
+  const plan = { payer: payer.publicKey } as PlannedTransaction;
+  const build = spyOn(TransactionComposer.prototype, "build").mockImplementation(async function (this: TransactionComposer) {
+    drafts.push(this.snapshot());
+    return { ...plan, draft: this.snapshot() };
+  });
+  const signer = spyOn(Solard.prototype, "signer").mockImplementation(() => payer);
+  const compile = spyOn(Solard.prototype, "compile").mockImplementation(async (_payer, draft) => ({ ...plan, draft }));
+  let submissions = 0;
+  const submit = spyOn(Solard.prototype, "submitPlan").mockImplementation(async () => {
+    submissions += 1;
+    if (submissions === 1) {
+      throw new Error("Simulation failed: BuySlippageBelowMinBaseAmountOut");
+    }
+    return { signature: "test-signature", sender: "rpc", executionId: 42, plan };
+  });
+  const settle = spyOn(Solard.prototype, "settleSubmission").mockImplementation(async () => {
+    throw new Error("Immediate submission must not wait for confirmation");
+  });
+  const sdk = createSolard({ dbPath: join(directory, "test.sqlite") });
+  try {
+    const options = {
+      priorityFee: { cuLimit: 300_000, microLamports: 0 },
+      waitForConfirmation: false,
+    };
+    const buy = await sdk.buy({ token: "token", wallet: "wallet", amount: 0.1 }, options);
+    const sell = await sdk.sell({ token: "token", wallet: "wallet" }, options);
+    expect(drafts).toHaveLength(3);
+    for (const draft of drafts) {
+      expect(draft.cuLimit).toBe(300_000);
+      expect(draft.cuPriceMicroLamports).toBe(0);
+    }
+    expect(buy.status).toBe("submitted");
+    expect(sell.status).toBe("submitted");
+    expect(buy.executionId).toBe(42);
+    expect(settle).not.toHaveBeenCalled();
+  } finally {
+    sdk.close();
+    build.mockRestore();
+    signer.mockRestore();
+    compile.mockRestore();
+    submit.mockRestore();
+    settle.mockRestore();
+    rmSync(directory, { recursive: true, force: true });
+  }
+});

package/src/client.ts

@@ -1,148 +1,279 @@
-import {
-  createTraderSolard as createCoreSolard,
-  type ClaimCreatorRewardsOptions,
-  type CreatorRewardClaimResult,
-  type CumulativeDistributionExecuteOptions,
-  type CumulativeDistributionInput,
-  type CumulativeDistributionPlan,
-  type CumulativeDistributionState,
-  type HumanAmount,
-  type MarketHistory,
-  type MarketHistoryOptions,
-  type MarketPrice,
-  type MergedReplayEventStream,
-  type ReplayEventSubscription,
-  type ReplayHistory,
-  type ReplayItem,
-  type ReplayOptions,
-  type ReplayEventsOptions,
-  type TokenHolderSnapshot,
-  type TokenHolderSnapshotOptions,
-  type TokenRef,
-  type WalletRef,
-  type WalletPrivateKeyExport,
-  type WalletPrivateKeyFormat,
-} from "@solard/core";
-
-export type SolardOptions = {
-  rpcUrl?: string;
-  dbPath?: string;
-  cacheTtlMs?: number;
-};
-
-export type SolardHistoryApi = {
-  replay(token: TokenRef, options?: ReplayOptions): Promise<ReplayHistory>;
-  market(
-    token: TokenRef,
-    options?: MarketHistoryOptions,
-  ): Promise<MarketHistory>;
-  merge(
-    histories: readonly (ReplayHistory | Iterable<ReplayItem>)[],
-  ): ReplayItem[];
-};
-
-export type SolardEventsApi = {
-  (
-    token: TokenRef,
-    options?: ReplayEventsOptions,
-  ): Promise<ReplayEventSubscription>;
-  merge(streams: readonly ReplayEventSubscription[]): MergedReplayEventStream;
-};
-
-export type Solard = {
-  close(): void;
-  history: SolardHistoryApi;
-  events: SolardEventsApi;
-  claims: {
-    creatorFees: {
-      claim(
-        token: TokenRef,
-        wallet: WalletRef,
-        options?: ClaimCreatorRewardsOptions,
-      ): Promise<CreatorRewardClaimResult>;
-      status(
-        id: string,
-      ): ReturnType<
-        ReturnType<typeof createCoreSolard>["claims"]["creatorFees"]["status"]
-      >;
-    };
-  };
-  distributions: {
-    plan(
-      options: CumulativeDistributionInput,
-    ): Promise<CumulativeDistributionPlan>;
-    execute(
-      options: CumulativeDistributionExecuteOptions,
-    ): Promise<CumulativeDistributionState>;
-    status(id: string): CumulativeDistributionState | null;
-  };
-  createWallet: ReturnType<typeof createCoreSolard>["createWallet"];
-  createVanityWallet: ReturnType<typeof createCoreSolard>["createVanityWallet"];
-  importWallet: ReturnType<typeof createCoreSolard>["importWallet"];
-  listWallets: ReturnType<typeof createCoreSolard>["listWallets"];
-  walletAddress(wallet: WalletRef): string;
-  exportWalletPrivateKey(
-    wallet: WalletRef,
-    format?: WalletPrivateKeyFormat,
-  ): WalletPrivateKeyExport;
-  addToken: ReturnType<typeof createCoreSolard>["addToken"];
-  resolveToken: ReturnType<typeof createCoreSolard>["resolveToken"];
-  tokenAccounts: ReturnType<typeof createCoreSolard>["tokenAccounts"];
-  snapshotHolders(
-    token: TokenRef,
-    options?: Omit<TokenHolderSnapshotOptions, "token">,
-  ): Promise<TokenHolderSnapshot>;
-  walletBalances: ReturnType<typeof createCoreSolard>["walletBalances"];
-  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"];
-};
-
-export function createSolard(options: SolardOptions = {}): Solard {
-  const core = createCoreSolard(options);
-  const history: SolardHistoryApi = Object.freeze({
-    replay: (token, replayOptions) => core.history.replay(token, replayOptions),
-    market: (token, marketOptions) => core.history.market(token, marketOptions),
-    merge: core.history.merge,
-  });
-  const events = Object.assign(
-    (token: TokenRef, eventOptions: ReplayEventsOptions = {}) =>
-      core.events(token, eventOptions),
-    { merge: core.events.merge },
-  ) as SolardEventsApi;
-  return Object.freeze({
-    close: core.close.bind(core),
-    history,
-    events: Object.freeze(events),
-    claims: Object.freeze({
-      creatorFees: Object.freeze({
-        claim: core.claims.creatorFees.claim,
-        status: core.claims.creatorFees.status,
-      }),
-    }),
-    distributions: Object.freeze({
-      plan: core.distributions.plan,
-      execute: core.distributions.execute,
-      status: core.distributions.status,
-    }),
-    createWallet: core.createWallet.bind(core),
-    createVanityWallet: core.createVanityWallet.bind(core),
-    importWallet: core.importWallet.bind(core),
-    listWallets: core.listWallets.bind(core),
-    walletAddress: core.walletAddress.bind(core),
-    exportWalletPrivateKey: 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),
-    samplePrice: core.samplePrice.bind(core),
-    buy: core.buy.bind(core),
-    sell: core.sell.bind(core),
-  });
-}
+import {
+  createTraderSolard as createCoreSolard,
+  type ClaimCreatorRewardsOptions,
+  type CreatorRewardClaimResult,
+  type CumulativeDistributionExecuteOptions,
+  type CumulativeDistributionInput,
+  type CumulativeDistributionPlan,
+  type CumulativeDistributionState,
+  type HumanAmount,
+  type MarketHistory,
+  type MarketHistoryOptions,
+  type MarketPrice,
+  type MergedReplayEventStream,
+  type ReplayEventSubscription,
+  type ReplayHistory,
+  type ReplayItem,
+  type ReplayOptions,
+  type ReplayEventsOptions,
+  type RecordConfirmedTradeInput,
+  type SendReceipt,
+  type TradeLandingPolicy,
+  type SenderId,
+  type SolardDecodedTransaction,
+  type SolardTransactionOptions,
+  type SolardPosition,
+  type SolardPositionQuery,
+  type SolardTrade,
+  type SolardTradeQuery,
+  type TokenHolderSnapshot,
+  type TokenHolderSnapshotOptions,
+  type TokenRef,
+  type WalletRef,
+  type WalletPrivateKeyExport,
+  type WalletPrivateKeyFormat,
+} from "@solard/core";
+
+export type SolardOptions = {
+  rpcUrl?: string;
+  dbPath?: string;
+  cacheTtlMs?: number;
+};
+
+export type SolardHistoryApi = {
+  replay(token: TokenRef, options?: ReplayOptions): Promise<ReplayHistory>;
+  market(
+    token: TokenRef,
+    options?: MarketHistoryOptions,
+  ): Promise<MarketHistory>;
+  merge(
+    histories: readonly (ReplayHistory | Iterable<ReplayItem>)[],
+  ): ReplayItem[];
+};
+
+export type SolardEventsApi = {
+  (
+    token: TokenRef,
+    options?: ReplayEventsOptions,
+  ): Promise<ReplayEventSubscription>;
+  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 = {
+  landing?: TradeLandingPolicy;
+  waitForConfirmation?: boolean;
+  priorityFee?: { cuLimit?: number; microLamports?: number };
+  via?: SenderId;
+  skipSimulation?: boolean;
+  skipPreflight?: boolean;
+};
+
+export type SolardTradeExecutionResult = {
+  attempts?: Array<{ executionId: number; signature: string; priorityMicroLamports: number }>;
+  executionId: number;
+  signature: string;
+  sender: string;
+  status: SendReceipt["status"];
+  slot: number | null;
+  error: string | null;
+  feeLamports?: number;
+  computeUnitsConsumed?: number;
+  /** Signed economic SOL delta excluding network fee and token-account rent. */
+  solPrincipalDeltaLamports?: bigint;
+  /** Signed target-token delta for the confirmed atomic route. */
+  targetTokenDeltaRaw?: bigint;
+  /** Confirmed transaction network fee. */
+  networkFeeLamports?: bigint;
+};
+
+export type Solard = {
+  close(): void;
+  history: SolardHistoryApi;
+  events: SolardEventsApi;
+  claims: {
+    creatorFees: {
+      claim(
+        token: TokenRef,
+        wallet: WalletRef,
+        options?: ClaimCreatorRewardsOptions,
+      ): Promise<CreatorRewardClaimResult>;
+      status(
+        id: string,
+      ): ReturnType<
+        ReturnType<typeof createCoreSolard>["claims"]["creatorFees"]["status"]
+      >;
+    };
+  };
+  distributions: {
+    plan(
+      options: CumulativeDistributionInput,
+    ): Promise<CumulativeDistributionPlan>;
+    execute(
+      options: CumulativeDistributionExecuteOptions,
+    ): Promise<CumulativeDistributionState>;
+    status(id: string): CumulativeDistributionState | null;
+  };
+  createWallet: ReturnType<typeof createCoreSolard>["createWallet"];
+  createVanityWallet: ReturnType<typeof createCoreSolard>["createVanityWallet"];
+  importWallet: ReturnType<typeof createCoreSolard>["importWallet"];
+  listWallets: ReturnType<typeof createCoreSolard>["listWallets"];
+  walletAddress(wallet: WalletRef): string;
+  exportPrivateKey(
+    wallet: WalletRef,
+    format?: WalletPrivateKeyFormat,
+  ): WalletPrivateKeyExport;
+  addToken: ReturnType<typeof createCoreSolard>["addToken"];
+  resolveToken: ReturnType<typeof createCoreSolard>["resolveToken"];
+  tokenAccounts: ReturnType<typeof createCoreSolard>["tokenAccounts"];
+  snapshotHolders(
+    token: TokenRef,
+    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(
+    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;
+}
+
+
+async function executeTrade(
+  core: ReturnType<typeof createCoreSolard>,
+  side: "buy" | "sell",
+  input: SolardBuyInput | SolardSellInput,
+  options: SolardTradeExecutionOptions = {},
+): Promise<SolardTradeExecutionResult> {
+  const { submission, receipt, attempts } = await core.executeTradePlan(input.wallet, async () => {
+    const composer = core.tx(input.wallet).priorityFee(options.priorityFee ?? {});
+    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 });
+    }
+    return await composer.build();
+  }, options.via ?? "rpc", side, options);
+  const confirmedTrade =
+    receipt.status === "confirmed"
+      ? (
+          await core.trades({
+            wallet: input.wallet,
+            token: input.token,
+            side,
+            status: "confirmed",
+            limit: 32,
+          })
+        ).find((trade) => trade.signature === receipt.signature) ?? null
+      : null;
+  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,
+    attempts,
+    ...(confirmedTrade?.solDeltaLamports != null
+      ? { solPrincipalDeltaLamports: confirmedTrade.solDeltaLamports }
+      : {}),
+    ...(confirmedTrade?.tokenDeltaRaw != null
+      ? { targetTokenDeltaRaw: confirmedTrade.tokenDeltaRaw }
+      : {}),
+    ...(confirmedTrade?.networkFeeLamports != null
+      ? { networkFeeLamports: confirmedTrade.networkFeeLamports }
+      : {}),
+  };
+}
+
+export function createSolard(options: SolardOptions = {}): Solard {
+  const core = createCoreSolard(options);
+  const history: SolardHistoryApi = Object.freeze({
+    replay: (token, replayOptions) => core.history.replay(token, replayOptions),
+    market: (token, marketOptions) => core.history.market(token, marketOptions),
+    merge: core.history.merge,
+  });
+  const events = Object.assign(
+    (token: TokenRef, eventOptions: ReplayEventsOptions = {}) =>
+      core.events(token, eventOptions),
+    { merge: core.events.merge },
+  ) as SolardEventsApi;
+  return Object.freeze({
+    close: core.close.bind(core),
+    history,
+    events: Object.freeze(events),
+    claims: Object.freeze({
+      creatorFees: Object.freeze({
+        claim: core.claims.creatorFees.claim,
+        status: core.claims.creatorFees.status,
+      }),
+    }),
+    distributions: Object.freeze({
+      plan: core.distributions.plan,
+      execute: core.distributions.execute,
+      status: core.distributions.status,
+    }),
+    createWallet: core.createWallet.bind(core),
+    createVanityWallet: core.createVanityWallet.bind(core),
+    importWallet: core.importWallet.bind(core),
+    listWallets: core.listWallets.bind(core),
+    walletAddress: core.walletAddress.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: (input, executionOptions) =>
+      executeTrade(core, "buy", input, executionOptions),
+    sell: (input, executionOptions) =>
+      executeTrade(core, "sell", input, executionOptions),
+  });
+}

package/src/default.ts

@@ -1,16 +1,16 @@
+import { getSolUsdPrice } from "@solard/core";
 import {
-  getSolUsdPrice,
+  listenTrades,
   subscribeLaunches,
   subscribeMigrations,
-  subscribeTrades,
-} from "@solard/core";
+} 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;
-  subscribeTrades: typeof subscribeTrades;
 };
 
 let instance: Solard | undefined;
@@ -22,9 +22,9 @@ function client(): Solard {
 
 const operations = {
   getSolUsdPrice,
+  listenTrades,
   subscribeLaunches,
   subscribeMigrations,
-  subscribeTrades,
 } as const;
 
 const slrd = new Proxy({} as DefaultSolard, {

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,17 +31,20 @@ describe("sdk membrane", () => {
     expect(exportedNames(source)).toEqual({
       values: [
         "createSolard",
+        "default",
         "fetchTokenMetadata",
         "formatRaw",
         "getSolUsdPrice",
+        "isDefinitivePreSubmissionError",
         "publicTokenMetadataUrl",
         "subscribeLaunches",
         "subscribeMigrations",
-        "subscribeTrades",
+        "listenTrades",
         "sol",
         "tokenAmount",
       ].sort(),
       types: [
+        "TradeLandingPolicy",
         "ClaimCreatorRewardsOptions",
         "CreatorRewardClaimPayout",
         "CreatorRewardClaimResult",
@@ -65,6 +69,9 @@ describe("sdk membrane", () => {
         "MarketPrice",
         "SolUsdPrice",
         "SolUsdSource",
+        "SubscribeLaunchesOptions",
+        "SubscribeMigrationsOptions",
+        "ListenTradesOptions",
         "MergedReplayEventStream",
         "QuoteAsset",
         "ReplayCoverage",
@@ -75,15 +82,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",
@@ -139,10 +161,15 @@ describe("sdk membrane", () => {
     expect(defaultClient).toContain("instance ??= createSolard()");
     expect(defaultClient).toContain('if (key === "close")');
     expect(defaultClient).toContain("getSolUsdPrice");
-    expect(defaultClient).toContain("subscribeTrades");
+    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", () => {
@@ -151,6 +178,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

@@ -1,84 +1,112 @@
-export { default } from "./default.ts";
-export { createSolard } from "./client.ts";
+export { default } from "./default.ts";
+export { createSolard } from "./client.ts";
 export type {
-  Solard,
-  SolardEventsApi,
-  SolardHistoryApi,
-  SolardOptions,
-} from "./client.ts";
-
-export { formatRaw, sol, tokenAmount } from "@solard/core";
-
+  Solard,
+  SolardBuyInput,
+  SolardEventsApi,
+  SolardHistoryApi,
+  SolardOptions,
+  SolardSellInput,
+  SolardTradeExecutionOptions,
+  SolardTradeExecutionResult,
+} from "./client.ts";
+
+export {
+  formatRaw,
+  sol,
+  tokenAmount,
+  isDefinitivePreSubmissionError,
+} from "@solard/core";
+
 export type {
   ClaimCreatorRewardsOptions,
-  CreatorRewardClaimPayout,
-  CreatorRewardClaimResult,
-  CumulativeDistributionExecuteOptions,
-  CumulativeDistributionInput,
-  CumulativeDistributionPlan,
-  CumulativeDistributionRecipient,
-  CumulativeDistributionState,
-  CumulativeEntitlement,
-  HumanAmount,
-  MarketHistory,
-  MarketHistoryOptions,
-  MarketPrice,
-  MergedReplayEventStream,
-  QuoteAsset,
-  ReplayCoverage,
-  ReplayEventSubscription,
-  ReplayEventsOptions,
-  ReplayHistory,
-  ReplayItem,
-  ReplayOptions,
-  ReplayPayout,
-  ReplayTransaction,
-  SendReceipt,
-  SenderId,
-  SimulationResult,
-  SolardCanonicalEvent,
-  SolardClaimAttribution,
-  SolardClaimEvent,
-  TokenEventHistoryProgress,
-  TokenHolder,
-  ExcludedTokenHolder,
-  TokenHolderSnapshot,
-  TokenHolderSnapshotOptions,
-  TokenRef,
-  TokenRow,
-  WalletInfo,
-  WalletPrivateKeyExport,
-  WalletPrivateKeyFormat,
-  WalletRef,
-} from "@solard/core";
-
-export {
-  fetchTokenMetadata,
-  getSolUsdPrice,
-  publicTokenMetadataUrl,
-  subscribeLaunches,
-  subscribeMigrations,
-  subscribeTrades,
-} from "@solard/core";
-export type {
-  LaunchEvent,
-  LaunchSubscription,
-  LaunchVenue,
-  MigrationDestination,
-  MigrationEvent,
-  MigrationSubscription,
-  MigrationVenue,
-  GetSolUsdPriceOptions,
-  SolUsdPrice,
-  SolUsdSource,
-  TradeEvent,
-  TradeMarket,
-  TradeSide,
-  TradeSubscription,
-  TradeVenue,
-  FetchTokenMetadataOptions,
-  TokenMetadata,
-  TokenMetadataHint,
-  TokenMetadataKind,
-  TokenMetadataMode,
-} from "@solard/core";
+  TradeLandingPolicy,
+  CreatorRewardClaimPayout,
+  CreatorRewardClaimResult,
+  CumulativeDistributionExecuteOptions,
+  CumulativeDistributionInput,
+  CumulativeDistributionPlan,
+  CumulativeDistributionRecipient,
+  CumulativeDistributionState,
+  CumulativeEntitlement,
+  HumanAmount,
+  MarketHistory,
+  MarketHistoryOptions,
+  MarketPrice,
+  MergedReplayEventStream,
+  QuoteAsset,
+  ReplayCoverage,
+  ReplayEventSubscription,
+  ReplayEventsOptions,
+  ReplayHistory,
+  ReplayItem,
+  ReplayOptions,
+  ReplayPayout,
+  ReplayTransaction,
+  RecordConfirmedTradeInput,
+  SendReceipt,
+  SenderId,
+  SimulationResult,
+  SolardDecodedTransaction,
+  SolardPosition,
+  SolardPositionQuery,
+  SolardTransactionNativeBalance,
+  SolardTransactionOptions,
+  SolardTransactionTokenBalance,
+  SolardTrade,
+  SolardTradeQuery,
+  SolardTradeSide,
+  SolardTradeStatus,
+  SolardCanonicalEvent,
+  SolardClaimAttribution,
+  SolardClaimEvent,
+  TokenEventHistoryProgress,
+  TokenHolder,
+  ExcludedTokenHolder,
+  TokenHolderSnapshot,
+  TokenHolderSnapshotOptions,
+  TokenRef,
+  TokenRow,
+  WalletInfo,
+  WalletPrivateKeyExport,
+  WalletPrivateKeyFormat,
+  WalletRef,
+} from "@solard/core";
+
+export {
+  fetchTokenMetadata,
+  getSolUsdPrice,
+  publicTokenMetadataUrl,
+} from "@solard/core";
+export {
+  listenTrades,
+  subscribeLaunches,
+  subscribeMigrations,
+} from "./live.ts";
+export type {
+  ListenTradesOptions,
+  SubscribeLaunchesOptions,
+  SubscribeMigrationsOptions,
+  TradeListener,
+} from "./live.ts";
+export type {
+  LaunchEvent,
+  LaunchSubscription,
+  LaunchVenue,
+  MigrationDestination,
+  MigrationEvent,
+  MigrationSubscription,
+  MigrationVenue,
+  GetSolUsdPriceOptions,
+  SolUsdPrice,
+  SolUsdSource,
+  TradeEvent,
+  TradeMarket,
+  TradeSide,
+  TradeVenue,
+  FetchTokenMetadataOptions,
+  TokenMetadata,
+  TokenMetadataHint,
+  TokenMetadataKind,
+  TokenMetadataMode,
+} from "@solard/core";

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",
+      () => {
+        finish();
+        try {
+          socket?.close(1000);
+        } catch {}
+      },
+      { 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.executeTradePlan(");
+    expect(core).toContain("async settleSubmission(");
+    expect(core).toContain("submission.plan.lastValidBlockHeight");
+  });
+});