@jhinresh/elizaos-plugin 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,66 @@
+# @jhinresh/elizaos-plugin
+
+> Maiat Trust Score plugin for ElizaOS — verify trust before your agent swaps or transacts.
+
+Adds trust-checking actions and evaluators to any ElizaOS agent so it can **refuse to interact with low-trust addresses** before executing swaps, transfers, or on-chain actions.
+
+Powered by [Maiat Protocol](https://maiat-protocol.vercel.app) — on-chain verified trust scores for tokens, DeFi protocols, and AI agents on Base.
+
+## Install
+
+```bash
+npm install @jhinresh/elizaos-plugin
+```
+
+## Usage
+
+```typescript
+import { maiatPlugin } from "@jhinresh/elizaos-plugin";
+
+const agent = new ElizaAgent({
+  plugins: [
+    maiatPlugin({
+      minScore: 3.0,   // reject addresses with score < 3.0/10
+      chain: "base",
+    }),
+  ],
+});
+```
+
+## What it does
+
+| Component | Type | Behaviour |
+|-----------|------|-----------|
+| `CHECK_TRUST` | Action | Agent can ask "is 0x... safe?" and get a trust score |
+| `TRUST_GATE` | Evaluator | Runs before any swap/transfer — rejects low-trust addresses |
+| `TRUST_DATA` | Provider | Injects trust context into agent's world state |
+
+## Trust Score Scale
+
+| Score | Risk | Action |
+|-------|------|--------|
+| 7–10 | 🟢 Low | Allow |
+| 4–6.9 | 🟡 Medium | Warn |
+| 0–3.9 | 🔴 High | **Block** |
+
+## Config
+
+```typescript
+maiatPlugin({
+  apiUrl: "https://maiat-protocol.vercel.app",  // default
+  apiKey: "your-key",   // optional — free tier: 100 req/day
+  minScore: 3.0,        // 0–10 scale
+  chain: "base",        // base | bnb | solana
+})
+```
+
+## Links
+
+- 🌐 [Live app](https://maiat-protocol.vercel.app)
+- 📖 [API docs](https://maiat-protocol.vercel.app/docs)
+- 🔗 [GitHub](https://github.com/JhiNResH/maiat-protocol)
+- 📦 [npm](https://www.npmjs.com/package/@jhinresh/elizaos-plugin)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @maiat/elizaos-plugin
+ *
+ * Maiat Trust Score plugin for ElizaOS (ai16z agent framework).
+ *
+ * Adds trust checking capabilities to any ElizaOS agent:
+ * - "Is this address safe?" → trust score lookup
+ * - Auto-gate transactions before execution
+ * - Report transaction outcomes back to Maiat
+ *
+ * @example
+ * ```typescript
+ * import { maiatPlugin } from "@maiat/elizaos-plugin";
+ *
+ * const agent = new ElizaAgent({
+ *   plugins: [maiatPlugin({ minScore: 3.0 })],
+ * });
+ * ```
+ */
+export interface MaiatElizaConfig {
+    apiUrl?: string;
+    apiKey?: string;
+    chain?: string;
+    minScore?: number;
+}
+interface TrustResult {
+    address: string;
+    score: number;
+    risk: string;
+    type: string;
+    flags: string[];
+    safe: boolean;
+}
+/**
+ * ElizaOS plugin definition following the standard plugin interface.
+ *
+ * Registers:
+ * - Action: CHECK_TRUST — responds to "is 0x... safe?" type queries
+ * - Evaluator: TRUST_GATE — evaluates if an address should be interacted with
+ * - Provider: TRUST_DATA — provides trust context for agent reasoning
+ */
+export declare function maiatPlugin(config?: MaiatElizaConfig): {
+    name: string;
+    description: string;
+    actions: {
+        name: string;
+        description: string;
+        examples: string[];
+        validate: (message: string) => Promise<boolean>;
+        handler: (message: string) => Promise<{
+            text: string;
+            data?: undefined;
+        } | {
+            text: string;
+            data: TrustResult;
+        }>;
+    }[];
+    evaluators: {
+        name: string;
+        description: string;
+        handler: (context: {
+            address?: string;
+        }) => Promise<{
+            pass: boolean;
+            reason: string;
+            score?: undefined;
+            risk?: undefined;
+        } | {
+            pass: boolean;
+            score: number;
+            risk: string;
+            reason: string;
+        }>;
+    }[];
+    providers: {
+        name: string;
+        description: string;
+        handler: () => Promise<{
+            text: string;
+        }>;
+    }[];
+};
+export default maiatPlugin;

package/dist/index.js

@@ -0,0 +1,130 @@
+/**
+ * @maiat/elizaos-plugin
+ *
+ * Maiat Trust Score plugin for ElizaOS (ai16z agent framework).
+ *
+ * Adds trust checking capabilities to any ElizaOS agent:
+ * - "Is this address safe?" → trust score lookup
+ * - Auto-gate transactions before execution
+ * - Report transaction outcomes back to Maiat
+ *
+ * @example
+ * ```typescript
+ * import { maiatPlugin } from "@maiat/elizaos-plugin";
+ *
+ * const agent = new ElizaAgent({
+ *   plugins: [maiatPlugin({ minScore: 3.0 })],
+ * });
+ * ```
+ */
+// ═══════════════════════════════════════════
+//  API Client (lightweight)
+// ═══════════════════════════════════════════
+async function queryMaiat(address, config) {
+    const apiUrl = config.apiUrl || "https://maiat-protocol.vercel.app";
+    const chain = config.chain || "base";
+    const minScore = config.minScore ?? 3.0;
+    const headers = {
+        "User-Agent": "maiat-elizaos-plugin/0.1.0",
+    };
+    if (config.apiKey)
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    const res = await fetch(`${apiUrl}/api/v1/score/${address}?chain=${chain}`, { headers });
+    if (!res.ok) {
+        throw new Error(`Maiat API error: ${res.status}`);
+    }
+    const data = await res.json();
+    return {
+        address: data.address,
+        score: data.score,
+        risk: data.risk,
+        type: data.type,
+        flags: data.flags || [],
+        safe: data.score >= minScore,
+    };
+}
+// ═══════════════════════════════════════════
+//  ElizaOS Plugin
+// ═══════════════════════════════════════════
+/**
+ * ElizaOS plugin definition following the standard plugin interface.
+ *
+ * Registers:
+ * - Action: CHECK_TRUST — responds to "is 0x... safe?" type queries
+ * - Evaluator: TRUST_GATE — evaluates if an address should be interacted with
+ * - Provider: TRUST_DATA — provides trust context for agent reasoning
+ */
+export function maiatPlugin(config = {}) {
+    return {
+        name: "maiat-trust",
+        description: "Trust scoring for on-chain addresses via Maiat Protocol",
+        actions: [
+            {
+                name: "CHECK_TRUST",
+                description: "Check the trust score of an on-chain address",
+                examples: [
+                    "Is 0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24 safe?",
+                    "Check trust score for 0x1234...",
+                    "Should I interact with this address: 0xabcd...?",
+                ],
+                validate: async (message) => {
+                    return /0x[a-fA-F0-9]{40}/.test(message);
+                },
+                handler: async (message) => {
+                    const match = message.match(/0x[a-fA-F0-9]{40}/);
+                    if (!match)
+                        return { text: "Please provide a valid Ethereum address (0x...)" };
+                    try {
+                        const result = await queryMaiat(match[0], config);
+                        const emoji = result.safe ? "🟢" : result.risk === "CRITICAL" ? "🔴" : "🟡";
+                        return {
+                            text: `${emoji} **Trust Score: ${result.score}/10** (${result.risk} risk)\n\nAddress: \`${result.address}\`\nType: ${result.type}\nFlags: ${result.flags.join(", ") || "None"}\n\n${result.safe ? "✅ Safe to interact." : "⚠️ Exercise caution — low trust score."}`,
+                            data: result,
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            text: `❌ Could not check trust score: ${error instanceof Error ? error.message : "Unknown error"}`,
+                        };
+                    }
+                },
+            },
+        ],
+        evaluators: [
+            {
+                name: "TRUST_GATE",
+                description: "Evaluates if a target address meets minimum trust requirements",
+                handler: async (context) => {
+                    if (!context.address)
+                        return { pass: true, reason: "No address to check" };
+                    try {
+                        const result = await queryMaiat(context.address, config);
+                        return {
+                            pass: result.safe,
+                            score: result.score,
+                            risk: result.risk,
+                            reason: result.safe
+                                ? `Address trusted (${result.score}/10)`
+                                : `Address untrusted (${result.score}/10, ${result.risk} risk)`,
+                        };
+                    }
+                    catch {
+                        return { pass: false, reason: "Trust check failed — blocking by default" };
+                    }
+                },
+            },
+        ],
+        providers: [
+            {
+                name: "TRUST_DATA",
+                description: "Provides trust scoring context for agent reasoning",
+                handler: async () => {
+                    return {
+                        text: "You have access to Maiat trust scoring. Before interacting with any unknown on-chain address, use CHECK_TRUST to verify it's safe. Addresses scoring below 3.0/10 should be avoided.",
+                    };
+                },
+            },
+        ],
+    };
+}
+export default maiatPlugin;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jhinresh/elizaos-plugin",
-  "version": "0.1.0",
-  "description": "Maiat Trust Score plugin for ElizaOS — trust-gated agent interactions",
+  "version": "0.1.2",
+  "description": "Maiat Trust Score plugin for ElizaOS — verify trust before your agent swaps or transacts",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -10,8 +10,23 @@
     "build": "tsc",
     "dev": "tsc --watch"
   },
+  "keywords": [
+    "maiat",
+    "elizaos",
+    "eliza",
+    "ai16z",
+    "trust-score",
+    "ai-agent",
+    "web3",
+    "defi",
+    "base"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JhiNResH/elizaos-plugin-maiat.git"
+  },
+  "homepage": "https://maiat-protocol.vercel.app",
   "devDependencies": {
     "typescript": "^5.5.0"
-  },
-  "keywords": ["maiat", "elizaos", "ai16z", "trust-score", "ai-agent"]
+  }
 }