x0-escrow

Program ID: AhaDyVm8LBxpUwFdArA37LnHvNx6cNWe3KAiy8zGqhHF x0-escrow enables trustless conditional payments between agents and services. Funds are locked in a PDA-controlled token account until delivery conditions are met, a dispute is resolved, or a timeout expires.

State Machine

Every escrow follows a strict state transition graph:

Created ──fund──▶ Funded ──deliver──▶ Delivered ──release──▶ Released
   │                │                     │
   │cancel          │dispute              │dispute
   ▼                ▼                     ▼
Cancelled        Disputed ──resolve──▶ Released / Refunded
                    │
                    │timeout
                    ▼
                 Refunded

Funded ──timeout──▶ auto-release ──▶ Released (to seller)

State	Description
`Created`	Escrow account initialized, not yet funded
`Funded`	Buyer has deposited tokens into the escrow vault
`Delivered`	Seller has marked delivery with optional proof hash
`Disputed`	Either party has raised a dispute with evidence
`Released`	Funds released to seller (terminal)
`Refunded`	Funds returned to buyer (terminal)
`Cancelled`	Escrow cancelled before funding (terminal)

Instructions

`create_escrow`

Creates a new escrow PDA and associated token vault.

create_escrow(
    amount: u64,
    memo_hash: [u8; 32],
    timeout_seconds: i64,
    arbiter: Option<Pubkey>
)

Parameter	Type	Description
`amount`	`u64`	Token amount to escrow (micro-units)
`memo_hash`	`[u8; 32]`	SHA-256 of the transaction memo/agreement
`timeout_seconds`	`i64`	Auto-release timeout (1 hour – 30 days)
`arbiter`	`Option<Pubkey>`	Optional third-party dispute resolver

`fund_escrow`

Buyer deposits the specified amount into the escrow vault. Transitions state from Created → Funded.

`mark_delivered`

Seller claims delivery, optionally providing a proof hash. Transitions Funded → Delivered.

mark_delivered(proof_hash: Option<[u8; 32]>)

`release_funds`

Buyer confirms satisfaction and releases funds to seller. Transitions Delivered → Released. Also records a successful transaction to x0-reputation via CPI.

`initiate_dispute`

Either buyer or seller raises a dispute with evidence.

initiate_dispute(evidence_hash: [u8; 32])

Transitions to Disputed. Records the dispute_initiated_slot for arbiter delay enforcement.

`resolve_dispute`

Only callable by the designated arbiter. Subject to ARBITER_RESOLUTION_DELAY_SLOTS = 216,000 (~24 hours) — the arbiter cannot resolve immediately after a dispute is raised.

resolve_dispute(release_to_seller: bool)

true → Funds released to seller, state → Released
false → Funds refunded to buyer, state → Refunded

`claim_auto_release`

Seller claims funds after the timeout has expired. Only valid when state is Funded or Delivered and the timeout has passed.

`claim_timeout_refund`

Buyer claims a refund if the escrow has timed out without delivery and no auto-release was triggered.

`cancel_escrow`

Cancels the escrow before it is funded. Only the buyer can cancel. State → Cancelled.

State Account

EscrowAccount

pub struct EscrowAccount {
    pub version: u8,
    pub buyer: Pubkey,
    pub seller: Pubkey,
    pub arbiter: Option<Pubkey>,
    pub amount: u64,
    pub memo_hash: [u8; 32],
    pub state: EscrowState,
    pub timeout: i64,
    pub created_at: i64,
    pub delivery_proof: Option<[u8; 32]>,
    pub dispute_evidence: Option<[u8; 32]>,
    pub mint: Pubkey,
    pub token_decimals: u8,
    pub dispute_initiated_slot: u64,   // For arbiter delay
    pub bump: u8,
}

PDA Seeds: ["escrow", buyer, seller, memo_hash]

Timeout Mechanics

Default timeout: 72 hours (DEFAULT_ESCROW_TIMEOUT_SECONDS = 259,200)
Minimum: 1 hour (MIN_ESCROW_TIMEOUT_SECONDS = 3,600)
Maximum: 30 days (MAX_ESCROW_TIMEOUT_SECONDS = 2,592,000)
Buffer: An additional ESCROW_TIMEOUT_BUFFER_SLOTS = 1,500 (~10 minutes) is added as safety margin
Auto-release: After timeout, the seller can call claim_auto_release to receive funds

Reputation Integration

On escrow completion, x0-escrow updates x0-reputation via CPI:

Outcome	Reputation Record
`release_funds` (buyer satisfied)	`record_success(response_time_ms)`
`resolve_dispute(true)` (seller wins)	`record_resolution_favor()`
`resolve_dispute(false)` (buyer wins)	`record_dispute()`
Policy rejection during funding	`record_failure(error_code)`

Events Emitted

Event	When
`EscrowCreated`	New escrow initialized
`EscrowFunded`	Buyer deposited tokens
`DeliveryMarked`	Seller claimed delivery
`DisputeInitiated`	Dispute raised
`FundsReleased`	Funds sent to seller
`FundsRefunded`	Funds returned to buyer
`DisputeResolved`	Arbiter resolved dispute

Overview

Core Programs

Zero-Knowledge

Application Layer

Reference

State Machine

Instructions

`create_escrow`

`fund_escrow`

`mark_delivered`

`release_funds`

`initiate_dispute`

`resolve_dispute`

`claim_auto_release`

`claim_timeout_refund`

`cancel_escrow`

State Account

EscrowAccount

Timeout Mechanics

Reputation Integration

Events Emitted

​State Machine

​Instructions

​create_escrow

​fund_escrow

​mark_delivered

​release_funds

​initiate_dispute

​resolve_dispute

​claim_auto_release

​claim_timeout_refund

​cancel_escrow

​State Account

​EscrowAccount

​Timeout Mechanics

​Reputation Integration

​Events Emitted

State Machine

Instructions

`create_escrow`

`fund_escrow`

`mark_delivered`

`release_funds`

`initiate_dispute`

`resolve_dispute`

`claim_auto_release`

`claim_timeout_refund`

`cancel_escrow`

State Account

EscrowAccount

Timeout Mechanics

Reputation Integration

Events Emitted