Recuperación

Propósito

La recuperación de entity es el mecanismo para restablecer el control de una entity cuando se pierde la clave privada de la billetera propietaria, o para ejecutar una transferencia planificada del control organizacional (sucesión).

El sistema de recuperación de ULedgerNET gestiona ambos escenarios con el mismo mecanismo:

Recuperación por pérdida de clave: el archivo .ukey de la billetera propietaria se pierde, se destruye o se compromete. Las billeteras de recuperación ejecutan una aprobación por umbral para transferir la propiedad a una nueva billetera sin la clave privada anterior.
Sucesión organizacional: un cambio planificado de control (un empleado se va, un departamento se reestructura, cambia el principal de un agente) se ejecuta como un evento de recuperación con plena atribución on-chain.

Ambos caminos producen el mismo resultado: cambia la billetera propietaria de la entity, se actualiza el backlink wallet.Entity del nuevo propietario y el evento queda registrado permanentemente on-chain.

Configuración de recuperación

Antes de que sea posible cualquier recuperación, la entity debe tener una configuración de recuperación establecida. Esto se hace mediante CONFIGURE_ENTITY_RECOVERY:

{
    "entityAddress": "<entity-address>",
    "recoveryWallets": [
        "<recovery-wallet-1>",
        "<recovery-wallet-2>",
        "<recovery-wallet-3>"
    ],
    "threshold": 2
}

Campo	Descripción
`recoveryWallets`	Direcciones de billeteras de confianza autorizadas para aprobar la recuperación.
`threshold`	Número de aprobaciones de billeteras de recuperación requeridas para ejecutar.

Reglas de configuración

Solo el propietario actual de la entity puede configurar la recuperación.
Una nueva configuración de recuperación entra en vigor tras un período de espera (se almacena provisionalmente como PendingRecoveryConfig). Esto impide que un atacante que controle momentáneamente la billetera propietaria instale de inmediato un conjunto de recuperación malicioso.
La configuración pendiente se activa una vez transcurrido el período de espera y sin que se haya enviado ninguna cancelación.

Elección de las billeteras de recuperación

Las billeteras de recuperación deben:

Estar en poder de personas distintas o sistemas distintos a los de la billetera propietaria: separación geográfica u organizacional.
No ser billeteras hijas de la entity que se recupera; un subárbol padre comprometido no debe controlar su propia recuperación.
Estar registradas en la misma cadena que la entity.

Para una entity PERSONAL (usuario humano), las billeteras de recuperación típicas son: la billetera de un colega de confianza, la billetera de un oficial de seguridad corporativo y una billetera de almacenamiento en frío (cold storage).

Para una entity AGENT, las billeteras de recuperación suelen ser los principales humanos que poseen la entity padre del agente.

Ciclo de vida de la recuperación

CONFIGURE_ENTITY_RECOVERY
    El propietario establece las billeteras de recuperación + el umbral
    Se almacena provisionalmente como PendingRecoveryConfig (comienza el período de espera)
    ↓
    [transcurre el período de espera, la configuración se activa]
    ↓

--- Evento de pérdida de clave o de sucesión ---

REQUEST_ENTITY_RECOVERY
    Cualquier billetera puede iniciarla (el solicitante identifica la nueva billetera propietaria)
    Se abre el proceso de recuperación
    ↓

APPROVE_ENTITY_RECOVERY
    Cada billetera de recuperación envía un voto de aprobación
    Las aprobaciones se acumulan on-chain
    ↓
    [se reciben las aprobaciones del umbral]
    ↓

EXECUTE_ENTITY_RECOVERY
    Cualquier billetera ejecuta la recuperación (el umbral ya se alcanzó)
    El propietario de la entity cambia a la nueva billetera propietaria solicitada
    Se elimina el backlink wallet.Entity del propietario anterior
    Se establece el backlink wallet.Entity del nuevo propietario
    Se cierra el proceso de recuperación
    ↓

[Opcional en cualquier momento antes de la ejecución:]
CANCEL_ENTITY_RECOVERY
    El propietario (¿o cualquier billetera de recuperación?) cancela la recuperación en curso
    Se descartan todas las aprobaciones acumuladas
    Se cierra el proceso de recuperación

La recuperación en la práctica

Escenario 1: clave privada perdida

El archivo .ukey de la billetera ML-DSA-87 de Alice se destruye por una falla de hardware. Alice posee una entity ORGANIZATION con tres billeteras de recuperación configuradas, en poder de sus colegas Bob, Charlie y Dave (umbral = 2).

Alice (o cualquier parte) envía REQUEST_ENTITY_RECOVERY especificando una nueva billetera propietaria que Alice ha generado.
Bob envía APPROVE_ENTITY_RECOVERY. (1/2)
Charlie envía APPROVE_ENTITY_RECOVERY. (2/2, umbral alcanzado)
Cualquier parte envía EXECUTE_ENTITY_RECOVERY.
El propietario de la entity es ahora la nueva billetera de Alice. Su historial se conserva; su nueva billetera tiene el backlink de la entity.

Escenario 2: sucesión de un agente

El principal de un agente de IA (un usuario humano) deja la organización. Las billeteras de recuperación de la entity AGENT son el oficial de seguridad y el director de TI de la empresa (umbral = 2).

El director de TI envía REQUEST_ENTITY_RECOVERY con la billetera del nuevo principal como propietario destino.
El oficial de seguridad envía APPROVE_ENTITY_RECOVERY.
El director de TI envía APPROVE_ENTITY_RECOVERY (si ambos son billeteras de recuperación, o espera a un tercero).
Se alcanza el umbral. Se envía EXECUTE_ENTITY_RECOVERY.
El propietario de la entity del agente es ahora la billetera del nuevo principal. Los ancestros de la billetera del agente cambian en consecuencia; su cadena de entities ahora se remonta al nuevo principal.

El registro on-chain

Cada paso (configurar, solicitar, aprobar, ejecutar, cancelar) es una transaction firmada on-chain. Todo el evento de recuperación queda registrado permanentemente con:

Quién inició la recuperación.
Qué billeteras de recuperación aprobaron y en qué orden.
Cuándo (altura de bloque) ocurrió la ejecución.
Las direcciones de la billetera propietaria anterior y de la nueva.

Esto constituye una auditabilidad completa de la sucesión.

Almacenamiento provisional de la configuración de recuperación (período de espera)

Cuando se envía CONFIGURE_ENTITY_RECOVERY, la nueva configuración se almacena como PendingRecoveryConfig en lugar de sobrescribir de inmediato el RecoveryConfig activo. Este período de almacenamiento provisional impide que un atacante que controle brevemente la billetera propietaria cambie de inmediato el conjunto de recuperación y luego active una recuperación para apoderarse de la entity.

La configuración pendiente se activa una vez transcurrido el número de bloques de espera sin cancelación. La configuración activa durante el período de espera sigue siendo la anterior; la entity no queda desprotegida durante el almacenamiento provisional.

Recuperación y Billeteras de los Agentes

Cuando se recupera una entity AGENT:

El backlink wallet.Entity de la billetera del agente se actualiza para reflejar la billetera del nuevo propietario.
La recuperación no deshabilita la billetera del agente en sí; esta continúa operando bajo su alcance de capabilities.
Si el nuevo propietario desea redefinir el alcance del agente, envía ALTER_WALLET para actualizar las capabilities.
Si el nuevo propietario desea deshabilitar al agente, envía ALTER_WALLET con Enabled = false.

La recuperación no restablece ni revoca las capabilities. La gestión de capabilities tras la recuperación es responsabilidad del nuevo propietario.

Propósito​

Configuración de recuperación​

Reglas de configuración​

Elección de las billeteras de recuperación​

Ciclo de vida de la recuperación​

La recuperación en la práctica​

Escenario 1: clave privada perdida​

Escenario 2: sucesión de un agente​

El registro on-chain​

Almacenamiento provisional de la configuración de recuperación (período de espera)​

Recuperación y Billeteras de los Agentes​