15. Recover a position from a lost wallet

A recovery restores a position to a holder who can no longer use the wallet that holds it. An agent moves the whole balance of the lost wallet to another address of the same identity, with its freezes. It is the path for a holder who cannot act, and for a wallet that holds frozen tokens: a holder who still controls its ONCHAINID moves its free tokens itself, with a transfer through the identity.

At a glance

Triggered by	Token Agent, at the request of the Investor
Actors	Investor, Issuer, Token Agent, Platform
Contracts	Token, TREXRegistry, IdentityRegistryStorage, ModularCompliance, compliance modules
Preconditions	The caller holds AGENT_RECOVERY_ADDRESS in the asset's domain (see 25); the lost wallet holds tokens on the reference chain; the lost wallet or the new address resolves to an identity in the asset's registry; the token is not paused; the Issuer has verified, under its own process, that the person asking is the holder
Result	The whole balance of the lost wallet, with its freezes, is at the new address, attributed to the same identity

Actors and roles

Actor	Role in this flow	What they hold
Investor	Asks for the recovery and proves who it is, off-chain. Does not transact.	An ONCHAINID. A new address: the ONCHAINID itself or another wallet
Issuer	Verifies the request under its own process and decides. Does not transact in this flow.	Its evidence of the holder's identity
Token Agent	Submits the recovery.	AGENT_RECOVERY_ADDRESS on the Token
Platform	Runs the reads and submits with the Token Agent's key.	The Token Agent's signing key, or a key authorized for it

Sequence

Step by step

Step 1. Verify the request

Who: Issuer and Platform

Call: Off-chain, using read calls

Before the call: The Investor has asked for the recovery and given the new address.

What happens: The Issuer verifies, under its own process, that the person asking is the holder of the identity. The Platform reads TREXRegistry.identity(lostWallet), which gives the identity that owns the position, and passes that identity in the call. It reads TREXRegistry.identity(newWallet): the result is zero, or that same identity. It reads Token.balanceOf(lostWallet), which must not be zero, and Token.paused(), which must be false. If part of the position is active on a satellite, the recovery does not reach it.

What changes: Nothing on-chain.

Step 2. Recover the position

Who: Token Agent (AGENT_RECOVERY_ADDRESS)

Call: Token.recoveryAddress(lostWallet, newWallet, investorOnchainID)

Before the call: Step 1 is done.

What the contract checks:

1. The caller holds AGENT_RECOVERY_ADDRESS in the asset's domain. Otherwise the call reverts with AccessManagedUnauthorized.

2. The two addresses are different. Otherwise SameWalletRecovery.

3. The lost wallet holds tokens. Otherwise NoTokenToRecover.

4. At least one of the two addresses resolves to an identity in the registry. Otherwise RecoveryNotPossible.

5. If the new address resolves to an identity, it is the identity named in the call. Otherwise RecoveryNotPossible.

6. The token is not paused. Otherwise EnforcedPause.

The contract does not check who is asking. It does not check that the identity named in the call is the one the lost wallet resolves to. A recovery that names another identity is accepted, when the new address already belongs to that identity or is not known to the registry. It does not evaluate the eligibility of the identity or the compliance rules.

What changes:

• When the new address resolves to no identity, the token registers it for the named identity in the asset's registry. The storage emits IdentityStored and the registry emits IdentityRegistered.

• The token moves the whole balance of the lost wallet to the new address and emits Transfer(lostWallet, newWallet, balance).

• A frozen amount on the lost wallet is carried over: the token emits TokensUnfrozen(lostWallet, amount) and TokensFrozen(newWallet, amount).

• An address freeze on the lost wallet is carried over: the token emits AddressFrozen(lostWallet, false, token) and, if the new address was not already frozen, AddressFrozen(newWallet, true, token).

• The token calls ModularCompliance.transferred(lostWallet, newWallet, balance). When both addresses belong to one identity, no position changes. When the new address belongs to another identity, the position moves to it. The TRACKER modules are told.

• When the lost wallet has a local registration, the token deletes it. The storage emits IdentityUnstored and the registry emits IdentityRemoved.

• The token emits RecoverySuccess(lostWallet, newWallet, investorOnchainID).

Step 3. Confirm the effect

Who: Platform

Call: Off-chain, using read calls

Before the call: Step 2 is confirmed.

What happens: The Platform reads Token.balanceOf(newWallet), Token.getFrozenTokens(newWallet) and Token.isFrozen(newWallet). It reads TREXRegistry.identity(newWallet), which returns the identity, and TREXRegistry.isVerified(newWallet). The Platform tells the Investor to revoke the lost wallet on its identity if it was linked there.

What changes: Nothing on-chain.

State after the flow

• Token.balanceOf(lostWallet) is zero and Token.balanceOf(newWallet) has increased by the recovered balance.

• Token.getFrozenTokens(newWallet) has increased by what was frozen on the lost wallet. A recovery releases nothing.

• If the lost wallet was frozen as an address, it no longer is, and the new address is.

• TREXRegistry.identity(newWallet) returns the identity. If the new address resolved nowhere, it now has a local registration.

• The lost wallet has no local registration. If its owner linked it in the global identity registry, that link is unchanged.

• ModularCompliance.positionOf(identity) is unchanged, for a recovery within one identity.

• Token.totalSupply() is unchanged.

Failure modes

Symptom	Cause	Fix
Reverts with AccessManagedUnauthorized	The caller does not hold AGENT_RECOVERY_ADDRESS in the asset's domain (step 2, check 1)	Grant the role: 25
Reverts with AccessManagedUnauthorized, naming the token	The token does not hold AGENT on the registry, which it needs to register the new address. The suite is not commissioned	Commission the suite: 25
Reverts with SameWalletRecovery	The lost wallet and the new address are the same (step 2, check 2)	Pass another address of the holder
Reverts with NoTokenToRecover	The lost wallet holds nothing on the reference chain (step 2, check 3)	Nothing to recover. For a position on a satellite, see the last row
Reverts with RecoveryNotPossible	Neither address resolves to an identity (step 2, check 4), or the new address belongs to another identity than the one named (step 2, check 5)	Read identity(lostWallet) and identity(newWallet). Pass the identity that owns the position, and an address that is unknown or belongs to it
Reverts with EnforcedPause	The token is paused (step 2, check 6)	Lift the pause first: 16
The recovery succeeded and the new address cannot receive further tokens	The identity lacks a valid claim for a required topic. A recovery does not check eligibility	Have the claim renewed: 05
The recovery succeeded and the position moved to another identity	The identity named in the call is not the one the lost wallet resolves to. The new address already belonged to that identity, or was unknown and was registered under it. The function allows it: it is a change of ownership, with no eligibility check	To stay within one identity, pass the identity the lost wallet resolves to (step 1). A recovery across identities is the Issuer's decision, to be taken as carefully as a forced transfer
The lost wallet still resolves to the identity	Its owner linked it in the global identity registry, which an agent cannot change	The owner revokes it: 23
Part of the position is still at the lost wallet's address on a satellite	A recovery acts on the reference chain	An agent recalls the position, then recovers it: 32

Common misunderstandings

Wrong: "A recovery restores access to the wallet."

Right: Nothing is restored on the lost wallet. Its tokens are moved to another address of the same holder. The wallet itself stays as it was, empty.

Wrong: "A recovery is a way out of a freeze."

Right: The freezes travel with the tokens. A frozen amount is frozen again at the new address, and a frozen address stays frozen. A forced transfer releases a freeze. A recovery does not.

Wrong: "The contract checks that the request comes from the holder."

Right: The contract checks the role of the caller and the consistency of the addresses. Verifying who is asking is the Issuer's procedure, done before the call. The RecoverySuccess event makes every recovery visible.

Wrong: "A recovery is the answer to every loss."

Right: It answers one case: the holder cannot move the tokens itself. A holder that still controls its ONCHAINID moves them with a transfer through the identity. A holder that lost the keys of its ONCHAINID recovers the identity through its guardians. An identity lost for good calls for a forced transfer to the holder's new identity.

Integration notes

• Read identity(lostWallet) and pass exactly that identity. It is what keeps the recovery inside one identity.

• The new address can be the ONCHAINID itself. A holder that lost a wallet does not need another wallet.

• A recovery moves the whole balance. There is no amount argument.

• A recovery also empties a wallet its owner has revoked. It is the only way to move frozen tokens out of such a wallet, since a transfer through the identity moves the free balance only.

• Index RecoverySuccess(lostWallet, newWallet, identity). The freeze events of a recovery name the token itself as the actor.

• A recovery is per asset. A holder that lost a wallet holding several assets is recovered on each token. Assets that share an identity storage share the registration of the new address.

• After the recovery, the holder revokes the lost wallet on its identity, so that the wallet can no longer receive any asset.

Related flows

• 24 Transfer through the identity : what a holder does itself when it still controls its identity

• 23 Revoke a wallet : ending the global link of the lost wallet

• 21 Recover access to an ONCHAINID : when the keys of the identity are lost

• 14 Execute a forced transfer : moving a position to another identity

• 13 Freeze and unfreeze an address or a partial balance : the freezes a recovery carries over

• 16 Pause and unpause a token : a recovery waits for the pause to be lifted