Escrow modes

Plaza intermediates the money in one of two modes per order. Both ship at launch. Both share the same order shape, thread, dispute pipeline, and ledger. Only the on-chain leg differs.

The mode is fixed at order placement and recorded on the receipt.

Custodied

Funds during escrow live in a Plaza-controlled hot wallet on Base, commingled with all other custodied-mode in-flight escrow. Plaza tracks per-order ownership in a Postgres ledger.

Flow.

1. Buyer’s agent calls POST /orders {ask URN, escrow_mode: "custodied"}.
2. Plaza returns 402 Payment Required with recipient = <Plaza hot wallet>.
3. Buyer signs an EIP-3009 transferWithAuthorization and submits it to POST /orders/{id}/fund.
4. Plaza submits the authorization on-chain. On confirmation, Plaza writes the ledger entries and the escrow_holds row, and transitions the order to funded.
5. On acceptance, Plaza writes the release ledger entries and the on-chain payout — one transfer of 19 USDC to the seller, with 1 retained as fee.
6. On dispute, the resolution path follows the verdict’s remedy with mode-specific transfers (one transfer for full release or full refund, two for partial).

Ledger. Double-entry, per-order. Every transaction sums to zero. The ledger is the source of truth for “what is in the hot wallet”; reconciliation against the on-chain balance runs continuously.

Hot/cold split. The hot wallet holds in-flight escrow plus a small operational buffer. Fee revenue and any excess sweeps to a cold multisig wallet. Sweeping is event-driven (after each release) and time-driven (hourly).

Hack exposure. Compromise of the hot wallet drains all in-flight custodied escrow plus the operational buffer. Mitigations:

• MPC signing (Privy / Turnkey / Fireblocks) — no single key holds the funds.
• Per-day signer caps enforced at the MPC provider.
• Aggressive sweep cadence.
• Cold wallet behind a 2-of-3 multisig with distinct keyholders.

Contract

Funds during escrow live in a Plaza-deployed escrow smart contract on Base, segregated by order_id. The contract enforces “funds for order X are released only by Plaza’s resolver key, only up to the funded amount.”

Contract surface.

contract PlazaEscrow {
    struct Hold { uint256 amount; address funder; bool open; }
    mapping(bytes32 => Hold) public holds;
    address public resolver;
    address public admin;
    bool public paused;

    function fund(bytes32 orderId, uint256 amount, address funder) external;
    function release(bytes32 orderId, address[] calldata to, uint256[] calldata amounts) external onlyResolver;
    function setResolver(address) external onlyAdmin;
    function pause() external onlyAdmin;
}

The release function accepts an array of (recipient, amount) pairs whose sum equals the held amount. This natively supports all three remedies — full to seller plus fee, full to buyer, partial split.

Flow. Identical to custodied except step 2 names the contract address as recipient and step 5 calls escrow.release(...) rather than signing a transfer from the hot wallet.

Hack exposure. Compromise of the resolver key lets the attacker call release on every in-flight order, bounded to in-flight contract escrow at that moment. Plaza pauses the contract, rotates the resolver, resumes. Compromise of the admin key (cold multisig) is needed to point the contract at a malicious resolver — much higher bar.

Contract risk. The contract code itself is a target. Mitigations:

• Minimal contract surface.
• Third-party audit before mainnet deployment.
• Bug bounty post-deploy.
• Non-upgradable contract. Migration is deploy-and-drain — deploy v2, route new orders to v2, drain v1 as orders resolve.

When each mode is used

The mode is set at order placement.

1. If the buyer’s agent specifies escrow_mode in the order request, that mode is used (subject to listing eligibility).
2. Otherwise, Plaza policy decides. The configurable default at launch: contract for orders at or above $1,000, custodied below.
3. Sellers can opt their listings into “contract only.”

On-chain transaction count per mode

The release path determines the count. Funding is one EIP-3009 transferWithAuthorization in both modes, submitted by Plaza’s facilitator on the buyer’s behalf.

Custodied

Outcome	Funding txs	Release txs	Total
Acceptance (release_to_seller)	1	1 (Plaza → seller, gross net of fee)	2
Verdict release_to_seller	1	1	2
Verdict full_refund	1	1 (Plaza → buyer)	2
Verdict partial_refund	1	2 (Plaza → buyer, Plaza → seller)	3

Fee revenue stays internal to the hot wallet’s ledger and sweeps to cold on its own cadence (event-driven after each release, time-driven hourly). The sweep is amortized across many orders and is not counted per-order.

Contract

Outcome	Funding txs	Release txs	Total
Acceptance (release_to_seller)	1 (fund)	1 (release with [seller, fee])	2
Verdict release_to_seller	1	1	2
Verdict full_refund	1	1 (release with [buyer])	2
Verdict partial_refund	1	1 (release with [buyer, seller, fee])	2

The contract’s release(orderId, address[] to, uint256[] amounts) call accepts an array, so partial refunds are one transaction in contract mode and two in custodied mode.

Gas cost ranges

Approximations on Base mainnet at recent gas prices (1–10 gwei). Replace with live numbers from your gas oracle in production accounting. Custodied mode pays gas for Plaza’s transfers; contract mode pays the same plus the contract dispatch.

Operation	Custodied	Contract
Fund (EIP-3009, facilitator-submitted)	70k–110k gas	130k–180k gas
Release, single recipient	50k–70k gas	90k–130k gas
Release, two recipients (partial)	100k–140k gas (two transfers)	110k–150k gas (one call, two transfers)

USD cost on Base at 5 gwei and ETH = $3,000: roughly $0.001 per simple transfer, $0.002–$0.003 per contract call. Plaza absorbs gas out of the 5% fee. The contract premium becomes meaningful only at very small order sizes; the default threshold (below) is set so that gas does not eat the fee margin.

Mode-selection logic

                       POST /v1/orders {ask_urn?, bid_urn?, quote_urn?,
                                        escrow_mode? }
                                  │
                                  ▼
                  ┌────────────────────────────────┐
                  │ buyer set escrow_mode in body? │
                  └────────────┬───────────────────┘
                               │
                  ┌────────────┴───────────┐
                yes                          no
                  │                           │
                  ▼                           ▼
       ┌──────────────────┐    ┌────────────────────────────────┐
       │ ask listing      │    │ price >= PLAZA_MODE_THRESHOLD? │
       │ marked           │    │   (default 1000.000000 USDC)   │
       │ contract-only?   │    └────────────┬───────────────────┘
       └──────┬───────────┘                 │
              │                  ┌──────────┴────────┐
       ┌──────┴──────┐         yes                    no
       yes            no         │                     │
       │              │          ▼                     ▼
       ▼              ▼     escrow_mode =         escrow_mode =
   override     respect      contract              custodied
   to contract  buyer
                pick
              │
              ▼
   record on PaymentRequirements (402)
   record on Order.escrow_mode
   record on Receipt.escrow_mode

Once recorded on placement, the mode is immutable. It travels onto the receipt and is queryable from the receipt forever. The reputation index aggregates across both modes; the mode is a wire-level detail, not a reputation signal.

Configuration

The relevant environment variables, settled across A2 (API surface) and A6 (host config):

• PLAZA_USDC_ADDRESS — USDC token contract on the chosen network (e.g. 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 on Base mainnet, the Sepolia mock on testnet).
• PLAZA_HOT_WALLET_ADDRESS — recipient for custodied mode funding.
• PLAZA_ESCROW_ADDRESS — PlazaEscrow deployment for contract mode funding.
• PLAZA_FACILITATOR_ADDRESS — submits EIP-3009 authorizations on-chain.
• PLAZA_CHAIN_RPC — Base RPC endpoint for funding submission, payouts, and reconciliation.
• PLAZA_MODE_THRESHOLD_USD — order-size threshold above which Plaza policy defaults to contract. Default 1000 (USD; converted to UsdcAmount per request).
• PLAZA_HOT_WALLET_DAILY_CAP_USD — per-day signer cap enforced at the MPC provider; alert above 80%.
• PLAZA_RESOLVER_DAILY_CAP_USD — same, for the contract-mode resolver key.
• PLAZA_CUSTODIED_MODE_DISABLED — emergency toggle. When set, new orders fall through to contract regardless of policy. Used during reconciliation drift incidents (see docs/operations/runbook.md).
• PLAZA_AUTO_ACCEPT_DISABLED — pauses auto-acceptance jobs during RPC outage.
• PLAZA_AUTO_ACCEPT_SECONDS — default auto-acceptance window. Per-ask override via Ask.auto_accept_seconds.

The MPC provider (Privy or Turnkey) takes its own PLAZA_* keys; see infra/mpc/.env.example.

Tradeoffs

	Custodied	Contract
On-chain operations per order	2 (acceptance / release / full refund); 3 (partial)	2 (every outcome)
Gas cost per order	Low (~0.001–0.003 USD)	Moderate (~0.002–0.005 USD)
Inference cost	None added	None added
Custody risk	Hot-wallet drain risk	Resolver-key drain bounded to in-flight contract escrow
Contract risk	None	Code-exploit risk
Time to resolution	Fastest (no contract round trip)	Slower (contract call confirmation)
Partial refund	Two transfers	One release call with array
Day-one ship	Fastest	Requires audit

Large orders go to contract mode where the security premium is justified. Small orders stay custodied where overhead matters and the operational risk to Plaza is bounded by the hot-wallet cap.

What doesn’t differ

• Order shape and state machine.
• Thread and message types.
• Dispute pipeline and arbitrator.
• Reputation. Composite scores aggregate receipts across both modes.
• Receipts. The escrow_mode field is recorded on the receipt; everything else is identical.

A buyer or seller never has to think about both modes at once. The mode is a wire-level detail of how money is held during the work.

Migration

Plaza will tighten the dollar threshold over time as contract gas becomes a smaller share of small-order economics. The current threshold is exposed at the public configuration endpoint and recorded on each receipt.

If the contract has a finding, Plaza pauses it, deploys v2, and drains v1 by letting v1 orders resolve. Custodied mode can absorb new volume during the cutover.

API surface

• POST /v1/orders body field: escrow_mode: "custodied" | "contract" | null. Null lets server policy decide.
• The 402 response (PaymentRequirements) carries escrow_mode; the recipient is the hot wallet for custodied and the PlazaEscrow contract for contract.
• GET /v1/orders/{urn} carries Order.escrow_mode, set on placement.
• GET /v1/receipts/{urn} carries the receipt’s escrow mode for the historical record.
• The escrow-hold lifecycle (EscrowHold.status) is the same in both modes: held → released | refunded | split. The on-chain transactions back the same status transitions.