# gitmark

> Anchor git commits to Bitcoin via blocktrails

Latest version **0.0.78** (published 2026-09-23) · AGPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install gitmark
pnpm add gitmark
yarn add gitmark
bun add gitmark
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.78 |
| Published | 2026-09-23 |
| First published | 2021-04-02 |
| Weekly downloads | 0 |
| License | AGPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Melvin Carvalho |
| Maintainers | melvincarvalho |
| Keywords | gitmark, blocktrails, bitcoin, git, nostr |

## Links

- npm: https://www.npmjs.com/package/gitmark
- Repository: https://github.com/solidpayorg/gitmark
- Homepage: https://git-mark.com
- Issues: https://github.com/solidpayorg/gitmark/issues
- npm.io page: https://npm.io/package/gitmark

## Recent versions

- 0.0.78 (latest) — 2026-09-23
- 0.0.77 — 2026-04-18
- 0.0.76 — 2026-04-06
- 0.0.75 — 2026-04-06
- 0.0.74 — 2026-04-04
- 0.0.73 — 2026-04-04
- 0.0.72 — 2026-04-04
- 0.0.71 — 2026-04-04
- 0.0.70 — 2026-04-04
- 0.0.69 — 2026-04-04
- 0.0.68 — 2022-07-25
- 0.0.67 — 2022-07-09
- 0.0.66 — 2022-07-09
- 0.0.65 — 2022-07-09
- 0.0.64 — 2022-07-09
- … 58 more at https://npm.io/package/gitmark/versions

## README

# git mark

Anchor git commits to Bitcoin via [blocktrails](https://blocktrails.org) key chaining.

[![npm](https://img.shields.io/npm/v/gitmark)](https://npmjs.com/package/gitmark)
[![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)

## Install

```sh
npm install -g gitmark
```

This gives you `git mark` as a native git subcommand.

## Quick Start

```bash
# Initialize in a git repo (tbtc4 = Bitcoin testnet4)
git mark init --chain tbtc4 --voucher txo:tbtc4:txid:vout?amount=X&key=Y

# Or read vouchers from a file (uses last line, removes on success)
git mark init --voucher ~/faucet/vouchers.txt

# Make commits, then mark them
git commit -m "my change"
git mark

# Verify the trail against Bitcoin
git mark verify

# Show trail state
git mark info
```

## Chains

Pick one with `--chain` at `git mark init`. It's recorded in `blocktrails.json` and used for every later mark.

| Chain | Network | Addresses | Explorer API |
|-------|---------|-----------|--------------|
| `tbtc4` (default) | Bitcoin testnet4 | `tb1p…` | mempool.space/testnet4 |
| `tbtc3` | Bitcoin testnet3 | `tb1p…` | mempool.space/testnet |
| `signet` | Bitcoin signet | `tb1p…` | mempool.space/signet |
| `btc` | Bitcoin | `bc1p…` | mempool.space |
| `xbt` | BLAKE2b fork of Bitcoin, from block 961,640 | `bc1p…` | mempool.kilombino.com |
| `txbt4` | BLAKE2b fork of testnet4, from block 150,308 | `tb1p…` | mempool.guide/testnet4 |

On `xbt` and `txbt4`, marks are signed with `SIGHASH_UNIFIED` ([spec](https://github.com/bitcoin-blake/blaketest/blob/gh-pages/unified-sighash.md)): a 65-byte signature ending `0x21` that Knots accepts on the BLAKE2b chains and SHA256d nodes reject. Coins from before the fork exist on both chains, so without this a mark could be replayed onto the original chain. `lib/unified-sighash.js` implements it and passes Knots's 166 test vectors (`test/unified_sighash.json`).

## How It Works

Each `git mark` creates a real Bitcoin transaction. The address is derived from your key + the commit hash using BIP-341 taproot key chaining:

```
baseKey + tweak(commit₁) → Address₁ → TXO₁
baseKey + tweak(commit₁, commit₂) → Address₂ → TXO₂
```

The chain of addresses on Bitcoin mirrors the chain of commits in git. Anyone can verify by re-deriving the addresses from the public key + commit hashes.

## Commands

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

## Trail File

`blocktrails.json` in your repo root — committed, visible, verifiable:

```json
{
  "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"
  ]
}
```

- **pubkeyBase** — compressed pubkey (02/03 prefix), base for BIP-341 key chaining
- **states** — commit hashes (input to key derivation)
- **txo** — Bitcoin anchors (TXO URIs, self-contained and verifiable)

Private spending state stored in `gitmark.txo` git config (never committed).

## Configuration

```bash
# Private key (auto-generated by init)
git config --local nostr.privkey <64-char-hex>

# Current UTXO (updated on each mark)
git config --local gitmark.txo txo:tbtc4:txid:vout?amount=X&commit=Y

# Dirty flag — set to false to keep working tree clean after marking
git config --local gitmark.dirty false
```

When `gitmark.dirty=false`, `git mark` only writes git notes + git config. Run `git mark update` to sync blocktrails.json when ready.

Same secp256k1 key used for Nostr, Bitcoin, and Solid pod authentication.

## Dependencies

Two: `@noble/curves` and `@noble/hashes`. No bitcoinjs-lib, no external transaction builders.

## Related

- [blocktrails.org](https://blocktrails.org) — state anchoring on Bitcoin
- [git-mark.com](https://git-mark.com) — project homepage
- [BIP-341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) — Taproot key tweaking

## License

AGPL-3.0 &copy; Melvin Carvalho

---
_Source: https://npm.io/package/gitmark · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._