Blockchain Commons Provenance Mark CLI (TypeScript)

> Disclaimer: This package is under active development and APIs may change.

Introduction

@bcts/provenance-mark-cli is a command line tool for creating and managing Provenance Mark chains.

Provenance Marks are cryptographically-secured markers that establish authenticity and provenance of digital works. They form chains where each mark references the previous one, creating an unforgeable timeline.

Features:
- Create new provenance mark chains with a genesis mark
- Add new marks to existing chains
- Print marks in publishable formats (Markdown, UR, JSON)
- Validate provenance mark chains for integrity
- Support for multiple resolution levels (low, medium, quartile, high)

Rust Reference Implementation

This TypeScript implementation is based on provenance-mark-cli-rust v0.6.0 (commit).

Installation

``bash


Install globally

bun add -g @bcts/provenance-mark-cli

Or run directly with bunx

bunx @bcts/provenance-mark-cli --help
`

Usage

$3

`bash


Create a new provenance mark chain

provenance new mychain

Create with a specific resolution

provenance new mychain --resolution high

Create with a custom comment

provenance new mychain --comment "Genesis mark for my project"

Create with a specific seed (base64)

provenance new mychain --seed "base64encodedSeed=="
`

Output:
`
Provenance mark chain created at: /path/to/mychain

Mark 0 written to: /path/to/mychain/marks/mark-0.json

---

2025-01-27T21:59:52Z

#### ur:provenance/lfaohdft...

#### 🅟 PLAY WASP FLUX SWAN

🅟 💎 🦄 🍓 🧢

Genesis mark.
`

$3

`bash


Add next mark to the chain

provenance next mychain --comment "New release v1.0"

Output as UR only

provenance next mychain --format ur --quiet

Output as JSON

provenance next mychain --format json
`

$3

`bash


Print all marks in the chain

provenance print mychain

Print specific range

provenance print mychain --start 0 --end 5

Print only the genesis mark

provenance print mychain --start 0 --end 0
`

$3

`bash


Validate a chain directory

provenance validate --dir mychain

Validate specific URs

provenance validate ur:provenance/... ur:provenance/...

Validate with warnings instead of errors

provenance validate --warn --dir mychain
`

Directory Structure

When you create a new chain, the following structure is created:

`
mychain/
├── generator.json # Chain state (KEEP SECRET!)
└── marks/
├── mark-0.json # Genesis mark
├── mark-1.json # Second mark
└── ...
`

Important: The generator.json file contains the seed and must be kept secret. If compromised, an attacker could forge marks in your chain.

Command Line Reference

`
Usage: provenance [options] [command]

Commands:
new

Create a new provenance mark chain
next Generate the next mark in a chain
print Print marks from a chain
validate Validate provenance marks

new Options:
--seed Seed for the chain (default: random)
--resolution Resolution: low, medium, quartile, high (default: quartile)
--comment Comment for genesis mark

next Options:
--comment Comment for the new mark
--format Output format: markdown, ur, json (default: markdown)
--quiet Suppress status messages

print Options:
--start First mark to print (default: 0)
--end Last mark to print (default: last)

validate Options:
--dir Validate all marks in directory
--warn Warn instead of error on issues

Global Options:
-h, --help Display help
-V, --version Display version
`

Mark Formats

Each mark includes:
- UR: Complete data structure in Uniform Resource format
- Bytewords: Human-readable identifier (e.g., 🅟 PLAY WASP FLUX SWAN)
- Bytemoji: Emoji identifier (e.g., 🅟 💎 🦄 🍓 🧢`)
- Comment: Optional descriptive text