# IOTA post Chrysalis reclaim process

*Updated 17th May 2021* by Antonio Nardella
20210517 CHANGELOG:
- Added guide to use HBMY’s iotaZeroBalanceHelper
20210511 CHANGELOG:
- Added version 0.0.3 of the reclaim tool
- Added notice for address checksum
- Added Troubleshooting section with guide to find address checksum using the IOTA Explorer
- Added version 0.0.4 of the reclaim tool

---
### **IMPORTANT NOTICE** As of this [blog post](https://https://blog.iota.org/iota-community-treasury-and-genesis-validation/) all the reclaims submissions will **close** on June 16th 2021 at 23:59 UTC.
---

### Security
Never share the seed, private key, Ledger passphrase with 24 words with anyone - including members of the IOTA Foundation.

IOTA Foundation members and moderators will never ask for your seed, your private keys, or your Ledger passphrase of 24 words. “Never” really means “never”. There are no exceptions, **ever**.

---

[TOC]

## What do you need
* Your **ORIGINAL SEED** with the frozen funds (`81 characters from A-Z and number 9`)
* **ALL ADDRESSES WITH CHECKSUM** with the frozen funds (If you have more addresses with frozen funds it will be necessary to repeat the reclaim process for every address; with checksum means 90 characters in total)
* A **NEW ADDRESS** generated with Firefly (starting with `iota`)

If you already have this information at hand please go straight to [The Chrysalis reclaim process](#The-Chrysalis-reclaim-process)

## The Original Seed

First things first let's make sure it is the **correct and original seed** and it is a reclaim case, unless it was already verified by an IOTA Foundation member before.

**IMPORTANT** This is **necessary** as the seed confirms the ownership of the tokens. Using the *wrong* seed during the reclaim process will **not** make it possible to reclaim the tokens.

There are a few ways to verify the seed, let's have a look at them

### OPTION A: Use the Trinity wallet

- Download and set up the latest version of the [Trinity wallet](https://trinity.iota.org). Version **1.6.2** as of this writing
- Insert the seed with the tokens to be reclaimed
- Go to **Account** -> **Account Management** -> **View addresses**
- Now the list of addresses associated to the seed are visible
- Click on the visible addresses to copy it and search for the address on this page:
:warning: THE LIST CONTAINS ONLY ADDRESSES WITHOUT CHECKSUM. Should the address have 90 characters, make sure to remove the last 9 characters from the address that is being searched
https://gist.githubusercontent.com/cyclux/2bb05d873c4ec6115cad1d100263d489/raw/612a49e46091586957448f6606ea981ab18022e7/snapshot_validation_20171023.txt
- The text near the address has to say either **KEY_REUSE** or **CURL_NOT_TRANSITIONED**

- Continue verifying addresses until you have the whole list of addresses with frozen tokens

**At this point we have the information that confirms that it is a reclaim case.**
Please **write down** the **seed** and the **address(es)** and proceed to: [The receiving address with Firefly](#The-receiving-address-with-Firefly)

There are certain situations where the addresses where calculated differently, this Trinity option will not works. If your address is not in the table above please continue to the next option

### OPTION B: HBMY's iotaZeroBalanceHelper

:warning: THIS TOOL IS A COMMUNITY TOOL AND IS NOT ENDORSED BY THE IOTA Foundation.

_The following information has been taken from the original repository_
This program was written to help Iota users who unexpectedly see a zero balance in their Trinity wallet. There are multiple reasons why this could be happening and often it is not easy for non-experts to find out what is going on.

#### Disclaimer
NEVER share your seed with anyone. No community member or member of the Iota Foundation will ever ask for your seed. If someone does it is 100% a scam to steal your money. That said, even entering your seed into a software other than the official Iota wallet should not be handled lightly and can only be recommended as a last resort. For your own safety you should run this software only an an air-gapped computer.

#### What does it do?
The goal is that the program lets unexperienced users test what could possibly cause Trinity to not show the expected balance. I plan to add more tests over time.
The program allows to
1. check if funds on addresses of a seed were taken into custody by the Iota Foundation in late 2017. If this is the case the affected funds are reclaimable.
2. check if there is any balance that Trinity might not show. The program will list all addresses with balance while Trinity will often only show a single address if no funds are found.
3. export a list of generated addresses to be tested with the online tool [iotaAddressHistoryChecker](https://github.com/HBMY289/iotaAddressHistoryChecker)

Seeds that are too short or too long will be adadpted in the same way the Iota Light Wallet did.

##### Reclaim
With the given seed the programm calculates a large number of addresses both using the current address generation algorith and the one that was used in 2017 and earlier. These addresses are then matched against a list of reclaimable addresses. Possible matches and reclaimable balance will be shown. If no match is found using the Iota reclaim process will NOT bring back your balance.

##### Balance
If a reclaim case could be ruled out, the balance option will generate addresses using the current algorithm and compare them to an internally stored snapshot of the tangle. This snapshot holds all addresses with balances and by matching against this list the program does not need any connection to the internet or the current tangle to check balances. Currently a snapshot file from Feb 12th, 2021 is included. If you are missing a funds that have been moved after this date you can supply a more recent snapshot file. Ask someone who has access to a Iota node to run the following command and supply you with the resulting file.

curl -H 'X-IOTA-API-VERSION: 1' -d '{"command":"getLedgerState"}' localhost:14265 >  snapshot.txt

Place the file `snapshot.txt` next to this tool's executable. It will be automatically be used when checking the balances.

##### Export Addresses to check online
This program requires to enter your seed and is designed to run without any internet connection. If all your addresses still do not show any balance you can check the addresses on the Iota tangle explorer [https://explorer.iota.org/legacy-mainnet](https://explorer.iota.org/legacy-mainnet) for any transactions that show where your funds went. To avoid having to enter all addresses manually I wrote another tool that automates this process ([iotaAddressHistoryChecker](https://github.com/HBMY289/iotaAddressHistoryChecker)). It will require a list of addresses exported by the iotaZeroBalanceHelper and then request all available tranascations from the explorer. It will report any token movements in a short and human readable report.

**Finally HBMY's iotaZeroBalanceHelper is available here**: https://github.com/HBMY289/iotaZeroBalanceHelper/releases

#### How to use HBMY’s iotaZeroBalanceHelper

- Start the tool, if you accept the connected risks press **y** and **Enter** on your keyboard
- Type or copy/paste your **original** seed with the frozen tokens from the reclaim and press **Enter**. Be aware that a typo (wrong character) in your seed will not have access to your tokens on the Tangle
- The tool will recognize if the seed has less than 81 character (which is possible for some older seeds). Press **y** and **Enter** on your keyboard to continue
- To check for a possible **reclaim** press the number **2** and **Enter** on your keyboard to continue
- Press the number **2** and **Enter** on your keyboard to continue the verification. The tool will start searching the addresses and matching them with the list of known reclaim addresses
- There are two cases now
- A) It is a reclaim case
- At this point we have the information that confirms that it is a reclaim case.
Please **write down** the **seed** and the **address(es)** and proceed to: [The receiving address with Firefly](#The-receiving-address-with-Firefly)
- B) It is NOT a reclaim case. This means that your seed is not involved in the reclaim chase, or that the inserted seed is wrong. If you are 100% sure that it is a reclaim case try to verify if there is a *typo* in your seed using [OPTION C: FVANtom's IOTA seed typo finder](#OPTION-C-FVANtom%E2%80%99s-IOTA-seed-typo-finder) from this same guide.
**IMPORTANT** Without the correct original seed it will not be possible to prove ownership of the tokens and complete the reclaim procedure

### OPTION C: FVANtom's IOTA seed typo finder
:warning: THIS TOOL IS A COMMUNITY TOOL AND IS NOT ENDORSED BY THE IOTA Foundation.

_The following information has been taken from the original repository_
##### WARNING

NEVER give your seed to anyone, not even to someone you think you can trust. Not even the devs. There's scammers out there. NEVER enter your seed into or download any software that is closed source and/or that hasn't been reviewed and approved by either the IOTA foundation or at least the IOTA community.

#### What does this tool do

I have written this tool to help a user on Reddit who accidentally made a typo in his seed while logging in into the wallet.

He then transfered iota to the address he generated and logged out of his wallet.

Because he accidentally made a typo when logging in, he lost access to his funds.

This program checks the most common typing mistakes and tries to find the real seed (typo-seed) of the address the funds were transferred to.

* Generating seeds with one missing character readded
* Generating seeds with one character missing
* Generating seeds with character typed double
* Generating seeds with letters that look like each other replaced
* Generating seeds with block of 2 character retyped
* Generating seeds with 2 neighbouring characters switched
* Generating seeds with 1 character mistyped

#### Who is this program useful for

Anyone who transferred funds to an IOTA address of a seed similar to his own but with a typo and doesn't know the 'typo-seed'.

#### To use this program you will need:

* Your original seed
* The address your funds were transfered (belonging to the 'typo-seed')

**Finally FVANtom's IOTA seed typo finder is available here**: https://github.com/FVANtom/find-typo-in-iota-seed/releases

Now start again either with **OPTION A** or **OPTION B** to make sure it is a reclaim case

## The receiving address with Firefly

- Download and set up the latest version of the [Firefly wallet](https://firefly.iota.org). Version **1.1.0** as of this writing
- Create a new wallet
- Walk through the *Secure you wallet procedure*
- Make sure to back up the 24 words recovery mnemonic and the Stronghold password. The **24 words mnemonic** are the **new seed** and these will always give you access to the tokens on the Tangle. **Make sure to secure them accordingly**. Here our [blog post](https://blog.iota.org/security-during-token-migration/) with security tips.
- After the initial Firefly set up click on **Receive** to generate a receiving address
- Click on **Copy Address** to copy that address (*Note*: the new addresses now start with `iota`)
- Copy this address to be used during the *Chrysalis reclaim process*

## Chrysalis reclaim tool MacOS

The reclaim tool is a terminal/command line tool and it needs a little preparation to get it started on MacOS

- Download the *Reclaim Simplified* tool `iota-reclaim-simplify.mac` from here:
https://github.com/iotaledger/reclaim-simplified/releases/tag/v0.0.4
- Open the Terminal ([This guide explains how to open the Terminal app](https://www.howtogeek.com/682770/how-to-open-the-terminal-on-a-mac/))
- Use the `cd` command to get to the `Download` or `Desktop` folder. In this example the chrysalis reclaim tool was downloaded to the `Desktop`
- Now make the tool *executable* so that it can be run with `chmod +x iota-reclaim-simplified.mac`
- Now run the tool for the first time `./iota-reclaim-simplified.mac` (**NOTE** It will fail and give an error)
- This is the error message. Click on **Cancel**
- At this point go to the **System Preferences** here go to **Security And Privacy**. Verify that `iota-reclaim-simplify.mac` was blocked and click on **Allow Anyway**
- 
- Now back to the Terminal and run the command again, this time a new pop-up will appear
- Now click on **Open** to run the *reclaim tool* and start following the instructions on the next section [The Chrysalis reclaim process](#The-Chrysalis-reclaim-process)

## The Chrysalis reclaim process

Now that we have
* The **ORIGINAL SEED** with the frozen funds (`81 characters from A-Z and number 9`)
* **ALL ADDRESSES WITH CHECKSUM** with the frozen funds (If you have more addresses with frozen funds it will be necessary to repeat the reclaim process for every address; with checksum means 90 characters in total)
* A **NEW ADDRESS** generated with Firefly (starting with `iota`)

it is possible to start the reclaim process.

Download the *Reclaim Simplified* tool from here:

https://github.com/iotaledger/reclaim-simplified/releases/tag/v0.0.4

*NOTES*:
- GNU/Linux users make sure to make the file executable `chmod +x iota-reclaim-simplified.linux`
- MacOS users please follow this guide first: [Chrysalis reclaim tool MacOS](#Chrysalis-reclaim-tool-MacOS) if you have not done so already

Open the command line or terminal, run the tool and follow the on-screen instructions.

- Type or paste the **Address with the frozen funds** including the checksum (90 characters)
- Press **Enter** on the keyboard
- Now type or paste the **New receiving address** generated with Firefly
- Press **Enter** on the keyboard
- Now type or paste the **original seed** that controls the frozen funds. **NOTE:** Should be the seed shorter than 81 characters, add the number 9 until it reaches 81 characters
- Press **Enter** on the keyboard
- This will be the output
- Make sure to scroll **UP** and copy all the text starting from
`=================================CUT HERE=====================================`
- This is how the complete text looks like
- Now either send this content to Antonio Nardella in a private message on the [IOTA Discord](https://discord.iota.org) or via e-mail to [e-mail]
- Repeat these steps for every frozen address

This information will be collected and the reclaims verified.
**IMPORTANT NOTICE** As of this [blog post](https://https://blog.iota.org/iota-community-treasury-and-genesis-validation/) all the reclaims submissions will **close** on June 16th 2021 at 23:59 UTC.

# Troubleshooting

## Error ERROR: The entered Claimed address is invalid: [...] at index 0 (not length of 90 trytes): invalid hash

### Reclaim tool with error

### The inserted Address is missing the checksum.
- To find the address + checksum go to the [IOTA Explorer](https://explorer.iota.org/legacy-mainnet) and Search for you address there
- The Explorer will show the Address and the checksum
- Copy the address from here and use it in the reclaim tool