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

package/src/internal/admission.ts

@@ -0,0 +1,131 @@
+import { PublicKey } from "@solana/web3.js";
+import {
+  unpackMint,
+  getAccountLenForMint,
+  getAccountLen,
+  getExtensionTypes,
+  getAccountTypeOfMintType,
+  ExtensionType,
+} from "@solana/spl-token";
+import type { Transport } from "./transport.js";
+const PUMP = new PublicKey("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P");
+const ATA = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+const TOKEN = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+const TOKEN22 = new PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+const WSOL = new PublicKey("So11111111111111111111111111111111111111112");
+function lamports(n: number): bigint {
+  if (!Number.isSafeInteger(n) || n < 0)
+    throw Error("Unsafe admission lamports");
+  return BigInt(n);
+}
+/** Conservative admission, not a guarantee against dynamic CPI/fee changes. */
+export async function admitBuy(
+  t: Transport,
+  wallet: PublicKey,
+  mint: PublicKey,
+  amount: bigint,
+  slippage: number,
+  maxSol: bigint,
+  priority: bigint,
+) {
+  const mintInfo = await t.connection.getAccountInfo(mint);
+  if (
+    !mintInfo ||
+    mintInfo.executable ||
+    ![TOKEN, TOKEN22].some((p) => p.equals(mintInfo.owner))
+  )
+    throw Error("Buy admission mint account unavailable/unsupported");
+  let baseSize: number;
+  try {
+    const parsed = unpackMint(mint, mintInfo, mintInfo.owner);
+    if (!parsed.isInitialized) throw Error("uninitialized");
+    baseSize = getAccountLenForMint(parsed);
+    if (mintInfo.owner.equals(TOKEN22))
+      baseSize = Math.max(
+        baseSize,
+        getAccountLen([
+          ...getExtensionTypes(parsed.tlvData)
+            .map(getAccountTypeOfMintType)
+            .filter((t) => t !== ExtensionType.Uninitialized),
+          ExtensionType.ImmutableOwner,
+        ]),
+      );
+  } catch {
+    throw Error(
+      "Buy admission mint layout/extensions unsupported before builder",
+    );
+  }
+  const ata = (owner: PublicKey, m: PublicKey, token: PublicKey) =>
+    PublicKey.findProgramAddressSync(
+      [owner.toBuffer(), token.toBuffer(), m.toBuffer()],
+      ATA,
+    )[0];
+  const pda = (name: string, key: PublicKey) =>
+    PublicKey.findProgramAddressSync(
+      [Buffer.from(name), key.toBuffer()],
+      PUMP,
+    )[0];
+  const uva = pda("user_volume_accumulator", wallet);
+  const keys = [
+    ata(wallet, mint, mintInfo.owner),
+    ata(wallet, WSOL, TOKEN),
+    uva,
+    ata(uva, WSOL, TOKEN),
+    pda("bonding-curve", mint),
+  ];
+  const accounts = await t.connection.getMultipleAccountsInfo(keys);
+  const curve = accounts[4];
+  if (
+    !curve ||
+    !curve.owner.equals(PUMP) ||
+    curve.data.length < 81 ||
+    !curve.data
+      .subarray(0, 8)
+      .equals(Buffer.from([23, 183, 248, 55, 96, 216, 172, 96]))
+  )
+    throw Error("Buy admission curve unavailable/unsupported before builder");
+  const quote = curve.data.subarray(83, 115);
+  const v2 =
+    curve.data.length >= 115 &&
+    (quote.equals(WSOL.toBuffer()) || quote.every((b) => b === 0));
+  // Current Pump IDL UserVolumeAccumulator serialized fields: discriminator8 +
+  // user32 + bool1 + four u64/i64 + bool1 + four cashback u64 = 106 bytes.
+  // Curve uses its live allocation; these builders do not emit extendAccount.
+  const sizes = [baseSize, 165, 106, 165, curve.data.length];
+  const names = [
+    "base_ata",
+    "wsol_ata",
+    "user_volume",
+    "user_volume_wsol_ata",
+    "curve",
+  ];
+  let rent = 0n;
+  const rentAccounts: Record<string, string> = {};
+  for (let i = 0; i < keys.length; i++) {
+    if (!v2 && (i === 1 || i === 3)) continue;
+    const info = accounts[i];
+    const size = Math.max(sizes[i], info?.data.length ?? 0);
+    const minimum = lamports(
+      await t.connection.getMinimumBalanceForRentExemption(size),
+    );
+    const existing = info ? lamports(info.lamports) : 0n;
+    const deficit = minimum > existing ? minimum - existing : 0n;
+    rent += deficit;
+    rentAccounts[names[i]] = deficit.toString();
+  }
+  const trade = (amount * BigInt(10000 + slippage) + 9999n) / 10000n;
+  const required = trade + rent + 5000n + priority;
+  const breakdown = {
+    trade_bound_lamports: trade.toString(),
+    account_rent_lamports: rent.toString(),
+    rent_accounts: rentAccounts,
+    network_fee_bound_lamports: (5000n + priority).toString(),
+    required_lamports: required.toString(),
+    note: "Conservative pre-build admission only; dynamic fees/CPI and account races remain outside this partial policy.",
+  };
+  if (required > maxSol)
+    throw Error(
+      `Trade + conservative network/account rent exceeds max SOL before builder; required ${required} lamports (trade ${trade}, rent ${rent}, network ${5000n + priority})`,
+    );
+  return breakdown;
+}

package/src/internal/app.ts

@@ -0,0 +1,509 @@
+import { PublicKey, VersionedTransaction } from "@solana/web3.js";
+import { Args, required, integer, rawAmount, solLamports } from "./config.js";
+import { Transport, estimateBuy, finite, sendFee } from "./transport.js";
+import { admitBuy } from "./admission.js";
+import { monitor } from "./monitor.js";
+import { Journal, fingerprint, outcome } from "./journal.js";
+import {
+  decodeBase64,
+  verifyUnsigned,
+  checkSignature,
+  inspectEnvelope,
+  decodeBuilderUnsigned,
+} from "./safety.js";
+function safeLamports(n: unknown): bigint {
+  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 0)
+    throw new Error("Unsafe response lamports");
+  return BigInt(n);
+}
+function requireAuth(env: NodeJS.ProcessEnv) {
+  if (!env.NODIUS_API_KEY)
+    throw new Error("Set NODIUS_API_KEY in environment (not CLI)");
+}
+async function identity(t: Transport, wallet: PublicKey) {
+  const account = await t.sdk.getBillingAccount();
+  if (account.pubkey !== wallet.toBase58())
+    throw new Error("API key billing identity does not match wallet");
+  return account;
+}
+async function submit(
+  t: Transport,
+  j: Journal,
+  id: string,
+  tx: VersionedTransaction,
+  emit: (v: any) => void,
+) {
+  const signature = checkSignature(tx);
+  await j.reserveSignature(signature);
+  await j.event(id, {
+    state: "unknown",
+    phase: "submission-intent",
+    signature,
+  });
+  emit({ state: "unknown", phase: "submission-intent", signature });
+  let state: "confirmed" | "failed" | "unknown" = "unknown";
+  try {
+    // Exactly one SDK call. maxRetries:0 disables upstream retries, NOT the
+    // server's intentional bounded same-byte multi-leg resends.
+    const result: any = await t.sdk.call("sendAndConfirm", [
+      Buffer.from(tx.serialize()).toString("base64"),
+      {
+        encoding: "base64",
+        maxRetries: 0,
+        skipPreflight: false,
+        preflightCommitment: "confirmed",
+      },
+    ]);
+    if (result?.signature === signature) {
+      const chainError =
+        result.transaction_error ?? result.chain_err ?? result.chain_error;
+      const landedError =
+        Number.isSafeInteger(result.slot) &&
+        result.slot >= 0 &&
+        typeof result.landing_time_ms === "number" &&
+        Number.isFinite(result.landing_time_ms) &&
+        result.landing_time_ms >= 0 &&
+        typeof result.error === "string" &&
+        result.error.length > 0 &&
+        !/timed?\s*out|timeout|without confirmation/i.test(result.error);
+      const definitive =
+        result.status === "failed" ||
+        chainError != null ||
+        result.definitive_error === true ||
+        landedError ||
+        (typeof result.error === "string" &&
+          /^(Transaction failed on-chain:|Transaction failed:)/.test(
+            result.error,
+          ));
+      state =
+        result.status === "unknown"
+          ? "unknown"
+          : definitive
+            ? "failed"
+            : result.status !== "unknown" && result.confirmed === true
+              ? "confirmed"
+              : "unknown";
+    }
+  } catch (error: unknown) {
+    // A signature-bound server rejection is definitive even when carried by
+    // HTTP 502. Never infer failure from a timeout/message alone, and never
+    // persist the SDK error body (it may contain transport details).
+    if (error && typeof error === "object" && "details" in error) {
+      const details: any = error.details;
+      const rejection = details?.error?.data ?? details;
+      if (rejection?.signature === signature && rejection?.status === "failed")
+        state = "failed";
+    }
+  }
+  await j.event(id, {
+    state,
+    phase: state === "unknown" ? "submission-uncertain" : "submission-result",
+    signature,
+  });
+  return {
+    state,
+    operation_id: id,
+    signature,
+    note:
+      state === "unknown"
+        ? "Do not rebuild/rebroadcast. Read status and account ledger; no automatic retry."
+        : undefined,
+  };
+}
+export async function run(
+  a: Args,
+  env: NodeJS.ProcessEnv = process.env,
+  emit: (v: any) => void = () => {},
+  bridge?: {
+    publicKey: PublicKey;
+    signTransaction(tx: VersionedTransaction): Promise<VersionedTransaction>;
+  },
+): Promise<any> {
+  const origin =
+    typeof a.endpoint === "string"
+      ? a.endpoint
+      : (env.NODIUS_ENDPOINT ?? "https://rpc.nodius.xyz");
+  if (a.command === "help")
+    return {
+      commands: [
+        "recent",
+        "monitor",
+        "inspect",
+        "migrate",
+        "buy",
+        "sell",
+        "send",
+        "status",
+      ],
+      note: "See README. Trading defaults to a read-only plan; monitoring is a paid stream.",
+    };
+  const t = new Transport(origin, env.NODIUS_API_KEY);
+  if (a.command === "monitor") {
+    requireAuth(env);
+    const filters: Record<string, unknown> = {};
+    if (a.mint) filters.mint = new PublicKey(required(a, "mint")).toBase58();
+    if (a.kinds) {
+      const kinds = required(a, "kinds").split(",");
+      if (
+        kinds.some(
+          (k) =>
+            !["newPair", "graduation", "walletActivity", "largeSwap"].includes(
+              k,
+            ),
+        ) ||
+        new Set(kinds).size !== kinds.length
+      )
+        throw new Error("Unsupported/duplicate signal kinds");
+      filters.kinds = kinds;
+    }
+    return monitor(
+      t.origin,
+      env.NODIUS_API_KEY!,
+      {
+        seconds: integer(String(a.seconds ?? "30"), 300),
+        maxEvents: integer(String(a["max-events"] ?? "100"), 1000),
+        maxFeeCredits:
+          a["max-fee-credits"] === undefined
+            ? undefined
+            : integer(required(a, "max-fee-credits")),
+        filters,
+      },
+      emit,
+    );
+  }
+  if (a.command === "recent") {
+    const limit = integer(String(a.limit ?? "20"), 50);
+    if (!limit) throw new Error("Positive limit required");
+    const result: any = await t.sdk.signalsRecent(limit);
+    // Some server versions return a fixed preview window despite the query.
+    if (Array.isArray(result)) return result.slice(0, limit);
+    if (Array.isArray(result?.events)) {
+      const events = result.events.slice(0, limit);
+      return {
+        ...result,
+        events,
+        ...(typeof result.count === "number" ? { count: events.length } : {}),
+      };
+    }
+    return result;
+  }
+  if (a.command === "inspect" || a.command === "migrate") {
+    requireAuth(env);
+    const wallet = new PublicKey(required(a, "wallet"));
+    const [account, balance, onchain, version] = await Promise.all([
+      t.sdk.getBillingAccount(),
+      t.connection.getBalance(wallet),
+      t.connection.getAccountInfo(wallet),
+      t.connection.getVersion(),
+    ]);
+    return {
+      state: "read-only",
+      wallet: wallet.toBase58(),
+      billing_identity_matches: account.pubkey === wallet.toBase58(),
+      billing_account: account,
+      balance_lamports: balance,
+      onchain_account: onchain,
+      version,
+      migration:
+        "new Connection(origin + /rpc, {httpHeaders: {X-Api-Key: process.env.NODIUS_API_KEY}, disableRetryOnRateLimit: true})",
+    };
+  }
+  const j = new Journal(
+    typeof a.journal === "string"
+      ? a.journal
+      : (env.NODIUS_JOURNAL ?? ".nodius-journal"),
+    env.NODIUS_API_KEY,
+  );
+  if (a.command === "status") {
+    requireAuth(env);
+    const record = await j.read(required(a, "operation-id"));
+    if (!record.signature)
+      return {
+        ...record,
+        state: record.state === "built" ? "built" : "unknown",
+        note: "No known signature: check account ledger. No rebuild/resume performed.",
+      };
+    let chain: any = null;
+    try {
+      const status = (await t.sdk.getSignatureStatuses([
+        record.signature,
+      ])) as any;
+      chain = status?.value?.[0] ?? null;
+    } catch {
+      /* Read failure does not authorize another send. */
+    }
+    const observed = outcome(chain);
+    const state = ["confirmed", "failed"].includes(record.state)
+      ? record.state
+      : observed;
+    await j.event(record.id, {
+      state,
+      phase: "status-reconciled",
+      signature: record.signature,
+    });
+    return { ...record, state, chain_status: chain };
+  }
+  if (a.command === "send") {
+    const bytes = decodeBase64(required(a, "signed-tx-base64"));
+    if (bytes.length > 1232)
+      throw new Error("Signed transaction exceeds packet limit");
+    let tx: VersionedTransaction;
+    try {
+      tx = VersionedTransaction.deserialize(bytes);
+    } catch {
+      throw new Error("Malformed signed transaction");
+    }
+    if (!Buffer.from(tx.serialize()).equals(bytes))
+      throw new Error("Noncanonical signed transaction");
+    const signature = checkSignature(tx);
+    const wallet = new PublicKey(required(a, "wallet"));
+    if (
+      tx.message.header.numRequiredSignatures !== 1 ||
+      !tx.message.staticAccountKeys[0].equals(wallet)
+    )
+      throw new Error("Signed transaction payer/signer mismatch");
+    const maxFee = integer(required(a, "max-fee-credits"));
+    const p = await t.pricing(),
+      fee = sendFee(p);
+    if (fee > maxFee) throw new Error("Send fee exceeds cap");
+    if (!a.execute)
+      return {
+        state: "plan",
+        signature,
+        send_fee_credits: fee,
+        note: "Existing signed transaction must be independently reviewed; this command does not validate trade instructions.",
+      };
+    requireAuth(env);
+    await identity(t, wallet);
+    const id = required(a, "operation-id");
+    await j.begin(id, fingerprint({ origin, signature }), {
+      command: "send",
+      wallet: wallet.toBase58(),
+    });
+    return submit(t, j, id, tx, emit);
+  }
+  if (a.command !== "buy" && a.command !== "sell")
+    throw new Error("Unsupported command");
+  if (a["build-only"] && !a.execute)
+    throw new Error("--build-only requires --execute");
+  const side = a.command;
+  const mint = new PublicKey(required(a, "mint")),
+    wallet = new PublicKey(required(a, "wallet"));
+  const maxSol = solLamports(required(a, "max-sol"));
+  if (maxSol <= 0n || maxSol > BigInt(Number.MAX_SAFE_INTEGER))
+    throw new Error(
+      "Max SOL must be positive and safely representable in lamports",
+    );
+  const amount =
+    side === "buy"
+      ? solLamports(required(a, "amount-sol"))
+      : rawAmount(required(a, "amount-raw"));
+  if (
+    amount <= 0n ||
+    (side === "buy" &&
+      (amount > maxSol || amount > BigInt(Number.MAX_SAFE_INTEGER)))
+  )
+    throw new Error("Amount outside SOL budget");
+  const maxFee = integer(required(a, "max-fee-credits")),
+    slippage = integer(required(a, "slippage-bps"), 9999),
+    priority = integer(required(a, "priority-fee")),
+    priorityCap = integer(required(a, "max-priority-fee"));
+  if (priority > priorityCap) throw new Error("Priority exceeds cap");
+  if (priority > 0 && a["max-priority-lamports"] === undefined)
+    throw new Error("Nonzero priority requires --max-priority-lamports");
+  const maxPriorityLamports = BigInt(
+    integer(String(a["max-priority-lamports"] ?? "0")),
+  );
+  const p = await t.pricing();
+  const sendCredits = sendFee(p);
+  const estimate = side === "buy" ? estimateBuy(p, amount) : null;
+  const plan = {
+    state: "plan",
+    side,
+    wallet: wallet.toBase58(),
+    mint: mint.toBase58(),
+    amount_raw: side === "sell" ? amount.toString() : undefined,
+    amount_lamports: side === "buy" ? amount.toString() : undefined,
+    max_sol_lamports: maxSol.toString(),
+    estimated_build_fee_credits: estimate,
+    send_fee_credits: sendCredits,
+    live_pricing: p,
+    limits: {
+      max_fee_credits: maxFee,
+      slippage_bps: slippage,
+      priority_fee_micro_lamports: priority,
+      max_priority_fee_micro_lamports: priorityCap,
+    },
+    warning:
+      "Builder is charged BEFORE returning. Buy estimate is not a server-side billing cap. Sell build is unquoted; post-build cap cannot undo its charge. Send failure does not automatically refund a successful builder.",
+  };
+  if (!a.execute) return plan;
+  if (side === "sell" && !a["accept-unquoted-build-charge"])
+    throw new Error(
+      "Sell charge unquoted: explicit --accept-unquoted-build-charge required BEFORE builder",
+    );
+  if (
+    estimate !== null &&
+    estimate + (a["build-only"] ? 0 : sendCredits) > maxFee
+  )
+    throw new Error("Estimated builder/send credits exceed cap");
+  if (!a["build-only"] && !a["ack-incomplete-policy"])
+    throw new Error(
+      "Partial instruction policy: --ack-incomplete-policy required before signing",
+    );
+  requireAuth(env);
+  if (!a["build-only"] && (!bridge || !bridge.publicKey.equals(wallet)))
+    throw new Error("Framework wallet mismatch or missing bridge");
+  const account = await identity(t, wallet);
+  if (
+    finite(account.balance) <
+    (estimate ?? 0) + (a["build-only"] ? 0 : sendCredits)
+  )
+    throw new Error("Insufficient billing balance");
+  const admission =
+    side === "buy"
+      ? await admitBuy(
+          t,
+          wallet,
+          mint,
+          amount,
+          slippage,
+          maxSol,
+          maxPriorityLamports,
+        )
+      : undefined;
+  const id = required(a, "operation-id");
+  const intent = {
+    origin,
+    side,
+    mint: mint.toBase58(),
+    wallet: wallet.toBase58(),
+    amount: amount.toString(),
+    slippage,
+    priority,
+  };
+  await j.begin(
+    id,
+    fingerprint({
+      origin,
+      side,
+      mint: mint.toBase58(),
+      wallet: wallet.toBase58(),
+      amount: amount.toString(),
+    }),
+    intent,
+  );
+  await j.event(id, { state: "unknown", phase: "builder-intent" });
+  let result: any;
+  try {
+    result =
+      side === "buy"
+        ? await t.sdk.executeSnipe(
+            mint.toBase58(),
+            Number(amount) / 1e9,
+            slippage,
+            { priority_fee_micro_lamports: priority },
+          )
+        : await t.sell(mint.toBase58(), amount.toString(), slippage, priority);
+  } catch {
+    await j.event(id, { state: "unknown", phase: "builder-uncertain" });
+    return {
+      state: "unknown",
+      operation_id: id,
+      note: "Builder response failed. Check ledger for debit/refund; never auto-rebuild. No transaction signed/submitted.",
+    };
+  }
+  await j.event(id, {
+    state: "built",
+    phase: "builder-returned",
+    build_result: {
+      mint: new PublicKey(result.mint).toBase58(),
+      fee_credits: finite(result.fee_credits),
+      ...(side === "buy"
+        ? {
+            tokens_out: safeLamports(result.tokens_out).toString(),
+            max_sol_cost_lamports: safeLamports(
+              result.max_sol_cost_lamports,
+            ).toString(),
+          }
+        : {
+            min_sol_output_lamports: safeLamports(
+              result.min_sol_output_lamports,
+            ).toString(),
+          }),
+    },
+  });
+  const charged = finite(result.fee_credits);
+  if (charged + (a["build-only"] ? 0 : sendCredits) > maxFee)
+    throw new Error(
+      "Already-charged builder plus send exceeds max credits; NOT signing/submitting (no automatic builder refund)",
+    );
+  if (result.mint !== mint.toBase58()) throw new Error("Builder mint mismatch");
+  const cost = safeLamports(
+    side === "buy"
+      ? result.max_sol_cost_lamports
+      : result.min_sol_output_lamports,
+  );
+  if (side === "buy" && cost > maxSol)
+    throw new Error(
+      "Already-charged build exceeds returned SOL cap; NOT signing/submitting",
+    );
+  const tx = decodeBuilderUnsigned(result.unsigned_tx_base64);
+  if (a["build-only"]) {
+    const envelope = inspectEnvelope(tx, wallet);
+    emit({
+      state: "built",
+      operation_id: id,
+      fee_credits: charged,
+      policy: envelope,
+    });
+    return {
+      state: "built",
+      operation_id: id,
+      fee_credits: charged,
+      unsigned_tx_base64: result.unsigned_tx_base64,
+      admission,
+      policy: envelope,
+      note: "Charged unsigned construction only. No signing/submission; instruction semantics are not authorized. No automatic resume/rebuild.",
+    };
+  }
+  const inspected = verifyUnsigned(tx, wallet, {
+    side,
+    mint,
+    maxSol,
+    amountRaw: side === "sell" ? amount : undefined,
+    maxPriority: BigInt(priorityCap),
+    maxPriorityLamports,
+    requestedPriority: BigInt(priority),
+    tokensOut: side === "buy" ? safeLamports(result.tokens_out) : undefined,
+    reportedCost: cost,
+  });
+  emit({
+    state: "built",
+    operation_id: id,
+    fee_credits: charged,
+    policy: inspected,
+  });
+  // Network fees are queried against this exact message; rent is conservatively
+  // reserved for a new token ATA. Pump-side CPI rent remains outside this partial policy.
+  const fee = await t.connection.getFeeForMessage(tx.message);
+  if (fee.value === null) throw new Error("Message fee unavailable/expired");
+  let overhead = safeLamports(fee.value);
+  if (inspected.ataCount)
+    overhead +=
+      BigInt(inspected.ataCount) *
+      safeLamports(await t.connection.getMinimumBalanceForRentExemption(165));
+  if (inspected.tradeCost + overhead > maxSol)
+    throw new Error(
+      "Trade + known network/ATA rent exceeds max SOL; NOT signing",
+    );
+  const originalMessage = Buffer.from(tx.message.serialize());
+  const signed = await bridge!.signTransaction(tx);
+  if (
+    !signed ||
+    !Buffer.from(signed.message.serialize()).equals(originalMessage)
+  )
+    throw new Error("Wallet mutated approved transaction message");
+  checkSignature(signed);
+  return submit(t, j, id, signed, emit);
+}