DEV Community: Craig Solomon

Webhook Security Patterns for Async Proof Workflows: HMAC, Idempotency, and Replay Protection

Craig Solomon — Thu, 10 Sep 2026 13:00:00 +0000

A file gets hashed. The hash goes off to get anchored. Sometime later, a webhook arrives saying the anchor is done. That gap between "submitted" and "confirmed" is where most of the hard problems in an async proof pipeline actually live. Not the hashing. Not the anchoring. The webhook.

I hit this building the anchoring flow behind ProofLedger, and it's a pattern that applies to any system where a client kicks off work and gets notified later: payment confirmations, video transcoding, background exports. If you're building or consuming webhooks for anything time-sensitive, these four problems show up in the same order every time.

Verify the signature before you trust the payload

A webhook endpoint is a URL on the open internet. Anyone can POST to it. If your handler reads status: "anchored" from the body and acts on it without checking where it came from, you've built an endpoint that lets a stranger fake completion events.

The standard fix is HMAC-SHA256. The sender computes a signature over the raw request body using a shared secret, puts it in a header, and the receiver recomputes it and compares.

import hashlib
import hmac
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b"shared-secret-from-sender"

def verify_signature(payload_body: bytes, signature_header: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET, payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

@app.route("/webhooks/proof-status", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Signature-256", "")
    if not verify_signature(request.get_data(), signature):
        abort(401, "invalid signature")

    event = request.get_json()
    process_event(event)
    return "", 204

Two details matter here and both are easy to get wrong. First, hmac.compare_digest instead of ==. A regular string comparison short-circuits on the first mismatched byte, which leaks timing information an attacker can use to guess the signature byte by byte. Second, sign the raw bytes, not the parsed JSON. If you verify against request.get_json() re-serialized, key ordering or whitespace differences between the sender's serializer and yours will produce a different signature than the one that was actually sent, and you'll get false rejections that are miserable to debug.

Idempotency: the same event will arrive more than once

Webhook senders retry on timeout, because from their side a timeout looks identical to a dropped delivery. That means your handler needs to survive receiving the exact same event two, three, sometimes ten times.

The fix is an idempotency key, some sender-provided ID that's unique per logical event, checked against a store before you do anything with side effects.

import sqlite3
import time

conn = sqlite3.connect("webhook_events.db")
conn.execute("""
    CREATE TABLE IF NOT EXISTS processed_events (
        event_id TEXT PRIMARY KEY,
        received_at REAL NOT NULL
    )
""")

def already_processed(event_id: str) -> bool:
    row = conn.execute(
        "SELECT 1 FROM processed_events WHERE event_id = ?", (event_id,)
    ).fetchone()
    return row is not None

def mark_processed(event_id: str) -> None:
    conn.execute(
        "INSERT OR IGNORE INTO processed_events (event_id, received_at) VALUES (?, ?)",
        (event_id, time.time()),
    )
    conn.commit()

def process_event(event: dict) -> None:
    event_id = event["id"]
    if already_processed(event_id):
        return
    mark_processed(event_id)
    apply_status_update(event)

The INSERT OR IGNORE plus a PRIMARY KEY constraint does the real work. Two requests racing for the same event_id will have one succeed and one silently no-op at the database level, which is a stronger guarantee than an in-process check-then-set that a second thread can slip through. A Redis SETNX with a TTL does the same job if you're not on SQLite. Either way, the key insight is that idempotency has to be enforced at the storage layer, not in application logic that can race.

Retry and backoff on the sending side

If you're the one firing webhooks (say, notifying a customer's endpoint when an anchor confirms), the receiving server will sometimes be down, slow, or rate-limiting you. Retrying immediately in a tight loop makes that worse. Exponential backoff with jitter spreads retries out and gives the receiver room to recover.

import random
import time
import requests

def send_webhook(url: str, payload: dict, max_attempts: int = 5) -> bool:
    for attempt in range(max_attempts):
        try:
            response = requests.post(url, json=payload, timeout=5)
            if response.status_code < 300:
                return True
            if response.status_code == 429:
                retry_after = float(response.headers.get("Retry-After", 0))
                time.sleep(retry_after or backoff_delay(attempt))
                continue
            if response.status_code < 500:
                return False  # client error, retrying won't help
        except requests.RequestException:
            pass
        time.sleep(backoff_delay(attempt))
    return False

def backoff_delay(attempt: int) -> float:
    base = min(2 ** attempt, 60)
    return base + random.uniform(0, base * 0.1)

Notice the branch on status code. A 429 gets special handling because the receiver told you exactly when to come back, a 4xx (other than 429) stops retrying because the request itself is malformed and resending it changes nothing, and anything else falls through to exponential backoff. Treating all failures the same, whether it's a 400 or a 503, wastes retry budget on requests that were never going to succeed.

Replay protection closes the last gap

Signature verification proves the payload came from the real sender. It doesn't prove the payload is fresh. If an attacker captures a valid signed request (from a compromised log, a proxy, a misconfigured CDN cache) they can replay it later and your handler will accept it, because the signature still checks out.

The fix is a timestamp in the payload, checked against a tolerance window, combined with the idempotency check you already have.

def is_replay(event: dict, tolerance_seconds: int = 300) -> bool:
    event_time = event.get("timestamp", 0)
    now = time.time()
    if abs(now - event_time) > tolerance_seconds:
        return True
    return already_processed(event["id"])

A five-minute tolerance window is generous enough to absorb clock drift and network delay between well-behaved systems, tight enough that a captured request is useless a few minutes after the fact. Sign the timestamp as part of the HMAC payload too, not just the event body, otherwise an attacker can strip an old timestamp and paste in a fresh one without invalidating the signature.

Putting it together

None of these four pieces is complicated on its own. What makes webhook handling hard is that skipping any one of them creates a gap the other three don't cover. Signature verification without idempotency means a legitimate but duplicated event can double-charge, double-anchor, or double-anything. Idempotency without replay protection means an old captured request stays valid forever. Backoff without respecting Retry-After just hammers a struggling server on your own schedule instead of theirs.

If you're building this for anchoring workflows specifically, the shape doesn't change: a hash goes out, a confirmation comes back on its own schedule, and your handler needs to be safe whether that confirmation shows up once, twice, or three minutes late with a stale timestamp attached.

What's your tolerance window for replay protection, and have you had to tune it after a real incident?

Your build produces a hash. Who can check it without asking you?

Craig Solomon — Thu, 03 Sep 2026 13:00:00 +0000

Here's the question I'd ask about your own pipeline, and it's not the one you think.

You already hash things. Your CI emits a digest for every artifact. Your lockfile is a wall of SHA-256. Your registry gives you a content-addressed tag. Good. That part is solved.

The question is: six months from now, when someone needs to know that a specific build existed on a specific day, who do they have to ask?

Usually the answer is you. Or your CI vendor. Or your artifact store. And that's fine right up until the moment it isn't, because the whole point of the record is to be believed by someone who has a reason not to believe you.

The obvious answer, and where it runs out

Obvious answer: the log has a timestamp. CI records the run, the run has a date, the artifact has a digest, done.

That works for almost everything. Debugging a regression, tracing a bad deploy, figuring out which build shipped on Tuesday. Nobody is adversarial in those situations, so a database row with a created_at on it is completely sufficient.

Where it runs out is when the party relying on the timestamp is not the party who issued it.

Because that log row is mutable by whoever owns the database. Not "will be tampered with," just: nothing about it makes tampering detectable. If I hand you a CSV export of my build history, the strongest thing you can say about it is that I gave it to you. You can't distinguish a real record from one I wrote yesterday. The trust isn't in the data, it's in me, and if I'm the one who benefits from the timestamp, that's the exact place you shouldn't be putting trust.

The retention window is the other half of it. Most CI providers age out logs. Your evidence quietly has a shelf life that's shorter than the thing you might need it for.

What actually fixes it

Put the hash somewhere neither of us controls.

That's it, mechanically. You take the SHA-256 of the bytes, you write that hash into a public blockchain transaction, and now the timestamp is attested by a system that doesn't know either of us and doesn't care who wins. Anyone can go look at the block. The block has a time. The transaction has your hash in it. If the file's hash matches, the file existed before that block was mined.

The file itself never goes anywhere. This is the part people get wrong when they first hear "blockchain" and reach for the door. Nothing is uploaded. A SHA-256 digest is 32 bytes and tells you nothing about the input. You can anchor a signed contract, a model checkpoint, a database dump full of PII, whatever, and the thing on chain is still just 32 bytes.

If you want to see this for yourself with tools you already have:

# what goes on chain
sha256sum dist/myapp-1.4.2.tar.gz
# 9f2c... 64 hex chars. that's the whole payload.

# and the verification, later, from the other side
sha256sum ./the-file-they-sent-me
# match or no match. binary answer. no server involved.

That second command is the important one, and I'll come back to it.

The part that took me a while to actually understand

I spent a while building this stuff, and the thing I got wrong at the start is that I thought the hard problem was the anchoring. It isn't. Anchoring is a solved, boring, well-understood operation. Writing 32 bytes into a chain is not where the difficulty lives.

The hard problem is verification, and specifically: verification by someone who distrusts you.

Think about what a verification flow usually looks like. Vendor gives you a proof. To check the proof, you go to the vendor's website and paste something in, and the vendor's website says "verified." Read that again. The entity whose honesty is in question is the same entity telling you the record is good. That's a closed loop. It has the shape of verification without any of the substance.

So the test isn't "can this be verified." It's "can this be verified when the issuer is offline, hostile, or out of business."

Which means the verification path has to be:

Public. No account, no API key, no login. If your auditor needs credentials from you to check your evidence, they're checking with your permission, and permission is exactly what's in dispute.
Local. They should be able to run it on their own machine against their own copy of the file.
Offline. The chain data is public. Nothing in the check requires my server to be up.

That third one is the one that pushed me toward shipping the verification as a separate installable thing. There's a verify-proof package on PyPI that does the check locally, and a GitHub Action for wiring it into CI. Separate from the service on purpose. If the service disappears, the checker still works, because the checker's job is to compare a hash against public chain data, and neither of those things is mine.

The tradeoff I took, and what it cost

I anchor to two chains: Polygon and Bitcoin.

Polygon is fast and cheap enough that I can offer it unlimited on every plan including the free one. No per-proof charge, no lifetime cap on free proofs. That's not generosity, it's just what the cost structure allows, and pretending otherwise would be silly.

Bitcoin is the opposite. It costs real money per anchor, so it's billed per anchor, ranging from $7.99 down to $3.99 depending on plan.

The reason for two is independence. If your record lives on one chain and someone wants to argue about that chain's consensus, its validators, its history, you're stuck arguing chain politics instead of arguing about your file. Two independent chains means the record survives that argument. Same hash, two places, verifiable separately.

Now the honest part, and it matters: the Bitcoin proof I produce is not cryptographically better than a free one. OpenTimestamps exists, it anchors to Bitcoin, it's free, and its proof is exactly as valid as mine. Anyone telling you their blockchain timestamp is more secure than another correctly-constructed blockchain timestamp is selling you something that doesn't exist. A hash in a block is a hash in a block.

What differs is everything around the proof: organization, retrieval, an API, being able to hand an auditor a URL. That's a platform question, not a cryptography question, and it's worth what it's worth. But if all you need is "this file existed on this date" and you're comfortable managing the proof files yourself, OpenTimestamps does that and costs nothing. Go use it. I'd rather you get a real timestamp somewhere than a fake one from me.

The API surface, since developers always ask

Three endpoints. That's the entire v1.

POST /api/v1/proof # submit a hash, Bearer sk_ auth
GET /api/v1/proof/:id # status, chain_tx, bitcoin_txid. owner only.
GET /api/v1/verify?hash=<sha256> # public, no auth, 120 req/hr per IP

That last line is the design decision the whole product hangs on. It's public and unauthenticated on purpose, because the person most likely to need it is opposing counsel or an auditor, and they are never going to have my API key. Docs at proofledger.io/api.html, OpenAPI spec at /openapi.json.

Note what's not there. No batch endpoint, no list endpoint, no webhooks. It's a small surface because the operation is small.

There's also a public verify URL for every proof, which is the thing you paste into an email when someone asks.

Go run this against whatever you're using now

Concrete, do it today, takes fifteen minutes.

Pick whatever system currently holds your timestamps. CI logs, artifact registry, document management tool, whatever. Then answer these against it:

Can someone with no account and no credentials from you verify a record? Actually try it. Log out, open a private window, attempt the check.
If your vendor's servers were down right now, could the check still be performed?
If the vendor shut down tomorrow, does the evidence survive?
Who can modify the timestamp field, and would anyone downstream be able to tell?

If the answers are no, no, no, and "me, and no," you don't have evidence. You have a record that's fine for operations and worthless the moment it's contested. Which might be totally acceptable! Most timestamps never get contested. Just know which one you've got before you need it to be the other one.

I'm building the anchoring side of this at proofledger.io, still solo, still figuring parts of it out.

The thing I actually want an answer to: for those of you who've had to produce build provenance for a customer audit or a compliance review, what did they accept as proof? I keep hearing that a signed statement from the vendor was enough, which surprises me every time. Curious whether that's the norm or whether I'm hearing from an unusual slice.

The Merkle Proof Bug That Silently Returns the Wrong Root

Craig Solomon — Mon, 31 Aug 2026 13:00:02 +0000

A Merkle proof check that comes back false doesn't always mean the file was tampered with. Half the time it means the hash-combination step is wrong: hex decoded as text instead of bytes, a sibling hash combined on the wrong side, or a hash function swapped out without anyone noticing. None of these throw an error. They just produce a root that doesn't match, and you're left assuming the worst about a file that's actually fine.

I ran into every one of these while writing the Merkle verification logic for verify-proof, a small Python package that checks a file's SHA-256 hash against a blockchain-anchored proof offline. It implements the same proof-checking logic that validates a ProofLedger timestamp proof, minus the anchoring service itself. Just the math, run locally, no API call required. The algorithm is short. The bugs it hides are not obvious until you've hit them once.

Two Ways to Combine a Hash, One Correct Answer

A Merkle proof is a list of sibling hashes plus a position ("left" or "right") for each step. Starting from your leaf hash, you combine it with each sibling in order, hash the result, and repeat until you land on a value. If that value matches the published root, the leaf was part of the tree.

The combining step looks trivial: concatenate two hex strings and hash them. Here's the version that looks right and isn't:

import hashlib

leaf_hash = "a3f5c8e1b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6"
sibling_hash = "1f2e3d4c5b6a798877665544332211001f2e3d4c5b6a798877665544332211"

combined = leaf_hash + sibling_hash
result = hashlib.sha256(combined.encode()).hexdigest()

That .encode() call is the bug. combined is a hex string, forty bytes of ASCII characters like "a", "3", "f". Encoding it treats those characters as text, so you end up hashing the string "a3f5c8e1..." instead of the sixteen raw bytes it represents. The hash function runs fine. It just runs on the wrong input.

The fix is to decode the hex into bytes before concatenating:

combined = bytes.fromhex(leaf_hash) + bytes.fromhex(sibling_hash)
result = hashlib.sha256(combined).hexdigest()

Two different byte sequences, two different roots. Nothing in the code tells you which one the original tree was built with. You find out by testing against a known-good proof, or you don't find out at all.

Left and Right Aren't Symmetric

Even with correct byte handling, order matters. hash(A + B) and hash(B + A) are different values, so each proof step needs to know which side the sibling belongs on:

def combine(current, sibling, position):
    current_bytes = bytes.fromhex(current)
    sibling_bytes = bytes.fromhex(sibling)
    if position == "left":
        combined = sibling_bytes + current_bytes
    else:
        combined = current_bytes + sibling_bytes
    return hashlib.sha256(combined).hexdigest()

Get "left" and "right" backwards and every proof with an odd number of steps fails, while proofs with an even number sometimes pass by coincidence, because reversing the order twice cancels out. That's the part that cost me an afternoon. A test suite with only even-depth trees will tell you the code works when it's actually broken half the time.

What This Means If You're Verifying, Not Just Building

If you're on the receiving end of a Merkle proof rather than the one generating it, none of this is visible to you. You get a leaf hash, a list of siblings, a root, and a "valid: true/false" result. When it comes back false, the honest first question isn't "was this file altered?" It's "did the verifier implement the combining step correctly?"

That's worth checking before you tell a claims adjuster or an opposing counsel that a document failed verification. A bad .encode() call and actual tampering produce the exact same output.

Verifying a Blockchain-Anchored Timestamp Without Trusting the Vendor

Craig Solomon — Thu, 27 Aug 2026 13:00:00 +0000

An expert witness gets handed a PDF. It says "Verified" in green text, with a transaction hash underneath. The other side's attorney asks the obvious question: verified by whom?

If the answer is "the company that sold this to the claimant," that's not verification. That's a receipt. The entire premise of anchoring evidence hashes to a public blockchain is that you shouldn't need to trust the vendor at all. The proof should stand up even if the vendor's servers are down, the company folded, or nobody on the stand has ever heard of it. This post builds a verifier that does exactly that: given a file and a certificate, it confirms the anchor by talking directly to public blockchain infrastructure. No vendor API in the loop.

What independent verification actually requires

Three things, and none of them involve calling back to whoever issued the certificate:

Recompute the file's hash yourself. Don't trust the hash printed on the certificate.
Look up the anchoring transaction directly on a public node or block explorer.
Confirm the hash you computed is actually embedded in that transaction's data.

If all three line up, the proof holds regardless of who generated the certificate. If the vendor is lying, or gone, or wrong, the chain itself contradicts them and you'll see it.

Step 1: recompute the hash

Never trust a hash string sitting in a JSON file. Read the actual bytes.

import hashlib

def sha256_file(path, chunk_size=65536):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(chunk_size), b""):
            h.update(chunk)
    return h.hexdigest()

Compare this against the file_hash field in the certificate. If they don't match, stop. Nothing else in this process matters until they do.

Step 2: check the Polygon anchor against a public node

A Polygon anchor typically records the hash as calldata in a contract transaction, or as an event log. Either way, you don't need the vendor's dashboard to read it. You need a JSON-RPC call to any public Polygon node.

import requests

POLYGON_RPC = "https://polygon-rpc.com"

def get_transaction(tx_hash):
    payload = {
        "jsonrpc": "2.0",
        "method": "eth_getTransactionByHash",
        "params": [tx_hash],
        "id": 1,
    }
    resp = requests.post(POLYGON_RPC, json=payload, timeout=10)
    resp.raise_for_status()
    return resp.json()["result"]

def hash_in_calldata(tx, file_hash):
    input_data = tx["input"].lower().replace("0x", "")
    return file_hash.lower() in input_data

polygon-rpc.com is a public endpoint maintained by the Polygon Foundation, not by whoever sold you the anchoring service. Anyone with the transaction hash from the certificate can run this and get the same answer, forever, independent of the original vendor.

Step 3: verify the Bitcoin batch with a merkle proof

Instant Polygon anchoring is useful, but Bitcoin gives you a settlement layer with a much longer track record and no single foundation controlling it. Anchoring every file's hash directly to Bitcoin isn't practical (fees, block space), so batch systems anchor once per day: every hash from that day gets folded into a merkle tree, and only the root goes into a Bitcoin transaction, usually via OP_RETURN.

Your certificate should include a merkle proof: the sibling hashes needed to walk from your file's leaf up to that day's root. Verifying it means recomputing the path yourself.

def sha256d(data):
    return hashlib.sha256(hashlib.sha256(data).digest()).digest()

def verify_merkle_proof(leaf_hash_hex, proof, expected_root_hex):
    current = bytes.fromhex(leaf_hash_hex)
    for step in proof:
        sibling = bytes.fromhex(step["hash"])
        if step["position"] == "left":
            current = sha256d(sibling + current)
        else:
            current = sha256d(current + sibling)
    return current.hex() == expected_root_hex.lower()

Then pull the actual on-chain transaction from a public Bitcoin explorer API and confirm the OP_RETURN output matches the root your proof produced:

def get_op_return_data(txid):
    url = f"https://blockstream.info/api/tx/{txid}"
    resp = requests.get(url, timeout=10)
    resp.raise_for_status()
    tx = resp.json()
    for vout in tx["vout"]:
        script = vout["scriptpubkey"]
        if script.startswith("6a"):  # OP_RETURN opcode
            return script[4:]  # strip opcode + push length byte
    return None

blockstream.info runs an open-source explorer with no account required. Any court, any auditor, any opposing expert can hit the same endpoint and reproduce your result.

Tying it together

def verify(file_path, certificate):
    file_hash = sha256_file(file_path)
    assert file_hash == certificate["file_hash"], "File hash mismatch"

    poly_tx = get_transaction(certificate["polygon_tx_hash"])
    assert hash_in_calldata(poly_tx, file_hash), "Hash not found in Polygon tx"

    root_verified = verify_merkle_proof(
        file_hash, certificate["merkle_proof"], certificate["btc_merkle_root"]
    )
    assert root_verified, "Merkle proof failed"

    op_return = get_op_return_data(certificate["btc_txid"])
    assert certificate["btc_merkle_root"].lower() in op_return.lower(), "Root not on-chain"

    return True

Four assertions. Two public APIs, neither belonging to the company that generated the certificate. If this function returns True, the timestamp claim holds up on its own, and it'll still hold up in five years even if the original service is gone.

Why this matters more than the anchoring itself

Most write-ups on evidence timestamping focus on the capture side: hash the file, send it somewhere, get a certificate back. That's the easy half. The half that actually gets tested in a deposition is whether the proof survives scrutiny from someone who has every incentive to poke holes in it.

A certificate that can only be validated by calling the vendor's own verification page is a certificate that depends on the vendor's continued existence and continued honesty. A certificate that can be validated with hashlib, a public RPC endpoint, and a block explorer API doesn't have that dependency. That's the actual point of putting the hash on a public chain instead of a private database: the proof stops being about who you trust and starts being about what you can independently recompute.

If you're building or evaluating evidence documentation tooling, this is the test worth running before anything else: strip away the vendor's dashboard and ask whether the proof still stands on public infrastructure alone. ProofLedger anchors to both chains for exactly this reason, but the verification logic above doesn't need to know that. It just needs the certificate and a network connection.

A checksum fixes half the problem.

Craig Solomon — Wed, 26 Aug 2026 13:00:00 +0000

A structural engineer submits an inspection report in a construction defect case. Opposing counsel pulls up the PDF properties, points to a "modified" date three weeks after the cover page, and asks the engineer to explain it on the stand. Nothing in the report changed. Software auto-updated the file when someone printed it. But now the report's credibility is the issue, not the roof.

That date on the PDF isn't a record of when the content was written. It's a record of the last time the operating system touched the file. Printing touches it. Opening it in a viewer that re-indexes fonts touches it. Copying it to a shared drive touches it. None of that is "someone edited this document." All of it can move the modified date.

Here's the part that catches people off guard: even if you never open a file again, metadata isn't tamper-evident. A modified date sits in the file system, not the file. Change your system clock, copy the file, and the new copy inherits whatever date you want it to have. There's no cryptographic link between the timestamp and the content. It's a label, not a proof.

A checksum fixes half the problem.

Run a file through SHA-256 and you get a hash, a fixed-length fingerprint of the content. Change one pixel, one character, one byte, and the hash changes completely. That's genuinely useful. It tells you a file hasn't been altered since the hash was generated.

What it doesn't tell you is when that hash was generated. You could compute a SHA-256 hash today for a photo you claim was taken last year. The hash proves the file matches itself. It says nothing about the timeline. Integrity and timing are two different problems, and a checksum only solves one of them.

Timing requires something outside your control.

To prove a file existed at a specific point in time, you need a record that you can't quietly edit afterward. A blockchain anchor works because the ledger isn't yours. You generate the hash locally (the file itself never leaves your device), and that hash gets written into a transaction on a public chain. Once it's confirmed, anyone can independently verify that exact hash existed in that block, at that time. Not because you said so. Because the network recorded it and thousands of nodes agree on the record.

ProofLedger anchors to two chains for a reason. Polygon confirms in seconds, so you get a timestamp almost immediately after capture. Bitcoin adds a daily batch anchor with a merkle proof tying your hash into that day's block, giving you the security of the most battle-tested chain in existence without paying Bitcoin fees on every file. Two independent, verifiable records instead of one.

Where this fits in a legal proceeding matters too.

Courts can authenticate blockchain-anchored records under FRE 901(b)(9), the rule covering evidence "produced by a process or system that produces an accurate result." That requires laying a foundation, usually expert testimony or a technical certification explaining how the anchoring process works and why it's reliable. It's not automatic. Separately, FRE 902(13) and 902(14) cover self-authentication of machine-generated records through written certification, added in 2017 specifically for cases like this, where a party wants to skip live testimony and authenticate via certified documentation instead. Different rule, different mechanism, and knowing which one applies to your situation is worth a conversation with counsel before you're in front of a judge.

If your organization is also using C2PA content credentials at capture, that's a good complement, not a substitute. C2PA embeds who captured a file, when, and with what device, directly into the file's metadata. The problem is that metadata lives inside the file. Re-upload it to a platform that strips metadata, convert the format, and the credential can disappear before it's ever needed. A blockchain anchor doesn't have that failure mode, because it was never stored in the file to begin with. It exists on a ledger the file doesn't control.

The engineer on the stand didn't need a better PDF. He needed a record, made the day the report was finished, that existed independently of the document and couldn't be explained away by a software quirk. That's the gap between a timestamp anyone can produce and one nobody can dispute.

See how dual-chain anchoring works

FRE 901 Blockchain Evidence Authentication: What the Standard Actually Requires

Craig Solomon — Fri, 21 Aug 2026 13:00:00 +0000

Meta description: How blockchain timestamps satisfy FRE 901(b)(9) and FRE 902(13) for evidence authentication in insurance claims and litigation.

You have a blockchain timestamp. The file hash is anchored on Bitcoin. Six months before the loss. Now someone's asking how you authenticate it.

That question comes up the moment blockchain-anchored evidence reaches a dispute. ProofLedger anchors file hashes to both Polygon and Bitcoin, and the records it generates are designed to satisfy the authentication standard from the start.

Under FRE 901(b)(9), evidence can be authenticated by showing it was produced by "a process or system that produces an accurate result." Blockchain timestamps fit this pathway. But the rule requires foundation. It isn't self-authenticating.

That distinction matters.

Self-authentication is FRE 902(13) and 902(14). Those provisions, added in 2017, allow machine-generated records to be admitted through written certification without live testimony. A blockchain anchor record can qualify under 902(13) when a proper certification accompanies the submission. That's the cleaner path at trial, and the one claims professionals should plan for.

FRE 901(b)(9) is still relevant for the foundation argument. It establishes that the blockchain itself is a reliable system. Expert testimony about how SHA-256 hashing works, how Polygon confirmation operates, and how Bitcoin's proof-of-work creates immutability satisfies the process-reliability standard. But it's a heavier lift than certification.

Here's the practical workflow. An adjuster or forensic consultant creates an evidence pack in ProofLedger at the time of site documentation. Each file gets SHA-256 hashed. Only the hash leaves the device; the original file stays local. The hash is anchored to Polygon for an immediate timestamp, then batched to Bitcoin with a daily merkle proof. The resulting certificate ties the hash to both chains, both timestamps.

When that evidence reaches discovery, the certificate is the starting point. Under FRE 902(13), it can be self-authenticated through written certification. Under FRE 901(b)(9), it supports expert testimony about process reliability. Either way, the anchor record is the foundation.

What it proves: the file existed at that hash value, at that moment. Not that the contents are true. Not that the file was the only version. But that the bit-for-bit document a party is presenting today existed before the loss date. That's the gap most digital evidence can't close.

Metadata timestamps can be changed. File creation dates can be altered. A blockchain anchor can't. The Bitcoin record has been continuously secured since 2009 by a network with more computing power than any single actor can match. A timestamp recorded there isn't going anywhere.

For claims professionals, the value shows up early. Risk managers and property managers who anchor documentation before a loss create a provenance record that survives the chain-of-custody challenges that come later in litigation. The anchor exists independent of the file, independent of any platform, independent of anything that might change hands during a claim.

FRE 901 blockchain evidence authentication isn't a theoretical discussion anymore. More carriers and legal teams are asking about it. The question now is whether the anchor records you're relying on were made correctly.

Anchor before the loss, not after. Risk documentation, not claim documentation.

Stacking C2PA Content Credentials with Blockchain Timestamps in Python

Craig Solomon — Thu, 20 Aug 2026 13:00:00 +0000

A file arrives from the field. It has C2PA content credentials: the camera model, GPS coordinates, capture time, an edit history. Solid provenance data.

Now it gets uploaded to a claims portal. The portal re-encodes it. Or it gets forwarded as an email attachment and the MIME handler strips the XMP block. Or someone converts it to a different format before anyone thinks to extract the metadata.

The C2PA manifest is gone. It lived inside the file, and the file changed.

A blockchain anchor doesn't work that way. Once a SHA-256 hash is written to an immutable ledger, the proof exists independently. No re-encoding touches it. No transfer strips it.

This post builds a Python pipeline that reads C2PA provenance data, hashes the file locally, and anchors the hash via REST API. Two evidence layers. One script.

What Each Layer Proves

C2PA (Content Credentials) answers provenance questions: which device captured the file, what software processed it, what edits were applied, and what the signing certificate's timestamp says. The standard has broad industry backing. Samsung Galaxy S25 and Google Pixel 10 now sign images natively at the camera level, so coverage from hardware is growing.

The limitation is architectural. A C2PA credential is a signed block embedded in the file. Strip the file's metadata, convert the format, or run it through a tool that doesn't preserve the XMP block, and the credential disappears. There's no independent copy.

A blockchain anchor is a different kind of proof. It answers: did this exact byte sequence exist at this point in time? The hash is computed from the file's bytes on your local machine. Only the hash goes anywhere. The anchor lives on a public ledger that anyone can read without touching the original file.

These are different questions. C2PA says where and how. Blockchain says when. If what's being disputed is timing, whether a file was created before or after a specific event, you need both.

Reading the C2PA Manifest

pip install c2pa-python requests

The c2pa-python package wraps the Rust C2PA SDK. The Reader class takes a MIME type and a binary stream. Check the README for your installed version, since the API has evolved across releases.

import c2pa
import json

MIME_MAP = {
    "jpg": "image/jpeg",
    "jpeg": "image/jpeg",
    "png": "image/png",
    "gif": "image/gif",
    "mp4": "video/mp4",
    "mov": "video/quicktime",
    "pdf": "application/pdf",
}

def get_mime(filepath: str) -> str:
    ext = filepath.rsplit(".", 1)[-1].lower()
    return MIME_MAP.get(ext, "application/octet-stream")

def read_c2pa(filepath: str) -> dict | None:
    """Return parsed manifest store, or None if no C2PA data."""
    try:
        with open(filepath, "rb") as f:
            reader = c2pa.Reader(get_mime(filepath), f)
            raw = reader.json()
        return json.loads(raw) if raw else None
    except Exception:
        return None

If the file has no C2PA credentials, you get None. That's expected. The anchor pipeline runs either way.

The manifest store JSON has a nested structure. The active manifest lives under manifests[active_manifest]. Here's how to pull the fields most useful for an evidence record:

def summarize_manifest(store: dict) -> dict:
    active_key = store.get("active_manifest", "")
    active = store.get("manifests", {}).get(active_key, {})
    sig_info = active.get("signature_info", {})
    assertions = [
        a.get("label")
        for a in active.get("assertions", [])
        if a.get("label")
    ]
    return {
        "claim_generator": active.get("claim_generator"),
        "format": active.get("format"),
        "signing_time": sig_info.get("time"),
        "signing_issuer": sig_info.get("issuer"),
        "assertions": assertions,
    }

signing_time is the timestamp from the credential authority. Useful context. But it's not an independent timestamp. It comes from the certificate authority that issued the manifest. Don't treat it as equivalent to a blockchain anchor.

Hashing and Anchoring

The file never leaves your machine. Only the SHA-256 hash goes to the API.

import hashlib
import time
import requests

ANCHOR_URL = "https://proofledger.io/api/v1/proof"
API_KEY = "sk_YOUR_KEY_HERE"

def sha256_file(filepath: str) -> str:
    h = hashlib.sha256()
    with open(filepath, "rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            h.update(chunk)
    return h.hexdigest()

def anchor_hash(sha256: str, filename: str) -> dict:
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    body = {"sha256": sha256, "filename": filename}

    for attempt in range(3):
        resp = requests.post(ANCHOR_URL, json=body, headers=headers, timeout=30)

        if resp.status_code == 201:
            return resp.json()

        if resp.status_code == 400:
            raise ValueError(f"Bad request: {resp.text}")

        if resp.status_code in (401, 403):
            raise PermissionError("Invalid API key or insufficient plan.")

        if resp.status_code == 409:
            return {**resp.json(), "_is_duplicate": True}

        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 60))
            print(f"Rate-limited. Waiting {wait}s.")
            time.sleep(wait)
            continue

        resp.raise_for_status()

    raise RuntimeError("Failed after 3 attempts.")

This calls the ProofLedger v1 REST API. The 409 response means the hash was already anchored. The response body includes duplicate_of, pointing to the original proof ID. Treat the earliest anchor as canonical.

The API requires a Professional or Business plan key (format: sk_...). Polygon anchoring happens automatically on submission. Bitcoin is an optional paid escalation per proof.

Third-Party Verification

Anyone with the SHA-256 can verify the anchor without credentials:

def verify_anchor(sha256: str) -> dict:
    url = f"https://proofledger.io/api/v1/verify?hash={sha256}"
    resp = requests.get(url, timeout=15)
    resp.raise_for_status()
    return resp.json()

This endpoint is public and rate-limited to 120 requests per hour per IP. No API key needed. Opposing counsel can run this check on a hash you provide.

result = verify_anchor(file_hash)
if result.get("found"):
    print(f"Anchored: {result['proof']['anchored_at']}")
    print(f"Explorer: {result.get('explorer_url')}")
else:
    print("Not found.")

Putting It Together

import json
from pathlib import Path

def process_file(filepath: str) -> dict:
    path = Path(filepath)

    sha256 = sha256_file(filepath)

    raw_manifest = read_c2pa(filepath)
    manifest_summary = summarize_manifest(raw_manifest) if raw_manifest else None

    proof = anchor_hash(sha256, path.name)

    record = {
        "file": path.name,
        "sha256": sha256,
        "c2pa": manifest_summary,
        "anchor": {
            "proof_id": proof.get("id"),
            "status": proof.get("status"),
            "certificate_url": proof.get("certificate_url"),
            "is_duplicate": proof.get("_is_duplicate", False),
            "duplicate_of": proof.get("duplicate_of"),
        },
    }

    sidecar = path.with_suffix(".proof.json")
    sidecar.write_text(json.dumps(record, indent=2))

    return record

if __name__ == "__main__":
    import sys
    for filepath in sys.argv[1:]:
        r = process_file(filepath)
        dup_note = " (duplicate)" if r["anchor"]["is_duplicate"] else ""
        print(f"{r['file']}: {r['anchor']['proof_id']}{dup_note}")

Run it on any files:

python c2pa_anchor.py site_photo.jpg inspection_report.pdf dashcam.mp4

Each file gets a .proof.json sidecar with the C2PA manifest summary (null if no credentials were present), the SHA-256, and the anchor record.

What You Have

For each file you process:

Original file, unchanged, on your machine
C2PA manifest summary when credentials are present: signing time, claim generator, assertion labels
SHA-256 anchored to a public ledger
A .proof.json sidecar tying both layers together

The C2PA layer tells you origin: which device, which pipeline, what the signing certificate says. The blockchain layer tells you existence: these bytes were recorded before anyone could dispute the timing.

Strip the C2PA data and the blockchain anchor still holds. The ledger doesn't care what happened to the file afterward.

C2PA coverage at the hardware level is growing. More files will arrive with credentials already embedded. Capturing those credentials alongside the anchor, before they get stripped somewhere downstream, adds maybe 20 lines to a file intake script.

One practical note: pin c2pa-python to a specific version in your requirements.txt. The SDK is actively developed and the API has changed between minor releases. Pin it, test it, and check the release notes before upgrading.

What format are the bulk of your incoming files? And are you seeing real C2PA credentials on production files yet, or mostly synthetic credentials in test images?

How Do Organizations Create Blockchain-Anchored Timestamps for Legal Evidence?

Craig Solomon — Wed, 19 Aug 2026 13:00:00 +0000

Organizations create blockchain-anchored timestamps for legal evidence by generating a SHA-256 hash of a file, then submitting that hash to a public blockchain network where it gets recorded in a specific block. The blockchain's timestamp becomes an independent, tamper-evident record showing the file (or rather, its fingerprint) existed at that exact moment, without the file itself ever leaving the organization's system.

That's the mechanism. The harder question is which method to use, and why it matters more than most people assume once a claim or dispute reaches discovery.

The Real Options for Timestamping Legal Evidence

A few approaches exist today, and they're not equally strong.

Notarization is the oldest method. A notary witnesses a signature and stamps a document with a date. It works for paper, it's legally recognized, and it doesn't scale to a folder of 400 site-inspection photos or a video file. Someone has to physically show up.

Cloud storage metadata (Google Drive upload dates, email timestamps, file system "created" dates) is what most people rely on by default. The problem: this metadata lives inside a system the organization itself controls, and it can be altered. A "created" date on a local file can be changed with a few clicks. Opposing counsel knows this, and it's the first thing a forensic examiner checks.

OpenTimestamps is a free, open protocol that anchors a file hash to the Bitcoin blockchain through a network of calendar servers. The cryptographic proof it produces is legitimate. What it lacks is a workflow: no hosted certificate, no branded verification page a claims adjuster or opposing counsel can open without technical setup, no case-organization layer. It's a proof format, not a documentation process.

C2PA Content Credentials takes a different approach. Backed by Adobe, Google, Meta, Microsoft, and OpenAI, C2PA embeds cryptographically signed provenance metadata directly inside a file, recording who captured it, when, with what device, and what edits followed. Samsung's Galaxy S25 and Google's Pixel 10 now sign photos at the camera level. The EU AI Act's Article 50 will require machine-readable content marking by August 2, 2026, and C2PA is the industry's chosen path there. Its limitation: the credential lives inside the file. Convert the format, strip metadata on upload to a platform, or transfer it the wrong way, and the credential can disappear before it ever reaches a courtroom.

Blockchain-anchored timestamping platforms anchor a file's hash externally, independent of the file itself. ProofLedger is one example built for this specifically: it hashes a file locally, anchors that hash to Polygon for an instant confirmation, and offers an optional Bitcoin anchor for additional immutability. Because the anchor lives on a public ledger rather than inside the file, it survives file transfers, format conversions, and platform re-uploads that would strip a C2PA credential.

Why Dual-Chain Anchoring Matters for Evidence

Anchoring to two independent networks is not redundancy for its own sake. Polygon confirms in seconds, which is useful when someone needs a timestamp immediately, at the moment of capture, not hours later. Bitcoin has processed blocks continuously since 2009 and represents a different kind of durability: rewriting Bitcoin's history would require overpowering more than half the network's accumulated proof-of-work, which is why it's treated as the gold standard for long-term immutability.

Anchoring to both means a single point of failure in one network doesn't undermine the record. If a party wants to attack the timing claim, they'd need to defeat two independently operated, publicly auditable systems, not one.

What a Blockchain Timestamp Does and Doesn't Prove

Here's where a lot of marketing overstates things, and where it matters to be precise for a legal or insurance audience.

A blockchain timestamp proves that a specific hash existed at a specific block, at a specific time. It does not, by itself, prove who created the file, what the file depicts, or that the file wasn't altered before it was hashed. It's a timing record, not a content authentication record.

Courts have a real framework for this. Under FRE 901(b)(9), evidence can be authenticated by showing it comes from "a process or system that produces an accurate result." That requires laying a foundation, typically expert testimony or a technical explanation of how the hashing and anchoring process works. It is not automatic. FRE 902(13) and 902(14), added in 2017, go further for machine-generated records: they allow self-authentication through written certification, without live testimony, if the certification meets the rule's requirements. These are the actual self-authentication rules, and they're worth citing by name if the goal is admissibility, not the more general 901(b)(9) process-reliability standard.

Pair a blockchain anchor with C2PA where possible and the two layers do different jobs. C2PA answers "who captured this, and with what." The anchor answers "did this exist before the date in question, and has anyone tampered with the record since." Neither replaces expert testimony. Both make that testimony easier to give.

How to Create a Blockchain-Anchored Timestamp, Step by Step

The process itself is simple, and that's intentional. It's the same regardless of file type, whether it's a 12-page inspection report or a multi-gigabyte site-walk video.

Hash the file locally. A SHA-256 hash is generated on the organization's own device. The file never uploads anywhere.
Submit the hash for anchoring. Polygon anchoring is free and unlimited on every tier. A Bitcoin anchor is available as a paid add-on for cases where the extra network adds value, litigation holds, high-value claims, anything likely to face a serious authentication challenge.
Receive a public verification record. A verify URL lets anyone (opposing counsel, an auditor, a claims examiner) confirm the hash independently, without needing an account or believing the organization's word for it.
Keep the certificate with the case file. Organized documentation, tagged by matter or claim number with loss-date context, is what turns a single proof into a defensible record months or years later when the dispute actually surfaces.

Teams that need this at scale (a claims department anchoring inspection photos across dozens of open files, or a firm handling recurring discovery production) can automate the process through a REST API, and developers can verify proofs offline with an open source verify-proof package rather than relying on a hosted page. Whatever the entry point, the underlying record works the same way: a hash, anchored publicly, checkable by anyone.

The choice isn't really between "blockchain or nothing." It's between a timestamp that lives only inside a system the organization controls, and one that exists independently of it. For evidence that might sit untouched for three years before a dispute even starts, that difference is the whole point. A tool like proofledger.io exists for exactly that gap: anchor the hash the day the evidence is captured, keep the file where it already lives, and have a record ready before anyone asks for one.

Beyond Authentication: FRE 803(6) and the Hearsay Problem in Blockchain Evidence

Craig Solomon — Mon, 17 Aug 2026 13:00:01 +0000

The authentication argument gets all the attention. FRE 901(b)(9), process reliability, blockchain cryptography. But admissibility has two separate problems, and the hearsay question is the one that catches practitioners off-guard.

Picture this: opposing counsel stipulates to authentication. They're not challenging whether the process was reliable or whether the hash matches the file. Their objection is hearsay. The proof certificate, they argue, is an out-of-court statement offered to prove when the file existed. Authentication doesn't answer that.

FRE 803(6) does.

Authentication and Hearsay Are Not the Same Problem

FRE 901(b)(9) authenticates evidence from a reliable process or system. FRE 902(13), added in 2017, handles that through written certification. No live testimony required. Both answer the same question: is this what it claims to be?

Hearsay is a different question. An out-of-court statement offered for the truth of the matter asserted runs into FRE 802 unless an exception applies. The business records exception under FRE 803(6) is the relevant one here. For blockchain timestamps, building both arguments before a dispute starts is worth the work.

What FRE 803(6) Actually Requires

The exception covers records of regularly conducted activity. For a record to qualify:

The record was made at or near the time of the event it describes
By or from someone with knowledge of that event
In the course of a regularly conducted business activity
Making the record was a regular practice of that activity
A records custodian can testify to those elements, or the record comes with certification under FRE 902(11) or 902(13)
The opponent can't show the source or circumstances indicate untrustworthiness

The timing element is the one that trips people up. "At or near the time" means contemporaneous with the event. A blockchain anchor created weeks after an inspection, or after demand letters are exchanged, loses the 803(6) argument. The exception is built for routine records, not retroactive documentation.

Two Records, Two Separate Analyses

A blockchain evidence situation involves two distinct records. Conflating them creates gaps.

The first is the blockchain entry itself. A Polygon transaction or Bitcoin merkle proof is a machine-generated output of a cryptographic process. Courts analyze that under FRE 901(b)(9) as evidence from a reliable process or system. It's a computational output, not a human assertion about what happened.

The second is the proof certificate or receipt that documents the connection between a specific file hash and a specific on-chain transaction. That certificate is created at the time of anchoring, typically by an automated system, and delivered to the party as a record of what was anchored and when. Opposing counsel who frames that certificate as hearsay isn't wrong to try. Authentication alone doesn't close that objection. The blockchain ledger entry and the certificate are separate records, and each has its own admissibility path.

The Stronger Argument Runs Through the Party's Own Records

I think the cleanest 803(6) path isn't built on the service provider's documentation. It's built on the party's own.

If a claims team, forensic firm, or law department adopts a written protocol to anchor evidence files at intake, the anchoring record becomes part of that organization's business records. Created at intake. By the person who received the file. In the regular course of evidence handling. As part of documented standard procedure. That's the structure 803(6) was designed to cover.

The foundation then runs through the organization's records custodian, not the blockchain service. And if the certification path under FRE 902(11) is available, the custodian doesn't need to testify. A written certification covering the four 803(6) elements handles it.

This is the argument that holds up in practice. The service provider's documentation structure isn't what makes it work. The party's own workflow is.

Layering the Rules

Each rule answers a different objection.

FRE 902(13) provides self-authentication for machine-generated records through written certification. That's the answer to "is the blockchain record authentic?" without live testimony. FRE 803(6) covers the hearsay objection to the proof certificate, when the anchoring was part of regular business practice. Process reliability under FRE 901(b)(9) supports both.

Dual-chain anchoring adds to the 901(b)(9) argument specifically. ProofLedger anchors to both Polygon and Bitcoin. Two independent blockchains, separate consensus mechanisms, both recording the same file hash at the same moment. Process reliability through redundancy is harder to attack than a single-source timestamp.

No single rule does everything. The practitioners who think through all three before a dispute are the ones who aren't scrambling during the opening hour of a hearing to explain why they skipped a step.

What This Means Monday Morning

If your organization anchors evidence files as part of standard practice, document the practice explicitly. A written policy covering who anchors, when, using what process, and where the records are kept gives the 803(6) foundation something to stand on. Undocumented workflows and inconsistent practice create gaps opposing counsel will use.

Anchor at the earliest point in the workflow. First inspection, first receipt, first capture. The business records timing element requires contemporaneous records. Anchoring after a dispute is anticipated changes the analysis entirely.

For the authentication layer, prepare the FRE 902(13) certification before you need it. A written certification describing the anchoring process, the cryptographic method, and the chain of custody for the records is more useful built in advance than assembled under deadline.

The hearsay objection to blockchain evidence isn't common yet. But the argument is available, and opposing counsel is learning. Building the 803(6) foundation now, while it's a procedural choice rather than a gap to patch, is the right time to do it.

Pre-Loss Documentation: Why File Timestamps Don't Prove Timing (And What Does)

Craig Solomon — Fri, 14 Aug 2026 13:00:00 +0000

A claims examiner is reviewing a disputed commercial property loss. The insured has submitted a folder of pre-loss photos. Good condition. No visible damage. Timestamps on the files read six months before the reported loss date.

File timestamps can be reset in under a minute. Cloud backups prove when a file was uploaded, not when it was shot. Nothing in that folder establishes provenance beyond reasonable doubt.

ProofLedger solves exactly that problem. Before the loss, when the policyholder anchors a photo or inspection report, a SHA-256 hash of that file is written to two blockchains: Polygon for instant confirmation and Bitcoin for proof-of-work immutability. The original file never leaves the device. What gets anchored is a cryptographic fingerprint, verifiable by anyone with the hash.

The documentation practice is straightforward. A commercial property owner anchors photos and inspection reports after each site visit through ProofLedger. Each anchor creates a timestamped record on Polygon within seconds and queues for the daily Bitcoin batch with a merkle proof tying it to that day's block. The property owner receives a certificate they can store with their policy documents.

When a claim comes in, the carrier's examiner doesn't have to take the insured's word for when the photos were taken. They verify the Bitcoin transaction independently. The timestamp on-chain predates the loss. The SHA-256 hash matches the file in the submission. That's a chain of custody built on temporal verification that no metadata manipulation can replicate.

Under FRE 901(b)(9), a blockchain record can be authenticated as the output of a process or system that produces an accurate result. Authentication still requires foundation, typically a technical declaration explaining how the anchoring process works. It's not self-authenticating under that rule. FRE 902(13) and 902(14) are the self-authentication provisions, applying to machine-generated records authenticated by written certification without live testimony.

For most insurance disputes, the practical question isn't litigation admissibility. It's whether the documentation survives a provenance challenge at the coverage review stage. Pre-loss anchoring shifts that burden. The insured isn't asking the carrier to trust a timestamp. The insured is pointing to a public ledger the carrier can verify independently.

One distinction that matters: a blockchain-anchored timestamp proves the file existed at a specific point in time. It doesn't prove ownership, identity, or the accuracy of what's depicted. The anchor is temporal verification, not a statement of truth about the underlying content. Carriers should evaluate it as one layer of documentation, alongside inspection records, purchase receipts, and policy history.

That's the point of neutral temporal authority. The ledger isn't vouching for the insured. It's establishing a fixed reference point that neither side can move.

Anchor before the loss, not after. Risk documentation, not claim documentation.

Watch-Folder Anchoring in Node.js: chokidar, Queues, and Rate-Limit Backoff

Craig Solomon — Thu, 13 Aug 2026 13:00:01 +0000

A file lands in an intake folder. You want a hash anchored to the blockchain the moment it arrives. Not batched overnight. Not manually triggered. Just: file detected, hashed, proof committed. While the file stays exactly where it is.

Here's how to build that service in Node.js. By the end you'll have a watcher that detects new files, streams them through SHA-256, queues API calls to stay under rate limits, and retries intelligently when limits are hit.

Why chokidar, and Why awaitWriteFinish Matters

Node's built-in fs.watch has platform inconsistencies and fires events before a file finishes writing. chokidar fixes both.

npm install chokidar

The critical option is awaitWriteFinish. Without it, a large upload triggers the add event while the file is still coming in. You hash an incomplete file. The anchor is wrong. Downstream verification fails.

import chokidar from 'chokidar';

const watcher = chokidar.watch('./intake', {
  persistent: true,
  ignoreInitial: false,
  awaitWriteFinish: {
    stabilityThreshold: 2000,  // ms of size stability before firing
    pollInterval: 200,
  },
});

watcher.on('add', (filePath) => {
  console.log(`Detected: ${filePath}`);
});

watcher.on('error', (err) => console.error('Watcher error:', err));

ignoreInitial: false means files already sitting in the folder when the service starts will be processed too. For a claims-intake pipeline, that's usually what you want. Startup should pick up anything that arrived while the service was down.

Streaming SHA-256 with Node's Built-In crypto

Don't load the whole file into memory. Stream it:

import { createHash } from 'crypto';
import { createReadStream } from 'fs';

async function sha256(filePath) {
  return new Promise((resolve, reject) => {
    const hash = createHash('sha256');
    const stream = createReadStream(filePath);
    stream.on('data', (chunk) => hash.update(chunk));
    stream.on('end', () => resolve(hash.digest('hex')));
    stream.on('error', reject);
  });
}

Output is always 64 hex characters. A 4KB text file and a 2GB video go through the same function. The hash doesn't care about file type or size.

A Queue for Backpressure

If 40 files land at once, a field inspector uploads a full photo set, you don't want 40 simultaneous API calls. Rate limits kick in immediately and cleanup gets messy.

A concurrency-limited queue handles this without extra dependencies:

class Queue {
  constructor(concurrency = 3) {
    this.concurrency = concurrency;
    this.running = 0;
    this.pending = [];
  }

  add(task) {
    return new Promise((resolve, reject) => {
      this.pending.push({ task, resolve, reject });
      this.drain();
    });
  }

  drain() {
    while (this.running < this.concurrency && this.pending.length > 0) {
      const { task, resolve, reject } = this.pending.shift();
      this.running++;
      Promise.resolve()
        .then(() => task())
        .then(resolve, reject)
        .finally(() => {
          this.running--;
          this.drain();
        });
    }
  }
}

const queue = new Queue(3);

Three concurrent calls is a reasonable default. The drain() method refills slots as tasks complete, so the queue drains at whatever pace the API allows.

Calling the Anchoring API

ProofLedger's v1 endpoint takes a SHA-256 hex string and an optional filename. On success it returns a proof record including a hosted certificate URL. On a duplicate submission it returns 409 with a duplicate_of field. The ID of the first anchor for this hash.

import path from 'path';

const ANCHOR_ENDPOINT = 'https://proofledger.io/api/v1/proof';
const API_KEY = process.env.ANCHOR_API_KEY;

async function anchor(filePath) {
  const digest = await sha256(filePath);
  const filename = path.basename(filePath);

  const res = await fetch(ANCHOR_ENDPOINT, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ sha256: digest, filename }),
  });

  if (res.status === 409) {
    const body = await res.json();
    console.log(`Already anchored: ${filename} (original: ${body.duplicate_of})`);
    return { duplicate: true, original: body.duplicate_of };
  }

  if (!res.ok) {
    const err = new Error(`API error: ${res.status}`);
    err.status = res.status;
    if (res.status === 429) {
      err.retryAfter = res.headers.get('Retry-After') || '5';
    }
    throw err;
  }

  const proof = await res.json();
  console.log(`Anchored: ${filename}`);
  console.log(`  Proof ID: ${proof.id}`);
  console.log(`  Certificate: ${proof.certificate_url}`);
  return proof;
}

certificate_url is a hosted proof page. Readable by anyone, no authentication required. When a dispute comes up later, that URL is what you share.

Native fetch is available in Node 18+. For Node 16, install node-fetch and the import is the same.

Retry Logic: Separating Retriable Errors from Fatal Ones

Not all errors should retry. A 400 means malformed input. Retrying won't fix it. A 401 or 403 means your credentials are wrong or your plan doesn't include API access. Those are not transient.

A 429 is different. Wait for the Retry-After header, then continue.

async function anchorWithRetry(filePath, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await anchor(filePath);
    } catch (err) {
      const status = err.status;

      if (status === 400 || status === 401 || status === 403) {
        console.error(`Non-retryable error ${status}: ${path.basename(filePath)}`);
        throw err;
      }

      if (status === 429) {
        const waitSec = parseInt(err.retryAfter || '5', 10);
        console.warn(`Rate limited. Waiting ${waitSec}s (attempt ${attempt}/${maxAttempts})`);
        await sleep(waitSec * 1000);
        continue;
      }

      // Network errors, 5xx — exponential backoff
      const backoff = Math.min(1000 * 2 ** attempt, 30000);
      console.warn(`Attempt ${attempt} failed: ${err.message}. Retry in ${backoff}ms`);
      await sleep(backoff);
    }
  }

  throw new Error(`All ${maxAttempts} attempts failed: ${path.basename(filePath)}`);
}

function sleep(ms) {
  return new Promise((r) => setTimeout(r, ms));
}

Capping backoff at 30 seconds keeps recovery reasonable without hammering the API during an outage.

Wiring It Together

import chokidar from 'chokidar';
import { createHash } from 'crypto';
import { createReadStream } from 'fs';
import path from 'path';

const INTAKE_DIR = process.env.INTAKE_DIR || './intake';
const API_KEY = process.env.ANCHOR_API_KEY;

if (!API_KEY) {
  console.error('ANCHOR_API_KEY is not set');
  process.exit(1);
}

const queue = new Queue(3);

const watcher = chokidar.watch(INTAKE_DIR, {
  persistent: true,
  ignoreInitial: false,
  awaitWriteFinish: {
    stabilityThreshold: 2000,
    pollInterval: 200,
  },
});

watcher.on('add', (filePath) => {
  queue
    .add(() => anchorWithRetry(filePath))
    .catch((err) => {
      console.error(`Final failure for ${path.basename(filePath)}: ${err.message}`);
    });
});

watcher.on('error', (err) => console.error('Watcher error:', err));

console.log(`Watching ${INTAKE_DIR} for incoming files...`);

Run it:

ANCHOR_API_KEY=sk_YOUR_KEY_HERE node service.mjs

Drop a file into ./intake/. It gets detected, hashed, and anchored. Duplicates are logged and skipped. Rate limits are respected. The certificate URL hits stdout for every successful anchor.

What to Add Before Production

The service above handles the core flow. A few patterns worth layering on:

SQLite state tracking. If the service restarts mid-batch, in-flight work is lost. A single-table SQLite database, file path, SHA-256 digest, proof ID, status, lets you skip already-anchored files on startup. Check before calling anchor().

Startup sweep. ignoreInitial: false already replays existing files. Pair it with the database check and the service self-heals: files that arrived while it was down get anchored on next start, files already anchored get skipped.

JSON logs. In production, emit structured log objects with filePath, digest, proofId, anchoredAt, and durationMs. Easier to query later when you need to find a specific file's proof record.

The core service is around 80 lines. Enough to drop in front of a claims-intake upload folder, a document export directory, or any pipeline where files arrive asynchronously and timing matters.

For offline verification against a proof JSON file, the verify-proof PyPI package handles it without network calls: github.com/Fulcrum-Enterprises/verify-proof

What does your file-intake setup look like? Curious whether people are handling backpressure with a library like p-queue or rolling their own.

How Forensic Consultants Create Verifiable Digital Evidence Records

Craig Solomon — Wed, 12 Aug 2026 13:00:05 +0000

A forensic consultant's verifiable record has to answer two questions: did this file change, and when did it exist? SHA-256 hashing at acquisition answers the first. Chain of custody documentation, methodology reports, and blockchain anchoring address the second.

Hash Verification: The Technical Foundation

SHA-256 is the current standard for digital evidence integrity. It's a one-way function: run any file through the algorithm and you get a fixed-length string. Change a single byte and the hash changes completely. A year later, that same unmodified file produces the same string.

Write-blockers handle the acquisition side. Hardware or software write-blockers prevent any data from being written to original storage media during imaging. A forensic consultant creates a bit-for-bit copy, hashes both the original and the copy, and records that both hashes match. The original is preserved exactly as found.

Tools like FTK Imager, EnCase, and Autopsy automate this workflow. They log acquisition time, hardware identifiers, hash values, and tool version. That log becomes part of the case file.

Chain of Custody: The Procedural Layer

Technical integrity doesn't stand alone. Every transfer of evidence gets documented: who received it, from whom, at what time, under what conditions. Evidence storage has to be secure and logged. Any analysis performed on the evidence gets recorded with the methodology, the tools used, and the findings.

This procedural record exists separately from hash verification. Both matter for admissibility. The hash proves the file wasn't modified. The custody log proves the file was handled properly.

Forensic Reports and Methodology Documentation

Forensic conclusions have to survive challenge. That means explaining the tools used (including version numbers), the methodology followed, the findings, and how those findings were reached.

Under Daubert, courts evaluate whether expert methodology is scientifically valid and reliably applied. A forensic expert who can't explain the acquisition process, or who used improperly validated tools, is vulnerable to a methodology challenge before the findings ever reach the jury.

Courts authenticate digital evidence under FRE 901(b)(9), which allows authentication of evidence produced by a process or system that generates an accurate result. This requires laying a foundation: typically, expert testimony explaining the methodology, the tools, and why the output is reliable. That's not self-authentication. Self-authentication for machine-generated records comes through FRE 902(13) and FRE 902(14), which allow written certification in place of live testimony.

File System Timestamps: What They Don't Prove

EXIF data in a photo might show a creation date. File system metadata shows access and modification times. Both are useful starting points. Neither is authoritative.

File system timestamps can be changed, and EXIF data can be stripped or edited during transfer. Moving a file from one device to another often updates the modification timestamp. A challenge that targets metadata will raise doubt about any timestamp that lives inside the file or on the same storage medium as the file.

Forensic consultants document these limitations in their reports. A hash proves the file's content is unchanged. It doesn't independently establish when that content was created.

Blockchain Anchoring: An Independent Temporal Record

Anchoring the hash to a public blockchain provides a timestamp that's external to the file and to the consultant's own infrastructure.

The mechanism: compute the SHA-256 hash of a file, submit it to a blockchain network, and receive a transaction record with a block timestamp. The blockchain can't be retroactively altered. Anyone with the file and the transaction record can independently verify that a file with that exact hash existed at that block timestamp.

Options exist at different usability levels. OpenTimestamps offers free Bitcoin anchoring and its proof is cryptographically sound. The tradeoff is usability: the output requires technical tools to verify, and there's no hosted verification page that a judge, opposing counsel, or claims examiner can read without specialized knowledge.

ProofLedger anchors to both Polygon (instant confirmation) and Bitcoin (daily batch with Merkle proofs). The file stays with the consultant. Only the hash goes on-chain. Each anchor produces a public verification URL and a certificate usable by non-technical parties, which matters when the end audience is litigation counsel or a claims department rather than a technical peer. Professional and Business plans include a REST API for workflows that need automated anchoring at acquisition.

A blockchain anchor doesn't make evidence automatically admissible. Under FRE 901(b)(9), the proponent still needs to explain the process: what was hashed, when, how the transaction was recorded, and how the blockchain timestamp can be read. What the anchor provides is a timestamp from an independent system with no incentive to backdate.

Combining the Layers

A forensic consultant building a complete verifiable record works with several layers together:

Write-blocked acquisition with logged hash values
A custody log documenting every transfer and handler
Detailed methodology documentation for expert reports
Blockchain anchoring of file hashes at the time of acquisition

Each layer addresses a different vulnerability. The write-blocker and hash protect against undetected modification. The custody log addresses handling and access questions. The methodology documentation supports Daubert review. The blockchain anchor supplies a timestamp that doesn't depend on the file's own metadata.

For disputed matters, the strength of the record depends on how early in the process these steps were applied. An anchor taken the day evidence is acquired is harder to challenge than one taken weeks later.

Practical Considerations for Forensic Consultants

Not every court treats blockchain timestamps identically. A forensic consultant should be prepared to explain the process plainly: what a blockchain is, why the timestamp is reliable, and how the transaction can be independently verified. Some courts will require live testimony under FRE 901(b)(9); in others, written certification under FRE 902(13) or FRE 902(14) may be sufficient to authenticate without calling a witness.

Practices adequate for civil matters may not survive criminal discovery. Chain of custody standards, methodology requirements, and admissibility thresholds are higher in criminal proceedings. Consultants who work across both contexts should apply the more stringent standard throughout.

The tools keep improving. The underlying principle doesn't: verifiable digital evidence requires both technical integrity and procedural rigor. The hash proves nothing changed. The custody log proves the right people handled it correctly. The anchor proves it existed when you say it did.

For consultants who want dual-chain anchoring with a public verification page non-technical parties can actually read, proofledger.io is worth exploring. Polygon anchoring is free on every plan.