> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pfbridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents & Disputes

> Soroban custom-account agents under scoped policies, order deadlines and cancel paths, bonded disputes with arbiter resolution, multi-key BLS registry.

<Note>
  🔨 **Planned for T2.** Builds on Phase 2's BLS-only auth model.
  Lands the agent-account model and dispute-handling paths on testnet,
  plus the multi-key `BLSKeyRegistry` upgrade.
</Note>

Phase 3 adds two capabilities held back from earlier phases:
**automated maker liquidity ops under a scoped policy**, and
**dispute paths for stuck or contested orders**. Both build on the
Phase 2 BLS foundation and introduce new on-chain primitives.

## Architecture diagram

<img src="https://mintcdn.com/proofbridge/1ew08pldeeuBKd_p/architecture/_diagrams/phase-3-agents-disputes.png?fit=max&auto=format&n=1ew08pldeeuBKd_p&q=85&s=683dbd6732db82c200c8a8246cc996cc" alt="Phase 3 architecture — Agents and disputes" width="1800" height="825" data-path="architecture/_diagrams/phase-3-agents-disputes.png" />

## Delta from Phase 2

What changes vs [Phase 2](/architecture/phase-2-bls-auth):

<CardGroup cols={2}>
  <Card title="Agent Account (Soroban + EVM)" icon="robot">
    Maker deploys their own contract — Soroban custom account with
    `__check_auth`, or per-maker Safe Module on EVM. Stores a policy
    table per agent (allowed actions, token whitelist, per-order cap,
    rate limit, expiry, revocation flag).
  </Card>

  <Card title="Multi-key `BLSKeyRegistry` v2" icon="layer-group">
    Replaces Phase 2's single-key registry. Each address can hold up
    to 5 active key slots with stable monotonic IDs and a `valid_until`
    timestamp per slot. `unlock` takes a slot hint so pairing-check
    cost stays at one attempt.
  </Card>

  <Card title="`OrderData` gains `deadline`" icon="clock">
    The `Order` struct expands from 15 to 16 fields — a signed
    `deadline` set per route. Both parties sign the deadline; each
    chain validates it's within bounds at create / lock time.
  </Card>

  <Card title="Cancel paths" icon="rotate-left">
    `cancel_order` (OrderPortal) and `cancel_lock` (AdManager) are
    permissionless after deadline. Refunds via pull-payment escrow,
    unwinds maker `ad.locked` back into ad balance.
  </Card>

  <Card title="Dispute lifecycle" icon="scale-balanced">
    `dispute()` posts a bond and moves the order into `Disputed`.
    `respond_to_dispute()` lets the counterparty add evidence.
    `resolve_dispute()` pays out per a discrete `DisputeOutcome` enum.
  </Card>

  <Card title="`ArbiterRole` actor" icon="user-shield">
    A new role holds dispute-resolution authority. In T2 this equals
    the protocol admin; the role moves to its own multisig in
    [Phase 4](/architecture/phase-4-mainnet).
  </Card>
</CardGroup>

## How agents work

A maker who wants automated liquidity operations:

<Steps>
  <Step title="Deploy an Agent Account">
    Soroban: deploy a custom-account contract that implements
    `__check_auth`. EVM: deploy a per-maker Safe + Safe Module. Either
    way, the maker is the owner.
  </Step>

  <Step title="Set the agent's policy">
    Owner calls `set_policy(agent_pubkey, policy)` with allowed actions,
    token whitelist, per-order cap, rate limit, expiry, and revocation
    flag.
  </Step>

  <Step title="Register the agent's BLS pubkey">
    Owner registers the agent's BLS public key against the Agent
    Account's address. The agent becomes the maker's BLS-signing
    identity for trades within policy.
  </Step>

  <Step title="Point ads at the Agent Account">
    Maker creates ads with `ad_creator = agent_account_address`. The
    agent can call `lock_for_order` and produce BLS signatures within
    policy bounds — without ever holding the maker's wallet key.
  </Step>

  <Step title="Rotate keys in one tx">
    To replace an agent (compromise, software change), the maker adds
    a new BLS key slot and sets `valid_until` on the old slot. No need
    to close ads or migrate liquidity.
  </Step>
</Steps>

Agents cannot initiate disputes, modify their own policy, touch funds
outside the maker's ads, or operate beyond `valid_until` / rate-limit
ceilings.

## How disputes work

The order lifecycle expands from `None → Open → Filled` to include two
new branches:

```text theme={null}
None → Open → Filled                    (happy path, unchanged from Phase 2)
       Open → Cancelled                 (timeout-based unwind after deadline)
       Open → Disputed → Resolved       (challenge path before deadline)
```

Disputes are raisable on either chain while the order is `Open` and
**before** the route's deadline. After deadline, the cancel path takes
over — no arbiter needed. The bond + arbiter judgement deters frivolous
disputes; the system self-regulates on incentives.

`DisputeOutcome` covers the four real-world resolutions:

| Outcome          | Source side (OrderPortal)             | Destination side (AdManager)                    |
| ---------------- | ------------------------------------- | ----------------------------------------------- |
| `MutualRefund`   | Bridger refunded                      | `ad.locked -= ad_amount` (back into ad balance) |
| `TradeProceeds`  | Bridger's deposit → maker's recipient | Maker's locked balance → bridger's recipient    |
| `BridgerForfeit` | Bridger's deposit → maker (forfeit)   | `ad.locked -= ad_amount`                        |
| `MakerForfeit`   | Bridger refunded                      | Maker's locked balance → bridger's recipient    |

The arbiter is responsible for issuing matching outcomes on both
chains. Off-chain coordination keeps the two halves consistent.

## Using the BLS auth circuit in disputes

The standalone Noir BLS auth circuit from
[Phase 2](/architecture/phase-2-bls-auth) finds its first real use
here. A counterparty defending a dispute can submit a ZK proof
attesting "I had a valid aggregated BLS authorization for this trade"
without publishing the raw aggregated signature off-chain. The
existing UltraHonk verifier checks the proof on-chain, and the
arbiter sees a portable cryptographic claim instead of asking for
screenshots.

## What ships next

<Card title="Phase 4: Mainnet Launch" icon="arrow-right" href="/architecture/phase-4-mainnet">
  Stellar + Ethereum mainnet deploy, admin and ArbiterRole both hand
  off to multisigs, 24-hour timelock on critical admin actions, protocol
  fee mechanism, USDC ↔ USDC launch route, cross-chain reconciliation
  listener.
</Card>