in reviewhumanPR #357Transport

VeriFlex: integrate Bona energy-flexibility trading with NandaTown and test lost-response handling

VeriFlex is our course project, using the Bona trust engine. Bona is the MCP trust service used by VeriFlex. It serves AI agents that trade energy flexibility.

Author

Status
In review
Opened on
Nov 11
Branch
integration/veriflex-bona-flex-lab

Description

The pitch.

## Summary

VeriFlex is our course project, using the Bona trust engine. Bona is the MCP trust service used by VeriFlex. It serves AI agents that trade energy flexibility. A buyer agent is about to pay for a seller's promise to cut load or export power in a 15-minute interval. Before it pays, Bona does four things:
- checks the offer against the meter's physical envelope;
- reserves the capacity atomically: the first commit wins, and a later request is cut down to what remains, or refused;
- settles delivery against metered readings;
- updates the seller's trust record.

Bona returns Ed25519-signed receipts over RFC 8785 canonical JSON for its holds, confirmations, settlements and trust results; in the recorded runs, every receipt verifies against the pinned key.

This PR adds `examples/bona_flex/`, a NandaTown scenario pack loaded through the scenario's `plugin_files`, and `tests/test_bona_flex_integration.py`. NandaTown's own source is not changed. The repository-level changes are two `.gitattributes` lines, which keep the evidence bytes exact, and four `.gitignore` lines for world folders.

The pack contains:
- Roles: buyers, a seller, a meter, a desk that drives the real Bona MCP server through a stdlib MCP client (`bona_link.py`), and a naive control desk;
- a pure validator: `bona_flex_validator.py`, 12 stages, importing only `nandatown` and the standard library;
- three scenarios, and the control's failing set, frozen before the first recorded run;
- `run_check.py`: one command for live runs, with a readable timeline;
- the offline checkers `check_evidence.py`, `check_receipts.py` and `verify.py`;
- the recorded evidence;
- a README.

## Integration

- **Where Bona runs.** Bona runs as its own process (`python -m bona.server`, MCP over stdio), spawned by the desk agent. Each run uses a new, fully synthetic world: invented ids and values in Bona's input format, and no utility data. The seller behaviours and the world simulator are reused unchanged from Bona's test bench, through a small operator helper (`bench.hw8.opserver`) that runs in Bona's own Python environment.
- **How NandaTown connects.** Buyers, the seller and the meter exchange Town messages, and only the desk calls Bona's four tools. Town provides:
  - registry discovery;
  - transport with injected faults (a dropped hold response, a duplicated hold request);
  - escrow and privacy redaction;
  - the signed attestation and the evidence bundle.

  Bona's full signed receipts sit in a sidecar next to the bundle. Each event carries its receipt's sha256, and one `bona_sidecar_bound` event carries the sidecar manifest hash, so Town's own manifest covers the receipts.
- **Changes on Bona's side.** Two bench-only seams; production defaults are unchanged:
  - a config-path override, accepted only in the bench environment;
  - a file-based test signing key, bound to the world folder.

  Both went through five review rounds, and Bona's own Phase 0 and Phase 1 gate suites passed on checkpoint `8cfac4d8b971e90ab92bf782ec81e7ebe75cc974` (private).

## Reproduce

> The public integration includes recorded end-to-end evidence and offline verification commands. Live end-to-end reproduction requires the private Bona runtime. Staff access was requested and remains pending.

**Pins:**
- NandaTown `6f9a7c064486c4a0ae9242f1ff341b8a4aad0244` (nandatown 0.2.0, evaluator `lab-0.2.6`).
- Bona runtime: an export, with no history, of private `dbeb00cb2c359cc8dfd7ae55040941f29d5cd9ba` (base `8f3ee028`). Live-tested at `d6ce1bb`. Distributed privately as `wcuelloj/veriflex-hw8-runtime`, tag `hw8-v1` = `8a2ca27`: packaging and README changes only after `d6ce1bb`, not live-tested again.
- Synthetic fixture manifest sha256 `5369ee0091457330162992836fa0da038d28d1fecbc1e942987a26fccf49e0f4`.
- **Verification platform:** Windows 11, Python 3.13.15 for everything, including pytest. The offline checkers (`check_evidence.py`, `check_receipts.py`, `verify.py`) were also run under Python 3.12.10 on

…

Try it

Open PR on GitHubView diff

Checkout locally

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