@nodiusxyz/solana-agent-kit 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @nodiusxyz/solana-agent-kit
 
-An opt-in **Solana Agent Kit 2.0.10** plugin for nodius.xyz recent signals, bounded monitoring, buy/sell plans, guarded execution and persistent status recovery. Node.js **22+**, ESM. This is a library plugin, not a CLI trading pack. MIT; only the MIT integration client is included, no server source.
+An opt-in **Solana Agent Kit 2.0.10** plugin for nodius.xyz recent signals, bounded monitoring, buy/sell plans, guarded execution and persistent status recovery. Node.js **20.20.2+**, ESM. This is a library plugin, not a CLI trading pack. MIT licensed.
 
 ## Install and drop in
 
@@ -32,7 +32,7 @@ console.log(await nodius.methods.nodiusRecent({ limit: 5 }));
 
 All five names are registered identically in `agent.methods` and `agent.actions`:
 
-- `nodiusRecent({ limit?: number })`: default 20, integer 1–50, recent server response.
+- `nodiusRecent({ limit?: number })`: default 20, integer 1–50. Locally limits returned events even when an older server returns a larger preview; returned `count` matches those events.
 - `nodiusMonitor({ maxFeeCredits: number, seconds?: number, maxEvents?: number, mint?: string, kinds?: SignalKind[] })`: defaults 30 seconds / 100 events; bounds 1–300 seconds / 1–1000 events. Kinds: `newPair`, `graduation`, `walletActivity`, `largeSwap`, no duplicates. Authenticated **paid** stream. Requires a nonnegative safe-integer admission budget: live `subscribe + maxEvents × notification + unsubscribe` estimate must fit **before WS opens**. For example `{ seconds: 3, maxEvents: 3, maxFeeCredits: 100 }`. Returns `{ state: "monitor-complete", events, subscription, notifications, estimated_stream_credits, note }`; closes/unsubscribes in finally. This never triggers trades. Duration is the stream deadline; HTTP pricing lookup can add up to its 10-second timeout and cleanup up to 500ms.
 - `nodiusTrade(input)`: buy or sell; defaults a **read-only plan**, only fetching pricing. No builder, signature, funding or submission by default.
 - `nodiusStatus({ operationId: string })`: reads the configured persistent journal and, if a signature exists, reconciles chain status. Never rebuilds, resumes or rebroadcasts. A missing signature is not permission to retry; inspect the billing ledger separately.
@@ -81,10 +81,18 @@ For executed trades, billing identity must match the wallet. The SDK uses `maxRe
 
 This is a **partial policy**, not a complete on-chain proof: dynamic program state, fee-recipient governance, program upgrades, Token-2022 extensions and all CPI behavior/rent are not fully verified. `ackIncompletePolicy: true` explicitly accepts these limitations, not arbitrary instructions. Slippage arguments are forwarded and returned instruction bounds checked; they are not an independent market-price oracle. `maxSol` is not a guaranteed cap on every possible CPI effect.
 
-Pricing is fetched fresh from `/pricing`. Buy build fee is estimated with a SOL quote no older than 15 seconds. Builder fees are charged **before** the response arrives. The estimated buy cap is **not a server-side billing cap**; the post-build check cannot undo a builder debit. Sell construction is unquoted and requires the explicit charge acknowledgement. Send failure does not automatically refund a successful build. Signals billing may include events queued beyond the locally received count; duration/event limits are **not** hard server billing caps. Keep account credit balances bounded and review ledger/transaction details.
+Pricing is fetched fresh from `/pricing`. Buy build fee is estimated from **`amountSol`**, not `maxSol`, with a SOL quote no older than 15 seconds. `maxSol` is the aggregate safety ceiling; raising it does not raise the requested trade size or its fee estimate. Before charged buy construction (including `buildOnly`), live mint/curve and buyer-associated account data plus live rent prices admit the slippage-bound trade, known missing/growing account rent, and a conservative network/priority allowance. Token-2022 account sizes use SPL extension sizing, including metadata-extended mints; v2 zero/WSOL quote layouts reserve the known WSOL and volume-associated accounts. Missing/unsupported curve layouts fail before construction. Admission failures report required lamports and trade/rent/network components; unsigned results include an `admission` breakdown. This is a conservative partial check, not an exact rent multiplier or complete CPI-spend guarantee. Send admission uses the live landed **total** rather than adding the base fee twice. Builder fees are charged **before** the response arrives. The estimated buy cap is **not a server-side billing cap**; the post-build check cannot undo a builder debit. Sell construction is unquoted and requires the explicit charge acknowledgement. Send failure does not automatically refund a successful build. Signals billing may include events queued beyond the locally received count; duration/event limits are **not** hard server billing caps. Keep account credit balances bounded and review ledger/transaction details.
 
 There is exactly one client `sendAndConfirm` invocation per submitted operation. The server can intentionally make bounded same-byte multi-leg resends; this is not an SDK retry. Journal logical economic intent is origin/wallet/side/mint/amount; changing slippage or priority cannot bypass an unresolved reservation (different amounts are different intents, not a global exactly-once guarantee). Operation/intent reservations precede charged construction, and signature reservations are permanent before submission. Transport failures produce `unknown`, never an automatic rebuild/rebroadcast. Preserve the journal across restarts; do not delete it or change directories to bypass guards. Prefer a private directory on durable local storage (created 0700, files 0600), never shared across unrelated wallets. Journal records store only allowlisted validated builder summaries, not arbitrary response fields or unsigned transaction payloads, and redact the current credential before writes. Journal records include intent/build details; protect them like financial records. Status reconciliation is observation, not an execution authorization. Reusing a transaction signature is always blocked, including after terminal outcomes.
 
+### Unsigned decoder and sell rent recovery
+
+`decodeBuilderUnsigned(unsignedTxBase64)` is exported from the package root. It accepts the canonical provider zero-signature envelope and returns a `VersionedTransaction` with an empty signing placeholder. This decoding does **not** authorize signing or validate trade instruction semantics; independently inspect/review the result. Signed-send validation remains strict and does not normalize zero signatures.
+
+Sell requests omit `closeAccount` and honor the server default: a full-balance sell can append own-base-ATA rent recovery; partial sells leave the account open. No close override is exposed. Classic and v2 signing policies permit only the expected derived base ATA, the correct token program, and exactly three close accounts (base ATA, wallet destination, wallet authority), with the close after the sell. Arbitrary accounts/destinations/authorities and reordered closes are rejected. Inventory eligibility is server/on-chain state, not an offline client proof.
+
+`nodiusStatus` reports a missing local ID as `Operation not found`, without filesystem paths. Malformed signed wire data reports `Malformed signed transaction` rather than parser internals. Signature-bound definitive `status: failed`/transaction errors are terminal failures; explicit `status: unknown` remains uncertain regardless of diagnostic details. Status recovery recognizes on-chain `err` as failed without sending again.
+
 ## Framework tools without hosted LLM credentials
 
 Programmatic methods above need **no LLM API key**. If desired, convert registered actions offline using published framework helpers:

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { SolanaAgentKit } from "solana-agent-kit";
 import { z } from "zod";
+export { decodeBuilderUnsigned } from "./internal/safety.js";
 export interface NodiusOptions {
     apiKey?: string;
     endpoint?: string;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { run } from "./internal/app.js";
 import { endpoint as validateEndpoint } from "./internal/config.js";
+export { decodeBuilderUnsigned } from "./internal/safety.js";
 const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const decimal = z.string().regex(/^(0|[1-9]\d*)(\.\d{1,9})?$/);
 const base = {

package/dist/internal/admission.d.ts

@@ -0,0 +1,11 @@
+import { PublicKey } from "@solana/web3.js";
+import type { Transport } from "./transport.js";
+/** Conservative admission, not a guarantee against dynamic CPI/fee changes. */
+export declare function admitBuy(t: Transport, wallet: PublicKey, mint: PublicKey, amount: bigint, slippage: number, maxSol: bigint, priority: bigint): Promise<{
+    trade_bound_lamports: string;
+    account_rent_lamports: string;
+    rent_accounts: Record<string, string>;
+    network_fee_bound_lamports: string;
+    required_lamports: string;
+    note: string;
+}>;

package/dist/internal/admission.js

@@ -0,0 +1,96 @@
+import { PublicKey } from "@solana/web3.js";
+import { unpackMint, getAccountLenForMint, getAccountLen, getExtensionTypes, getAccountTypeOfMintType, ExtensionType, } from "@solana/spl-token";
+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) {
+    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, wallet, mint, amount, slippage, maxSol, priority) {
+    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;
+    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, m, token) => PublicKey.findProgramAddressSync([owner.toBuffer(), token.toBuffer(), m.toBuffer()], ATA)[0];
+    const pda = (name, key) => 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 = {};
+    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/dist/internal/app.js

@@ -1,6 +1,7 @@
 import { PublicKey, VersionedTransaction } from "@solana/web3.js";
 import { 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";
@@ -42,7 +43,7 @@ async function submit(t, j, id, tx, emit) {
             },
         ]);
         if (result?.signature === signature) {
-            const chainError = result.chain_err ?? result.chain_error;
+            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" &&
@@ -51,20 +52,32 @@ async function submit(t, j, id, tx, emit) {
                 typeof result.error === "string" &&
                 result.error.length > 0 &&
                 !/timed?\s*out|timeout|without confirmation/i.test(result.error);
-            const definitive = chainError != null ||
+            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 = definitive
-                ? "failed"
-                : result.confirmed === true
-                    ? "confirmed"
-                    : "unknown";
+            state =
+                result.status === "unknown"
+                    ? "unknown"
+                    : definitive
+                        ? "failed"
+                        : result.status !== "unknown" && result.confirmed === true
+                            ? "confirmed"
+                            : "unknown";
         }
     }
-    catch {
-        /* HTTP/RPC/timeout errors are ambiguous; no rebroadcast or rebuild. */
+    catch (error) {
+        // 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 = error.details;
+            const rejection = details?.error?.data ?? details;
+            if (rejection?.signature === signature && rejection?.status === "failed")
+                state = "failed";
+        }
     }
     await j.event(id, {
         state,
@@ -124,7 +137,19 @@ export async function run(a, env = process.env, emit = () => { }, bridge) {
         const limit = integer(String(a.limit ?? "20"), 50);
         if (!limit)
             throw new Error("Positive limit required");
-        return t.sdk.signalsRecent(limit);
+        const result = 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);
@@ -183,7 +208,13 @@ export async function run(a, env = process.env, emit = () => { }, bridge) {
         const bytes = decodeBase64(required(a, "signed-tx-base64"));
         if (bytes.length > 1232)
             throw new Error("Signed transaction exceeds packet limit");
-        const tx = VersionedTransaction.deserialize(bytes);
+        let tx;
+        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);
@@ -235,7 +266,7 @@ export async function run(a, env = process.env, emit = () => { }, bridge) {
     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, maxSol) : null;
+    const estimate = side === "buy" ? estimateBuy(p, amount) : null;
     const plan = {
         state: "plan",
         side,
@@ -271,6 +302,9 @@ export async function run(a, env = process.env, emit = () => { }, bridge) {
     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,
@@ -344,6 +378,7 @@ export async function run(a, env = process.env, emit = () => { }, bridge) {
             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.",
         };

package/dist/internal/journal.js

@@ -106,7 +106,13 @@ export class Journal {
         }
     }
     async read(id) {
-        const start = JSON.parse(await readFile(join(this.directory, "operation-" + fingerprint(id) + ".json"), "utf8"));
+        let start;
+        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");

package/dist/internal/safety.js

@@ -75,6 +75,8 @@ export function verifyUnsigned(tx, wallet, p) {
         ["b817ee6167c5d33d", "5df6823ce7e940b2"].includes(Buffer.from(ix.data).subarray(0, 8).toString("hex")))) {
         return verifyV2(tx, wallet, p);
     }
+    let sellToken, sellAta;
+    let closes = 0;
     let trades = 0, atas = 0, tradeCost = 0n;
     const instructions = [];
     const seenCompute = new Set();
@@ -146,6 +148,28 @@ export function verifyUnsigned(tx, wallet, p) {
             }
             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);

package/dist/internal/transport.js

@@ -18,7 +18,9 @@ export function estimateBuy(p, lamports) {
 }
 export function sendFee(p) {
     const m = p.methods?.sendAndConfirm;
-    const fee = finite(m?.base_credits) + finite(m?.landed_credits);
+    const base = finite(m?.base_credits);
+    // landed_credits is the terminal TOTAL, not a surcharge on base_credits.
+    const fee = Math.max(base, finite(m?.landed_credits));
     if (!Number.isSafeInteger(fee) || fee <= 0)
         throw new Error("Invalid sendAndConfirm live fee");
     return fee;
@@ -71,7 +73,6 @@ export class Transport {
             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", {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@nodiusxyz/solana-agent-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Opt-in bounded nodius.xyz plugin for Solana Agent Kit",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=20.20.2"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,6 +31,7 @@
   "dependencies": {
     "@nodiusxyz/sdk": "0.2.15",
     "@solana/web3.js": "1.99.0",
+    "@solana/spl-token": "0.4.15",
     "bs58": "6.0.0",
     "tweetnacl": "1.0.3",
     "ws": "8.22.0",

package/src/index.ts

@@ -2,6 +2,7 @@ import type { SolanaAgentKit, Plugin } from "solana-agent-kit";
 import { z } from "zod";
 import { run } from "./internal/app.js";
 import { endpoint as validateEndpoint, type Args } from "./internal/config.js";
+export { decodeBuilderUnsigned } from "./internal/safety.js";
 export interface NodiusOptions {
   apiKey?: string;
   endpoint?: string;

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

@@ -1,6 +1,7 @@
 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 {
@@ -54,7 +55,8 @@ async function submit(
       },
     ]);
     if (result?.signature === signature) {
-      const chainError = result.chain_err ?? result.chain_error;
+      const chainError =
+        result.transaction_error ?? result.chain_err ?? result.chain_error;
       const landedError =
         Number.isSafeInteger(result.slot) &&
         result.slot >= 0 &&
@@ -65,6 +67,7 @@ async function submit(
         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 ||
@@ -72,14 +75,25 @@ async function submit(
           /^(Transaction failed on-chain:|Transaction failed:)/.test(
             result.error,
           ));
-      state = definitive
-        ? "failed"
-        : result.confirmed === true
-          ? "confirmed"
-          : "unknown";
+      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";
     }
-  } catch {
-    /* HTTP/RPC/timeout errors are ambiguous; no rebroadcast or rebuild. */
   }
   await j.event(id, {
     state,
@@ -160,7 +174,18 @@ export async function run(
   if (a.command === "recent") {
     const limit = integer(String(a.limit ?? "20"), 50);
     if (!limit) throw new Error("Positive limit required");
-    return t.sdk.signalsRecent(limit);
+    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);
@@ -222,7 +247,12 @@ export async function run(
     const bytes = decodeBase64(required(a, "signed-tx-base64"));
     if (bytes.length > 1232)
       throw new Error("Signed transaction exceeds packet limit");
-    const tx = VersionedTransaction.deserialize(bytes);
+    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);
@@ -286,7 +316,7 @@ export async function run(
   );
   const p = await t.pricing();
   const sendCredits = sendFee(p);
-  const estimate = side === "buy" ? estimateBuy(p, maxSol) : null;
+  const estimate = side === "buy" ? estimateBuy(p, amount) : null;
   const plan = {
     state: "plan",
     side,
@@ -330,6 +360,18 @@ export async function run(
     (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,
@@ -420,6 +462,7 @@ export async function run(
       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.",
     };

package/src/internal/journal.ts

@@ -112,12 +112,17 @@ export class Journal {
     }
   }
   async read(id: string): Promise<any> {
-    const start = JSON.parse(
-      await readFile(
-        join(this.directory, "operation-" + fingerprint(id) + ".json"),
-        "utf8",
-      ),
-    );
+    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(

package/src/internal/safety.ts

@@ -112,6 +112,8 @@ export function verifyUnsigned(
   ) {
     return verifyV2(tx, wallet, p);
   }
+  let sellToken: PublicKey | undefined, sellAta: PublicKey | undefined;
+  let closes = 0;
   let trades = 0,
     atas = 0,
     tradeCost = 0n;
@@ -196,6 +198,32 @@ export function verifyUnsigned(
           );
       } 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");

package/src/internal/transport.ts

@@ -29,7 +29,9 @@ export function estimateBuy(p: Pricing, lamports: bigint): number {
 }
 export function sendFee(p: Pricing): number {
   const m = p.methods?.sendAndConfirm;
-  const fee = finite(m?.base_credits) + finite(m?.landed_credits);
+  const base = finite(m?.base_credits);
+  // landed_credits is the terminal TOTAL, not a surcharge on base_credits.
+  const fee = Math.max(base, finite(m?.landed_credits));
   if (!Number.isSafeInteger(fee) || fee <= 0)
     throw new Error("Invalid sendAndConfirm live fee");
   return fee;
@@ -87,7 +89,6 @@ export class Transport {
       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", {