Skip to main content

Recovery

Purpose​

Entity recovery is the mechanism for restoring control of an entity when the owner wallet's private key is lost, or for executing a planned transfer of organizational control (succession).

ULedgerNET's recovery system handles both scenarios with the same mechanism:

  • Key loss recovery: the owner wallet's .ukey file is lost, destroyed, or compromised. Recovery wallets execute threshold approval to transfer ownership to a new wallet without the old private key.
  • Organizational succession: a planned change of control (an employee leaves, a department is restructured, an agent's principal changes) is executed as a recovery event with full on-chain attribution.

Both paths produce the same result: the entity's owner wallet changes, the new owner's wallet.Entity backlink is updated, and the event is permanently recorded on-chain.

Recovery Configuration​

Before any recovery is possible, an entity must have a recovery configuration set. This is done via CONFIGURE_ENTITY_RECOVERY:

{
    "entityAddress": "<entity-address>",
    "recoveryWallets": [
        "<recovery-wallet-1>",
        "<recovery-wallet-2>",
        "<recovery-wallet-3>"
    ],
    "threshold": 2
}
FieldDescription
recoveryWalletsAddresses of trusted wallets authorized to approve recovery.
thresholdNumber of recovery wallet approvals required to execute.

Configuration Rules​

  • Only the current entity owner can configure recovery.
  • A new recovery configuration takes effect after a delay period (staging as PendingRecoveryConfig). This prevents an attacker who momentarily controls the owner wallet from immediately installing a malicious recovery set.
  • The pending config becomes active after the delay elapses and no cancellation is submitted.

Choosing Recovery Wallets​

Recovery wallets should be:

  • Held by different people or different systems than the owner wallet: geographic or organizational separation.
  • Not child wallets of the entity being recovered; a compromised parent subtree should not control its own recovery.
  • Registered on the same chain as the entity.

For a PERSONAL entity (human user), typical recovery wallets are: a trusted colleague's wallet, a corporate security officer's wallet, and a cold storage wallet.

For an AGENT entity, recovery wallets are typically the human principals who own the agent's parent entity.

Recovery Lifecycle​

CONFIGURE_ENTITY_RECOVERY
    Owner sets recovery wallets + threshold
    Staged as PendingRecoveryConfig (delay period begins)
    ↓
    [delay elapses, config becomes active]
    ↓

--- Key loss or succession event ---

REQUEST_ENTITY_RECOVERY
    Any wallet can initiate (the requestor identifies the new owner wallet)
    Recovery process opens
    ↓

APPROVE_ENTITY_RECOVERY
    Each recovery wallet submits an approval vote
    Approvals accumulate on-chain
    ↓
    [threshold approvals received]
    ↓

EXECUTE_ENTITY_RECOVERY
    Any wallet executes the recovery (threshold already met)
    Entity owner changes to the requested new owner wallet
    Old owner's wallet.Entity backlink is cleared
    New owner's wallet.Entity backlink is set
    Recovery process closed
    ↓

[Optional at any point before execution:]
CANCEL_ENTITY_RECOVERY
    Owner (or any recovery wallet?) cancels the in-progress recovery
    All accumulated approvals discarded
    Recovery process closed

Recovery in Practice​

Scenario 1: Lost Private Key​

Alice's ML-DSA-87 wallet .ukey file is destroyed in a hardware failure. Alice holds an ORGANIZATION entity with three configured recovery wallets held by her colleagues Bob, Charlie, and Dave (threshold = 2).

  1. Alice (or any party) submits REQUEST_ENTITY_RECOVERY specifying a new owner wallet Alice has generated.
  2. Bob submits APPROVE_ENTITY_RECOVERY. (1/2)
  3. Charlie submits APPROVE_ENTITY_RECOVERY. (2/2, threshold met)
  4. Any party submits EXECUTE_ENTITY_RECOVERY.
  5. The entity's owner is now Alice's new wallet. Her history is preserved; her new wallet has the entity backlink.

Scenario 2: Agent Succession​

An AI agent's principal (a human user) leaves the organization. The AGENT entity's recovery wallets are the company's security officer and IT director (threshold = 2).

  1. IT director submits REQUEST_ENTITY_RECOVERY with the new principal's wallet as the target owner.
  2. Security officer submits APPROVE_ENTITY_RECOVERY.
  3. IT director submits APPROVE_ENTITY_RECOVERY (if they are both recovery wallets, or wait for a third).
  4. Threshold met. EXECUTE_ENTITY_RECOVERY submitted.
  5. The agent entity's owner is now the new principal's wallet. The agent wallet's ancestry changes accordingly; its entity chain now traces to the new principal.

The On-Chain Record​

Every step (configure, request, approve, execute, cancel) is a signed transaction on-chain. The entire recovery event is permanently recorded with:

  • Who initiated the recovery.
  • Which recovery wallets approved and in what order.
  • When (block height) execution occurred.
  • The old and new owner wallet addresses.

This is full succession auditability.

Recovery Config Staging (Delay Period)​

When CONFIGURE_ENTITY_RECOVERY is submitted, the new configuration is stored as PendingRecoveryConfig rather than immediately overwriting the active RecoveryConfig. This staging period prevents an attacker who briefly controls the owner wallet from immediately changing the recovery set and then triggering recovery to seize the entity.

The pending config activates after the delay block count elapses with no cancellation. The active config during the delay period is still the previous one; the entity is not unprotected during staging.

Recovery and Agent Wallets​

When an AGENT entity is recovered:

  1. The agent wallet's wallet.Entity backlink is updated to reflect the new owner's wallet.
  2. The agent wallet itself is not disabled by recovery; it continues operating under its capability scope.
  3. If the new owner wants to re-scope the agent, they submit ALTER_WALLET to update capabilities.
  4. If the new owner wants to disable the agent, they submit ALTER_WALLET with Enabled = false.

Recovery does not reset or revoke capabilities. Capability management after recovery is the new owner's responsibility.