@ton-agent-kit/plugin-escrow 1.0.2 → 1.1.0

package/src/index.ts

@@ -4,16 +4,51 @@ 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";
+import { confirmDeliveryAction } from "./actions/confirm-delivery";
+import { autoReleaseEscrowAction } from "./actions/auto-release-escrow";
+import { openDisputeAction } from "./actions/open-dispute";
+import { joinDisputeAction } from "./actions/join-dispute";
+import { voteReleaseAction } from "./actions/vote-release";
+import { voteRefundAction } from "./actions/vote-refund";
+import { claimRewardAction } from "./actions/claim-reward";
+import { fallbackSettleAction } from "./actions/fallback-settle";
+import { sellerStakeAction } from "./actions/seller-stake";
 
 /**
- * Escrow Plugin — TON escrow deal management
+ * Escrow Plugin -- TON escrow with self-selecting arbiters, staking, and
+ * dispute-resolution voting.
+ *
+ * Manages the full lifecycle of on-chain escrow deals: creation, funding,
+ * delivery confirmation, release/refund, and a dispute flow where independent
+ * arbiters self-select by staking TON, then vote to release or refund.
  *
  * 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
+ * - `create_escrow` -- Create a new escrow deal (arbiters self-select during disputes)
+ * - `deposit_to_escrow` -- Fund an escrow with TON
+ * - `release_escrow` -- Release funds to beneficiary (depositor only, non-dispute)
+ * - `refund_escrow` -- Refund funds to depositor
+ * - `get_escrow_info` -- Get escrow details or list all escrows
+ * - `confirm_delivery` -- Confirm service delivery on-chain (buyer only)
+ * - `auto_release_escrow` -- Release after deadline (requires delivery confirmation)
+ * - `open_dispute` -- Open a dispute, freezing the escrow for arbiter voting
+ * - `join_dispute` -- Stake TON to join as an arbiter in a dispute
+ * - `vote_release` -- Arbiter votes to release funds during a dispute
+ * - `vote_refund` -- Arbiter votes to refund funds during a dispute
+ * - `claim_reward` -- Claim arbiter reward after settlement (winners profit, losers forfeit)
+ * - `fallback_settle` -- Settle after the 72 h voting deadline expires
+ * - `seller_stake` -- Seller stakes TON to signal commitment to the deal
+ *
+ * @example
+ * ```typescript
+ * import EscrowPlugin from "@ton-agent-kit/plugin-escrow";
+ * const agent = new TonAgentKit(wallet, rpcUrl).use(EscrowPlugin);
+ * const escrow = await agent.runAction("create_escrow", {
+ *   beneficiary: "EQBx...",
+ *   amount: "1.5",
+ * });
+ * ```
+ *
+ * @since 1.0.0
  */
 const EscrowPlugin = definePlugin({
   name: "escrow",
@@ -23,9 +58,19 @@ const EscrowPlugin = definePlugin({
     releaseEscrowAction,
     refundEscrowAction,
     getEscrowInfoAction,
+    confirmDeliveryAction,
+    autoReleaseEscrowAction,
+    openDisputeAction,
+    joinDisputeAction,
+    voteReleaseAction,
+    voteRefundAction,
+    claimRewardAction,
+    fallbackSettleAction,
+    sellerStakeAction,
   ],
 });
 
+/** @since 1.0.0 */
 export default EscrowPlugin;
 
 export {
@@ -34,4 +79,13 @@ export {
   releaseEscrowAction,
   refundEscrowAction,
   getEscrowInfoAction,
+  confirmDeliveryAction,
+  autoReleaseEscrowAction,
+  openDisputeAction,
+  joinDisputeAction,
+  voteReleaseAction,
+  voteRefundAction,
+  claimRewardAction,
+  fallbackSettleAction,
+  sellerStakeAction,
 };

package/src/utils.ts

@@ -8,22 +8,30 @@ import {
   storeDeposit,
   storeRelease,
   storeRefund,
+  storeDeliveryConfirmed,
+  storeAutoRelease,
+  storeOpenDispute,
+  storeJoinDispute,
+  storeVoteRelease,
+  storeVoteRefund,
+  storeClaimReward,
+  storeFallbackSettle,
+  storeSellerStake,
 } from "./contracts/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;
+  minArbiters: number;
+  minStake: string;
   description: string;
   status: string;
   createdAt: string;
@@ -48,22 +56,23 @@ export function saveEscrows(escrows: Record<string, EscrowRecord>): void {
   }
 }
 
-// ── On-chain helpers ──────────────────────────────────────────────────────
+// ── 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,
+  minArbiters: bigint,
+  minStake: bigint,
+  reputationContract: Address,
+  requireRepCollateral: boolean,
+  minRepScore: bigint,
+  baseSellerStake: bigint,
 ): Promise<Address> {
-  const escrow = await Escrow.fromInit(depositor, beneficiary, arbiter, deadline);
-
+  const escrow = await Escrow.fromInit(depositor, beneficiary, deadline, minArbiters, minStake, reputationContract, requireRepCollateral, minRepScore, baseSellerStake);
   const deployBody = beginCell()
-    .store(storeDeploy({ $$type: "Deploy", queryId: BigInt(0) }))
+    .store(storeDeploy({ $$type: "Deploy", queryId: 0n }))
     .endCell();
 
   await sendTransaction(agent, [
@@ -75,77 +84,70 @@ export async function deployEscrowContract(
       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();
+export async function depositToContract(agent: AgentContext, contractAddress: Address, amount: string): Promise<void> {
+  const body = beginCell().store(storeDeposit({ $$type: "Deposit", queryId: 0n })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano(amount), bounce: true, body })]);
+}
 
-  await sendTransaction(agent, [
-    internal({
-      to: contractAddress,
-      value: toNano(amount),
-      bounce: true,
-      body,
-    }),
-  ]);
+export async function releaseContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeRelease({ $$type: "Release", queryId: 0n })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), 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();
+export async function refundContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeRefund({ $$type: "Refund", queryId: 0n })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
 
-  await sendTransaction(agent, [
-    internal({
-      to: contractAddress,
-      value: toNano("0.02"),
-      bounce: true,
-      body,
-    }),
-  ]);
+export async function confirmDeliveryOnContract(agent: AgentContext, contractAddress: Address, x402TxHash: string): Promise<void> {
+  const body = beginCell().store(storeDeliveryConfirmed({ $$type: "DeliveryConfirmed", x402TxHash })).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();
+export async function autoReleaseOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeAutoRelease({ $$type: "AutoRelease" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
 
-  await sendTransaction(agent, [
-    internal({
-      to: contractAddress,
-      value: toNano("0.02"),
-      bounce: true,
-      body,
-    }),
-  ]);
+export async function openDisputeOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeOpenDispute({ $$type: "OpenDispute" })).endCell();
+  // 0.05 TON: 0.02 escrow gas + 0.03 for cross-contract notification to reputation
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.05"), bounce: true, body })]);
+}
+
+export async function joinDisputeOnContract(agent: AgentContext, contractAddress: Address, stakeAmount: string): Promise<void> {
+  const body = beginCell().store(storeJoinDispute({ $$type: "JoinDispute" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano(stakeAmount), bounce: true, body })]);
+}
+
+export async function voteReleaseOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeVoteRelease({ $$type: "VoteRelease" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
+
+export async function voteRefundOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeVoteRefund({ $$type: "VoteRefund" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
+
+export async function claimRewardOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeClaimReward({ $$type: "ClaimReward" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
+
+export async function fallbackSettleOnContract(agent: AgentContext, contractAddress: Address): Promise<void> {
+  const body = beginCell().store(storeFallbackSettle({ $$type: "FallbackSettle" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano("0.02"), bounce: true, body })]);
+}
+
+export async function sellerStakeOnContract(agent: AgentContext, contractAddress: Address, stakeAmount: string): Promise<void> {
+  const body = beginCell().store(storeSellerStake({ $$type: "SellerStake" })).endCell();
+  await sendTransaction(agent, [internal({ to: contractAddress, value: toNano(stakeAmount), 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));
@@ -154,21 +156,10 @@ export async function getContractState(agent: AgentContext, contractAddress: Add
   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";
+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 res = await fetch(`${apiBase}/accounts/${encodeURIComponent(address)}/events?limit=1`);
     const data = await res.json();
     return data.events?.[0]?.event_id || "pending";
   } catch {