Otto b4e2eb3c12 Remove Node.js hooks, require ots CLI only

- Delete hooks/post-commit-node (local proofs only, no attestation)
- Delete hooks/pre-commit-node (no upgrade support)
- Update hooks/install.sh to require ots CLI (no fallback)
- Update documentation with clear ots CLI requirement
- Add prominent warnings about Node.js limitations

Rationale: The @opentimestamps/ots Node.js package only creates
local proofs without calendar submission or Bitcoin attestation.
For tamper-evident timestamps, ots CLI is the only complete
implementation. No partial/fallback implementations.

2026-03-08 00:50:32 +01:00

4.1 KiB

Raw Blame History

name	description
git-ots-hook	Install and manage OpenTimestamp git hooks that generate cryptographic proof for every commit. Requires opentimestamps-client (ots CLI) for full Bitcoin attestation.

Git OpenTimestamp Hook

Automatically generates OpenTimestamp proofs for git commits via git hooks.

⚠️ Prerequisites (Required)

You must have ots CLI installed:

# Recommended (isolated install)
pipx install opentimestamps-client

# Or with pip
pip install opentimestamps-client

# Or from source
git clone https://github.com/opentimestamps/opentimestamps-client
cd opentimestamps-client && pip install .

Verify installation:

ots --version
# v0.7.2 or later

Why ots CLI is required: The Node.js @opentimestamps/ots package only creates local proofs without calendar submission or Bitcoin attestation. For tamper-evident timestamps anchored to Bitcoin, the Python opentimestamps-client is the only complete implementation.

Quick Start

# Install both hooks (requires ots CLI)
./hooks/install.sh /path/to/repo

# Or from repo root
./hooks/install.sh .

The installer will:

Verify ots CLI is installed
Install post-commit and pre-commit hooks
Setup .gitignore (excludes cache file)

What It Does

Post-commit hook: Generates .ots/<commit-hash>.ots for each new commit
Pre-commit backfill: Upgrades historical proofs to Bitcoin-attested status
Creates .ots/proof.ots (latest proof reference)
Stores commit chain in .ots/commit-chain.txt
Smart caching: Skips calendar calls for recently checked proofs
Submits to 4+ remote calendar servers for Bitcoin anchoring

Generated Files

repo/
├── .ots/
│   ├── <commit-hash>.ots   # Individual proof per commit
│   ├── proof.ots           # Latest commit proof (reference)
│   ├── prev-commit.txt     # Previous commit hash (chaining)
│   ├── commit-chain.txt    # Full commit chain mapping
│   └── .attestation-cache  # Local cache (gitignore this)
└── ...

Manual Installation

If you prefer manual setup:

cp hooks/post-commit-ots .git/hooks/post-commit
cp hooks/pre-commit-ots .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit

Add to .gitignore:

.ots/.attestation-cache

Manual Usage

Check attestation status:

ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
# 0 = attested, >0 = pending

Verify a proof:

ots verify .ots/<commit-hash>.ots

Upgrade pending proofs:

ots upgrade .ots/<commit-hash>.ots

Notes

Versioning Proofs

git add .ots/
git commit -m "Add OpenTimestamp proofs"

Commit these:

*.ots - Individual proof per commit
proof.ots - Latest proof reference
commit-chain.txt - Full chain
prev-commit.txt - Previous commit link

Ignore these:

.attestation-cache - Local performance cache

Performance

First backfill: ~30-60s (scans history, contacts calendars)
Subsequent commits: ~10-15s (cached status skips redundant calls)
Cache: 1-hour validity, re-checks pending proofs after 10 min
Attestation time: ~10 min (Bitcoin block confirmation)

How It Works

Commit created → Post-commit hook runs
Hash generated → SHA256 of commit hash
Submitted to calendars → 4+ remote servers receive hash
Bitcoin anchoring → Calendars batch and anchor to Bitcoin
Attestation → ots upgrade downloads Bitcoin proof
Verification → Anyone can verify against Bitcoin blockchain

Calendar Servers

Default calendars used:

https://a.pool.opentimestamps.org
https://b.pool.opentimestamps.org
https://a.pool.eternitywall.com
https://btc.calendar.catallaxy.com

Uninstall

rm .git/hooks/post-commit .git/hooks/pre-commit

4.1 KiB Raw Blame History