Cómo construir un producto sobre un gateway Label 309

Para incorporar una función de prueba de existencia sin operar tú mismo una blockchain, construyes sobre un gateway. Un gateway Label 309 es el motor de publicación que hay detrás de un producto de prueba de existencia: hace el trabajo operativo difícil —presupuestos, subidas, envío de la transacción de Cardano, confirmación, gestión de reorganizaciones, indexación de registros, saldos de cuenta, financiación del almacenamiento, claves de API y webhooks— y lo expone todo por HTTP plano. Tu producto llama a esos endpoints y se queda con todo lo que tus usuarios realmente ven: la interfaz, la relación de facturación, el flujo de trabajo del dominio y la marca.

El núcleo del gateway es de código abierto, y CardanoWall es el producto de referencia construido sobre él. Lo útil para quien desarrolla es que no hay puerta privada: CardanoWall accede al gateway a través de los mismos endpoints públicos que usarías tú, así que cualquier patrón que funcione para el producto de referencia funciona también para ti.

¿Quién debería construir sobre un gateway?

Construye sobre un gateway si quieres la prueba de existencia dentro de un producto, no como una acción manual que el usuario realiza en una web.

Encajan bien, por ejemplo:

productos de notarización de documentos;
archivos de pruebas para cumplimiento;
plataformas de procedencia de IA y gobernanza de conjuntos de datos;
sistemas de prueba para integración continua;
herramientas de material probatorio para uso jurídico;
portales de divulgación cifrada;
servicios de autenticidad de medios;
herramientas internas de auditoría empresarial;
páginas de prueba para editoriales.

En todos estos casos, los usuarios no quieren pensar en la construcción de transacciones de Cardano, la financiación de UTxO, los créditos de almacenamiento ni las confirmaciones en cadena. Quieren un flujo de trabajo que produzca pruebas duraderas y verificables. El gateway hace posible ese flujo sin que tu equipo tenga que convertirse en operador de infraestructura de Cardano.

¿De qué se encarga el gateway y de qué se encarga tu producto?

El reparto es la clave de todo, así que conviene decirlo con claridad. El gateway se encarga del plano base: la canalización de publicación y todo el estado de dinero, cadena y almacenamiento que hay detrás:

presupuesto, subida y publicación;
construcción, envío, confirmación y gestión de reorganizaciones de la transacción de Cardano, y los reembolsos ante un fallo permanente;
subidas de contenido y texto cifrado al almacenamiento, además de la financiación del almacenamiento que las sostiene;
un índice de registros on-chain compartido que cubre todos los registros Label 309 de la red;
los saldos de cuenta y los asientos del libro mayor que los mueven;
la fijación de precios por tipo de cambio y los márgenes;
las credenciales de API y la entrega de webhooks.

Esto es trabajo de infraestructura. Tiene que ser preciso, observable y aburrido en producción. Tu aplicación no debería reimplementarlo a menos que operar un gateway sea tu verdadero trabajo; y si lo es, consulta opera tu propio gateway.

Tu producto se encarga del plano del proveedor: todo lo que tiene forma de proveedor:

las cuentas de usuario y las sesiones;
la incorporación de usuarios y la facturación;
los permisos del producto;
tu interfaz y tus correos;
los precios que presentas a los clientes;
conceptos de dominio como «caso», «versión», «conjunto de datos» o «paquete de pruebas»;
los modelos de lectura construidos a partir de los eventos del gateway;
los flujos de trabajo de soporte.

El gateway no necesita saber que una prueba pertenece a un litigio, a un ciclo de entrenamiento de un modelo, a un paquete de cumplimiento trimestral o a un número de una revista. Solo necesita publicar registros Label 309 correctos y mantener el estado operativo a su alrededor. Esa separación deja más limpios ambos sistemas: tu producto puede reconstruirse o cambiar de marca sin tocar el estado de cadena ni de dinero, y el gateway puede actualizarse sin saber que tu producto existe.

¿Cómo llamas al plano de datos en nombre de un usuario?

El plano de datos (/api/v1/*) es la API orientada a la cuenta. Úsalo siempre que la acción ocurra en nombre de un usuario o una cuenta:

pedir un presupuesto de una publicación;
subir contenido o texto cifrado;
publicar un registro;
leer un saldo o el libro mayor de la cuenta;
listar, recuperar o verificar registros públicos;
registrar webhooks con alcance de cuenta.

En un producto envolvente, tu backend emite un token de cuenta de corta vida para la cuenta de gateway del usuario, y el cliente llama al plano de datos solo con los scopes que necesita. Los scopes son el límite de permisos: una pantalla de publicación necesita poe:create, un widget de saldo necesita account:read, y los endpoints de registros públicos no necesitan credencial alguna: atienden a quien llama de forma anónima, que es lo que convierte al índice en un bien público y no en una vista por cliente.

Los tokens son de corta vida por diseño (una hora por defecto). Emite uno por sesión y vuelve a emitirlo al expirar, de modo que un token filtrado sea un problema de una hora en vez de un incidente. Y nunca envíes credenciales de operador al navegador: esa es la única regla que la siguiente sección existe para proteger.

¿Cómo llamas al plano de control como operador?

El plano de control (/control/v1/*) es solo para backends de confianza y operadores. Úsalo para:

crear cuentas de gateway y habilitarlas o deshabilitarlas;
aplicar ajustes en el libro mayor después de que tu sistema de facturación cobre el dinero;
fijar márgenes por cuenta;
emitir tokens de cuenta y claves de API;
registrar el firehose de webhooks del operador;
registrar y gestionar las carteras y las fuentes de financiación del almacenamiento;
leer el estado de auditoría y operativo.

Este plano vive detrás de tu backend. Trata las credenciales de operador como secretos de producción con autoridad de gasto, porque la tienen. Un token de operador de corta vida (24 horas por defecto) se encarga de la administración del día a día; un único secreto raíz, guardado en un almacén de secretos, se reserva para las pocas operaciones que registran carteras y fuentes de almacenamiento.

El plano de control es lo que mantiene conectados tu sistema de facturación y el saldo prepago del gateway. Un pago se completa con éxito en tu sistema y, a continuación, tu backend aplica un único ajuste idempotente en el libro mayor de la cuenta de gateway. Ese es todo el carril de crédito, y las dos secciones siguientes explican por qué está construido exactamente así.

¿Por qué no deberías consultar las tablas del gateway directamente?

Porque el esquema no es un contrato: lo son la API HTTP y los webhooks.

El motor del gateway se encarga de sus propios esquemas de Postgres (cw_core y cw_api). Tu producto no debería leerlos ni escribir en ellos, ni siquiera cuando ambos sistemas comparten la misma instancia de Postgres. La coexistencia de esquemas es una forma de despliegue admitida, pero el límite es el esquema, no la base de datos: esos esquemas del motor son internos y pueden cambiar sin previo aviso, mientras que los planos HTTP y el firehose son estables. Si cruzas ese límite, una actualización rutinaria del gateway puede romper tu producto sin avisar.

Si necesitas datos que la API no expone, trátalo como una carencia de la API que hay que señalar, no como una licencia para hacer joins entre esquemas.

¿Cómo construyes tus propias pantallas a partir de los eventos del gateway?

Todo producto necesita sus propias vistas: registros enviados, historial de clientes, saldos, fallos de publicación, líneas de tiempo de casos, paquetes de pruebas, paneles de auditoría. No las construyas haciendo polling de cada fila ni haciendo joins contra las entrañas del gateway.

En su lugar, registra webhooks y proyecta los eventos en tus propias tablas. El gateway expone un firehose de operador —cada evento de ciclo de vida de la instancia— más suscripciones de webhook con alcance de cuenta para flujos más acotados. Una vista de «elementos enviados» es el ejemplo canónico: consume los eventos de estado de publicación, proyéctalos en tu propia tabla y renderiza desde ahí.

La entrega es de al menos una vez, así que haz que tu proyección sea idempotente. Un modelo de lectura práctico puede indexar por:

el id del evento o el id de entrega (para que una reentrega no haga nada);
el id de registro del gateway;
el hash de la transacción final;
tu propio id de usuario;
el id de tu propio objeto de dominio;
el estado y las marcas de tiempo.

Tu interfaz renderiza entonces desde tus propias tablas, mientras que el gateway sigue siendo la autoridad para el gasto, el ciclo de vida de la publicación y los hechos de la cadena. Cada entrega va firmada; verifica la firma y aplica una ventana de tolerancia sobre el sello de tiempo antes de confiar en un evento.

¿Cómo debería fluir el dinero entre tu facturación y el gateway?

Mantén el modelo simple: el saldo del gateway es el saldo gastable, y tu sistema de facturación es solo una de las formas en que el dinero llega hasta él.

Tu carril de facturación puede cobrar con tarjetas, facturas, pagos en cripto, créditos empresariales manuales o subvenciones. El gateway no necesita saber nada de eso. El patrón limpio es:

Tu sistema de facturación confirma un pago.
Tu backend aplica un único ajuste idempotente en el libro mayor de la cuenta de gateway, indexado por el id del pago.
El saldo del gateway aumenta.
Las futuras operaciones de publicación y subida debitan ese saldo.
Si una publicación falla de forma permanente, el propio gateway revierte el débito.

De ahí se derivan dos consecuencias. Primera, la idempotencia importa porque las canalizaciones de facturación entregan de al menos una vez: pasa el propio id del pago como referencia del ajuste, y cinco entregas de un mismo pago acreditan el saldo una sola vez. Segunda, no copies el libro mayor del gateway en tu propia tabla para tratar esa copia como la verdad a la hora de decidir un gasto; cachéala para renderizar si hace falta, pero lee el gateway siempre que la decisión mueva dinero de verdad. Como el gateway emite sus propios reembolsos, tampoco deberías construir una vía de reembolso del lado del proveedor para los fallos de publicación: provocaría un doble reembolso.

¿Dónde debería vivir cada tipo de clave?

Un gateway nunca debería necesitar la semilla de identidad de un usuario. El cliente o el SDK pueden calcular el hash del contenido, cifrar las cargas selladas y firmar registros de forma local; el gateway solo publica los bytes del registro finalizado y envía la transacción de Cardano. (Para entender por qué ese límite importa de extremo a extremo, consulta por qué las claves nunca salen del dispositivo.)

Una integración completa tiene varias clases de claves bien distintas, y el error que hay que evitar es aplanarlas todas en un único «secreto de API». Tienen radios de impacto muy diferentes:

las semillas de identidad de usuario y las claves privadas de destinatario: la identidad criptográfica del usuario, que pertenece al extremo;
las claves de firma de registros derivadas de esa identidad;
las claves de API de cuenta y los tokens de cuenta de corta vida: que pertenecen al producto o al contexto de cliente que los necesita;
los tokens de operador y el secreto raíz: que solo pertenecen a backends de confianza;
las propias claves de firma de Cardano y de almacenamiento del gateway, y sus secretos de firma de webhooks: que pertenecen al keyring del gateway.

Asigna cada clase al lugar más pequeño que pueda albergarla, y una sola filtración se mantiene contenida.

¿Cuándo deberías autoalojar el gateway en vez de usar uno gestionado?

Autoaloja cuando la independencia operativa importa más que la comodidad.

Un gateway gestionado es el camino más simple para la mayoría de las integraciones: publicas a través de un servicio listo para usar por superficies de API estándar y nunca operas tú mismo la cadena ni el almacenamiento. Autoalojar cambia esa simplicidad por control: tu propia financiación de la cartera de Cardano, tu propia financiación del almacenamiento, tus propias políticas de operador, tu propio tiempo de actividad y tus propias dependencias de red, tus propios márgenes, tu propio límite de cumplimiento y ninguna dependencia de un tercero para publicar.

Pero el control también es responsabilidad. Autoalojar significa que financias el ADA y los créditos de almacenamiento, proteges el keyring, operas Postgres, monitorizas los proveedores de cadena, gestionas las copias de seguridad, rotas las credenciales, gestionas los webhooks y respondes a los incidentes. Elimina una dependencia de proveedor; no elimina el trabajo operativo. Operar tu propio gateway repasa lo que eso conlleva en realidad.

¿Qué deberían ver tus usuarios en una prueba?

La mayoría de los usuarios debería ver primero los conceptos de tu producto. Les importa «publicar pruebas», «sellar este archivo», «probar esta instantánea de un conjunto de datos» o «anclar esta versión». No deberían tener que leer una especificación de metadatos para usar el producto.

Aun así, toda vista de prueba debería exponer los hechos que hacen que la afirmación se pueda comprobar de forma independiente:

el hash de la transacción;
la hora del bloque y el estado de confirmación;
el algoritmo de hash y el digest;
la clave pública del firmante, cuando el registro va firmado;
las URIs de almacenamiento, cuando las haya;
el estado de destinatario sellado, cuando sea pertinente;
la raíz de Merkle y la prueba de la hoja, cuando el registro agrupa muchos archivos;
el propio veredicto de la verificación.

Así es como el producto sigue siendo agradable de usar sin ocultar la afirmación criptográfica que tiene debajo.

¿Cómo evitas atar tu producto a un solo gateway?

El gateway te ayuda a publicar; nunca debería convertirse en la prueba.

El registro en la cadena son metadatos Label 309, y la verificación está diseñada para funcionar a partir de tres entradas únicamente: los metadatos de la transacción, opcionalmente los bytes del contenido y un explorador público de Cardano, con las claves del destinatario añadidas solo para descifrar registros sellados. En esa cadena de confianza no interviene ningún servidor del emisor. Si tu gateway desapareciera mañana, un registro válido debería seguir verificándose con herramientas independientes. Conviene recordar, además, qué afirma y qué no afirma una prueba así: muestra que esos bytes exactos ya existían en un momento público verificable, no que ninguna afirmación sobre ellos sea cierta, te pertenezca o esté autorizada.

Construye tu producto en torno a esa promesa:

almacena los hashes de transacción de forma duradera;
deja que los usuarios exporten informes de verificación y descarguen paquetes de pruebas;
conserva las listas de hojas de Merkle y sus pruebas;
documenta cómo verificar un registro fuera de tu interfaz;
evita los campos privados que solo tu backend puede interpretar.

Esa es la diferencia entre «tenemos una fila en una base de datos» y «produjimos una prueba que cualquiera puede comprobar».

Para seguir leyendo

¿Qué es un gateway Label 309? y opera tu propio gateway: el gateway desde el lado del operador.
Construye sobre la API de CardanoWall y usa la CLI en la automatización: las superficies orientadas a desarrolladores con más detalle.
Por qué publicar tiene un precio: qué paga en realidad el saldo prepago.
Label 309 es de código abierto: el estándar y su código de referencia.
El estándar de código abierto vive en label309.org; el gateway, los SDKs y la CLI están en github.com/cardanowall. Label 309 se ha presentado al proceso CIP de Cardano y está bajo revisión por los editores de CIP como propuesta de la categoría Metadata.