Sistema de Wallet de ULedgerNET

Descripción General

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

Arquitectura de Wallet

Estructura Jerárquica

🔍 click to expand

Tipos de Wallet

Tipo	Descripción	Campo Padre
Wallet Padre	Wallet de nivel raíz sin padre	Vacío
Wallet Hijo	Creado por un wallet padre	Dirección del padre
Wallet Satélite	Término para cualquier wallet descendiente	Rastreado por el padre

Estructura de Wallet

Propiedades Principales

🔍 click to expand

Detalles de Propiedades

Propiedad	Tipo	Descripción
publicKey	string	La clave pública del wallet (codificada en hex)
address	string	Hash SHA256 de la clave pública en minúsculas
parent	string	Dirección del wallet padre (vacío para wallets raíz)
enabled	boolean	Si el wallet puede realizar transacciones
satelliteWallets	string[]	Lista de direcciones de wallets hijo
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 wallet (crear, actualizar wallets hijo)

Lógica de Verificación de Administrador

Un wallet se considera administrador si tiene el grupo admin con los cuatro permisos habilitados:

🔍 click to expand

Operaciones de Wallet

Creación de Wallets

🔍 click to expand

Payload de Transacción: Crear Wallet

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

Requisitos del Wallet Padre

Para crear un wallet hijo, 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 Wallet

Operación de Modificación de Wallet

🔍 click to expand

Payload de Transacción: Modificar Wallet

Campo	Tipo	Requerido	Descripción
target	string	Sí	Dirección del wallet 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
Wallet modificándose a sí mismo	Debe tener wallet.update o ser administrador
No existe padre	Solo el wallet mismo puede modificarse

Deshabilitación en Cascada

Deshabilitación Automática de Hijos

Cuando un wallet padre es deshabilitado, todos los wallets descendientes son deshabilitados automáticamente:

🔍 click to expand

Algoritmo en Cascada

🔍 click to expand

Esto garantiza que:

• Ningún wallet hijo huérfano permanezca activo
• 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
Wallet Existente	El wallet objetivo debe existir (para modificar)
Wallet Habilitado	El wallet debe estar habilitado para realizar transacciones
Coincidencia de Tipo de Clave	El tipo de clave de la transacción debe coincidir con el wallet
Firma Válida	Verificación de firma criptográfica
Autorización del Padre	El padre debe autorizar las operaciones del hijo

Identidad del Wallet

Derivación de Dirección

Las direcciones de wallet 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 Wallet

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 Wallet

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 Wallet

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 el wallet del empleado
2. Todos sus wallets hijo son deshabilitados 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 wallets para sus equipos
• Los líderes de equipo pueden crear wallets para los miembros del equipo
• Cada nivel tiene los permisos apropiados

Consideraciones de Seguridad

Gestión de Claves

Práctica	Recomendación
Wallets Raíz	Usar HSM o almacenamiento seguro de claves
Rotación de Claves	Crear nuevo wallet hijo, deshabilitar el antiguo
Respaldo	Respaldo seguro de claves privadas
Registros de Acceso	Monitorear operaciones del wallet

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 del wallet periódicamente

Comportamiento de Wallets Deshabilitados

• Los wallets deshabilitados no pueden enviar transacciones
• Los wallets deshabilitados no pueden firmar operaciones de wallets hijo
• Las transacciones existentes permanecen válidas
• La rehabilitación requiere autorización del padre

---

Fin de la Serie de Documentación Técnica