Skip to main content

LSP11BasicSocialRecovery

LSP11BasicSocialRecovery

Standard Specifications
Solidity implementation

Implementation of LSP11 - Basic Social Recovery standard

Sets permission for a controller address after a recovery process to interact with an ERC725 contract via the LSP6KeyManager

Public Methods

Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally.

constructor

References
constructor(address _owner, address target_);

Sets the target and the owner addresses

Parameters

NameTypeDescription
_owneraddressThe owner of the LSP11 contract
target_addressThe address of the ER725 contract to recover

addGuardian

References
function addGuardian(address newGuardian) external nonpayable;

Adds a guardian of the targetCan be called only by the owner

Parameters

NameTypeDescription
newGuardianaddressThe address to add as a guardian

getGuardianChoice

References
function getGuardianChoice(address guardian) external view returns (address);

Returns the address of a controller that a guardian selected for in order to recover the target

Parameters

NameTypeDescription
guardianaddressthe address of a guardian to query his selection

Returns

NameTypeDescription
0addressthe address that guardian selected

getGuardians

References
function getGuardians() external view returns (address[]);

Returns the addresses of all guardians The guardians will select an address to be added as a controller key for the linked target if he reaches the guardian threshold and provide the correct string that produce the secretHash

Returns

NameTypeDescription
0address[]-

getGuardiansThreshold

References
function getGuardiansThreshold() external view returns (uint256);

Returns the guardian threshold The guardian threshold represents the minimum number of selection by guardians required for an address to start a recovery process

Returns

NameTypeDescription
0uint256-

getRecoveryCounter

References
function getRecoveryCounter() external view returns (uint256);

Returns the current recovery counter When a recovery process is successfully finished the recovery counter is incremented

Returns

NameTypeDescription
0uint256-

getRecoverySecretHash

References
function getRecoverySecretHash() external view returns (bytes32);

Returns the recovery secret hash

Returns

NameTypeDescription
0bytes32-

isGuardian

References
function isGuardian(address _address) external view returns (bool);

Returns TRUE if the address provided is a guardian, FALSE otherwise

Parameters

NameTypeDescription
_addressaddressThe address to query

Returns

NameTypeDescription
0bool-

owner

References
function owner() external view returns (address);

Returns the address of the current owner.

Returns

NameTypeDescription
0address-

recoverOwnership

References
function recoverOwnership(
address recoverer,
string plainSecret,
bytes32 newSecretHash
) external nonpayable;

Recovers the ownership permissions of an address in the linked target and increment the recover counter Requirements

  • the address of the recoverer must have a selection equal or higher than the threshold defined in getGuardiansThreshold(...)

  • must have provided the right plainSecret that produces the secret Hash

Parameters

NameTypeDescription
recovereraddressThe address of the recoverer
plainSecretstringThe secret word that produce the secret Hash
newSecretHashbytes32-

removeGuardian

References
function removeGuardian(address existingGuardian) external nonpayable;

Removes a guardian of the targetCan be called only by the owner

Parameters

NameTypeDescription
existingGuardianaddress-

renounceOwnership

References
function renounceOwnership() external nonpayable;

Leaves the contract without owner. It will not be possible to call onlyOwner functions anymore. Can only be called by the current owner. NOTE: Renouncing ownership will leave the contract without an owner, thereby removing any functionality that is only available to the owner.


selectNewController

References
function selectNewController(address addressSelected) external nonpayable;

select an address to be a potentiel controller address if he reaches the guardian threshold and provide the correct secret string Requirements:

  • only guardians can select an address

Parameters

NameTypeDescription
addressSelectedaddressThe address selected by the guardian

setGuardiansThreshold

References
function setGuardiansThreshold(uint256 newThreshold) external nonpayable;

Sets the minimum number of selection by the guardians required so that an address can recover ownershipCan be called only by the owner

Parameters

NameTypeDescription
newThresholduint256-

setRecoverySecretHash

References
function setRecoverySecretHash(
bytes32 newRecoverSecretHash
) external nonpayable;

Throws if hash provided is bytes32(0)

Parameters

NameTypeDescription
newRecoverSecretHashbytes32The hash of the secret string Requirements: - secretHash cannot be bytes32(0)

supportsInterface

References
function supportsInterface(bytes4 _interfaceId) external view returns (bool);

See IERC165-supportsInterface.

Parameters

NameTypeDescription
_interfaceIdbytes4-

Returns

NameTypeDescription
0bool-

target

References
function target() external view returns (address);

The address of an ERC725 contract where we want to recover and set permissions for a controller address

Returns

NameTypeDescription
0address-

transferOwnership

References
function transferOwnership(address newOwner) external nonpayable;

Transfers ownership of the contract to a new account (newOwner). Can only be called by the current owner.

Parameters

NameTypeDescription
newOwneraddress-

Internal Methods

Any method labeled as internal serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs.

Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities.

_checkOwner

function _checkOwner() internal view;

Throws if the sender is not the owner.


_setOwner

function _setOwner(address newOwner) internal nonpayable;

Changes the owner if newOwner and oldOwner are different This pattern is useful in inheritance.


_validateRequirements

function _validateRequirements(
address recoverer,
uint256 currentRecoveryCounter,
string plainSecret,
bytes32 newHash,
address[] guardians
) internal view;

The number of guardians should be reasonable, as the validation method is using a loop to check the selection of each guardian Throws if:

  • The address trying to recover didn't reach the guardiansThreshold

  • The new hash being set is bytes32(0)

  • The secret word provided is incorrect


_cleanStorage

function _cleanStorage(
uint256 recoveryCounter,
uint256 guardiansLength,
address[] guardians
) internal nonpayable;

Remove the guardians choice after a successfull recovery process To avoid keeping unnecessary state


Events

GuardianAdded

References
event GuardianAdded(address indexed newGuardian);

Emitted when setting a new guardian for the target

Parameters

NameTypeDescription
newGuardian indexedaddressThe address of the added guardian

GuardianRemoved

References
event GuardianRemoved(address indexed removedGuardian);

Emitted when removing an existing guardian for the target

Parameters

NameTypeDescription
removedGuardian indexedaddressThe address of the guardian removed

GuardiansThresholdChanged

References
event GuardiansThresholdChanged(uint256 indexed guardianThreshold);

Emitted when changing the guardian threshold

Parameters

NameTypeDescription
guardianThreshold indexeduint256The minimum number of selection by guardians needed by a controller to start a recovery process

OwnershipTransferred

References
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);

Parameters

NameTypeDescription
previousOwner indexedaddress-
newOwner indexedaddress-

RecoveryProcessSuccessful

References
event RecoveryProcessSuccessful(uint256 indexed recoveryCounter, address indexed newController, bytes32 indexed newSecretHash, address[] guardians);

Emitted when the recovery process is finished by the controller who reached the guardian threshold and submitted the string that produce the secretHash

Parameters

NameTypeDescription
recoveryCounter indexeduint256The current recovery process
newController indexedaddressThe address of the new controller controlling the target by the KeyManager
newSecretHash indexedbytes32-
guardiansaddress[]The array of addresses containing the guardians of the target

SecretHashChanged

References
event SecretHashChanged(bytes32 indexed secretHash);

Emitted when changing the secret hash

Parameters

NameTypeDescription
secretHash indexedbytes32The secret hash used to finish the recovery process

SelectedNewController

References
event SelectedNewController(uint256 indexed recoveryCounter, address indexed guardian, address indexed addressSelected);

Emitted when a guardian select a new potentiel controller address for the target

Parameters

NameTypeDescription
recoveryCounter indexeduint256The current recovery process counter
guardian indexedaddressThe address of the guardian
addressSelected indexedaddressThe address selected by the guardian

Errors

AddressZeroNotAllowed

References
error AddressZeroNotAllowed();

reverts when the address zero calls recoverOwnership(..) function


CallerIsNotGuardian

References
error CallerIsNotGuardian(address caller);

reverts when the caller is not a guardian

Parameters

NameTypeDescription
calleraddress-

GuardianAlreadyExist

References
error GuardianAlreadyExist(address addressToAdd);

reverts when adding an already existing guardian

Parameters

NameTypeDescription
addressToAddaddress-

GuardianDoNotExist

References
error GuardianDoNotExist(address addressToRemove);

reverts when removing a non-existing guardian

Parameters

NameTypeDescription
addressToRemoveaddress-

GuardiansNumberCannotGoBelowThreshold

References
error GuardiansNumberCannotGoBelowThreshold(uint256 guardianThreshold);

reverts when removing a guardian and the threshold is equal to the number of guardians

Parameters

NameTypeDescription
guardianThresholduint256-

SecretHashCannotBeZero

References
error SecretHashCannotBeZero();

reverts when the secret hash provided is equal to bytes32(0)


ThresholdCannotBeHigherThanGuardiansNumber

References
error ThresholdCannotBeHigherThanGuardiansNumber(
uint256 thresholdGiven,
uint256 guardianNumber
);

reverts when setting the guardians threshold to a number higher than the guardians number

Parameters

NameTypeDescription
thresholdGivenuint256-
guardianNumberuint256-

ThresholdNotReachedForRecoverer

References
error ThresholdNotReachedForRecoverer(
address recoverer,
uint256 selections,
uint256 guardiansThreshold
);

reverts when recoverOwnership(..) is called with a recoverer that didn't reach the guardians threshold

Parameters

NameTypeDescription
recovereraddressThe address of the recoverer
selectionsuint256The number of selections that the recoverer have
guardiansThresholduint256The minimum number of selection needed

WrongPlainSecret

References
error WrongPlainSecret();

reverts when the plain secret produce a different hash than the secret hash originally set