# 🧵 Recover a Lost Account and Tokens
Welcome to the complete guide for the **"Recover a Lost Account"** workflow for the Token City Blockchain API.
This workflow enables you to **recover a lost blockchain account** along with its associated tokens, by generating the appropriate EIP712 signature and executing the recovery operation.
🌟 **Objective**: Securely recover a user's blockchain account and its token assets in case of account loss or compromise.
---
## 📚 OpenAPI Documentation
- [Swagger UI Token City Blockchain API](../api-1.8.1/blockchain-api-token-city)
---
## ✨ Workflow Summary
This workflow automates the recovery process of a lost account on the Token City blockchain:
1. 🔹 Generate typed data for EIP712 signature for the account recovery.
2. 🔹 Sign the generated EIP712 object using an authorized recovery agent account.
3. 🔹 Recover the lost account and its tokens using the signed data.
4. 🔹 Monitor recovery transaction status via webhook.
---
## 📋 Workflow Steps Table
| :------------------------- | :----------------------------------------------------------- | :----- | :------------------------------------------------ | :-------------------- | :---------------------------------------------------------------------- |
| Generate EIP712 Typed Data | `POST /erc3643/{tokenId}/recovery-address/eip712-typed-data` | POST | `tokenId`, `lostWallet`, `newWallet` | `typedData` | Prepares the typed data needed for EIP712 signing |
| Sign EIP712 Object | `POST /accounts/{accountId}/signEip712` | POST | `typedData` | `signature` | Signs the typed EIP712 object with an authorized recovery agent account |
| Recover Lost Account | `POST /erc3643/{tokenId}/recovery-address` | POST | `tokenId`, `lostWallet`, `newWallet`, `signature` | Transaction ID | Executes the account recovery and transfers tokens |
| Monitor Recovery Status | Webhook subscription | - | - | TX_MINED or TX_FAILED | Confirms recovery completion via webhook notification |
---
## 🎨 Workflow Visualizations
### 🌊 Mermaid Sequence Diagram
```mermaid
sequenceDiagram
participant Client
participant API
participant Blockchain
Client->>API: POST /erc3643/{tokenId}/recovery-address/eip712-typed-data
API-->>Client: (200) EIP712 typedData
Client->>API: POST /accounts/{accountId}/signEip712
API-->>Client: (200) signature
Client->>API: POST /erc3643/{tokenId}/recovery-address
API-->>Client: (200) Transaction ID
API->>Blockchain: Process recovery transaction
alt Transaction mined
Blockchain-->>API: TX_MINED
API-->>Client: Webhook: TX_MINED (tokens transferred)
else Transaction failed
Blockchain-->>API: TX_FAILED
API-->>Client: Webhook: TX_FAILED (with reason)
end
```
---
## 📝 Step-by-Step Implementation
### Step 1: Generate EIP712 Typed Data for Recovery
Generate the structured data required for signing the recovery operation.
**Endpoint:** `POST /erc3643/{tokenId}/recovery-address/eip712-typed-data`
**Path Parameters:**
- `tokenId`: UUID of the token from which to recover assets
**Request Body:**
```json
{
"lostWallet": "0xLostAddress1234567890abcdef1234567890abcdef",
"newWallet": "0xNewAddress0987654321fedcba0987654321fedcba",
"investorOnchainID": "0xIdentityAddress123456789abcdef123456789abc"
}
```
**Request Parameters:**
- `lostWallet`: The blockchain address that was lost/compromised
- `newWallet`: The new replacement wallet address
- `investorOnchainID`: The on-chain identity address of the investor
**Response:**
```json
{
"domain": {
"name": "TokenCityRecovery",
"version": "1.0.0",
"chainId": 137,
"verifyingContract": "0xTokenContractAddress..."
},
"types": {
"EIP712Domain": [
{ "name": "name", "type": "string" },
{ "name": "version", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "verifyingContract", "type": "address" }
],
"RecoverAddress": [
{ "name": "lostWallet", "type": "address" },
{ "name": "newWallet", "type": "address" },
{ "name": "investorOnchainID", "type": "address" }
]
},
"primaryType": "RecoverAddress",
"message": {
"lostWallet": "0xLostAddress1234567890abcdef1234567890abcdef",
"newWallet": "0xNewAddress0987654321fedcba0987654321fedcba",
"investorOnchainID": "0xIdentityAddress123456789abcdef123456789abc"
}
}
```
---
### Step 2: Sign the EIP712 Typed Data
Sign the typed data using an authorized recovery agent account.
**Endpoint:** `POST /accounts/{accountId}/signEip712`
**Path Parameters:**
- `accountId`: UUID of the authorized recovery agent account
**Request Body:**
```json
{
"typedData": {
"domain": {
"name": "TokenCityRecovery",
"version": "1.0.0",
"chainId": 137,
"verifyingContract": "0xTokenContractAddress..."
},
"types": {
"EIP712Domain": [
{ "name": "name", "type": "string" },
{ "name": "version", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "verifyingContract", "type": "address" }
],
"RecoverAddress": [
{ "name": "lostWallet", "type": "address" },
{ "name": "newWallet", "type": "address" },
{ "name": "investorOnchainID", "type": "address" }
]
},
"primaryType": "RecoverAddress",
"message": {
"lostWallet": "0xLostAddress1234567890abcdef1234567890abcdef",
"newWallet": "0xNewAddress0987654321fedcba0987654321fedcba",
"investorOnchainID": "0xIdentityAddress123456789abcdef123456789abc"
}
}
}
```
**Response:**
```json
{
"signature": "0xea8a0fb12ebadd4574b9fc1677ebfbede47f51d6afe352c625a4032b5f8e190d6ea64ee83e4eaf5d380ec1505d2f35cdcf80f38e66d677eea1ed45a3158c285c1b"
}
```
---
### Step 3: Execute Account Recovery
Execute the recovery operation with the signed data to transfer tokens to the new wallet.
**Endpoint:** `POST /erc3643/{tokenId}/recovery-address`
**Path Parameters:**
- `tokenId`: UUID of the token from which to recover assets
**Request Body:**
```json
{
"lostWallet": "0xLostAddress1234567890abcdef1234567890abcdef",
"newWallet": "0xNewAddress0987654321fedcba0987654321fedcba",
"investorOnchainID": "0xIdentityAddress123456789abcdef123456789abc",
"signature": "0xea8a0fb12ebadd4574b9fc1677ebfbede47f51d6afe352c625a4032b5f8e190d6ea64ee83e4eaf5d380ec1505d2f35cdcf80f38e66d677eea1ed45a3158c285c1b"
}
```
**Response:**
```json
{
"id": "tx_recovery_123e4567-e89b-12d3-a456-426614174000",
"status": "pending",
"message": "Recovery transaction submitted to blockchain",
"lostWallet": "0xLostAddress1234567890abcdef1234567890abcdef",
"newWallet": "0xNewAddress0987654321fedcba0987654321fedcba",
"tokenBalance": "1000000000000000000",
"estimatedCompletionTime": "2-5 minutes"
}
```
---
### Step 4: Monitor Recovery Status
Subscribe to webhooks or poll transaction status to confirm recovery completion.
**TX_MINED Webhook:**
```json
{
"type": "TX_MINED",
"event": {
"txUUID": "tx_recovery_123e4567-e89b-12d3-a456-426614174000",
"txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
"blockNumber": 12345678,
"operation": "recovery",
"tokensMoved": "1000000000000000000",
"fromAddress": "0xLostAddress1234567890abcdef1234567890abcdef",
"toAddress": "0xNewAddress0987654321fedcba0987654321fedcba",
"timestamp": 1634567890
}
}
```
**TX_FAILED Webhook:**
```json
{
"type": "TX_FAILED",
"event": {
"txUUID": "tx_recovery_123e4567-e89b-12d3-a456-426614174000",
"reason": "Unauthorized recovery agent",
"errorCode": "UNAUTHORIZED",
"timestamp": 1634567890
}
}
```
---
## 💡 Key Concepts
### What is Account Recovery?
Account recovery is a compliance feature in ERC-3643 tokens that allows:
- Transfer of tokens from a lost/compromised wallet to a new wallet
- Maintains the investor's on-chain identity
- Requires authorization from token agents or recovery agents
- Preserves compliance and KYC verifications
- Provides an audit trail for regulatory purposes
### Recovery Authorization
Only authorized recovery agents can execute recoveries:
- **Token Agents**: Designated by the token issuer with recovery permissions
- **Recovery Agents**: Specific addresses with dedicated recovery role
- **Multi-sig Wallets**: For enhanced security and governance
- **Issuer Accounts**: Issuers typically have recovery capabilities
### Identity Preservation
During recovery:
- The on-chain identity remains the same
- All KYC/AML claims stay valid
- Token balance is transferred atomically to the new wallet
- Compliance status is maintained
- Transfer restrictions still apply to the new wallet
### When to Use Recovery
Recovery is appropriate for:
- **Lost Private Keys**: Investor permanently lost access to wallet
- **Compromised Accounts**: Wallet security breached
- **Device Loss**: Hardware wallet or device stolen/destroyed
- **Death/Incapacitation**: Inheritance or legal transfer
- **Technical Issues**: Wallet software corruption
---
## ⚠️ Important Notes
1. **Authorization Required**: Only token agents with recovery permissions can execute recoveries
2. **Identity Link**: The on-chain identity must match the lost wallet's registered identity
3. **New Wallet Setup**: New wallet should be created and registered before recovery
4. **Balance Transfer**: All token balance is moved atomically; partial recovery not supported
5. **Irreversible**: Recovery transactions cannot be undone once mined
6. **Compliance**: New wallet inherits all compliance requirements and restrictions
7. **Verification**: Carefully verify typed data matches exactly before signing
8. **Documentation**: Maintain records of recovery for audit purposes
---
## 🔗 Related Endpoints
- [Generate Recovery Typed Data](../api-1.8.1/recovery-address-eip-712-typed-data)
- [Execute Recovery](../api-1.8.1/recovery-address)
- [Sign EIP712](../api-1.8.1/sign-eip-712-typed-data)
- [Subscribe to Webhooks](../api-1.8.1/create-webhook-subscription)
- [Create Valid Investor Account](./create-valid-investor-account)
---
## 🆘 Troubleshooting
### Recovery Transaction Failed
If recovery fails, verify:
- ✓ Signer has recovery agent permissions on the token
- ✓ Lost wallet address is correct and has non-zero token balance
- ✓ New wallet address is valid and different from lost wallet
- ✓ On-chain identity address matches the lost wallet's registered identity
- ✓ New wallet has been registered in identity registry
- ✓ New wallet has required KYC/AML claims
- ✓ Signature is valid and matches typed data exactly
- ✓ Sufficient gas is available for the transaction
### Identity Mismatch Error
If you get an identity mismatch:
- ✓ Verify the investorOnchainID belongs to the lost wallet
- ✓ Check identity registry for the correct identity address
- ✓ Ensure identity was not previously updated or transferred
- ✓ Confirm identity contract is deployed and accessible
- ✓ Query the token's identity registry to verify the link
### Unauthorized Recovery Agent
If authorization fails:
- ✓ Verify signer account is a recovery agent on the token contract
- ✓ Check agent permissions using token's `isAgent()` function
- ✓ Ensure recovery agent role hasn't been revoked
- ✓ Confirm signer account matches the one used for signing
- ✓ Contact token issuer to grant or restore recovery permissions
### New Wallet Not Registered
If new wallet cannot receive tokens:
- ✓ New wallet must have on-chain identity created first
- ✓ Identity must be registered in token's identity registry
- ✓ Required claims (KYC/AML) must be added to new identity
- ✓ Follow "Create Valid Investor Account" guide for new wallet
- ✓ Verify identity is approved and not suspended
### Signature Validation Failed
If signature is rejected:
- ✓ Typed data structure matches exactly the response from Step 1
- ✓ No modifications were made to the typed data before signing
- ✓ Correct account was used for signing (recovery agent)
- ✓ EIP712 domain parameters match (chainId, verifyingContract)
- ✓ Message fields are in correct format (addresses, etc.)
---
## 📚 Additional Resources
- [ERC-3643 Standard - Recovery](https://eips.ethereum.org/EIPS/eip-3643#recovery)
- [HMAC Authentication Guide](./hmac-authentication)
- [Create Valid Investor Account](./create-valid-investor-account)
- [Webhook Notification Guide](./send-transaction-and-receive-status-via-webhook)
- [Corporate Events Guide](./send-corporative-event)
---
## 💼 Use Case Examples
### Example 1: Investor Lost Private Key
**Scenario:** An investor lost their hardware wallet containing 1000 security tokens.
**Initial State:**
- Lost wallet: `0xLost...123`
- Token balance: 1000 tokens
- On-chain identity: `0xIdentity...abc`
- New wallet: Not yet created
**Step 1 - Create and Register New Wallet:**
Follow "Create Valid Investor Account" guide:
```json
{
"pincode": "secure456",
"type": "ETHEREUM",
"description": "Recovery Wallet - John Investor"
}
```
New wallet created: `0xNew...456`
Register identity and add KYC claims
**Step 2 - Generate Recovery Typed Data:**
```json
{
"lostWallet": "0xLost...123",
"newWallet": "0xNew...456",
"investorOnchainID": "0xIdentity...abc"
}
```
**Step 3 - Recovery Agent Signs:**
Token agent with recovery permissions signs the typed data
**Step 4 - Execute Recovery:**
```json
{
"lostWallet": "0xLost...123",
"newWallet": "0xNew...456",
"investorOnchainID": "0xIdentity...abc",
"signature": "0xea8a0fb..."
}
```
**Step 5 - Confirmation:**
TX_MINED webhook received confirming 1000 tokens moved to new wallet
**Result:** Investor successfully recovered access to 1000 tokens while maintaining compliance status and identity.
---
### Example 2: Compromised Account Emergency Recovery
**Scenario:** Suspicious transactions detected, immediate recovery needed.
**Timeline:**
- **T+0 min**: Suspicious transfer detected
- **T+5 min**: Account frozen by compliance team
- **T+10 min**: New secure wallet created
- **T+15 min**: Recovery typed data generated
- **T+17 min**: Emergency recovery agent signs
- **T+20 min**: Recovery executed
- **T+23 min**: TX_MINED - tokens safely in new wallet
**Actions Taken:**
1. Froze compromised account to prevent further unauthorized transfers
2. Created new wallet with enhanced security (multi-sig)
3. Executed recovery with emergency recovery agent
4. Updated investor records with new wallet address
5. Unfroze new wallet for normal operations
**Result:** Fast 23-minute recovery prevented token loss from compromised account.
---
### Example 3: Inheritance Transfer via Recovery
**Scenario:** Token holder passed away, estate needs to transfer tokens to beneficiary.
**Documents Required:**
- Death certificate
- Probate court order
- Beneficiary identity verification
- Estate executor authorization
**Process:**
1. Create corporate event for forced transfer (via ERIR if required)
2. Alternatively, use recovery mechanism if permitted by token rules
3. Estate executor acts as authorized recovery agent
4. Generate recovery data for deceased's wallet → beneficiary wallet
5. Execute with proper authorization and documentation
**Considerations:**
- May require ERIR approval depending on jurisdiction
- Both forced transfer and recovery mechanisms can be used
- Recovery maintains identity link; forced transfer creates new identity
- Choose method based on token's governance rules
**Result:** Compliant transfer of deceased holder's tokens to rightful beneficiary with full audit trail.
---
### Example 4: Hardware Wallet Failure
**Scenario:** Hardware wallet device failed, seed phrase not backed up.
**Problem:**
- Device: Ledger Nano S (failed, won't power on)
- Tokens: 500 tokens in wallet
- Seed phrase: Not written down (user error)
- Device: Out of warranty, unrecoverable
**Solution via Recovery:**
1. Contacted Token City support
2. Verified identity through KYC records
3. Created new hardware wallet with proper backup
4. Token issuer assigned recovery agent permission
5. Recovery agent executed wallet recovery
6. Tokens transferred to new, properly backed-up wallet
**Lessons Learned:**
- Always backup seed phrases securely
- Recovery is a safety net, not a replacement for proper security
- Keep contact with token issuer for emergency situations
**Result:** Despite poor security practices, investor recovered tokens through compliant recovery process. Now uses proper backup procedures.