🧵 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

✨ Workflow Summary

This workflow automates the recovery process of a lost account on the Token City blockchain:

🔹 Generate typed data for EIP712 signature for the account recovery.
🔹 Sign the generated EIP712 object using an authorized recovery agent account.
🔹 Recover the lost account and its tokens using the signed data.
🔹 Monitor recovery transaction status via webhook.

📋 Workflow Steps Table

Step	API Operation	Method	Parameters	Outputs	Description
Generate EIP712 Typed Data	`POST /erc3643/{tokenId}/recovery-address/eip712-typed-data`	POST	`tokenId`, `oldAccount`, `newAccount`	EIP712 Typed Data	Prepares the typed data needed for EIP712 signing
Sign EIP712 Object	`POST /accounts/{accountId}/signEip712`	POST	`passcode`, `eip712Object`	`eip712Signature`	Signs the typed EIP712 object with an authorized recovery agent account
Recover Lost Account	`POST /erc3643/{tokenId}/recovery-address`	POST	`tokenId`, `oldAccount`, `newAccount`, `identity`, `nonce`, `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

📝 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:

{
  "oldAccount": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "newAccount": "0xbe188D6641E8b680743A4815dFA0f6208038960F"
}

Request Parameters:

oldAccount: Address of the wallet to be recovered
newAccount: Address of the new wallet

Response:

{
{
  "passcode": "123456",
  "eip712Object": {
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "version", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "RecoverAddress": [
        { "name": "oldAccount", "type": "address" },
        { "name": "newAccount", "type": "address" },
        { "name": "identity", "type": "address" }
      ]
    },
    "primaryType": "RecoverAddress",
    "domain": {
      "name": "TokenCityRecovery",
      "version": "1.0.0",
      "chainId": 137,
      "verifyingContract": "0xTokenContractAddress..."
    },
    "message": {
      "oldAccount": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
      "newAccount": "0xbe188D6641E8b680743A4815dFA0f6208038960F",
      "identity": "0x5Bbfb5dAB27c0b32FDdAa6705d8B23E070a7613e",
      "nonce": "10"
    }
  }
}
}

Step 2: Sign the EIP712 Typed Data

Sign the typed data using an authorized recovery account (ERIR / Tc Validator Account).

Endpoint: POST /accounts/{accountId}/signEip712

Path Parameters:

accountId: WalletAddress of authorized recovery agent account

Request Body:

{
  "passcode": "123456",
  "eip712Object": {
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "version", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "RecoverAddress": [
        { "name": "oldAccount", "type": "address" },
        { "name": "newAccount", "type": "address" },
        { "name": "identity", "type": "address" }
      ]
    },
    "primaryType": "RecoverAddress",
    "domain": {
      "name": "TokenCityRecovery",
      "version": "1.0.0",
      "chainId": 137,
      "verifyingContract": "0xTokenContractAddress..."
    },
    "message": {
      "oldAccount": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
      "newAccount": "0xbe188D6641E8b680743A4815dFA0f6208038960F",
      "identity": "0x5Bbfb5dAB27c0b32FDdAa6705d8B23E070a7613e",
      "nonce": "10"
    }
  }
}

Response:

{
  "eip712Signature": "0x2d98d5a2b62d9fa3c599227f6106462c0c8158e1ae558efa0037a74c354565803eb82ecf16a89dc6a466d6adab39d3fc3bc50ea6950601a02f58cfa0cd312c6d1b"
}

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:

{
  "oldAccount": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
  "newAccount": "0xbe188D6641E8b680743A4815dFA0f6208038960F",
  "identity": "0x5Bbfb5dAB27c0b32FDdAa6705d8B23E070a7613e",
  "nonce": "1",
  "signature": "0x2d98d5a2b62d9fa3c599227f6106462c0c8158e1ae558efa0037a74c354565803eb82ecf16a89dc6a466d6adab39d3fc3bc50ea6950601a02f58cfa0cd312c6d1b"
}

Request Parameters:

oldAccount: Address of the wallet to be recovered
newAccount: Address of the new wallet
identity: Address of the identity contract from which the old wallet will be removed and the new one added
nonce: Unique number per request to prevent replay attacks
signature: EIP712 signature of the request

Response:

{
  "id": "567e7895-c76b-12d3-a456-426614174000"
}

Step 4: Monitor Recovery Status

Subscribe to webhooks or poll transaction status to confirm recovery completion.

TX_MINED Webhook:

{
  "type": "TX_MINED",
  "event": {
    "txUUID": "tx_recovery_123e4567-e89b-12d3-a456-426614174000",
    "txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "timestamp": 1634567890
  }
}

TX_FAILED Webhook:

{
  "type": "TX_FAILED",
  "event": {
    "txUUID": "tx_recovery_123e4567-e89b-12d3-a456-426614174000",
    "reason": "Unauthorized recovery agent",
    "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:

Accepted Validators: Designated by the token issuer with recovery permissions (ERIR / TC Validator Wallet)

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 pincode and emergencyCode: Investor permanently lost access to wallet
Compromised Accounts: Wallet security breached
Technical Issues: Wallet software corruption

⚠️ Important Notes

Authorization Required: Only token agents with recovery permissions can execute recoveries
Identity Link: The identity address must match the old wallet's registered identity
New Wallet Setup: New wallet should be created and registered before recovery
Balance Transfer: All token balance is moved atomically; freezed and unfreezed also
Irreversible: Recovery transactions cannot be undone once mined
Compliance: New wallet inherits all compliance requirements and restrictions
Verification: Carefully verify typed data matches exactly before signing
Documentation: Maintain records of recovery for audit purposes
Nonce: Each recovery request requires a unique nonce to prevent replay attacks

🆘 Troubleshooting

Recovery Transaction Failed

If recovery fails, verify:

✓ Signer has recovery agent permissions on the token
✓ Old account address is correct and has non-zero token balance
✓ New account address is valid and different from old account
✓ Identity address matches the old account's registered identity
✓ New account has been registered in identity registry
✓ Signature is valid and matches typed data exactly
✓ Nonce is unique and hasn't been used before
✓ Sufficient gas is available for the transaction

Unauthorized Recovery Agent

If authorization fails:

✓ Verify signer account is a recovery agent on the token contract
✓ Ensure recovery agent role hasn't been revoked
✓ Confirm signer account matches the one used for signing

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

💼 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 New Wallet:

POST /accounts

New wallet created: 0xNew...456

Step 2 - Generate Recovery Typed Data:

{
  "oldAccount": "0xLost...123",
  "newAccount": "0xNew...456"
}

Response:

{
  "passcode": "123456",
  "eip712Object": {
    "types": {
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "version", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ],
      "RecoverAddress": [
        { "name": "oldAccount", "type": "address" },
        { "name": "newAccount", "type": "address" },
        { "name": "identity", "type": "address" }
      ]
    },
    "primaryType": "RecoverAddress",
    "domain": {
      "name": "TokenCityRecovery",
      "version": "1.0.0",
      "chainId": 137,
      "verifyingContract": "0xTokenContractAddress..."
    },
    "message": {
      "oldAccount": "0xdE394eD7ac8Ca7E5Ed89F54BA3B02Aed7aD12343",
      "newAccount": "0xbe188D6641E8b680743A4815dFA0f6208038960F",
      "identity": "0x5Bbfb5dAB27c0b32FDdAa6705d8B23E070a7613e",
      "nonce": "10"
    }
  }
}

Step 3 - Recovery Agent Signs: Token agent with recovery permissions signs the EIP712 typed data

Step 4 - Execute Recovery:

{
  "oldAccount": "0xLost...123",
  "newAccount": "0xNew...456",
  "identity": "0xIdentity...abc",
  "nonce": "1",
  "signature": "0x2d98d5a..."
}

Response: { "id": "567e7895-c76b-12d3-a456-426614174000" }

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.

📚 OpenAPI Documentation​

✨ Workflow Summary​

📋 Workflow Steps Table​

🎨 Workflow Visualizations​

🌊 Mermaid Sequence Diagram​

📝 Step-by-Step Implementation​

Step 1: Generate EIP712 Typed Data for Recovery​

Step 2: Sign the EIP712 Typed Data​

Step 3: Execute Account Recovery​

Step 4: Monitor Recovery Status​

💡 Key Concepts​

What is Account Recovery?​

Recovery Authorization​

Identity Preservation​

When to Use Recovery​

⚠️ Important Notes​

🔗 Related Endpoints​

🆘 Troubleshooting​

Recovery Transaction Failed​

Unauthorized Recovery Agent​

Signature Validation Failed​

📚 Additional Resources​

💼 Use Case Examples​

Example 1: Investor Lost Private Key​

📚 OpenAPI Documentation

✨ Workflow Summary

📋 Workflow Steps Table

🎨 Workflow Visualizations

🌊 Mermaid Sequence Diagram

📝 Step-by-Step Implementation

Step 1: Generate EIP712 Typed Data for Recovery

Step 2: Sign the EIP712 Typed Data

Step 3: Execute Account Recovery

Step 4: Monitor Recovery Status

💡 Key Concepts

What is Account Recovery?

Recovery Authorization

Identity Preservation

When to Use Recovery

⚠️ Important Notes

🔗 Related Endpoints

🆘 Troubleshooting

Recovery Transaction Failed

Unauthorized Recovery Agent

Signature Validation Failed

📚 Additional Resources

💼 Use Case Examples

Example 1: Investor Lost Private Key