Servicio de estampado de firmas documentales en blockchain Alastria

Resumen

Una empresa necesitaba garantizar la integridad y trazabilidad de documentos generados por sus aplicaciones internas, registrando sus firmas (hashes) en la red Alastria Red-T. El trabajo consistió en diseñar un servicio en Java desplegable en Docker que expone una API REST sencilla para estampar y consultar hashes onchain, ocultando toda la complejidad propia de la interacción con blockchain (gestión de claves, nonces, errores de transacción, sincronización con el nodo).

Contexto

La organización tenía varias aplicaciones internas que generaban documentos relevantes desde el punto de vista legal y operativo: contratos, evidencias, certificados internos y registros de auditoría. La necesidad era doble:

Poder demostrar en el futuro que un documento concreto existía en un momento dado y no había sido alterado.
Hacerlo sobre una red blockchain con respaldo institucional, en este caso Alastria Red-T, una red permissioned ampliamente adoptada en España.

El problema no era técnico desde el punto de vista del negocio, sino desde el punto de vista del desarrollo: ninguna de las aplicaciones cliente debía conocer detalles de blockchain. Los equipos de aplicación querían algo tan simple como “envíame este hash y guárdamelo de forma fiable”.

Problema

Integrar cada aplicación directamente contra la red presentaba varios problemas:

Cada equipo tendría que aprender a usar Web3j, gestionar wallets, firmar transacciones y manejar nonces.
Los errores de blockchain (gas insuficiente, nonce desincronizado, nodo no disponible, transacción revertida) son específicos y poco intuitivos para desarrolladores backend convencionales.
La gestión de claves privadas distribuida en cada aplicación habría sido un riesgo de seguridad y de operación.
Las transacciones onchain no son instantáneas, por lo que cualquier integración naive bloquearía las aplicaciones cliente.
Sin una capa común, cada aplicación implementaría su propia lógica de reintentos, validación y verificación, con resultados inconsistentes.

Una solución “rápida” a base de scripts puntuales habría empeorado el problema a medio plazo.

Objetivos

Centralizar la interacción con Alastria Red-T en un único servicio reutilizable.
Ofrecer una API REST clara, equivalente en simplicidad a guardar un registro en una base de datos.
Aislar la gestión de claves y la configuración del nodo.
Manejar los errores propios de blockchain de forma robusta sin propagarlos al cliente.
Permitir un despliegue sencillo en cualquier entorno mediante Docker.
Dejar trazabilidad suficiente para auditoría y depuración.

Enfoque técnico

El servicio se construyó en Java (Spring Boot) y se empaquetó como una imagen Docker autocontenida, parametrizable mediante variables de entorno (endpoint del nodo, dirección del contrato, credenciales, política de reintentos).

Aspectos principales del diseño:

Capa REST mínima y estable: dos operaciones principales (POST para estampar un hash y GET para verificar su existencia y obtener metadatos), más endpoints auxiliares de salud y diagnóstico. La API se diseñó pensando en que pudiera permanecer estable aunque la implementación interna cambiara.
Capa de servicio: orquesta la validación, normalización del hash, envío de la transacción al smart contract correspondiente y la persistencia local de los resultados.
Capa de integración con Alastria Red-T: usando Web3j sobre la red Besu/Quorum subyacente. Encapsula la creación de transacciones, firma, envío al nodo, polling de confirmación y traducción de errores onchain a errores aplicativos claros.
Gestión de claves: claves del wallet de servicio inyectadas mediante secretos del entorno, nunca en código ni en el repositorio. El servicio actúa como “custodio operativo”, lo que evita que cada aplicación cliente maneje claves propias.
Idempotencia: cada estampado se identifica por el propio hash más un identificador opcional del cliente, permitiendo reintentos seguros si una aplicación reenvía la misma operación.
Persistencia local: una base de datos relacional guarda el estado de cada operación (pendiente, confirmada, fallida) junto con el transaction hash onchain, evitando depender exclusivamente del nodo para responder consultas frecuentes.
Manejo de errores onchain: nonce desincronizado, nodo caído, transacción revertida o tiempos de confirmación largos se gestionan con reintentos controlados y trazabilidad detallada.
Logging y monitorización: logs estructurados con identificadores de correlación entre la petición REST, el registro interno y la transacción onchain.
Docker first: la imagen se diseñó para arrancar configurada por entorno, sin requerir builds específicas por cliente o entorno, facilitando despliegues internos y en infraestructuras del cliente.

Decisiones y trade-offs

Se descartó exponer la red directamente a las aplicaciones cliente, aunque inicialmente parecía más “puro”. La complejidad operativa y los riesgos de seguridad asociados a distribuir claves y lógica blockchain en cada aplicación no compensaban.

Se optó por una API síncrona desde el punto de vista del cliente, pero asíncrona internamente: la respuesta inicial confirma que el hash ha sido aceptado y persistido, mientras que la confirmación onchain se procesa en segundo plano y queda disponible por consulta posterior. Esto permitió mantener tiempos de respuesta predecibles sin sacrificar fiabilidad.

Se priorizó la estabilidad de la API REST sobre la riqueza de funcionalidades. Un contrato pequeño y bien definido es más fácil de mantener cuando varias aplicaciones internas dependen de él.

Se evitó construir una infraestructura blockchain propia: usar Alastria Red-T daba garantías institucionales y reducía coste operativo frente a mantener una red privada interna.

Resultado

Las aplicaciones internas pueden estampar y verificar firmas documentales con una llamada REST trivial, sin conocer detalles de blockchain.
La gestión de claves y errores onchain queda centralizada en un único punto, más fácil de auditar y operar.
El despliegue del servicio en distintos entornos se reduce a desplegar una imagen Docker con su configuración.
Los errores propios del mundo onchain dejan de impactar a los equipos de aplicación.
Queda una base sólida para añadir en el futuro nuevas funcionalidades: firma de eventos, registros de auditoría adicionales o integración con otras redes.

Stack técnico

Java / Spring Boot
Web3j
Alastria Red-T (Besu / Quorum)
Smart contract de registro de hashes
PostgreSQL
Docker
REST APIs

Qué demuestra este caso

Este caso demuestra capacidad para diseñar servicios backend que abstraen tecnologías complejas (en este caso blockchain) detrás de APIs simples y estables, aplicando criterios de arquitectura, seguridad operativa y mantenibilidad. También muestra criterio para decidir qué complejidad debe vivir dentro del servicio y qué debe quedar fuera, protegiendo al resto del ecosistema de aplicaciones.

Versión corta para tarjeta

Title: Estampado de firmas documentales en Alastria Red-T

Sector: Servicios internos / Backend corporativo

Problem: Varias aplicaciones internas necesitaban registrar firmas de documentos en blockchain sin asumir la complejidad de operar onchain.

Technical approach: Servicio en Java desplegable en Docker que expone una API REST y encapsula la interacción con Alastria Red-T, la gestión de claves y los errores onchain.

Result: Integración blockchain reducida a llamadas REST simples, gestión centralizada de claves y errores, y despliegue homogéneo en cualquier entorno.

Tags: Blockchain, Alastria, Java, REST API, Docker, Arquitectura backend

CTA opcional

Si tu organización necesita integrar tecnologías complejas (blockchain, sistemas legacy, ERPs, motores de búsqueda) detrás de APIs claras y mantenibles, puedo ayudarte a diseñar la capa de servicio adecuada y dejarla operativa en producción.