SKIP TO CONTENT
TOKENIZATION6 minBuilding the RWA Chain / Ep. 4 · Stage 4-2

Token Recovery: How Tokens Move Without the Lost Key

Take an invented case: an investor loses the wallet that holds 500 tokens. How does the issuer’s agent move them, and could it pick the wrong wallet?

XIN
Pixel-art night scene: a brass key locked inside a glass vault on a rooftop, while from a taller tower next door a magenta crane arm lowers a hook toward the gold token coin sitting beside the vault.

IN 30 SECONDS

Token recovery is an agent-only function that moves a lost wallet’s whole balance to a new wallet, without the lost key. In the reference code, it checks the new wallet against an identity the agent supplies.

KEY TAKEAWAYS · 3

  • In the T-REX reference code, recovery is a forced transfer with an identity check in front. The lost wallet’s key is never used.
  • The check trusts the identity the agent passes in. It never compares it with the one registered for the lost wallet.
  • A forced transfer emits an ordinary Transfer event, so monitoring has to check which function was called.
On this page

How token recovery works, step by step

IN SHORT Recovery is a forced transfer with an identity check in front, and the lost wallet’s key is never used.

WORDS TO KNOW

Agent role
Addresses the token lets freeze wallets, force transfers and recover tokens, without the holder’s key. Who holds it is a deployment choice.
Forced transfer
A transfer an agent makes out of a wallet without that wallet’s signature.
Identity registry
The token’s list linking each wallet to an investor identity.
Claim
A signed statement about an investor, from an issuer the token trusts, such as “passed identity checks”.

Recovery is for an investor who lost access to a wallet. The ERC-3643 spec makes it mandatory.

… MUST have a recovery system in case an investor loses access to his private key.

The ERC-3643 specification

In the T-REX reference code, only the Agent role Addresses the token lets freeze wallets, force transfers and recover tokens, without the holder’s key. Who holds it is a deployment choice. See the glossary can start it.

STEP BY STEP

Flow diagram: 5 stepsFlow diagram: 5 steps. Agent starts recovery, then Is the new wallet a management key?. Is the new wallet a management key?, then List the new wallet. List the new wallet, then Force the whole balance across. Force the whole balance across, then Delete the old entry, log the recovery.1Agent starts recovery2Is the new wallet amanagement key?On the identity the agentsupplies3List the new walletSame identity, lost wallet’scountry code4Force the whole balanceacrossFreezes applied again5Delete the old entry, logthe recovery
The function is recoveryAddress; its onlyAgent guard rejects any other caller. In code: keyHasPurpose(newWallet, 1). Purpose 1 is a management key.

Step 1. Agent call. Only an address with the agent role can call the recovery function.

Pick a step to see it move
  1. Agent call Only an address with the agent role can call the recovery function.
  2. Identity check The new wallet must be a management key, one allowed to administer the identity, on the identity record (ONCHAINID) the agent passes in.
  3. Register The token lists the new wallet in its identity registry, with that identity and the lost wallet’s country code.
  4. Move A forced transfer moves the full balance. Any frozen amount and address freeze are applied again.
  5. Trail The old wallet’s registry entry is deleted and a RecoverySuccess event is emitted: a public trail.
What the recovery function does in the T-REX reference code (commit f139012). Implementations can differ.

WATCH OUT

Look at step 2. The code doesn’t check that the identity is the one registered for the lost wallet. It trusts the agent’s input.

The Forced transfer A transfer an agent makes out of a wallet without that wallet’s signature. See the glossary still needs the new wallet to pass the verified check. That takes a wallet listed in the Identity registry The token’s list linking each wallet to an investor identity. See the glossary, whose identity holds the valid Claim A signed statement about an investor, from an issuer the token trusts, such as “passed identity checks”. See the glossary the token requires.

IN PLAIN WORDS

Part of the custody question moves to whoever holds those identity keys, and part goes back to the agent.

In this code, pausing the token stops ordinary transfers but not this one. The forced transfer also pulls frozen tokens along, unfreezing the amount it needs.

Coming up next: What if the agent passes in someone else’s identity?

A worked example: one recovery, one blind spot

IN SHORT The same recovery call works for the rightful holder, and also when the agent passes in a different identity.

A WORKED EXAMPLE

Illustrative numbers

PASSInvented case: recovery to the holder’s own new wallet

INPUT

Lost wallet
0x9f2c...e41a
Balance
500 tokens, 100 frozen
Identity passed in
the holder’s own

WHAT HAPPENS

  1. The new wallet is a management key on that identity, so the check passes.
  2. A forced transfer moves all 500 tokens, and 100 are frozen again.
  3. The lost wallet’s entry is deleted and the recovery is logged.

OUTPUT

New wallet
500 tokens, 100 frozen
Lost wallet’s key
never used

NOT CAUGHTSame call, a different identity passed in

INPUT

Identity passed in
another one, where the new wallet is a management key

WHAT HAPPENS

  1. The check only asks if the new wallet is a management key on that identity.
  2. It never compares it with the identity registered for the lost wallet.
  3. If that identity holds valid claims from the token’s trusted issuers, the wallet passes the verified check and all 500 move.

OUTPUT

Result
balance moves
What limits it
who holds the agent role, and their process

ITEM GET

The agent is the safeguard

The code never compares the new identity with the lost wallet’s, so the agent’s own process decides whether a recovery goes to the right person.

A forced transfer emits an ordinary Transfer event. To tell it from a holder-signed transfer, monitoring has to check which function was called.

If the agent is a multisig, that can take a trace. And monitoring only detects a move after the fact; it doesn’t prevent it. Sources: ERC-3643, T-REX Token.sol (commit f139012).

FAQ

Technically, whenever someone other than the key holder can change the balance, as an ERC-3643 agent can. Whether that changes who “holds the security in custody” is the SEC’s question. This series doesn’t answer it, and it isn’t legal advice.

They add a second path to move the position. In the T-REX code only the agent role can call them, and a forced transfer can move frozen tokens. The spec requires both, so the question is who holds the agent role, under what controls.

STAGE CLEAR

What you now know

  • How recovery moves a whole balance to a new wallet, frozen amounts included, without the lost key.
  • Why the identity check depends on the agent, not on the lost wallet’s record.

Check yourself

Tap or click a question to see the answer.

Illustrative case: a custodian’s monitoring shows only ordinary Transfer events out of its wallet this month. Can it conclude that no agent moved its tokens?

No. A forced transfer also emits an ordinary Transfer event. It has to check which function was called, which can take a trace when the agent is a multisig.

Next stage:Who can hold these powers, and which design choices change how much the key decides?6 min
Adam Boudjemaa
Adam Boudjemaa

Web3 x AI engineer, former CTO of Integra. Named author (1 of 5) of ERC-3643, first author of ERC-6960, co-author of ERC-7410, and co-author of ERC-8203, which is still a draft.

Have a project to ship or a role to fill?

Discuss your project or role

My work at the web3 x AI intersectionOpen-source tools I build

LinkedInTwitterGitHub
Follow the engineering notes

Get new articles on production AI and smart contracts by email.