Skip to content

Commit 695b8c8

Browse files
author
Doug Hamaker
committed
Add dispute example bundle: end-to-end billing dispute proof
examples/dispute/ contains a complete scenario: - raw_events.json: 5 synthetic AI usage events (Acme Corp, 37,500 requests) - evidence.json: sealed evidence pack (schema 0.2.0, key_id dispute-demo-2026-q2) - evidence_tampered.json: same pack with event[1].quantity changed (4100 -> 2900) - verify_valid.txt: exact output of usageguard verify on intact pack - verify_tampered.txt: exact output on tampered pack (Event 1: leaf hash mismatch) - README.md: scenario, file descriptions, try-it commands, authority note No new CLI commands. No runtime changes. 4 regression tests: - bundled valid evidence verifies - bundled tampered evidence fails on event 1 - raw event count matches sealed event count - tampered event has different quantity, others unchanged 80 Rust + 16 Python = 96 tests green.
1 parent e2a0b38 commit 695b8c8

8 files changed

Lines changed: 987 additions & 1 deletion

File tree

Cargo.lock

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

examples/dispute/README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Dispute Example
2+
3+
A complete end-to-end example of how UsageGuard is used when a customer questions a usage invoice.
4+
5+
## Scenario
6+
7+
You bill Acme Corp for 37,500 API requests in the week of April 7-9, 2026:
8+
- 10,100 GPT-4o completion requests
9+
- 27,400 embedding requests
10+
11+
Acme disputes: "That seems high. How do we know those numbers weren't changed?"
12+
13+
You send them the evidence pack and your public key.
14+
15+
## Files
16+
17+
| File | What it is |
18+
|------|-----------|
19+
| `raw_events.json` | The 5 usage events as recorded by your system |
20+
| `evidence.json` | Sealed evidence pack (Merkle tree + ed25519 signature) |
21+
| `evidence_tampered.json` | Same pack with event[1] quantity changed from 4100 to 2900 |
22+
| `verify_valid.txt` | Output of `usageguard verify evidence.json` |
23+
| `verify_tampered.txt` | Output of `usageguard verify evidence_tampered.json` |
24+
25+
## Try it yourself
26+
27+
```bash
28+
# Verify the valid evidence pack
29+
usageguard verify evidence.json
30+
# Output: VERIFIED — 5 events, intact
31+
32+
# Verify the tampered evidence pack
33+
usageguard verify evidence_tampered.json
34+
# Output: FAILED — Event 1: leaf hash mismatch
35+
36+
# Optionally inspect how events were normalized (not authoritative)
37+
usageguard explain evidence.json
38+
usageguard explain evidence.json --event-index 1 --verbose
39+
```
40+
41+
## What happened in the tampered version
42+
43+
`evidence_tampered.json` is identical to `evidence.json` except `events[1].quantity` was changed from `4100.0` to `2900.0`. That single field change causes the leaf hash for event 1 to no longer match the Merkle proof, and `verify` reports the failure.
44+
45+
## Authority
46+
47+
Only `verify` determines whether the evidence pack is intact. `explain` is an inspection tool that helps humans read provenance and Merkle proofs — it is not the proof itself.
48+
49+
If `verify` passes, the evidence pack is intact and matches the signed usage record.
50+
51+
## Public key for this example
52+
53+
```
54+
2e930834ff9b43c01a897bd0dffa01bd0870505633b09615d0a532103ea472ee
55+
```
56+
57+
Key ID: `dispute-demo-2026-q2`
58+
59+
In production, the vendor publishes their public key separately (website, documentation, or direct exchange). The key inside the evidence pack is what was used to sign — you compare it against the key the vendor gave you.

0 commit comments

Comments
 (0)