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

package/src/index.ts

@@ -0,0 +1,296 @@
+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 interface NodiusOptions {
+  apiKey?: string;
+  endpoint?: string;
+  journalDir: string;
+  allowExecution?: boolean;
+  ackIncompletePolicy?: boolean;
+}
+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 type SendInput = z.input<typeof sendSchema>;
+export type StatusInput = z.input<typeof statusSchema>;
+export type MonitorInput = z.input<typeof monitorSchema>;
+export type TradeInput = z.input<typeof tradeSchema>;
+export type NodiusResult = Record<string, unknown>;
+export function createNodiusPlugin(options: NodiusOptions) {
+  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: SolanaAgentKit | undefined;
+  const recent = z
+    .object({ limit: integer.min(1).max(50).default(20) })
+    .strict();
+  function clean(value: unknown): any {
+    const text = (s: string) =>
+      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: SolanaAgentKit,
+    input: unknown,
+    kind: "recent" | "trade" | "monitor" | "status" | "send",
+  ): Promise<NodiusResult> {
+    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: SolanaAgentKit,
+    input: unknown,
+    kind: "recent" | "trade" | "monitor" | "status" | "send",
+  ): Promise<NodiusResult> {
+    if (!owner || agent !== owner) throw Error("Plugin agent mismatch");
+    let args: 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: Record<string, string> = {
+        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: unknown[] = [];
+    let monitorPlan: Record<string, unknown> = {};
+    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: SendInput) => invoke(owner!, input, "send"),
+      nodiusStatus: (input: StatusInput) => invoke(owner!, input, "status"),
+      nodiusMonitor: (input: MonitorInput) => invoke(owner!, input, "monitor"),
+      nodiusRecent: (input: { limit?: number } = {}) =>
+        invoke(owner!, input, "recent"),
+      nodiusTrade: (input: TradeInput) => 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: SolanaAgentKit, i: unknown) => invoke(a, i, "send"),
+      },
+      {
+        name: "nodiusStatus",
+        similes: [],
+        description:
+          "Reconcile local operation status; never rebuild or rebroadcast",
+        examples: [],
+        schema: statusSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "status"),
+      },
+      {
+        name: "nodiusMonitor",
+        similes: [],
+        description:
+          "Paid bounded signal monitor (<=300s, <=1000 events); no autonomous trading",
+        examples: [],
+        schema: monitorSchema,
+        handler: (a: SolanaAgentKit, i: unknown) => invoke(a, i, "monitor"),
+      },
+      {
+        name: "nodiusRecent",
+        similes: [],
+        description: "Read recent Nodius signals; never trades",
+        examples: [],
+        schema: recent,
+        handler: (a: SolanaAgentKit, i: unknown) => 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: SolanaAgentKit, i: unknown) => invoke(a, i, "trade"),
+      },
+    ],
+    initialize(agent: SolanaAgentKit) {
+      if (owner && owner !== agent)
+        throw Error("Plugin instance already bound to another agent");
+      owner = agent;
+    },
+  } satisfies Plugin;
+  // 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: z.AnyZodObject = 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 as typeof action.schema;
+  }
+  return plugin;
+}