@solard/sdk 0.2.29 → 0.2.31

package/README.md

@@ -3,11 +3,26 @@
 Public Solard SDK. It intentionally contains no duplicate business logic; it re-exports the supported `@solard/core` API.
 
 ```ts
-import { Solard, sol } from "@solard/sdk";
+import { createSolard } from "@solard/sdk";
 
-const slrd = new Solard();
-const wallet = slrd.createWallet("trader-1");
-const wallets = slrd.listWallets();
-
-await slrd.tx(wallet.address).transferSol("RECIPIENT", sol("0.01")).send();
+const slrd = createSolard();
+await slrd.addToken(mint, undefined, { venueHint: "pumpswap", pool: poolAddress });
+const buy = await slrd.buy(
+  { wallet: "trader-1", token: mint, amount: { sol: 0.001 }, slippageBps: 500 },
+  { intentKey: "example:buy:1", priorityFee: { cuLimit: 600_000, microLamports: 200_000 } },
+);
+if (buy.status === "confirmed") {
+  console.log(buy.solPrincipalDeltaLamports, buy.networkFeeLamports, buy.targetTokenDeltaRaw);
+}
+// Sell through the same atomic quote-token -> SOL route.
+// await slrd.sell({ wallet: "trader-1", token: mint, amount: "all", slippageBps: 500 });
 ```
+
+The trader preset supports Pump/PumpSwap, Meteora DBC and DAMM v2. Custom quote
+routes require a supported SOL market for the quote token and suitable lookup
+tables when needed. Composer routes fall back to Jupiter instructions. Unavailable
+converted prices are null. `unresolved` means reconcile with `resumeTrade(intentKey)`
+before another trade. Buy accepts `minOutputRaw`; sell accepts `minOutputLamports`.
+Both use confirmed/failed/unresolved results with phase, code, attempts and accounting.
+`quote`, `curveLiquidity`, `maxSendableSol`, `transferToken` and `exitWallet` share the
+core implementation. Raydium AMM/CPMM execution does not supply live pool prices.

package/package.json

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

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

@@ -1,60 +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 });
-  }
-});
+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("unresolved");
+    expect(sell.status).toBe("unresolved");
+    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

@@ -17,8 +17,11 @@ import {
   type ReplayOptions,
   type ReplayEventsOptions,
   type RecordConfirmedTradeInput,
-  type SendReceipt,
-  type TradeLandingPolicy,
+  type SendReceipt,
+  type TradeLandingPolicy,
+  type TradeResult,
+  type TradeExecutionOptions,
+  type LivePoolReserves,
   type SenderId,
   type SolardDecodedTransaction,
   type SolardTransactionOptions,
@@ -35,7 +38,8 @@ import {
 } from "@solard/core";
 
 export type SolardOptions = {
-  rpcUrl?: string;
+  rpcUrl?: string;
+  rpcUrls?: readonly string[];
   dbPath?: string;
   cacheTtlMs?: number;
 };
@@ -59,48 +63,50 @@ export type SolardEventsApi = {
   merge(streams: readonly ReplayEventSubscription[]): MergedReplayEventStream;
 };
 
-export type SolardBuyInput = {
+export type SolardBuyInput = {
+  reserves?: LivePoolReserves;
+  maxPriceSol?: string | number;
   wallet: WalletRef;
   token: TokenRef;
   amount: HumanAmount | string | number;
   slippageBps?: number;
+  minOutputRaw?: bigint | string;
 };
 
-export type SolardSellInput = {
+export type SolardSellInput = {
+  closeTokenAccount?: boolean;
+  reserves?: LivePoolReserves;
+  minPriceSol?: string | number;
   wallet: WalletRef;
   token: TokenRef;
   amount?: "all" | { bps: number };
   slippageBps?: number;
+  minOutputLamports?: bigint | string;
 };
 
-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 SolardTradeExecutionOptions = TradeExecutionOptions;
 
-export type Solard = {
+export type SolardTradeExecutionResult = TradeResult;
+export type Solard = {
+  resolveCurrentMarket: ReturnType<typeof createCoreSolard>["resolveCurrentMarket"];
+  getClaimableCreatorFees: ReturnType<typeof createCoreSolard>["getClaimableCreatorFees"];
+  claimAllCreatorFees: ReturnType<typeof createCoreSolard>["claimAllCreatorFees"];
+  walletLedger: ReturnType<typeof createCoreSolard>["walletLedger"];
+  historicalTape: ReturnType<typeof createCoreSolard>["historicalTape"];
+  getSupportedPumpPairs: ReturnType<typeof createCoreSolard>["getSupportedPumpPairs"];
+  listVanityMints: ReturnType<typeof createCoreSolard>["listVanityMints"];
+  releaseVanityMint: ReturnType<typeof createCoreSolard>["releaseVanityMint"];
+  closeEmptyTokenAccounts: ReturnType<typeof createCoreSolard>["closeEmptyTokenAccounts"];
+  prepareTokenDeployment: ReturnType<typeof createCoreSolard>["prepareTokenDeployment"];
+  deployToken: ReturnType<typeof createCoreSolard>["deployToken"];
+  warmBlockhash: ReturnType<typeof createCoreSolard>["warmBlockhash"];
+  curveLiquidity: ReturnType<typeof createCoreSolard>["curveLiquidity"];
+  maxSendableSol: ReturnType<typeof createCoreSolard>["maxSendableSol"];
+  transferToken: ReturnType<typeof createCoreSolard>["transferToken"];
+  exitWallet: ReturnType<typeof createCoreSolard>["exitWallet"];
+  resumeTrade(intentKey: string): Promise<SolardTradeExecutionResult>;
+  reconcile(intentKey: string): Promise<SolardTradeExecutionResult>;
+  quote: ReturnType<typeof createCoreSolard>["quote"];
   close(): void;
   history: SolardHistoryApi;
   events: SolardEventsApi;
@@ -183,49 +189,13 @@ async function executeTrade(
   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 }
-      : {}),
-  };
+  if (side === "buy") {
+    const buy = input as SolardBuyInput;
+    return await core.buy(buy.token, buy.wallet, tradeAmount(buy.amount), { ...options, slippageBps: buy.slippageBps, minOutputRaw: buy.minOutputRaw, maxPriceSol: buy.maxPriceSol, reserves: buy.reserves });
+  }
+  const sell = input as SolardSellInput;
+  return await core.sell(sell.token, sell.wallet, { ...options, bps: sellBps(sell.amount), slippageBps: sell.slippageBps, minOutputLamports: sell.minOutputLamports, minPriceSol: sell.minPriceSol, reserves: sell.reserves, closeTokenAccount: sell.closeTokenAccount });
+
 }
 
 export function createSolard(options: SolardOptions = {}): Solard {
@@ -240,7 +210,26 @@ export function createSolard(options: SolardOptions = {}): Solard {
       core.events(token, eventOptions),
     { merge: core.events.merge },
   ) as SolardEventsApi;
-  return Object.freeze({
+  return Object.freeze({
+    resolveCurrentMarket: core.resolveCurrentMarket.bind(core),
+    getClaimableCreatorFees: core.getClaimableCreatorFees.bind(core),
+    claimAllCreatorFees: core.claimAllCreatorFees.bind(core),
+    walletLedger: core.walletLedger.bind(core),
+    historicalTape: core.historicalTape.bind(core),
+    getSupportedPumpPairs: core.getSupportedPumpPairs.bind(core),
+    listVanityMints: core.listVanityMints.bind(core),
+    releaseVanityMint: core.releaseVanityMint.bind(core),
+    closeEmptyTokenAccounts: core.closeEmptyTokenAccounts.bind(core),
+    prepareTokenDeployment: core.prepareTokenDeployment.bind(core),
+    deployToken: core.deployToken.bind(core),
+    warmBlockhash: core.warmBlockhash.bind(core),
+    curveLiquidity: core.curveLiquidity.bind(core),
+    maxSendableSol: core.maxSendableSol.bind(core),
+    transferToken: core.transferToken.bind(core),
+    exitWallet: core.exitWallet.bind(core),
+    resumeTrade: core.resumeTrade.bind(core),
+    reconcile: core.reconcile.bind(core),
+    quote: core.quote.bind(core),
     close: core.close.bind(core),
     history,
     events: Object.freeze(events),

package/src/default.ts

@@ -1,51 +1,51 @@
-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 {
-  instance ??= createSolard();
-  return instance;
-}
-
-const operations = {
-  getSolUsdPrice,
-  listenTrades,
-  subscribeLaunches,
-  subscribeMigrations,
-} as const;
-
-const slrd = new Proxy({} as DefaultSolard, {
-  get(_target, key) {
-    if (key === "close") {
-      return () => {
-        const current = instance;
-        instance = undefined;
-        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;
-  },
-  set() {
-    return false;
-  },
-});
-
-export default slrd;
+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 {
+  instance ??= createSolard();
+  return instance;
+}
+
+const operations = {
+  getSolUsdPrice,
+  listenTrades,
+  subscribeLaunches,
+  subscribeMigrations,
+} as const;
+
+const slrd = new Proxy({} as DefaultSolard, {
+  get(_target, key) {
+    if (key === "close") {
+      return () => {
+        const current = instance;
+        instance = undefined;
+        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;
+  },
+  set() {
+    return false;
+  },
+});
+
+export default slrd;