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

package/dist/index.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { run } from "./internal/app.js";
+import { endpoint as validateEndpoint } from "./internal/config.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/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>;

package/dist/internal/app.js

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

package/dist/internal/config.d.ts

@@ -0,0 +1,10 @@
+export type Args = {
+    command: string;
+    [key: string]: string | boolean;
+};
+export declare function parseArgs(argv: string[]): Args;
+export declare function required(a: Args, k: string): string;
+export declare function integer(s: string, max?: number): number;
+export declare function rawAmount(s: string): bigint;
+export declare function solLamports(s: string): bigint;
+export declare function endpoint(s: string): string;