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

package/dist/internal/monitor.d.ts

@@ -0,0 +1,12 @@
+export interface MonitorOptions {
+    seconds: number;
+    maxFeeCredits?: number;
+    maxEvents: number;
+    filters: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export declare function monitor(origin: string, apiKey: string, o: MonitorOptions, emit: (v: any) => void): Promise<{
+    state: string;
+    events: number;
+    subscription: string;
+}>;

package/dist/internal/monitor.js

@@ -0,0 +1,122 @@
+import WebSocket from "ws";
+import { wsUrlFor } from "@nodiusxyz/sdk";
+import { Transport, finite } from "./transport.js";
+export async function monitor(origin, apiKey, o, emit) {
+    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;
+    const pending = new Map();
+    let end;
+    const done = new Promise((r) => (end = r));
+    let deadlineReject;
+    const deadline = new Promise((_, 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;
+        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, params) => new Promise((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((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;
+            try {
+                await Promise.race([
+                    call("signalUnsubscribe", [sub]),
+                    new Promise((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/dist/internal/safety.d.ts

@@ -0,0 +1,37 @@
+import { PublicKey, VersionedTransaction } from "@solana/web3.js";
+export declare const PUMP = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
+export declare function decodeBase64(s: string): Buffer;
+export declare function decodeBuilderUnsigned(encoded: string): VersionedTransaction;
+export declare function inspectEnvelope(tx: VersionedTransaction, wallet: PublicKey): {
+    signing_authorized: boolean;
+    instruction_count: number;
+    instructions: {
+        program: string;
+        accounts: {
+            address: string;
+            signer: boolean;
+            writable: boolean;
+        }[];
+        data_hex: string;
+    }[];
+    note: string;
+};
+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 declare function verifyUnsigned(tx: VersionedTransaction, wallet: PublicKey, p: Policy): {
+    tradeCost: bigint;
+    ataCount: number;
+    instructions: any[];
+    limitations: string;
+};
+export declare function checkSignature(tx: VersionedTransaction): string;

package/dist/internal/safety.js

@@ -0,0 +1,199 @@
+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) {
+    const b = Buffer.from(s, "base64");
+    if (!s || b.toString("base64") !== s)
+        throw new Error("Noncanonical base64");
+    return b;
+}
+export function decodeBuilderUnsigned(encoded) {
+    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, wallet) {
+    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 function verifyUnsigned(tx, wallet, p) {
+    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, sellAta;
+    let closes = 0;
+    let trades = 0, atas = 0, tradeCost = 0n;
+    const instructions = [];
+    const seenCompute = new Set();
+    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) {
+    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/dist/internal/transport.d.ts

@@ -0,0 +1,23 @@
+import { NodiusClient } from "@nodiusxyz/sdk";
+import { Connection } from "@solana/web3.js";
+export interface Pricing {
+    ok?: boolean;
+    credits_per_usdc: number;
+    sol_usdc: {
+        price: number;
+        age_secs: number;
+    } | null;
+    methods: Record<string, any>;
+}
+export declare function finite(n: unknown): number;
+export declare function estimateBuy(p: Pricing, lamports: bigint): number;
+export declare function sendFee(p: Pricing): number;
+export declare class Transport {
+    private readonly apiKey?;
+    readonly sdk: NodiusClient;
+    readonly connection: Connection;
+    readonly origin: string;
+    constructor(origin: string, apiKey?: string | undefined);
+    pricing(): Promise<Pricing>;
+    sell(mint: string, amount: string, slippage: number, priority: number): Promise<any>;
+}

package/dist/internal/transport.js

@@ -0,0 +1,97 @@
+import { NodiusClient } from "@nodiusxyz/sdk";
+import { Connection } from "@solana/web3.js";
+import { endpoint, rawAmount } from "./config.js";
+export function finite(n) {
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 0)
+        throw new Error("Invalid live numeric field");
+    return n;
+}
+export function estimateBuy(p, lamports) {
+    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) {
+    const m = p.methods?.sendAndConfirm;
+    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;
+}
+export class Transport {
+    apiKey;
+    sdk;
+    connection;
+    origin;
+    constructor(origin, apiKey) {
+        this.apiKey = apiKey;
+        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() {
+        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());
+        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, amount, slippage, priority) {
+        rawAmount(amount);
+        const params = JSON.stringify({
+            mint,
+            slippage_bps: slippage,
+            priority_fee_micro_lamports: priority,
+        });
+        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());
+        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;
+    }
+}

package/dist/internal/v2-policy.d.ts

@@ -0,0 +1,19 @@
+import { PublicKey, VersionedTransaction } from "@solana/web3.js";
+export interface V2Policy {
+    side: "buy" | "sell";
+    mint: PublicKey;
+    maxSol: bigint;
+    amountRaw?: bigint;
+    maxPriority: bigint;
+    maxPriorityLamports?: bigint;
+    requestedPriority?: bigint;
+    reportedCost: bigint;
+    tokensOut?: bigint;
+}
+/** Offline instruction policy only. Never signs, mutates or fetches account state. */
+export declare function verifyV2(tx: VersionedTransaction, wallet: PublicKey, p: V2Policy): {
+    tradeCost: bigint;
+    ataCount: number;
+    instructions: any[];
+    limitations: string;
+};