audit_trail

Public commitment ledger for predictions produced by EdgeSeeker.

Each file in this repository is part of a chain of evidence that lets any third party verify, without trusting EdgeSeeker, that specific predictions existed at specific times — and were not altered after the fact.

What's in here

anchors/YYYY-MM-DD.json   Daily salted SHA-256 manifest hash of the day's
                          predictions. The GitHub commit timestamp on each file
                          is the external attestation that this hash existed
                          before the day's games started.

models/<model_id>.json    Registration of each model artifact used in
                          production: artifact fingerprint, training window,
                          code commit, sport, prediction type. Binary
                          artifacts are stored privately; the fingerprint
                          (a Merkle-style hash of the artifact's file contents,
                          not a hash of the tarball — see METHODOLOGY.md) lets
                          a contracted customer verify the files.

reports/YYYY-MM-DD.json   Performance and calibration metrics computed from
                          the audit trail joined with game outcomes. Committed
                          alongside the daily anchor (so each carries a GitHub
                          commit timestamp); not yet folded into the salted
                          manifest hash — see METHODOLOGY.md.

verify.py                 Pure-stdlib Python 3 script that lets anyone
                          independently verify any anchor or any individual
                          prediction's content hash.

METHODOLOGY.md            Full protocol description.

sample/                   Synthetic, runnable fixture so anyone can exercise
                          verify.py end-to-end without a contract or any real
                          EdgeSeeker data. See sample/README.md.

Quick verification

Requirements: the core verifier (subcommands anchor and content) is pure Python standard library — Python 3.8+, no third-party packages, no network. The optional bitcoin subcommand has one pinned dependency — see below.

If you are a contracted customer and have been given a set of predictions and the day's salt, you can confirm they match the public anchor:

git clone https://github.com/OffensiveEdge/audit_trail.git
cd audit_trail
python verify.py anchor --date 2026-05-20 \
  --predictions predictions_subset.json --salt salt.hex
# PASS  anchor 2026-05-20: 34 predictions + 0 new model registrations hash to 6071446a… which matches the published anchor

And to confirm an individual prediction's value was not altered:

python verify.py content --predictions predictions_full.json
# PASS  content: all 34 rows' content_hash values match the recomputed canonical hash of their prediction fields

Try it without a contract

If you just want to confirm verify.py works as described — without an NDA, contract, or any real EdgeSeeker data — run it against the synthetic fixture in sample/:

git clone https://github.com/OffensiveEdge/audit_trail.git
cd audit_trail

# Per-row content hashes
python verify.py content --predictions sample/predictions_full.json

# Daily anchor verification
python verify.py anchor \
  --date 2099-01-01 \
  --predictions sample/predictions_subset.json \
  --models sample/models.json \
  --salt sample/salt.hex \
  --repo-root sample/

Both should print PASS. Everything in sample/ is fabricated — no real predictions, features, or model parameters are exposed. See sample/README.md for the full description of what the fixture proves (and doesn't).

Bitcoin attestation subcommand (optional)

Modes A/B above prove predictions → anchor file, dated by that file's GitHub commit timestamp, with zero dependencies and no network. Each anchor also carries an OpenTimestamps proof (anchors/YYYY-MM-DD.json.ots) that stamps it to the Bitcoin blockchain — an independent timestamp that doesn't rely on trusting GitHub's clock. Checking that is an optional, supplemental step via the bitcoin subcommand. The subcommand lazy-loads the ots CLI only when invoked, so Modes A/B keep their pure-stdlib, offline property:

pip install -r requirements-bitcoin.txt              # the `ots` client (opentimestamps-client==0.7.2, pinned)
python verify.py bitcoin                              # all anchors  (needs a local Bitcoin node)
python verify.py bitcoin --date 2026-05-20            # one anchor
python verify.py bitcoin --offline                    # read each proof's on-chain block, no node/network
python verify.py bitcoin --digests                    # just the anchor hashes, no ots

The bitcoin subcommand verifies through the OpenTimestamps reference client — it never reimplements Bitcoin/merkle validation. For each anchor it confirms the .ots proof commits to the exact sha256 of that anchor file (the same file Mode A matched your predictions to), then resolves the Bitcoin attestation to a block + time. The published .ots proofs are upgraded and self-contained — each carries its Bitcoin block attestation directly, so verification never depends on an OpenTimestamps calendar staying online. Trust note: the merkle path is checked locally, but confirming the block is real requires your own Bitcoin Core node (pruned is fine — it keeps every block header, which is all the proof needs). The client has no public-explorer fallback, and that is deliberate: needing your own node is what makes the check fully trustless. Without a node, --offline reads the Bitcoin block each proof already contains. Full runbook: python verify.py bitcoin --help.

Pre-v1.0 anchors were checked by a separate verify_bitcoin.py script that this subcommand replaces. The pre-v1.0 file remains in git history for verifying pre-v1.0 anchors: git checkout <pre-v1.0-commit> -- verify_bitcoin.py.

Integrity guarantees

This ledger is append-only and tamper-evident — enforced, not just asserted:

• Cryptographic — each anchor commits to a salted manifest hash and to verify.py's own hash; every prediction's content_hash binds each field, so altering any input breaks the published hash.
• Append-only CI guard — .github/workflows/integrity.yml runs on every push and fails if any published anchors//models/ file is modified, renamed, or deleted, or any .ots proof is removed.
• Protected history — main blocks force-pushes and branch deletion; history is never rewritten.
• Immutable source — the upstream prediction database is written only by the pipeline and rejects UPDATE/DELETE.

Full policy and change-control rules: INTEGRITY.md.

Full protocol

See METHODOLOGY.md for the full specification: anchor protocol, per-prediction content hash, model registration, performance reports, and disclosed pre-ledger reconstructed data.

License

The verification code (verify.py) is released under the MIT License so any third party can independently audit a claim of EdgeSeeker's. Predictions, salts, and model artifacts are private and provided only under contract.