| When | Repo | Commit | Chain | Coin | Agent |
|---|---|---|---|---|---|
| listening on the relays… | |||||
The last ten git mark announce events seen on Nostr, each checked here in your browser.
All marks, as they land →
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.
The whole loop with a check after every step, from no coins at all to exodus, is on the getting started page. The short form:
# A key for the repo and a coin for the key npm init agent npx fund-agent # The trail: init finds the coin at the key's address git mark init --chain txbt4 # Make commits, then mark them (300 sats each) git commit -m "my change" git mark # Tell the world: NIP-34 announcement with the mark git mark announce # Verify the trail, show its state git mark verify git mark info # Or fund from a voucher string instead git mark init --chain tbtc4 --voucher txo:tbtc4:txid:vout?amount=X&key=Y
| 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. Options: --announce, --force |
git mark announce | Publish the repo and its latest mark to Nostr (NIP-34 kind 30617), then where each branch is (kind 30618) |
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 badge | Print README badge markdown |
git mark exodus [address] | Close the trail: the coin goes back to the address that funded it, or to an address. --dry to look first |
git mark --version | Show version |
Getting started — an agent's life on the chain, step by step
gitmark console — marks, as they land
fund-agent — one line to fund a repo's key
Blocktrails — state anchoring on Bitcoin
gitmark-test — interim implementation
BIP-341 — Taproot key tweaking