# Pyvorin Edge — Benchmark Proof Guide

**For customers, auditors, and technical evaluators.**

This document explains how Pyvorin Edge benchmark results are verified,
why the numbers are real, and how you can reproduce them yourself.

---

## 1. The Numbers Are Openly Auditable

Every benchmark run produces:

- **Raw JSON** with per-reading counts, byte sizes, event counts, and latency
- **Hardware attestation** (CPU temp, serial number, model, throttling status)
- **Cryptographic signature** (Ed25519) proving the report was not tampered with
- **Integrity hash** (SHA-256) of the canonical JSON

If any value is changed after the run, the signature and integrity hash will
fail verification. This is not blockchain theatre — it is standard
cryptography (NIST FIPS 186-5 compliant Ed25519).

---

## 2. Reproduce on Your Own Hardware

You do not need to trust our numbers. You can generate your own in under
10 minutes.

### What you need

- Raspberry Pi 5 (4 GB or 8 GB RAM)
- Raspberry Pi OS (64-bit, Bookworm)
- Internet connection

### Steps

```bash
# 1. Install Pyvorin Edge SDK
curl -fsSL https://pypi.pyvorin.com/pifiles/install-pyvorin-edge.sh | bash

# 2. Run the proof orchestrator
cd ~/pyvorin-edge
bash pifiles/prove-benchmark.sh

# 3. Review the attested report
cat proof/benchmark_report.md
```

The script will:
1. Read your Pi's hardware serial number and temperature
2. Run all 8 industry vertical benchmarks
3. Cryptographically sign the results
4. Generate a markdown report

**Total time:** ~3–5 minutes.

---

## 3. Verify a Signed Report

If someone sends you a `benchmark_attested.json`, you can verify it
independently:

### 3.1 Verify the cryptographic signature

```bash
python3 -c "
import json, base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

data = json.load(open('benchmark_attested.json'))
pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(data['public_key_b64']))

# Reconstruct the payload (everything except signature and key)
payload = {k: v for k, v in data.items() if k not in ('signature', 'public_key_b64')}
canonical = json.dumps(payload, sort_keys=True, separators=(',', ':')).encode()

# Verify — raises InvalidSignature if tampered
pub.verify(base64.b64decode(data['signature']), canonical)
print('SIGNATURE VALID — report is untampered')
"
```

### 3.2 Verify the integrity hash

```bash
python3 -c "
import json, hashlib

data = json.load(open('benchmark_attested.json'))
expected = data['integrity_hash']

# Recompute hash over everything except the hash itself
payload = {k: v for k, v in data.items() if k != 'integrity_hash'}
canonical = json.dumps(payload, sort_keys=True, separators=(',', ':')).encode()
actual = hashlib.sha256(canonical).hexdigest()

assert actual == expected, f'Hash mismatch: {actual} != {expected}'
print('INTEGRITY HASH VALID')
"
```

### 3.3 Verify hardware identity

Check that the report came from a real Pi 5, not a cloud VM:

```bash
# On the Pi that generated the report:
vcgencmd get_throttled
cat /proc/device-tree/serial-number
cat /proc/device-tree/model
```

Compare the output against the `hardware` section of the JSON.

---

## 4. What "99.99% Reduction" Actually Means

The reduction percentage is computed from real byte counts:

```
raw_bytes    = len(json.dumps(every_reading)) * num_readings
edge_bytes   = len(json.dumps(events + window_summaries))
reduction    = (1 - edge_bytes / raw_bytes) * 100
```

This is not a made-up marketing number. It is the exact difference between:

- **Raw mode**: Sending every sensor reading to the cloud (e.g. 86400 readings/day)
- **Edge mode**: Sending only the events and rolling-window summaries that cross thresholds

If you run the benchmark yourself, you can inspect `raw_bytes` and `edge_bytes`
for each vertical in the JSON output.

---

## 5. What "0.0099 ms Latency" Actually Means

The latency is the per-timestep pipeline evaluation time, measured with
Python's `time.perf_counter()` (nanosecond resolution on Linux):

```python
t0 = time.perf_counter()
for rule in pipeline.rules:
    fired = rule.condition(state)
t1 = time.perf_counter()
latency_ms = (t1 - t0) * 1000.0
```

This measures **only** the rule-evaluation overhead, not the sensor simulation
or JSON serialization. It answers the question: "If a reading arrives, how
long does the edge pipeline take to decide whether to fire an event?"

The p50 is the median across all ~86400 timesteps. On a Pi 5 this is
consistently < 0.01 ms because the pipeline is pure Python with no I/O,
no network calls, and no cloud round-trips.

---

## 6. Why We Use Deterministic Scenario Injection

Each vertical has a custom `ScenarioInjector` that simulates realistic
failure modes (bearing wear, door breach, compressor failure, etc.).
The injection is:

- **Deterministic**: Same seed → same anomalies every run
- **Time-bounded**: Anomalies occur at fixed wall-clock offsets (e.g. hour 4–6)
- **Realistic**: Based on actual IoT failure patterns in each industry

This means:
- You can reproduce the exact same event counts we report
- You can inspect the injection code to see what was simulated
- The scenarios are in `examples/industry_benchmarks/run_all.py`

---

## 7. FAQ

### Q: Could you just fake the numbers in the JSON?
**A:** The signature and integrity hash make tampering detectable. If you
generate the report yourself, you control the key pair and can verify
everything end-to-end.

### Q: Why do the numbers look too good to be true?
**A:** 99.99% reduction is the mathematical consequence of sending 27 events
instead of 1.7 million readings. The math is in the open-source code.
Run it yourself.

### Q: Does this run on anything other than a Pi 5?
**A:** Yes. The benchmark runs on any Linux machine with Python ≥ 3.10.
On x86_64, the ARM64 NEON kernels fall back to scalar C. The latency
numbers will differ but the reduction percentages will be identical.

### Q: What if my Pi is thermally throttled?
**A:** The attestation report includes throttling status. If throttled,
the latency numbers may be higher. Run in a cool environment or add a
heatsink/fan for best results.

### Q: Can I verify this without installing anything?
**A:** Ask us for a live screen-share demo. We will run the benchmark on a
Pi 5 in real time, share the terminal via asciinema, and give you the
signed report to verify independently.

---

## 8. Contact

For audit support, reproduction assistance, or live demos:

- Email: support@pyvorin.com
- Live demo: https://app.pyvorin.com/edge
- Install script: https://pypi.pyvorin.com/pifiles/install-pyvorin-edge.sh
- Proof script: https://pypi.pyvorin.com/pifiles/prove-benchmark.sh

---

*Last updated: 2026-06-01*