MDL – Markdown Logged

A document is not trusted because it cannot be changed, but because any change is detectable.

MDL is a lightweight, cryptographically verifiable document format built on top of Markdown.
It wraps any .md file in an immutable proof layer — without breaking human readability.

---

Features

Feature	Description
Immutable-by-proof	Any modification is cryptographically detectable
Human-readable	Plain text, no binary blobs
Modular	Each proof layer is independent and optional
Offline-first	Core functionality needs no network
Extendable	Blockchain anchoring, RFC3161 timestamps planned for v2

---

Proof Layers

CONTENT
  └── SHA-256 hash          (Level 0 – tamper detection)
  └── Local entropy         (Level 1 – non-reproducible timestamp)
  └── Market anchor         (Level 2 – global state snapshot via Yahoo Finance)
  └── Ed25519 signature     (Level 3 – identity binding, optional)

---

Installation

Python 3.10+ required.

pip install -r requirements.txt

---

Usage

Generate a keypair (once)

python cli.py keygen --out ./keys

Creates keys/mdl_private.hex and keys/mdl_public.hex.

Create an MDL document

# Without signature
python cli.py create document.md document.mdl

# With Ed25519 signature
python cli.py create document.md document.mdl --sign ./keys/mdl_private.hex

Verify an MDL document

# Hash + entropy + market only
python cli.py verify document.mdl

# Including signature verification
python cli.py verify document.mdl --pubkey ./keys/mdl_public.hex

Inspect metadata

python cli.py info document.mdl

---

File Format

An .mdl file is a plain UTF-8 text file:

--- MDL HEADER v1 ---
{
  "version": "1.0",
  "created_at": "2026-03-29T12:00:00Z",
  "modules": ["hash", "local_entropy", "market_anchor_v1", "signature"],
  "proof": {
    "hash": "<sha256 hex>",
    "local_entropy": { "system_time_utc": "...", "monotonic_ns": ..., "random_nonce": "..." },
    "market_anchor_v1": { "canonical_string": "...", "hash": "...", "indices": { ... } },
    "signature": { "algorithm": "ed25519", "value": "<hex>" }
  }
}

--- CONTENT ---
# Your Markdown here
...

Rules:

• The hash is computed over the raw bytes of the CONTENT section only (header excluded).
• UTF-8 encoding is mandatory.
• No whitespace normalization.

---

Verification Levels

Level	Modules present	Trust model
0	hash	Tamper detection
1	+ local_entropy	Non-reproducible timestamp
2	+ market_anchor_v1	Global context (financial state)
3	+ signature	Identity binding
4	+ blockchain (v2)	Absolute time proof

---

Repository Structure

mdl/
├── mdl/
│   ├── __init__.py
│   ├── core.py          # Proof orchestration
│   ├── parser.py        # .mdl file parsing
│   ├── writer.py        # .mdl file assembly
│   ├── verifier.py      # Verification engine
│   └── modules/
│       ├── hash.py      # SHA-256 module
│       ├── entropy.py   # Local entropy module
│       ├── market.py    # Market anchor module (Yahoo Finance)
│       └── signature.py # Ed25519 signature module
├── cli.py               # Command line interface
├── requirements.txt
├── examples/
│   ├── example.md
│   └── example.mdl
└── specs/
    └── MDL_v1.md

---

Roadmap

• SHA-256 hash module
• Local entropy module
• Market anchor module (Yahoo Finance)
• Ed25519 digital signatures
• Blockchain anchoring (OpenTimestamps / Bitcoin)
• RFC3161 trusted timestamps
• Web viewer (Streamlit MVP)
• MDL v1.1 formal specification (BNF grammar)
• PyPI package

---

Philosophy

MDL is an open trust layer for text.

It does not prevent modification — it makes any modification immediately detectable.
The proof is embedded in the file itself, requires no server, and remains readable by humans.

---

License

Apache 2.0