Publica tu primera prueba de existencia en Cardano

La prueba Label 309 más sencilla es un hash anclado en Cardano.

Tomas un archivo, calculas su hash criptográfico, publicas ese hash en un registro Label 309 bajo la etiqueta de metadatos 309 de Cardano y guardas el hash de la transacción resultante. Más tarde, cualquiera que tenga el archivo original puede recalcular el hash y confirmar que el compromiso correspondiente estaba en la cadena a más tardar en el momento de bloque de la transacción. No necesita tu servidor, ni tu dominio, ni tu identidad para comprobarlo: solo la referencia de la transacción y un explorador público de Cardano.

Ese es el primer nivel de la prueba de existencia. Todo lo demás se construye sobre él. Esta guía te lleva paso a paso por la publicación de una, casi siempre desde la herramienta de línea de comandos cardanowall, y termina mostrándote cómo confirmar que realmente funcionó.

¿Qué estás publicando en realidad?

Cuando creas una prueba básica, no publicas el archivo en sí.

Publicas un compromiso con el archivo: su digest. Un digest es una huella criptográfica de tamaño fijo. Si el archivo cambia en un solo byte, el digest cambia por completo. Esa propiedad es lo que convierte a un hash en un sustituto fiable de los bytes exactos.

Una prueba solo con el hash encaja bien con cosas como:

contratos y facturas;
artefactos de publicación y manifiestos de compilación;
resultados de IA e instantáneas de conjuntos de datos;
documentos de políticas y paquetes de pruebas;
sumas de verificación que ya generó otro sistema.

La prueba no revela el contenido del archivo. Revela únicamente el hash, el algoritmo de hash que elegiste y los metadatos opcionales que decidas incluir en el registro. Para saber más sobre qué campos acaban en la cadena, consulta qué va a parar a la blockchain.

¿Qué necesitas antes de publicar?

Publicar necesita un gateway. Verificar no.

La verificación se ejecuta enteramente a partir de datos públicos de la cadena. Publicar es distinto: algo tiene que construir y enviar la transacción de Cardano, pagar la comisión de la red, gestionar la confirmación y —si guardas archivos fuera de la cadena— pagar el coste de almacenamiento. Un gateway Label 309 es el servicio que hace todo eso. El gateway de código abierto y las herramientas que lo rodean son agnósticos respecto al gateway, así que apuntas las herramientas al gateway del que tengas una clave.

Para tu primera prueba necesitas:

un archivo o un digest precalculado;
la URL base de un gateway Label 309;
una clave de API o un token de cuenta de corta duración para ese gateway;
saldo suficiente en tu cuenta del gateway;
opcionalmente, una semilla de identidad, si quieres firmar el registro.

Si usas el gateway alojado de CardanoWall, CardanoWall gestiona por ti la cuenta del gateway y el saldo de prepago. Si ejecutas tu propio gateway, financias tú mismo sus carteras de Cardano y de almacenamiento. En cualquier caso, publicar cuesta dinero porque se pagan comisiones reales en tu nombre: ese es el tema de por qué publicar tiene un precio.

¿Por qué el flujo es primero el presupuesto y luego la publicación?

Un gateway nunca debería publicar en silencio y sorprenderte con una factura. Por eso toda publicación tiene la misma forma de dos pasos: fija un precio y luego envía.

Construye o estima el registro.
Pide un presupuesto al gateway.
Recibe un id de presupuesto y un desglose del precio (comisión de red, almacenamiento, margen de servicio).
Envía el registro finalizado con ese presupuesto.
Recibe un id de registro del gateway de inmediato, mientras la transacción aún se está enviando.
Sigue el estado hasta que la transacción se confirme en la cadena.
Verifica el resultado de forma independiente.

Un presupuesto fija el precio durante una ventana limitada —actualmente, 15 minutos—. Si caduca antes de que publiques, pides uno nuevo; el precio puede variar si se movieron los tipos de cambio, pero nada más cambia.

Este patrón de dos pasos es lo que hace segura la automatización. Tu script puede registrar el presupuesto, aplicar su propia política de gasto y solo entonces publicar, de modo que un repunte de precio o un lote enviado por error nunca puedan arrasar con tu saldo.

Publica un archivo con la CLI

Para un archivo local, el flujo en la línea de comandos es deliberadamente reducido:

cardanowall submit \
  --file ./contract.pdf \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY"

La CLI calcula el hash del archivo, construye el registro Label 309, pide al gateway que lo presupueste y lo publique, e imprime el resultado. --base-url y --api-key también se leen de las variables de entorno CARDANOWALL_BASE_URL y CARDANOWALL_API_KEY, así que desaparecen del comando en CI.

Para un uso repetido, guarda el gateway como un perfil con nombre en lugar de pasar el endpoint cada vez:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall submit --file ./contract.pdf

El binario cardanowall es una herramienta nativa única y autónoma, sin ningún entorno de ejecución que instalar. Instálalo desde crates.io con cargo install cardanowall-cli (el crate es cardanowall-cli; el comando instalado es cardanowall), o compílalo a partir del repositorio de código abierto en github.com/cardanowall.

¿Cómo publicas un hash que ya tienes?

A veces el digest ya existe: de una canalización de compilación, un registro de contenedores, un proceso de publicación o un archivo de datos. En ese caso, publica el digest directamente, sin que haya ningún archivo de por medio:

cardanowall submit --hash <64-hex-digest>

El modo de hash por defecto es sha2-256. Pasa --alg blake2b-256 cuando necesites ese algoritmo en su lugar. El registro deja constancia de qué algoritmo usaste, de modo que un verificador sepa cómo recalcular el digest más adelante.

Publicar un hash precalculado es también la opción correcta cuando el archivo de origen es demasiado grande, demasiado sensible o está demasiado controlado como para pasarlo por una herramienta de uso general. Lo único que importa es que los bytes exactos y el proceso de hash exacto se mantengan reproducibles; de lo contrario, nadie podrá recalcular un digest coincidente.

¿Deberías firmar el registro?

Firma el registro cuando quieras demostrar que una identidad Label 309 concreta responde por él.

Una prueba solo con el hash dice: estos bytes existían a más tardar en este momento. Una prueba firmada añade: y esta clave de firma respalda este registro exacto. Esa afirmación adicional importa para los registros de publicación de una empresa, los archivos oficiales, las canalizaciones de CI/CD, los flujos de trabajo de pruebas legales, los registros de procedencia de IA y cualquier identidad pública de larga duración con la que publiques.

Las firmas son siempre opcionales. Una prueba sin firma sigue siendo una prueba de existencia completa y plenamente verificable: Label 309 es agnóstico respecto al emisor por diseño, y un verificador nunca tiene por qué confiar en quien publica. Firmar solo responde a una pregunta distinta: quién responde por el registro, no si los bytes existieron.

La semilla de identidad nunca debe enviarse al gateway. La CLI y el SDK están diseñados para que la firma ocurra localmente y solo viaje la firma terminada. Proporciona la semilla a través de --seed-stdin o --seed-file en lugar de un argumento --seed a secas, porque los argumentos de la línea de comandos se filtran por el historial del shell, los listados de procesos y los registros de CI:

cardanowall submit --file ./release-manifest.json --seed-stdin

¿Adjuntas el archivo o solo el hash?

Tienes tres opciones, en orden creciente de lo que comprometes en la cadena.

Solo el hash. La prueba más pequeña y privada. Basta cuando ya sabes que el archivo se conservará en algún lugar que controlas. El registro lleva el digest y nada sobre su recuperación.

El hash más un enlace direccionado por contenido. Adjunta una URI ar:// (Arweave) o ipfs:// (IPFS) para que los verificadores puedan recuperar los bytes más tarde. El hash sigue decidiendo si los bytes recuperados coinciden: una URI direccionada por contenido vincula los bytes al propio enlace, de modo que un verificador nunca tiene que confiar en el gateway, el DNS ni el TLS para saber que recuperó el archivo correcto.

Sellado. Cifra el archivo, guarda el texto cifrado fuera de la cadena y pon el sobre sellado en el registro. Este es el camino para los registros confidenciales, la entrega a un destinatario concreto y la recuperación del contenido más adelante si pierdes tu copia local.

Para una primera prueba, empieza por solo el hash. Añade la firma, el almacenamiento fuera de la cadena, la agrupación de Merkle o la entrega sellada cuando un caso de uso real lo pida.

¿Cómo sabes que realmente funcionó?

No te detengas en «el gateway lo aceptó». La prueba solo está completa cuando la transacción está en la cadena y verifica.

Cuando publicas, el gateway te devuelve un id de registro de inmediato y el hash de la transacción se rellena de forma asíncrona en cuanto la transacción se construye y se envía. Así que, después de publicar, guarda:

el hash de la transacción de Cardano;
el id de registro del gateway, si usaste un gateway;
el archivo o el digest original;
la identidad pública de la clave de firma, si firmaste;
cualquier lista de hojas de Merkle o prueba de inclusión, si agrupaste;
cualquier material de recuperación, si la prueba está sellada.

Luego verifica la transacción igual que lo haría cualquier tercero: a partir de la cadena pública, sin que intervenga ningún gateway:

cardanowall verify <tx-hash> --json

Un veredicto valid es la línea de meta. Los demás veredictos te dicen qué hacer a continuación:

pending — la transacción aún no se ha confirmado con suficiente profundidad. Espera más confirmaciones y reinténtalo.
unverifiable — no hay fallo en el registro, pero una comprobación necesaria no pudo ejecutarse. Revisa tus fuentes de datos, la disponibilidad del almacenamiento fuera de la cadena y la política de red.
failed — un problema real atribuible al registro. Investiga el propio registro.

La separación entre failed y unverifiable es deliberada: failed significa que el registro es incorrecto, mientras que unverifiable significa que el verificador no pudo terminar una comprobación. Para conocer el flujo de verificación completo, consulta verifica un registro Label 309.

¿Qué debería mostrar una interfaz después de publicar?

Una buena interfaz muestra algo más que la palabra «publicado». Para una primera prueba, deja a la vista:

el hash corto de la transacción, con un botón para copiar;
el hash completo de la transacción en la vista de detalle;
el algoritmo de hash y el digest;
el estado de publicación;
el momento de bloque, una vez confirmado;
el veredicto de verificación;
si el registro estaba firmado;
si se adjuntaron archivos o se sellaron;
si se omitió alguna comprobación.

Eso hace que la prueba se entienda sin obligar a nadie a leer la especificación.

¿Qué puede salir mal al publicar?

La mayoría de los fallos al publicar son operativos, no misteriosos. La cuenta puede quedarse sin saldo. El presupuesto puede haber caducado. El registro puede ser demasiado grande para una transacción de Cardano. Un archivo subido puede no llegar a almacenarse. La transacción de Cardano puede fallar de forma permanente: en ese caso, un gateway bien construido revierte el cargo por sí mismo, así que solo se te factura por lo que llega a la cadena. O puede que la cartera financiada del gateway simplemente necesite atención.

Un flujo de trabajo de publicación serio gestiona los reintentos de forma idempotente. Un gateway deduplica el reintento de una publicación por los bytes exactos del registro —reenviar el registro idéntico devuelve el resultado existente en lugar de gastar dos veces— y acepta una clave de idempotencia en los lotes de subida, de modo que una subida reentregada sea segura ante repeticiones. En un producto de cara al usuario, diseña la ruta de reintento antes de que tu primer cliente real se tope con un tiempo de espera de red, no después.

Si estás integrando esto en una canalización, usa la CLI en automatización entra más a fondo en la salida JSON, los códigos de salida y el manejo seguro de secretos.

¿Qué no demuestra tu primera prueba?

Una prueba de existencia es precisa sobre lo que afirma, lo que significa que también es precisa sobre lo que no afirma.

No demuestra la propiedad.
No demuestra la autoría, a menos que la firmes y puedas vincular la clave de firma con la identidad reclamada.
No demuestra que el archivo sea verdadero, lícito u original.
No conserva el archivo, a menos que lo guardes en algún lugar duradero.

Lo que sí demuestra es exacto y duradero: los bytes precisos que coinciden con el hash comprometido existían a más tardar en el momento de bloque de la transacción, y cualquier firma opcional, comprobación de almacenamiento o comprobación de contenido sellado se verificó según la política del verificador.

Eso basta para ser genuinamente útil, y es lo bastante preciso como para ser fiable. Para conocer mejor el límite de lo que un sello de tiempo puede y no puede establecer, consulta qué no demuestra una prueba.

Lecturas adicionales

Verifica un registro Label 309: la otra mitad del flujo, sin confianza y sin cuenta.
Por qué publicar tiene un precio: qué paga la comisión.
Usa la CLI en automatización: salida JSON, códigos de salida y secretos en CI.
Qué va a parar a la blockchain: los campos que un registro lleva realmente.
El estándar abierto y las implementaciones de referencia: label309.org y el código fuente en github.com/cardanowall.