gitmark 0.0.68 → 0.0.70

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:www.rgbfaq.com)",
+      "WebFetch(domain:rgb.info)",
+      "Bash(npm install)",
+      "Bash(npm search txo_parser)",
+      "Bash(../gitmark/bin/git-mark)",
+      "Bash(../gitmark/bin/git-mark --genesis abc123:0)"
+    ],
+    "deny": [],
+    "ask": [],
+    "defaultMode": "acceptEdits",
+    "additionalDirectories": [
+      "/home/melvin/remote/github.com/solidpayorg/solidpayorg"
+    ]
+  }
+}

package/BURN.md

@@ -0,0 +1,11 @@
+## Introduction
+
+Burn is an optional garbage collection operation.  Burn is when you want to and a git mark tracking chain.
+
+## Transaction
+
+The best way to do this is to send vout 0 back to the orginal pubkey, creating a tweak of 0 which is impossible.
+
+## Conclusion
+
+This optional operation can clean up a chain and freeze it in time

package/CRYPTO.md

@@ -0,0 +1,27 @@
+# Crypto
+
+![image](https://github.com/solidpayorg/gitmark/assets/65864/a06152fc-a7f5-4a99-a75f-4471e16ea173)
+
+`version 0.0.2`
+
+This page describes the on-chain primitives and mappings used in gitmark [SCHEMA](./SCHEMA.md)
+
+# Gitmark Transitions: Bridging Blockchain and Git
+
+Gitmark transitions offer a novel approach to embedding on-chain commitments within the blockchain, enabling a seamless capture of changes from one transaction to another. This methodology leverages a unique process termed as a **"tweaked spend to self"** to modify a transaction's output (TXO), enriching it with additional data while ensuring the original asset holder retains ownership.
+
+## How It Works
+
+- **Initial State (Address 1)**: Identified as `A`, this represents the blockchain address prior to modification.
+- **Transformed State (Address 2)**: Denoted as `A + T`, this address emerges post-modification, with `T` symbolizing the tweak applied to `A`. This tweak is not arbitrary; it encapsulates specific, transition-relevant information.
+
+The new address has a vout of 0.  All other vouts are not used in gitmark, they may be used to send funds elsewhere.
+  
+### The Role of `T`
+
+`T` stands out as it is meticulously designed to serve as an on-chain commitment, directly alluding to a distinct Git commit. The core of `T`'s value lies in its equivalence to the latest Git hash. This equivalence forges a verifiable nexus between the blockchain transaction and a specific snapshot of the Git repository.
+
+### Implications
+
+This intricate connection ensures the blockchain's role extends beyond the realm of financial transactions, positioning it as a robust, unalterable ledger for software development benchmarks through Git commits. Gitmark transitions herald a new era of transparency and auditability in software development. They exploit blockchain's core strengths—trust and integrity—to solidify digital records' credibility.
+

package/GENESIS.md

@@ -1,12 +1,16 @@
 ## Genesis
 
+### Prerequisites 
+
 The genesis transaction output starts the chain of marks in git mark
 
-In order to start marking you will need a genesis transaction output
+In order to start marking you will need a genesis transaction output aka uxto
 
 This will also have a public address and a private key (secret exponent)
 
-You will need the transaction id and the secret exponent to start git marking
+You will need the **transaction output id** and the **private key** to start git marking
+
+### Storing Secrets
 
 One way to save the secret exponent is in git
 
@@ -14,7 +18,7 @@ One way to save the secret exponent is in git
 git config gitmark.secret <secretexponent>
 ```
 
-This is not terribly secure, but for small projects to get started it is convenient
+This is not terribly secure, but for small projects to get started it is convenient.  An article on trade offs of this approach is presented here [here](https://withblue.ink/2021/05/07/storing-secrets-and-passwords-in-git-is-bad.html)
 
 A useful way to generate an address and secret exponent would be:
 
@@ -22,28 +26,60 @@ https://project-bitmark.github.io/brain/
 
 Use a very secure password for anything more than testing
 
+### Funding
+
 Once you have an address, send some coins there from a faucet, a friend, or by being marked
 
 The genesis id also doubles as the @id for a gitmark project
 
-Optionally it can be added a file, `gitmark.json` in the root directory of your repo
+
+### Gitmark.json
+
+Optionally a file can be added, `gitmark.json`, in the root directory of your repo
 
 It may look like this:
 
 ```JSON
 {
-  "@id": "gitmark:b1fb9acb83f85887760b2e1a71e1df370976b1596be101bb0dbe8fd1c80f91cd:0",
-  "genesis": "gitmark:b1fb9acb83f85887760b2e1a71e1df370976b1596be101bb0dbe8fd1c80f91cd:0",
+  "@id": "gitmark:59ff24db0321cb6b32a404815345b00ae68ca8b81150fbea6464ee10557e0fae:1",
+  "genesis": "gitmark:59ff24db0321cb6b32a404815345b00ae68ca8b81150fbea6464ee10557e0fae:1",
   "nick": "myrepo",
   "package": "./package.json",
+  "pubkey": "7574866ae7653e084c3c8e9e6359660e2c728d249fefb0f984bd32393f2ac67f",
   "repository": "./"
 }
 ```
 
+- **@id** is the unspent transaction output
+- **genesis** points to the same transaction output
+- **nick** is a short name e.g. as used in npm
+- **package** points to a package.json info
+- **pubkey** is the pubkey for the genesis tx, in hex
+- **repository** is an absolute or relative hint as to where to find the git code
+
+
+### First git mark
+
 Once you have your genesis tx, you can make your first git mark by running, for example:
 
 ```
 git mark --genesis b1fb9acb83f85887760b2e1a71e1df370976b1596be101bb0dbe8fd1c80f91cd:0
 ```
 
-Do this after you have commited your first files, and as recommended a gitmark.json file too
+Do this after you have committed your first files, and as recommended a gitmark.json file too
+
+
+### Notes on Commits
+
+The commit requires a name, email and commit message, with optional signing.
+
+The **name** can be whatever you want
+
+The **email** is open, but you can select a noreply address to indicate privacy, such as noreply@<genesis-hash>.gitmark
+  
+The **commit message** can be anything, and will be the first commit ready to be marked.  e.g. "first"
+
+### Notes on .gitmark   
+
+The .gitmark address is just a place holder if it is undesirable to enter a public email address.  In future it may be possible to resolve .gitmark URLs to a working GitHub repository and deployments
+  

package/MARK.md

@@ -0,0 +1,38 @@
+![image](https://github.com/solidpayorg/gitmark/assets/65864/09e421be-a3ce-4e4d-b2c2-e5c1be4ebb87)
+
+## Introduction
+
+Mark is the main function of gitmark.  It has a prerequisite on [GENESIS](./GENESIS.md) and
+with these two oprations you are able to create robust git repos recorded in time, and 
+identifiable globally.
+
+## Chain follows repo
+
+A mark is a marking of the underlying block chain with an on-chain committment
+
+The transaction is tweeked with the new git hash, according to [CRYPTO](./CRYPTO.md)
+
+In essense, this proves the chain is following the github repo and provides a timestamp server
+
+## Repo follows chain
+
+In order to create a two-way relationship the repo also follows the chain by recording the most recent
+transaction object (txo) in a well known location.
+
+## TXO well known location
+
+The txo well known location is in the directory `.txo`
+
+In there is a file txo.txt which is of the form:
+
+```
+<txo_uri> <balance>
+```
+
+The balance is an amount in satoshis
+
+## Conclusion
+
+In this way, the chain follows the repository, and the repository follows the chain, 
+leading to a robust, auditable, time-stamping solution using Git and blockchains. 
+This approach prevents double-spending by ensuring that the repository and the blockchain are in sync with each other.

package/OPS.md

@@ -0,0 +1,31 @@
+## Gitmark Operations
+
+### Genesis
+
+Genesis is the utxo used to create a reference to the project
+
+[Docs](./GENESIS.md)
+
+### Mark
+
+Marks a super commit by tweaking a spend to self transaction by the by commit hash
+
+[Docs](./MARK.md)
+
+### Topup
+
+Tops up a seal, can be combined with Mark
+
+[Docs](./MARK.md)
+
+### Transfer
+
+Transfers ownership of the contract to another party
+
+[Docs](./TRANSFER.md)
+
+### Burn
+
+Marks a repo as inactive
+
+[Docs](./BURN.md)

package/README.md

@@ -1,159 +1,99 @@
-<div align="center">
-  <h1>gitmark</h1>
-</div>
+# git mark
 
-<div align="center">  
-Mark your git commits, to create global consensus, and a definitive project history
-</div>
+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-MIT-blue.svg)](./LICENSE)
 
-<div align="center">
-<h4>Getting Started</h4>
-</div>
-  
----
-  
-
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/solidpayorg/git-mark/blob/gh-pages/LICENSE)
-![npm](https://img.shields.io/npm/v/gitmark)
-[![npm](https://img.shields.io/npm/dw/gitmark.svg)](https://npmjs.com/package/gitmark)
-[![Github Stars](https://img.shields.io/github/stars/solidpayorg/gitmark.svg)](https://github.com/solidpayorg/gitmark/)
-  
-  
-## Introduction
-
-Gitmark extends git to allow commits to be "marked" (using the command `git mark`) by a supporting block chain. This "reinforces" or "finalizes" a given commit, to determine global consensus and a definitive project history
-
-## Installation
+## Install
 
 ```sh
-sudo npm install -g gitmark
+npm install -g gitmark
 ```
 
-## Usage
-
-```bash
-git mark # marks the current commit
-
-git mark [--genesis txoutput] # used for the genesis commit
-```
-
-## Motivation
-
-Gitmark, was originally created to facilitate the [marking](https://github.com/project-bitmark/marking/wiki) use case, which aims to allow global, distributed, reputation trees, to be grounded in a block chain
-
-What is made possible, is a way to provide consensus on a definitive git branch/chain, in order to ensure that the history has not been tampered with
-
-One can reconstruct the current state from the history, and this can also be used to preserve your reputation at any given time, say, if any provider ceases to operate
-
-It's also possible to audit and verify the integrity of the git chain, to create a secure, finalized, state machine, with a definitive head, that is globally synced
-
-The system can be extended beyond reputation trees, to use any git based store, and anchor it to a secure, verifyable chain of blocks, to determine the definitve history
-
-Many thanks go to Peter Todd for his work on [single use seals](https://petertodd.org/2017/scalable-single-use-seal-asset-transfer) and Dr Maxim Orlovsky for his work on [RGB](https://rgb-org.github.io/)
-
-_Gitmark is pre-alpha software, it should be considered experimental, and used at your own risk_
-
-## Prerequisites
-
-Because gitmark was designed to anchor reputation trees, the reputation of the underlying block chain must be unimpared.  Gitmark only supports block chains that are provably fair.  Bitcoin is regarded as the most secure and fairest of all block chains, and should be used for high value projects where cost is not an issue
-
-Gitmark does not support projects that are premines, instamines, ICOs, have developer taxes or provably unfair consensus, such as proof of stake
-
-In solving the reputation use case, we aim to innovate in the space, contribute back code, and operate as a testing ground
-
-Bearing in mind that this is experimental software, the [bitmark](https://bitmark.rocks/) block chain, is the first chain on which gitmark is tested and implemented.  As it inexpensive, easily obitained, and was designed for the grounding of reputation trees (gitmark is a play on the word bitmark). This also provides a testing ground for developers to get started.  The Liquid network is also a possible target, and Litecoin appears to be another good possibility, as well as the various testnets
-
-The first prerequisite is to obtain an unspent transaction on a supporting block chain. This can be in any coin, but to get started we suggest, getting hold of one Bitmark, which can be obtained inexpensively for example in the [chat room](https://projectbitmark.slack.com/) as it is designed to be spread between helpful actors, to foster innovation
-
-## Getting started
+This gives you `git mark` as a native git subcommand.
 
-After you have obtained some block chain currency, send those coins to an address for which you have the keypair. That becomes the genesis unspent transaction
+## Quick Start
 
-Having created a genesis transaction, and recording the key pair safely, you are ready to start marking!
-
-Install gitmark globally via npm, the executables will be in the bin directory which can be located with `which git-mark`
-
-The genesis transaction provides the first input to the `git mark` command, and the private key (secret exponent in hex) is needed to advance the genesis transaction in line with the current git HEAD
-
-## Git mark
-
-Simply running `git mark` on a repo will create your first marking
-
-You will need a genesis address for the first run of the form `tx:output` and supply that with the argument --genesis [tx]
-
-You will also need the private key from that tx, which is an argument to the gitmark script, but can be also saved in a location as directed by the output from the git mark command. The key (ie 64 char hex secret exponent) should be stored in the indicated file with the json key "privkey"
-
-_Warning: do not use the default private key, that is set, in the script!_
-
-Git mark will generate a new address to send to, a fee, an amount, a spending private key and unspent tx data as inputs to an rpc or a simple script `tx.sh` that lives in the bin directory. Future versions will use a transaction builder to send to a network directly
-
-After running this script, an empty commit message is generated which you can check in, and points to the latest new unspent transaction, creating a two way link.  The commit message is a gitmark [URI](./URI.md)
-
-Congratulations! You have now marked your first git repo!
-
-See also: [Example Workflow](./WORKFLOW.md)
-
-## How it works
-
-Gitmark simply uses [single use seals](https://petertodd.org/2017/scalable-single-use-seal-asset-transfer) to tweak the initial public key address of the genesis transaction by the commit hash of the git tree. The current git hash is added to the original, genesis, public key in the output transaction, creating a chain of commits in the block chain
-
-In this way the block chain points to git. It then points the next commit back to the block chain tx, creating two way link, and therefore, strong binding, at one particular point in time
+```bash
+# Initialize in a git repo (tbtc4 = Bitcoin testnet4)
+git mark init --chain tbtc4 --voucher txo:tbtc4:txid:vout?amount=X&key=Y
 
-Similarly the definitive git tree forms a chain of commits that go forward in time, and so do the new transaction on the block chain. Further commits are periodically marked in time proving an auditable trail in both time on-chain of the evolution of the git tree. It also shows the latest confirmed state of a git tree that can be used for trading or in safe or smart contracts
+# Make commits, then mark them
+git commit -m "my change"
+git mark
 
-The first use case for gitmark is marking of reputation trees, but it can be applied to any git system where the history is important
+# Verify the trail against Bitcoin
+git mark verify
 
-## Recent git marks
+# Show trail state
+git mark info
+```
 
-- [Github](https://github.com/search?o=desc&q=%22gitmark+%22&s=committer-date&type=Commits)
+## How It Works
 
-## Use Cases
+Each `git mark` creates a real Bitcoin transaction. The address is derived from your key + the commit hash using BIP-341 taproot key chaining:
 
-- Distributed Reputation Trees
-- Distributed Ledgers
-- Registries
-- Safe or Smart Contracts
-- Asset Issuance
-- Distributed Exchanges
-- Reconstruct histories from Genesis
-- Distributed Global Consensus
-- Domain independent web sites
-- Archiving and Time Travel through History
-- Distributed Identity and PKI
-- Federated Side Chains
-- Auditing Histories
-- Fraud Detection
-- Supply Chains
+```
+baseKey + tweak(commit₁) → Address₁ → TXO₁
+baseKey + tweak(commit₁, commit₂) → Address₂ → TXO₂
+```
 
-## Related work
+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 |
+
+## Trail File
+
+`blocktrails.json` in your repo root — committed, visible, verifiable:
+
+```json
+{
+  "version": "0.0.3",
+  "profile": "gitmark",
+  "publicKeyBase": "02abc...",
+  "chain": "tbtc4",
+  "states": ["a1b2c3", "e5f6a7"],
+  "txo": [
+    "txo:tbtc4:abc:0?commit=a1b2c3",
+    "txo:tbtc4:def:0?commit=e5f6a7"
+  ]
+}
+```
 
-- [Single Use Seals](https://petertodd.org/2017/scalable-single-use-seal-asset-transfer)
-- [RGB](https://rgb-org.github.io/)
-- [Commerce Block Mainstay](https://www.commerceblock.com/mainstay/) [[White Paper](https://cloudflare-ipfs.com/ipns/ipfs.commerceblock.com/commerceblock-whitepaper-mainstay.pdf)]
-- [BIP 175 - Pay to Contract Protocol](https://github.com/bitcoin/bips/blob/master/bip-0175.mediawiki)
+- **publicKeyBase** — 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)
 
-## Source code
+Private spending state stored in `.git/blocktrails.json` (never committed).
 
-- [Source](https://github.com/solidpayorg/gitmark)
-- [Issue Tracker](https://github.com/solidpayorg/gitmark/issues)
-- [NPM](https://www.npmjs.com/package/gitmark)
+## Key Storage
 
-## Future work
+Your private key is stored in git config:
 
-- Git marks can be extended to further layers by using git submodules hence creating almost unlimited space
+```bash
+git config nostr.privkey <64-char-hex>
+```
 
-- Private git repositories can be supported out of the box, and given that private keys are used in each seal, encrypted backups can be made
+Same secp256k1 key used for Nostr, Bitcoin, and Solid pod authentication.
 
-- The project git tree can be backed up or archived using git clone in multiple locations. It is natural that popular projects are cloned often in any case
+## Dependencies
 
-- Seals can be opened and closed using a federation, in order to try out multiple consensus and vefification methods
+Two: `@noble/curves` and `@noble/hashes`. No bitcoinjs-lib, no external transaction builders.
 
-- More robust verification frameworks can be built using node testing frameworks, and continusous integration, tho currently the distribution contains a git-mark-verify script
+## Related
 
-- Lightweight Autonomous Marking Agents (LAMAs) can be created that listen to communities for marks and just work, without needing a human operator. The service can be deployed on a server or container, and be designed to bring itself up if it goes down in any one location
+- [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
 
-- MIT
+MIT

package/SCHEMA.md

@@ -0,0 +1,25 @@
+## Gitmark Schema
+
+The Gitmark schema is a framework for organizing and tracking changes in a Git repository. It is inspired by the concept of [RGB Schemas](https://www.rgbfaq.com/glossary/schema-and-scripts/schema), which provide a way to represent and validate data in a decentralized network.
+
+## Operations (OPS)
+
+The Gitmark schema defines five core operations (OPS) for managing the state of a Git repository:
+
+1. [GENESIS](./GENESIS.md): Initializes a new Git repository and creates the first commit.
+2. [MARK](./MARK.md): Records a specific state or event in the Git repository, such as a milestone or release.
+3. [TOPUP](./TOPUP.md): Adds new funds or resources to the Git repository, such as through a crowdfunding campaign or sponsorship.
+4. [TRANSFER](./TRANSFER.md): Moves funds or resources from one part of the Git repository to another, such as between different branches or accounts.
+5. [BURN](./BURN.md): Closes out a Git repository and transfers any remaining funds or resources to a designated recipient.
+
+## Cryptographic Operations
+
+The Gitmark schema uses cryptographic operations to ensure the integrity and security of the Git repository. These operations include:
+
+1. Tweaking: A process for transitioning from one state to another in the Git repository, using cryptographic techniques to ensure that the transition is valid and secure.
+2. Genesis: The creation of a new Git repository, using cryptographic techniques to establish the initial state and ensure that it is secure.
+3. And other cryptographic operations as described in [CRYPTO](./CRYPTO.md)
+
+The Gitmark schema maps each of these cryptographic operations to the corresponding OPS, ensuring that the Git repository is managed in a secure and consistent manner.
+
+By following the Gitmark schema, developers can ensure that their Git repositories are well-organized, secure, and easy to manage. The schema provides a clear framework for tracking changes and managing resources, making it easier to collaborate and build high-quality software.

package/TOPUP.md

@@ -0,0 +1,15 @@
+## Introduction
+
+Topup is a function of Gitmark that lets you increase the amount of funds in a commitment. This allows a repo to continue operating after it has become low on funds.
+
+## Add another tx input
+
+Simply add another tx input to your transaction, and the new transaction output will have more funds in it.
+
+## Donations
+
+Certain versions of the software may incur donations; this, in turn, could be used to top up the project and keep it going longer.
+
+## Conclusion
+
+Topup is a super simple workflow that sweeps inputs into a new output spliced together with a mark, in order to increase funds on-chain.

package/USE_CASES.md

@@ -0,0 +1,67 @@
+# **Gitmark Use Cases**
+
+Gitmark harnesses git and blockchain technologies to provide innovative solutions across various fields. Below is a detailed breakdown of its diverse applications:
+
+### **1. Distributed Reputation Systems**
+- **Purpose:** Create tamper-proof, transparent, decentralized reputation systems.
+- **Benefits:** Enhances trust in digital interactions.
+
+### **2. Distributed Ledgers**
+- **Applications:** Financial transactions, supply chain management, etc.
+- **Technology:** Combines git with blockchain for secure, decentralized ledgers.
+
+### **3. Registries**
+- **Function:** Establish decentralized registries for assets, identities, and more.
+- **Advantages:** Ensures data integrity and accessibility.
+
+### **4. Safe or Smart Contracts**
+- **Capability:** Execute contracts stored on blockchain, ensuring transparency and immutability.
+- **Feature:** Automated contract execution.
+
+### **5. Asset Issuance**
+- **Service:** Issue digital assets like tokens or certificates with a blockchain-backed history.
+- **Highlight:** Provides verifiability and auditability.
+
+### **6. Distributed Exchanges**
+- **Description:** Build decentralized exchanges for peer-to-peer asset trading.
+- **Characteristic:** Maintains a transparent and immutable transaction record.
+
+### **7. Historical Reconstruction**
+- **Functionality:** Reconstruct complete histories from genesis block.
+- **Use:** Offers a comprehensive, verifiable record of transactions and changes.
+
+### **8. Distributed Global Consensus**
+- **Purpose:** Facilitate decentralized decision-making and governance.
+- **Approach:** Enables distributed consensus on system states.
+
+### **9. Decentralized Web Hosting**
+- **Application:** Host websites in a decentralized manner, promoting resistance to censorship.
+- **Benefit:** Eliminates single points of failure.
+
+### **10. Archiving and Historical Analysis**
+- **Features:** Archive data and navigate through historical records.
+- **Use Case:** Provides insights and supports audits.
+
+### **11. Distributed Identity and PKI**
+- **Function:** Create decentralized identity systems and public key infrastructure.
+- **Advantages:** Enhances security and privacy in digital interactions.
+
+### **12. Federated Side Chains**
+- **Objective:** Build interoperable side chains among different blockchains or git repositories.
+- **Benefit:** Facilitates communication and interoperability.
+
+### **13. Auditing**
+- **Capability:** Audit entire histories of systems for transparency and accountability.
+- **Contexts:** Useful in financial transactions, supply chain management, etc.
+
+### **14. Fraud Detection**
+- **Method:** Maintain a tamper-proof, auditable record to detect and prevent fraud.
+- **Industries:** Applicable across various sectors.
+
+### **15. Supply Chain Management**
+- **Service:** Create traceable and accountable supply chain systems.
+- **Feature:** Enhances transparency and efficiency throughout processes.
+
+### **Conclusion**
+Gitmark's integration of git and blockchain technologies offers transformative potential across industries, revolutionizing data storage, sharing, and verification to create more secure and efficient systems.
+

package/bin/git-mark.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+
+/**
+ * git-mark — Anchor git commits to Bitcoin via blocktrails
+ *
+ * Usage:
+ *   git mark init [--chain tbtc4] [--voucher txo:...]
+ *   git mark [--chain tbtc4]
+ *   git mark info
+ *   git mark verify
+ */
+
+import { secp256k1, schnorr } from '@noble/curves/secp256k1';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+// --- Constants ---
+const SECP_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n;
+const TRAIL_FILE = 'blocktrails.json';
+const PRIVATE_FILE = '.git/blocktrails.json';
+const DEFAULT_CHAIN = 'tbtc4';
+
+const CHAINS = {
+  tbtc3:  { explorer: 'https://mempool.space/testnet/api', name: 'Bitcoin Testnet3' },
+  tbtc4:  { explorer: 'https://mempool.space/testnet4/api', name: 'Bitcoin Testnet4' },
+  btc:    { explorer: 'https://mempool.space/api', name: 'Bitcoin' },
+  signet: { explorer: 'https://mempool.space/signet/api', name: 'Bitcoin Signet' },
+};
+
+// --- Blocktrails key chaining (BIP-341) ---
+function taggedHash(tag, ...msgs) {
+  const tagHash = sha256(new TextEncoder().encode(tag));
+  return sha256(concatBytes(tagHash, tagHash, ...msgs));
+}
+
+function btScalar(pubkeyCompressed, state) {
+  const xOnly = pubkeyCompressed.slice(1);
+  const stateBytes = typeof state === 'string' ? new TextEncoder().encode(state) : state;
+  const sh = sha256(stateBytes);
+  return bytesToBigInt(taggedHash('TapTweak', xOnly, sh)) % SECP_N;
+}
+
+function bytesToBigInt(bytes) {
+  return BigInt('0x' + bytesToHex(bytes));
+}
+
+function bigIntToBytes(n) {
+  const hex = n.toString(16).padStart(64, '0');
+  return hexToBytes(hex);
+}
+
+function deriveChainedPrivkey(privkeyBytes, states) {
+  let d = bytesToBigInt(privkeyBytes);
+  let cur = new Uint8Array(secp256k1.getPublicKey(privkeyBytes, true));
+  for (const s of states) {
+    const t = btScalar(cur, s);
+    d = (d + t) % SECP_N;
+    cur = new Uint8Array(secp256k1.ProjectivePoint.BASE.multiply(d).toRawBytes(true));
+  }
+  return bigIntToBytes(d);
+}
+
+function deriveChainedPubkey(pubkeyBase, states) {
+  let P = secp256k1.ProjectivePoint.fromHex(bytesToHex(pubkeyBase));
+  let cur = pubkeyBase;
+  for (const s of states) {
+    const t = btScalar(cur, s);
+    P = P.add(secp256k1.ProjectivePoint.BASE.multiply(t));
+    cur = new Uint8Array(P.toRawBytes(true));
+  }
+  return cur;
+}
+
+// --- Bech32m encoding ---
+const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+function polymod(values) {
+  const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+  let chk = 1;
+  for (const v of values) { const b = chk >> 25; chk = ((chk & 0x1ffffff) << 5) ^ v; for (let i = 0; i < 5; i++) if ((b >> i) & 1) chk ^= GEN[i]; }
+  return chk;
+}
+function hrpExpand(hrp) { const r = []; for (const c of hrp) r.push(c.charCodeAt(0) >> 5); r.push(0); for (const c of hrp) r.push(c.charCodeAt(0) & 31); return r; }
+function convertBits(data, from, to) { let acc = 0, bits = 0; const r = []; const max = (1 << to) - 1; for (const v of data) { acc = (acc << from) | v; bits += from; while (bits >= to) { bits -= to; r.push((acc >> bits) & max); } } if (bits > 0) r.push((acc << (to - bits)) & max); return r; }
+
+function bech32mEncode(hrp, version, program) {
+  const values = [version, ...convertBits(program, 8, 5)];
+  const enc = [...hrpExpand(hrp), ...values, 0, 0, 0, 0, 0, 0];
+  const mod = polymod(enc) ^ 0x2bc830a3;
+  const checksum = [0, 1, 2, 3, 4, 5].map(i => (mod >> (5 * (5 - i))) & 31);
+  let result = hrp + '1';
+  for (const v of [...values, ...checksum]) result += BECH32_CHARSET[v];
+  return result;
+}
+
+function pubkeyToAddress(pubkeyHex, states, chain) {
+  const pubBytes = hexToBytes(pubkeyHex);
+  const derived = states.length > 0 ? deriveChainedPubkey(pubBytes, states) : pubBytes;
+  const xOnly = derived.slice(1);
+  const hrp = chain === 'btc' ? 'bc' : 'tb';
+  return bech32mEncode(hrp, 1, xOnly);
+}
+
+// --- P2TR script ---
+function p2trScript(xonly) {
+  return new Uint8Array([0x51, 0x20, ...xonly]);
+}
+
+// --- Transaction building helpers ---
+function writeVarInt(n) {
+  if (n < 0xfd) return new Uint8Array([n]);
+  if (n <= 0xffff) { const b = new Uint8Array(3); b[0] = 0xfd; b[1] = n & 0xff; b[2] = (n >> 8) & 0xff; return b; }
+  return new Uint8Array([0xfe, n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff]);
+}
+function writeU32LE(n) { const b = new Uint8Array(4); b[0] = n & 0xff; b[1] = (n >> 8) & 0xff; b[2] = (n >> 16) & 0xff; b[3] = (n >> 24) & 0xff; return b; }
+function writeU64LE(n) { const b = new Uint8Array(8); let v = BigInt(n); for (let i = 0; i < 8; i++) { b[i] = Number(v & 0xffn); v >>= 8n; } return b; }
+function concatBytes(...arrays) { const r = new Uint8Array(arrays.reduce((s, a) => s + a.length, 0)); let o = 0; for (const a of arrays) { r.set(a, o); o += a.length; } return r; }
+function reverseTxid(txid) { return hexToBytes(txid).reverse(); }
+
+function buildTransaction(input, outputs, privkeyBytes) {
+  const inputs = [input];
+  const internalXOnly = new Uint8Array(secp256k1.getPublicKey(privkeyBytes, true)).slice(1);
+  const untweakedHex = '5120' + bytesToHex(internalXOnly);
+  const needsTweak = bytesToHex(inputs[0].scriptPubKey) !== untweakedHex;
+  let signingKey = privkeyBytes;
+  if (needsTweak) {
+    const tweak = taggedHash('TapTweak', internalXOnly);
+    const t = bytesToBigInt(tweak);
+    let d = bytesToBigInt(privkeyBytes);
+    const fullPub = secp256k1.getPublicKey(privkeyBytes, false);
+    if (fullPub[64] & 1) d = SECP_N - d;
+    signingKey = bigIntToBytes((d + t) % SECP_N);
+  }
+
+  const version = 2, locktime = 0, sequence = 0xfffffffd;
+  const serOutputs = outputs.map(o =>
+    concatBytes(writeU64LE(o.amount), writeVarInt(o.scriptPubKey.length), o.scriptPubKey)
+  );
+
+  const shaPrevouts = sha256(concatBytes(...inputs.map(i => concatBytes(reverseTxid(i.txid), writeU32LE(i.vout)))));
+  const shaAmounts = sha256(concatBytes(...inputs.map(i => writeU64LE(i.amount))));
+  const shaScriptPubKeys = sha256(concatBytes(...inputs.map(i => concatBytes(writeVarInt(i.scriptPubKey.length), i.scriptPubKey))));
+  const shaSequences = sha256(concatBytes(...inputs.map(() => writeU32LE(sequence))));
+  const shaOutputs = sha256(concatBytes(...serOutputs));
+
+  const sigs = [];
+  for (let i = 0; i < inputs.length; i++) {
+    const sigMsg = concatBytes(
+      new Uint8Array([0x00, 0x00]),
+      writeU32LE(version), writeU32LE(locktime),
+      shaPrevouts, shaAmounts, shaScriptPubKeys, shaSequences, shaOutputs,
+      new Uint8Array([0x00]),
+      writeU32LE(i)
+    );
+    const sighash = taggedHash('TapSighash', sigMsg);
+    sigs.push(schnorr.sign(sighash, signingKey));
+  }
+
+  const parts = [
+    writeU32LE(version),
+    new Uint8Array([0x00, 0x01]),
+    writeVarInt(inputs.length)
+  ];
+  for (const inp of inputs) {
+    parts.push(reverseTxid(inp.txid), writeU32LE(inp.vout), new Uint8Array([0x00]), writeU32LE(sequence));
+  }
+  parts.push(writeVarInt(outputs.length));
+  for (const so of serOutputs) parts.push(so);
+  for (const sig of sigs) {
+    parts.push(new Uint8Array([0x01]), writeVarInt(sig.length), sig);
+  }
+  parts.push(writeU32LE(locktime));
+  return bytesToHex(concatBytes(...parts));
+}
+
+async function broadcastTx(rawHex, explorer) {
+  const resp = await fetch(`${explorer}/tx`, { method: 'POST', body: rawHex, headers: { 'Content-Type': 'text/plain' } });
+  if (!resp.ok) throw new Error(`Broadcast failed: ${await resp.text()}`);
+  return (await resp.text()).trim();
+}
+
+// --- Git helpers ---
+function gitExec(cmd) { return execSync(cmd, { encoding: 'utf8' }).trim(); }
+function getHead() { return gitExec('git rev-parse HEAD'); }
+function getPrivkey() {
+  try { return gitExec('git config nostr.privkey'); } catch { return null; }
+}
+function setPrivkey(key) { gitExec(`git config --local nostr.privkey ${key}`); }
+function isGitRoot() { return existsSync('.git'); }
+
+// --- Trail file helpers ---
+function loadTrail() {
+  if (!existsSync(TRAIL_FILE)) return null;
+  return JSON.parse(readFileSync(TRAIL_FILE, 'utf8'));
+}
+function saveTrail(trail) {
+  writeFileSync(TRAIL_FILE, JSON.stringify(trail, null, 2) + '\n');
+}
+function loadPrivateState() {
+  if (!existsSync(PRIVATE_FILE)) return null;
+  return JSON.parse(readFileSync(PRIVATE_FILE, 'utf8'));
+}
+function savePrivateState(state) {
+  writeFileSync(PRIVATE_FILE, JSON.stringify(state, null, 2) + '\n');
+}
+
+// --- Parse TXO URI ---
+function parseTxoUri(uri) {
+  const match = uri.match(/^txo:([^:]+):([a-f0-9]+):(\d+)/);
+  if (!match) throw new Error('Invalid TXO URI');
+  const params = new URLSearchParams(uri.split('?')[1] || '');
+  return { chain: match[1], txid: match[2], vout: parseInt(match[3]), amount: parseInt(params.get('amount')), key: params.get('key') };
+}
+
+// --- Commands ---
+async function cmdInit(args) {
+  if (!isGitRoot()) {
+    console.error('Error: .git/ not found in current directory. Run from a git repo root.');
+    process.exit(1);
+  }
+  if (existsSync(TRAIL_FILE) && !args.includes('--force')) {
+    console.error(`Error: ${TRAIL_FILE} already exists. Use --force to reinitialize.`);
+    process.exit(1);
+  }
+
+  // Chain
+  const chainIdx = args.indexOf('--chain');
+  const chain = chainIdx !== -1 ? args[chainIdx + 1] : DEFAULT_CHAIN;
+  if (!CHAINS[chain]) { console.error(`Unknown chain: ${chain}`); process.exit(1); }
+
+  // Key
+  let privkey = getPrivkey();
+  let keySource = 'git config';
+  if (!privkey) {
+    const sk = secp256k1.utils.randomPrivateKey();
+    privkey = bytesToHex(sk);
+    setPrivkey(privkey);
+    keySource = 'generated';
+  }
+  const pubkey = bytesToHex(secp256k1.getPublicKey(hexToBytes(privkey), true));
+
+  // Create trail
+  const trail = {
+    version: '0.0.3',
+    profile: 'gitmark',
+    publicKeyBase: pubkey,
+    chain,
+    states: [],
+    txo: []
+  };
+
+  // Voucher funding
+  const voucherIdx = args.indexOf('--voucher');
+  if (voucherIdx !== -1) {
+    const voucherUri = args[voucherIdx + 1];
+    const txo = parseTxoUri(voucherUri);
+    if (!txo.key) { console.error('Voucher must include &key= parameter'); process.exit(1); }
+    if (!txo.amount) { console.error('Voucher must include &amount= parameter'); process.exit(1); }
+
+    const voucherKey = hexToBytes(txo.key);
+    const baseXonly = hexToBytes(pubkey).slice(1);
+    const baseScript = p2trScript(baseXonly);
+
+    // Fetch voucher scriptPubKey
+    const explorer = CHAINS[chain].explorer;
+    const txResp = await fetch(`${explorer}/tx/${txo.txid}`);
+    if (!txResp.ok) { console.error('Could not fetch voucher transaction'); process.exit(1); }
+    const txData = await txResp.json();
+    const prevOut = txData.vout?.[txo.vout];
+    if (!prevOut) { console.error(`Voucher output ${txo.vout} not found`); process.exit(1); }
+
+    const fee = 300;
+    const outputAmount = txo.amount - fee;
+    if (outputAmount <= 546) { console.error('Voucher too small'); process.exit(1); }
+
+    const rawTx = buildTransaction(
+      { txid: txo.txid, vout: txo.vout, amount: txo.amount, scriptPubKey: hexToBytes(prevOut.scriptpubkey) },
+      [{ amount: outputAmount, scriptPubKey: baseScript }],
+      voucherKey
+    );
+    const newTxid = await broadcastTx(rawTx, explorer);
+
+    savePrivateState({ txid: newTxid, vout: 0, amount: outputAmount });
+    console.log(`Funded: ${outputAmount} sats (txid: ${newTxid})`);
+  }
+
+  saveTrail(trail);
+
+  console.log(`Initialized gitmark trail: ${TRAIL_FILE}`);
+  console.log(`Key source: ${keySource}`);
+  console.log(`Base public key: ${pubkey}`);
+  console.log(`Chain: ${chain}`);
+  console.log(`Address: ${pubkeyToAddress(pubkey, [], chain)}`);
+  if (!existsSync(PRIVATE_FILE) && voucherIdx === -1) {
+    console.log(`\nUnfunded. Use: git mark init --voucher txo:${chain}:txid:vout?amount=X&key=Y`);
+    console.log(`Or send sats to: ${pubkeyToAddress(pubkey, [], chain)}`);
+  }
+}
+
+async function cmdMark(args) {
+  const trail = loadTrail();
+  if (!trail) { console.error(`No ${TRAIL_FILE} found. Run: git mark init`); process.exit(1); }
+  const priv = loadPrivateState();
+  if (!priv) { console.error('No funding. Run: git mark init --voucher txo:...'); process.exit(1); }
+
+  const privkey = getPrivkey();
+  if (!privkey) { console.error('No private key. Set: git config nostr.privkey <hex>'); process.exit(1); }
+
+  const head = getHead();
+  const chain = trail.chain;
+  const explorer = CHAINS[chain]?.explorer;
+  if (!explorer) { console.error(`Unknown chain: ${chain}`); process.exit(1); }
+
+  // All previous states + current commit
+  const prevStates = [...trail.states];
+  const allStates = [...prevStates, head];
+
+  // Derive signing key (chained through previous states)
+  const signingKey = prevStates.length > 0
+    ? deriveChainedPrivkey(hexToBytes(privkey), prevStates)
+    : hexToBytes(privkey);
+
+  // Derive next address (chained through all states including current)
+  const nextPub = deriveChainedPubkey(hexToBytes(trail.publicKeyBase), allStates);
+  const nextXonly = nextPub.slice(1);
+  const nextScript = p2trScript(nextXonly);
+
+  // Fetch current UTXO scriptPubKey
+  const txResp = await fetch(`${explorer}/tx/${priv.txid}`);
+  if (!txResp.ok) { console.error('Could not fetch current UTXO'); process.exit(1); }
+  const txData = await txResp.json();
+  const prevOut = txData.vout?.[priv.vout];
+  if (!prevOut) { console.error('Current UTXO not found'); process.exit(1); }
+
+  const fee = 300;
+  const outputAmount = priv.amount - fee;
+  if (outputAmount <= 546) { console.error('Trail UTXO too small. Fund with: git mark init --voucher ...'); process.exit(1); }
+
+  const rawTx = buildTransaction(
+    { txid: priv.txid, vout: priv.vout, amount: priv.amount, scriptPubKey: hexToBytes(prevOut.scriptpubkey) },
+    [{ amount: outputAmount, scriptPubKey: nextScript }],
+    signingKey
+  );
+  const newTxid = await broadcastTx(rawTx, explorer);
+
+  // Update trail
+  trail.states.push(head);
+  trail.txo.push(`txo:${chain}:${newTxid}:0?commit=${head}`);
+  saveTrail(trail);
+
+  // Update private state
+  savePrivateState({ txid: newTxid, vout: 0, amount: outputAmount });
+
+  const address = pubkeyToAddress(trail.publicKeyBase, allStates, chain);
+  console.log(`Marked: ${head.slice(0, 8)} → ${newTxid.slice(0, 16)}...`);
+  console.log(`Address: ${address}`);
+  console.log(`Balance: ${outputAmount} sats`);
+  console.log(`TXO: txo:${chain}:${newTxid}:0?commit=${head}`);
+}
+
+async function cmdInfo() {
+  const trail = loadTrail();
+  if (!trail) { console.error(`No ${TRAIL_FILE} found.`); process.exit(1); }
+  const priv = loadPrivateState();
+
+  console.log(`Profile: ${trail.profile}`);
+  console.log(`Version: ${trail.version}`);
+  console.log(`Chain: ${trail.chain}`);
+  console.log(`Base public key: ${trail.publicKeyBase}`);
+  console.log(`Base address: ${pubkeyToAddress(trail.publicKeyBase, [], trail.chain)}`);
+  console.log(`Marks: ${trail.states.length}`);
+  if (trail.states.length > 0) {
+    const currentAddr = pubkeyToAddress(trail.publicKeyBase, trail.states, trail.chain);
+    console.log(`Current address: ${currentAddr}`);
+    console.log(`Last commit: ${trail.states[trail.states.length - 1]}`);
+    console.log(`Last TXO: ${trail.txo[trail.txo.length - 1]}`);
+  }
+  if (priv) {
+    console.log(`Balance: ${priv.amount} sats`);
+  } else {
+    console.log('Balance: unfunded');
+  }
+}
+
+async function cmdVerify() {
+  const trail = loadTrail();
+  if (!trail) { console.error(`No ${TRAIL_FILE} found.`); process.exit(1); }
+  if (trail.states.length === 0) { console.log('No marks to verify.'); return; }
+
+  const chain = CHAINS[trail.chain];
+  if (!chain) { console.error(`Unknown chain: ${trail.chain}`); process.exit(1); }
+
+  console.log(`Verifying ${trail.states.length} mark(s)...`);
+  let ok = true;
+
+  for (let i = 0; i < trail.states.length; i++) {
+    const statesUpTo = trail.states.slice(0, i + 1);
+    const expectedAddr = pubkeyToAddress(trail.publicKeyBase, statesUpTo, trail.chain);
+    const txoUri = trail.txo[i];
+    const parsed = parseTxoUri(txoUri);
+
+    try {
+      const resp = await fetch(`${chain.explorer}/tx/${parsed.txid}`);
+      if (!resp.ok) { console.log(`  [${i}] FAIL — tx not found: ${parsed.txid.slice(0, 16)}...`); ok = false; continue; }
+      const txData = await resp.json();
+      const out = txData.vout?.[parsed.vout];
+      if (!out) { console.log(`  [${i}] FAIL — output ${parsed.vout} not found`); ok = false; continue; }
+      if (out.scriptpubkey_address === expectedAddr) {
+        console.log(`  [${i}] OK — ${trail.states[i].slice(0, 8)} → ${expectedAddr.slice(0, 20)}...`);
+      } else {
+        console.log(`  [${i}] FAIL — address mismatch`);
+        console.log(`    expected: ${expectedAddr}`);
+        console.log(`    got:      ${out.scriptpubkey_address}`);
+        ok = false;
+      }
+    } catch (e) {
+      console.log(`  [${i}] ERROR — ${e.message}`);
+      ok = false;
+    }
+  }
+
+  console.log(ok ? '\nAll marks verified.' : '\nVerification failed.');
+  process.exit(ok ? 0 : 1);
+}
+
+// --- CLI ---
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (cmd === 'init') {
+  cmdInit(args.slice(1));
+} else if (cmd === 'info') {
+  cmdInfo();
+} else if (cmd === 'verify') {
+  cmdVerify();
+} else if (cmd === 'mark' || !cmd || (cmd && !cmd.startsWith('-'))) {
+  // Default action is mark (git mark = git mark mark)
+  // But if no trail exists, suggest init
+  if (!existsSync(TRAIL_FILE) && cmd !== 'mark') {
+    console.log('Usage:');
+    console.log('  git mark init [--chain tbtc4] [--voucher txo:...]');
+    console.log('  git mark                  # anchor HEAD to Bitcoin');
+    console.log('  git mark info             # show trail state');
+    console.log('  git mark verify           # verify trail against Bitcoin');
+  } else {
+    cmdMark(args.slice(cmd === 'mark' ? 1 : 0));
+  }
+} else {
+  console.log('Usage:');
+  console.log('  git mark init [--chain tbtc4] [--voucher txo:...]');
+  console.log('  git mark                  # anchor HEAD to Bitcoin');
+  console.log('  git mark info             # show trail state');
+  console.log('  git mark verify           # verify trail against Bitcoin');
+}

package/index.html

@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>git mark — Anchor Git Commits to Bitcoin</title>
+  <meta name="description" content="Mark your git commits on Bitcoin using blocktrails key chaining. Tamper-proof history, globally verifiable, two dependencies.">
+  <meta property="og:title" content="git mark — Anchor Git Commits to Bitcoin">
+  <meta property="og:description" content="Mark your git commits on Bitcoin using blocktrails key chaining. Tamper-proof history, globally verifiable.">
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="https://git-mark.com">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: Georgia, 'Times New Roman', serif; background: #fafaf8; color: #2c2c2c; line-height: 1.7; padding: 2rem; }
+    .container { max-width: 720px; margin: 0 auto; }
+    h1 { font-size: 2.2rem; font-weight: 400; margin-bottom: 0.25rem; }
+    .subtitle { color: #666; font-size: 1.1rem; margin-bottom: 0.5rem; }
+    .meta { color: #999; font-size: 0.85rem; margin-bottom: 2rem; padding-bottom: 1.5rem; border-bottom: 1px solid #ddd; }
+    .meta a { color: #999; }
+    h2 { font-size: 1.3rem; color: #f7931a; margin: 2.5rem 0 1rem; font-weight: 600; }
+    p { margin-bottom: 1.25rem; }
+    code { background: #f0efeb; padding: 0.15rem 0.4rem; border-radius: 3px; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 0.85em; color: #555; }
+    pre { background: #f0efeb; padding: 1rem; border-radius: 4px; overflow-x: auto; font-family: 'SFMono-Regular', Consolas, monospace; font-size: 0.85rem; margin: 1.25rem 0; line-height: 1.5; }
+    a { color: #1a5276; }
+    strong { font-weight: 600; }
+    table { width: 100%; border-collapse: collapse; margin: 1.5rem 0; font-size: 0.9rem; }
+    th { text-align: left; padding: 0.6rem 0.75rem; border-bottom: 2px solid #ddd; color: #888; font-weight: 500; }
+    td { padding: 0.5rem 0.75rem; border-bottom: 1px solid #eee; }
+    .highlight { color: #f7931a; font-weight: 600; }
+    .callout { background: #fff8f0; border: 1px solid #f7931a33; border-radius: 4px; padding: 1.25rem; margin: 1.5rem 0; }
+    .callout .label { font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.1em; color: #f7931a; margin-bottom: 0.5rem; }
+    footer { margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid #ddd; color: #999; font-size: 0.85rem; }
+    footer a { color: #888; }
+  </style>
+</head>
+<body>
+  <div class="container">
+
+    <h1>git mark</h1>
+    <div class="subtitle">Anchor git commits to Bitcoin via blocktrails</div>
+    <div class="meta">
+      <a href="https://github.com/solidpayorg/gitmark">GitHub</a> &middot;
+      <a href="https://www.npmjs.com/package/gitmark">npm</a> &middot;
+      <a href="https://blocktrails.org">blocktrails.org</a>
+    </div>
+
+    <h2>What It Does</h2>
+
+    <p><span class="highlight">Every <code>git mark</code> creates a Bitcoin transaction</span> 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.</p>
+
+    <p>The result is a two-way link: the blockchain follows your repo (via tweaked addresses), and your repo follows the blockchain (via <code>blocktrails.json</code>).</p>
+
+    <h2>Install</h2>
+
+<pre>npm install -g gitmark</pre>
+
+    <p>This gives you <code>git mark</code> as a native git subcommand.</p>
+
+    <h2>Quick Start</h2>
+
+<pre># Initialize in a git repo
+git mark init --chain tbtc4 --voucher txo:tbtc4:txid:vout?amount=X&amp;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</pre>
+
+    <h2>How It Works</h2>
+
+    <table>
+      <tr><th>Step</th><th>What Happens</th></tr>
+      <tr><td>Init</td><td>Generates or reads your Nostr key, creates <code>blocktrails.json</code>, optionally funds the trail</td></tr>
+      <tr><td>Mark</td><td>Takes HEAD commit hash, derives a tweaked taproot address via BIP-341, builds and broadcasts a Bitcoin transaction</td></tr>
+      <tr><td>Verify</td><td>Walks the trail, re-derives each address from the public key + commit hashes, checks each transaction on Bitcoin</td></tr>
+    </table>
+
+    <p>Each mark advances the key chain: <code>newKey = baseKey + tweak(commit_hash)</code>. The chain of derived addresses on Bitcoin mirrors the chain of commits in git.</p>
+
+    <h2>The Trail File</h2>
+
+    <p><code>blocktrails.json</code> lives in your repo root, committed and visible:</p>
+
+<pre>{
+  "version": "0.0.3",
+  "profile": "gitmark",
+  "publicKeyBase": "02abc...",
+  "chain": "tbtc4",
+  "states": ["a1b2c3...", "e5f6a7..."],
+  "txo": [
+    "txo:tbtc4:abc:0?commit=a1b2c3...",
+    "txo:tbtc4:def:0?commit=e5f6a7..."
+  ]
+}</pre>
+
+    <p><strong>states</strong> — the commit hashes (input to key chaining math). <strong>txo</strong> — the Bitcoin anchors (TXO URIs, self-contained and verifiable). Anyone who clones your repo can verify the trail independently.</p>
+
+    <h2>Key Storage</h2>
+
+    <p>Your private key is stored in git config:</p>
+
+<pre>git config nostr.privkey &lt;64-char-hex&gt;</pre>
+
+    <p>The same secp256k1 key you use for Nostr, Bitcoin, and Solid pod authentication. One key for everything.</p>
+
+    <div class="callout">
+      <div class="label">Blocktrails</div>
+      <p style="margin-bottom: 0.75rem">Git-mark is a <a href="https://blocktrails.org">blocktrails</a> application profile. The key chaining math is identical to <a href="https://blocktrails.org">MRC20 tokens</a> — just with commit hashes as state instead of token ledgers. A generic blocktrails verifier handles both.</p>
+      <p style="margin-bottom: 0">Two dependencies: <code>@noble/curves</code> and <code>@noble/hashes</code>. No bitcoinjs-lib. No external transaction builders. Pure secp256k1 math.</p>
+    </div>
+
+    <h2>Commands</h2>
+
+    <table>
+      <tr><th>Command</th><th>Description</th></tr>
+      <tr><td><code>git mark init</code></td><td>Initialize trail. Options: <code>--chain</code>, <code>--voucher</code>, <code>--force</code></td></tr>
+      <tr><td><code>git mark</code></td><td>Anchor HEAD commit to Bitcoin</td></tr>
+      <tr><td><code>git mark info</code></td><td>Show trail state, balance, addresses</td></tr>
+      <tr><td><code>git mark verify</code></td><td>Verify all marks against Bitcoin</td></tr>
+    </table>
+
+    <h2>Related</h2>
+
+    <p>
+      <a href="https://blocktrails.org">Blocktrails</a> &mdash; state anchoring on Bitcoin<br>
+      <a href="https://github.com/nicepkg/gitmark-test">gitmark-test</a> &mdash; interim implementation<br>
+      <a href="https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki">BIP-341</a> &mdash; Taproot key tweaking
+    </p>
+
+    <footer>
+      <p>&copy; 2026 <a href="https://melvin.me">Melvin Carvalho</a> &middot; MIT License &middot; <a href="https://github.com/solidpayorg/gitmark">Source</a></p>
+    </footer>
+
+  </div>
+</body>
+</html>

package/package.json

@@ -1,40 +1,34 @@
 {
   "name": "gitmark",
-  "version": "0.0.68",
-  "description": "gitmark",
-  "main": "index.js",
+  "version": "0.0.70",
+  "type": "module",
+  "description": "Anchor git commits to Bitcoin via blocktrails",
+  "main": "bin/git-mark.js",
+  "bin": {
+    "git-mark": "bin/git-mark.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node bin/git-mark.js --help"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/solidpayorg/gitmark.git"
   },
   "keywords": [
-    "gitmark"
+    "gitmark",
+    "blocktrails",
+    "bitcoin",
+    "git",
+    "nostr"
   ],
-  "bin": {
-    "git-mark": "bin/git-mark",
-    "git-mark-init": "bin/git-mark-init",
-    "git-mark-list": "bin/git-mark-list",
-    "git-mark-verify": "bin/git-mark-verify"
-  },
   "author": "Melvin Carvalho",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/solidpayorg/gitmark/issues"
   },
-  "homepage": "https://github.com/solidpayorg/gitmark#readme",
+  "homepage": "https://git-mark.com",
   "dependencies": {
-    "bip-schnorr": "^0.6.4",
-    "bitcoinjs-lib": "^5.2.0",
-    "child_process": "^1.0.2",
-    "fs": "^0.0.1-security",
-    "gitlog": "^4.0.4",
-    "gitmark": "^0.0.56",
-    "minimist": "^1.2.5",
-    "sha256": "^0.2.0",
-    "tiny-secp256k1": "^1.1.6",
-    "ws": "^8.2.3"
+    "@noble/curves": "^1.2.0",
+    "@noble/hashes": "^1.3.0"
   }
-}
+}