Skip to content

Commit 88b970e

Browse files
tomimordutterbutteryuliyaalexiev
authored
docs: add account recovery with guardian section (#347)
<!-- Thank you for contributing to the ZKsync Docs! Before submitting the PR, please make sure you do the following: - Update your PR title to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) - Read the [Contributing Guide](https://github.com/matter-labs/zksync-docs/blob/main/CONTRIBUTING.md). - Understand our [Code of Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md) - Please delete any unused parts of the template when submitting your PR --> # Description This PR adds documentation and diagrams for the upcoming “Account Recovery with Guardians” feature in SSO accounts. More info: - [GuardianRecoveryValidator]( https://github.com/matter-labs/zksync-sso-clave-contracts/blob/audit-guardian-recovery/src/validators/GuardianRecoveryValidator.sol) - [IGuardianRecoveryValidator](https://github.com/matter-labs/zksync-sso-clave-contracts/blob/audit-guardian-recovery/src/interfaces/IGuardianRecoveryValidator.sol) Co-authored-by: Dustin Brickwood <[email protected]> Co-authored-by: yuliyaalexiev <[email protected]>
1 parent 0173a92 commit 88b970e

File tree

4 files changed

+130
-19
lines changed

4 files changed

+130
-19
lines changed

‎content/00.zksync-era/30.unique-features/30.zksync-sso/28.account-recovery.md‎

Lines changed: 121 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,127 @@ In case you lose your passkeys, ZKsync SSO will provide several methods to recov
1010
Users can synchronize their passkeys across multiple devices using services like iCloud Keychain for Apple devices or similar services on other platforms.
1111
This means if one device is lost, the passkeys are still accessible on other synchronized devices.
1212

13-
## Other Options
13+
## Account Recovery with Guardians
14+
15+
Recovering an account with a Guardian is a **safety feature** designed to help users regain access to their SSO accounts if their primary
16+
authentication method (such as a passkey) is lost.
17+
18+
Users can **initiate the recovery process to update their passkey authentication,** with the Guardian serving as both verifier and facilitator.
19+
20+
### Guardian
21+
22+
A Guardian is a **trusted entity** designated to assist in **recovering access to a smart account**.
23+
It achieves this by signing to verify the legitimacy of the recovery process.
24+
25+
→ In other words, another account that acts as a *guardian* of the SSO account, protecting the owner from losing access to it due to the loss of the
26+
primary authentication method.
27+
28+
**Key characteristics include:**
29+
30+
- Can be another smart account with any valid blockchain address.
31+
- Must be explicitly proposed by the SSO account owner.
32+
- Must actively accept the Guardian role.
33+
- Can verify recovery attempts but cannot directly control the account.
34+
- Allows multiple guardians to be assigned to an account.
35+
36+
### Main flows high-level description
37+
38+
#### Adding & Verifying a Guardian
39+
40+
This diagram illustrates the process of adding a new guardian to a user's SSO account.
41+
42+
The flow begins when a user decides to add a guardian and involves communication between the User, Auth Server, and SSO Account to generate and
43+
process a unique invitation that the designated guardian must accept.
44+
45+
![Guardian Setup](/images/zksync-sso/account-recovery/guardiansetup.svg)
46+
47+
#### Recovering an account
48+
49+
This diagram illustrates the step-by-step process of recovering an SSO account when a user has lost access to their primary authentication method.
50+
51+
The flow shows the interactions between the User, Auth Server, and Guardian during the recovery process, including the initial recovery request,
52+
passkey update, guardian verification, and completion of the recovery.
53+
54+
![Guardian Recovery](/images/zksync-sso/account-recovery/guardianrecovery.svg)
55+
56+
#### Stop malicious account recovery
57+
58+
This diagram illustrates how SSO account owners **can detect and stop unauthorized recovery attempts initiated** by a malicious guardian. The flow
59+
shows how users are alerted of pending recoveries during normal SSO login and can cancel suspicious recovery attempts before they are completed.
60+
61+
![Malicious Guardian](/images/zksync-sso/account-recovery/maliciousguardian.svg)
62+
63+
### Module Implementation
64+
65+
The solution centers on a [new erc7579 validator module](https://erc7579.com/modules) called `GuardianRecoveryValidator`. This guide illustrates
66+
how to perform different guardian recovery actions with this module:
67+
68+
#### Adding & verifying a Guardian
69+
70+
To link a guardian to a smart account, the account owner must first **propose the guardian**, after which the guardian must **verify and accept**
71+
their role. This ensures **mutual consent** and secure onboarding.
72+
73+
##### **Proposing a Guardian**
74+
75+
The `proposeGuardian` method handles the initial registration of external accounts by:
76+
77+
1. Taking an external account address and storing it as a **pending guardian**.
78+
2. Enabling `addGuardian` to **confirm and activate** this guardian.
79+
3. Emits: `GuardianProposed`.
80+
81+
##### **Verifying a Guardian**
82+
83+
The `addGuardian` method handles the registration of external accounts by:
84+
85+
1. Verifying that the guardian was **previously proposed** by the account.
86+
2. Marking the guardian as **active and ready**.
87+
3. Recording the guardian-to-account relationship for **future recovery and validation**.
88+
4. Emits: `GuardianAdded`.
89+
90+
#### **Removing a Guardian**
91+
92+
The `removeGuardian` method handles guardian removal by:
93+
94+
1. Accepting the guardian's address as input.
95+
2. Removing the guardian from the account's list.
96+
3. Cleaning up associated metadata (e.g., removing the account from the guardian's guarded list).
97+
4. Emitting a **`GuardianRemoved`** event to log the change.
98+
99+
#### **Recovery Process**
100+
101+
The following section detail the technical implementation of initiating, completing, and canceling the recovery process.
102+
103+
##### **Initiating Recovery**
104+
105+
A verified guardian can **initiate account recovery** using the `initRecovery` method, which:
106+
107+
1. Verifies the caller is an **active guardian** of the account.
108+
2. Verifies that account does not have non-expired pending recovery
109+
3. Records a recovery request with:
110+
- **Hashed credential ID**
111+
- **Raw public key**
112+
- **Timestamp**
113+
4. Emits a **`RecoveryInitiated`** event for auditability.
114+
5. The contract enforces:
115+
1. **Timelock**: Recovery must be **delayed by 24 hours** before it can be executed.
116+
2. **Expiration**: Recovery must be completed within **72 hours**, else it **expires**.
117+
118+
##### **Completing Recovery**
119+
120+
Account recovery is completed by submitting a specific transaction validated via `validateTransaction`, which:
121+
122+
1. Ensures the transaction calls `WebAuthValidator.addValidationKey`.
123+
2. Confirm the **credential ID and public key** match the recovery request.
124+
3. Verifies that **24 hours have passed** since initiation and the request is within the **72-hour validity window**.
125+
4. Mark recovery as complete by calling `finishRecovery`
126+
5. Emits: **`RecoveryFinished`**
127+
128+
##### **Cancelling Recovery**
129+
130+
A pending recovery can be discarded using `discardRecovery`, which:
131+
132+
1. Removes the recovery request from storage.
133+
2. Emits a **`RecoveryDiscarded`** event for traceability.
14134

15135
*More account recovery options are coming soon.*
16136

@@ -36,22 +156,4 @@ If passkeys are lost, they can recover access by authenticating with their EOA,
36156
OAuth Recovery ERC-7579 module enables users to set up an account recovery through OAuth tokens associated with their existing Web2 logins like
37157
Gmail, Facebook, or X (formerly Twitter). This allows users to regain access by logging in with their familiar social media or email accounts.
38158
39-
-->
40-
41-
<!--
42-
43-
### Adding Another Passkey (*coming soon*)
44-
45-
You will be able to register a new device by adding a new passkey to your account. This typically involves verifying your identity on the new device,
46-
after which the new passkey is securely associated with your account.
47-
48-
### Recovery via Externally Owned Account (EOA) (*coming soon*)
49-
50-
You will soon be able to link an Externally Owned Account (EOA) to your ZKsync SSO account. If passkeys are lost,
51-
you can recover access by authenticating with your EOA, providing an additional layer of security and recovery options.
52-
53-
### Recovery via OAuth (*coming soon*)
54-
55-
The OAuth Recovery ERC-7579 module enables you to set up account recovery through OAuth tokens associated with your existing Web2 logins like
56-
Gmail, Facebook, or X (formerly Twitter). This allows you to regain access by logging in with your familiar social media or email accounts.
57159
-->

0 commit comments

Comments
 (0)