git-mark

Git commits anchored to Bitcoin via Blocktrails.

npm install 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

# Show current address
git mark address

# Export txo.json
git mark export

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...
console.log(genesis.uri);     // txo:tbtc4:...

// Advance with git commit
const commitHash = 'cf97baba489e88c1ffbe6758c0fe8c18ff83d17d';
const result = gm.advance(commitHash, newTxid, vout, amount);

// Get current state
console.log(gm.address());
console.log(gm.currentPubkey());
console.log(gm.spendingKey());

// Export TXO URIs
const uris = gm.exportTxoJson();

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

txo:<network>:<txid>:<vout>?amount=<sats>&pubkey=<hex>[&commit=<git_hash>]

Genesis (no commit):

txo:tbtc4:34cea31b10e809e7cef4e19ce6e681da22ba1d2ae723af110cbba191e854be0e:0?amount=1000000&pubkey=3e458cc6f434c2292b3a23c044f4b046d5726c5ddee91c85f920c16817a5c8cf

After commit:

txo:tbtc4:45fbcbd79fc639204ae3dbe940881c66f7db1ad9b99eb49ff74fd83c481a9f7d:0?amount=999000&pubkey=b5bc388cf7a77362e7ec18cb4ba5ea9a9bc1cfd41b07322de3c40d20fa8e920c&commit=cf97baba489e88c1ffbe6758c0fe8c18ff83d17d

Git-mark uses single-use seals to bind Git commits 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
...

Each commit hash becomes a scalar tweak that derives the next pubkey. The UTXO chain on Bitcoin mirrors the commit chain in Git.

Clients verify by:

1. Checking genesis has no commit
2. Computing P_new = P_prev + sha256(commit) × G for each step
3. Comparing computed pubkeys against recorded pubkeys

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

Create a new Gitmark instance.

Initialize with genesis UTXO. Returns { txo, uri, address }.

Advance state with a git commit. Returns { txo, uri, address, prevAddress }.

Get current Taproot address.

Get current x-only pubkey (64 hex chars).

Get current spending private key.

Get array of TXO URI strings.

Export URIs for .well-known/txo/txo.json.

Verify a chain of TXO URIs. Returns { valid: boolean, error?: string }.

Parse a TXO URI string into components.

Format components into a TXO URI string.

• Blocktrails
• Blocktrails Spec
• Legacy gitmark
• Single-Use Seals

MIT