@jhinresh/agentkit-plugin 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @maiat/agentkit-plugin
+
+> Trust-gated transactions for Coinbase AgentKit agents
+
+Automatically check trust scores before every transaction. Block interactions with untrusted addresses. One line to integrate.
+
+## Install
+
+```bash
+npm install @maiat/agentkit-plugin
+```
+
+## Quick Start
+
+```typescript
+import { AgentKit } from "@coinbase/agentkit";
+import { maiatTrustPlugin } from "@maiat/agentkit-plugin";
+
+const agent = new AgentKit({
+  // your config
+});
+
+// Add Maiat trust gating
+agent.use(maiatTrustPlugin({
+  minScore: 3.0,  // Block addresses below 3.0/10
+  chain: "base",
+  onBlocked: (addr, score, risk) => {
+    console.log(`🔴 Blocked ${addr}: ${score}/10 (${risk})`);
+  },
+}));
+```
+
+## How It Works
+
+1. Agent wants to interact with address `0x1234...`
+2. Plugin queries Maiat API: `GET /v1/score/0x1234...`
+3. Score ≥ minScore → ✅ transaction proceeds
+4. Score < minScore → ❌ `MaiatTrustError` thrown, transaction blocked
+
+## Actions
+
+### `maiat_check_trust`
+Check trust score for any address.
+
+```typescript
+const result = await agent.run("Check if 0x4752... is trustworthy");
+// → { score: 8.5, risk: "LOW", safe: true, ... }
+```
+
+### `maiat_gate_transaction`
+Pre-flight check before executing a transaction.
+
+```typescript
+// Automatically called before transactions when plugin is active
+// Throws MaiatTrustError if target is untrusted
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `minScore` | `3.0` | Minimum trust score (0-10) |
+| `apiUrl` | `https://maiat-protocol.vercel.app` | API endpoint |
+| `apiKey` | (none) | API key for higher limits |
+| `chain` | `base` | Default chain |
+| `warnOnly` | `false` | Log warnings instead of blocking |
+| `onBlocked` | (none) | Callback when transaction blocked |
+| `onCheck` | (none) | Callback for every check |
+
+## Standalone Client
+
+```typescript
+import { MaiatClient } from "@maiat/agentkit-plugin";
+
+const maiat = new MaiatClient({ chain: "base" });
+
+const result = await maiat.checkTrust("0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24");
+console.log(result.score, result.risk); // 8.5 "LOW"
+
+// Batch check
+const results = await maiat.batchCheck(["0x1234...", "0x5678..."]);
+```
+
+## x402 Integration
+
+Works seamlessly with Coinbase's x402 protocol for agent-to-agent payments:
+
+```typescript
+import { maiatTrustPlugin } from "@maiat/agentkit-plugin";
+
+// Agent automatically checks trust before paying via x402
+const plugin = maiatTrustPlugin({
+  minScore: 5.0,  // Higher threshold for payments
+  onBlocked: (addr, score) => {
+    console.log(`Payment to ${addr} blocked — trust score ${score}/10`);
+  },
+});
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@jhinresh/agentkit-plugin",
+  "version": "0.1.0",
+  "description": "Maiat Trust Score plugin for Coinbase AgentKit — auto-check trust before every transaction",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@coinbase/agentkit": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "keywords": ["maiat", "agentkit", "coinbase", "trust-score", "ai-agent", "web3", "x402"]
+}

package/src/index.ts

@@ -0,0 +1,241 @@
+/**
+ * @maiat/agentkit-plugin
+ * 
+ * Coinbase AgentKit plugin that adds trust scoring to every agent transaction.
+ * 
+ * Usage:
+ * ```typescript
+ * import { AgentKit } from "@coinbase/agentkit";
+ * import { maiatTrustPlugin } from "@maiat/agentkit-plugin";
+ * 
+ * const agent = new AgentKit({ ... });
+ * agent.use(maiatTrustPlugin({ minScore: 3.0 }));
+ * 
+ * // Now every transaction auto-checks trust before executing
+ * // Addresses below minScore are blocked automatically
+ * ```
+ */
+
+// ═══════════════════════════════════════════
+//  Types
+// ═══════════════════════════════════════════
+
+export interface MaiatPluginConfig {
+  /** Minimum trust score (0-10) to allow transactions. Default: 3.0 */
+  minScore?: number;
+  /** Maiat API base URL. Default: https://maiat-protocol.vercel.app */
+  apiUrl?: string;
+  /** API key for higher rate limits */
+  apiKey?: string;
+  /** Chain to check. Default: base */
+  chain?: string;
+  /** If true, log warnings but don't block. Default: false */
+  warnOnly?: boolean;
+  /** Callback when a transaction is blocked */
+  onBlocked?: (address: string, score: number, risk: string) => void;
+  /** Callback for every trust check */
+  onCheck?: (address: string, score: number, risk: string) => void;
+}
+
+export interface TrustScoreResult {
+  address: string;
+  score: number;
+  risk: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+  type: string;
+  flags: string[];
+  breakdown: {
+    onChainHistory: number;
+    contractAnalysis: number;
+    blacklistCheck: number;
+    activityPattern: number;
+  };
+  details: {
+    txCount: number;
+    balanceETH: number;
+    isContract: boolean;
+    walletAge: string | null;
+    lastActive: string | null;
+  };
+  protocol?: {
+    name: string;
+    category: string;
+    auditedBy?: string[];
+  };
+}
+
+export class MaiatTrustError extends Error {
+  constructor(
+    public address: string,
+    public score: number,
+    public risk: string,
+    public minScore: number,
+  ) {
+    super(
+      `Maiat: Transaction blocked — address ${address} has trust score ${score}/10 (${risk} risk), minimum required: ${minScore}`
+    );
+    this.name = "MaiatTrustError";
+  }
+}
+
+// ═══════════════════════════════════════════
+//  API Client
+// ═══════════════════════════════════════════
+
+export class MaiatClient {
+  private apiUrl: string;
+  private apiKey: string;
+  private chain: string;
+  private cache: Map<string, { result: TrustScoreResult; expiresAt: number }> = new Map();
+
+  constructor(config: Pick<MaiatPluginConfig, "apiUrl" | "apiKey" | "chain"> = {}) {
+    this.apiUrl = config.apiUrl || "https://maiat-protocol.vercel.app";
+    this.apiKey = config.apiKey || "";
+    this.chain = config.chain || "base";
+  }
+
+  async checkTrust(address: string, chain?: string): Promise<TrustScoreResult> {
+    const cacheKey = `${address}:${chain || this.chain}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.result;
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "User-Agent": "maiat-agentkit-plugin/0.1.0",
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    const url = `${this.apiUrl}/api/v1/score/${address}?chain=${chain || this.chain}`;
+    const res = await fetch(url, { headers });
+
+    if (!res.ok) {
+      throw new Error(`Maiat API error (${res.status}): ${await res.text()}`);
+    }
+
+    const result: TrustScoreResult = await res.json();
+
+    // Cache for 5 minutes
+    this.cache.set(cacheKey, { result, expiresAt: Date.now() + 5 * 60 * 1000 });
+
+    return result;
+  }
+
+  async batchCheck(addresses: string[], chain?: string): Promise<TrustScoreResult[]> {
+    return Promise.all(addresses.map((addr) => this.checkTrust(addr, chain)));
+  }
+
+  isSafe(score: number, minScore: number = 3.0): boolean {
+    return score >= minScore;
+  }
+}
+
+// ═══════════════════════════════════════════
+//  AgentKit Plugin Interface
+// ═══════════════════════════════════════════
+
+/**
+ * AgentKit plugin action definitions.
+ * These are the tools/actions that the agent can use.
+ */
+export function maiatTrustActions(config: MaiatPluginConfig = {}) {
+  const client = new MaiatClient(config);
+  const minScore = config.minScore ?? 3.0;
+
+  return [
+    {
+      name: "maiat_check_trust",
+      description: `Check the trust score of an on-chain address using Maiat. Returns a 0-10 score with risk assessment. Addresses scoring below ${minScore} are considered unsafe.`,
+      schema: {
+        type: "object" as const,
+        properties: {
+          address: { type: "string", description: "On-chain address to check (0x...)" },
+          chain: { type: "string", description: "Chain: base, ethereum, bnb. Default: base" },
+        },
+        required: ["address"],
+      },
+      handler: async (params: { address: string; chain?: string }) => {
+        const result = await client.checkTrust(params.address, params.chain);
+        config.onCheck?.(result.address, result.score, result.risk);
+
+        const safe = client.isSafe(result.score, minScore);
+        return {
+          score: result.score,
+          risk: result.risk,
+          type: result.type,
+          flags: result.flags,
+          safe,
+          breakdown: result.breakdown,
+          details: result.details,
+          protocol: result.protocol,
+          recommendation: safe
+            ? `✅ Address is trusted (${result.score}/10). Safe to proceed.`
+            : `⚠️ Address has low trust (${result.score}/10, ${result.risk} risk). ${config.warnOnly ? "Proceeding with caution." : "Transaction blocked."}`,
+        };
+      },
+    },
+    {
+      name: "maiat_gate_transaction",
+      description: "Check if a transaction target is trustworthy before executing. Blocks transactions to untrusted addresses automatically.",
+      schema: {
+        type: "object" as const,
+        properties: {
+          to: { type: "string", description: "Target address of the transaction" },
+          value: { type: "string", description: "Transaction value (optional context)" },
+          chain: { type: "string", description: "Chain: base, ethereum, bnb" },
+        },
+        required: ["to"],
+      },
+      handler: async (params: { to: string; value?: string; chain?: string }) => {
+        const result = await client.checkTrust(params.to, params.chain);
+        config.onCheck?.(result.address, result.score, result.risk);
+
+        if (!client.isSafe(result.score, minScore) && !config.warnOnly) {
+          config.onBlocked?.(result.address, result.score, result.risk);
+          throw new MaiatTrustError(result.address, result.score, result.risk, minScore);
+        }
+
+        return {
+          approved: true,
+          score: result.score,
+          risk: result.risk,
+          address: result.address,
+        };
+      },
+    },
+  ];
+}
+
+// ═══════════════════════════════════════════
+//  Convenience Export
+// ═══════════════════════════════════════════
+
+/**
+ * Create a Maiat trust plugin for AgentKit
+ * 
+ * @example
+ * ```ts
+ * import { maiatTrustPlugin } from "@maiat/agentkit-plugin";
+ * 
+ * const plugin = maiatTrustPlugin({ 
+ *   minScore: 3.0,
+ *   onBlocked: (addr, score) => console.log(`Blocked ${addr}: ${score}/10`)
+ * });
+ * 
+ * // Use with AgentKit
+ * agent.use(plugin);
+ * ```
+ */
+export function maiatTrustPlugin(config: MaiatPluginConfig = {}) {
+  return {
+    name: "maiat-trust",
+    version: "0.1.0",
+    actions: maiatTrustActions(config),
+    client: new MaiatClient(config),
+  };
+}
+
+// Default export
+export default maiatTrustPlugin;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}