Skip to main content
Every document Blockgence issues comes out sealed: evidence packages, freeze requests, post-mortems, incident deliverables and Monero payment proofs. The seal has three pieces. Each one proves something different, and none of them proves that the content is true:
What a document says is backed by the published methodology, the sources it cites and what the document itself declares it could not see. The seal does not replace that.

Where the seal lives

Everything is in manifest.integrity. The fingerprint covers the whole document except manifest.integrity, since a hash cannot cover itself. That is why the signature and the timestamp go inside integrity, under attestations, and do not invalidate each other.
The values in this example are illustrative. The text fields inside a document (covers, recipe, the notes) are written in Spanish.

1. The content fingerprint

A JSON document can be reordered or re-indented without changing its meaning, which would break any hash “of the file”. So the fingerprint is computed over a published canonical form that can be reproduced without Blockgence’s code:
1

Remove the integrity section

Take the whole document and remove manifest.integrity.
2

Serialize in canonical form

JSON with keys sorted alphabetically at every level, , and : separators with no spaces, and unescaped UTF-8.
3

Apply sha256

The resulting hex is manifest.integrity.digest. Any change to the content (an amount, a confidence, a date) changes it.
The recipe also travels inside every document, in manifest.integrity.recipe.
Declared limit. Decimal numbers are written with the shortest representation that round-trips to the same value, which is what Python and JavaScript emit. Other languages may differ in exponent notation (1e-07 vs 1e-7). For the values in a package (amounts, confidences, percentages) this does not happen in practice. If it did, the reference is the document’s canonical bytes.

2. Blockgence’s signature

The fingerprint alone does not say who issued the document. The signature binds that fingerprint to Blockgence’s key.
  • Algorithm: Ed25519 (RFC 8032).
  • Signed message: the ASCII bytes of blockgence-integrity-v1:sha256: followed by the fingerprint in hex. The prefix pins the fingerprint algorithm and keeps the signature from being reused for anything else.
  • Where it is: manifest.integrity.attestations.signature, with:
    • key_id: the sha256 of the public key’s 32 bytes;
    • the public key, in base64 (public_key) and PEM (public_key_pem);
    • the signature in base64 (value);
    • the recipe to verify it, including one with OpenSSL (verify_openssl).
The public key travels inside the document so it can be verified without asking for it, but on its own it proves nothing: anyone can strip the signature and sign with their own key. What proves Blockgence issued it is that its key_id matches the public key we publish.
Whoever verifies rebuilds the message from the fingerprint they recompute from the content. They never use the fingerprint or the message the document carries: integrity is not covered by the fingerprint and anyone can edit it. If the server that issued the document had no signing key configured, signature is null and signature_note says why. In that case the fingerprint proves the document has not changed, but not who issued it.

3. The timestamp (optional)

The signature does not prove when a document was issued: manifest.generated_at is set by the system itself. The timestamp anchors the fingerprint in Bitcoin with OpenTimestamps.
The timestamp is off by default: the server operator turns it on. When it is off, the document is issued anyway, with timestamp: null and a note in timestamp_note. Documents built from simulated data are not timestamped either.
When it is on:
  1. When sealing, a 32-byte commitment is sent to the OpenTimestamps calendars, and the proof is stored as pending inside the document. The two calendars operated by opentimestamps.org are used.
  2. A few hours later, the calendars include the commitment in a Bitcoin transaction. The server completes the proof on its own, once an hour.
  3. The delivered document does not change. The complete proof is downloaded separately, as an .ots file, from GET /v1/evidence/timestamp/{digest}.ots.
What leaves the machine. Each calendar receives a single 32-byte request: sha256(fingerprint || nonce), with a random 16-byte nonce that stays in the proof and is never sent. Neither the content, nor the fingerprint itself, nor any case data is sent.
What it proves, once complete: that the document’s fingerprint already existed when the Bitcoin block cited by the proof was mined. While the proof is pending it proves nothing yet: it only records that the timestamp was requested. The proofs Blockgence produces are read and verified by the official OpenTimestamps client (ots verify).

The complete proof

Two open routes, with no API key and no credits:
  • The status returns status (pending or complete), the Bitcoin blocks that anchor the proof with their merkle_root, the calendars, the dates and how to verify.
  • The file comes with the X-OTS-Status header.
  • While it is still pending, each request tries to complete it, at most once every 10 minutes per fingerprint.
  • Errors: 404 if that server did not seal that fingerprint; 400 if the name is not a hex sha256.

Which methodology version

Every document cites the methodology it was built with, in manifest.methodology: its version (version), a fingerprint of its actual parameters (fingerprint) and how many entries it has. The package also carries the entries that analysis used. See Methodology changelog.

Next step

Verify a signature

Step by step, with Python 3 and OpenSSL, with no account and without Blockgence’s code.

Public key

The current fingerprint, where it is published and what happens if it changes.