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

package/dist/index.js

@@ -0,0 +1,277 @@
+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 = {
+    mint: z.string().min(32).max(44),
+    maxSol: decimal,
+    maxFeeCredits: integer,
+    slippageBps: integer.max(9999),
+    priorityFee: integer,
+    maxPriorityFee: integer,
+    maxPriorityLamports: integer.optional(),
+    execute: z.boolean().default(false),
+    buildOnly: z.boolean().default(false),
+    operationId: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,80}$/)
+        .optional(),
+    acceptUnquotedBuildCharge: z.boolean().default(false),
+};
+export const tradeSchema = z.discriminatedUnion("side", [
+    z.object({ ...base, side: z.literal("buy"), amountSol: decimal }).strict(),
+    z
+        .object({
+        ...base,
+        side: z.literal("sell"),
+        amountRaw: z.string().regex(/^[1-9]\d*$/),
+    })
+        .strict(),
+]);
+const tradeActionSchema = z
+    .object({
+    ...base,
+    side: z.enum(["buy", "sell"]),
+    amountSol: decimal.optional(),
+    amountRaw: z
+        .string()
+        .regex(/^[1-9]\d*$/)
+        .optional(),
+})
+    .strict();
+export const monitorSchema = z
+    .object({
+    maxFeeCredits: integer,
+    seconds: integer.min(1).max(300).default(30),
+    maxEvents: integer.min(1).max(1000).default(100),
+    mint: z.string().min(32).max(44).optional(),
+    kinds: z
+        .array(z.enum(["newPair", "graduation", "walletActivity", "largeSwap"]))
+        .min(1)
+        .max(4)
+        .optional(),
+})
+    .strict();
+export const statusSchema = z
+    .object({ operationId: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/) })
+    .strict();
+export const sendSchema = z
+    .object({
+    signedTxBase64: z.string().min(1).max(1644),
+    maxFeeCredits: integer,
+    execute: z.boolean().default(false),
+    operationId: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,80}$/)
+        .optional(),
+})
+    .strict();
+export function createNodiusPlugin(options) {
+    const parsed = z
+        .object({
+        apiKey: z
+            .string()
+            .min(1)
+            .regex(/^[^\r\n]+$/)
+            .optional(),
+        endpoint: z.string().optional(),
+        journalDir: z.string().min(1),
+        allowExecution: z.boolean().default(false),
+        ackIncompletePolicy: z.boolean().default(false),
+    })
+        .strict()
+        .parse(options);
+    const o = Object.freeze({
+        ...parsed,
+        endpoint: validateEndpoint(parsed.endpoint ?? "https://rpc.nodius.xyz"),
+    });
+    let owner;
+    const recent = z
+        .object({ limit: integer.min(1).max(50).default(20) })
+        .strict();
+    function clean(value) {
+        const text = (s) => o.apiKey ? s.split(o.apiKey).join("[REDACTED]") : s;
+        if (typeof value === "string")
+            return text(value);
+        if (typeof value === "bigint")
+            return value.toString();
+        if (Array.isArray(value))
+            return value.map(clean);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => [text(k), clean(v)]));
+        return value;
+    }
+    async function invoke(agent, input, kind) {
+        try {
+            return clean(await dispatch(agent, input, kind));
+        }
+        catch (e) {
+            throw new Error(clean(e instanceof Error ? e.message : String(e)));
+        }
+    }
+    async function dispatch(agent, input, kind) {
+        if (!owner || agent !== owner)
+            throw Error("Plugin agent mismatch");
+        let args = {
+            command: kind,
+            endpoint: o.endpoint ?? "https://rpc.nodius.xyz",
+            journal: o.journalDir,
+        };
+        if (kind === "recent") {
+            const v = recent.parse(input);
+            args.limit = String(v.limit);
+        }
+        else if (kind === "send") {
+            const v = sendSchema.parse(input);
+            if (v.execute && o.allowExecution !== true)
+                throw Error("Host execution is disabled");
+            if (v.execute && o.ackIncompletePolicy !== true)
+                throw Error("Host incomplete policy acknowledgement required");
+            args["signed-tx-base64"] = v.signedTxBase64;
+            args.wallet = owner.wallet.publicKey.toBase58();
+            args["max-fee-credits"] = String(v.maxFeeCredits);
+            args.execute = v.execute;
+            if (v.operationId)
+                args["operation-id"] = v.operationId;
+        }
+        else if (kind === "status") {
+            const v = statusSchema.parse(input);
+            args["operation-id"] = v.operationId;
+        }
+        else if (kind === "monitor") {
+            const v = monitorSchema.parse(input);
+            args["max-fee-credits"] = String(v.maxFeeCredits);
+            args.seconds = String(v.seconds);
+            args["max-events"] = String(v.maxEvents);
+            if (v.mint)
+                args.mint = v.mint;
+            if (v.kinds)
+                args.kinds = v.kinds.join(",");
+        }
+        else {
+            const v = tradeSchema.parse(input);
+            if (v.execute && o.allowExecution !== true)
+                throw Error("Host execution is disabled");
+            if (v.execute && !v.buildOnly && o.ackIncompletePolicy !== true)
+                throw Error("Host incomplete policy acknowledgement required");
+            args.command = v.side;
+            args.wallet = owner.wallet.publicKey.toBase58();
+            const map = {
+                amountSol: "amount-sol",
+                amountRaw: "amount-raw",
+                maxSol: "max-sol",
+                maxFeeCredits: "max-fee-credits",
+                slippageBps: "slippage-bps",
+                priorityFee: "priority-fee",
+                maxPriorityFee: "max-priority-fee",
+                maxPriorityLamports: "max-priority-lamports",
+                operationId: "operation-id",
+                buildOnly: "build-only",
+                acceptUnquotedBuildCharge: "accept-unquoted-build-charge",
+            };
+            for (const [k, value] of Object.entries(v)) {
+                if (k === "side")
+                    continue;
+                args[map[k] ?? k] = typeof value === "boolean" ? value : String(value);
+            }
+            args["ack-incomplete-policy"] = o.ackIncompletePolicy === true;
+        }
+        const notifications = [];
+        let monitorPlan = {};
+        const result = await run(args, { NODIUS_API_KEY: o.apiKey }, (v) => {
+            if (kind === "monitor") {
+                if (v.state === "monitor-plan")
+                    monitorPlan = v;
+                else
+                    notifications.push(v);
+            }
+        }, {
+            publicKey: owner.wallet.publicKey,
+            signTransaction: (tx) => owner.wallet.signTransaction(tx),
+        });
+        return kind === "monitor"
+            ? { ...monitorPlan, ...result, notifications }
+            : result;
+    }
+    const plugin = {
+        name: "nodius",
+        methods: {
+            nodiusSend: (input) => invoke(owner, input, "send"),
+            nodiusStatus: (input) => invoke(owner, input, "status"),
+            nodiusMonitor: (input) => invoke(owner, input, "monitor"),
+            nodiusRecent: (input = {}) => invoke(owner, input, "recent"),
+            nodiusTrade: (input) => invoke(owner, input, "trade"),
+        },
+        actions: [
+            {
+                name: "nodiusSend",
+                similes: [],
+                description: "Submit independently reviewed, already signed own-wallet transaction. Defaults plan; no trade instruction proof. Requires both host permissions.",
+                examples: [],
+                schema: sendSchema,
+                handler: (a, i) => invoke(a, i, "send"),
+            },
+            {
+                name: "nodiusStatus",
+                similes: [],
+                description: "Reconcile local operation status; never rebuild or rebroadcast",
+                examples: [],
+                schema: statusSchema,
+                handler: (a, i) => invoke(a, i, "status"),
+            },
+            {
+                name: "nodiusMonitor",
+                similes: [],
+                description: "Paid bounded signal monitor (<=300s, <=1000 events); no autonomous trading",
+                examples: [],
+                schema: monitorSchema,
+                handler: (a, i) => invoke(a, i, "monitor"),
+            },
+            {
+                name: "nodiusRecent",
+                similes: [],
+                description: "Read recent Nodius signals; never trades",
+                examples: [],
+                schema: recent,
+                handler: (a, i) => invoke(a, i, "recent"),
+            },
+            {
+                name: "nodiusTrade",
+                similes: [],
+                description: "Buy/sell defaults to read-only plan. Host must separately authorize charged execution and partial policy.",
+                examples: [],
+                schema: tradeActionSchema,
+                handler: (a, i) => invoke(a, i, "trade"),
+            },
+        ],
+        initialize(agent) {
+            if (owner && owner !== agent)
+                throw Error("Plugin instance already bound to another agent");
+            owner = agent;
+        },
+    };
+    // Keep ZodObject identity for the published tool converters, but sanitize
+    // validation issues before the framework's pre-handler executor surfaces them.
+    for (const action of plugin.actions) {
+        const schema = action.schema.strict();
+        const sync = schema.safeParse.bind(schema), asyncParse = schema.safeParseAsync.bind(schema);
+        schema.safeParse = (data, params) => {
+            const r = sync(data, params);
+            return r.success
+                ? r
+                : { success: false, error: new z.ZodError(clean(r.error.issues)) };
+        };
+        schema.safeParseAsync = async (data, params) => {
+            const r = await asyncParse(data, params);
+            return r.success
+                ? r
+                : { success: false, error: new z.ZodError(clean(r.error.issues)) };
+        };
+        action.schema = schema;
+    }
+    return plugin;
+}

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.d.ts

@@ -0,0 +1,6 @@
+import { PublicKey, VersionedTransaction } from "@solana/web3.js";
+import { Args } from "./config.js";
+export declare function run(a: Args, env?: NodeJS.ProcessEnv, emit?: (v: any) => void, bridge?: {
+    publicKey: PublicKey;
+    signTransaction(tx: VersionedTransaction): Promise<VersionedTransaction>;
+}): Promise<any>;