@solard/sdk 0.2.37 → 0.2.40

package/src/client.ts

@@ -43,9 +43,11 @@ import {
   type TradeListener,
 } from "./live.ts";
 
-export type SolardOptions = {
+export type SolardOptions = {
+  transactionVersion?: 0 | 1;
   rpcUrl?: string;
   rpcUrls?: readonly string[];
+  websocketUrls?: readonly string[];
   dbPath?: string;
   cacheTtlMs?: number;
 };
@@ -95,12 +97,25 @@ export type SolardSellInput = {
 export type SolardTradeExecutionOptions = TradeExecutionOptions;
 
 export type SolardTradeExecutionResult = TradeResult;
-export type Solard = {
+export type Solard = {
+  tx:ReturnType<typeof createCoreSolard>['tx'];
+  compileGroups:ReturnType<typeof createCoreSolard>['compileGroups'];
+  simulatePlan:ReturnType<typeof createCoreSolard>['simulatePlan'];
+  sendBatchPlans:ReturnType<typeof createCoreSolard>['sendBatchPlans'];
+  prepareFastTrade: ReturnType<typeof createCoreSolard>["prepareFastTrade"];
   listenTrades(
     options?: Omit<ListenTradesOptions, "tokens"> & {
       tokens?: readonly string[];
     },
   ): Promise<TradeListener>;
+  prepareUnsignedBuy: ReturnType<typeof createCoreSolard>["prepareUnsignedBuy"];
+  prepareUnsignedTokenDeployment: ReturnType<typeof createCoreSolard>["prepareUnsignedTokenDeployment"];
+  resolvePumpLaunchQuote: ReturnType<typeof createCoreSolard>["resolvePumpLaunchQuote"];
+  simulateUnsignedTokenDeployment: ReturnType<typeof createCoreSolard>["simulateUnsignedTokenDeployment"];
+  simulateUnsignedBuy: ReturnType<typeof createCoreSolard>["simulateUnsignedBuy"];
+  prepareUnsignedSell: ReturnType<typeof createCoreSolard>["prepareUnsignedSell"];
+  simulateUnsignedSell: ReturnType<typeof createCoreSolard>["simulateUnsignedSell"];
+  proposeUnsignedBuyLookupTable: ReturnType<typeof createCoreSolard>["proposeUnsignedBuyLookupTable"];
   resolveCurrentMarket: ReturnType<
     typeof createCoreSolard
   >["resolveCurrentMarket"];
@@ -268,7 +283,7 @@ async function executeTrade(
   });
 }
 
-export function createSolard(options: SolardOptions = {}): Solard {
+export function createSolard(options: SolardOptions = {}): Solard {
   const core = createCoreSolard(options);
   const history: SolardHistoryApi = Object.freeze({
     replay: (token, replayOptions) => core.history.replay(token, replayOptions),
@@ -280,19 +295,33 @@ export function createSolard(options: SolardOptions = {}): Solard {
       core.events(token, eventOptions),
     { merge: core.events.merge },
   ) as SolardEventsApi;
-  return Object.freeze({
+  return Object.freeze({
+    tx:core.tx.bind(core),
+    compileGroups:core.compileGroups.bind(core),
+    simulatePlan:core.simulatePlan.bind(core),
+    sendBatchPlans:core.sendBatchPlans.bind(core),
     listenTrades: (
       listenerOptions: Omit<ListenTradesOptions, "tokens"> & {
         tokens?: readonly string[];
       } = {},
     ) =>
       openTradeListener({
+        websocketUrls: listenerOptions.websocketUrls ?? options.websocketUrls,
         rpcUrls:
           options.rpcUrls ?? (options.rpcUrl ? [options.rpcUrl] : undefined),
         dbPath: options.dbPath,
         ...listenerOptions,
         tokens: listenerOptions.tokens ?? [],
       }),
+    prepareFastTrade: core.prepareFastTrade.bind(core),
+    prepareUnsignedBuy: core.prepareUnsignedBuy.bind(core),
+    prepareUnsignedTokenDeployment: core.prepareUnsignedTokenDeployment.bind(core),
+    resolvePumpLaunchQuote: core.resolvePumpLaunchQuote.bind(core),
+    simulateUnsignedTokenDeployment: core.simulateUnsignedTokenDeployment.bind(core),
+    simulateUnsignedBuy: core.simulateUnsignedBuy.bind(core),
+    prepareUnsignedSell: core.prepareUnsignedSell.bind(core),
+    simulateUnsignedSell: core.simulateUnsignedSell.bind(core),
+    proposeUnsignedBuyLookupTable: core.proposeUnsignedBuyLookupTable.bind(core),
     resolveCurrentMarket: core.resolveCurrentMarket.bind(core),
     getClaimableCreatorFees: core.getClaimableCreatorFees.bind(core),
     claimAllCreatorFees: core.claimAllCreatorFees.bind(core),

package/src/export-surface.test.ts

@@ -29,7 +29,10 @@ function exportedNames(value: string) {
 describe("sdk membrane", () => {
   test("has an exact curated root export surface", () => {
     expect(exportedNames(source)).toEqual({
-      values: [
+      values: [
+        "composeTransactionDrafts",
+        "observeSolardRpc",
+        "withSolardRpcContext",
         "normalizeValueBandPolicy",
         "planValueBandDecision",
         "valueBandThresholds",
@@ -54,7 +57,14 @@ describe("sdk membrane", () => {
         "sol",
         "tokenAmount",
       ].sort(),
-      types: [
+      types: [
+        "TransactionDraft",
+        "TransactionGroupInput",
+        "PlannedTransaction",
+        "SolardRpcObservation",
+        "SolardRpcContext",
+        "FeedRecoveryVerification",
+        "RecoverableTradeSubscription",
         "SellEconomics",
         "SupportedLaunchLabPair",
         "TradeListenerMigration",

package/src/index.ts

@@ -1,6 +1,8 @@
 export { default } from "./default.ts";
 export { createSolard } from "./client.ts";
-export { createTraderSolard } from "@solard/core";
+export {observeSolardRpc,withSolardRpcContext} from '@solard/core';
+export type {SolardRpcObservation,SolardRpcContext} from '@solard/core';
+export { createTraderSolard } from "@solard/core";
 export {
   normalizeValueBandPolicy,
   planValueBandDecision,
@@ -123,6 +125,8 @@ export {
 export type {
   ListenTradesOptions,
   LiveEndpointOptions,
+  FeedRecoveryVerification,
+  RecoverableTradeSubscription,
   SubscribeLaunchesOptions,
   SubscribeMigrationsOptions,
   TradeListener,
@@ -149,3 +153,5 @@ export type {
   TokenMetadataKind,
   TokenMetadataMode,
 } from "@solard/core";
+export {composeTransactionDrafts} from '@solard/core';
+export type {TransactionDraft,TransactionGroupInput,PlannedTransaction} from '@solard/core';

package/src/live-recovery.test.ts

@@ -0,0 +1,122 @@
+import { expect, spyOn, test } from "bun:test";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, NATIVE_MINT } from "@solana/spl-token";
+import * as core from "@solard/core";
+import { subscribeTrades } from "./live.ts";
+
+test("feed verification gates delivery, validates a snapshot, preserves deduplication and cancels queued recovery", async () => {
+  const originalSocket = globalThis.WebSocket;
+  globalThis.WebSocket = class extends EventTarget {
+    constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); }
+    send(text: string) { const value = JSON.parse(text);
+      if (value.method === "slotSubscribe") queueMicrotask(() => this.dispatchEvent(
+        new MessageEvent("message", { data: JSON.stringify({ id: value.id, result: 1 }) })));
+    }
+    close() {}
+  } as any;
+  const fetchMock = spyOn(globalThis, "fetch").mockImplementation((async (_url, init) => {
+    const method = JSON.parse(String(init?.body)).method;
+    return Response.json({ result: method === "getGenesisHash"
+      ? "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"
+      : { context: { slot: 42 }, value: 0 } });
+  }) as typeof fetch);
+  const mint = Keypair.generate().publicKey, pool = Keypair.generate().publicKey;
+  const poolProgram = Keypair.generate().publicKey;
+  let snapshotValid = false, emitted = 0, reads = 0;
+  const accounts = spyOn(Connection.prototype, "getAccountInfo").mockImplementation(async address => {
+    reads++;
+    if (!snapshotValid) return null;
+    const data = Buffer.alloc(82);
+    if (address.equals(mint)) { data[44] = 6; data.writeBigUInt64LE(1_000_000_000n, 36); }
+    else { mint.toBuffer().copy(data); NATIVE_MINT.toBuffer().copy(data, 32); }
+    return { executable: false, lamports: 1, owner: address.equals(mint) ? TOKEN_PROGRAM_ID : poolProgram, data };
+  });
+  let emit!: (event: core.TradeEvent) => Promise<void>;
+  const trades = spyOn(core, "subscribeTrades").mockImplementation(async options => {
+    emit = options.onTrade as typeof emit;
+    const watched = new Set(options.tokens);
+    let settle!: () => void;
+    const closed = new Promise<void>(resolve => { settle = resolve; });
+    return {
+      addTokens: async values => { for (const value of typeof values === "string" ? [values] : values) watched.add(value); },
+      removeTokens: async values => { for (const value of typeof values === "string" ? [values] : values) watched.delete(value); },
+      hasToken: value => watched.has(value), listTokens: () => [...watched],
+      close: async () => { watched.clear(); settle(); }, closed,
+    };
+  });
+  let subscription: Awaited<ReturnType<typeof subscribeTrades>> | undefined;
+  let clock: ReturnType<typeof spyOn> | undefined;
+  const event = (signature: string, atMs = Date.now()) => ({
+    type: "trade", mint: mint.toBase58(), signature, venue: "pumpswap", pool: pool.toBase58(),
+    side: "buy", slot: 42, atMs, baseRaw: 1n, quoteRaw: 2n,
+    metadata: null, market: {
+      quoteMint: NATIVE_MINT.toBase58(), baseDecimals: 6, quoteDecimals: 9,
+      supplyRaw: 1_000_000_000n, supply: 1000,
+      baseReserveRaw: 1n, baseReserve: 0.000001,
+      quoteReserveRaw: 2n, quoteReserve: 0.000000002,
+      priceQuotePerToken: 0.002, marketCapQuote: 2,
+      priceSol: 0.002, marketCapSol: 2, solUsd: null,
+      solUsdSource: null, solUsdAtMs: null, priceUsd: null, marketCapUsd: null,
+    },
+  }) as core.TradeEvent;
+  const verify = async ({ connection, tokens, signal }: coreVerification) => {
+    expect(signal.aborted).toBe(false);
+    expect(tokens).toContain(mint.toBase58());
+    const [mintAccount, poolAccount] = await Promise.all([
+      connection.getAccountInfo(mint), connection.getAccountInfo(pool),
+    ]);
+    return !!mintAccount && !!poolAccount && mintAccount.owner.equals(TOKEN_PROGRAM_ID) &&
+      mintAccount.data[44] === 6 && mintAccount.data.readBigUInt64LE(36) > 0n &&
+      poolAccount.owner.equals(poolProgram) &&
+      new PublicKey(poolAccount.data.subarray(0, 32)).equals(mint) &&
+      new PublicKey(poolAccount.data.subarray(32, 64)).equals(NATIVE_MINT);
+  };
+  try {
+    // Environment-only/single-endpoint streams expose the same recovery API.
+    const oldEndpoint = process.env.RPC_ENDPOINT;
+    process.env.RPC_ENDPOINT = "https://recovery-only.example/";
+    try { subscription = await subscribeTrades({ tokens: [mint.toBase58()],
+      rpcUrls: [], healthCheckIntervalMs: 1000, onTrade: () => { emitted++; } }); }
+    finally { if (oldEndpoint === undefined) delete process.env.RPC_ENDPOINT; else process.env.RPC_ENDPOINT = oldEndpoint; }
+    expect(await subscription.verifyAndResume(verify)).toBe(false);
+    await emit(event("blocked")); expect(emitted).toBe(0);
+    snapshotValid = true;
+    expect(await subscription.verifyAndResume(verify)).toBe(true);
+    expect(reads).toBe(4);
+    await emit(event("accepted")); await emit(event("accepted"));
+    await emit(event("old", Date.now() - 31_000));
+    expect(emitted).toBe(1);
+    const future = Date.now() + 61_000;
+    clock = spyOn(Date, "now").mockReturnValue(future);
+    expect(subscription.feedVerified).toBe(false);
+    await emit(event("after-silence")); expect(emitted).toBe(1);
+    expect(await subscription.verifyAndResume(verify)).toBe(true);
+    await emit(event("resumed")); expect(emitted).toBe(2);
+    clock.mockRestore(); clock = undefined;
+    let finish!: (value: boolean) => void;
+    const verification = subscription.verifyAndResume(async () => await new Promise<boolean>(resolve => { finish = resolve; }));
+    while (!finish) await Bun.sleep(1);
+    const added = subscription.addTokens(Keypair.generate().publicKey.toBase58());
+    finish(true);
+    expect(await verification).toBe(false); await added;
+    expect(subscription.feedVerified).toBe(false);
+    let queuedRan = false;
+    let hangingStarted = false;
+    const hanging = subscription.verifyAndResume(async () => {
+      hangingStarted = true; return await new Promise<boolean>(() => {});
+    });
+    const hangingResult = hanging.then(value => ({ value, error: undefined as unknown }),
+      error => ({ value: false, error }));
+    while (!hangingStarted) await Bun.sleep(1);
+    await expect(subscription.verifyAndResume(async () => { queuedRan = true; return true; }, 5))
+      .rejects.toThrow("cancelled or timed out");
+    expect(queuedRan).toBe(false);
+    await subscription.close();
+    expect(((await hangingResult).error as Error).message).toContain("cancelled or timed out");
+    expect(subscription.feedVerified).toBe(false);
+  } finally {
+    clock?.mockRestore(); await subscription?.close();
+    trades.mockRestore(); accounts.mockRestore(); fetchMock.mockRestore(); globalThis.WebSocket = originalSocket;
+  }
+});
+type coreVerification = Parameters<import("./live.ts").FeedRecoveryVerification>[0];

package/src/live.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, spyOn, test } from "bun:test";
+const mockFetch = (implementation: (...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>) =>
+  spyOn(globalThis, "fetch").mockImplementation(implementation as typeof fetch);
 import { Connection } from "@solana/web3.js";
 import { mkdtempSync, rmSync } from "node:fs";
 import { join } from "node:path";
@@ -26,7 +28,7 @@ describe("sdk live endpoint", () => {
       redactRpcEndpoint(
         "https://mainnet.helius-rpc.com/?api-key=secret-value&foo=bar",
       ),
-    ).toBe("https://mainnet.helius-rpc.com/?api-key=<redacted>&foo=bar");
+    ).toBe("https://mainnet.helius-rpc.com/***");
   });
 });
 test("live endpoint selection requires readiness, sticks, and rotates after later failures", async () => {
@@ -57,7 +59,7 @@ test("pooled trade stream preserves dynamic watched tokens when it rotates and c
   const originalSocket = globalThis.WebSocket;
   let firstHealthy = true;
   let nextId = 0;
-  const registrations: Array<{ endpoint: string; token: string }> = [];
+  const registrations: Array<{ endpoint: string; ws: string; token: string }> = [];
   const first = "https://live-primary.example/";
   const second = "https://live-fallback.example/";
   const mint = "So11111111111111111111111111111111111111112";
@@ -66,18 +68,29 @@ test("pooled trade stream preserves dynamic watched tokens when it rotates and c
       super();
       queueMicrotask(() => this.dispatchEvent(new Event("open")));
     }
+    send(payload: string) {
+      const request = JSON.parse(payload) as { method?: string; id?: number };
+      if (request.method === "slotSubscribe") queueMicrotask(() =>
+        this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({
+          jsonrpc: "2.0", id: request.id, result: 42,
+        }) })));
+    }
     close() {}
   } as any;
-  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(
-    async (input) => {
+  const fetchMock = mockFetch(
+    async (input, init) => {
       if (String(input) === first && !firstHealthy)
         return new Response("", { status: 401 });
-      return new Response(JSON.stringify({ result: "ok" }));
+      const method = JSON.parse(String(init?.body)).method;
+      return new Response(JSON.stringify({ result: method === "getGenesisHash"
+        ? "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"
+        : { context: { slot: 50 }, value: 0 } }));
     },
   );
   const logsMock = spyOn(Connection.prototype, "onLogs").mockImplementation(
     function (token) {
-      registrations.push({ endpoint: this.rpcEndpoint, token: String(token) });
+      registrations.push({ endpoint: this.rpcEndpoint,
+        ws: (this as any)._rpcWsEndpoint, token: String(token) });
       return ++nextId;
     },
   );
@@ -102,11 +115,29 @@ test("pooled trade stream preserves dynamic watched tokens when it rotates and c
     )
       await Bun.sleep(25);
     expect(registrations).toEqual([
-      { endpoint: first, token: mint },
-      { endpoint: second, token: mint },
+      { endpoint: first, ws: "wss://live-primary.example/", token: mint },
+      { endpoint: second, ws: "wss://live-fallback.example/", token: mint },
     ]);
     expect(subscription.listTokens()).toEqual([mint]);
     expect(subscription.hasToken(mint)).toBe(true);
+    // A provider change must be explicitly reconciled by the application;
+    // a rejected snapshot cannot re-enable trading callbacks.
+    expect(subscription.feedVerified).toBe(false);
+    const rejected = await subscription.verifyAndResume(async ({tokens}) => {
+      expect(tokens).toEqual([mint]); return false;
+    });
+    expect(rejected).toBe(false);
+    expect(subscription.feedVerified).toBe(false);
+    const recovery = await subscription.verifyAndResume(async ({connection, tokens, signal}) => {
+      expect(connection.rpcEndpoint).toBe(second);
+      expect(tokens).toEqual([mint]);
+      expect(signal.aborted).toBe(false);
+      return true; // fixture represents successfully checked fresh pool/mint state
+    });
+    expect(recovery).toBe(true);
+    expect(subscription.feedVerified).toBe(true);
+    await expect(subscription.verifyAndResume(async () => new Promise<boolean>(() => {}), 5))
+      .rejects.toThrow("Feed verification cancelled or timed out");
     await subscription.close();
     await subscription.closed;
     expect(subscription.listTokens()).toEqual([]);
@@ -133,10 +164,22 @@ test("listenTrades refreshes migrated identities without changing the watched to
       super();
       queueMicrotask(() => this.dispatchEvent(new Event("open")));
     }
+    send(payload: string) {
+      const request = JSON.parse(payload) as { method?: string; id?: number };
+      if (request.method === "slotSubscribe") queueMicrotask(() =>
+        this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({
+          jsonrpc: "2.0", id: request.id, result: 42,
+        }) })));
+    }
     close() {}
   } as any;
-  const fetchMock = spyOn(globalThis, "fetch").mockImplementation(
-    async () => new Response(JSON.stringify({ result: "ok" })),
+  const fetchMock = mockFetch(
+    async (_input, init) => {
+      const method = JSON.parse(String(init?.body)).method;
+      return new Response(JSON.stringify({ result: method === "getGenesisHash"
+        ? "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"
+        : { context: { slot: 50 }, value: 0 } }));
+    },
   );
   let onMigration: any;
   let onTrade: any;