@nodiusxyz/solana-agent-kit 0.0.0-stage → 0.1.0

package/src/internal/journal.ts

@@ -0,0 +1,140 @@
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+export function fingerprint(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export function outcome(status: any): "confirmed" | "failed" | "unknown" {
+  if (status?.err != null) return "failed";
+  if (
+    status?.confirmationStatus === "confirmed" ||
+    status?.confirmationStatus === "finalized"
+  )
+    return "confirmed";
+  return "unknown";
+}
+export class Journal {
+  constructor(
+    readonly directory: string,
+    private readonly credential?: string,
+  ) {}
+  private encode(value: unknown): string {
+    const scrub = (v: any): any => {
+      const text = (s: string) =>
+        this.credential ? s.split(this.credential).join("[REDACTED]") : s;
+      if (typeof v === "string") return text(v);
+      if (Array.isArray(v)) return v.map(scrub);
+      if (v && typeof v === "object")
+        return Object.fromEntries(
+          Object.entries(v).map(([k, item]) => [text(k), scrub(item)]),
+        );
+      return v;
+    };
+    return JSON.stringify(scrub(value));
+  }
+  private async reserve(kind: string, key: string, value: unknown) {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const path = join(this.directory, kind + "-" + fingerprint(key) + ".json");
+    const file = await open(path, "wx", 0o600);
+    try {
+      await file.writeFile(this.encode(value) + "\n");
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    const dir = await open(this.directory, "r");
+    try {
+      await dir.sync();
+    } finally {
+      await dir.close();
+    }
+  }
+  async begin(id: string, hash: string, metadata: unknown) {
+    if (!/^[A-Za-z0-9_-]{1,80}$/.test(id))
+      throw new Error("Invalid operation id");
+    await this.reserve("operation", id, {
+      id,
+      metadata,
+      state: "unknown",
+      phase: "reserved",
+    });
+    const lockPath = join(this.directory, "intent-lock-" + fingerprint(hash));
+    const lock = await open(lockPath, "wx", 0o600);
+    try {
+      const path = join(
+        this.directory,
+        "fingerprint-" + fingerprint(hash) + ".json",
+      );
+      let existing: any;
+      try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+      } catch (e: any) {
+        if (e.code !== "ENOENT") throw e;
+      }
+      if (existing) {
+        const previous = await this.read(existing.id);
+        if (
+          !["confirmed", "failed"].includes(previous.state) ||
+          !previous.signature
+        )
+          throw new Error(
+            "Previous identical intent is unresolved; use status, never force/rebuild",
+          );
+      }
+      const f = await open(path, "w", 0o600);
+      try {
+        await f.writeFile(this.encode({ id }) + "\n");
+        await f.sync();
+      } finally {
+        await f.close();
+      }
+    } finally {
+      await lock.close();
+      await unlink(lockPath);
+    }
+  }
+  async reserveSignature(signature: string) {
+    await this.reserve("signature", signature, { signature });
+  }
+  async event(id: string, event: Record<string, unknown>) {
+    const f = await open(
+      join(this.directory, "events-" + fingerprint(id) + ".jsonl"),
+      "a",
+      0o600,
+    );
+    try {
+      await f.writeFile(
+        this.encode({ ...event, at: new Date().toISOString() }) + "\n",
+      );
+      await f.sync();
+    } finally {
+      await f.close();
+    }
+  }
+  async read(id: string): Promise<any> {
+    const start = JSON.parse(
+      await readFile(
+        join(this.directory, "operation-" + fingerprint(id) + ".json"),
+        "utf8",
+      ),
+    );
+    let text = "";
+    try {
+      text = await readFile(
+        join(this.directory, "events-" + fingerprint(id) + ".jsonl"),
+        "utf8",
+      );
+    } catch (e: any) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    for (const line of text.split("\n").filter(Boolean)) {
+      try {
+        Object.assign(start, JSON.parse(line));
+      } catch {
+        start.state = "unknown";
+        start.phase = "corrupt-journal";
+      }
+    }
+    return start;
+  }
+}

package/src/internal/monitor.ts

@@ -0,0 +1,141 @@
+import WebSocket from "ws";
+import { wsUrlFor } from "@nodiusxyz/sdk";
+import { Transport, finite } from "./transport.js";
+export interface MonitorOptions {
+  seconds: number;
+  maxFeeCredits?: number;
+  maxEvents: number;
+  filters: Record<string, unknown>;
+  signal?: AbortSignal;
+}
+export async function monitor(
+  origin: string,
+  apiKey: string,
+  o: MonitorOptions,
+  emit: (v: any) => void,
+) {
+  if (
+    !apiKey ||
+    !Number.isFinite(o.seconds) ||
+    o.seconds <= 0 ||
+    o.seconds > 300 ||
+    !Number.isSafeInteger(o.maxEvents) ||
+    o.maxEvents <= 0 ||
+    o.maxEvents > 1000
+  )
+    throw new Error("Monitor requires auth, <=300 seconds and <=1000 events");
+  const price = await new Transport(origin, apiKey).pricing();
+  const m = price.methods;
+  const upper =
+    finite(m.subscribeSignal) +
+    finite(m.signalNotification) * o.maxEvents +
+    finite(m.signalUnsubscribe);
+  if (
+    !Number.isSafeInteger(upper) ||
+    (o.maxFeeCredits !== undefined &&
+      (!Number.isSafeInteger(o.maxFeeCredits) ||
+        o.maxFeeCredits < 0 ||
+        upper > o.maxFeeCredits))
+  )
+    throw new Error(
+      "Monitor live estimate exceeds fee budget or unsafe pricing",
+    );
+  emit({
+    state: "monitor-plan",
+    seconds: o.seconds,
+    max_events: o.maxEvents,
+    estimated_stream_credits: upper,
+    note: "Server may bill queued events beyond locally received count; not a strict billing cap.",
+  });
+  const ws = new WebSocket(wsUrlFor(origin), {
+    headers: { "X-Api-Key": apiKey },
+    handshakeTimeout: Math.min(o.seconds * 1000, 10000),
+  });
+  let next = 0,
+    count = 0,
+    sub: string | undefined;
+  const pending = new Map<
+    number,
+    { resolve: (v: any) => void; reject: (e: Error) => void }
+  >();
+  let end!: () => void;
+  const done = new Promise<void>((r) => (end = r));
+  let deadlineReject!: (e: Error) => void;
+  const deadline = new Promise<never>((_, r) => (deadlineReject = r));
+  deadline.catch(() => {});
+  const expire = () => {
+    end();
+    deadlineReject(new Error("Monitor deadline/cancellation"));
+  };
+  const timer = setTimeout(expire, o.seconds * 1000);
+  o.signal?.addEventListener("abort", expire, { once: true });
+  ws.on("message", (b) => {
+    let q: any;
+    try {
+      q = JSON.parse(b.toString());
+    } catch {
+      return;
+    }
+    if (pending.has(q.id)) {
+      const p = pending.get(q.id)!;
+      pending.delete(q.id);
+      if (q.error) p.reject(new Error("Signals RPC rejected"));
+      else p.resolve(q.result);
+    } else if (
+      sub &&
+      q.method === "signalNotification" &&
+      q.params?.subscription === sub &&
+      count < o.maxEvents
+    ) {
+      count++;
+      emit(q.params.result);
+      if (count === o.maxEvents) end();
+    }
+  });
+  ws.on("error", () => expire());
+  ws.on("close", () => expire());
+  const call = (method: string, params: unknown[]) =>
+    new Promise<any>((resolve, reject) => {
+      const id = ++next;
+      pending.set(id, { resolve, reject });
+      ws.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }), (e) => {
+        if (e) {
+          pending.delete(id);
+          reject(new Error("Signals send failed"));
+        }
+      });
+    });
+  try {
+    await Promise.race([
+      new Promise<void>((resolve, reject) => {
+        ws.once("open", resolve);
+        ws.once("error", () => reject(new Error("Signals connection failed")));
+      }),
+      deadline,
+    ]);
+    sub = String(
+      await Promise.race([call("subscribeSignal", [o.filters]), deadline]),
+    );
+    await done;
+    return { state: "monitor-complete", events: count, subscription: sub };
+  } finally {
+    clearTimeout(timer);
+    o.signal?.removeEventListener("abort", expire);
+    if (sub && ws.readyState === WebSocket.OPEN) {
+      let cleanup: NodeJS.Timeout | undefined;
+      try {
+        await Promise.race([
+          call("signalUnsubscribe", [sub]),
+          new Promise<void>((r) => (cleanup = setTimeout(r, 500))),
+        ]);
+      } catch {
+        /* best effort unsubscribe, close still guaranteed */
+      } finally {
+        if (cleanup) clearTimeout(cleanup);
+      }
+    }
+    ws.terminate();
+    for (const p of pending.values()) p.reject(new Error("Monitor closed"));
+    pending.clear();
+  }
+}

package/src/internal/safety.ts

@@ -0,0 +1,231 @@
+import {
+  PublicKey,
+  VersionedTransaction,
+  VersionedMessage,
+  TransactionMessage,
+  ComputeBudgetProgram,
+} from "@solana/web3.js";
+import bs58 from "bs58";
+import { verifyV2 } from "./v2-policy.js";
+import nacl from "tweetnacl";
+export const PUMP = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
+const ATA = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const TOKEN = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const TOKEN2022 = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+export function decodeBase64(s: string): Buffer {
+  const b = Buffer.from(s, "base64");
+  if (!s || b.toString("base64") !== s) throw new Error("Noncanonical base64");
+  return b;
+}
+export function decodeBuilderUnsigned(encoded: string): VersionedTransaction {
+  const bytes = decodeBase64(encoded);
+  if (bytes.length > 1232)
+    throw new Error("Builder transaction exceeds packet limit");
+  if (bytes[0] === 0) {
+    // A canonical zero-count signature shortvec is one byte. Never relax the
+    // already-signed send parser or normalize any nonzero signature count.
+    const message = VersionedMessage.deserialize(bytes.subarray(1));
+    if (
+      message.header.numRequiredSignatures !== 1 ||
+      !Buffer.from(message.serialize()).equals(bytes.subarray(1))
+    )
+      throw new Error("Noncanonical unsigned message or signer count");
+    return new VersionedTransaction(message);
+  }
+  const tx = VersionedTransaction.deserialize(bytes);
+  if (!Buffer.from(tx.serialize()).equals(bytes))
+    throw new Error("Noncanonical builder transaction");
+  return tx;
+}
+
+export function inspectEnvelope(tx: VersionedTransaction, wallet: PublicKey) {
+  if (tx.message.version !== 0 || tx.message.addressTableLookups.length)
+    throw new Error("Unsigned inspection requires v0 without lookup tables");
+  if (
+    tx.message.header.numRequiredSignatures !== 1 ||
+    !tx.message.staticAccountKeys[0]?.equals(wallet)
+  )
+    throw new Error("Unsigned builder payer/signer mismatch");
+  if (
+    tx.signatures.length > 1 ||
+    tx.signatures.some((s) => s.some((b) => b !== 0))
+  )
+    throw new Error("Builder must have zero or one empty signature");
+  // Server builders may omit all signatures. A zero placeholder only normalizes
+  // the unsigned envelope; this never signs or authorizes instruction semantics.
+  if (tx.signatures.length === 0) tx.signatures = [new Uint8Array(64)];
+  if (tx.serialize().length > 1232)
+    throw new Error("Transaction exceeds packet limit");
+  const message = TransactionMessage.decompile(tx.message);
+  return {
+    signing_authorized: false,
+    instruction_count: message.instructions.length,
+    instructions: message.instructions.map((ix) => ({
+      program: ix.programId.toBase58(),
+      accounts: ix.keys.map((k) => ({
+        address: k.pubkey.toBase58(),
+        signer: k.isSigner,
+        writable: k.isWritable,
+      })),
+      data_hex: Buffer.from(ix.data).toString("hex"),
+    })),
+    note: "Unsigned envelope inspection only; instruction semantics are not authorized for signing.",
+  };
+}
+
+export interface Policy {
+  side: "buy" | "sell";
+  mint: PublicKey;
+  maxSol: bigint;
+  amountRaw?: bigint;
+  maxPriority: bigint;
+  maxPriorityLamports?: bigint;
+  requestedPriority?: bigint;
+  tokensOut?: bigint;
+  minOutput?: bigint;
+  reportedCost: bigint;
+}
+export function verifyUnsigned(
+  tx: VersionedTransaction,
+  wallet: PublicKey,
+  p: Policy,
+) {
+  inspectEnvelope(tx, wallet);
+  if (
+    tx.message.header.numRequiredSignatures !== 1 ||
+    !tx.message.staticAccountKeys[0].equals(wallet)
+  )
+    throw new Error("Fee payer or signer mismatch");
+  if (tx.signatures.some((s) => s.some((b) => b !== 0)))
+    throw new Error("Builder must be unsigned");
+  if (tx.message.version === 0 && tx.message.addressTableLookups.length)
+    throw new Error("Address lookup tables unsupported by policy");
+  const msg = TransactionMessage.decompile(tx.message);
+  if (
+    msg.instructions.some(
+      (ix) =>
+        ix.programId.toBase58() === PUMP &&
+        ["b817ee6167c5d33d", "5df6823ce7e940b2"].includes(
+          Buffer.from(ix.data).subarray(0, 8).toString("hex"),
+        ),
+    )
+  ) {
+    return verifyV2(tx, wallet, p);
+  }
+  let trades = 0,
+    atas = 0,
+    tradeCost = 0n;
+  const instructions: any[] = [];
+  const seenCompute = new Set<number>();
+  let price = 0n,
+    limit = 1400000n;
+  for (const ix of msg.instructions) {
+    const program = ix.programId.toBase58(),
+      data = Buffer.from(ix.data);
+    instructions.push({
+      program,
+      accounts: ix.keys.map((k) => ({
+        address: k.pubkey.toBase58(),
+        writable: k.isWritable,
+        signer: k.isSigner,
+      })),
+      data_hex: data.toString("hex"),
+    });
+    if (program === ComputeBudgetProgram.programId.toBase58()) {
+      if (ix.keys.length || seenCompute.has(data[0]))
+        throw new Error("Malformed/duplicate compute instruction");
+      seenCompute.add(data[0]);
+      if (data[0] === 3 && data.length === 9) {
+        price = data.readBigUInt64LE(1);
+        if (price > p.maxPriority) throw new Error("Priority fee exceeds cap");
+      } else if (data[0] === 2 && (data.length === 5 || data.length === 9)) {
+        if (data.length === 9 && data.readUInt32LE(5) !== 0)
+          throw new Error("Legacy CU upper bytes must be zero");
+        limit = BigInt(data.readUInt32LE(1));
+        if (limit <= 0n || limit > 1400000n)
+          throw new Error("Compute unit limit exceeds runtime cap");
+      } else throw new Error("Unsupported compute instruction");
+    } else if (program === ATA && p.side === "buy") {
+      if (
+        ++atas > 1 ||
+        data.length !== 1 ||
+        data[0] !== 1 ||
+        ix.keys.length !== 6 ||
+        !ix.keys[0].pubkey.equals(wallet) ||
+        !ix.keys[2].pubkey.equals(wallet) ||
+        !ix.keys[3].pubkey.equals(p.mint) ||
+        ix.keys[4].pubkey.toBase58() !== "11111111111111111111111111111111" ||
+        ![TOKEN, TOKEN2022].includes(ix.keys[5].pubkey.toBase58())
+      )
+        throw new Error("ATA policy mismatch");
+      const expected = PublicKey.findProgramAddressSync(
+        [wallet.toBuffer(), ix.keys[5].pubkey.toBuffer(), p.mint.toBuffer()],
+        new PublicKey(ATA),
+      )[0];
+      if (!ix.keys[1].pubkey.equals(expected))
+        throw new Error("ATA derivation mismatch");
+    } else if (program === PUMP) {
+      if (
+        ++trades !== 1 ||
+        !ix.keys[2]?.pubkey.equals(p.mint) ||
+        !ix.keys[6]?.pubkey.equals(wallet)
+      )
+        throw new Error("Pump mint/user policy mismatch");
+      const disc = Buffer.from(
+        p.side === "buy"
+          ? [102, 6, 61, 18, 1, 218, 235, 234]
+          : [51, 230, 133, 164, 1, 127, 131, 173],
+      );
+      if (
+        !data.subarray(0, 8).equals(disc) ||
+        data.length !== (p.side === "buy" ? 25 : 24) ||
+        ix.keys.length !== (p.side === "buy" ? 18 : 16)
+      )
+        throw new Error(
+          "Only tested classic pump layout supported (v2/cashback rejected)",
+        );
+      const amount = data.readBigUInt64LE(8),
+        bound = data.readBigUInt64LE(16);
+      if (amount === 0n || bound === 0n)
+        throw new Error("Zero trade/slippage guard");
+      if (p.side === "buy") {
+        tradeCost = bound;
+        if (bound > p.maxSol || bound !== p.reportedCost)
+          throw new Error(
+            "Decoded SOL amount exceeds cap or differs from response",
+          );
+      } else if (amount !== p.amountRaw || bound !== p.reportedCost)
+        throw new Error("Sell amount/min-output mismatch");
+    } else throw new Error("Unexpected instruction program: " + program);
+  }
+  if (trades !== 1) throw new Error("Exactly one trade required");
+  if (p.requestedPriority !== undefined && price !== p.requestedPriority)
+    throw new Error("Priority differs from requested price");
+  if (
+    p.maxPriorityLamports !== undefined &&
+    (price * limit + 999999n) / 1000000n > p.maxPriorityLamports
+  )
+    throw new Error("Total priority exceeds lamport cap");
+  return {
+    tradeCost,
+    ataCount: atas,
+    instructions,
+    limitations:
+      "Partial policy: does not validate all pump PDAs, fee recipients, program state or CPI behavior. Not a complete safety proof.",
+  };
+}
+export function checkSignature(tx: VersionedTransaction): string {
+  const count = tx.message.header.numRequiredSignatures;
+  if (count < 1 || tx.signatures.length !== count)
+    throw new Error("Missing signatures");
+  for (let i = 0; i < count; i++)
+    if (
+      !nacl.sign.detached.verify(
+        tx.message.serialize(),
+        tx.signatures[i],
+        tx.message.staticAccountKeys[i].toBytes(),
+      )
+    )
+      throw new Error("Invalid transaction signature");
+  return bs58.encode(tx.signatures[0]);
+}

package/src/internal/transport.ts

@@ -0,0 +1,111 @@
+import { NodiusClient } from "@nodiusxyz/sdk";
+import { Connection } from "@solana/web3.js";
+import { endpoint, rawAmount } from "./config.js";
+export interface Pricing {
+  ok?: boolean;
+  credits_per_usdc: number;
+  sol_usdc: { price: number; age_secs: number } | null;
+  methods: Record<string, any>;
+}
+export function finite(n: unknown): number {
+  if (typeof n !== "number" || !Number.isFinite(n) || n < 0)
+    throw new Error("Invalid live numeric field");
+  return n;
+}
+export function estimateBuy(p: Pricing, lamports: bigint): number {
+  const c = finite(p.credits_per_usdc),
+    q = p.sol_usdc,
+    m = p.methods?.executeSnipe;
+  if (!q || finite(q.age_secs) > 15 || finite(q.price) <= 0 || !m || c <= 0)
+    throw new Error("Fresh authoritative buy pricing unavailable");
+  const v =
+    finite(m.build_fee_credits) +
+    Math.ceil(
+      ((Number(lamports) / 1e9) * q.price * c * finite(m.flow_fee_bps)) / 10000,
+    );
+  if (!Number.isSafeInteger(v) || v <= 0 || !Number.isSafeInteger(c) || c <= 0)
+    throw new Error("Unsafe pricing estimate/rate");
+  return v;
+}
+export function sendFee(p: Pricing): number {
+  const m = p.methods?.sendAndConfirm;
+  const fee = finite(m?.base_credits) + finite(m?.landed_credits);
+  if (!Number.isSafeInteger(fee) || fee <= 0)
+    throw new Error("Invalid sendAndConfirm live fee");
+  return fee;
+}
+export class Transport {
+  readonly sdk: NodiusClient;
+  readonly connection: Connection;
+  readonly origin: string;
+  constructor(
+    origin: string,
+    private readonly apiKey?: string,
+  ) {
+    this.origin = endpoint(origin);
+    this.sdk = new NodiusClient(this.origin, {
+      apiKey,
+      autoPay: false,
+      maxRetries: 0,
+      timeout: 10000,
+    });
+    this.connection = new Connection(this.origin + "/rpc", {
+      commitment: "confirmed",
+      httpHeaders: apiKey ? { "X-Api-Key": apiKey } : {},
+      disableRetryOnRateLimit: true,
+      fetch: (url, init) =>
+        fetch(url, {
+          ...init,
+          signal: AbortSignal.timeout(10000),
+          redirect: "error",
+          cache: "no-store",
+        }),
+    });
+  }
+  async pricing(): Promise<Pricing> {
+    const r = await fetch(this.origin + "/pricing", {
+      signal: AbortSignal.timeout(10000),
+      cache: "no-store",
+      redirect: "error",
+    });
+    if (!r.ok) throw new Error("Pricing HTTP failure");
+    const p = (await r.json()) as Pricing;
+    if (p.ok !== true) throw new Error("Invalid pricing response");
+    finite(p.credits_per_usdc);
+    return p;
+  }
+  // The published SDK converts bigint to a JSON STRING, but rpc.rs requires as_u64().
+  // Emit validated digits as an unquoted numeric JSON literal, never through Number.
+  async sell(
+    mint: string,
+    amount: string,
+    slippage: number,
+    priority: number,
+  ): Promise<any> {
+    rawAmount(amount);
+    const params = JSON.stringify({
+      mint,
+      slippage_bps: slippage,
+      priority_fee_micro_lamports: priority,
+      closeAccount: false,
+    });
+    const body = `{"jsonrpc":"2.0","id":1,"method":"executeSell","params":[${params.slice(0, -1)},"token_amount":${amount}}]}`;
+    const r = await fetch(this.origin + "/rpc", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(this.apiKey ? { "X-Api-Key": this.apiKey } : {}),
+      },
+      body,
+      signal: AbortSignal.timeout(10000),
+      redirect: "error",
+    });
+    if (!r.ok)
+      throw new Error("Sell build HTTP failure (charge may be uncertain)");
+    const v = (await r.json()) as any;
+    if (v.error)
+      throw new Error("Sell builder rejected; consult account ledger");
+    if (!v.result) throw new Error("Malformed sell build result");
+    return v.result;
+  }
+}