How to Verify a Bitcoin Timestamp Proof Locally
You’ve got a .ots file sitting in a timestamps branch, and a lawyer, an auditor, or your own skeptical brain wants to know: does this actually prove anything, or is it just a file a vendor handed me?
That question is the whole point of cryptographic timestamping. A proof that only the issuer can validate isn’t a proof — it’s a promise. This article walks through how to verify a Bitcoin timestamp proof locally, step by step, using Timestamp GIT’s built-in verification tools. No command-line tools required, no trust in our servers required, and — if you want to go further — no dependence on Timestamp GIT existing at all.
Why Local Verification Matters
Most software attestations are trust-me-bro documents. A vendor signs a PDF saying “yes, this commit existed on this date.” If the vendor folds, gets acquired, or quietly changes its signing keys, your evidence gets weaker. The proof was never really yours.
Bitcoin-anchored proofs work differently. Timestamp GIT embeds commit hashes into the Bitcoin blockchain via the OpenTimestamps protocol, using public OTS calendars. The verification path uses only SHA-256 and Bitcoin block data — no proprietary cryptography, no secret sauce. That means:
- The proof outlives the vendor. Even if Timestamp GIT disappeared tomorrow, the
.otsreceipt and the Bitcoin block it references remain verifiable by anyone. - Verification is local by default. Timestamp GIT’s web verifier runs the entire computation in your browser. Nobody sees what you verify, and no server response is required to reach a conclusion.
- Compliance teams accept it. In a legal audit, “our internal logs say so” is often dismissed as self-serving. A Merkle path that terminates in a specific Bitcoin block header is a different category of evidence.
In short: the whole value of proof-of-existence collapses if verification requires trusting the issuer. It doesn’t here.
If you want the conceptual background on why prior art needs cryptographic anchoring, that’s covered in What Is Cryptographic Prior Art? A Guide for Software Teams. This article is about the mechanical act of verifying.
What a Timestamp GIT Proof Looks Like
When you install the GitHub App and connect a repository, every commit lands in a nightly batch. Here’s what you end up with:
- A
.otsreceipt file. A compact cryptographic proof that a given Git commit hash — or rather, the Merkle root covering a day’s batch of hashes — existed at a specific point in time. - A manifest
.txtfile per repository. The list of commit hashes batched for that day. - A dedicated timestamps branch or shadow repository. Proofs are pushed back into your own infrastructure, either inside the source repo or in a separate target repo.
Each proof corresponds to a daily batch. The pipeline groups all pending commit hashes, builds a Merkle tree natively, creates OpenTimestamps proofs against public OTS calendars, and anchors the Merkle root into a Bitcoin transaction.
The .ots file is self-contained for verification purposes: it contains the Merkle path from your commit hash up to the anchored root, plus a reference to the Bitcoin block header that contains the anchor. You don’t need Timestamp GIT’s database to check it.
One timing note that trips people up: Bitcoin confirmation takes several hours — typically around 3. So the proof-writing step lands a few hours after the midnight cron worker runs. A fresh commit isn’t instantly verifiable. See Interpreting Results and Edge Cases below.
Step-by-Step: Verifying Your Proof Locally
Step 1: Get the .ots file
It’s already in your repo. Look in the timestamps branch, or in the shadow repository if you configured proofs to live separately from source. You can also pull it from the Timestamp GIT dashboard via your repositories list.
Step 2: Use the browser-based verifier
Navigate to the verification page for your repository and date:
https://timestampgit.dev/verification/{user}/{repo}/{date}
This is a step-by-step, multi-level Merkle chain verification. Every hash computation happens locally in your browser — the page doesn’t ship your data anywhere, and nobody sees what you verify. You’ll see the chain unwind from your commit hash, through intermediate Merkle nodes, up to the root and the Bitcoin block reference.
This is the path most developers and compliance reviewers should take. No CLI tools required, no Bitcoin node required.
Step 3 (optional): Verify with standard OpenTimestamps tooling
The .ots format is open. If your process demands a fully independent toolchain — or you simply prefer it — you can take the receipt file and check it against the Bitcoin blockchain using standard OpenTimestamps verification tools and a Bitcoin node or lightweight client. That’s the “hard way,” and it’s completely optional. The proof is vendor-independent by design: only SHA-256 and Bitcoin block data are involved.
Step 4: Confirm the result
A successful check gives you two concrete outputs:
- The Bitcoin block height where your Merkle root was anchored.
- The block timestamp, which establishes the upper bound on when your commit hash could have existed.
That’s your evidence: not “Timestamp GIT says so,” but “this hash is provably contained in a Merkle tree whose root is committed in Bitcoin block N.”
Using Timestamp GIT’s Built-In Verification Tools
Beyond the per-date verifier, there are three tools worth knowing.
The public status page
https://timestampgit.dev/status/{user}/{repo}
This is a public dashboard showing proof longevity, your earliest anchor date, daily regularity, the Bitcoin block and transaction data behind each anchor, and a calendar heatmap of coverage. If you’re doing due diligence on a repo — yours or someone else’s — start here. It also exposes downloadable audit CSV and a PDF certificate.
The verification page
Covered above, but worth restating as the primary tool:
https://timestampgit.dev/verification/{user}/{repo}/{date}
Merkle chain verification, in-browser, for one specific day’s timestamp.
Badges and certificates
Embeddable badges are available for your README to publicly display verification status. Anyone can click the link attached to the badge and verify the timestamp through the website. For audit packets, download the PDF certificate for a specific date.
If your repo is private, note that private repos append an encrypted HMAC to the URL — the HMAC is specific to the server instance, so only authorized users can see that repo’s status. Your verification workflow is unchanged; the URL is just scoped.
Interpreting Results and Edge Cases
What a successful verification actually means
It proves the commit hash existed at or before the Bitcoin block’s timestamp. Not “exactly at,” and not “the code was written then” — it proves the hash was in existence no later than that block. For prior-art purposes, that’s exactly the assertion you need: you had this artifact on or before date X.
Pending proofs
If you check a repo the morning after a commit and the proof looks incomplete, that’s expected. The nightly cron worker batches hashes, builds the tree, and anchors it; Bitcoin confirmation then takes a few hours (normally around 3). Once confirmed, the timestamp is immutable. Wait, then re-check — nothing is broken.
The zero-knowledge boundary
Verification operates on commit hashes, never on your source code. Timestamp GIT never sees, copies, or stores your actual source. The proof confirms a hash existed; it reveals nothing about what was in the code. That’s deliberate, and it’s why the same verification flow works for closed-source and trade-secret repositories.
When things go wrong
- Missing
.otsfile — retrieve it from the timestamps branch, the shadow repository, or your dashboard. - Corrupted receipt — re-download from the repository or dashboard; the anchored data on the Bitcoin side is unaffected, so a fresh copy of the receipt restores verification.
Teams that want even less exposure
Timestamp GIT’s managed GitHub App is the zero-setup path — Read-only access to the source repo, Read-write to the target repo, and proofs land automatically. For teams that don’t want the service reading even a commit hash, Enterprise ZK Mode takes a different route: a 12-line GitHub Action runs on your infrastructure and pushes only the commit hash to the Timestamp GIT API. Your source never leaves your environment.
Automating Verification for Compliance
Manual checks are fine for a one-off audit. If you’re running continuous compliance, wire it into CI or your internal tooling.
Fetch verification data via the API
The full Merkle chain for a specific day:
curl -s "https://timestampgit.dev/api/verify/acme-corp/payments-api/2026-09-14" \
-o verify-2026-09-14.json
Public status endpoints (no auth needed):
# Last anchored Bitcoin block info
curl -s "https://timestampgit.dev/api/statusLast/acme-corp/payments-api"
# Total stamped commit count
curl -s "https://timestampgit.dev/api/statusCount/acme-corp/payments-api"
# Combined summary, useful for Shields.io badges
curl -s "https://timestampgit.dev/api/statusSummary/acme-corp/payments-api"
Pull audit ledgers and certificates
# Full audit ledger as CSV
curl -s "https://timestampgit.dev/api/audit/acme-corp/payments-api" -o audit.csv
# PDF certificate for a single date
curl -s "https://timestampgit.dev/api/report/acme-corp/payments-api/2026-09-14" \
-o certificate-2026-09-14.pdf
A minimal CI guardrail — fail the build if the most recent anchor is stale — looks like this:
#!/usr/bin/env bash
set -euo pipefail
REPO_PATH="acme-corp/payments-api"
LAST=$(curl -s "https://timestampgit.dev/api/statusLast/${REPO_PATH}")
BLOCK=$(echo "$LAST" | python3 -c "import sys,json; print(json.load(sys.stdin).get('blockHeight',''))")
if [ -z "$BLOCK" ]; then
echo "No anchored Bitcoin block found for ${REPO_PATH}. Check nightly anchoring."
exit 1
fi
echo "Latest anchor confirmed in Bitcoin block ${BLOCK}"
Air-gapped verification with Docker
For maximum security and air-gapped environments, Timestamp GIT is available 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
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
The application is available at http://localhost:8080 after startup. On first launch, a setup wizard guides you through connecting your GitHub App and configuring your instance. A time-limited demo license can be requested from the Docker License page with your name, company, email, and optional phone number, and the demo license file is downloadable once issued.
FAQ
Do I need to run any command-line tools to verify a Timestamp GIT proof? No. Timestamp GIT provides a web-based verifier that performs all computations locally in your browser. You can also use standard OpenTimestamps tools if you prefer, but it’s not required.
How long does it take for a proof to become verifiable? After the nightly anchoring, it takes a few hours (typically around 3) for the Bitcoin transaction to be confirmed. Once confirmed, the proof is immediately verifiable.
Can I verify a proof without trusting Timestamp GIT?
Yes. The .ots file contains all necessary cryptographic data, and you can verify it against the Bitcoin blockchain using open-source tools. Timestamp GIT’s verifier also runs locally, so no trust in our servers is needed.
What if I lose the .ots file?
You can retrieve it from your repository’s timestamps branch or shadow repository. If you’re a Timestamp GIT user, you can also download it from your dashboard.
Conclusion
Local verification is the difference between “a company told me so” and “I checked it myself against the Bitcoin blockchain.” With Timestamp GIT, the checking part takes four steps and zero CLI tooling: grab the .ots file, open the verification page, read the block height, done. The heavy lifting — commit detection, nightly batching, Merkle tree construction, OTS calendar submission, Bitcoin anchoring, and pushing proofs back into your repo — happens automatically once the GitHub App is installed.
Start at timestampgit.dev, install the GitHub App on one repository, and verify your first proof tomorrow. For private repos and continuous compliance workflows, the Pro Agency and Enterprise ZK plans cover the rest.
Related posts
- GitHub App That Timestamps Commits Automatically
- How Freelancers Can Prove Code Ownership Before a Dispute
- What Is Cryptographic Prior Art? A Guide for Software Teams