@ton-agent-kit/plugin-escrow 1.0.0

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@ton-agent-kit/plugin-escrow",
+  "version": "1.0.0",
+  "description": "Escrow plugin for TON Agent Kit — create, fund, release, and refund escrow deals",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": { "build": "tsc" },
+  "dependencies": {
+    "@ton-agent-kit/core": "^1.0.0",
+    "@ton/ton": "^16.2.0",
+    "@ton/core": "^0.63.1"
+  },
+  "keywords": ["ton", "blockchain", "ai", "agent", "sdk"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/Andy00L/ton-agent-kit.git" }
+}

package/src/actions/create-escrow.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import {
+  loadEscrows,
+  saveEscrows,
+  deployEscrowContract,
+  type EscrowRecord,
+} from "../utils";
+
+export const createEscrowAction = defineAction<
+  {
+    beneficiary: string;
+    amount: string;
+    description?: string;
+    deadlineTimestamp?: number;
+    deadlineDays?: number;
+    deadlineHours?: number;
+    deadlineMinutes?: number;
+  },
+  any
+>({
+  name: "create_escrow",
+  description:
+    "Create a new on-chain escrow deal. Deploys a Tact Escrow contract to TON. " +
+    "The beneficiary receives funds when released. " +
+    "Deadline can be set via deadlineTimestamp (exact Unix timestamp), deadlineDays, deadlineHours, or deadlineMinutes. " +
+    "Priority: timestamp > days > hours > minutes. Defaults to 60 minutes if none provided.",
+  schema: z.object({
+    beneficiary: z
+      .string()
+      .describe("Address of the beneficiary (who receives funds)"),
+    amount: z.string().describe("Amount of TON to escrow"),
+    description: z.string().optional().describe("Description of the deal"),
+    deadlineTimestamp: z.coerce
+      .number()
+      .optional()
+      .describe("Exact deadline as Unix timestamp (seconds). Takes highest priority."),
+    deadlineDays: z.coerce
+      .number()
+      .optional()
+      .describe("Deadline in days from now (e.g., 90 for ~3 months)"),
+    deadlineHours: z.coerce
+      .number()
+      .optional()
+      .describe("Deadline in hours from now (e.g., 24 for 1 day)"),
+    deadlineMinutes: z.coerce
+      .number()
+      .optional()
+      .describe("Deadline in minutes from now (e.g., 60 for 1 hour). Default if nothing else set."),
+  }) as any,
+  handler: async (agent, params) => {
+    const escrowId = `escrow_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const now = Math.floor(Date.now() / 1000);
+
+    let deadline: number;
+    if (params.deadlineTimestamp) {
+      deadline = params.deadlineTimestamp;
+    } else if (params.deadlineDays) {
+      deadline = now + params.deadlineDays * 86400;
+    } else if (params.deadlineHours) {
+      deadline = now + params.deadlineHours * 3600;
+    } else {
+      deadline = now + (params.deadlineMinutes || 60) * 60;
+    }
+
+    const depositor = agent.wallet.address;
+    const beneficiary = Address.parse(params.beneficiary);
+    const arbiter = agent.wallet.address; // Agent is arbiter by default
+
+    // Deploy a new Escrow contract on-chain
+    const contractAddress = await deployEscrowContract(
+      agent,
+      depositor,
+      beneficiary,
+      arbiter,
+      BigInt(deadline),
+    );
+
+    // Save to JSON index (escrowId → contract address mapping)
+    const escrow: EscrowRecord = {
+      id: escrowId,
+      contractAddress: contractAddress.toRawString(),
+      depositor: depositor.toRawString(),
+      beneficiary: params.beneficiary,
+      arbiter: arbiter.toRawString(),
+      amount: params.amount,
+      deadline,
+      deadlineISO: new Date(deadline * 1000).toISOString(),
+      description: params.description || "",
+      status: "created",
+      createdAt: new Date().toISOString(),
+    };
+
+    const escrows = loadEscrows();
+    escrows[escrowId] = escrow;
+    saveEscrows(escrows);
+
+    return {
+      escrowId,
+      status: "created (contract deployed on-chain)",
+      contractAddress: contractAddress.toRawString(),
+      friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+      beneficiary: params.beneficiary,
+      friendlyBeneficiary: toFriendlyAddress(beneficiary, agent.network),
+      amount: params.amount + " TON",
+      deadline: escrow.deadlineISO,
+      description: params.description || "",
+      nextStep: `Deposit ${params.amount} TON using deposit_to_escrow with escrowId: ${escrowId}`,
+    };
+  },
+});

package/src/actions/deposit-to-escrow.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import {
+  loadEscrows,
+  saveEscrows,
+  depositToContract,
+  getLatestTxHash,
+} from "../utils";
+
+export const depositToEscrowAction = defineAction<{ escrowId: string }, any>({
+  name: "deposit_to_escrow",
+  description:
+    "Deposit TON into an on-chain escrow contract. Sends TON to the deployed Escrow smart contract.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID from create_escrow"),
+  }) as any,
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) throw new Error(`Escrow not found: ${params.escrowId}`);
+    if (escrow.status !== "created")
+      throw new Error(`Escrow already ${escrow.status}`);
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    // Send Deposit message with TON to the escrow contract
+    await depositToContract(agent, contractAddress, escrow.amount);
+
+    // Wait for confirmation
+    await new Promise((r) => setTimeout(r, 10000));
+
+    const txHash = await getLatestTxHash(
+      agent.wallet.address.toRawString(),
+      agent.network,
+    );
+
+    // Update index
+    escrow.status = "funded";
+    saveEscrows(escrows);
+
+    return {
+      escrowId: params.escrowId,
+      status: "funded (on-chain)",
+      contractAddress: escrow.contractAddress,
+      friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+      amount: escrow.amount + " TON",
+      depositTxHash: txHash,
+      beneficiary: escrow.beneficiary,
+      friendlyBeneficiary: toFriendlyAddress(Address.parse(escrow.beneficiary), agent.network),
+      deadline: escrow.deadlineISO,
+    };
+  },
+});

package/src/actions/get-escrow-info.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { Address, fromNano } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import { loadEscrows, getContractState } from "../utils";
+
+export const getEscrowInfoAction = defineAction<{ escrowId?: string }, any>({
+  name: "get_escrow_info",
+  description:
+    "Get escrow details. Reads on-chain contract state if available. " +
+    "If escrowId is provided, returns that escrow. If no escrowId, lists ALL escrows.",
+  schema: z.object({
+    escrowId: z
+      .string()
+      .optional()
+      .describe("Escrow ID. If not provided, lists all escrows."),
+  }) as any,
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+
+    if (params.escrowId) {
+      const escrow = escrows[params.escrowId];
+      if (!escrow) throw new Error(`Escrow not found: ${params.escrowId}`);
+
+      // Try to read on-chain state
+      try {
+        const contractAddress = Address.parse(escrow.contractAddress);
+        const onChain = await getContractState(agent, contractAddress);
+
+        return {
+          id: escrow.id,
+          contractAddress: escrow.contractAddress,
+          friendlyContract: toFriendlyAddress(Address.parse(escrow.contractAddress), agent.network),
+          description: escrow.description,
+          createdAt: escrow.createdAt,
+          onChain: {
+            depositor: toFriendlyAddress(onChain.depositor, agent.network),
+            beneficiary: toFriendlyAddress(onChain.beneficiary, agent.network),
+            arbiter: toFriendlyAddress(onChain.arbiter, agent.network),
+            amount: fromNano(onChain.amount) + " TON",
+            balance: fromNano(onChain.balance) + " TON",
+            deadline: new Date(Number(onChain.deadline) * 1000).toISOString(),
+            released: onChain.released,
+            refunded: onChain.refunded,
+            status: onChain.released
+              ? "released"
+              : onChain.refunded
+                ? "refunded"
+                : onChain.amount > BigInt(0)
+                  ? "funded"
+                  : "created",
+          },
+        };
+      } catch (e: any) {
+        // Contract not yet active or network error — fall back to index
+        return {
+          ...escrow,
+          onChainError: e.message || "Could not read contract state (may not be deployed yet)",
+        };
+      }
+    }
+
+    // List all escrows from index
+    const list = Object.values(escrows);
+    return {
+      count: list.length,
+      escrows: list.map((e) => ({
+        id: e.id,
+        status: e.status,
+        contractAddress: e.contractAddress || null,
+        friendlyContract: e.contractAddress
+          ? toFriendlyAddress(Address.parse(e.contractAddress), agent.network)
+          : null,
+        amount: e.amount + " TON",
+        beneficiary: e.beneficiary,
+        friendlyBeneficiary: e.beneficiary
+          ? toFriendlyAddress(Address.parse(e.beneficiary), agent.network)
+          : null,
+        deadline: e.deadlineISO,
+        description: e.description,
+      })),
+    };
+  },
+});

package/src/actions/refund-escrow.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import {
+  loadEscrows,
+  saveEscrows,
+  refundContract,
+  getLatestTxHash,
+} from "../utils";
+
+export const refundEscrowAction = defineAction<{ escrowId: string }, any>({
+  name: "refund_escrow",
+  description:
+    "Refund escrowed funds back to the depositor via the on-chain Escrow contract. " +
+    "Can refund if authorized (depositor/arbiter) or after deadline has passed.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to refund"),
+  }) as any,
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) throw new Error(`Escrow not found: ${params.escrowId}`);
+    if (escrow.status !== "funded")
+      throw new Error(`Escrow is ${escrow.status}, must be funded`);
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    // Send Refund message to the escrow contract
+    // The contract itself enforces authorization (depositor/arbiter/past deadline)
+    await refundContract(agent, contractAddress);
+
+    // Wait for confirmation
+    await new Promise((r) => setTimeout(r, 10000));
+
+    const txHash = await getLatestTxHash(
+      agent.wallet.address.toRawString(),
+      agent.network,
+    );
+
+    const now = Math.floor(Date.now() / 1000);
+    const pastDeadline = now > escrow.deadline;
+
+    // Update index
+    escrow.status = "refunded";
+    saveEscrows(escrows);
+
+    return {
+      escrowId: params.escrowId,
+      status: "refunded (on-chain)",
+      contractAddress: escrow.contractAddress,
+      friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+      amount: escrow.amount + " TON",
+      depositor: escrow.depositor,
+      friendlyDepositor: toFriendlyAddress(Address.parse(escrow.depositor), agent.network),
+      reason: pastDeadline ? "Deadline passed" : "Authorized refund",
+      refundTxHash: txHash,
+    };
+  },
+});

package/src/actions/release-escrow.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { Address } from "@ton/core";
+import { defineAction, toFriendlyAddress } from "@ton-agent-kit/core";
+import {
+  loadEscrows,
+  saveEscrows,
+  releaseContract,
+  getLatestTxHash,
+} from "../utils";
+
+export const releaseEscrowAction = defineAction<{ escrowId: string }, any>({
+  name: "release_escrow",
+  description:
+    "Release escrowed funds to the beneficiary via the on-chain Escrow contract. Only the depositor or arbiter can release.",
+  schema: z.object({
+    escrowId: z.string().describe("Escrow ID to release"),
+  }) as any,
+  handler: async (agent, params) => {
+    const escrows = loadEscrows();
+    const escrow = escrows[params.escrowId];
+    if (!escrow) throw new Error(`Escrow not found: ${params.escrowId}`);
+    if (escrow.status !== "funded")
+      throw new Error(`Escrow is ${escrow.status}, must be funded`);
+
+    const contractAddress = Address.parse(escrow.contractAddress);
+
+    // Send Release message to the escrow contract
+    await releaseContract(agent, contractAddress);
+
+    // Wait for confirmation
+    await new Promise((r) => setTimeout(r, 10000));
+
+    const txHash = await getLatestTxHash(
+      agent.wallet.address.toRawString(),
+      agent.network,
+    );
+
+    // Update index
+    escrow.status = "released";
+    saveEscrows(escrows);
+
+    return {
+      escrowId: params.escrowId,
+      status: "released (on-chain)",
+      contractAddress: escrow.contractAddress,
+      friendlyContract: toFriendlyAddress(contractAddress, agent.network),
+      amount: escrow.amount + " TON",
+      beneficiary: escrow.beneficiary,
+      friendlyBeneficiary: toFriendlyAddress(Address.parse(escrow.beneficiary), agent.network),
+      releaseTxHash: txHash,
+    };
+  },
+});

package/src/index.ts

@@ -0,0 +1,37 @@
+import { definePlugin } from "@ton-agent-kit/core";
+import { createEscrowAction } from "./actions/create-escrow";
+import { depositToEscrowAction } from "./actions/deposit-to-escrow";
+import { releaseEscrowAction } from "./actions/release-escrow";
+import { refundEscrowAction } from "./actions/refund-escrow";
+import { getEscrowInfoAction } from "./actions/get-escrow-info";
+
+/**
+ * Escrow Plugin — TON escrow deal management
+ *
+ * Actions:
+ * - create_escrow: Create a new escrow deal
+ * - deposit_to_escrow: Fund an escrow with TON
+ * - release_escrow: Release funds to beneficiary
+ * - refund_escrow: Refund funds to depositor
+ * - get_escrow_info: Get escrow details or list all
+ */
+const EscrowPlugin = definePlugin({
+  name: "escrow",
+  actions: [
+    createEscrowAction,
+    depositToEscrowAction,
+    releaseEscrowAction,
+    refundEscrowAction,
+    getEscrowInfoAction,
+  ],
+});
+
+export default EscrowPlugin;
+
+export {
+  createEscrowAction,
+  depositToEscrowAction,
+  releaseEscrowAction,
+  refundEscrowAction,
+  getEscrowInfoAction,
+};

package/src/utils.ts

@@ -0,0 +1,177 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { Address, internal, toNano, beginCell } from "@ton/core";
+import { TonClient4 } from "@ton/ton";
+import type { AgentContext } from "@ton-agent-kit/core";
+import {
+  Escrow,
+  storeDeploy,
+  storeDeposit,
+  storeRelease,
+  storeRefund,
+} from "../../../contracts/output/Escrow_Escrow";
+import { sendTransaction } from "@ton-agent-kit/core";
+
+const ESCROW_FILE = ".escrow-store.json";
+
+// ── JSON index (escrowId → metadata + contract address) ───────────────────
+
+export interface EscrowRecord {
+  id: string;
+  contractAddress: string;
+  depositor: string;
+  beneficiary: string;
+  arbiter: string;
+  amount: string;
+  deadline: number;
+  deadlineISO: string;
+  description: string;
+  status: string;
+  createdAt: string;
+}
+
+export function loadEscrows(): Record<string, EscrowRecord> {
+  try {
+    if (existsSync(ESCROW_FILE)) {
+      return JSON.parse(readFileSync(ESCROW_FILE, "utf-8"));
+    }
+  } catch (err: any) {
+    console.error(`Failed to load escrow store: ${err.message}`);
+  }
+  return {};
+}
+
+export function saveEscrows(escrows: Record<string, EscrowRecord>): void {
+  try {
+    writeFileSync(ESCROW_FILE, JSON.stringify(escrows, null, 2), "utf-8");
+  } catch (err: any) {
+    console.error(`Failed to save escrow store: ${err.message}`);
+  }
+}
+
+// ── On-chain helpers ──────────────────────────────────────────────────────
+
+/**
+ * Deploy a new Escrow contract instance and return the contract address.
+ */
+export async function deployEscrowContract(
+  agent: AgentContext,
+  depositor: Address,
+  beneficiary: Address,
+  arbiter: Address,
+  deadline: bigint,
+): Promise<Address> {
+  const escrow = await Escrow.fromInit(depositor, beneficiary, arbiter, deadline);
+
+  const deployBody = beginCell()
+    .store(storeDeploy({ $$type: "Deploy", queryId: BigInt(0) }))
+    .endCell();
+
+  await sendTransaction(agent, [
+    internal({
+      to: escrow.address,
+      value: toNano("0.05"),
+      bounce: false,
+      init: escrow.init!,
+      body: deployBody,
+    }),
+  ]);
+
+  return escrow.address;
+}
+
+/**
+ * Send a Deposit message (with TON attached) to an escrow contract.
+ */
+export async function depositToContract(
+  agent: AgentContext,
+  contractAddress: Address,
+  amount: string,
+): Promise<void> {
+  const body = beginCell()
+    .store(storeDeposit({ $$type: "Deposit", queryId: BigInt(0) }))
+    .endCell();
+
+  await sendTransaction(agent, [
+    internal({
+      to: contractAddress,
+      value: toNano(amount),
+      bounce: true,
+      body,
+    }),
+  ]);
+}
+
+/**
+ * Send a Release message to an escrow contract.
+ */
+export async function releaseContract(
+  agent: AgentContext,
+  contractAddress: Address,
+): Promise<void> {
+  const body = beginCell()
+    .store(storeRelease({ $$type: "Release", queryId: BigInt(0) }))
+    .endCell();
+
+  await sendTransaction(agent, [
+    internal({
+      to: contractAddress,
+      value: toNano("0.02"),
+      bounce: true,
+      body,
+    }),
+  ]);
+}
+
+/**
+ * Send a Refund message to an escrow contract.
+ */
+export async function refundContract(
+  agent: AgentContext,
+  contractAddress: Address,
+): Promise<void> {
+  const body = beginCell()
+    .store(storeRefund({ $$type: "Refund", queryId: BigInt(0) }))
+    .endCell();
+
+  await sendTransaction(agent, [
+    internal({
+      to: contractAddress,
+      value: toNano("0.02"),
+      bounce: true,
+      body,
+    }),
+  ]);
+}
+
+/**
+ * Read on-chain escrow state via get method.
+ */
+export async function getContractState(agent: AgentContext, contractAddress: Address) {
+  const client = new TonClient4({ endpoint: agent.rpcUrl });
+  const contract = client.open(Escrow.fromAddress(contractAddress));
+  const data = await contract.getEscrowData();
+  const balance = await contract.getBalance();
+  return { ...data, balance };
+}
+
+/**
+ * Look up the latest tx hash for an address via TonAPI.
+ */
+export async function getLatestTxHash(
+  address: string,
+  network: "testnet" | "mainnet",
+): Promise<string> {
+  const apiBase =
+    network === "testnet"
+      ? "https://testnet.tonapi.io/v2"
+      : "https://tonapi.io/v2";
+  try {
+    const res = await fetch(
+      `${apiBase}/accounts/${encodeURIComponent(address)}/events?limit=1`,
+    );
+    const data = await res.json();
+    return data.events?.[0]?.event_id || "pending";
+  } catch {
+    return "pending";
+  }
+}