How Graven works

Graven never stores your file unless you explicitly ask us to. We work with a cryptographic fingerprint of your document called a SHA-256 hash: a 64-character string that is unique to the exact bytes of that file. Change a single pixel, comma, or byte, and the fingerprint changes completely.

1. You upload a file. Your browser sends it to our server over HTTPS.
2. (Optional) We embed an invisible watermark. For images, PDFs, and text, we can hide a short identifier inside the file itself so even copies remain traceable.
3. We compute the fingerprint of the final bytes.
4. We anchor it on Polygon (a public blockchain). The fingerprint, the time, your account address, and whether the record is revocable get recorded in a smart contract.
5. You distribute the file however you normally would — email, signed PDF, shared link, printed copy.
6. Anyone can verify it later by dropping the file (or just its hash) into our public verify page. They do not need an account.

Sign in

Sign-in is handled by Clerk. You can use email + password, passwordless magic links, or a connected social account, depending on what your administrator has enabled. You only need an account to anchor or manage documents. Verification is public.

Anchor a document

Go to /anchor. Choose the file and pick:

• Type — Revocable records can be cancelled later by you (the issuer). Irrevocable records are permanent and cannot be undone, by anyone, ever. Use irrevocable only when the document is final.
• Embed invisible watermark — modifies the file before hashing so the watermark and the anchor describe the same bytes. You will be offered a download of the watermarked copy, which is the one you should distribute.
• Watermark mode — Auto-detect picks the right algorithm from the file's MIME type. Force image/text/PDF only if you know the auto guess is wrong.
• Store an encrypted copy — only available if you opted into storage in Settings.

View documents

/dashboard lists every document you have anchored, newest first. Click one to see its hash, transaction hash, block number, issuer address, and status. From the detail page you can revoke (if revocable and not already revoked) and download (if you stored an encrypted copy).

Revoke

Revoking a revocable document does not remove the anchor — the original record stays on-chain forever. Instead, a second transaction marks it revoked, and from that moment on, anyone verifying the file will see status REVOKED with the revocation timestamp. Use this when a document is superseded, leaked, or invalidated.

Anyone can verify a file at /verify without signing in. Two ways:

• Drop the file. Your browser uploads it to our server. We first try to extract a watermark; if found, we resolve to the original anchored hash even if the bytes were modified. Otherwise we fall back to hashing the file directly.
• Paste the SHA-256 hash. Useful if you already computed the hash yourself and do not want to share the file.

Result statuses

• ANCHORED

  The file matches a registered hash and has not been revoked. You will also see the issuer's blockchain address, the original filename, the issuance time, and (if available) the uploader's email.

• REVOKED

  The file was anchored at some point but the issuer has since revoked it. Treat the document as no longer valid.

• NOT REGISTERED

  The hash is not on-chain. Either the file has been modified (even a single byte), or it was never anchored in the first place.

From /api-keys you can create tokens to drive Graven from your own code. Keys look like:

dik_live_a1b2c3d4e5f6…  (64 hex chars after the prefix)

• The plaintext is shown exactly once when you create it. We only ever store a hash of the key — if you lose it, revoke it and create a new one.
• Revoked keys stop working immediately but are kept in your audit log.
• Send the key as Authorization: Bearer dik_live_….

Example

curl -X POST https://<your-graven-host>/v1/programmatic/documents \
  -H "Authorization: Bearer dik_live_…" \
  -F "file=@./contract.pdf" \
  -F "doc_type=revocable"

Graven's core promise is provability, not storage — by default we only keep the on-chain fingerprint and metadata, never your bytes. If you want a managed copy as well, you can opt in from Settings. Two gates apply:

1. You must enable storage on your account once.
2. For each upload, you must tick “Store an encrypted copy.” The toggle is off by default to avoid accidental uploads of sensitive material.

Files are stored with server-side encryption (SSE) in object storage. Download links are short-lived (≈ 5 minutes) and bound to your account.

What is a hash?

A SHA-256 hash is a deterministic, fixed-length fingerprint of any input. Identical inputs always yield identical hashes; different inputs almost certainly yield different hashes. It is computationally infeasible to (a) reverse a hash back to the original file or (b) construct a second file that hashes to the same value. That is why anchoring a hash is equivalent to anchoring the file's identity without revealing its contents.

What is anchoring?

Anchoring means writing the hash to a public blockchain. We use Polygon — an Ethereum-compatible network — because it is fast, cheap, and globally readable. The record is stored in a smart contract that anyone in the world can independently query. Graven does not need to be online for verification to succeed; the proof lives on the chain.

Revocable vs. irrevocable

We deploy two separate smart contracts:

• Irrevocable — once written, the record is permanent and immutable. Suitable for credentials, diplomas, published articles, audit reports.
• Revocable — the issuer (and only the issuer) can later mark the record revoked. The original anchor still exists; the revocation is a second event layered on top. Suitable for contracts, policies, anything that may be superseded.

What is the watermark?

A watermark embeds a short identifier into the file in a way that is invisible to humans but detectable by software:

• Images / PDFs — we modulate certain frequency coefficients in the discrete cosine transform (DCT) of the image. The visible image is unchanged to the eye but a short ID can be extracted later, even after re-saving as JPEG or taking a screenshot.
• Plain text — we insert zero-width Unicode characters between letters. They render as nothing but survive copy/paste in most editors and messaging apps.

Watermarking is complementary to anchoring. The anchor proves “these exact bytes are registered.” The watermark proves “this content, even if rescaled or recompressed, traces back to the registered record.”

Architecture, in one diagram

Browser  ──HTTPS──►  Portal (Next.js)  ──►  BFF (Go)  ──►  Polygon
                                              │
                                              ├──►  Watermark service
                                              └──►  Encrypted storage (opt-in)

The browser never talks to the blockchain directly. The BFF (backend-for-frontend) holds the credentials, brokers the transactions, and is the only component allowed to spend gas.