@ton-agent-kit/plugin-identity 1.0.1 → 1.1.1

package/README.md

@@ -0,0 +1,64 @@
+# @ton-agent-kit/plugin-identity
+
+Identity plugin for on-chain agent registration, discovery, and reputation management on TON. Agents can register themselves, discover other agents by capability, and query reputation scores backed by a Tact smart contract.
+
+Part of [TON Agent Kit](https://github.com/Andy00L/ton-agent-kit).
+
+## Install
+
+```bash
+npm install @ton-agent-kit/plugin-identity @ton-agent-kit/core zod
+```
+
+## Usage
+
+```typescript
+import { TonAgentKit, KeypairWallet } from "@ton-agent-kit/core";
+import IdentityPlugin from "@ton-agent-kit/plugin-identity";
+
+const agent = new TonAgentKit(wallet).use(IdentityPlugin);
+
+// Register the agent on-chain
+await agent.runAction("register_agent", {
+  name: "my-agent",
+  services: ["swap", "analytics"],
+});
+
+// Discover other agents
+const agents = await agent.runAction("discover_agent", {
+  service: "swap",
+});
+
+// Check reputation
+const rep = await agent.runAction("get_agent_reputation", {
+  agentAddress: "EQBx...",
+});
+console.log(rep.score);
+```
+
+## Actions
+
+| Action | Description |
+|---|---|
+| `register_agent` | Register the current agent on-chain with metadata. |
+| `discover_agent` | Discover registered agents, optionally filtered by service. |
+| `get_agent_reputation` | Query an agent's on-chain reputation score. |
+| `deploy_reputation_contract` | Deploy a new Reputation smart contract. |
+| `withdraw_reputation_fees` | Withdraw accumulated fees from the Reputation contract. |
+| `process_pending_ratings` | Process queued ratings into finalized scores. |
+| `get_open_disputes` | List currently open reputation disputes. |
+| `trigger_cleanup` | Trigger cleanup of expired or stale agent registrations. |
+| `get_agent_cleanup_info` | Get cleanup eligibility info for an agent. |
+
+## Documentation
+
+See [docs/reputation-system.md](https://github.com/Andy00L/ton-agent-kit/blob/main/docs/reputation-system.md) for the full reputation system design.
+
+## Links
+
+- [GitHub](https://github.com/Andy00L/ton-agent-kit)
+- [npm](https://www.npmjs.com/package/@ton-agent-kit/plugin-identity)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton-agent-kit/plugin-identity",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Identity plugin for TON Agent Kit — agent registry, discovery, and reputation",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/actions/deploy-reputation-contract.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { Address, internal, toNano, beginCell } from "@ton/core";
+
+import { defineAction, toFriendlyAddress, sendTransaction } from "@ton-agent-kit/core";
+import { saveReputationConfig } from "../reputation-config";
+
+export const deployReputationContractAction = defineAction({
+  name: "deploy_reputation_contract",
+  description:
+    "Deploy the on-chain Reputation smart contract (Tact) to TON. Once deployed, register_agent and get_agent_reputation will use it automatically for verifiable, immutable reputation scores.",
+  schema: z.object({
+    fee: z
+      .string()
+      .optional()
+      .describe("Fee per write operation in TON. Defaults to '0.01'."),
+  }),
+  handler: async (agent, params) => {
+    try {
+      // Dynamic import of compiled Tact contract
+      // This file is generated by: bun run contracts/deploy-reputation.ts
+      let Reputation: any;
+      let storeDeploy: any;
+      try {
+        const mod = await import("../contracts/Reputation_Reputation");
+        Reputation = mod.Reputation;
+        storeDeploy = mod.storeDeploy;
+      } catch {
+        return {
+          deployed: false,
+          message:
+            "Compiled contract not found. Run 'bun run contracts/deploy-reputation.ts' first to compile the Tact contract, then copy output to packages/plugin-identity/src/contracts/.",
+        };
+      }
+
+      const ownerAddress = agent.wallet.address;
+      const reputation = await Reputation.fromInit(ownerAddress);
+
+      const deployBody = beginCell()
+        .store(storeDeploy({ $$type: "Deploy", queryId: BigInt(0) }))
+        .endCell();
+
+      await sendTransaction(agent, [
+        internal({
+          to: reputation.address,
+          value: toNano("0.05"),
+          bounce: false,
+          init: reputation.init!,
+          body: deployBody,
+        }),
+      ]);
+
+      const contractAddr = reputation.address.toRawString();
+
+      // Save config so other actions auto-detect the contract
+      saveReputationConfig({
+        contractAddress: contractAddr,
+        network: agent.network,
+        deployedAt: new Date().toISOString(),
+      });
+
+      return {
+        deployed: true,
+        contractAddress: contractAddr,
+        friendlyContract: toFriendlyAddress(reputation.address, agent.network),
+        network: agent.network,
+        fee: params.fee || "0.01",
+        message: `Reputation contract deployed at ${toFriendlyAddress(reputation.address, agent.network)}. Agents can now register on-chain.`,
+      };
+    } catch (err: any) {
+      return {
+        deployed: false,
+        error: err.message,
+        message: `Failed to deploy reputation contract: ${err.message}`,
+      };
+    }
+  },
+});

package/src/actions/discover-agent.ts

@@ -2,50 +2,98 @@ import { z } from "zod";
 import { Address } from "@ton/core";
 import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
 import { loadAgentRegistry } from "../utils";
+import { resolveContractAddress } from "../reputation-config";
+import { callContractGetter, lookupAgentIndex, parseAgentDataFromStack } from "../reputation-helpers";
 
-export const discoverAgentAction = defineAction({
-  name: "discover_agent",
-  description:
-    "Find registered agents by capability or name. Search the local agent registry to find agents that can perform specific tasks.",
-  schema: z.object({
-    capability: z
-      .string()
-      .optional()
-      .describe("Capability to search for (e.g., 'price_feed', 'trading')"),
-    name: z.string().optional().describe("Agent name to search for"),
-  }),
-  handler: async (agent, params) => {
-    const registry = loadAgentRegistry();
-    let results = Object.values(registry);
-
-    if (params.capability) {
-      const cap = params.capability.toLowerCase();
-      results = results.filter((a: any) =>
-        a.capabilities.some((c: string) => c.toLowerCase().includes(cap)),
-      );
-    }
-
-    if (params.name) {
-      const name = params.name.toLowerCase();
-      results = results.filter((a: any) =>
-        a.name.toLowerCase().includes(name),
-      );
-    }
-
-    return {
-      query: { capability: params.capability, name: params.name },
-      count: results.length,
-      agents: results.map((a: any) => ({
-        id: a.id,
-        name: a.name,
-        address: a.address,
-        friendlyAddress: toFriendlyAddress(Address.parse(a.address), agent.network),
-        capabilities: a.capabilities,
-        description: a.description,
-        endpoint: a.endpoint,
-        reputation: a.reputation,
-        registeredAt: a.registeredAt,
-      })),
-    };
-  },
-});
+export function createDiscoverAgentAction(contractAddress?: string) {
+  return defineAction({
+    name: "discover_agent",
+    description:
+      "Find registered agents by capability or name. Searches both on-chain (if contract deployed) and local registry. Set includeOffline=true to include unavailable agents.",
+    schema: z.object({
+      capability: z
+        .string()
+        .optional()
+        .describe("Capability to search for (e.g., 'price_feed', 'trading')"),
+      name: z.string().optional().describe("Agent name to search for"),
+      includeOffline: z
+        .boolean()
+        .optional()
+        .describe("Include offline/unavailable agents. Defaults to false."),
+    }),
+    handler: async (agent, params) => {
+      const addr = resolveContractAddress(contractAddress, agent.network);
+
+      // ── Hybrid mode: JSON registry for discovery, on-chain for reputation ──
+      const registry = loadAgentRegistry();
+      let results = Object.values(registry);
+
+      if (!params.includeOffline) {
+        results = results.filter((a: any) => a.available !== false);
+      }
+
+      if (params.capability) {
+        const cap = params.capability.toLowerCase();
+        results = results.filter((a: any) =>
+          a.capabilities.some((c: string) => c.toLowerCase().includes(cap)),
+        );
+      }
+
+      if (params.name) {
+        const name = params.name.toLowerCase();
+        results = results.filter((a: any) => a.name.toLowerCase().includes(name));
+      }
+
+      // Enrich with on-chain reputation if contract is available
+      if (addr) {
+        const apiBase =
+          agent.network === "testnet"
+            ? "https://testnet.tonapi.io/v2"
+            : "https://tonapi.io/v2";
+
+        for (const a of results as any[]) {
+          try {
+            const idx = await lookupAgentIndex(apiBase, addr, a.name, agent.config.TONAPI_KEY);
+            if (idx !== null) {
+              const dataRes = await callContractGetter(
+                apiBase, addr, "agentData", [idx.toString()], agent.config.TONAPI_KEY,
+              );
+              const parsed = parseAgentDataFromStack(dataRes?.stack);
+              if (parsed) {
+                const rep = parsed.totalTasks > 0
+                  ? Math.round((parsed.successes / parsed.totalTasks) * 100)
+                  : 0;
+                a.reputation = { score: rep, totalTasks: parsed.totalTasks, successfulTasks: parsed.successes };
+                a.onChain = true;
+              }
+            }
+          } catch {
+            // On-chain lookup failed for this agent — keep JSON data
+          }
+        }
+      }
+
+      return {
+        query: { capability: params.capability, name: params.name, includeOffline: params.includeOffline },
+        count: results.length,
+        agents: results.map((a: any) => ({
+          id: a.id,
+          name: a.name,
+          address: a.address,
+          friendlyAddress: a.address ? toFriendlyAddress(Address.parse(a.address), agent.network) : "",
+          capabilities: a.capabilities,
+          available: a.available !== false,
+          description: a.description,
+          endpoint: a.endpoint,
+          reputation: a.reputation,
+          registeredAt: a.registeredAt,
+          onChain: a.onChain || false,
+        })),
+        onChain: !!addr,
+        contractAddress: addr || undefined,
+      };
+    },
+  });
+}
+
+export const discoverAgentAction = createDiscoverAgentAction();

package/src/actions/get-agent-cleanup-info.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { defineAction } from "@ton-agent-kit/core";
+import { resolveContractAddress } from "../reputation-config";
+import { callContractGetter } from "../reputation-helpers";
+
+export const getAgentCleanupInfoAction = defineAction({
+  name: "get_agent_cleanup_info",
+  description:
+    "Check if an agent is eligible for cleanup. Shows score, ratings count, last active date, and which cleanup condition would trigger removal. " +
+    "Reasons: 1=bad_score (<20% with 100+ ratings), 2=inactive (30+ days), 3=ghost (0 ratings after 7 days).",
+  schema: z.object({
+    agentIndex: z.coerce.number().describe("Agent index to check"),
+  }),
+  handler: async (agent, params) => {
+    const addr = resolveContractAddress(undefined, agent.network);
+    if (!addr) {
+      return { message: "No reputation contract configured" };
+    }
+
+    const apiBase = agent.network === "testnet"
+      ? "https://testnet.tonapi.io/v2"
+      : "https://tonapi.io/v2";
+
+    const result = await callContractGetter(
+      apiBase, addr, "agentCleanupInfo",
+      [params.agentIndex.toString()],
+      agent.config.TONAPI_KEY,
+    );
+
+    if (!result?.stack || result.stack.length === 0) {
+      return { message: "Failed to read cleanup info" };
+    }
+
+    // agentCleanupInfo returns a struct as a tuple
+    const stack = result.stack;
+    let items = stack;
+    if (stack[0]?.type === "tuple" && stack[0].tuple) {
+      items = stack[0].tuple;
+    }
+
+    const parseNum = (item: any): number => {
+      if (!item || item.type !== "num") return 0;
+      const s = item.num as string;
+      if (s.startsWith("-0x") || s.startsWith("-0X")) return Number(-BigInt(s.slice(1)));
+      return Number(BigInt(s));
+    };
+    const parseBool = (item: any): boolean => {
+      if (!item) return false;
+      if (item.type === "num") {
+        const s = item.num as string;
+        if (s.startsWith("-0x")) return -BigInt(s.slice(1)) !== 0n;
+        return BigInt(s) !== 0n;
+      }
+      return false;
+    };
+
+    const info = {
+      index: parseNum(items[0]),
+      exists: parseBool(items[1]),
+      score: parseNum(items[2]),
+      totalRatings: parseNum(items[3]),
+      registeredAt: parseNum(items[4]),
+      lastActive: parseNum(items[5]),
+      daysSinceActive: parseNum(items[6]),
+      daysSinceRegistered: parseNum(items[7]),
+      eligibleForCleanup: parseBool(items[8]),
+      cleanupReason: parseNum(items[9]),
+    };
+
+    const reasons: Record<number, string> = {
+      0: "none — agent is healthy",
+      1: "bad_score — score < 20% with 100+ ratings",
+      2: "inactive — no activity for 30+ days",
+      3: "ghost — 0 ratings after 7+ days since registration",
+    };
+
+    return {
+      ...info,
+      cleanupReasonText: reasons[info.cleanupReason] || "unknown",
+      onChain: true,
+      contractAddress: addr,
+    };
+  },
+});

package/src/actions/get-agent-reputation.ts

@@ -1,53 +1,126 @@
 import { z } from "zod";
-import { Address } from "@ton/core";
-import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { Address, internal, toNano } from "@ton/core";
+import { defineAction, toFriendlyAddress, sendTransaction } from "@ton-agent-kit/core";
 import { loadAgentRegistry, saveAgentRegistry } from "../utils";
+import { resolveContractAddress } from "../reputation-config";
+import { buildRateBody, callContractGetter, lookupAgentIndex, parseAgentDataFromStack } from "../reputation-helpers";
 
-export const getAgentReputationAction = defineAction({
-  name: "get_agent_reputation",
-  description:
-    "Get the reputation score of a registered agent. Set addTask=true and success=true to record a successful task. Set addTask=true and success=false to record a failed task.",
-  schema: z.object({
-    agentId: z.string().describe("Agent ID to check or update"),
-    addTask: z
-      .union([z.boolean(), z.string()])
-      .optional()
-      .describe("Set to true to record a completed task"),
-    success: z
-      .union([z.boolean(), z.string()])
-      .optional()
-      .describe("If addTask is true, whether the task was successful"),
-  }),
-  handler: async (agent, params) => {
-    const registry = loadAgentRegistry();
-    const agentRecord = registry[params.agentId];
-    if (!agentRecord) throw new Error(`Agent not found: ${params.agentId}`);
-
-    // Coerce string booleans
-    const addTask = typeof params.addTask === "string" ? params.addTask === "true" : params.addTask;
-    const success = typeof params.success === "string" ? params.success === "true" : params.success;
-
-    // Update reputation if recording a task
-    if (addTask) {
-      agentRecord.reputation.totalTasks += 1;
-      if (success !== false) {
-        agentRecord.reputation.successfulTasks += 1;
+export function createGetAgentReputationAction(contractAddress?: string) {
+  return defineAction({
+    name: "get_agent_reputation",
+    description:
+      "Get the reputation score of a registered agent. Set addTask=true and success=true/false to record a task result. Works both on-chain and locally.",
+    schema: z.object({
+      agentId: z.string().describe("Agent ID or name to check or update"),
+      addTask: z
+        .union([z.boolean(), z.string()])
+        .optional()
+        .describe("Set to true to record a completed task"),
+      success: z
+        .union([z.boolean(), z.string()])
+        .optional()
+        .describe("If addTask is true, whether the task was successful"),
+    }),
+    handler: async (agent, params) => {
+      const addTask = typeof params.addTask === "string" ? params.addTask === "true" : params.addTask;
+      const success = typeof params.success === "string" ? params.success === "true" : params.success;
+
+      const addr = resolveContractAddress(contractAddress, agent.network);
+
+      // ── On-chain mode ──
+      if (addr) {
+        try {
+          const apiBase =
+            agent.network === "testnet"
+              ? "https://testnet.tonapi.io/v2"
+              : "https://tonapi.io/v2";
+
+          // Get the actual agent name for on-chain lookup
+          // Prefer JSON registry (has the exact name used at registration)
+          const jsonRegistry = loadAgentRegistry();
+          const jsonRecord = jsonRegistry[params.agentId];
+          const agentName = jsonRecord?.name
+            || (params.agentId.startsWith("agent_") ? params.agentId.slice(6) : params.agentId);
+
+          // If rating, send Rate message
+          if (addTask) {
+            const body = buildRateBody(agentName, success !== false);
+
+            await sendTransaction(agent, [
+              internal({
+                to: Address.parse(addr),
+                value: toNano("0.03"),
+                bounce: true,
+                body,
+              }),
+            ]);
+          }
+
+          // Look up agent index by name hash
+          const idx = await lookupAgentIndex(apiBase, addr, agentName, agent.config.TONAPI_KEY);
+
+          if (idx !== null) {
+            // Get on-chain data using index
+            const dataRes = await callContractGetter(
+              apiBase, addr, "agentData", [idx.toString()], agent.config.TONAPI_KEY,
+            );
+            const repRes = await callContractGetter(
+              apiBase, addr, "agentReputation", [idx.toString()], agent.config.TONAPI_KEY,
+            );
+
+            const agentData = dataRes?.stack ? parseAgentDataFromStack(dataRes.stack) : null;
+            const repScore = repRes?.stack?.[0]?.num
+              ? Number(BigInt(repRes.stack[0].num))
+              : 0;
+
+            return {
+              agentId: params.agentId,
+              name: agentName,
+              reputation: {
+                score: repScore,
+                totalTasks: agentData?.totalTasks || 0,
+                successfulTasks: agentData?.successes || 0,
+              },
+              available: agentData?.available ?? true,
+              onChain: true,
+              contractAddress: addr,
+            };
+          }
+
+          // Agent not found on-chain — fall through to JSON
+        } catch {
+          // Fall through to JSON
+        }
       }
-      agentRecord.reputation.score = Math.round(
-        (agentRecord.reputation.successfulTasks /
-          agentRecord.reputation.totalTasks) *
-          100,
-      );
-      saveAgentRegistry(registry);
-    }
-
-    return {
-      agentId: params.agentId,
-      name: agentRecord.name,
-      address: agentRecord.address,
-      friendlyAddress: toFriendlyAddress(Address.parse(agentRecord.address), agent.network),
-      reputation: agentRecord.reputation,
-      registeredAt: agentRecord.registeredAt,
-    };
-  },
-});
+
+      // ── JSON fallback mode ──
+      const registry = loadAgentRegistry();
+      const agentRecord = registry[params.agentId];
+      if (!agentRecord) throw new Error(`Agent not found: ${params.agentId}`);
+
+      if (addTask) {
+        agentRecord.reputation.totalTasks += 1;
+        if (success !== false) {
+          agentRecord.reputation.successfulTasks += 1;
+        }
+        agentRecord.reputation.score = Math.round(
+          (agentRecord.reputation.successfulTasks / agentRecord.reputation.totalTasks) * 100,
+        );
+        saveAgentRegistry(registry);
+      }
+
+      return {
+        agentId: params.agentId,
+        name: agentRecord.name,
+        address: agentRecord.address,
+        friendlyAddress: toFriendlyAddress(Address.parse(agentRecord.address), agent.network),
+        reputation: agentRecord.reputation,
+        available: agentRecord.available !== false,
+        onChain: false,
+        registeredAt: agentRecord.registeredAt,
+      };
+    },
+  });
+}
+
+export const getAgentReputationAction = createGetAgentReputationAction();

package/src/actions/get-open-disputes.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { defineAction } from "@ton-agent-kit/core";
+import { resolveContractAddress } from "../reputation-config";
+import { callContractGetter, parseDisputeData } from "../reputation-helpers";
+
+export const getOpenDisputesAction = defineAction({
+  name: "get_open_disputes",
+  description:
+    "Get all open (unsettled) disputes from the reputation contract. Arbiters use this to find disputes they can join and vote on.",
+  schema: z.object({
+    limit: z.coerce.number().optional().describe("Max disputes to return. Default 20."),
+  }),
+  handler: async (agent, params) => {
+    const addr = resolveContractAddress(undefined, agent.network);
+    if (!addr) {
+      return { disputes: [], count: 0, message: "No reputation contract configured" };
+    }
+
+    const apiBase = agent.network === "testnet"
+      ? "https://testnet.tonapi.io/v2"
+      : "https://tonapi.io/v2";
+
+    const limit = params.limit || 20;
+
+    const countRes = await callContractGetter(apiBase, addr, "disputeCount", undefined, agent.config.TONAPI_KEY);
+    const totalDisputes = countRes?.stack?.[0]?.num ? Number(BigInt(countRes.stack[0].num)) : 0;
+
+    if (totalDisputes === 0) {
+      return { disputes: [], count: 0, total: 0, message: "No disputes registered" };
+    }
+
+    const disputes: any[] = [];
+    let checked = 0;
+    for (let i = totalDisputes - 1; i >= 0 && disputes.length < limit; i--) {
+      try {
+        const dataRes = await callContractGetter(apiBase, addr, "disputeData", [i.toString()], agent.config.TONAPI_KEY);
+        if (dataRes?.stack) {
+          const dispute = parseDisputeData(dataRes.stack);
+          if (dispute && !dispute.settled) {
+            disputes.push({
+              index: i,
+              escrowAddress: dispute.escrowAddress,
+              depositor: dispute.depositor,
+              beneficiary: dispute.beneficiary,
+              amount: dispute.amount,
+              votingDeadline: new Date(dispute.votingDeadline * 1000).toISOString(),
+              isExpired: Date.now() / 1000 > dispute.votingDeadline,
+            });
+          }
+        }
+      } catch {}
+      checked++;
+      if (checked > 100) break;
+    }
+
+    return {
+      disputes,
+      count: disputes.length,
+      total: totalDisputes,
+      onChain: true,
+      contractAddress: addr,
+      message: `Found ${disputes.length} open dispute(s)`,
+    };
+  },
+});