git-mark

Git commits anchored to Bitcoin via Blocktrails

GitHub Blocktrails Spec Legacy gitmark

Overview

git-mark binds Bitcoin UTXOs to Git commits using elliptic curve tweaking. Each commit hash becomes a tweak that derives a new pubkey, creating a cryptographic chain linking your repository history to Bitcoin.

Genesis: P₀ = privkey × G (base pubkey) Commit 1: P₁ = P₀ + sha256(commit₁) × G (tweaked by git commit) Commit 2: P₂ = P₁ + sha256(commit₂) × G ...

How It Works

Git-mark uses single-use seals to create a two-way binding between Git and Bitcoin:

┌─────────────┐ │ Git Commit │ │ (state Δ) │ └──────┬──────┘ │ hash ▼ ┌──────────┐ tweak ┌──────────┐ │ P_old │────────────►│ P_new │ │ (UTXO₁) │ │ (UTXO₂) │ └──────────┘ └──────────┘ │ │ │ spend │ new output ▼ ▼ ┌────────────────────────────────────┐ │ Bitcoin Transaction │ └────────────────────────────────────┘

TXO URI Format

txo:<network>:<txid>:<vout>?amount=<sats>&pubkey=<hex>[&commit=<git_hash>]
FieldDescription
networkBitcoin network (tbtc4, mainnet, signet)
txidTransaction ID (64 hex chars)
voutOutput index
amountValue in satoshis
pubkeyX-only pubkey (64 hex chars)
commitGit commit hash (40 hex chars, absent for genesis)

Quick Start

# Install
npm install -g git-seal

# Initialize in your repo
git mark init

# Set your private key
git config nostr.privkey <64-char-hex>

# Create genesis with your first UTXO
git mark genesis --txid <txid> --vout 0 --amount 1000000

# Make changes and commit
git commit -m "initial state"

# Anchor the commit to Bitcoin
git mark advance --txid <new-txid> --vout 0 --amount 999000

# Show current state
git mark show

# Verify chain integrity
git mark verify

TXO URI Parser

Parse TXO URI

Chain Verifier

Verify TXO Chain

Paste TXO URIs (one per line):

Library Usage

import { Gitmark } from 'git-seal';

// Create instance with private key
const gm = new Gitmark(privateKey, 'tbtc4');

// Initialize genesis
const genesis = gm.genesis(txid, vout, amount);
console.log(genesis.address); // tb1p...

// Advance with git commit
const result = gm.advance(commitHash, newTxid, vout, amount);
console.log(result.uri); // txo:tbtc4:...

// Get current address
console.log(gm.address());

// Export TXO URIs for .well-known/txo/txo.json
const uris = gm.exportTxoJson();

// Verify a chain (no private key needed)
const valid = Gitmark.verify(uris);
if (!valid.valid) console.error(valid.error);

Directory Structure

.well-known/
└── txo/
    └── txo.json      # Array of TXO URIs

Links

License

MIT