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

package/src/internal/config.ts

@@ -0,0 +1,107 @@
+export type Args = { command: string; [key: string]: string | boolean };
+const common = ["endpoint"];
+const trade = [
+  "mint",
+  "wallet",
+  "keypair",
+  "max-sol",
+  "max-fee-credits",
+  "slippage-bps",
+  "priority-fee",
+  "max-priority-fee",
+  "max-priority-lamports",
+  "journal",
+  "operation-id",
+  "execute",
+  "build-only",
+  "accept-unquoted-build-charge",
+  "ack-incomplete-policy",
+];
+const flags: Record<string, string[]> = {
+  buy: [...trade, "amount-sol"],
+  sell: [...trade, "amount-raw"],
+  send: [
+    "tx-file",
+    "wallet",
+    "max-fee-credits",
+    "journal",
+    "operation-id",
+    "execute",
+  ],
+  inspect: ["wallet"],
+  migrate: ["wallet"],
+  recent: ["limit"],
+  monitor: ["seconds", "max-events", "mint", "kinds"],
+  status: ["journal", "operation-id"],
+  help: [],
+};
+const booleans = new Set([
+  "execute",
+  "build-only",
+  "accept-unquoted-build-charge",
+  "ack-incomplete-policy",
+]);
+export function parseArgs(argv: string[]): Args {
+  const command = argv[0] ?? "help";
+  if (!(command in flags)) throw new Error("Unknown command");
+  const out: Args = { command };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!flag.startsWith("--"))
+      throw new Error("Unexpected positional argument");
+    const k = flag.slice(2);
+    if (![...common, ...flags[command]].includes(k) || k in out)
+      throw new Error("Unknown or duplicate flag: " + flag);
+    if (booleans.has(k)) out[k] = true;
+    else {
+      const v = argv[++i];
+      if (!v || v.startsWith("--")) throw new Error("Missing value: " + flag);
+      out[k] = v;
+    }
+  }
+  return out;
+}
+export function required(a: Args, k: string): string {
+  const v = a[k];
+  if (typeof v !== "string" || !v) throw new Error("Required --" + k);
+  return v;
+}
+export function integer(s: string, max = Number.MAX_SAFE_INTEGER): number {
+  if (!/^(0|[1-9]\d*)$/.test(s)) throw new Error("Invalid integer");
+  const n = Number(s);
+  if (!Number.isSafeInteger(n) || n > max)
+    throw new Error("Integer exceeds cap");
+  return n;
+}
+export function rawAmount(s: string): bigint {
+  if (!/^[1-9]\d*$/.test(s))
+    throw new Error("Amount must be a positive raw integer");
+  const n = BigInt(s);
+  if (n > 18446744073709551615n) throw new Error("Amount exceeds u64");
+  return n;
+}
+export function solLamports(s: string): bigint {
+  if (!/^(0|[1-9]\d*)(\.\d{1,9})?$/.test(s))
+    throw new Error("SOL requires plain decimal with <=9 places");
+  const [w, f = ""] = s.split(".");
+  return BigInt(w) * 1000000000n + BigInt(f.padEnd(9, "0"));
+}
+export function endpoint(s: string): string {
+  const u = new URL(s);
+  if (
+    u.username ||
+    u.password ||
+    u.search ||
+    u.hash ||
+    !["", "/"].includes(u.pathname) ||
+    !(
+      u.protocol === "https:" ||
+      (u.protocol === "http:" &&
+        ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname))
+    )
+  )
+    throw new Error(
+      "Use HTTPS origin (HTTP only for loopback), no URL credentials or path",
+    );
+  return u.origin;
+}

package/src/internal/journal.ts

@@ -0,0 +1,145 @@
+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> {
+    let start: any;
+    try {
+      start = JSON.parse(
+        await readFile(
+          join(this.directory, "operation-" + fingerprint(id) + ".json"),
+          "utf8",
+        ),
+      );
+    } catch {
+      throw new Error("Operation not found");
+    }
+    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,259 @@
+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 sellToken: PublicKey | undefined, sellAta: PublicKey | undefined;
+  let closes = 0;
+  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");
+      if (p.side === "sell") {
+        sellToken = ix.keys[9].pubkey;
+        sellAta = ix.keys[5].pubkey;
+      }
+    } else if (p.side === "sell" && [TOKEN, TOKEN2022].includes(program)) {
+      const expected = PublicKey.findProgramAddressSync(
+        [wallet.toBuffer(), ix.programId.toBuffer(), p.mint.toBuffer()],
+        new PublicKey(ATA),
+      )[0];
+      if (
+        ++closes !== 1 ||
+        trades !== 1 ||
+        ix !== msg.instructions[msg.instructions.length - 1] ||
+        data.length !== 1 ||
+        data[0] !== 9 ||
+        ix.keys.length !== 3 ||
+        !sellToken?.equals(ix.programId) ||
+        !sellAta?.equals(expected) ||
+        !ix.keys[0].pubkey.equals(expected) ||
+        !ix.keys[0].isWritable ||
+        ix.keys[0].isSigner ||
+        ix.keys
+          .slice(1)
+          .some((k) => !k.pubkey.equals(wallet) || !k.isSigner || !k.isWritable)
+      )
+        throw Error("Sell close account policy 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]);
+}