> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How a report is sealed

> The sha256 fingerprint of the content, Blockgence's Ed25519 signature and the optional Bitcoin timestamp: what each one proves and what it does not.

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:

| Piece | What it proves | What it does not prove |
| - | - | - |
| **Fingerprint** (`sha256`) | That the document has not changed since it was sealed. | Who issued it: anyone can alter the content and recompute the fingerprint. |
| **Signature** (Ed25519) | That it was issued by whoever holds Blockgence's private key, and has not changed since it was signed. | When it was issued, or that the content is true or complete. |
| **Timestamp** (OpenTimestamps, optional) | That the fingerprint already existed when a Bitcoin block was mined. | Who issued it, or the exact time: it gives an upper bound. |

> [!NOTE]
>
> 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.

```json theme={null}
{
  "schema": "blockgence.evidence/v1",
  "manifest": {
    "generated_at": "2026-11-20T14:03:11Z",
    "methodology": { "version": "2026.11.17w", "fingerprint": "576c6f78dc064d0c", "entries_total": 167 },
    "simulated_data": false,
    "integrity": {
      "algorithm": "sha256",
      "canonicalization": "json:sort_keys=true,separators=(',',':'),ensure_ascii=false,utf-8",
      "covers": "todo el documento excepto manifest.integrity",
      "digest": "e32f85d26c8709a0…",
      "recipe": ["1. Quitar manifest.integrity del documento.", "…"],
      "attestations": {
        "signature": { "algorithm": "ed25519", "key_id": "sha256:d8853d1c…", "value": "…", "…": "…" },
        "timestamp": null,
        "timestamp_note": "Sin sello de tiempo de un tercero: …"
      }
    }
  }
}
```

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`.

> [!WARNING]
>
> **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`).

> [!WARNING]
>
> 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](https://docs.blockgence.com/en/methodology/public-key.md).

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](https://opentimestamps.org).

> [!NOTE]
>
> 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`](#the-complete-proof).

> [!NOTE]
>
> **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:

```bash Status (JSON) theme={null}
curl https://app.blockgence.com/v1/evidence/timestamp/e32f85d26c8709a0...
```

```bash .ots file theme={null}
curl -O https://app.blockgence.com/v1/evidence/timestamp/e32f85d26c8709a0....ots
```

* **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](https://docs.blockgence.com/en/methodology/changelog.md).

## Next step

> [card] [Verify a signature](https://docs.blockgence.com/en/methodology/verify-signature.md)
>
> Step by step, with Python 3 and OpenSSL, with no account and without Blockgence's code.

> [card] [Public key](https://docs.blockgence.com/en/methodology/public-key.md)
>
> The current fingerprint, where it is published and what happens if it changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.