---
title: ReplayProof  Agent POV  Verified Replay
emoji: 🌍
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false
license: other
short_description: Play it. Prove it. Replay it.
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/PnZZVpPI2Q2FyyiwWyd7M.png
---
# ReplayProof__Agent_POV__Verified_Replay
**Play it. Prove it. Replay it.**

ReplayProof is a lightweight, game-like **Agent POV** simulation that records every step as a **signed, hash-chained receipt**.  
You can export a run as a ZIP bundle (receipts + optional GIF), then **verify** the run’s integrity and **replay** it deterministically on another machine.

This Space is intentionally simple and fast: CPU-friendly, no model downloads, no GPU needed.

---

## What this Space does

### ✅ Play
- Run a deterministic gridworld with an autonomous agent
- See both:
  - **World View** (top-down)
  - **Agent POV** (partial observability)

### ✅ Prove
- Every step is recorded as a receipt:
  - Canonical JSON
  - Hash chain linking each event to the previous
  - Ed25519 signatures

### ✅ Replay
- Upload a receipt bundle ZIP
- The Space re-simulates the run and checks that state hashes match
- Optionally exports a replay GIF

---

## Why this exists
Most “AI demos” are not reproducible. People share settings and results, but there’s no way to prove:
- what actually ran,
- whether it was altered,
- whether it can be reproduced.

ReplayProof turns **trust** into **verification**.

---

## Files in this repo
- `app.py` — Gradio UI (Play / Receipts / Verify / Replay)
- `replayproof_sim.py` — deterministic sim + POV + rendering
- `replayproof_receipts.py` — receipts, signing, bundle export, verify, replay
- `replayproof_media.py` — GIF export + optional watermark
- `requirements.txt`

---

## How to use (in the Space)

### 1) New Session
Pick seed + settings → click **New Session**.

### 2) Run
Use:
- **Step**
- **Run 50**
- **Run 250**

### 3) Export
In **Receipts** tab:
- toggle **Include GIF in bundle**
- toggle **Watermark final hash**
- click **Download Receipt Bundle (ZIP)**

You’ll get a ZIP containing:
- `events.jsonl`
- `root.json`
- optional `run_<session>.gif`

### 4) Verify
In **Verify** tab:
- upload the ZIP
- click **Verify Bundle**
- you’ll get a JSON report with checks + any errors

### 5) Replay
In **Replay** tab:
- upload the ZIP
- click **Replay From Bundle**
- you’ll see the reproduced end-state and (optionally) a replay GIF

---

## Receipt bundle format

### `events.jsonl`
One JSON object per step (one per line), including:
- `spec`: `replayproof-event-v0`
- `session_id`
- `ts` (UTC ISO)
- `step`
- `action`
- `seed`
- `cfg_sha256`
- `obs_sha256` (hash of what the agent “sees”)
- `state_sha256` (hash of full sim state)
- `prev_event_sha256` (hash-chain pointer)
- `event_sha256` (hash of canonical event body)
- `sig` (Ed25519 signature over `event_sha256`)
- `pubkey_id`

### `root.json`
A manifest for the run:
- `spec`: `replayproof-root-v0`
- session metadata + config
- public key (base64)
- first/final event hashes
- `final_state_sha256`
- optional `media_sha256`
- `root_sha256` + `root_sig`

---

## Determinism and verification notes
- The simulation is deterministic given:
  - seed
  - config
  - the exact sim logic
- The strongest check is **replay_state_hashes_ok**, which re-simulates and compares `state_sha256` at each step.
- Media hashes (GIF/MP4) can be environment-sensitive (encoding differences), so media verification is optional and separate from state verification.

---

## Security model (plain English)
ReplayProof proves:
- the run has not been tampered with (hash chain)
- the receipts were produced by the same signing key (Ed25519 signatures)
- the run can be reproduced to the same final state hash (replay verification)

It does NOT claim:
- the code itself is “trusted” (you can still inspect it)
- the agent is “honest” beyond what receipts prove

---

## Roadmap (sensible upgrades)
- Player-controlled mode (WASD) where actions are enforced from receipts
- Share links / seed leaderboard (“challenge this run”)
- MP4 export
- Multi-agent mode + dispute system (“show receipts” gameplay)
- Visual diff on verification failure (where exactly it diverged)

---

## Local run
```bash
pip install -r requirements.txt
python app.py


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference