in reviewhumanPR #319Identity
TrailProof: run an agent purchase and its dispute under Track, cross-verified against a shared ledger
TrailProof is an append-only commitment ledger for purchases made by AI agents, exposed as an MCP server (https://github.com/Andreyivvi/TrailProof).
Author
@Andreyivvi
github profile →- Status
- In review
- Opened on
- Nov 5
- Branch
- integration/trailproof-quote-ledger
Description
The pitch.
## Summary TrailProof is an append-only commitment ledger for purchases made by AI agents, exposed as an MCP server (https://github.com/Andreyivvi/TrailProof). Buyer agent, merchant and payment provider each lock a signed SHA-256 fingerprint of what they saw at every step of an order; on a dispute each side reveals its plaintext, the ledger checks it against the committed hashes, and a deterministic rules engine produces findings and a verdict. This PR adds `examples/trailproof/`: a TrailProof-aware buyer and seller for Town's Track, a standard-library MCP client that speaks TrailProof's documented contract, a reproducible compatibility check (`run_check.py`) with recorded evidence, and `tests/test_trailproof_integration.py` (skipped unless `TRAILPROOF_HOME` is set). The quote task is unchanged. Underneath it the two participants run TrailProof's whole order lifecycle against one shared ledger: the user key commits a MANDATE, the seller commits its OFFER, the buyer agent orders only after `check_order` says the offer is inside the mandate, the seller's payment provider commits the CHARGE, the seller commits the FULFILMENT, and the buyer commits the DELIVERY it actually found. When the parcel is not what was offered the buyer opens a dispute, both sides reveal, the ledger decides, and the payment provider refunds. Ledger receipts travel in Town's acknowledgement notes, so Town's bundle, the ledger chain and the exported evidence pack can be cross-checked offline. ## Integration - **Where the project runs**: in its own checkout, as a separate process: `python -m trailproof.server --http` (MCP streamable HTTP, one shared ledger for all participants). The project code is not in this PR. - **How Town connects**: the two participants are ordinary `cmd:` harnesses over the mailbox contract (`TownClient`, `Journal`, `run_loop`). They talk to the ledger through `examples/trailproof/trailproof_link.py`, which re-implements TrailProof's canonical JSON, `sha256(canonical_json(payload))`, the `commit|prev|refs` signing message and the `event_id|commit|ledger_ts` receipt from TrailProof's README, with Ed25519 from `cryptography` (already a Town dependency). It does not import the TrailProof package, so a passing run also shows a third-party client built from the documented contract interoperates with the server. - **How the agents coordinate past the quote**: through the ledger alone. Town's mailbox carries only the quote request and response. The seller acts when the buyer's ORDER appears on the chain and when a case is opened; the buyer acts when the FULFILMENT appears. The delivery itself is a file the seller drops and the buyer reads, the one channel that is neither Town nor the ledger. - **First compatibility check**: Town's own MCP handshake probe, `nandatown mcp test --cmd "... -m trailproof.server"`, reports `ok: true` and lists TrailProof's nine tools. - **Change on the project side**: TrailProof's server was stdio-only; a `--http` flag was added so two Town participants can commit to the same chain. ## Reproduce Town: this branch on top of `projnanda/nandatown` main at `6f9a7c0` (nandatown 0.2.0). TrailProof: 0.1.0 at `8bd88b9` (also recorded in `examples/trailproof/evidence/summary.json`). Python 3.12, Windows 11 (the participants use only Town and the standard library; no platform-specific code). ```bash git clone https://github.com/Andreyivvi/TrailProof && (cd TrailProof && uv sync && uv run pytest) python3 -m venv .venv && source .venv/bin/activate && python -m pip install -e '.[dev]' nandatown mcp test --cmd "TrailProof/.venv/bin/python -m trailproof.server" TRAILPROOF_HOME=$PWD/TrailProof python examples/trailproof/run_check.py TRAILPROOF_HOME=$PWD/TrailProof python -m pytest -q tests/test_trailproof_integration.py # 15 passed nandatown verify examples/trailproof/evidence/wrong_product # recorded bundle, offline ``` `run_check.py` starts the ledger, runs eight Track cases with both …
Try it
Open PR on GitHubView diffCheckout locally
git fetch origin pull/319/head:pr-319
git checkout pr-319