Technical Overview

FiDeal is built on Agoric, a proof-of-stake blockchain purpose-built for safe asset exchange. This document covers the architecture, smart contract design, and protocol mechanics.

Architecture

FiDeal runs on three layers:

Layer	Technology	Role
Smart contracts	Agoric Zoe + Orchestration	Escrow logic, fund custody, state machine, atomic settlement
Backend API	Next.js 16 API routes	Wallet derivation, agent API, AI arbitration, Stripe onramp
Frontend	Next.js 16 + Radix UI + Tailwind	Escrow management, wallet connection, payment links

Chain: agoricdev-25 (devnet). Settlement currency is USDC via IBC (ibc/FE98AAD68F02F03565E9FA39AECEE789FE076A90B8B63BFC77912EFD0D5F83A4).

Smart Contract Design

FiDeal uses two Zoe contracts:

FiDeal — Human-to-human escrow. Users create escrows via shareable payment links, lock USDC, and release on delivery confirmation. Supports milestone-based escrows (2–10 milestones per escrow).
FiDealAI — Agent-to-agent escrow. AI agents create and manage escrows programmatically through a REST API. Same on-chain guarantees, faster timeouts.

Both contracts follow Agoric's orchestration pattern:

contract.js  →  Contract setup, publicFacet with invitation makers
flows.js     →  Business logic (createEscrow, markDelivered, confirmRelease, etc.)
proposal.js  →  CoreEval deployment proposal for on-chain installation

On startup, each contract creates a durable local orchestration account (zone.makeOnce) that serves as the escrow vault. All locked USDC flows through this single account. Escrow records are stored in a durable MapStore, keyed by sequential escrow ID.

FiDeal Flows

Flow	Description
`createEscrow`	Payer locks USDC, optionally with 2–10 milestones.
`markDelivered`	Payee marks a milestone or the whole escrow as delivered.
`confirmRelease`	Payer confirms and releases funds (minus protocol fee).
`cancelEscrow`	Payer cancels within the 12-hour cancellation window.
`raiseDispute`	Either party raises a dispute with category and statement.
`respondToDispute`	Payee responds to a dispute (Tier 1 peer resolution).
`acceptResolution`	Accept a resolution outcome.
`resolveDispute`	Resolver submits AI or human resolution.
`createRequest`	Create a payment request (payee-initiated).
`fundRequest`	Payer funds an existing request.
`directSend`	Direct payment send (no escrow).

FiDealAI Flows

Flow	Description
`registerAgent`	Self-serve agent registration on the allowlist.
`createAgentEscrow`	Payer agent locks USDC for agent-to-agent transaction.
`claimAgentEscrow`	Payee agent claims delivery with proof.
`disputeAgentEscrow`	Payer disputes during the dispute window.
`respondToAgentDispute`	Payee responds (Tier 1).
`acceptAgentResolution`	Payer accepts partial concession or counter. Requires `ESCALATED` state — invalid once `AI_REVIEW` begins.
`resolveByHumanReview`	Human reviewer makes final decision.

Escrow State Machine

Every escrow moves through a defined set of states. Transitions are triggered by Zoe offers (requiring wallet signatures) or by the on-chain timer.

FiDeal (Human) States

CREATED ──→ DELIVERED ──→ RELEASED
   │             │
   │             ▼
   └──────→ DISPUTED ──→ RESOLVED
   │                         │
   ▼                         ▼
EXPIRED ──→ REFUNDED    REFUNDED

State	Description
CREATED	Payer locked USDC. Waiting for payee to mark delivery.
DELIVERED	Payee marked work complete. Waiting for payer to release.
RELEASED	Terminal. Funds sent to payee minus protocol fee.
DISPUTED	Dispute raised. Enters 3-tier resolution process.
RESOLVED	Terminal. Funds distributed per resolution split.
EXPIRED	Timer ran out before completion.
REFUNDED	Terminal. Funds returned to payer.

FiDealAI (Agent) States

CREATED ──→ CLAIM_PENDING ──→ RELEASED
   │              │
   │              ▼
   │        RESPONSE_PENDING ──→ ESCALATED ──→ AI_REVIEW
   │                                              │
   │                                    ┌─────────┴─────────┐
   │                                    ▼                   ▼
   │                               SETTLED          HUMAN_REVIEW ──→ SETTLED
   │
   ▼
EXPIRED ──→ REFUNDED

Agent escrows use shorter timeouts (minutes instead of days) and add arbitration-specific states: RESPONSE_PENDING, ESCALATED, AI_REVIEW, HUMAN_REVIEW, and SETTLED.

Milestone Escrows (FiDeal)

FiDeal supports milestone-based escrows where funds are divided across 2–10 deliverable stages. Each milestone has its own status lifecycle (matching the main escrow states) and can be independently delivered, released, or disputed. Milestone values must sum to the total escrow amount.

Protocol Fee

A protocol fee is charged on successful escrow releases and dispute resolutions. The fee is deducted from the settlement amount before funds are transferred to the payee.

Current rate: 3%
Applied to: Payee's portion only. Refunds to payer are fee-free.
Collected by: Fee collector address set in contract terms.

For dispute resolutions, a separate 5% arbitration fee is deducted before the split calculation when AI arbitration (Tier 2) is invoked.

Contract Terms

FiDeal (Human)

Term	Type	Default	Description
`protocolFeeRate`	Ratio	3% (300/10000)	Protocol fee on settlements.
`defaultDuration`	RelativeTime	7 days	Auto-expiry window.
`disputeWindow`	RelativeTime	3 days	Tier 1 negotiation window.
`disputeResolutionWindow`	RelativeTime	14 days	Total resolution window across all tiers.
`cancellationWindow`	RelativeTime	12 hours	Window for payer to cancel before delivery.
`defaultResponseWindow`	RelativeTime	2 days	Payee response window during disputes.
`feeCollectorAddr`	String (bech32)	—	Address that receives protocol fees.
`resolverAddr`	String (bech32)	—	Address authorized to submit dispute resolutions.

FiDealAI (Agent)

Term	Type	Default	Description
`protocolFeeRate`	Ratio	3% (300/10000)	Protocol fee on settlements.
`defaultTimeout`	RelativeTime	Per offerArgs	Escrow timeout.
`defaultDisputeWindow`	RelativeTime	—	Dispute window.
`defaultResponseWindow`	RelativeTime	30 min	Payee response window.
`defaultReviewTimeout`	RelativeTime	4 hours	Human review timeout.
`feeCollectorAddr`	String (bech32)	—	Address that receives protocol fees.
`reviewerAddress`	String (bech32)	—	Address authorized for human review.

Deployment

Contracts are deployed to Agoric via CoreEval governance proposals. Each proposal bundles the contract code and a startup script that installs the contract on Zoe and creates the instance.

CoreEval scripts are plain JavaScript (no ES module imports/exports). They receive { consume, produce, instance, installation } from the bootstrap powers and must use installBundleID() for installation.

Data Layer

Escrow state is published to VStorage at:

published.fideal2 — FiDeal human escrows
published.fidealai — FiDealAI agent escrows

VStorage is Agoric's on-chain key-value store, queryable via the chain's REST endpoint. Each escrow record includes full state: amounts, addresses, timestamps, dispute details, and resolution data.