Documentation for the token recovery mechanism implemented in ERC20Recoverable.sol.
It is desirable that share tokens (which legally represent the company’s equity) do not get “lost” if a shareholder loses the private key to their account or accidentally sends them to an invalid address. While some issuers address this by adding a back-door to their smart contract, giving them full control over all tokens, we prefer following a decentralized approach. This is also what the Swiss Blockchain Federation recommends in their Security Token Circular. Our decentralized approach allows holders to reclaim their shares without having to rely on a centralized authority.
The recovery process works as follows: Let us assume that Alice has lost the key to her address A. She picks a new address B and makes all calls from the new address.
If the key is found again, or the claim was made maliciously, the rightful owner can always call clearClaim from the claimed address to delete the claim and seize the collateral. This makes attacks economically infeasible. When an attacker makes a claim for your address to obtain all your 7 shares in Example Inc., the attacker must also provide a collateral worth 7 shares. Now you have six months time to call clearClaim, thereby not only deleting the fraudulent claim, but also taking away the attacker’s collateral. If your wallet does not support calling custom methods such as clearClaim, you can also just transfer one share to a new address, which triggers an implicit call to clearClaim and has the same effect.
Claims can also be deleted by a special role (in this case the collateral is returned). There is a function getClaimDeleter() that defines who can do this (typically the issuer). The purpose of this is to protect shareholders in cases where they cannot act on their own for some reason. Also, this guards against malicious use of the claim mechanisms in cases where the attacker got to know that the claimed address got lost and acts before the rightful owner does.
As a collateral, the share tokens themselves can be used. E.g. if you lost your key, get a friend to stake their shares for you. A custom collateral (ERC‑20 token) can be set by the issuer. Using a stablecoin like XCHF has the advantage that during the waiting period the amount staked is not subject to the volatility of Ether. Ether is not supported as collateral, but the issuer could decide to accept wrapped ether.
In transaction 0x2802...61, someone we are familiar with accidentally sent 1′145 shares of ServiceHunter AG (SHS) to address 0x0479. That address is the hexadecimal representation of the number 1145 and an address that no one controls. To recover the shares, the owner invoked declareLost in transaction 0x2459...31 with an additional 1145 shares as collateral. (Note that the SHS contract is based on the old version of our claimable mechanism which required an additional nonce parameter and a preclaim not described here.) After waiting for half a year, transaction 0x7429...38 was issued to resolve the claim, returning both the lost shares as well as the collateral to their owner. Note that in this example, the recovery function was implemented by token contract itself. In the meantime, this functionality has been moved to the recovery hub.
