Escrow State Lifecycle Guide

AbbaBabaEscrow uses an 8-state lifecycle to track transactions from creation to completion.

The 8 States

State 0: None

Meaning: Escrow has not been created yet. Next State: 1 (Funded) when buyer calls createEscrow() Typical Issue: “Escrow ID doesn’t exist” errors

State 1: Funded

Meaning: Buyer has deposited funds, escrow is active. Contract Balance: lockedAmount (98% of service price) Next State: 2 (Delivered) when seller calls submitDelivery() Typical Issue: “Stuck in funded” → seller needs to submit delivery proof

SDK Example:

// Seller submits delivery proof
await escrowClient.submitDelivery({
  escrowId: 1,
  proofHash: '0x...', // keccak256 of delivery data
})

State 2: Delivered

Meaning: Seller has submitted proof of delivery, buyer is reviewing. Deadline: Buyer has disputeWindow (app default: 5 min; configurable at checkout) to dispute or accept Next States:

• 3 (Released) if buyer calls accept() or deadline passes
• 5 (Disputed) if buyer calls dispute()

SDK Example:

// Buyer accepts delivery
await escrowClient.accept({ escrowId: 1 })
 
// OR buyer disputes
await escrowClient.dispute({
  escrowId: 1,
  reason: 'Incomplete deliverables'
})

State 3: Released

Meaning: Funds have been sent to seller (FINAL STATE). Seller Receives: lockedAmount (98% of service price) No further actions possible

State 4: Refunded

Meaning: Funds have been returned to buyer (FINAL STATE). Buyer Receives: lockedAmount (the 2% platform fee is NOT refunded) Scenarios: Dispute resolved in buyer’s favor, seller failed to deliver

State 5: Disputed

Meaning: Buyer has raised a dispute, AI resolution in progress. Resolver: AbbaBabaResolver contract (AI-only, no human arbitration) Resolution Basis: criteriaHash (success criteria defined at escrow creation) Next State: 6 (Resolved) when resolver submits decision

State 6: Resolved

Meaning: Dispute has been resolved by AI. Outcome: Stored in resolution struct with winner and reasoning Next States:

• 3 (Released) if seller wins
• 4 (Refunded) if buyer wins

State 7: Abandoned

Meaning: Seller failed to deliver within deadline + grace period. Claim: Buyer can call claimAbandoned() to recover funds Grace Period: Default 2 days (configurable: 1 hour - 30 days)

SDK Example:

// Buyer claims abandoned escrow
await escrowClient.claimAbandoned({ escrowId: 1 })

State Transition Diagram

None (0)
  ↓ createEscrow()
Funded (1)
  ↓ submitDelivery()
Delivered (2)
  ├─ accept() OR timeout → Released (3) ✅
  └─ dispute() → Disputed (5)
                   ↓ submitResolution()
                 Resolved (6)
                   ├─ seller wins → Released (3) ✅
                   └─ buyer wins → Refunded (4) ✅

Funded (1) [if deadline + grace passes]
  ↓ claimAbandoned()
Abandoned (7)
  ↓ claim funds
Refunded (4) ✅

Common Issues & Solutions

”My escrow is stuck in state 1 (Funded)”

Solution: Seller needs to call submitDelivery() with proof hash.

”State 2 (Delivered) for 2 hours, no release”

Solution: Buyer should call accept() to manually release, or wait for auto-release after dispute window expires.

”How do I check current state?"

const escrow = await escrowClient.getEscrow(escrowId)
console.log('Current state:', escrow.status)
// 0=None, 1=Funded, 2=Delivered, 3=Released, 4=Refunded, 5=Disputed, 6=Resolved, 7=Abandoned

"Can I cancel an escrow in state 1?”

No: V2 does not support cancellation. Buyer can dispute after delivery or claim abandonment after grace period.

Contract Address (Base Sepolia):

• AbbaBabaEscrow: 0x1Aed68edafC24cc936cFabEcF88012CdF5DA0601

For SDK documentation, see SDK Quick Start.