Arquitectura de referencia con Fireblocks, BitGo y Kaleido

Son las 03:10 y llegan dos avisos del mismo depósito de 300.000 USDC: uno de Fireblocks y otro, por error de configuración, de un webhook viejo que nadie apagó. Media hora después llega un tercero, idéntico al primero, porque nuestro servidor tardó en responder. Si cada aviso suma saldo, el cliente tiene 900.000 USDC en nuestro libro. Este capítulo arma la arquitectura que evita ese error: qué hace cada proveedor, qué hace nuestro sistema y cómo se cruzan.

Tres términos ordenan el capítulo. Una capacidad es algo que la operación necesita hacer (guardar llaves, aprobar un retiro, leer la cadena). Un límite de integración es la frontera entre lo que decide el proveedor y lo que decide nuestro sistema. Conciliar es comparar dos o más registros del mismo hecho y explicar cada diferencia antes de seguir.

Mapa de capacidades: qué resuelve cada proveedor

El punto de partida es lo que cada proveedor documenta de sí mismo, no lo que su marca sugiere. Fireblocks se describe con tres componentes: wallets basadas en MPC (su protocolo MPC-CMP, que nunca reúne la llave privada completa), un motor de políticas que bloquea, aprueba o pide firmantes adicionales según reglas, y gestión de tesorería con cuentas de bóveda segregadas u ómnibus. [1] También integra proveedores de AML/KYT (Chainalysis, Elliptic y TRM Labs), con uno solo por workspace. [2]

BitGo ofrece wallets multifirma y MPC con tres llaves (usuario, respaldo y BitGo) y firma 2 de 3; sus wallets de custodia son todas en frío y BitGo se compromete a completar los retiros desde ellas en 24 horas. [3] Su arquitectura de referencia separa custodia, standby y depósito/retiro, unidas por whitelists. [4] Sus políticas se definen por destino, iniciador, porcentaje del saldo, umbral, velocidad o respuesta de un webhook. [5]

Kaleido se presenta en dos frentes. Su custodia no genera ni guarda llaves: estas viven en el HSM o keystore que elige el cliente, y las políticas se escriben como código Rego (Open Policy Agent) y se aplican antes de firmar. [6] Y su capa de infraestructura da nodos gestionados para redes públicas EVM y no EVM, enrutamiento JSON-RPC e indexación. [7] [8]

Los emisores completan el mapa. Circle Mint es el canal para acuñar y redimir USDC con Circle, por consola o API. [9] Para USDT, emitir y redimir directamente exige ser cliente verificado de Tether. [10] En lo que pudimos consultar de tether.to no hay una API documentada para automatizar ese flujo; su integración queda a validar con el proveedor y, mientras tanto, se diseña como un proceso manual con doble control.

La matriz siguiente es la propuesta inicial. Cada celda dice "documentado" solo si la fuente citada lo respalda; el resto queda a validar contra el contrato.

Las dos últimas filas son nuevas. La de Circle no nombra el "Circle Direct Adapter" porque ninguna documentación oficial usa ese término; el capítulo de USDC lista sus candidatos documentados, a validar con el proveedor. La de liquidación usa Go Network, que BitGo describe como la red que conecta empresas mediante sus Go Accounts, wallets ómnibus de custodia en frío con libro fuera de la cadena; BitGo no documenta un producto llamado "BitGo market maker", y ese mapeo también queda a validar con el proveedor. Esa capacidad se trata en liquidez y liquidación.

Límites de integración: qué vive en el proveedor y qué en el nuestro

La regla que ordena la frontera es una: el proveedor decide si una firma ocurre; nuestro sistema decide si un saldo existe para el cliente. Las políticas de aprobación, la lista blanca de destinos y las llaves viven en el proveedor, donde las protege su propio quórum. El libro contable por cliente, moneda y red, la idempotencia de las órdenes y la conciliación viven en nuestro sistema, porque ningún proveedor ve el total.

Esa frontera tiene una consecuencia de diseño. No conviene replicar las políticas del proveedor en nuestro código (se desalinean), pero sí registrar qué política estaba vigente cuando se aprobó cada movimiento. Y hay excepciones que el libro debe conocer: BitGo advierte que una recuperación con la llave de usuario y la de respaldo no pasa por sus políticas. [5] Un procedimiento de recuperación, por tanto, se registra en nuestro libro como evento extraordinario con aprobación propia.

Figura 1

Arquitectura de referencia: proveedores, bandeja de eventos, verificación y libro

Fuentes:

[11][12][13]

Cómo leer esta figura

Fila superior con cinco cajas: Fireblocks (MPC hot y warm, políticas, KYT), BitGo (custodia cold, whitelists), Circle Mint (mint y redeem de USDC), Tether en ocre (cuenta verificada, API a validar) y Banco (wires y extractos). De Fireblocks, BitGo y Circle Mint bajan flechas azules hasta una línea horizontal rotulada webhooks firmados, al menos una vez, sin orden garantizado; de Tether baja una flecha discontinua ocre. Fila central: bandeja de eventos que deduplica por id, flecha a verificar on-chain con bloque, hash y saldo, flecha verde a libro contable como fuente de verdad propia, flecha verde a conciliación diaria que compara libro, proveedor y cadena, y flecha roja rotulada difiere hacia excepciones, retener y escalar. Del banco baja una línea discontinua rotulada extractos hasta la conciliación. Fila inferior: de verificar on-chain baja una flecha a nodos e indexación, Kaleido o nodo propio, que apunta a redes públicas como Ethereum, Tron y Solana; de la conciliación baja una línea discontinua rotulada saldos del proveedor hacia las redes. Nota final: cada evento es una pista, no un hecho; el libro solo cambia tras verificar.

Descargar SVGDescargar .tex

Código TikZ

Abrir `.tex` en otra pestaña

Dónde corre cada firmante en nuestra red

Escenario: seguridad revisa el diagrama de red del Middleware Blockchain y pregunta qué servidores tocan material de llave. Con Fireblocks y BitGo la respuesta no es "ninguno": la firma automática exige componentes que corren en nuestra infraestructura. La tabla los ubica; el detalle de configuración, réplicas y TLS está en el módulo 6, firma operativa.

Fuentes. BitGo describe Express como un servicio ligero que corre como demonio en nuestro centro de datos y hace de proxy de su API, con la promesa de que las llaves privadas nunca salen de nuestra red. [20] Su README exige TLS cuando Express apunta a producción y escucha en interfaces externas. [21] El modo de signer externo añade una instancia en una máquina aislada donde se guardan las llaves de usuario y se firma, y no es compatible con wallets MPC ECDSA. [22] En Advanced Wallets, el AWM es un servidor aislado en una subred interna sin internet que solo acepta tráfico de MBE y solo habla con nuestro KMS, por TLS mutuo. [23] Fireblocks pide alojar el API Co-signer en nuestro entorno, en una máquina con enclaves (Intel SGX, AWS Nitro o Google Cloud Confidential Space), y permite conectar un callback handler que aprueba o rechaza cada solicitud; sin él, el co-signer firma o aprueba todo lo que le llega para ese usuario de API. [24]

Dos reglas salen de la tabla. Primera: en el diagrama, cada uno de estos componentes es una zona de confianza propia, no un microservicio más del orquestador. Segunda: el callback handler y la regla de política por webhook de BitGo [5] son el punto donde nuestra lógica de negocio vuelve a mirar cada firma; si no existen, la política del proveedor es el único control. Con wallets de custodia de BitGo no hace falta ninguno de los dos componentes de BitGo, porque firma BitGo.

Eventos y webhooks: al menos una vez, y verificados en la cadena

Un webhook es una llamada HTTP que el proveedor hace a nuestro servidor cuando algo cambia. Los tres que entregan eventos documentan lo mismo con distintas palabras. Circle entrega cada notificación al menos una vez, puede repetirla y no garantiza el orden; pide deduplicar por notificationId. [12] Fireblocks avisa que el mismo evento puede llegar varias veces y que no garantiza el orden, y recomienda guardar los ID procesados y comparar createdAt. [11] BitGo pide que la aplicación funcione aunque reciba el mismo webhook dos veces. [14]

Los reintentos marcan cuánto puede tardar un evento. Fireblocks reintenta con espera creciente (10 segundos, 30, 120, hasta 14.400) y marca la notificación como fallida tras diez intentos. [15] BitGo hace hasta siete intentos más, de 1 a 240 minutos, y suspende un webhook tras fallos consecutivos. [14] Sobre reenviar lo perdido, la guía de buenas prácticas de Fireblocks habla de hasta 24 horas y su resumen de Webhooks V2 de hasta 30 días; cuál aplica al workspace contratado queda a validar con el proveedor. [11] [16]

Antes de procesar, se verifica el origen. Fireblocks firma cada webhook con JWS y publica las llaves públicas en un endpoint JWKS por entorno. [17] BitGo firma con HMAC usando un secreto que el cliente crea y rota, y publica las IP de salida. [14] Un evento sin firma válida se descarta y se registra; no se responde con error que dispare reintentos inútiles.

Verificado el origen, el evento todavía no es un hecho. Fireblocks recomienda no acreditar al recibir el aviso de transacción: esperar el evento de saldo con una altura de bloque igual o mayor y comparar con la cadena; si no coinciden, no acreditar hasta investigar. [13] También pide comparar el hash del bloque, porque una reorganización puede cambiarlo a la misma altura. [13] En Ethereum, la consulta al nodo se hace contra una etiqueta de bloque explícita (latest, safe o finalized). [18] El capítulo Indexadores, eventos y reorgs desarrolla ese mecanismo.

Kaleido describe sus FireFly Connectors como una entrega de transacciones "exactamente una vez" y un flujo de eventos "sin eventos perdidos". [8] Aunque sea así dentro de su capa, nuestra bandeja no cambia de contrato: deduplica por ID y verifica en la cadena, porque el riesgo está en el tramo entre su sistema y el nuestro. Elegir qué nodo consulta esa verificación es otra decisión; diversidad de clientes explica por qué conviene que no sea el mismo que usa el custodio.

Conciliación: tres libros que deben cuadrar

Volvamos al depósito duplicado de las 03:10. Con la bandeja anterior, el segundo y el tercer aviso no producen efectos y el libro tiene 300.000 USDC. La conciliación diaria es la segunda red de seguridad: compara, por moneda y red, el libro propio, lo que informa cada proveedor (saldos de bóveda o wallet) y la cadena leída en nuestro nodo. Para el tramo bancario de USDC se suma el extracto CAMT.053 diario que genera Circle Mint. [19]

Cada diferencia tiene dueño y plazo. Las más comunes son tres: un evento que nunca llegó (se recupera con un reenvío o una consulta al arrancar, como recomienda Fireblocks tras una caída), un asiento sin respaldo en la cadena (se revierte con aprobación) y un saldo en la cadena que nadie registró (se investiga como posible depósito no atribuido). [13] Hasta que una diferencia se explica, la wallet afectada no envía.

La invariante del libro ómnibus

Los tres libros (el propio, el del proveedor y la cadena) solo cuadran si el libro propio respeta una regla, que en el Middleware Blockchain es la más importante: la suma de los saldos de todos los clientes en nuestro libro es igual al saldo en la cadena de las wallets ómnibus que los respaldan, por moneda y red, descontadas las operaciones en curso. Ningún proveedor la vigila por nosotros. Fireblocks lo dice sin rodeos: no ofrece un componente de libro interno para esta necesidad y cada cliente lo implementa como quiera; y, en redes con memo o tag, al no haber un saldo en la cadena por cliente que validar, nuestro sistema interno se vuelve la fuente de verdad. [25]

La invariante se comprueba en dos momentos. En cada depósito, antes de acreditar, con la validación por altura y hash de bloque descrita arriba. [13] Y en el cierre diario, sumando el libro por moneda y red y comparándolo con la cadena y con el proveedor. Una diferencia en el cierre no se corrige ajustando el libro: se explica, asiento por asiento. Cómo se construye ese libro, qué equivalente de "subcuenta sintética" ofrece cada proveedor y cómo se atribuye cada depósito se desarrolla en el módulo 8, ómnibus y libro interno.

Cuando dos proveedores cubren lo mismo: criterios para elegir

La matriz muestra solapamientos: los tres ofrecen políticas, y Fireblocks y BitGo ofrecen llaves MPC. Elegir por marca lleva a dos motores de políticas sobre el mismo saldo, que es el peor de los mundos: dos lugares donde un cambio puede abrir una puerta. Los criterios siguientes sirven para decidir cada solapamiento y dejar la razón escrita.

Un último criterio es la dependencia de proveedor (vendor lock-in): cuánto cuesta cambiar. Se mide con preguntas concretas que el contrato debe responder: si las llaves o fragmentos se pueden exportar, si el historial de transacciones se puede descargar completo, y cuánto código depende de identificadores propios del proveedor. Nuestro libro usa un identificador interno por moneda y red, y cada adaptador traduce; así cambiar un proveedor toca un adaptador, no el núcleo.

Entregable: matriz capacidad-proveedor validada

El entregable es la matriz de la primera sección, convertida en documento vivo. Cada celda pasa por tres estados: propuesta (sale de este capítulo), documentada (hay una fuente oficial citada) y validada (el proveedor la confirmó por escrito para nuestro contrato). Solo las celdas validadas entran en producción.

Este es el último capítulo de la ruta, el módulo 12. El anterior, liquidez y liquidación, cierra el circuito con contrapartes; USDC y Circle Mint y USDT y Tether definen los flujos con los emisores; Custodia, firma operativa, AML y KYT y ómnibus y libro interno fijan quién aprueba, qué corre en nuestra red, qué se analiza y cómo se lleva el libro. La arquitectura de una dApp en producción muestra el mismo patrón de idempotencia desde el lado del contrato.