Skip to main content

LSP11BasicSocialRecovery

Standard Specifications

LSP-11-BasicSocialRecovery

Solidity implementation

LSP11BasicSocialRecovery.sol

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-

OwnableCallerNotTheOwner​

References
error OwnableCallerNotTheOwner(address callerAddress);

Reverts when only the owner is allowed to call the function.

Parameters​

NameTypeDescription
callerAddressaddressThe address that tried to make the call.

OwnableCannotSetZeroAddressAsOwner​

References
error OwnableCannotSetZeroAddressAsOwner();

Reverts when trying to set address(0) as the contract owner when deploying the contract, initializing it or transferring ownership of the contract.


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