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

package/dist/internal/config.js

@@ -0,0 +1,106 @@
+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 = {
+    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) {
+    const command = argv[0] ?? "help";
+    if (!(command in flags))
+        throw new Error("Unknown command");
+    const out = { 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, k) {
+    const v = a[k];
+    if (typeof v !== "string" || !v)
+        throw new Error("Required --" + k);
+    return v;
+}
+export function integer(s, max = Number.MAX_SAFE_INTEGER) {
+    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) {
+    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) {
+    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) {
+    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/dist/internal/journal.d.ts

@@ -0,0 +1,13 @@
+export declare function fingerprint(value: unknown): string;
+export declare function outcome(status: any): "confirmed" | "failed" | "unknown";
+export declare class Journal {
+    readonly directory: string;
+    private readonly credential?;
+    constructor(directory: string, credential?: string | undefined);
+    private encode;
+    private reserve;
+    begin(id: string, hash: string, metadata: unknown): Promise<void>;
+    reserveSignature(signature: string): Promise<void>;
+    event(id: string, event: Record<string, unknown>): Promise<void>;
+    read(id: string): Promise<any>;
+}

package/dist/internal/journal.js

@@ -0,0 +1,129 @@
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+export function fingerprint(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export function outcome(status) {
+    if (status?.err != null)
+        return "failed";
+    if (status?.confirmationStatus === "confirmed" ||
+        status?.confirmationStatus === "finalized")
+        return "confirmed";
+    return "unknown";
+}
+export class Journal {
+    directory;
+    credential;
+    constructor(directory, credential) {
+        this.directory = directory;
+        this.credential = credential;
+    }
+    encode(value) {
+        const scrub = (v) => {
+            const text = (s) => 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));
+    }
+    async reserve(kind, key, value) {
+        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, hash, metadata) {
+        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;
+            try {
+                existing = JSON.parse(await readFile(path, "utf8"));
+            }
+            catch (e) {
+                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) {
+        await this.reserve("signature", signature, { signature });
+    }
+    async event(id, event) {
+        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) {
+        const start = JSON.parse(await readFile(join(this.directory, "operation-" + fingerprint(id) + ".json"), "utf8"));
+        let text = "";
+        try {
+            text = await readFile(join(this.directory, "events-" + fingerprint(id) + ".jsonl"), "utf8");
+        }
+        catch (e) {
+            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/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,175 @@
+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 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");
+        }
+        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>;
+}