elizaos-plugin-solmachina 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SolMachina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# elizaos-plugin-solmachina
+
+Put the **SolMachina financial firewall** in front of an ElizaOS agent's trades — the "Guard Everywhere"
+pattern: before the agent executes a swap/buy, it asks SolMachina and proceeds **only on EXECUTE + policy ALLOW**.
+
+One `SOLMACHINA_GUARD` call returns **EXECUTE / REVIEW / REJECT** + a risk index (SMRI) + evidence + a **signed,
+time-boxed authorization** you can verify offline. Paid per call in USDC over **x402** (Solana + Base). No account.
+
+```bash
+npm i elizaos-plugin-solmachina
+```
+
+## Use it
+
+```js
+import { solmachinaPlugin } from "elizaos-plugin-solmachina";
+
+// Wire your agent's x402-capable fetch (built from its Solana/Base wallet) to enable LIVE paid decisions:
+const plugin = solmachinaPlugin({ payFetch, defaultPolicy: "conservative" });
+
+// ...register `plugin` in your ElizaOS agent's `plugins: [...]`.
+```
+
+Or the zero-config default (no wallet): the Guard action then returns the exact USDC **payment terms + guidance**
+instead of a decision — it **never fabricates a verdict** without a real, paid answer.
+
+```js
+import solmachina from "elizaos-plugin-solmachina"; // default export, no payFetch
+```
+
+## What the agent gets
+
+The `SOLMACHINA_GUARD` action (similes: `CHECK_TOKEN`, `PRE_TRADE_CHECK`, `SHOULD_I_BUY`, `FINANCIAL_FIREWALL`):
+- extracts the token mint from the message (or `options.mint`),
+- calls `GET /v1/decision?mint=…&policy=…`,
+- replies **✅ EXECUTE · SMRI 92 · ALLOW — safe to proceed** or **⛔ REJECT — do not proceed: <reasons>**,
+- returns structured `data: { allowed, decision, verdict, smri, authorization, evidence }` for your agent logic.
+
+A `SOLMACHINA_POLICY` provider injects the rule: *"before any swap/buy/transfer, call SOLMACHINA_GUARD and
+proceed only on EXECUTE + ALLOW."*
+
+## Config (`runtime.getSetting` / .env)
+
+| Setting | Meaning |
+|---|---|
+| `SOLMACHINA_BASE_URL` | API base (default `https://api.solmachina.com`) |
+| `SOLMACHINA_POLICY` | named firewall: `conservative` \| `bluechip` \| `anti-rug` \| `degen` |
+
+Payment is provided in code via `solmachinaPlugin({ payFetch })` (an x402 `fetch` from your agent's wallet — e.g.
+`wrapFetchWithPayment` from `x402-fetch`). Without it, Guard runs in "terms + guidance" mode.
+
+## Status (honest)
+
+Built to ElizaOS's **documented** plugin API (`Plugin` / `Action` / `Provider`, `runtime.getSetting`,
+`HandlerCallback`). The action's logic — mint extraction, verdict formatting, fail-closed "no fabricated verdict"
+behaviour — is covered by tests (`node --test index.test.mjs`, 7/7). **Not yet run inside a live ElizaOS agent
+runtime**: load it in a real agent and confirm the action fires before publishing. Pin your `@elizaos/core`
+version — the plugin API has evolved across major versions.
+
+## Links
+Docs: https://api.solmachina.com/docs · SDK: `solmachina-sdk` · MCP: `https://api.solmachina.com/mcp` ·
+registry: `io.github.imnotamob/solmachina-x402`. Not financial advice.

package/index.js

@@ -0,0 +1,121 @@
+// @elizaos/plugin-solmachina — put the SolMachina financial firewall in front of an ElizaOS agent's trades.
+//
+// "Guard Everywhere": before an autonomous agent executes a swap/buy, it calls SOLMACHINA_GUARD(mint) and
+// proceeds only on EXECUTE + policy ALLOW. One call returns EXECUTE / REVIEW / REJECT + a risk index + evidence
+// + a signed, time-boxed authorization (verify offline). Paid per call in USDC over x402 (Solana + Base).
+//
+// Built to ElizaOS's documented plugin API (Plugin / Action / Provider, runtime.getSetting). Loadable as ESM.
+// Payment: the real decision is a paid x402 call. Provide an x402-capable fetch (from your agent's wallet) via
+// `solmachinaPlugin({ payFetch })`; without one, the action returns the exact USDC terms + guidance instead of
+// a guessed verdict (honest — never fabricates a decision).
+
+const DEFAULT_BASE = "https://api.solmachina.com";
+const B58 = /[1-9A-HJ-NP-Za-km-z]{32,44}/; // first base58-looking run in free text
+const KNOWN_POLICIES = new Set(["conservative", "bluechip", "anti-rug", "degen"]);
+
+function decodeTerms(res) {
+  try {
+    const h = res.headers.get && res.headers.get("payment-required"); if (!h) return null;
+    const json = typeof atob === "function" ? atob(h) : Buffer.from(h, "base64").toString("utf8");
+    const t = JSON.parse(json);
+    return { resource: t?.resource?.url, accepts: (t?.accepts || []).map(a => ({ network: a.network, amount: a.amount, asset: a.asset, payTo: a.payTo })) };
+  } catch { return null; }
+}
+
+function extractMint(message, options) {
+  const fromOpts = options && (options.mint || options.token);
+  if (typeof fromOpts === "string" && fromOpts.trim()) return fromOpts.trim();
+  const text = (message && message.content && message.content.text) || "";
+  const m = String(text).match(B58);
+  return m ? m[0] : null;
+}
+
+/**
+ * Build the plugin. Pass an x402-capable `payFetch` (fetch(url,init) that handles 402→pay→retry, from your
+ * agent's Solana/Base wallet) to enable live paid Guard decisions. `baseUrl` and `defaultPolicy` optional.
+ * @param {{ payFetch?: Function, baseUrl?: string, defaultPolicy?: string }} [opts]
+ */
+export function solmachinaPlugin(opts = {}) {
+  const baseUrl = String(opts.baseUrl || DEFAULT_BASE).replace(/\/+$/, "");
+
+  const guard = {
+    name: "SOLMACHINA_GUARD",
+    similes: ["CHECK_TOKEN", "PRE_TRADE_CHECK", "TOKEN_DECISION", "FINANCIAL_FIREWALL", "VERIFY_TOKEN", "SHOULD_I_BUY"],
+    description: "Before executing a swap/buy on Solana/Base, ask SolMachina whether the token passes your risk policy. Returns EXECUTE/REVIEW/REJECT + risk index + a signed authorization. Proceed only on EXECUTE + ALLOW.",
+
+    validate: async (runtime, message) => {
+      // valid whenever we can find a token mint to assess (options or a base58 run in the text)
+      return !!extractMint(message, (message && message.content) || {});
+    },
+
+    handler: async (runtime, message, _state, options, callback) => {
+      const mint = extractMint(message, options);
+      if (!mint) {
+        if (callback) await callback({ text: "SolMachina Guard: no token mint found to assess. Provide a Solana/Base token mint.", actions: ["SOLMACHINA_GUARD"], source: message?.content?.source });
+        return { text: "no mint", success: false };
+      }
+      const policy = (options && options.policy) || runtime.getSetting("SOLMACHINA_POLICY") || opts.defaultPolicy;
+      const qs = new URLSearchParams({ mint });
+      if (policy && KNOWN_POLICIES.has(String(policy))) qs.set("policy", String(policy));
+      const url = `${baseUrl}/v1/decision?${qs.toString()}`;
+      const doFetch = typeof opts.payFetch === "function" ? opts.payFetch : (globalThis.fetch);
+
+      let res;
+      try { res = await doFetch(url, { headers: { accept: "application/json" } }); }
+      catch (e) {
+        const msg = "SolMachina Guard: could not reach the decision service (" + String(e?.message || e) + ").";
+        if (callback) await callback({ text: msg, actions: ["SOLMACHINA_GUARD"], source: message?.content?.source });
+        return { text: msg, success: false };
+      }
+
+      if (res.status === 402) {
+        const terms = decodeTerms(res);
+        const msg = `SolMachina Guard is a paid x402 decision (USDC, Solana + Base). Wire your agent's x402 wallet as \`payFetch\` to enable live Guard verdicts.${terms ? ` Terms: pay ${terms.accepts?.[0]?.amount} atomic USDC to ${terms.accepts?.[0]?.payTo} on ${terms.accepts?.[0]?.network}.` : ""}`;
+        if (callback) await callback({ text: msg, actions: ["SOLMACHINA_GUARD"], source: message?.content?.source });
+        return { text: msg, success: false, data: { paymentRequired: true, terms } };
+      }
+
+      let body = null; try { body = await res.json(); } catch { /* leave null */ }
+      if (!res.ok || !body || body.error) {
+        const msg = `SolMachina Guard: decision unavailable (${body?.error || ("http " + res.status)}).`;
+        if (callback) await callback({ text: msg, actions: ["SOLMACHINA_GUARD"], source: message?.content?.source });
+        return { text: msg, success: false, data: body || null };
+      }
+
+      const verdict = body.policy && body.policy.verdict;
+      const allowed = body.decision === "EXECUTE" && (verdict == null || verdict === "ALLOW");
+      const bits = [`SolMachina ${body.decision}`];
+      if (body.smri != null) bits.push(`SMRI ${body.smri}`);
+      if (verdict) bits.push(`policy ${verdict}`);
+      if (body.reason) bits.push(body.reason);
+      const failed = (body.policy && body.policy.failed) || [];
+      const line = allowed
+        ? `✅ ${bits.join(" · ")} — passes your policy. Safe to proceed (not financial advice; authorization valid until ${body.authorization?.notAfterUtc}).`
+        : `⛔ ${bits.join(" · ")} — DO NOT proceed.${failed.length ? " Failed: " + failed.join("; ") : ""}`;
+      if (callback) await callback({ text: line, actions: ["SOLMACHINA_GUARD"], source: message?.content?.source });
+      return { text: line, success: true, data: { allowed, decision: body.decision, verdict: verdict || null, smri: body.smri, authorization: body.authorization, evidence: body.evidence } };
+    },
+
+    examples: [[
+      { name: "{{user}}", content: { text: "Should I buy DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 ?" } },
+      { name: "{{agent}}", content: { text: "Let me run it through the SolMachina firewall first.", actions: ["SOLMACHINA_GUARD"] } },
+    ]],
+  };
+
+  const provider = {
+    name: "SOLMACHINA_POLICY",
+    description: "Reminds the agent to gate financially-sensitive actions through SolMachina Guard.",
+    get: async () => "Risk policy: before any swap, buy, or fund transfer on Solana/Base, call SOLMACHINA_GUARD(mint) and proceed ONLY on EXECUTE + policy ALLOW. Treat REVIEW/REJECT as stop.",
+  };
+
+  return {
+    name: "solmachina",
+    description: "SolMachina financial firewall for autonomous agents: EXECUTE/REVIEW/REJECT + signed authorization before a trade, paid per call in USDC over x402.",
+    actions: [guard],
+    providers: [provider],
+    services: [],
+  };
+}
+
+export const solmachinaPluginDefault = solmachinaPlugin();
+export default solmachinaPluginDefault;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "elizaos-plugin-solmachina",
+  "version": "0.1.0",
+  "description": "SolMachina financial firewall for ElizaOS agents — EXECUTE/REVIEW/REJECT + a signed, time-boxed authorization before a trade, paid per call in USDC over x402 (Solana + Base).",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "exports": { ".": { "import": "./index.js" } },
+  "files": ["index.js", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["elizaos", "elizaos-plugin", "eliza", "plugin", "solmachina", "x402", "solana", "base", "usdc", "ai-agents", "agent", "financial-firewall", "decision", "risk", "defi", "trading"],
+  "peerDependencies": { "@elizaos/core": ">=1.0.0" },
+  "peerDependenciesMeta": { "@elizaos/core": { "optional": true } },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "SOLMACHINA_BASE_URL": { "type": "string", "description": "SolMachina API base URL (default https://api.solmachina.com)", "required": false },
+      "SOLMACHINA_POLICY": { "type": "string", "description": "Named firewall policy: conservative | bluechip | anti-rug | degen", "required": false }
+    }
+  },
+  "homepage": "https://api.solmachina.com/docs",
+  "repository": { "type": "git", "url": "git+https://github.com/apisolmachina/elizaos-plugin-solmachina.git" },
+  "license": "MIT",
+  "author": "SolMachina"
+}