Every git mark creates a Bitcoin transaction that anchors your current commit to the blockchain. The transaction address is derived from your key + the commit hash using BIP-341 key chaining. Anyone can verify the anchor. Nobody can tamper with it.
The result is a two-way link: the blockchain follows your repo (via tweaked addresses), and your repo follows the blockchain (via blocktrails.json).
npm install -g gitmark
This gives you git mark as a native git subcommand.
# Initialize in a git repo git mark init --chain tbtc4 --voucher txo:tbtc4:txid:vout?amount=X&key=Y # Make commits, then mark them git commit -m "my change" git mark # Verify the trail git mark verify # Show trail state git mark info
| Step | What Happens |
|---|---|
| Init | Generates or reads your Nostr key, creates blocktrails.json, optionally funds the trail |
| Mark | Takes HEAD commit hash, derives a tweaked taproot address via BIP-341, builds and broadcasts a Bitcoin transaction |
| Verify | Walks the trail, re-derives each address from the public key + commit hashes, checks each transaction on Bitcoin |
Each mark advances the key chain: newKey = baseKey + tweak(commit_hash). The chain of derived addresses on Bitcoin mirrors the chain of commits in git.
blocktrails.json lives in your repo root, committed and visible:
{
"version": "0.0.3",
"profile": "gitmark",
"pubkeyBase": "02abc...",
"chain": "tbtc4",
"states": ["a1b2c3...", "e5f6a7..."],
"txo": [
"txo:tbtc4:abc:0?commit=a1b2c3...",
"txo:tbtc4:def:0?commit=e5f6a7..."
]
}
states — the commit hashes (input to key chaining math). txo — the Bitcoin anchors (TXO URIs, self-contained and verifiable). Anyone who clones your repo can verify the trail independently.
Your private key is stored in git config:
git config nostr.privkey <64-char-hex>
The same secp256k1 key you use for Nostr, Bitcoin, and Solid pod authentication. One key for everything.
Git-mark is a blocktrails application profile. The key chaining math is identical to MRC20 tokens — just with commit hashes as state instead of token ledgers. A generic blocktrails verifier handles both.
Two dependencies: @noble/curves and @noble/hashes. No bitcoinjs-lib. No external transaction builders. Pure secp256k1 math.
| Command | Description |
|---|---|
git mark init | Initialize trail. Options: --chain, --voucher, --force |
git mark | Anchor HEAD commit to Bitcoin |
git mark info | Show trail state, balance, addresses |
git mark verify | Verify all marks against Bitcoin |
git mark update | Update blocktrails.json from git notes |
git mark --version | Show version |
Blocktrails — state anchoring on Bitcoin
gitmark-test — interim implementation
BIP-341 — Taproot key tweaking