README.md

metadata

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

pip install -r requirements.txt
python app.py


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