Sistema de Billeteras de ULedgerNET

Descripción General

ULedgerNET implementa un sistema de billeteras jerárquico que soporta relaciones padre-hijo, control de acceso basado en permisos y gestión de billeteras en cascada. Esta arquitectura permite la gestión de identidades a nivel empresarial mientras mantiene la seguridad criptográfica.

Arquitectura de Billetera

Estructura Jerárquica

🔍 click to expand

Tipos de Billetera

Tipo	Descripción	Campo Padre
Billetera Padre	Billetera de nivel raíz sin padre	Vacío
Billetera Hija	Creada por una billetera padre	Dirección del padre
Billetera Satélite	Término para cualquier billetera descendiente	Rastreado por el padre

Estructura de Billetera

Propiedades Principales

🔍 click to expand

Detalles de Propiedades

Propiedad	Tipo	Descripción
publicKey	string	La clave pública de la billetera (codificada en hex)
address	string	Hash SHA256 de la clave pública en minúsculas
parent	string	Dirección de la billetera padre (vacío para billeteras raíz)
enabled	boolean	Si la billetera puede realizar transacciones
satelliteWallets	string[]	Lista de direcciones de billeteras hijas
authGroups	map	Grupos de permisos para control de acceso
keyType	enum	Algoritmo criptográfico (secp256k1, ED25519, BLS12-377, ML-DSA-87)

Sistema de Permisos

Grupos de Autorización

ULedgerNET utiliza un sistema de permisos flexible basado en grupos de autorización:

🔍 click to expand

Estructura de Permisos

Cada grupo de autorización contiene permisos CRUD:

Permiso	Descripción
Create	Crear nuevas entradas de este tipo
Read	Leer entradas existentes
Update	Modificar entradas existentes
Delete	Eliminar entradas

Grupos Integrados

Grupo	Propósito
admin	Acceso administrativo completo (CRUD completo en todos los recursos)
wallet	Permisos de gestión de billeteras (crear, actualizar billeteras hijas)

Lógica de Verificación de Administrador

Una billetera se considera administradora si tiene el grupo admin con los cuatro permisos habilitados:

🔍 click to expand

Operaciones de Billetera

Creación de Billeteras

🔍 click to expand

Payload de Transacción: Crear Billetera

Campo	Tipo	Requerido	Descripción
publicKey	string	Sí	Clave pública para la nueva billetera
keyType	enum	Sí	Tipo de clave criptográfica
authGroups	map	No	Permisos iniciales para la billetera

Requisitos de la Billetera Padre

Para crear una billetera hija, el padre debe:

1. Existir en el blockchain
2. Estar habilitado (no deshabilitado)
3. Tener permiso - ya sea:
   • Ser administrador (grupo admin con CRUD completo)
   • Tener el grupo wallet con permiso create

Modificación de Billetera

Operación de Modificación de Billetera

🔍 click to expand

Payload de Transacción: Modificar Billetera

Campo	Tipo	Requerido	Descripción
target	string	Sí	Dirección de la billetera a modificar
enabled	boolean	Sí	Nuevo estado de habilitación
authGroups	map	No	Permisos actualizados

Reglas de Autorización

Escenario	Autorización Requerida
Padre modificando hijo	El padre debe tener wallet.update o ser administrador
Billetera modificándose a sí misma	Debe tener wallet.update o ser administrador
No existe padre	Solo la billetera misma puede modificarse

Deshabilitación en Cascada

Deshabilitación Automática de Hijos

Cuando una billetera padre es deshabilitada, todas las billeteras descendientes son deshabilitadas automáticamente:

🔍 click to expand

Algoritmo en Cascada

🔍 click to expand

Esto garantiza que:

• Ninguna billetera hija huérfana permanezca activa
• La suspensión de cuentas empresariales se propague correctamente
• La revocación de seguridad sea integral

Validación de Transacciones

Verificaciones Previas a la Validación

Antes del procesamiento, las transacciones se validan contra las transacciones pendientes:

🔍 click to expand

Requisitos de Validación

Verificación	Descripción
Billetera existente	La billetera objetivo debe existir (para modificar)
Billetera Habilitada	La billetera debe estar habilitada para realizar transacciones
Coincidencia de Tipo de Clave	El tipo de clave de la transacción debe coincidir con la billetera
Firma Válida	Verificación de firma criptográfica
Autorización del Padre	El padre debe autorizar las operaciones del hijo

Identidad de la Billetera

Derivación de Dirección

Las direcciones de billetera se derivan de forma determinista a partir de las claves públicas:

🔍 click to expand

Esto garantiza:

• Generación consistente de direcciones entre nodes
• Imposibilidad de colisión de direcciones
• La dirección puede verificar la propiedad de la clave pública

Tipos de Clave Soportados

Tipo de Clave	Algoritmo	Resistente a Quantum
secp256k1	ECDSA	❌
ED25519	EdDSA	❌
BLS12-377	BLS Signatures	❌
ML-DSA-87	Dilithium	✅

Referencia de API

Obtener Billetera

GET /blockchains/{blockchain_id}/wallets/{address}

Respuesta:

{
  "publicKey": "04a1b2c3...",
  "address": "abc123...",
  "parent": "",
  "enabled": true,
  "satelliteWallets": ["def456...", "ghi789..."],
  "authGroups": {
    "admin": {"create": true, "read": true, "update": true, "delete": true}
  },
  "keyType": 0
}

Transacción de Creación de Billetera

POST /blockchains/{blockchain_id}/transactions

Cuerpo de la Solicitud:

{
  "from": "parent_address",
  "to": "new_wallet_address", 
  "payloadType": "CREATE_WALLET",
  "payload": "{\"publicKey\":\"04abc...\",\"keyType\":0,\"authGroups\":{}}",
  "senderSignature": "signature_hex"
}

Transacción de Modificación de Billetera

POST /blockchains/{blockchain_id}/transactions

Cuerpo de la Solicitud:

{
  "from": "parent_or_self_address",
  "payloadType": "ALTER_WALLET",
  "payload": "{\"target\":\"wallet_address\",\"enabled\":false}",
  "senderSignature": "signature_hex"
}

Casos de Uso Empresarial

Jerarquía Organizacional

🔍 click to expand

Revocación de Acceso

Cuando un empleado se va:

1. Deshabilitar la billetera del empleado
2. Todas sus billeteras hijas son deshabilitadas automáticamente
3. No se pueden iniciar más transacciones
4. Las transacciones confirmadas existentes permanecen en la cadena

Gestión de Departamentos

• Los jefes de departamento pueden crear billeteras para sus equipos
• Los líderes de equipo pueden crear billeteras para los miembros del equipo
• Cada nivel tiene los permisos apropiados

Consideraciones de Seguridad

Gestión de Claves

Práctica	Recomendación
Billeteras raíz	Usar HSM o almacenamiento seguro de claves
Rotación de Claves	Crear una nueva billetera hija, deshabilitar la antigua
Respaldo	Respaldo seguro de claves privadas
Registros de Acceso	Monitorear operaciones de la billetera

Mejores Prácticas de Permisos

Práctica	Recomendación
Mínimo Privilegio	Otorgar los permisos mínimos requeridos
Administrador con Moderación	Limitar la asignación del grupo admin
Profundidad de Jerarquía	Mantener la jerarquía manejable
Auditorías Regulares	Revisar los permisos de la billetera periódicamente

Comportamiento de Billeteras Deshabilitadas

• Las billeteras deshabilitadas no pueden enviar transacciones
• Las billeteras deshabilitadas no pueden firmar operaciones de billeteras hijas
• Las transacciones existentes permanecen válidas
• La rehabilitación requiere autorización del padre

---

Fin de la Serie de Documentación Técnica