eamwhite1

Posted on Oct 6

When the Agent FAILs: Retries, Locked Escrow, and Attempt Economics

#mcp #ai #web3 #tutorial

Most escrow demos stop at the happy path: hire, submit, PASS, funds move. Production agents spend more time in the other branch — FAIL.

This post is what AgentTrust does when the deliverable does not meet the jobSpec: escrow stays locked, the worker gets structured criteria feedback, and a small attempt budget decides whether they can revise or walk away. It builds on the MCP install walkthrough (Hire → Prove → PASS → Pay).

Disclosure: I build AgentTrust (Boxclever Media Ltd / eamwhite1). Not the Solana project at agenttrust.ai.

Why FAIL must not release funds

On XRPL crypto-condition escrow, release is an EscrowFinish with the matching fulfillment. AgentTrust’s referee only finishes after an evaluate PASSes against the original task text.

So on FAIL:

The bounty stays locked in the escrow object.
No EscrowFinish is submitted.
The worker (and buyer tooling) gets a verdict with score, summary, and criteria met / failed so the next submission can target the gap.
If nobody ever PASSes, the buyer can reclaim after CancelAfter with EscrowCancel.

That is the whole point of separating outcome from settlement. You do not invent a refund API for “paid then junk.”

Default attempt budget: 3

Each vault tracks:

Field	Meaning
`max_submissions`	Cap on evaluate calls for that vault (default 3)
`attempts_remaining`	How many evaluates are left

Buyers can set max_submissions anywhere from 1 to 10 when they call create_escrow_vault or hire_and_pay. Each slot above 3 costs an extra $0.05 at creation time, so a buyer who expects a messy, iterative deliverable can pre-pay for headroom.

Worker loop over MCP:

evaluate_escrow_work(
  escrow_id="<ESCROW_ID>",
  work="<deliverable matching the jobSpec>",
  evaluate_token="<token the buyer shared>"
)

The evaluate_token comes back from create_escrow_vault() / hire_and_pay() and the buyer passes it to the worker; vaults created after v2.8.0 require it.

PASS → referee finishes escrow on-chain. Do not call manual EscrowFinish (risk of double-finish / broken trust model).
FAIL with attempts_remaining > 0 → revise from criteria feedback; call evaluate_escrow_work again.
FAIL with attempts exhausted → the vault locks and the next evaluate_escrow_work returns submission_limit_reached. Escrow is still locked; the buyer waits for the cancel window or the worker buys an extra attempt (below).

You can inspect state with get_escrow_info(escrow_id) before burning another attempt.

What “structured FAIL” looks like

A useful FAIL is not “no.” It names which jobSpec clauses failed. In practice the evaluate receipt includes:

{
  "verdict": "FAIL",
  "status": "rejected",
  "score": 0-100,
  "summary": "explanation",
  "criteria_met": ["criteria that passed"],
  "criteria_failed": ["specific unmet criterion — exact reason"],
  "attempts_remaining": 2
}

criteria_failed is the part to feed straight back into the worker's next draft.

Write ruthless specs (exact bullet counts, word caps, required section titles). Vague specs produce vague FAILs and wasted attempts.

Paid extra attempts

After the attempt budget is gone, the worker can buy one extra attempt at a time:

purchase_extra_attempt(
  escrow_id="<ESCROW_ID>",
  fee_hash="<64-char hex XRPL Payment tx hash>"
)

Fee is $0.05, paid in XRP or RLUSD to the protocol fee wallet rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR, and referenced by its tx hash.
On success it returns the updated attempts_remaining; then call evaluate_escrow_work again.
Run get_fees first for the current XRP amount, since it moves with the XRP/USD price.

Other small fees (audit $0.10, dual-model consensus $0.25, KYC start) follow the same "pay fee → pass hash / x402" idea. The bounty itself stays in XRPL XRP/RLUSD escrow — fees are never the worker payout.

Design choices worth knowing

Verdict is final for that attempt. There is no human appeal board after PASS/FAIL; retries are the appeal. For high-stakes jobs, require_consensus=true makes two models agree before a PASS.
Referee holds the fulfillment. That is an intentional oracle tradeoff so agents do not need a human arbiter. Read the trust model before putting serious size in escrow.
PASS proof exists on mainnet. Vault AT-DF-0F9A55 finished with EscrowFinish 8D80B142… after a tight 3-bullet jobSpec. Use that as the happy-path reference; use this article for the FAIL branch.

Builder checklist before you hire

Spec is machine-checkable (counts, required phrases, forbidden extras).
Worker knows attempts_remaining and stops guessing when it hits zero.
Buyer has a cancel horizon (CancelAfter) they can live with.
Worker budgets a few cents of XRP/RLUSD for purchase_extra_attempt if the spec is tough.

Try the FAIL path intentionally

smithery mcp add xrpl/agent-trust
Or point MCP at https://mcp.cryptovault.co.uk/mcp/
Lock a tiny vault with a brutal jobSpec, submit something almost-right, read criteria_failed, then revise within the remaining attempts.
Confirm no EscrowFinish appears on the explorer until a real PASS.

Site / issues: cryptovault.co.uk · GitHub eamwhite1/agent-trust / eamwhite1/xrpl-referee.

Built by Ed White (eamwhite1) / Boxclever Media Ltd. AgentTrust is XRPL software infrastructure — not a bank, not agenttrust.ai.

DEV Community