in reviewhumanPR #351Transport

Pearl Street: metered peak-reduction market in the Lab, with an overpromising provider

Runs Pearl Street, a flexibility exchange for energy agents, end to end in the Town Lab. A utility posts a 30 MW peak-reduction need. Five sites register, find the exchange in Town's index and offer kW.

Author

Status
In review
Opened on
Nov 11
Branch
integration/pearl-street-flex-market

Description

The pitch.

## Summary

Runs Pearl Street, a flexibility exchange for energy agents, end to end in the Town Lab. A utility posts a 30 MW peak-reduction need. Five sites register, find the exchange in Town's index and offer kW. Their limits come from the synthetic, public Engie challenge dataset (80 prosumers), so every site number is synthetic. Pearl Street's real exchange clears them at one uniform price. A meter attests delivery every 15 minutes. Settlement moves through Town's ledger and drives Town reputation.

The boundary case is an overpromising provider. Its declared mandate is 3x its metering-attested power. Pearl Street accepts it, and the provider wins an award it cannot deliver. It is caught only at settlement, and the grid is left 9,298 kW short at peak.

Town fault injection is then run on the same roster: three named transport faults (drop, duplicate, delay) and a drop-rate sweep (1%, 5%, 10%, 20 seeds each). A single lost meter reading is enough for Pearl Street to charge an honest provider and rate it down.

Three follow-ups, on the same roster:
- **A split sweep** shows that this harm comes mainly from Pearl Street's missing-reading rule. A late reading is treated the same as a lost one.
- **A two-evening repeat** shows the overpromiser wins again on day two when nothing feeds back. A Town reputation gate cuts the day-two shortfall from 9,298 to 6,000 kW.
- **A forged registry listing** takes the whole market offline under Town's default registry, but not under `index.owned.v1`.

Everything is under `examples/pearl_street/`. No Town code is changed. The adapter, the exchange and the test share one author (see Results and limitations).

## Integration

- **Pearl Street side.** `exchange.core.Exchange` comes from the public repo [cafetters/pearl-street-public](https://github.com/cafetters/pearl-street-public), pinned to commit `f839d1e2e8482152109c53f2f5234c9a40b3da27` in `examples/pearl_street/requirements.txt`. That repo is a one-commit snapshot of a private development repo at `f7128ab5f2984874b684b1cb0ab881b8c29c152b`. Some internal notes are left out, and nothing in `exchange/` changed. The exchange package is standard-library only. It installs with `--no-deps` because `flex-exchange`'s declared dependencies (pandas, pandapower, ...) serve its own simulator, which is not used here.
- **Town side.** `pearl_street_town.py` is loaded through the scenario's `plugin_files:` and registers five roles:
  - `pearl_exchange` hosts the exchange and passes each Town message through `Exchange.handle()`. The Pearl Street envelope's `sender` is the Town sender that Town's auth layer verified, and its `t_utc` is the arrival time, so neither is chosen by the agent.
  - `grid_operator` is the utility: it posts the need, pays credits and rates providers.
  - `meter` attests asset limits and is the only source of delivery readings.
  - `flex_provider` is a data center or a PV + battery site. Each one's honesty is set in config.
  - `listing_forger` is used only by the forged-listing test. Like Town's `rival_forger`, it republishes another agent's registry card with its own key.
- **Shared Town layers exercised:**
  - registry: discovery of the exchange and the meter by capability
  - auth: signatures and the sender binding above
  - data_facts: attested limits and 15-minute readings
  - payments: credits and shortfall charges in cents; money is conserved
  - trust: ratings driven by Pearl Street's delivery record
- **Validator.** `pearl_street_validator.py` does not import Pearl Street. It recomputes clearing and settlement from the scenario recipe and the meter's attestations. Every check fails if a configured participant is missing, so a dropped message cannot become a pass.
- **Data.** The synthetic, public Engie challenge dataset (80 prosumers, 2023, 15-minute steps; built from public NREL, EIA, Census and MISO sources). `engie_slice.json` holds five sites' limits (one data center, four PV + battery sites) from the dataset's metadata

…

Try it

Open PR on GitHubView diff

Checkout locally

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