> ## 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.

# Architecture

> Four contracts per chain, a coordinating relayer, and background workers

## Per chain: four contracts

| Contract         | Role                                                           |
| ---------------- | -------------------------------------------------------------- |
| `AdManager`      | maker escrow — ads, liquidity, lock-for-order                  |
| `OrderPortal`    | bridger escrow — orders and deposits                           |
| `MerkleManager`  | the append-only MMR of deposits                                |
| `BLSKeyRegistry` | wallet → settlement-key registry, proof-of-possession enforced |

Deposits into either escrow append to the MMR. Unlocks verify the
aggregated BLS signature against the registry and the deposit proof
against the counterparty chain's root.

<img src="https://mintcdn.com/proofbridge/Q904cguIxUfnPlot/architecture/_diagrams/phase-2-bls-auth.png?fit=max&auto=format&n=Q904cguIxUfnPlot&q=85&s=20b476208b4b121cc89d032fa92007f2" alt="T1 delivered architecture — BLS auth, pre-auth retired" width="1800" height="668" data-path="architecture/_diagrams/phase-2-bls-auth.png" />

```mermaid theme={null}
flowchart TB
    M["Maker"]:::actor
    B["Bridger"]:::actor
    R["Relayer workers<br/>aggregate · prove · submit"]:::actor

    subgraph CHAIN["Each chain (mirrored on the other)"]
        AM["AdManager<br/>maker escrow"]
        OP["OrderPortal<br/>bridger escrow"]
        MM["MerkleManager<br/>append-only MMR"]
        REG["BLSKeyRegistry<br/>wallet → settlement key"]
        CPV["CounterpartyVerifier<br/>BLS pairing check"]
        V["Verifier<br/>ZK deposit proof"]
        AM -- "appendOrderHash" --> MM
        OP -- "appendOrderHash" --> MM
        AM -- "verify agg sig" --> CPV
        OP -- "verify agg sig" --> CPV
        CPV -- "keyOf(party)" --> REG
        AM -- "verify proof" --> V
        OP -- "verify proof" --> V
    end

    M -- "register key · create ad · lock" --> CHAIN
    B -- "register key · create order" --> CHAIN
    R -- "submit unlocks (permissionless)" --> CHAIN
```

## The relayer: coordinator, not authority

The relayer holds **no funds** and grants **no approvals**. Its jobs:

* mirror each chain's MMR and serve trade/route/ad state over the API
* collect the two parties' co-signatures and reject malformed ones early
* run the background pipeline: **aggregate → prove → submit**
* sponsor gas for key registrations and unlocks

Every fund movement is gated by the parties' signatures plus proofs, so
any honest actor could run the same code and submit the same
transactions — unlocks are permissionless by design.

## Background workers

Settlement work is queued, idempotent, and crash-safe:

* **Aggregator** — combines the two BLS signatures once both arrive
* **Prover** — generates the two deposit proofs (seconds each)
* **Submitter** — broadcasts the unlocks with retry, stuck-transaction
  handling, and a circuit breaker; confirms against chain state

A watchtower reconciles the database against the chains and raises alarms;
the database is a rebuildable projection of chain events, not a source of
authority.

## What changed from v1

The v1 relayer pre-authorized every trade with its own signature inside
each contract call. Those parameters — the authorization token, signature,
and expiry — are deleted from every state-changing entry point on both
chains. The v1 docs remain available in the version picker for the
historical design.