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

# Cómo se sella un informe

> La huella sha256 del contenido, la firma Ed25519 de Blockgence y el sello de tiempo opcional en Bitcoin: qué prueba cada uno y qué no.

Cada documento que emite Blockgence sale **sellado**. Son paquetes de evidencia, pedidos de congelamiento, post-mortems, entregables de incidentes y pruebas de pago en Monero.

El sello tiene tres piezas. Cada una prueba algo distinto, y ninguna prueba que el contenido sea verdadero:

| Pieza | Qué prueba | Qué no prueba |
| - | - | - |
| **Huella** (`sha256`) | Que el documento no cambió desde que se selló. | Quién lo emitió: cualquiera puede alterar el contenido y recalcular la huella. |
| **Firma** (Ed25519) | Que lo emitió quien tiene la clave privada de Blockgence y que no cambió desde que se firmó. | La hora de emisión, ni que el contenido sea verdadero o completo. |
| **Sello de tiempo** (OpenTimestamps, opcional) | Que la huella ya existía cuando se minó un bloque de Bitcoin. | Quién lo emitió, ni la hora exacta: da una cota. |

> [!NOTE]
>
> La veracidad de lo que dice un documento la sostienen la metodología publicada, las fuentes que cita y lo que el propio documento declara que no pudo ver. El sello no la reemplaza.

## Dónde va el sello

Todo vive en `manifest.integrity`. La huella cubre **todo el documento excepto `manifest.integrity`**: un hash no puede cubrirse a sí mismo. Por eso firma y sello de tiempo van adentro de `integrity`, en `attestations`, y no se invalidan entre sí.

```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: …"
      }
    }
  }
}
```

Los valores de este ejemplo son ilustrativos.

## 1. La huella del contenido

Un JSON se puede reordenar o re-indentar sin cambiar su significado, y eso rompería cualquier hash «del archivo». Por eso la huella se calcula sobre una **forma canónica** publicada, que se puede reproducir sin el código de Blockgence:

**1. Quitar la sección de integridad**

Tomar el documento completo y quitar `manifest.integrity`.

**2. Serializar en forma canónica**

JSON con las claves ordenadas alfabéticamente en todo nivel, separadores `,` y `:` sin espacios, y UTF-8 sin escapar.

**3. Aplicar sha256**

El hex resultante es `manifest.integrity.digest`. Cualquier alteración del contenido (un monto, una confianza, una fecha) lo cambia.

La receta viaja también dentro de cada documento, en `manifest.integrity.recipe`.

> [!WARNING]
>
> **Límite declarado.** Los números con decimales se escriben con la representación más corta que vuelve al mismo valor, que es lo que emiten Python y JavaScript. Otros lenguajes pueden diferir en la notación exponencial (`1e-07` frente a `1e-7`). Para los valores de un paquete (montos, confianzas, porcentajes) no pasa en la práctica. Si pasara, la referencia son los bytes canónicos del documento.

## 2. La firma de Blockgence

La huella sola no dice quién emitió el documento. La firma ata esa huella a la clave de Blockgence.

* **Algoritmo:** Ed25519 (RFC 8032).
* **Mensaje firmado:** los bytes ASCII de `blockgence-integrity-v1:sha256:` seguidos de la huella en hex. El prefijo fija el algoritmo de la huella y evita que la firma sirva para otra cosa.
* **Dónde está:** `manifest.integrity.attestations.signature`, con:
  * `key_id`: el sha256 de los 32 bytes de la clave pública;
  * la clave pública, en base64 (`public_key`) y en PEM (`public_key_pem`);
  * la firma en base64 (`value`);
  * la receta para verificarla, incluida una con OpenSSL (`verify_openssl`).

> [!WARNING]
>
> La clave pública viaja dentro del documento para poder verificar sin pedirla, pero **sola no prueba nada**: cualquiera puede quitar la firma y firmar con su propia clave. Lo que prueba que lo emitió Blockgence es que su `key_id` coincida con la [clave pública que publicamos](https://docs.blockgence.com/es/methodology/public-key.md).

Quien verifica **rehace** el mensaje con la huella que recalcula del contenido. Nunca usa la huella ni el mensaje que trae el documento: `integrity` no está cubierto por la huella y cualquiera puede editarlo.

Si el servidor que emitió el documento no tenía una clave de firma configurada, `signature` sale `null` y `signature_note` dice por qué. En ese caso la huella prueba que el documento no cambió, pero no quién lo emitió.

## 3. El sello de tiempo (opcional)

La firma no prueba **cuándo** se emitió un documento: `manifest.generated_at` lo pone el propio sistema. El sello de tiempo ancla la huella en Bitcoin con [OpenTimestamps](https://opentimestamps.org).

> [!NOTE]
>
> El sello de tiempo está **apagado por defecto**: lo enciende el operador del servidor. Cuando no está, el documento sale igual, con `timestamp: null` y una nota en `timestamp_note`. Tampoco se sellan los documentos hechos con datos simulados.

Cuando está encendido:

1. **Al sellar**, se envía a los calendarios de OpenTimestamps un compromiso de 32 bytes, y la prueba queda `pending` dentro del documento. Se usan los dos calendarios que opera opentimestamps.org.
2. **Unas horas después**, los calendarios incluyen el compromiso en una transacción de Bitcoin. El servidor completa la prueba solo, una vez por hora.
3. **El documento ya entregado no cambia.** La prueba completa se descarga aparte, como archivo `.ots`, desde [`GET /v1/evidence/timestamp/{digest}.ots`](#la-prueba-completa).

> [!NOTE]
>
> **Qué sale de la máquina.** A cada calendario se le manda un único pedido de 32 bytes: `sha256(huella || nonce)`, con un nonce de 16 bytes al azar que queda en la prueba y nunca se envía. No sale el contenido, ni la huella misma, ni datos del caso.

Lo que prueba, cuando se completa: que la huella del documento ya existía cuando se minó el bloque de Bitcoin que cita la prueba. Mientras la prueba esté pendiente, no prueba nada todavía: solo registra que se pidió el sello.

Las pruebas que produce Blockgence las lee y verifica el cliente oficial de OpenTimestamps (`ots verify`).

### La prueba completa

Dos rutas abiertas, sin clave de API y sin créditos:

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

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

* **El estado** trae `status` (`pending` o `complete`), los bloques de Bitcoin que anclan la prueba con su `merkle_root`, los calendarios, las fechas y cómo verificar.
* **El archivo** viene con el header `X-OTS-Status`.
* **Mientras sigue pendiente**, cada pedido intenta completarla, como mucho una vez cada 10 minutos por huella.
* **Errores:** `404` si ese servidor no selló esa huella; `400` si el nombre no es un sha256 en hex.

## Qué versión de la metodología

Cada documento cita la metodología con que se armó, en `manifest.methodology`: su versión (`version`), una huella de sus parámetros reales (`fingerprint`) y cuántas entradas tiene. El paquete trae además las entradas que usó ese análisis. Ver [Changelog de metodología](https://docs.blockgence.com/es/methodology/changelog.md).

## Siguiente paso

> [card] [Verificar una firma](https://docs.blockgence.com/es/methodology/verify-signature.md)
>
> Paso a paso, con Python 3 y OpenSSL, sin cuenta y sin el código de Blockgence.

> [card] [Clave pública](https://docs.blockgence.com/es/methodology/public-key.md)
>
> La huella vigente, dónde se publica y qué pasa si cambia.


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