in reviewhumanPR #334Transport

FairClear: add sealed second-price procurement integration and forged/late-bid tests

FairClear is a clearing service for AI agents: instead of haggling, a buyer agent opens a sealed request for quotes (RFQ), each seller agent submits one sealed bid, the lowest bid wins and is paid the second-lowest bid (Vickrey RFQ), and…

Author

Status
In review
Opened on
Nov 10
Branch
integration/fairclear-sealed-clearing

Description

The pitch.

## Summary
FairClear is a clearing service for AI agents: instead of haggling, a buyer agent opens a sealed request for quotes (RFQ), each seller agent submits one sealed bid, the lowest bid wins and is paid the second-lowest bid (Vickrey RFQ), and the result is signed so anyone can check it.

This PR adds `integrations/fairclear/`: a Lab scenario in which Town's own agents discover FairClear through the Town index and run a full procurement through it — sealed signed bids, clearing, a signed result the buyer verifies, and settlement through Town escrow — plus a validator that checks every step from recorded events. No Town core files change.

## Integration
- **Town layers exercised:** registry (FairClear publishes `clearing.sealed2p`; buyer looks it up), auth (bid commitments signed with each seller's Town identity; forged sender rejected; clearing result signed and verified by the buyer), payments (escrow hold, refund, release), communication/transport (envelopes), data_facts and memory.
- **Plugin file:** `fairclear_town.py`, loaded through the scenario's `plugin_files`; roles `fairclear_clearing`, `fairclear_buyer`, `fairclear_seller`; validator `fairclear_procurement`.
- **Separately hosted service:** the clearing decision can be delegated to a live FairClear deployment (`FAIRCLEAR_BACKEND=external`, `FAIRCLEAR_CLEARING_CMD=<bridge>`), via a JSON stdin/stdout contract documented in the README. The deployment and its bridge run outside this repo; the default `reference` backend is a textbook implementation so anyone can reproduce the run.

## Reproduce
- Nanda Town commit: `6f9a7c0` (main, 4 Nov 2026); nandatown 0.2.0; evaluator lab-0.2.6; Python 3.12.
- FairClear version: private build of 10 Nov 2026, mechanism `vickrey-rfq-v1`.
```bash
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e '.[dev]'
nandatown run integrations/fairclear/fairclear_procurement.yaml
python -m pytest -q tests/test_fairclear_integration.py
```

## Results and limitations
**Interface under test:** Town agents → Town registry → FairClear clearing service (sealed bids over Town messaging, signed by Town auth) → signed result → Town escrow settlement.

Scenario: buyer wants 2 widgets, private reserve 2000 cents/unit. Sellers' costs: a 1800, b 1700, c 1900 (also sends a duplicate bid), plus a late bidder (1500) and a forger impersonating seller-a.

| Stage | Expected | Observed (reference) | Observed (live FairClear) |
|---|---|---|---|
| discovery | buyer finds `clearing.sealed2p` in the index | passed | passed |
| sealed_bids | 3 honest bids, only commitments recorded before close | passed | passed |
| rejections | duplicate, late and forged bids rejected | passed (`duplicate bid`, `rfq closed`, `bad signature`) | passed |
| efficient_award | lowest cost (seller-b) wins | passed | passed |
| second_price | paid 1800/unit (second-lowest) | passed | passed (real engine's signed result also verified offline: `verified: true`) |
| receipt_verified | buyer verifies signature and recomputes award | passed | passed |
| settlement | one escrow release of 3600 to seller-b, rest refunded | passed | passed |
| ledger_conserved | money conserved | passed (10000 cents) | passed |

**Failure / boundary cases (in `tests/test_fairclear_integration.py`):**
- A wrong clearing service (pays the winner its own bid, i.e. first price) plugged in as the external backend: `second_price` and `receipt_verified` fail, the buyer refuses to pay (escrow refunded), and the ledger still balances.
- One eligible bid pays the reserve; bids above the reserve never win.
- The late bid is the one that would otherwise have won (1500): Town rejects it after close.

Full Town suite: 1868 passed, 1 skipped (the live-deployment test, which skips without `FAIRCLEAR_CLEARING_CMD`).

**Not tested:** Track (HTTP mailbox) and Path (A2A) modes; model-driven agents (all agents here are scripted); differentiated goods; network faults during bidding; collusion across repeated

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/334/head:pr-334
git checkout pr-334