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
@myong28
github profile →- 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 diffCheckout locally
git fetch origin pull/334/head:pr-334
git checkout pr-334