Etch

Content provenance on a tamper-evident Merkle chain. Register, verify, and prove content existed at a point in time.

pip install etch-provenance   # imports as `etch`

Why Etch?

C2PA embeds provenance in media files. Blockchain attestation services cost gas and take minutes. Etch gives you cryptographic content provenance with a single HTTP call — sub-millisecond, privacy-preserving (content is never stored), and independently verifiable.

Quick start

Start the server

# SQLite (zero config) — serves on :8100
uvicorn etch.server:app --reload --port 8100

# PostgreSQL
ETCH_DATABASE_URL=postgresql+asyncpg://user:pass@localhost/etch uvicorn etch.server:app --port 8100

Interactive API docs: http://localhost:8100/docs (OpenAPI schema at /openapi.json).

Register content

curl -X POST http://localhost:8100/v1/proof \
  -H "Content-Type: application/json" \
  -d '{"content": "My original article text", "label": "Blog: Launch Day"}'

Response:

{
  "proof_id": 0,
  "content_hash": "a3f1...",
  "label": "Blog: Launch Day",
  "timestamp": 1710000000.0,
  "leaf_hash": "...",
  "mmr_root": "...",
  "chain_depth": 1
}

Verify content

curl -X POST http://localhost:8100/v1/proof/0/verify \
  -H "Content-Type: application/json" \
  -d '{"content": "My original article text"}'

Privacy mode (hash only)

# Pre-hash locally — content never leaves your machine
HASH=$(echo -n "secret document" | sha256sum | cut -d' ' -f1)
curl -X POST http://localhost:8100/v1/proof \
  -H "Content-Type: application/json" \
  -d "{\"content_hash\": \"$HASH\"}"

The two chains

Etch exposes one primitive through two front doors:

Everything else (/v1/c2pa, /v1/dooh, /v1/assent, /g/, watermark) is a domain-specific façade over one of those two.

API

/v1/proof/* — legacy registration (no auth)

/v1/records/* — System of Record API (API key, namespace-isolated)

Keys look like etch_{live|test}_sk_{token} and are sent as Authorization: Bearer …. Only the SHA-256 of a key is stored. Provision the first namespace and key with:

from etch.auth import bootstrap_namespace
namespace_id, api_key = await bootstrap_namespace("acme-crm")

curl -X POST http://localhost:8100/v1/records \
  -H "Authorization: Bearer etch_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
        "record": {"type": "salesforce.opportunity", "id": "0065g00000XYZ", "data": {"stage": "Closed Won"}},
        "metadata": {"actor": "sync-job"},
        "if_changed": true
      }'

if_changed is opt-in de-duplication. With record.id set, Etch looks up the latest record for that (namespace, external_id, record_type); if the record_hash is unchanged it returns the existing receipt with "deduplicated": true and appends nothing. It defaults to false on purpose — the chain is append-only and re-registering unchanged content is a legitimate timestamped re-attestation, so nothing is ever silently suppressed.

/v1/c2pa/* — C2PA manifest bridge (no auth)

/v1/dooh/* — DOOH playback receipts (API key)

Bilaterally-signed proof that a creative played on a specific screen at a specific time.

SDK and quickstart: etch/dooh/README.md. Protocol: docs/dooh-spec.md (CC-BY 4.0) — read the trust model first.

/v1/assent/* — Etch Assent (anonymous, rate-limited)

Client-side PDF signing with an anonymous provenance chain. Plaintext PDFs are encrypted in the browser with AES-256-GCM; the key lives in the URL fragment, which browsers never transmit, so Etch cannot decrypt what it stores.

Product + protocol spec: docs/ETCH_ASSENT_SPEC.md. Frontend lives in assent-app/ and builds to site/assent/.

Assent MCP server: an agent asks a human to sign. Three tools. request_signature takes plain text, which it renders to a one-page sign-off PDF, or a path to an existing PDF. It encrypts the document on the agent's machine, uploads only the ciphertext, stamps the plaintext hash as event 0, and returns a sign_url that opens in the normal Assent Sign page. The agent delivers the link itself. The key exists only in that URL and in a 0600 file under ~/.etch/assent/requests/. signature_status reads the public chain and reports one of sent, opened, signing, or finalized. It also flags a signer who was shown different bytes from what was sent. fetch_signed downloads the signed copy, decrypts it locally, saves it only if its SHA-256 equals the chain's finalized hash, and recomputes the inclusion proof.

pip install "etch-provenance[mcp]"
claude mcp add etch-assent -- etch-assent-mcp

Set ETCH_ASSENT_BASE_URL (default https://assent.to) to change the link host, or ETCH_ASSENT_API_URL to send API calls somewhere else, such as a local server.

Glyph — shortcodes, sigils, and the public resolver

A shortcode is 8 Crockford-base32 characters encoding a 32-bit proof_id plus an 8-bit checksum over the content hash, so typos and fabrications are detectable before a DB lookup.

Watermark (etchmark) — inaudible audio pointer

Embed returns lossless WAV; the spread-spectrum layer survives the artist's own lossy re-encode. Extraction reads WAV/FLAC natively and MP3/AAC/Opus via ffmpeg if it's on PATH.

The watermark is a pointer, not a proof. It tells a verifier which Etch record claims a recording; the chain remains the only source of truth. The PRNG seed is public by design.

Other

How it works

Etch uses a Merkle Mountain Range (MMR) hash chain. Each proof receipt commits to all previous entries:

payload_hash = SHA256(payload_json)          # payload_json names the content hash
leaf_hash    = SHA256(prev_root : action_type : payload_hash : timestamp)
mmr_root     = SHA256(prev_root : leaf_hash)

Every proof returns payload_json, the exact bytes payload_hash was computed over. Check that it hashes to payload_hash and that its record_hash (or content_hash) is the SHA-256 of your content. That ties the proof to your content, not just to some leaf. The SDK's InclusionProof.verify(record_hash=...) runs all four steps.

If any historical entry is tampered with, all subsequent hashes become invalid. Proofs can be verified offline — no server trust required. The chain is append-only: nothing is ever deleted or compacted.

As a library

from etch import AuditChain, verify_inclusion_proof

chain = AuditChain()
entry = chain.append("content_proof", {"content_hash": "a3f1..."})

proof = chain.generate_proof(entry.leaf_index)
assert verify_inclusion_proof(proof)  # offline verification

Python SDK

from etch import EtchClient

async with EtchClient(base_url="http://localhost:8100", api_key="etch_live_sk_…") as etch:
    receipt = await etch.records.create(
        record_type="invoice",
        record_id="INV-1001",
        data={"total": 4200},
        if_changed=True,
    )
    result = await etch.records.verify(receipt.id, data={"total": 4200})

EtchClient.register() / .verify() still target the legacy /v1/proof API and are deprecated in favour of .records.

Configuration

Optional extras: pip install "etch-provenance[postgres]" (asyncpg), "etch-provenance[qr]" (QR sigils), "etch-provenance[mcp]", "etch-provenance[dev]", "etch-provenance[all]".

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest                      # asyncio_mode = auto
ruff check etch/ tests/     # line-length 120, py311

uvicorn etch.server:app --reload --port 8100

cd assent-app && npm install && npm run dev   # Assent frontend

Release procedure: docs/RELEASING.md.

License

Rising Sun License v1.0. Free for personal use. Commercial deployments connect to the Nous network.

The DOOH SDK (etch/dooh/) is Apache-2.0; the DOOH spec is CC-BY 4.0.