A CV That Outlives the Startup: Anchoring Freelance Work in Bitcoin With OpenTimestamps
A freelancer's CV has a trust problem. Anyone can type "shipped a payments platform" and attach a screenshot. Even when a platform verifies the work, that verification is just a row in the platform's database. What happe
A freelancer's CV has a trust problem. Anyone can type "shipped a payments platform" and attach a screenshot. Even when a platform verifies the work, that verification is just a row in the platform's database. What happens when the platform shuts down, gets acquired, or quietly edits the row?
Ganji is a freelance platform built around Bitcoin Lightning escrow, with a reputation that travels with the freelancer. Each freelancer has a Live CV built from deals that were completed and released. We wanted it to make a much narrower but much stronger promise:
This exact file existed, with exactly these bytes, no later than a specific moment in Bitcoin history. Anyone can check it, forever, without asking us for permission.
That is what OpenTimestamps (OTS) gives us. In this post I'll walk through the pipeline in our Go backend, where the trust boundaries are, and the gap we closed by verifying against the real chain instead of trusting the receipt alone.
Step 1: Reduce the Work to a Fingerprint
We never timestamp a whole file. We hash its contents with SHA-256 and store the 64-character hex digest as the CV entry's hash.
r, err := s.store.Open(ctx, c.StorageKey)
if err != nil {
return err
}
defer r.Close()
h := sha256.New()
if _, err := io.Copy(h, r); err != nil {
return err
}
digest := h.Sum(nil) // 32 bytes
The details matter. We hash the bytes in the blob, not the storage key or a filename. One changed byte produces a completely different fingerprint, so the hash is the file's identity for verification purposes. This was a real bug in an earlier version: hashing the key told you nothing about whether the deliverable had been swapped.
The hash is written when a deal is released after the client approves the work, alongside verified_at. Milestone mode complicates the picture slightly. A milestone can carry its own tagged artifacts (artifacts.milestone_id), but the current anchoring runs once at deal release over the deal's artifacts. That is an honest scope boundary, not a claim that every milestone is individually notarized.
Both the approve path and a self-healing read path call the same insertAnchors function. If the approve-time hook fails, the next CV read finds released deals with missing anchors and writes them then. Derived data should never take down a public profile.
Step 2: Send the Fingerprint to a Notary
OpenTimestamps is a cheap way to get a fingerprint committed to a Bitcoin block. Think of it as a notary that handles many documents at once:
- We
POSTthe raw 32-byte digest to a public calendar such asa.pool.opentimestamps.org. Only the hash leaves our servers. - The calendar does not store our file. It combines our digest with everyone else's digests from the same period into a Merkle tree.
- Periodically, the calendar commits that tree's root, a single 32-byte number, in a Bitcoin transaction.
- Right away, the calendar returns a receipt that says, in effect, "your digest is in the batch I am about to commit." We wrap it in a standard
.otsfile.
file bytes ββsha256βββΆ digest ββPOST /digestβββΆ calendar
β
Merkle root of many digests
β
Bitcoin transaction
β
pending receipt now, Bitcoin proof later
That first receipt is pending: it has a calendar attestation but no Bitcoin block height yet. We serialize the complete .ots file and store it in cv_entries.ots_proof, with ots_submitted_at.
Submission is best-effort by design. It runs in a goroutine with a 60-second timeout, and failure is logged, not propagated. If the calendars are down, the CV still works: the SHA-256 anchor is intact and OTS simply did not happen on this entry. A free notary service should never become a hard dependency of your product.
Step 3: Wait for Bitcoin, Then Upgrade the Receipt
Calendars commit in batches, and confirmation typically takes a few hours, so a pending proof is not useful on its own yet. A background worker runs UpgradeOTSProofs at boot and then every six hours. For each row with a proof but no ots_confirmed_at, it:
- Parses the
.otsfile and finds the pending sequence. - Computes the commitment: the value the proof reaches at the pending attestation, which is the key the calendar looks up.
- Sends a
GETto<calendar>/timestamp/<hex-commitment>. - Treats a
404as "not committed yet": it returnsErrProofNotReady, skips the row, and retries next cycle. - Treats a
200as success. The calendar has returned the Bitcoin tail, the Merkle path and the transaction. We splice it onto the pending sequence and re-serialize the proof.
On success we set ots_confirmed_at. The receipt now carries a real block height, and the entry is no longer just "a hash we recorded". It is a hash publicly committed in Bitcoin history.
Step 4: Verify at Two Trust Levels
This is the part we are most opinionated about. A receipt that claims you are in block 891686 is not the same as actually being in block 891686.
Level 1: Offline Replay
ots.VerifyProof needs no network and no Ganji service. It:
- parses the
.otsfile; - checks that the digest embedded in the proof equals the artifact hash we are verifying (
bytes.Equal(file.Digest, hash)); - replays every operation in the sequence, requiring a well-formed embedded Bitcoin transaction and a 32-byte block Merkle root;
- reports the lowest attested block height.
That proves the receipt is internally consistent and commits to this exact hash. It does not prove the block exists. A buggy or malicious calendar could hand out a well-formed receipt for a block that never happened.
Level 2: Check the Real Chain
When OTS_ESPLORA_URL is configured, Verifier.Verify goes further. For each Bitcoin-attested sequence, it fetches the actual block header at the attested height and compares the header's Merkle root with the root computed from the proof:
if !bytes.Equal(root, header.MerkleRoot[:]) {
return 0, time.Time{}, fmt.Errorf(
"ots: chain verification failed at block %d", att.BitcoinBlockHeight)
}
A match means the hash is genuinely anchored in Bitcoin, and we also get the block header's timestamp. A mismatch fails verification outright. It means a calendar bug, a forgery, or, very rarely, a block that was orphaned in a chain reorganization.
Be aware of what this step trusts: the Esplora server you point it at. For full independence, run your own instance or a Bitcoin node.
If the chain source is merely unreachable, we degrade gracefully. We keep the offline result, set ChainErr, log it, and fall back to the worker-recorded confirmation time, which is a weaker claim because it records when our worker noticed the confirmation, not when the block was mined.
The public verification endpoint returns both layers: the live hash comparison (does the stored hash still match the current file bytes?), plus ots_verified, ots_block_height, and ots_confirmed_at. If the blob behind the storage key is swapped, the hash comparison fails even if the receipt itself is valid. That is detection, not prevention, but detection is what a verifier needs.
What This Actually Proves, and What It Doesn't
It is tempting to oversell blockchain timestamps, so we try to be precise.
Proves:
- The artifact existed with exactly these bytes no later than the attested block.
- The CV line is cryptographically tied to that file: both the stored hash and the proof's digest must match.
- Nobody, including us, can backdate an entry by editing our database. Editing can remove or replace a receipt, but it cannot produce a valid receipt for an earlier block.
Does not prove:
- Who uploaded the file. OTS timestamps facts, not identities.
- When it was submitted, beyond "before roughly the block's timestamp". Block timestamps are set by miners and can be off by up to about two hours, so treat them as approximate.
- That the block exists, if you skip the chain check. Offline-only verification trusts the calendar's claim.
- That the chain source is honest. The chain check is only as trustworthy as the Esplora server or node behind it.
- That the storage key never changed. We detect a swapped blob; we do not make the swap impossible.
A useful property falls out of this design. Anyone holding the exported .ots receipt and the original file can re-prove the timestamp with any OpenTimestamps tool against the public blockchain, even if Ganji disappears. The receipt is portable trust.
Notes From the Implementation
Trust score is derived, not asserted. We recompute it from released deals on every profile read (base 100, +25 per released deal, capped at 1000). If the refresh fails, we show the stored value and log. A reputation number should be a cache of verifiable facts, not a new source of authority.
The test fixture is a real proof. Our OTS tests use a real OpenTimestamps project file whose digest is committed at block 891686. The offline verify test replays it, a fake chain exercises the confirm, mismatch, and degrade paths, and the CV service test drives the whole stack through VerifyEntry. That fixture is the shortest end-to-end evidence that the arithmetic is right.
Size is not a problem. Real proofs are small, on the order of kilobytes. We cap parsed calendar responses at 1 MiB to keep public endpoints safe, but in practice a receipt is tiny compared with the deliverable it describes.
The Bigger Lesson
We did not need a blockchain to store files, to run a reputation system, or to replace Postgres. We needed one very specific thing: a cheap, public, immutable "this fingerprint existed by then" receipt that a stranger can verify without trusting our company.
OpenTimestamps gives us that, with no per-artifact on-chain fee for us, because many digests share one Bitcoin commitment. The engineering work is mostly around the edges: hashing the right bytes, making submission non-blocking, upgrading pending proofs, and, critically, checking the receipt against the real chain before calling it confirmed.
If you are building anything that says "verified" on a public page, ask yourself what a stranger could actually check after your servers are gone. That question shaped more of this design than any library choice.
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.