b4e2eb3c12
- 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.
89 lines
2.3 KiB
Markdown
89 lines
2.3 KiB
Markdown
# AI Agent Instructions
|
|
|
|
Quick reference for AI agents installing OpenTimestamp hooks.
|
|
|
|
## ⚠️ Hard Requirement
|
|
|
|
**`ots` CLI must be installed.** No fallback available.
|
|
|
|
```bash
|
|
pipx install opentimestamps-client
|
|
```
|
|
|
|
The Node.js `@opentimestamps/ots` package is **not a valid alternative** - it only creates local proofs without calendar submission or Bitcoin attestation.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# 1. Verify/install prerequisites
|
|
if ! command -v ots &> /dev/null; then
|
|
pipx install opentimestamps-client
|
|
fi
|
|
|
|
# 2. Install hooks
|
|
./hooks/install.sh .
|
|
|
|
# 3. Commit proofs
|
|
git add .ots/ .gitignore
|
|
git commit -m "Add OpenTimestamp proofs for commit history"
|
|
```
|
|
|
|
## Manual Installation
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
**.gitignore:**
|
|
```
|
|
.ots/.attestation-cache
|
|
```
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose | Version? |
|
|
|------|---------|----------|
|
|
| `hooks/post-commit-ots` | Post-commit hook | Yes |
|
|
| `hooks/pre-commit-ots` | Backfill hook | Yes |
|
|
| `hooks/install.sh` | Installer (checks ots) | Yes |
|
|
| `.ots/*.ots` | Individual proofs | Yes |
|
|
| `.ots/proof.ots` | Latest proof reference | Yes |
|
|
| `.ots/commit-chain.txt` | Commit chain | Yes |
|
|
| `.ots/.attestation-cache` | Local cache | No |
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# Check attestation status
|
|
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
|
|
# 0 = attested, >0 = pending
|
|
|
|
# Verify proof
|
|
ots verify .ots/<commit-hash>.ots
|
|
|
|
# Upgrade pending proofs
|
|
ots upgrade .ots/<commit-hash>.ots
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- **No Node.js fallback** - ots CLI is mandatory
|
|
- **Attestation time:** ~10 min (Bitcoin confirmation)
|
|
- **Cache validity:** 1 hour, re-checks pending after 10 min
|
|
- **Commit overhead:** ~10-15s after initial backfill
|
|
- **Proof size:** ~500-900 bytes each
|
|
- **Safe to commit:** Yes, `.ots/` directory should be versioned
|
|
|
|
## Why ots CLI is Required
|
|
|
|
| Feature | ots CLI | Node.js Package |
|
|
|---------|---------|-----------------|
|
|
| Calendar submission | ✓ | ✗ |
|
|
| Bitcoin attestation | ✓ | ✗ |
|
|
| Proof upgrade | ✓ | ✗ |
|
|
| Verification | ✓ | ✗ |
|
|
| Local proofs | ✓ | ✓ |
|
|
|
|
The Node.js package only creates self-attested local proofs with no third-party verification. For tamper-evident timestamps anchored to Bitcoin, ots CLI is the only complete implementation.
|