Billeteras

¿Qué Es una Billetera?

Una billetera es una identidad criptográfica en una cadena de ULedger. Consta de:

• Un par de claves (clave pública + clave privada) generado a partir de entropía BIP39.
• Una dirección (address) derivada como SHA256(lowercase(publicKey)): determinista, no aleatoria.
• Una referencia parent: la billetera que creó a esta (vacía para las billeteras raíz).
• Un mapa de grupos de autorización (auth groups): conjuntos de permisos CRUD basados en roles.
• Una lista de capabilities: permisos detallados, acotados y con vencimiento.
• Una lista de billeteras satélite: direcciones de todas las billeteras hijas directas.
• Una bandera enabled: las billeteras deshabilitadas no pueden firmar ni enviar transactions.
• Un tipo de clave (key type): el algoritmo criptográfico (fijado en la creación; debe coincidir con la cadena).

Las billeteras no almacenan fondos en el sentido tradicional. Contienen permisos, firman transactions y sirven como ancla de identidad para todas las acciones en la cadena.

---

Estructura de Datos de la Billetera

UL_Wallet {
    PublicKey        string                       // Compressed hex public key
    Address          string                       // SHA256(lowercase(publicKey))
    Parent           string                       // Parent wallet address ("" = root)
    Entity           string                       // Primary entity affiliation backlink
    Enabled          bool
    SatelliteWallets []string                     // Direct children
    AuthGroups       map[string]UL_AuthPermission // "admin" and "wallet" groups
    Capabilities     []Capability                 // Scoped permissions
    KeyType          string                       // secp256k1 | ed25519 | mldsa87 | bls12377
}

UL_AuthPermission {
    Create bool
    Read   bool
    Update bool
    Delete bool
}

---

Tipos de Clave de Billetera

El tipo de clave se establece al crear la cadena y se aplica a todas las billeteras de esa cadena.

Tipo de Clave	Algoritmo	Notas
secp256k1	ECDSA sobre la curva secp256k1	Compatible con Bitcoin/Ethereum; ampliamente soportado.
ed25519	EdDSA sobre Curve25519	Verificación más rápida; firmas más pequeñas.
mldsa87	ML-DSA-87 (CRYSTALS-Dilithium nivel 5)	Poscuántico; recomendado para cadenas de auditoría a largo plazo.
bls12377	BLS sobre la curva BLS12-377	Agregación de firmas; casos de uso especializados.

Las claves privadas de las billeteras se generan a partir de frases mnemónicas BIP39 (opcionalmente protegidas con una frase de contraseña) y se almacenan en archivos .ukey. La clave privada nunca sale del proceso del SDK; solo se transmiten a la red las firmas y las claves públicas.

---

Jerarquía de Billeteras

Las billeteras forman un árbol. Toda billetera, excepto las billeteras raíz, tiene una dirección Parent que apunta a la billetera que la creó.

Root Wallet (Parent = "")
├── Child Wallet A (Parent = Root)
│   ├── Grandchild Wallet A1 (Parent = Child A)
│   └── Grandchild Wallet A2 (Parent = Child A)
└── Child Wallet B (Parent = Root)
    └── Grandchild Wallet B1 (Parent = Child B)

Las billeteras padre registran a todas sus hijas directas en su arreglo SatelliteWallets. Esto permite recorrer un subárbol completo a partir de cualquier billetera.

Reglas de la Jerarquía

• Una billetera raíz tiene Parent == "" y, antes de vincularse a una entity, no debe tener ya una afiliación a una entity.
• Una billetera hija no hereda más permisos de los que posee su padre. La herencia de capabilities se aplica en la creación: las capabilities de una hija deben ser un subconjunto estricto de las de la billetera padre.
• Deshabilitar una billetera padre mediante ALTER_WALLET se propaga en cascada mediante BFS a todos sus descendientes; todas las billeteras satélite se deshabilitan de forma atómica. Esta es la única operación sobre subárboles que es atómica.
• Volver a habilitar una billetera padre no vuelve a habilitar automáticamente a sus hijas. La rehabilitación debe hacerse explícitamente por cada billetera.

---

Grupos de Autorización (Auth Groups)

Toda billetera incluye dos auth groups estándar: admin y wallet.

Grupo admin

Controla el acceso administrativo a la propia billetera y a su entity. Una billetera con permisos admin completos (Create+Read+Update+Delete) puede:

• Modificar la configuración de la propia billetera.
• Vincular la billetera a una entity como miembro con rol de administrador.
• Crear billeteras hijas.

Grupo wallet

Controla las capacidades de creación y actualización de billeteras dentro del ámbito de autoridad de la billetera.

Full admin example:
AuthGroups = {
    "admin": { Create: true, Read: true, Update: true, Delete: true },
    "wallet": { Create: true, Read: true, Update: true, Delete: true }
}

Read-only wallet:
AuthGroups = {
    "admin": { Create: false, Read: true, Update: false, Delete: false },
    "wallet": { Create: false, Read: true, Update: false, Delete: false }
}

Importante: los auth groups controlan los permisos administrativos. Los permisos de acción detallados (p. ej., "invocar este contrato") se manejan mediante Capabilities, no mediante auth groups. Ver Capabilities.

---

Ciclo de Vida de la Billetera

1. Generar

# Generate wallets with secp256k1 keys
go run ./cmd/generate_wallets --type=secp256k1

# Generate wallets with an authority group assigned
go run ./cmd/generate_wallets --type=mldsa87 --auth=admin

Se generan archivos .ukey en el directorio ./wallets. Cada archivo contiene el par de claves de una billetera.

2. Registrar

go run ./cmd/register_wallets

Se envían transactions TX_CREATE_WALLET para todas las billeteras en ./wallets, incorporándolas a la blockchain. Hasta que se registre, la dirección de una billetera no es reconocida por la cadena.

3. Modificar

go run ./cmd/alter_wallets

Se envían transactions ALTER_WALLET para actualizar auth groups, adjuntar capabilities, habilitar/deshabilitar o modificar la configuración de la billetera.

4. Crear Billeteras Hijas

Una billetera registrada con wallet.Create == true en sus auth groups puede crear billeteras hijas enviando transactions TX_CREATE_WALLET que se referencien a sí misma como parent.

5. Deshabilitar / Cascada

# Via SDK: submit ALTER_WALLET with Enabled = false

Deshabilitar una billetera envía ALTER_WALLET. El procesador realiza una cascada BFS, deshabilitando de forma atómica todas las billeteras satélite. Este es el paro de emergencia para todo un subárbol de agentes.

---

El Backlink de Entity (wallet.Entity)

Una billetera tiene un único campo Entity (su afiliación primaria a una entity). Este campo se establece solo en circunstancias específicas:

Cuándo se establece wallet.Entity	Disparador
Una billetera raíz crea una entity	La billetera creadora pasa a ser la propietaria de la entity
Una billetera con rol de administrador se vincula a una entity	El vínculo con rol de administrador establece el backlink
Se transfiere la propiedad	Se actualiza el backlink de la billetera de la nueva propietaria
Se ejecuta una recuperación	Se actualiza el backlink de la billetera recuperada

Los vínculos con rol de miembro no establecen wallet.Entity. Una billetera vinculada a una entity con un rol member y bits de permiso específicos tiene poder dentro de esa entity, pero su afiliación primaria no cambia. Esto permite que las billeteras participen en múltiples entities sin confundir su hogar primario.

---

Archivos de Billetera (Formato .ukey)

Las claves privadas de las billeteras se almacenan como archivos .ukey. El nombre del archivo es la dirección de la billetera (hash de la clave pública). Ejemplo:

./wallets-uis-mldsa/8e620db359101eb28bf9db4f08c2677349f7747d1c59528774f2193318b8c1c7.ukey

El SDK carga estos archivos al firmar transactions. Se deben mantener seguros los archivos .ukey; contienen el material de la clave privada sin cifrar.