Agent Escrow

Agent Escrow is a trustless on-chain escrow and settlement layer built for the AI agent economy. It allows AI agents and humans to hire each other for tasks by locking payments into a smart contract.

Comment

Agent Escrow

Project Story / About the project

Inspiration

AI agents can discover work, call APIs, and produce deliverables, but payment still often depends on an informal promise: the agent delivers first and hopes the requester pays. The requester has the opposite concern: paying first and hoping the agent delivers.

We built Agent Escrow to give both sides a small, transparent settlement primitive. A requester locks BOT for one designated agent, the agent accepts and submits delivery evidence before a deadline, and the payment is released on-chain. If the requester becomes unresponsive after submission, anyone can trigger settlement once the review window expires. If work is not submitted on time, the requester can recover the escrow.

What it does

Agent Escrow is a trust-minimized escrow and reputation dApp deployed on BOT Chain mainnet. Its lifecycle is:

Open -> Accepted -> Submitted -> Released
Open -> Cancelled
Accepted -> Refunded after a missed work deadline
Accepted or Submitted -> Cancelled after both parties approve
Submitted -> Released by the requester, or finalized after review expires

The requester chooses the agent address up front, which prevents open-claim sniping. The work clock begins only when that agent accepts. Submission evidence is recorded on-chain, while large or private deliverables can remain off-chain behind a content hash or access-controlled URL.

After a successful release, the requester can add one score from 1 to 5. Ratings are tied to completed escrows, and each bounty can be rated only once. For an agent with ratings (s_1, s_2, \ldots, s_n), the displayed reputation is:

$$ R_{agent} = \frac{1}{n}\sum_{i=1}^{n}s_i $$

The app also reconstructs wallet history directly from indexed contract events. Users can look up any BOT Chain address and see its requester and agent history, active escrows, BOT earned, BOT paid out, and aggregate rating.

How we built it

The protocol is a Solidity 0.8.24 state machine protected with OpenZeppelin's ReentrancyGuard. State is updated before external value transfers, and role checks constrain every lifecycle action. Hardhat is used for compilation, deployment, verification, and a 16-test contract/deployment suite covering lifecycle transitions, exact deadline behavior, permissions, ratings, refunds, mutual cancellation, and a malicious reentrant receiver.

The client is a React 19 and TypeScript single-page app built with Vite, Tailwind CSS, shadcn/ui, Three.js, and ethers.js 6. There is no application backend or off-chain ledger: the browser connects to the wallet and BOT Chain directly. Indexed events are queried in RPC-safe block ranges, deduplicated, cached, and hydrated with current contract state. The static app is deployed through GitHub Pages with hash-based routing.

The production contract is verified on BOT Chain mainnet at 0x9DC2e2cB2850680EC74Fd3A4c006B0982972F62B on chain ID 677. The frontend fails closed if its deployment address or deployment block is missing, preventing it from silently connecting the current ABI to a stale contract.

Challenges we faced

The hardest contract challenge was designing symmetric failure paths. A requester needs a refund when accepted work misses its deadline, while an agent needs a path to payment when submitted work is ignored. We solved this with separate work and review windows, requester release, permissionless timeout finalization, open cancellation, and mutual cancellation after acceptance.

The hardest frontend challenge was rebuilding useful product state without a backend. Wallet history has to be derived from indexed events across many blocks, then reconciled with each bounty's latest on-chain state. We added chunked event queries, bounty-ID deduplication, retry handling for RPC timing, pagination, and caching so arbitrary wallet lookups remain practical.

We also had to make a two-wallet protocol understandable in a self-serve interface. The UI surfaces network status, wallet balance, role-specific actions, deadline-aware controls, a lifecycle tracker, transaction feedback, recent bounties, and a live activity feed so users can see why an action is or is not available.

What we learned

We learned that escrow is less about the happy-path transfer and more about defining who can recover funds at every boundary. Starting the work deadline at acceptance, not creation, avoids penalizing an agent before it agrees to the task. Starting the review deadline at submission gives the requester a real inspection window without allowing silence to block payment forever.

We also learned that an event log can act as a portable, backend-free history layer, but only when queries are chunked, deduplicated, cached, and checked against current state. Finally, agent automation should use the verified contract directly with a dedicated low-balance wallet, strict contract and spending allowlists, and human approval above a configured threshold.

Current status and limitations

Agent Escrow is live on BOT Chain mainnet, and the deployed contract has real on-chain activity. The contract is tested and source-verified, but has not received an external security audit. The current version does not include agent discovery, private submissions, dispute arbitration, or a protocol fee. These were intentionally left outside the hackathon scope to keep the fund-moving surface small and inspectable.

Built With

Share this project:

Updates

Submission history