Crate pallet_recovery 

Recovery Pallet

Pallet Recovery allows you to have friends or family recover access to your account if you lose your seed phrase or private key.

Terminology

• lost: An account that has lost access to its private key and needs to be recovered.
• friend: A befriended account that can approve a recovery process.
• initiator: An account that initiated a recovery attempt.
• recovered: An account that has been successfully recovered.
• inheritor: An account that is inheriting access to a lost account after recovery.
• attempt: An attempt to recover a lost account by an initiator.
• priority: The priority of a friend group in inheritance conflicts. See InheritancePriority.
• deposit: An amount of currency that needs to be held for allocating on-chain storage.
• friends_needed: The number of friends that need to approve an attempt.
• inheritance delay: How long an attempt will be delayed before it can succeed.
• provided block: The blocks that are provided by the T::BlockNumberProvider.

Scenario: Recovering a lost account

Story of how the user Alice loses access and is recovered by her friends.

1. Alice uses the recovery pallet to configure one or more friends groups:

• Alice picks a suitable inheritor account that will inherit the access to her account for each friend group. This could be a multisig.
• Alice configures all groups via set_friend_groups.

2. Alice loses access to her account and becomes a lost account.
3. Any member (aka initiator) of Alice’s friend groups become aware of the situation and starts a recovery attempt via initiate_attempt.
4. The friend group self-organizes and one-by-one approve the ongoing attempt via approve_attempt.
5. Exactly friends_needed friends approve the attempt (further approvals will fail since they are useless).
6. Any account finishes the attempt via finish_attempt after at least inheritance delay blocks since the initiation have passed.
7. Alice’s account is now officially recovered and accessible by the inheritor account.
8. The inheritor may call control_inherited_account at any point to transfer Alice’s funds to her new account.

Scenario: Multiple friend groups try to recover an account

Alice may have configured multiple friend groups that all try to recover her account at the same time. This can lead to a conflict of which friend group should eventually inherit the access.

1. Alice configures groups Family (delay 10d, priority 0) and Friends (delay 20d, priority 1). Since numerical lower values denote higher priority, Family therefore has higher priority than Friends.
2. Day 0: Alice loses access to her account.
3. Day 6: Friends initiate a recovery attempt for Alice.
4. Day 15: Family finally understands Polkadot and initiates an attempt as well.
5. Day 25: Family inherits access to Alice account.
6. Day 26: Friends group gets nothing since they have lower priority than Family.

In the case above you see how the Friends group is now unable to recover Alice account since the Family group already did it and has higher priority. Now, imagine the case that the Friends group would have started on day 4 and would have already recovered the account on day 24. Two days later, the Family group can take access back and will replace the inheritor account with their own. The Friends group had access for two days since they were faster. If Alice account has most balance locked in 28 day staking this would not make a big difference, since only the free balance would be immediately transferable.

After a recovery attempt was completed, lower-priority friend groups cannot open a new attempt to recover the account.

Data Structures

The pallet has three storage items, see the in-code docs FriendGroups, Attempt and Inheritor. Storage items may contain deposit “tickets” or similar noise and should therefore not be read directly but only through the API.

API

Reading data can be done through the view functions:

• provided_block_number: The block number that will be used to measure time.
• friend_groups: The friend groups of an account that can initiate recovery attempts.
• attempts: Ongoing recovery attempts for a lost account.
• inheritor: The account that inherited full access to the lost account.
• inheritance: All the recovered accounts that an account inherited access to.

Re-exports

pub use weights::WeightInfo;

pub use pallet::*;

Modules

migrations

Multi-block migrations for the recovery pallet.

pallet

The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

types

Generic types that can be moved to frame-support once stable.

weights

Autogenerated weights for pallet_recovery

Structs

Attempt

An attempt to recover an account.

FriendGroup

Group of friends that can initiate a recovery attempt for a specific lost account.

Constants

MAX_GROUPS_PER_ACCOUNT

Maximum number of friend groups that an account can have.

Type Aliases

AccountIdLookupOf

ApprovalBitfield

Approval bitfield for a specific number of friends.

ApprovalBitfieldOf

Bitfield to track approval per friend in a friend group.

AttemptOf

Attempt to recover an account.

AttemptTicketOf

Ticket for an attempt to recover an account.

BalanceOf

CreditOf

FriendGroupIndex

Index of a friend group of a lost account.

FriendGroupOf

A FriendGroup for a specific Config.

FriendGroupsOf

Collection of friend groups of a lost account.

FriendsOf

Friends of a friend group.

HashOf

InheritancePriority

Priority of a friend group in account inheritance conflicts.

InheritorTicketOf

Ticket for the inheritor of an account.

ProvidedBlockNumberOf

The block number type that will be used to measure time.

SecurityDepositOf

Amount of a security deposit - as opposed to a storage deposit.