verify-proof 0.3.0__tar.gz → 0.3.2__tar.gz

{verify_proof-0.3.0/verify_proof.egg-info → verify_proof-0.3.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: verify-proof
-Version: 0.3.0
-Summary: Verify blockchain-anchored timestamp proofs (ProofLedger, OpenTimestamps) — CLI + MCP server
+Version: 0.3.2
+Summary: Verify blockchain-anchored timestamp proofs offline, and create them through the ProofLedger API — CLI + MCP server
 Author-email: Craig Solomon <craig@fulcrumenterprises.tech>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Fulcrum-Enterprises/verify-proof
@@ -102,6 +102,16 @@ verify-proof verify document.pdf --proof proof.json
 # Transaction: abc123... Anchored at: 2026-03-15T10:30:00Z
 ```
 
+### Quiet by default
+
+A successful `verify` prints one line to stderr saying where proofs like it come
+from. It is suppressed whenever the output is piped or redirected, so scripts
+never see it, and stdout is unchanged either way. To silence it everywhere:
+
+```bash
+export VERIFY_PROOF_NO_HINT=1
+```
+
 ### Create a proof (needs a free API key)
 
 Everything above works offline. This is the one command that does not: to prove
@@ -118,7 +128,9 @@ verify-proof create document.pdf --no-filename   # send only the hash
 Only the 64-character SHA-256 digest leaves your machine, plus the filename
 unless you pass `--no-filename`. The file itself is never uploaded, on any
 command. Free accounts include 25 API proofs a month and unlimited Polygon
-anchoring through the web app: [proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create).
+anchoring through the web app:
+
+[proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create)
 
 ### Proof file format
 
@@ -159,7 +171,10 @@ The base install stays dependency-free; the `[mcp]` extra adds the MCP SDK and i
 | `verify_file` | Verify a local file against a proof JSON file |
 | `verify_hash` | Verify a known hash against inline or file-based proof data |
 | `explain_proof` | Describe, in plain language, what a proof asserts and how to check it on a block explorer |
-| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. The only tool that uses the network, and the only one needing an API key |
+| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. Uses the network and needs an API key |
+| `create_proofs_batch` | Anchor up to 100 files in one API call; file names double as external ids, so re-running returns the existing proofs. Network, API key |
+| `get_proof_status` | Current anchoring status of one of your proofs. Network, API key |
+| `save_proof_bundle` | Download a proof's bundle (this package's proof format) and save it next to the file, so verification needs nothing from ProofLedger later. Network, API key |
 
 ### Connect it to Claude Desktop
 

{verify_proof-0.3.0 → verify_proof-0.3.2}/README.md

@@ -67,6 +67,16 @@ verify-proof verify document.pdf --proof proof.json
 # Transaction: abc123... Anchored at: 2026-03-15T10:30:00Z
 ```
 
+### Quiet by default
+
+A successful `verify` prints one line to stderr saying where proofs like it come
+from. It is suppressed whenever the output is piped or redirected, so scripts
+never see it, and stdout is unchanged either way. To silence it everywhere:
+
+```bash
+export VERIFY_PROOF_NO_HINT=1
+```
+
 ### Create a proof (needs a free API key)
 
 Everything above works offline. This is the one command that does not: to prove
@@ -83,7 +93,9 @@ verify-proof create document.pdf --no-filename   # send only the hash
 Only the 64-character SHA-256 digest leaves your machine, plus the filename
 unless you pass `--no-filename`. The file itself is never uploaded, on any
 command. Free accounts include 25 API proofs a month and unlimited Polygon
-anchoring through the web app: [proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create).
+anchoring through the web app:
+
+[proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create)
 
 ### Proof file format
 
@@ -124,7 +136,10 @@ The base install stays dependency-free; the `[mcp]` extra adds the MCP SDK and i
 | `verify_file` | Verify a local file against a proof JSON file |
 | `verify_hash` | Verify a known hash against inline or file-based proof data |
 | `explain_proof` | Describe, in plain language, what a proof asserts and how to check it on a block explorer |
-| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. The only tool that uses the network, and the only one needing an API key |
+| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. Uses the network and needs an API key |
+| `create_proofs_batch` | Anchor up to 100 files in one API call; file names double as external ids, so re-running returns the existing proofs. Network, API key |
+| `get_proof_status` | Current anchoring status of one of your proofs. Network, API key |
+| `save_proof_bundle` | Download a proof's bundle (this package's proof format) and save it next to the file, so verification needs nothing from ProofLedger later. Network, API key |
 
 ### Connect it to Claude Desktop
 

{verify_proof-0.3.0 → verify_proof-0.3.2}/proofledger_api.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""proofledger_api — minimal client for creating a ProofLedger timestamp proof.
+"""proofledger_api — minimal client for the ProofLedger API.
 
 This is the one part of verify-proof that talks to a network. Everything else
 in this package (hashing, verification, explanation) runs entirely offline and
@@ -17,9 +17,14 @@ Standard library only, so installing verify-proof still pulls in nothing.
 
 from __future__ import annotations
 
+import hashlib
+import hmac
 import json
+import re
 import os
+import time
 import urllib.error
+import urllib.parse
 import urllib.request
 
 DEFAULT_BASE_URL = "https://proofledger.io"
@@ -31,6 +36,11 @@ API_KEY_ENV = "PROOFLEDGER_API_KEY"
 _UTM = "utm_source=verify-proof&utm_medium=cli"
 SIGNUP_URL = f"{DEFAULT_BASE_URL}/login.html?{_UTM}&utm_campaign=api-key"
 PRICING_URL = f"{DEFAULT_BASE_URL}/pricing.html?{_UTM}&utm_campaign=quota"
+# The one printed after a successful `verify`, which is the command almost every
+# install actually runs. Its own campaign so the scoreboard can tell the people who
+# arrived after verifying somebody else's proof from the ones who went looking for
+# an API key.
+HOME_URL = f"{DEFAULT_BASE_URL}/?{_UTM}&utm_campaign=verified"
 
 
 class ProofLedgerError(RuntimeError):
@@ -111,6 +121,121 @@ def submit_proof(
         ) from exc
 
 
+def _request(
+    method: str,
+    path: str,
+    payload: dict | None = None,
+    key: str | None = None,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: int = 30,
+) -> dict:
+    """One authenticated call to the v1 API. Errors become ProofLedgerError."""
+    request = urllib.request.Request(
+        f"{base_url.rstrip('/')}{path}",
+        data=None if payload is None else json.dumps(payload).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {key or api_key()}",
+            "Content-Type": "application/json",
+            "User-Agent": "verify-proof (https://pypi.org/project/verify-proof/)",
+        },
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read().decode("utf-8")
+            return json.loads(body) if body else {}
+    except urllib.error.HTTPError as exc:
+        raise ProofLedgerError(_http_message(exc)) from exc
+    except urllib.error.URLError as exc:
+        raise ProofLedgerError(
+            f"Could not reach {base_url}: {exc.reason}\n"
+            "Hashing and verification still work offline."
+        ) from exc
+
+
+def _digest(sha256: str) -> str:
+    digest = sha256.strip().lower().removeprefix("0x")
+    if len(digest) != 64 or any(c not in "0123456789abcdef" for c in digest):
+        raise ProofLedgerError(f"Not a SHA-256 hex digest: {sha256!r}")
+    return digest
+
+
+def submit_batch(
+    items: list[dict],
+    key: str | None = None,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: int = 60,
+) -> dict:
+    """Anchor up to 100 hashes in one call (POST /api/v1/proofs/batch).
+
+    Each item: {"sha256": ..., "external_id": optional, "filename": optional}.
+    Items are checked first and written together; Polygon only. The response
+    has a `summary` and one entry per item with `result` created / exists /
+    invalid and, for the first two, the `proof`.
+    """
+    if not items or len(items) > 100:
+        raise ProofLedgerError("submit_batch takes 1 to 100 items.")
+    payload = {"items": []}
+    for it in items:
+        out = {"sha256": _digest(it["sha256"])}
+        if it.get("external_id") is not None:
+            out["external_id"] = str(it["external_id"])
+        if it.get("filename"):
+            out["filename"] = str(it["filename"])[:500]
+        payload["items"].append(out)
+    return _request("POST", "/api/v1/proofs/batch", payload, key, base_url, timeout)
+
+
+def get_proof(proof_id: int | str, key: str | None = None, base_url: str = DEFAULT_BASE_URL) -> dict:
+    """One of your proofs by ProofLedger id (GET /api/v1/proof/:id)."""
+    return _request("GET", f"/api/v1/proof/{urllib.parse.quote(str(proof_id))}", None, key, base_url)
+
+
+def get_proof_by_external_id(external_id: str, key: str | None = None, base_url: str = DEFAULT_BASE_URL) -> dict | None:
+    """One of your proofs by your own record id, or None when there is none."""
+    try:
+        r = _request("GET", "/api/v1/proofs?" + urllib.parse.urlencode({"external_id": external_id}), None, key, base_url)
+    except ProofLedgerError as exc:
+        if "404" in str(exc):
+            return None
+        raise
+    return r.get("proof")
+
+
+def get_bundle(proof_id: int | str, chain: str = "polygon", key: str | None = None, base_url: str = DEFAULT_BASE_URL) -> dict:
+    """The bundle for a proof (GET /api/v1/proof/:id/bundle): everything needed
+    to verify it without ProofLedger, in this package's proof-file format.
+    Save it next to the file and `verify-proof verify <file> --proof bundle.json`
+    works offline, for as long as the chain exists."""
+    if chain not in ("polygon", "bitcoin"):
+        raise ProofLedgerError("chain must be 'polygon' or 'bitcoin'")
+    return _request("GET", f"/api/v1/proof/{urllib.parse.quote(str(proof_id))}/bundle?chain={chain}", None, key, base_url)
+
+
+def verify_webhook_signature(
+    secret: str,
+    header: str,
+    raw_body: bytes | str,
+    tolerance_seconds: int = 300,
+    now: int | None = None,
+) -> bool:
+    """Check a ProofLedger webhook delivery before trusting it.
+
+    ProofLedger sends `ProofLedger-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + body)>`.
+    Pass the RAW request body exactly as received; re-serialising it breaks the MAC.
+    Pure computation, no network.
+    """
+    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", str(header or ""))
+    if not m:
+        return False
+    t = int(m.group(1))
+    if abs((now if now is not None else int(time.time())) - t) > tolerance_seconds:
+        return False
+    body = raw_body if isinstance(raw_body, bytes) else str(raw_body).encode("utf-8")
+    expected = hmac.new(secret.encode("utf-8"), f"{t}.".encode("utf-8") + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, m.group(2))
+
+
 def _http_message(exc: urllib.error.HTTPError) -> str:
     """Turn an API error into something the reader can act on."""
     detail = ""
@@ -127,6 +252,12 @@ def _http_message(exc: urllib.error.HTTPError) -> str:
             + (f"\n({detail})" if detail else "")
         )
     if exc.code == 429:
+        retry_after = exc.headers.get("Retry-After") if exc.headers else None
+        if retry_after:
+            return (
+                f"Rate limit: 120 requests per minute per key (429). Retry after {retry_after} s.\n"
+                "One batch call carries up to 100 hashes." + (f"\n({detail})" if detail else "")
+            )
         return (
             "Monthly API proof limit reached (429).\n"
             "Free and Standard include 25 proofs a month, Professional 500, "
@@ -178,7 +309,8 @@ def summarize(proof: dict, base_url: str = DEFAULT_BASE_URL) -> str:
     lines += [
         "",
         "Anchoring is not instant. Polygon usually settles within minutes; "
-        "Bitcoin is Merkle-batched daily. Re-check the proof, or verify the "
+        "Bitcoin, when requested, is anchored in hand-signed batches with no fixed "
+        "timeline. Re-check the proof, or verify the "
         "downloaded proof file offline with:  verify-proof verify <file> "
         "--proof <proof.json>",
     ]

{verify_proof-0.3.0 → verify_proof-0.3.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "verify-proof"
-version = "0.3.0"
-description = "Verify blockchain-anchored timestamp proofs (ProofLedger, OpenTimestamps) — CLI + MCP server"
+version = "0.3.2"
+description = "Verify blockchain-anchored timestamp proofs offline, and create them through the ProofLedger API — CLI + MCP server"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"

{verify_proof-0.3.0 → verify_proof-0.3.2/verify_proof.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: verify-proof
-Version: 0.3.0
-Summary: Verify blockchain-anchored timestamp proofs (ProofLedger, OpenTimestamps) — CLI + MCP server
+Version: 0.3.2
+Summary: Verify blockchain-anchored timestamp proofs offline, and create them through the ProofLedger API — CLI + MCP server
 Author-email: Craig Solomon <craig@fulcrumenterprises.tech>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Fulcrum-Enterprises/verify-proof
@@ -102,6 +102,16 @@ verify-proof verify document.pdf --proof proof.json
 # Transaction: abc123... Anchored at: 2026-03-15T10:30:00Z
 ```
 
+### Quiet by default
+
+A successful `verify` prints one line to stderr saying where proofs like it come
+from. It is suppressed whenever the output is piped or redirected, so scripts
+never see it, and stdout is unchanged either way. To silence it everywhere:
+
+```bash
+export VERIFY_PROOF_NO_HINT=1
+```
+
 ### Create a proof (needs a free API key)
 
 Everything above works offline. This is the one command that does not: to prove
@@ -118,7 +128,9 @@ verify-proof create document.pdf --no-filename   # send only the hash
 Only the 64-character SHA-256 digest leaves your machine, plus the filename
 unless you pass `--no-filename`. The file itself is never uploaded, on any
 command. Free accounts include 25 API proofs a month and unlimited Polygon
-anchoring through the web app: [proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create).
+anchoring through the web app:
+
+[proofledger.io](https://proofledger.io/login.html?utm_source=verify-proof&utm_medium=readme&utm_campaign=create)
 
 ### Proof file format
 
@@ -159,7 +171,10 @@ The base install stays dependency-free; the `[mcp]` extra adds the MCP SDK and i
 | `verify_file` | Verify a local file against a proof JSON file |
 | `verify_hash` | Verify a known hash against inline or file-based proof data |
 | `explain_proof` | Describe, in plain language, what a proof asserts and how to check it on a block explorer |
-| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. The only tool that uses the network, and the only one needing an API key |
+| `create_proof` | Anchor a file's hash on ProofLedger to create a new proof. Uses the network and needs an API key |
+| `create_proofs_batch` | Anchor up to 100 files in one API call; file names double as external ids, so re-running returns the existing proofs. Network, API key |
+| `get_proof_status` | Current anchoring status of one of your proofs. Network, API key |
+| `save_proof_bundle` | Download a proof's bundle (this package's proof format) and save it next to the file, so verification needs nothing from ProofLedger later. Network, API key |
 
 ### Connect it to Claude Desktop
 

{verify_proof-0.3.0 → verify_proof-0.3.2}/verify_proof.py

@@ -8,7 +8,7 @@ Supports verification of:
 - SHA-256 file hashes against Bitcoin and Polygon blockchain anchors
 - Proof of creation timestamps for digital content
 - Pre-loss evidence timestamps for legal/insurance records (ProofLedger)
-- Any OpenTimestamps (.ots) compatible proof file
+- JSON proof files carrying hash, blockchain, tx_id and merkle_path (ProofLedger bundles; binary OpenTimestamps .ots files are a different format and are not parsed here, use the ots tool)
 
 Usage:
     python verify_proof.py <file> [--proof <proof.json>] [--algorithm sha256]
@@ -36,12 +36,14 @@ immutable, independently verifiable timestamps that prove what existed and when.
 import argparse
 import hashlib
 import json
+import os
 import sys
 from pathlib import Path
 
 from proofledger_api import (
     API_KEY_ENV,
     DEFAULT_BASE_URL,
+    HOME_URL,
     ProofLedgerError,
     submit_proof,
     summarize,
@@ -122,12 +124,41 @@ def load_proof(proof_path: str) -> dict:
         return json.load(f)
 
 
+
+def _hint() -> None:
+    """One quiet line after a successful verify, pointing at where proofs come from.
+
+    Almost everybody who installs this runs `verify`, and `verify` never touches
+    the network, which is the product. So the only tagged link the package ever
+    printed lived in the missing-key error on `create`, a path most users never
+    reach: 417 installs in a month produced 10 tagged arrivals in 120 days. The
+    tool was doing its job and saying nothing about who made it.
+
+    Three manners rules, because a dev tool that nags gets uninstalled and the
+    goodwill is the whole asset:
+
+    * **stderr, never stdout.** Somebody is parsing `VERIFIED: ...` in a script
+      and a marketing line in that stream would break them.
+    * **Only when a human is watching.** Not a TTY means piped or scripted, and
+      a pipeline does not need to hear from us.
+    * **One env var turns it off for good** (`VERIFY_PROOF_NO_HINT=1`).
+    """
+    if os.environ.get("VERIFY_PROOF_NO_HINT"):
+        return
+    try:
+        if not sys.stdout.isatty():
+            return
+    except Exception:  # pragma: no cover - exotic stdout
+        return
+    print(f"\n(proofs like this are made with ProofLedger: {HOME_URL})", file=sys.stderr)
+
+
 def main():
     parser = argparse.ArgumentParser(
         prog="verify-proof",
         description=(
             "Verify blockchain-anchored timestamp proofs. "
-            "Works with ProofLedger, OpenTimestamps, and compatible proofs."
+            "Reads JSON proofs (ProofLedger bundles and compatible); .ots files are not parsed."
         ),
         epilog=(
             "Examples:\n"
@@ -211,6 +242,7 @@ def main():
 
         if result["verified"]:
             print(f"VERIFIED: {result['message']}")
+            _hint()
             sys.exit(0)
         else:
             print(f"FAILED: {result.get('error', 'Unknown error')}")

{verify_proof-0.3.0 → verify_proof-0.3.2}/verify_proof_mcp.py

@@ -3,19 +3,22 @@
 
 A Model Context Protocol (MCP) server that lets MCP-compatible clients
 (Claude Desktop, Cursor, and any other MCP host) verify blockchain-anchored
-timestamp proofs directly. It exposes the `verify-proof` library as four tools
+timestamp proofs directly. It exposes the `verify-proof` library as tools
 so an assistant can, on the user's own machine:
 
   - compute the SHA-256 hash of a local file (the file is never uploaded),
   - verify a local file against a blockchain-anchored proof JSON,
   - verify a known hash against inline proof data,
   - explain in plain language what a proof file asserts,
-  - create a new proof by anchoring a file's hash on ProofLedger.
+  - create a new proof by anchoring a file's hash on ProofLedger,
+  - create proofs for up to 100 files in one call, check a proof's status,
+    and save a proof's bundle so it verifies later without ProofLedger.
 
 The first four run entirely offline and always will: verification that depends
-on the issuing service is not verification. `create_proof` is the exception and
-says so in its own description - anchoring requires a service, and it sends the
-hash (never the file) to ProofLedger, with a free API key.
+on the issuing service is not verification. The ProofLedger tools (create,
+batch, status, bundle) are the exception and say so in their own descriptions:
+anchoring requires a service, and they send hashes (never files) to
+ProofLedger, with a free API key.
 
 Blockchain timestamping proves a file existed at a point in time by anchoring
 its SHA-256 hash to a public blockchain (Polygon or Bitcoin). ProofLedger
@@ -47,7 +50,15 @@ except ImportError as exc:  # pragma: no cover - depends on installed SDK
         f"(underlying import error: {exc})"
     )
 
-from proofledger_api import ProofLedgerError, submit_proof, summarize
+from proofledger_api import (
+    DEFAULT_BASE_URL,
+    ProofLedgerError,
+    get_bundle,
+    get_proof,
+    submit_batch,
+    submit_proof,
+    summarize,
+)
 from verify_proof import hash_file, load_proof
 from verify_proof import verify_proof as _verify_proof
 
@@ -269,6 +280,108 @@ def create_proof(file_path: str, bitcoin: bool = False, send_filename: bool = Tr
     return summarize(proof)
 
 
+@mcp.tool()
+def create_proofs_batch(file_paths: list[str], send_filenames: bool = True) -> str:
+    """Create proofs for several local files in ONE ProofLedger API call (up to 100).
+
+    Uses the network and needs PROOFLEDGER_API_KEY, like create_proof. Each
+    file is hashed locally; only the hashes (and filenames, if allowed) are
+    sent. The file name is also used as the external_id, so running this twice
+    on the same files returns the existing proofs instead of creating more.
+    Polygon anchoring only.
+
+    Args:
+        file_paths: Paths of the files to timestamp, 1 to 100.
+        send_filenames: Send each file's name as its label. Set false to send
+                        only the hashes (external ids are still the names).
+    """
+    paths = [Path(p) for p in file_paths]
+    missing = [str(p) for p in paths if not p.is_file()]
+    if missing:
+        return "File not found: " + ", ".join(missing)
+    if not paths or len(paths) > 100:
+        return "Give between 1 and 100 files."
+    items = [
+        {"sha256": hash_file(str(p)), "external_id": p.name, "filename": p.name if send_filenames else None}
+        for p in paths
+    ]
+    try:
+        r = submit_batch(items)
+    except ProofLedgerError as exc:
+        return str(exc)
+    summary = r.get("summary", {})
+    lines = [
+        f"Batch submitted: {summary.get('created', 0)} created, "
+        f"{summary.get('exists', 0)} already existed, {summary.get('invalid', 0)} invalid.",
+        "",
+    ]
+    for it, p in zip(r.get("items", []), paths):
+        proof = it.get("proof") or {}
+        if it.get("result") in ("created", "exists"):
+            lines.append(
+                f"  {p.name}: proof {proof.get('id')} ({it['result']})  "
+                f"{DEFAULT_BASE_URL}{proof.get('certificate_url', '')}"
+            )
+        else:
+            lines.append(f"  {p.name}: {it.get('result')} - {it.get('error', '')}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_proof_status(proof_id: int) -> str:
+    """Fetch the current status of one of YOUR ProofLedger proofs by id.
+
+    Uses the network and needs PROOFLEDGER_API_KEY. Shows whether the Polygon
+    anchor has landed (usually within a minute of creation) and the Bitcoin
+    status when it was requested. For checking somebody else's proof, use
+    verify_file with their bundle instead; that needs no key and no network.
+    """
+    try:
+        p = get_proof(proof_id)
+    except ProofLedgerError as exc:
+        return str(exc)
+    lines = [
+        f"Proof {p.get('id')}  ({p.get('filename') or 'no filename'})",
+        f"  SHA-256        : {p.get('sha256')}",
+        f"  Polygon        : {p.get('polygon_status')}" + (f"  tx {p.get('chain_tx')}" if p.get("chain_tx") else ""),
+        f"  Bitcoin        : {p.get('bitcoin_status')}" + (f"  tx {p.get('bitcoin_txid')}" if p.get("bitcoin_txid") else ""),
+        f"  Created        : {p.get('created_at')}",
+        f"  Certificate    : {DEFAULT_BASE_URL}{p.get('certificate_url', '')}",
+    ]
+    if p.get("issued_via"):
+        lines.append(f"  Recorded through {p['issued_via']} \u00b7 Anchored by ProofLedger")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def save_proof_bundle(proof_id: int, output_path: str, chain: str = "polygon") -> str:
+    """Download the bundle for one of YOUR proofs and save it as a JSON file.
+
+    Uses the network and needs PROOFLEDGER_API_KEY. The bundle is everything
+    needed to verify the proof WITHOUT ProofLedger: hash, chain, transaction
+    id, anchor time and, for Bitcoin, the Merkle path. Save it next to the
+    file; `verify_file` (or `verify-proof verify`) then works offline, for as
+    long as the blockchain exists. Before the anchor lands the bundle says
+    anchored: false; fetch it again afterwards.
+
+    Args:
+        proof_id: The ProofLedger proof id.
+        output_path: Where to write the JSON (e.g. song.mp3.proof.json).
+        chain: "polygon" (default) or "bitcoin" for the top-level fields.
+    """
+    try:
+        bundle = get_bundle(proof_id, chain=chain)
+    except ProofLedgerError as exc:
+        return str(exc)
+    out = Path(output_path)
+    out.write_text(json.dumps(bundle, indent=2), encoding="utf-8")
+    state = "anchored" if bundle.get("anchored") else "NOT YET ANCHORED (fetch again later)"
+    return (
+        f"Saved bundle for proof {proof_id} to {out} ({bundle.get('blockchain')}, {state}). "
+        f"Verify offline with: verify-proof verify <file> --proof {out}"
+    )
+
+
 def main() -> None:
     """Entry point — run the server over stdio (the transport MCP hosts use)."""
     mcp.run()