# Git OpenTimestamp Hook

Automatically generate [OpenTimestamp](https://opentimestamps.org/) proofs for git commits with full Bitcoin attestation.

## ⚠️ Requirements

**Required:** `opentimestamps-client` (ots CLI)

```bash
pipx install opentimestamps-client
```

> **Note:** The Node.js `@opentimestamps/ots` package is **not supported** - it only creates local proofs without calendar submission or Bitcoin attestation. For tamper-evident timestamps, you must use the Python `opentimestamps-client`.

## Quick Install

```bash
# Clone this repository
git clone <repository-url>
cd git-ots-hook

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

# Commit the proofs
cd /path/to/your/repo
git add .ots/
git commit -m "Add OpenTimestamp proofs"
```

That's it! Every commit will now be timestamped and anchored to Bitcoin.

## Manual Installation

```bash
# Copy hooks
cp hooks/post-commit .git/hooks/post-commit
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit

# Setup .gitignore
echo ".ots/.attestation-cache" >> .gitignore
```

## What You Get

- **Automatic timestamping** - Every commit gets a cryptographic proof
- **Bitcoin attestation** - Proofs anchored to Bitcoin blockchain (~10 min)
- **Full history** - Backfill hook upgrades all historical commits
- **Smart caching** - Minimal network overhead after initial setup
- **Tamper-evident** - Anyone can verify your commit history

## Generated Files

```
repo/
├── .ots/
│   ├── <commit-hash>.ots   # Individual proof (commit this)
│   ├── proof.ots           # Latest proof (commit this)
│   ├── prev-commit.txt     # Chain link (commit this)
│   ├── commit-chain.txt    # Full chain (commit this)
│   └── .attestation-cache  # Local cache (ignore this)
└── ...
```

## Verification

**Check a proof:**
```bash
ots info .ots/<commit-hash>.ots
```

**Verify attestation:**
```bash
ots verify .ots/<commit-hash>.ots
```

**Upgrade pending proofs:**
```bash
ots upgrade .ots/<commit-hash>.ots
```

## How It Works

1. You make a git commit
2. Post-commit hook extracts commit hash
3. Hash submitted to 4+ remote calendar servers
4. Calendars aggregate and anchor to Bitcoin
5. After ~10 min: proof becomes Bitcoin-attested
6. Pre-commit hook upgrades old proofs before new commits

## Performance

- **First backfill:** 30-60s (full history scan)
- **Normal commits:** 10-15s (cached, minimal network)
- **Attestation:** ~10 min (Bitcoin block time)

## Uninstall

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

## Links

- [OpenTimestamp](https://opentimestamps.org/)
- [opentimestamps-client](https://github.com/opentimestamps/opentimestamps-client)
- [Bitcoin anchoring explained](https://petertodd.org/2016/opentimestamps-announcement)

## License

MIT