Arquitectura del Sistema
Diagrama de capas
┌─────────────────────────────────────────────────────────────────────┐
│ Integraciones externas │
│ Agentes LLM · Frameworks de IA · Backends de aplicaciones │
└─────────────────────────┬───────────────────────────────────────────┘
│ HTTP / Go SDK
┌─────────────────────────▼───────────────────────────────────────────┐
│ Go SDK (golang-sdk) │
│ Gestión de billeteras · Envío de transactions · Runners de pruebas │
│ Ciclo de vida de identidad · Orquestación del council · Recibos │
└─────────────────────────┬───────────────────────────────────────────┘
│ HTTP (REST)
┌─────────────────────────▼───────────────────────────────────────────┐
│ Servidor web del nodo │
│ Middleware de auth · Límite de tasa · Despacho de rutas │
│ /chains · /wallets · /entities · /contracts · /credentials │
└──────┬──────────────────────┬──────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────────────────────────────────────────┐
│ Blockchain │ │ Capa de consenso │
│ (por cadena)│ │ Votación BFT · Buffers de propuestas/votos │
│ │◄───│ Caché de miembros · Acuerdo de quórum │
│ Procesadores│ │ Finalización de bloques │
│ (60+ tipos │ └──────────────────────────────────────────────────┘
│ de TX) │
└──────┬──────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Tipos de dominio centrales │
│ Wallet · Entity · Transaction · Block · Capability · Contract │
└──────┬──────────────────────┬──────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────────────────────────────────────────┐
│ Almacenam. │ │ Subsistemas de ejecución │
│ BadgerDB │ │ ULVM (wazero WASM) · Cripto · Pruebas · Identidad│
│ + sidecar │ │ Credenciales · Red (libp2p QUIC+GossipSub) │
└─────────────┘ └──────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Sidecar Helix STARK (por nodo) │
│ Probador Plonky3 · Checkpoints · Plegado recursivo de pruebas │
│ Auditor independiente · Anclaje entre algoritmos │
└─────────────────────────────────────────────────────────────────────┘
Nodos y councils
Un council es el conjunto de nodos validadores que alcanzan consenso BFT sobre una cadena. En un despliegue de producción, el runbook de Helix describe un council de 9 nodos, cada uno alojando:
- Cadena principal (
secp256k1): la cadena de consenso primaria. - Cadena de miembros A (
secp256k1): cadena secundaria de actividad de miembros. - Cadena de miembros B (
mldsa87): cadena de miembros post-cuántica.
Cada cadena tiene un consenso BFT independiente. Un checkpoint requiere el acuerdo del quórum del council antes de escribirse.
Puertos de los nodos (local por defecto)
| Servicio | Puertos |
|---|---|
| Servidor web del nodo (API HTTP) | 8080–8088 |
| Administración del nodo | 8200–8208 |
| p2p del nodo (libp2p) | 9080–9088 |
| Sidecar Helix (por nodo) | 8100–8108 |
| Auditor independiente | 8120 |
| Relay DHT | 4001 |
Cadenas y tipos de clave
Una cadena se identifica mediante un ID de blockchain (un hash hexadecimal). En el momento de crear la cadena se fija el algoritmo de clave. Todas las billeteras de esa cadena deben usar ese algoritmo. Para la referencia completa de algoritmos se puede consultar Tipos de clave de billetera.
Las claves de las billeteras se derivan de mnemónicos BIP39 con entropía. La clave privada de una billetera nunca sale del SDK; solo la clave pública y las transactions firmadas tocan la red.
Ciclo de vida de la transaction
1. CONSTRUCT
El SDK construye el payload de la transaction (tipo, campos, dirección
del remitente)
2. SIGN
El SDK firma el payload con la clave privada del remitente (archivo .ukey)
3. SUBMIT
HTTP POST a cualquier endpoint de nodo → pool de pendientes
4. GOSSIP
El nodo transmite la transaction a los pares mediante GossipSub (libp2p)
5. VALIDATE
Durante la propuesta del bloque: las verificaciones de autorización
(ancestros, capabilities, listas negras) se ejecutan contra el estado actual
6. EXECUTE
El procesador de bloques ejecuta la transaction: actualiza billeteras,
entities, estado de contratos, saldos de tokens
7. COMMIT
Bloque finalizado, estado confirmado en BadgerDB + archivos sidecar
8. CONFIRM
El SDK consulta a cualquier nodo (incluso uno distinto del de envío)
para obtener el recibo de la transaction, y se confirma la consistencia
entre nodos
Verificaciones de autorización (se ejecutan en los pasos 5 y 6)
- La cadena de ancestros de la entity del remitente debe estar completamente habilitada.
- La cadena de gobernanza de la entity destino respeta las listas negras.
- Los destinatarios de transferencias de valor pueden autoincluirse en la lista negra.
- Las billeteras restringidas por capability se verifican contra las capabilities que poseen.
- El vencimiento de la capability se evalúa al momento de la ejecución (comparación de altura de bloque).
Arquitectura de almacenamiento
ULedgerNET utiliza un modelo de almacenamiento híbrido:
- BadgerDB almacena una clave centinela de un solo byte por registro (verificaciones rápidas de existencia de claves).
- Los archivos sidecar almacenan en disco los registros serializados completos.
- Ruta de lectura: caché en memoria acotada → centinela de BadgerDB → lectura del archivo sidecar.
Esto mantiene BadgerDB compacto sin perder la capacidad de auditar el conjunto completo de registros en archivos planos.
El registro de credenciales es local al nodo; no se replica entre nodos. Cada nodo emite y rastrea sus propias verifiable credentials de forma independiente.
Pipeline de pruebas Helix STARK
Bloques finalizados por el consenso BFT
│
▼
El sidecar Helix (por nodo) recopila encabezados de bloque + datos de miembros
│
▼
El probador Plonky3 genera una prueba STARK para el lote de la época
│
▼
Plegado recursivo de pruebas: cada prueba de época se pliega en la cadena previa
│
▼
Checkpoint escrito en la cadena principal (anclado entre algoritmos:
firmas secp256k1 + ML-DSA-87 sobre el mismo checkpoint)
│
▼
El auditor independiente verifica el checkpoint sin acceso a ningún nodo
El resultado es una prueba de tamaño constante que cubre un historial de cadena de longitud arbitraria. Un auditor no necesita reproducir toda la cadena; solo se requieren las pruebas de checkpoint y las claves públicas de los miembros del council.
SDK de Go como capa de integración
El SDK de Go (github.com/ULedgerInc/golang-sdk) es la interfaz de integración principal. Proporciona:
- Generación y registro de billeteras: crear e incorporar billeteras a partir de entropía BIP39.
- Envío de transactions y sondeo: enviar cualquier tipo de transaction, consultar el recibo, verificar la consistencia entre nodos.
- Runners de pruebas por dominio: arneses con aserciones de extremo a extremo para los dominios de token, contract, walletops, data y council.
- Ciclo de vida de identidad: crear DIDs, emitir verifiable credentials, configurar la recuperación.
- Orquestación del council: ciclo de vida completo de propuestas: agregar miembros, autorizar agentes, crear propuestas, emitir work tokens, enviar votos, finalizar.
El SDK lee las claves de billetera de archivos .ukey, usa una configuración JSON para los endpoints de los nodos y los parámetros de la cadena, y escribe reportes JSON con marca de tiempo para cada ejecución.
Capa de red
La comunicación entre nodos utiliza libp2p con:
- Transporte: QUIC (principal) + TCP (respaldo)
- Seguridad: handshake del protocolo Noise
- Descubrimiento: DHT (Kademlia) mediante un nodo relay de arranque (bootstrap)
- Mensajería: GossipSub para la propagación de transactions y los anuncios de bloques
Los nodos se autentican entre sí mediante sus pares de claves. El relay DHT en el puerto 4001 sirve como punto de arranque para los nuevos nodos que se unen al council.