Timestamp GIT

← All posts

2026-11-19

How to Verify a Bitcoin Timestamp Proof for Your Code

How to Verify a Bitcoin Timestamp Proof for Your Code
timestamp git blockchain proof

How to Verify a Bitcoin Timestamp Proof for Your Code

A timestamp proof you can’t check yourself is just a vendor promise with better branding. Sooner or later someone — a lawyer in a patent dispute, an auditor during due diligence, or a CTO who suspects your “independent implementation” wasn’t independent — will ask you to show that a given commit hash existed on a given date. That moment is the verification step, and it’s the one most teams never rehearse.

The good news: with Timestamp GIT, verification isn’t a research project. The GitHub App anchors your commit hashes nightly, and checking a proof takes one click, one URL, or one curl. This article walks through the exact verification paths, what the results mean, and where the edge cases hide.

Why Verification Matters: From Trust to Proof

There’s a difference between a claim and evidence:

  • A claim is “we wrote this in March.” It lives in a database you control and can be edited.
  • Evidence is “this specific commit hash was included in a Merkle tree whose root is embedded in Bitcoin block N.” Anyone can recompute it.

For compliance, audits, and litigation, evidence has one extra requirement: it must be repeatable and independent of the vendor. If your proof only verifies while a specific company’s servers are up, it’s not really proof — it’s a subscription.

Timestamp GIT’s design accounts for this. The .ots receipt plus public Bitcoin block data is the entire proof. There’s no proprietary component in the verification path, and nothing to install on your developers’ machines. This article stays focused on the verification step; if you’re still deciding whether to timestamp at all, the strategic case is in our founder’s guide to prior art.

What a Bitcoin Timestamp Proof Actually Contains

A proof for a single day consists of two artifacts, stored in a dedicated timestamps branch or a shadow repository so they version alongside your code:

  1. A manifest file (.txt) listing the commit hashes collected for that repository on that day.
  2. An .ots receipt file containing the Merkle path that links your hash up to the Merkle root anchored in Bitcoin.

The chain looks like this:

commit hash ─┐
commit hash ─┼─ Merkle tree ─ Merkle root ─ Bitcoin transaction ─ block
commit hash ─┘        │
                 .ots receipt (Merkle path from your hash to the root)

Two properties matter when you verify:

  • The manifest proves which hashes were included.
  • The .ots receipt proves when the Merkle root entered the chain.

Because the anchoring uses the OpenTimestamps protocol and nothing else proprietary, the proof survives us: it’s SHA-256 plus Bitcoin block data, verifiable offline, forever.

Step-by-Step: Verifying a Timestamp Proof With Timestamp GIT

1. Start With the Badge in Your README

Every monitored repository can display a Shields.io verification badge. It’s a live pointer, not a static image: it links to the public status page for that repository. You generate the embed snippet on the repository-connected page (https://timestampgit.dev/connected/{user}/{repo}), which shows a live preview before you paste it.

<!-- Paste the snippet generated at /connected/{user}/{repo} -->
[![Timestamp GIT status](BADGE_URL_FROM_CONNECTED_PAGE)](https://timestampgit.dev/status/OWNER/REPO)

When a reviewer clicks the badge, they land on the evidence — not a marketing page.

2. Read the Repository Status Page

Open:

https://timestampgit.dev/status/{user}/{repo}

This public dashboard gives you the audit-friendly summary:

  • Proof longevity — how far back your anchoring history goes.
  • Earliest anchor date — the first day your hashes hit Bitcoin.
  • Daily regularity — proof that the nightly job actually ran, day after day.
  • Bitcoin block and transaction data for the anchors.
  • A calendar heatmap so gaps are visually obvious.
  • Downloads: the audit CSV and a PDF certificate.

For an auditor, the heatmap plus the CSV is usually enough for a first pass. Missing squares are the thing to investigate.

3. Verify a Specific Day Locally

For a date-level proof, open:

https://timestampgit.dev/verification/{user}/{repo}/{date}

This page walks the Merkle chain step by step and performs the computation locally in your browser. Nothing about what you verify is transmitted — the zero-knowledge property applies to verification too, not just to ingestion.

That matters more than it sounds. A compliance reviewer can check a proof involving sensitive internal repositories without handing the vendor any additional information.

4. Pull the Merkle Chain via the API

If you’d rather verify programmatically (or store the evidence in your own compliance system), the API returns the full Merkle chain data for a specific day:

curl -s "https://timestampgit.dev/api/verify/OWNER/REPO/2026-11-18" | jq

You can also fetch the last anchored block and the running commit count:

curl -s "https://timestampgit.dev/api/statusLast/OWNER/REPO" | jq
curl -s "https://timestampgit.dev/api/statusCount/OWNER/REPO" | jq

No CLI tools, no protocol commands, no wallet software. The heavy lifting — commit detection via the GitHub App webhook, batching, Merkle tree construction, and Bitcoin anchoring — already happened overnight.

Reading the Results — and the Edge Cases

A valid proof means something narrow and strong: this commit hash existed at or before this Bitcoin block’s timestamp. It does not tell you the code is good, that you wrote every line, or who typed it. Authorship beyond the hash is a separate question — our breakdown of whether Git commit timestamps hold up as proof covers that distinction.

Other things to keep in mind:

  • Block timestamp variance. Bitcoin block timestamps can drift slightly from wall-clock time. The proof stays cryptographically strong regardless, because the block itself is immutable — nobody can re-mine history to move your anchor.
  • Missing proof for a date. Proofs are written a few hours after midnight: the cron worker batches hashes, builds the Merkle tree, submits it to public OTS calendars, and then waits for Bitcoin confirmation — normally around three hours. A proof for a day may simply not be written yet. If it’s older than that, check whether the repository was actually monitored during that window.
  • Private repositories. Status URLs for private repos carry an encrypted HMAC, and only holders of that URL can see the status. Verification itself still happens locally in the browser.
  • Self-hosted instances. Each instance generates its own HMAC. If you migrate a badge from a SaaS instance to your own Docker deployment, regenerate the badge link — an HMAC from one instance won’t validate on another.

Verifying Without the SaaS: Docker Self-Hosted and Offline Checks

For air-gapped or high-paranoia environments, Timestamp GIT ships as a Docker image. A quick-start Docker Compose setup looks like this:

services:
  timestampgit:
    image: rue1401/timestampgit:prod
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

  valkey:
    image: valkey/valkey:8
    restart: unless-stopped

Then:

docker compose pull
docker compose up -d
docker compose logs -f timestampgit

The app is available at http://localhost:8080, and a setup wizard on first launch walks you through connecting your GitHub App and configuring the instance. A time-limited demo license is available from the Docker License page if you want to evaluate before committing.

Self-hosting doesn’t change the verification math. The .ots files and Bitcoin block data are the same artifacts, and they verify offline. You can go fully manual and feed the .ots file to standard OpenTimestamps verification tools against a local Bitcoin node — that’s the hard way, and it works precisely because the proof is vendor-independent. The product’s viewer and API simply make it a one-click affair instead of a weekend project.

Automating Verification for Compliance

If verification is a checkbox in a quarterly review, automate it:

  • Export the ledger. GET /api/audit/{user}/{repo} returns the full audit ledger as CSV — the artifact your auditor actually wants in the file room.
  • Generate per-day certificates. GET /api/report/{user}/{repo}/{date} produces a PDF certificate for a specific date, useful when a single proof needs to be attached to a contract or dispute filing.
  • Poll for freshness. A short cron job on your side catches the failure mode that matters: anchoring silently stopping.
#!/usr/bin/env bash
set -euo pipefail

REPOS=("acme/api" "acme/web" "acme/infra")

for repo in "${REPOS[@]}"; do
  printf '%-14s ' "$repo"
  curl -s "https://timestampgit.dev/api/statusLast/${repo}" | jq -c '.'
done

Run it daily; if the last anchored block stops advancing, you know before an auditor does.

  • Display status publicly. Embed the Shields.io badge so downstream users and clients can see verification status without asking you for anything.

For teams that want maximum separation, Enterprise ZK plans ship a short GitHub Action that runs inside your own CI and transmits nothing but commit hashes — the anchoring and verification model stays the same, and verification still happens locally.

FAQ

Do I need to run any OpenTimestamps commands to verify a proof?

No. Timestamp GIT provides a web-based verification page and REST API that handle the entire check. You can also download the .ots file and use standard verification tools if you prefer, but it isn’t required.

How long does it take for a proof to become verifiable?

Proofs are anchored nightly and confirmed in the Bitcoin blockchain after a few hours — typically around three hours. A commit made today will have a verifiable proof by the next day.

Can I verify a proof for a private repository?

Yes, but private repository status pages require an encrypted HMAC appended to the URL. Authorized users can access them, and the verification itself still happens locally in your browser.

What if Timestamp GIT disappears? Can I still verify?

Yes. The proof is vendor-independent: it relies only on SHA-256 and Bitcoin block data. You can verify the .ots file offline with standard OpenTimestamps tools even if our service is gone.

Conclusion

Verification is where timestamping stops being a nice idea and becomes defensible evidence. The workflow is short: click the badge, read the status page, open the day-level verification view, or hit /api/verify/{user}/{repo}/{date} and check the Merkle chain yourself. Every path ends in the same place — a commit hash that existed before a specific Bitcoin block, provable forever, without trusting anyone’s database.

If you haven’t started, the setup is the boring part: install the GitHub App on a repository and let the nightly job run. You’ll have your first verifiable proof by tomorrow. Head to timestampgit.dev to connect your first repo.

Related posts

EU label: AI-generated content