@solard/sdk 0.2.6 → 0.2.8

package/src/browser/pump.ts

@@ -0,0 +1,230 @@
+import {
+  ComputeBudgetProgram,
+  PublicKey,
+  TransactionMessage,
+  VersionedTransaction,
+  type Connection,
+  type TransactionInstruction,
+} from "@solana/web3.js";
+
+import { readMint } from "@solard/core/chain/state.ts";
+import { rawAmount } from "@solard/core/core/amounts.ts";
+import type { TokenRow } from "@solard/core/db/schema.ts";
+import { PumpCurveVenue } from "@solard/core/venues/pump/pump-curve-venue.ts";
+import { PumpSwapVenue } from "@solard/core/venues/pump/pumpswap-venue.ts";
+import { VenueRegistry } from "@solard/core/venues/route-resolver.ts";
+
+import type { BrowserTradeBuild } from "./types.ts";
+
+const PACKET_LIMIT = 1232;
+
+function tokenShell(args: {
+  mint: string;
+  decimals: number;
+  baseTokenProgram: string;
+}): TokenRow {
+  const now = Date.now();
+  return {
+    id: 0,
+    mint: args.mint,
+    name: null,
+    symbol: null,
+    decimals: args.decimals,
+    createKind: "unknown",
+    creator: null,
+    quoteMint: null,
+    quoteTokenProgram: null,
+    baseTokenProgram: args.baseTokenProgram,
+    bondingCurve: null,
+    pool: null,
+    sharingConfig: null,
+    venueHint: "unknown",
+    metadataJson: null,
+    refreshedAtMs: null,
+    createdAtMs: now,
+    updatedAtMs: now,
+  } as TokenRow;
+}
+
+async function resolvePumpToken(
+  connection: Connection,
+  mint: PublicKey,
+): Promise<{ registry: VenueRegistry; token: TokenRow }> {
+  const mintInfo = await readMint(connection, mint);
+  const registry = new VenueRegistry()
+    .register(new PumpCurveVenue())
+    .register(new PumpSwapVenue());
+  const shell = tokenShell({
+    mint: mint.toBase58(),
+    decimals: mintInfo.decimals,
+    baseTokenProgram: mintInfo.tokenProgram.toBase58(),
+  });
+  const inspected = await registry.inspect(connection, mint);
+  if (!inspected) {
+    throw new Error(
+      `Mint ${mint.toBase58()} is not a supported Pump/PumpSwap token.`,
+    );
+  }
+  return { registry, token: { ...shell, ...inspected } as TokenRow };
+}
+
+function priorityInstructions(options: {
+  cuLimit?: number;
+  priorityMicroLamports?: number;
+}) {
+  const out = [];
+  if (options.cuLimit != null) {
+    out.push(
+      ComputeBudgetProgram.setComputeUnitLimit({
+        units: Math.max(1, Math.trunc(options.cuLimit)),
+      }),
+    );
+  }
+  if (options.priorityMicroLamports != null) {
+    out.push(
+      ComputeBudgetProgram.setComputeUnitPrice({
+        microLamports: Math.max(0, Math.trunc(options.priorityMicroLamports)),
+      }),
+    );
+  }
+  return out;
+}
+
+async function compile(args: {
+  connection: Connection;
+  user: PublicKey;
+  instructions: TransactionInstruction[];
+  side: "buy" | "sell";
+  venue: string;
+  mint: PublicKey;
+  inputRaw: bigint;
+  expectedOutputRaw: bigint;
+  minimumOutputRaw: bigint;
+  quoteMint: PublicKey;
+  quoteDecimals: number;
+  cuLimit?: number;
+  priorityMicroLamports?: number;
+}): Promise<BrowserTradeBuild> {
+  const latest = await args.connection.getLatestBlockhash("confirmed");
+  const message = new TransactionMessage({
+    payerKey: args.user,
+    recentBlockhash: latest.blockhash,
+    instructions: [...priorityInstructions(args), ...args.instructions],
+  }).compileToV0Message();
+  const transaction = new VersionedTransaction(message);
+  const serializedSize = transaction.serialize().length;
+  if (serializedSize > PACKET_LIMIT) {
+    throw new Error(
+      `Local ${args.venue} ${args.side} transaction is ${serializedSize} bytes; ` +
+        `Solana packet limit is ${PACKET_LIMIT}. Configure browser lookup tables before sending.`,
+    );
+  }
+  return {
+    transaction,
+    side: args.side,
+    venue: args.venue,
+    mint: args.mint.toBase58(),
+    inputRaw: args.inputRaw,
+    expectedOutputRaw: args.expectedOutputRaw,
+    minimumOutputRaw: args.minimumOutputRaw,
+    quoteMint: args.quoteMint.toBase58(),
+    quoteDecimals: args.quoteDecimals,
+    blockhash: latest.blockhash,
+    lastValidBlockHeight: latest.lastValidBlockHeight,
+    serializedSize,
+  };
+}
+
+export async function buildLocalPumpBuy(args: {
+  connection: Connection;
+  user: PublicKey;
+  mint: string | PublicKey;
+  quoteInRaw: bigint;
+  slippageBps?: number;
+  cuLimit?: number;
+  priorityMicroLamports?: number;
+}): Promise<BrowserTradeBuild> {
+  const mint =
+    args.mint instanceof PublicKey ? args.mint : new PublicKey(args.mint);
+  const { registry, token } = await resolvePumpToken(args.connection, mint);
+  const { plugin, market } = await registry.resolve(
+    args.connection,
+    token,
+    args.user,
+  );
+  if (market.quoteAsset.kind !== "native-sol") {
+    throw new Error(
+      `Pump token ${mint.toBase58()} is quoted in ${market.quoteAsset.mint.toBase58()}, not native SOL.`,
+    );
+  }
+  const ctx = { connection: args.connection, token, user: args.user };
+  const quote = await plugin.quoteBuy(
+    ctx,
+    market,
+    rawAmount(args.quoteInRaw, market.quoteAsset),
+    args.slippageBps ?? 1_500,
+  );
+  const built = await plugin.buildBuy(ctx, market, quote);
+  return await compile({
+    connection: args.connection,
+    user: args.user,
+    instructions: built.instructions,
+    side: "buy",
+    venue: market.venue,
+    mint,
+    inputRaw: quote.inputRaw,
+    expectedOutputRaw: quote.expectedOutputRaw,
+    minimumOutputRaw: quote.minimumOutputRaw,
+    quoteMint: market.quoteAsset.mint,
+    quoteDecimals: market.quoteAsset.decimals,
+    cuLimit: args.cuLimit ?? 350_000,
+    priorityMicroLamports: args.priorityMicroLamports ?? 0,
+  });
+}
+
+export async function buildLocalPumpSell(args: {
+  connection: Connection;
+  user: PublicKey;
+  mint: string | PublicKey;
+  baseInRaw: bigint;
+  slippageBps?: number;
+  cuLimit?: number;
+  priorityMicroLamports?: number;
+}): Promise<BrowserTradeBuild> {
+  const mint =
+    args.mint instanceof PublicKey ? args.mint : new PublicKey(args.mint);
+  const { registry, token } = await resolvePumpToken(args.connection, mint);
+  const { plugin, market } = await registry.resolve(
+    args.connection,
+    token,
+    args.user,
+  );
+  if (market.quoteAsset.kind !== "native-sol") {
+    throw new Error(
+      `Pump token ${mint.toBase58()} is quoted in ${market.quoteAsset.mint.toBase58()}, not native SOL.`,
+    );
+  }
+  const ctx = { connection: args.connection, token, user: args.user };
+  const quote = await plugin.quoteSell(
+    ctx,
+    market,
+    args.baseInRaw,
+    args.slippageBps ?? 1_500,
+  );
+  const built = await plugin.buildSell(ctx, market, quote);
+  return await compile({
+    connection: args.connection,
+    user: args.user,
+    instructions: built.instructions,
+    side: "sell",
+    venue: market.venue,
+    mint,
+    inputRaw: quote.inputRaw,
+    expectedOutputRaw: quote.expectedOutputRaw,
+    minimumOutputRaw: quote.minimumOutputRaw,
+    quoteMint: market.quoteAsset.mint,
+    quoteDecimals: market.quoteAsset.decimals,
+    cuLimit: args.cuLimit ?? 350_000,
+    priorityMicroLamports: args.priorityMicroLamports ?? 0,
+  });
+}

package/src/browser/storage.ts

@@ -0,0 +1,254 @@
+import { PublicKey } from "@solana/web3.js";
+
+import type {
+  BrowserContact,
+  BrowserStorageLike,
+  BrowserTokenAlias,
+} from "./types.ts";
+
+type StoredCollection<T> = {
+  version: 1;
+  rows: T[];
+};
+
+function cleanAlias(value: string, kind: string): string {
+  const alias = value.trim().replace(/^@/, "");
+  if (!alias) throw new Error(`${kind} alias is required.`);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(alias)) {
+    throw new Error(
+      `${kind} alias must be 1..64 characters using letters, numbers, dot, underscore, or hyphen.`,
+    );
+  }
+  return alias;
+}
+
+function canonicalAddress(value: string): string {
+  try {
+    return new PublicKey(value.trim()).toBase58();
+  } catch {
+    throw new Error(`Invalid Solana address: ${value}`);
+  }
+}
+
+function sameName(left: string, right: string): boolean {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+export class MemoryBrowserStorage implements BrowserStorageLike {
+  private readonly values = new Map<string, string>();
+
+  get length(): number {
+    return this.values.size;
+  }
+
+  clear(): void {
+    this.values.clear();
+  }
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  key(index: number): string | null {
+    return [...this.values.keys()][index] ?? null;
+  }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+}
+
+export function defaultBrowserStorage(): BrowserStorageLike {
+  const storage = globalThis.localStorage;
+  if (!storage) {
+    throw new Error(
+      "localStorage is unavailable. Pass a BrowserStorageLike adapter explicitly.",
+    );
+  }
+  return storage;
+}
+
+export class BrowserSolardStore {
+  constructor(
+    readonly storage: BrowserStorageLike = defaultBrowserStorage(),
+    readonly namespace = "solard:browser:v1",
+  ) {}
+
+  private key(name: string): string {
+    return `${this.namespace}:${name}`;
+  }
+
+  private readCollection<T>(name: string): StoredCollection<T> {
+    const raw = this.storage.getItem(this.key(name));
+    if (!raw) return { version: 1, rows: [] };
+
+    const parsed = JSON.parse(raw) as Partial<StoredCollection<T>>;
+    if (!Array.isArray(parsed.rows)) {
+      throw new Error(`Invalid browser storage collection: ${name}`);
+    }
+    return { version: 1, rows: parsed.rows };
+  }
+
+  private writeCollection<T>(name: string, rows: T[]): void {
+    this.storage.setItem(
+      this.key(name),
+      JSON.stringify({ version: 1, rows } satisfies StoredCollection<T>),
+    );
+  }
+
+  listContacts(): BrowserContact[] {
+    return this.readCollection<BrowserContact>("contacts")
+      .rows.slice()
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  addContact(
+    nameInput: string,
+    addressInput: string,
+    options: { overwrite?: boolean } = {},
+  ): BrowserContact {
+    const name = cleanAlias(nameInput, "Contact");
+    const address = canonicalAddress(addressInput);
+    const rows = this.listContacts();
+    const byName = rows.find((row) => sameName(row.name, name));
+    const byAddress = rows.find((row) => row.address === address);
+
+    if (byAddress && (!byName || !sameName(byAddress.name, byName.name))) {
+      throw new Error(
+        `${address} is already saved as contact @${byAddress.name}.`,
+      );
+    }
+
+    if (byName) {
+      if (byName.address === address) return byName;
+      if (!options.overwrite) {
+        throw new Error(
+          `Contact @${byName.name} already points to ${byName.address}.`,
+        );
+      }
+      byName.address = address;
+      byName.updatedAtMs = Date.now();
+      this.writeCollection("contacts", rows);
+      return { ...byName };
+    }
+
+    const now = Date.now();
+    const row: BrowserContact = {
+      name,
+      address,
+      createdAtMs: now,
+      updatedAtMs: now,
+    };
+    rows.push(row);
+    this.writeCollection("contacts", rows);
+    return { ...row };
+  }
+
+  findContact(ref: string): BrowserContact | null {
+    const value = ref.trim().replace(/^@/, "");
+    return (
+      this.listContacts().find((row) => sameName(row.name, value)) ??
+      this.listContacts().find((row) => row.address === value) ??
+      null
+    );
+  }
+
+  removeContact(ref: string): BrowserContact {
+    const value = ref.trim().replace(/^@/, "");
+    const rows = this.listContacts();
+    const index = rows.findIndex(
+      (row) => sameName(row.name, value) || row.address === value,
+    );
+    if (index < 0) throw new Error(`Unknown browser contact: ${ref}`);
+    const [removed] = rows.splice(index, 1);
+    this.writeCollection("contacts", rows);
+    return { ...removed! };
+  }
+
+  listTokenAliases(): BrowserTokenAlias[] {
+    return this.readCollection<BrowserTokenAlias>("tokens")
+      .rows.slice()
+      .sort((a, b) => a.alias.localeCompare(b.alias));
+  }
+
+  registerToken(
+    aliasInput: string,
+    mintInput: string,
+    options: { overwrite?: boolean } = {},
+  ): BrowserTokenAlias {
+    const alias = cleanAlias(aliasInput.replace(/^\$/, ""), "Token");
+    const mint = canonicalAddress(mintInput);
+    const rows = this.listTokenAliases();
+    const existing = rows.find((row) => sameName(row.alias, alias));
+
+    if (existing) {
+      if (existing.mint === mint) return existing;
+      if (!options.overwrite) {
+        throw new Error(
+          `Token alias ${alias} already points to ${existing.mint}.`,
+        );
+      }
+      existing.mint = mint;
+      existing.updatedAtMs = Date.now();
+      this.writeCollection("tokens", rows);
+      return { ...existing };
+    }
+
+    const now = Date.now();
+    const row: BrowserTokenAlias = {
+      alias,
+      mint,
+      createdAtMs: now,
+      updatedAtMs: now,
+    };
+    rows.push(row);
+    this.writeCollection("tokens", rows);
+    return { ...row };
+  }
+
+  resolveToken(ref: string): string {
+    const value = ref.trim().replace(/^\$/, "");
+    try {
+      return new PublicKey(value).toBase58();
+    } catch {
+      // Alias resolution below.
+    }
+
+    const lowered = value.toLowerCase();
+    const accepted =
+      lowered === "slrd" ? new Set(["slrd", "solard"]) : new Set([lowered]);
+
+    const row = this.listTokenAliases().find((item) =>
+      accepted.has(item.alias.toLowerCase()),
+    );
+    if (!row) {
+      throw new Error(
+        `Unknown browser token alias "${ref}". Register it with tokens.register(alias, mint) or pass a mint address.`,
+      );
+    }
+    return row.mint;
+  }
+
+  setSetting<T>(name: string, value: T): void {
+    this.storage.setItem(this.key(`setting:${name}`), JSON.stringify(value));
+  }
+
+  getSetting<T>(name: string, fallback: T): T {
+    const raw = this.storage.getItem(this.key(`setting:${name}`));
+    return raw == null ? fallback : (JSON.parse(raw) as T);
+  }
+
+  removeSetting(name: string): void {
+    this.storage.removeItem(this.key(`setting:${name}`));
+  }
+
+  resolveDestination(ref: string): string {
+    const contact = this.findContact(ref);
+    if (contact) return contact.address;
+    return canonicalAddress(ref);
+  }
+}

package/src/browser/types.ts

@@ -0,0 +1,99 @@
+import type {
+  PublicKey,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+
+export interface BrowserWalletSigner {
+  publicKey: PublicKey | null;
+  connect?: () => Promise<unknown>;
+  disconnect?: () => Promise<unknown>;
+  signTransaction<T extends Transaction | VersionedTransaction>(
+    transaction: T,
+  ): Promise<T>;
+  signAllTransactions?<T extends Transaction | VersionedTransaction>(
+    transactions: T[],
+  ): Promise<T[]>;
+}
+
+export interface BrowserStorageLike {
+  readonly length: number;
+  clear(): void;
+  getItem(key: string): string | null;
+  key(index: number): string | null;
+  removeItem(key: string): void;
+  setItem(key: string, value: string): void;
+}
+
+export type BrowserContact = {
+  name: string;
+  address: string;
+  createdAtMs: number;
+  updatedAtMs: number;
+};
+
+export type BrowserTokenAlias = {
+  alias: string;
+  mint: string;
+  createdAtMs: number;
+  updatedAtMs: number;
+};
+
+export type BrowserTokenBalance = {
+  mint: string;
+  amountRaw: bigint;
+  amountUi: string;
+  decimals: number;
+  program: "spl-token" | "token-2022";
+  label: string;
+  tokenAccounts: string[];
+};
+
+export type BrowserPortfolio = {
+  address: string;
+  solLamports: bigint;
+  tokenBalances: BrowserTokenBalance[];
+};
+
+export type BrowserBroadcastResult = {
+  signature: string;
+  confirmed: boolean;
+  blockhash: string;
+  lastValidBlockHeight: number;
+};
+
+export type BrowserTradeSide = "buy" | "sell";
+
+export type BrowserTradeBuild = {
+  transaction: VersionedTransaction;
+  side: BrowserTradeSide;
+  venue: string;
+  mint: string;
+  inputRaw: bigint;
+  expectedOutputRaw: bigint;
+  minimumOutputRaw: bigint;
+  quoteMint: string;
+  quoteDecimals: number;
+  blockhash: string;
+  lastValidBlockHeight: number;
+  serializedSize: number;
+};
+
+export type BrowserTradeResult = BrowserBroadcastResult & {
+  side: BrowserTradeSide;
+  venue: string;
+  mint: string;
+  inputRaw: bigint;
+  expectedOutputRaw: bigint;
+  minimumOutputRaw: bigint;
+};
+
+export type BrowserSolardOptions = {
+  rpcUrl: string;
+  wallet?: BrowserWalletSigner | null;
+  storage?: BrowserStorageLike;
+  storageNamespace?: string;
+  commitment?: "processed" | "confirmed" | "finalized";
+  rpcMaxRps?: number;
+  fetch?: typeof globalThis.fetch;
+};