# How Adology's Prediction Receipts Work — 2-Minute Walkthrough

*For journalists, analysts, and anyone who wants to verify independently.*

---

## The 5-Step Chain

### Step 1: Every prediction is written down before the outcome

When Adology locks a forecast on a brand's post, the system immediately appends a record
to an append-only file (`data/forward_slips.jsonl`) containing:

- The brand handle and platform
- The predicted final engagement count
- The model version that made the prediction
- The exact UTC timestamp when the lock happened

The post is still young — typically 30 minutes to 24 hours old. The final engagement
count is unknowable at the time of writing. This is what makes it a forward prediction
rather than a backtest.

### Step 2: The record is fingerprinted with a SHA-256 hash

Immediately after writing, the system computes a [SHA-256 hash](https://en.wikipedia.org/wiki/SHA-2)
over the record's payload and stores it as `record_hash`. SHA-256 is a standard
cryptographic one-way function: change even one digit of `predicted_final` and the
hash changes completely. The `slip_hash` shown on the public leaderboard is the first
16 hex characters of a separate SHA-256 over just the four core fields
(`post_id`, `predicted_final`, `t_predict`, `model_version`).

### Step 3: Each record commits to the previous one — a chain

Every new record stores the previous record's `record_hash` as its own `prev_hash`,
then hashes both together into its `record_hash`. This means you cannot silently edit,
delete, or insert any record without breaking every hash that follows it. The first
record in the chain uses 64 zeros as its `prev_hash` (the "genesis sentinel").

### Step 4: The file is anchored to the Bitcoin blockchain

After each batch of resolutions, the system calls
[OpenTimestamps](https://opentimestamps.org/) — an open protocol that embeds a hash
of the entire ledger file into a Bitcoin transaction. Once confirmed, the blockchain
provides an independent, third-party proof that the file existed with its exact contents
before a given Bitcoin block. Bitcoin is not controlled by Adology or any single party;
its history cannot be rewritten.

The `.ots` proof file lives alongside the ledger and can be verified by anyone with the
`ots` CLI client:

```bash
ots verify data/forward_slips.jsonl.ots
```

### Step 5: Editing history breaks the math

If anyone altered an old prediction — changing a miss to a hit, adjusting a number,
deleting a record — the SHA-256 chain would break at that point and every record after
it would fail verification. The hash chain makes silent retroactive edits computationally
infeasible.

---

## How to Verify Yourself

### In the browser (no installation required)

Open [`public_leaderboard/verify/index.html`](index.html) (or the live URL). Paste any
slip JSON record from the leaderboard — or pick one of the three embedded examples —
and click **Verify**. The page uses the browser's built-in
[Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
to recompute SHA-256, with no server call and no external dependencies. It works offline.

Try the cheat test: change any digit in the pre-filled record and click **Test edit**.
The hash check turns red immediately.

### On the command line

```bash
# Verify the full hash chain of the live ledger
python3 engine/forward_slips.py verify
```

Expected output (clean chain):

```
hash-chain OK — N records intact (tamper-evident)
OTS: stamped (XXXX bytes) | client available: True
```

```bash
# Run the full self-test suite (uses a temp ledger, never touches prod data)
python3 engine/forward_slips.py selftest
```

```bash
# Verify the OTS proof directly with the OpenTimestamps client
# Install: pip install opentimestamps-client
ots verify data/forward_slips.jsonl.ots
```

---

## What OpenTimestamps Anchoring Means

OpenTimestamps is an open-source protocol by [Peter Todd](https://petertodd.org/).
It works by:

1. Computing a SHA-256 of your file
2. Submitting that hash to a public calendar server, which aggregates thousands of hashes
3. Embedding the aggregated root hash into a Bitcoin transaction
4. Once the Bitcoin block is mined, no one — not Adology, not the calendar server,
   not anyone — can alter the blockchain record

The `.ots` proof file is a compact binary that proves your file's hash was included in
a specific Bitcoin block. Anyone can verify it independently. The calendar servers
(opentimestamps.org, Alice, Bob) are operated by different parties; you don't need to
trust any one of them because Bitcoin is the final arbiter.

**Cite-safe language:** *"Each prediction record is SHA-256 hashed and hash-chained
at the time of writing. The ledger is periodically anchored to the Bitcoin blockchain
via OpenTimestamps, providing third-party proof that the predictions existed before
their outcomes."*

---

## What This Does NOT Prove

- **That the predictions were good.** Hash verification only proves the numbers weren't
  changed after the fact. Accuracy is the scoreboard's job. See
  [`public_leaderboard/index.html`](../index.html) for the full track record — all misses
  are shown and cannot be deleted.
- **That the timestamp is accurate to the second.** Machine clocks can drift. The
  OpenTimestamps anchor provides the strongest independent timestamp (Bitcoin block time),
  but anchoring happens in batches, not per prediction.
- **That the underlying data is correct.** Engagement counts come from the
  Instagram/TikTok APIs via an Apify scraper. The system locks what it reads.

---

*Adology · [`public_leaderboard/index.html`](../index.html)*