Skip to content

Commit 23d0b0e

Browse files
cpb8010cpb8010
committed
feat: connect guardian
needs testing
1 parent e7ef5e8 commit 23d0b0e

File tree

13 files changed

+381
-41
lines changed

13 files changed

+381
-41
lines changed

‎packages/auth-server/GUARDIAN_TESTING.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# Guardian Recovery - Manual Testing Guide
2+
3+
This guide walks through manually testing the guardian recovery feature in the
4+
ZKsync SSO auth-server.
5+
6+
## Prerequisites
7+
8+
1. **Local blockchain running**:
9+
10+
```bash
11+
# Start Anvil (in one terminal)
12+
cd packages/erc4337-contracts
13+
pnpm anvil
14+
```
15+
16+
2. **Deploy contracts**:
17+
18+
```bash
19+
# Deploy contracts (in another terminal)
20+
cd packages/erc4337-contracts
21+
forge script script/Deploy.s.sol --broadcast \
22+
--rpc-url http://localhost:8545 \
23+
--private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
24+
```
25+
26+
This will automatically update `packages/auth-server/stores/local-node.json`
27+
with the deployed addresses.
28+
29+
3. **Start bundler**:
30+
31+
```bash
32+
cd packages/erc4337-contracts
33+
pnpm bundler
34+
```
35+
36+
4. **Start auth-server**:
37+
38+
```bash
39+
pnpm nx dev auth-server
40+
```
41+
42+
## Test Scenarios
43+
44+
### Scenario 1: Basic Guardian Flow (SSO Account as Guardian)
45+
46+
This tests the most common case where a user wants another SSO account to be
47+
their guardian.
48+
49+
#### Step 1: Create Primary Account
50+
51+
1. Navigate to `http://localhost:3000`
52+
2. Click "Create Account" or "Sign Up"
53+
3. Create a passkey when prompted (use name like "Primary User")
54+
4. Complete account creation
55+
5. **Save the account address** from the dashboard (e.g., `0xABC...123`)
56+
57+
#### Step 2: Create Guardian Account
58+
59+
1. Open a new **incognito/private browser window**
60+
2. Navigate to `http://localhost:3000`
61+
3. Create a new passkey (use name like "Guardian User")
62+
4. Complete account creation
63+
5. **Save this guardian account address** (e.g., `0xDEF...456`)
64+
65+
#### Step 3: Propose Guardian
66+
67+
1. Go back to the **first browser window** (Primary User)
68+
2. Navigate to Dashboard → Settings
69+
3. Find the "Guardian Recovery" section
70+
4. Click "Add Guardian"
71+
5. Enter the guardian address from Step 2 (`0xDEF...456`)
72+
6. Click "Propose Guardian"
73+
7. Wait for transaction to confirm
74+
8. **Expected**: Guardian should appear in "Pending Guardians" list
75+
76+
#### Step 4: Confirm Guardian
77+
78+
1. Copy the confirmation link shown (or construct it):
79+
80+
```text
81+
http://localhost:3000/recovery/guardian/confirm-guardian?accountAddress=0xABC...123&guardianAddress=0xDEF...456
82+
```
83+
84+
2. Open this link in the **incognito window** (Guardian User)
85+
3. The page should detect it's an SSO account
86+
4. Click "Confirm Guardian"
87+
5. Wait for transaction to confirm
88+
6. **Expected**: "Guardian Confirmed" success message
89+
90+
#### Step 5: Verify Guardian is Active
91+
92+
1. Go back to **Primary User window**
93+
2. Refresh the Settings page
94+
3. **Expected**: Guardian should now appear in "Active Guardians" list with
95+
status "Ready"
96+
97+
---
98+
99+
### Scenario 2: External Wallet as Guardian
100+
101+
This tests using a connected external wallet (like MetaMask) as a guardian.
102+
103+
#### Step 1: Create Account to Guard
104+
105+
1. Navigate to `http://localhost:3000`
106+
2. Create an SSO account with passkey
107+
3. **Save the account address**
108+
109+
#### Step 2: Propose External Wallet as Guardian
110+
111+
1. In Settings → Guardian Recovery
112+
2. Click "Add Guardian"
113+
3. Enter an external wallet address (e.g., from MetaMask)
114+
4. Click "Propose Guardian"
115+
5. Wait for confirmation
116+
117+
#### Step 3: Confirm with External Wallet
118+
119+
1. Copy the confirmation link
120+
2. Open link in a new browser window
121+
3. Click "Connect Wallet" button
122+
4. Connect the wallet that matches the guardian address
123+
5. **Expected**: "Wallet Connected" status appears
124+
6. Click "Confirm Guardian"
125+
7. Sign the transaction with the wallet
126+
8. **Expected**: Guardian confirmed successfully
127+
128+
---
129+
130+
### Scenario 3: Guardian Status Checks
131+
132+
Test that the system correctly identifies guardian account types.
133+
134+
#### Check SSO Account
135+
136+
1. Create two SSO accounts (as in Scenario 1)
137+
2. Navigate to confirmation page with guardian's address
138+
3. **Expected**: Page should show "ZKsync SSO Account" badge
139+
4. **Expected**: "Confirm Guardian" button appears automatically
140+
141+
#### Check Non-SSO Account
142+
143+
1. Create one SSO account
144+
2. Use a regular Ethereum address as guardian
145+
3. Navigate to confirmation page
146+
4. **Expected**: Page shows "Standard Account"
147+
5. **Expected**: "Connect Wallet" button appears
148+
6. **Expected**: Must connect wallet before confirming
149+
150+
---
151+
152+
### Scenario 4: Remove Guardian
153+
154+
Test removing an active guardian.
155+
156+
#### Step 1: Set up Guardian
157+
158+
1. Follow Scenario 1 to add and confirm a guardian
159+
160+
#### Step 2: Remove Guardian
161+
162+
1. In Primary Account Settings
163+
2. Find the active guardian in the list
164+
3. Click "Remove Guardian" button
165+
4. Confirm the transaction
166+
5. **Expected**: Guardian removed from list
167+
6. **Expected**: Guardian no longer appears in guardian list
168+
169+
---
170+
171+
### Scenario 5: Multiple Guardians
172+
173+
Test managing multiple guardians for one account.
174+
175+
1. Create one primary SSO account
176+
2. Create two guardian SSO accounts (in separate incognito windows)
177+
3. Propose both as guardians from primary account
178+
4. Confirm both guardians (using their respective browser sessions)
179+
5. **Expected**: Both guardians appear as "Active" in Settings
180+
6. Remove one guardian
181+
7. **Expected**: One guardian remains active
182+
183+
---
184+
185+
## Testing Edge Cases
186+
187+
### Invalid Guardian Address
188+
189+
1. Try to propose an invalid address (not checksummed, wrong format)
190+
2. **Expected**: Validation error prevents submission
191+
192+
### Duplicate Guardian
193+
194+
1. Add and confirm a guardian
195+
2. Try to add the same guardian address again
196+
3. **Expected**: Should handle gracefully (check current behavior)
197+
198+
### Self as Guardian
199+
200+
1. Try to add your own account address as guardian
201+
2. **Expected**: Should be prevented or handled appropriately
202+
203+
### Confirming Already Confirmed Guardian
204+
205+
1. Confirm a guardian
206+
2. Try to access the confirmation link again
207+
3. **Expected**: Show "Guardian already confirmed" message
208+
209+
---
210+
211+
## Checking Contract State
212+
213+
You can verify the guardian state on-chain using cast:
214+
215+
```bash
216+
# Check if address is a guardian for an account
217+
cast call <GUARDIAN_EXECUTOR_ADDRESS> \
218+
"guardianStatusFor(address,address)" \
219+
<ACCOUNT_ADDRESS> <GUARDIAN_ADDRESS> \
220+
--rpc-url http://localhost:8545
221+
222+
# Get all guardians for an account
223+
cast call <GUARDIAN_EXECUTOR_ADDRESS> \
224+
"getGuardians(address)" \
225+
<ACCOUNT_ADDRESS> \
226+
--rpc-url http://localhost:8545
227+
```
228+
229+
---
230+
231+
## Troubleshooting
232+
233+
### Guardian Executor Address Not Set
234+
235+
- **Symptom**: Error "Recovery contract address not configured"
236+
- **Fix**: Ensure `local-node.json` has valid `guardianExecutor` and `recovery`
237+
addresses
238+
- **Check**: Both should point to the GuardianExecutor contract address
239+
240+
### Transactions Failing
241+
242+
- **Check**: Anvil is running and bundler is connected
243+
- **Check**: Account has sufficient ETH/balance
244+
- **Check**: Paymaster is configured (if using one)
245+
246+
### SSO Account Not Detected
247+
248+
- **Symptom**: External wallet required even for SSO accounts
249+
- **Check**: `useIsSsoAccount` composable is working
250+
- **Check**: Account was created with the current auth-server instance
251+
252+
### Cannot Connect to Confirmation Page
253+
254+
- **Symptom**: 404 on `/recovery/guardian/...` routes
255+
- **Fix**: Ensure `pages/recovery` folder exists (not `recovery.disabled`)
256+
- **Check**: Run `pnpm nx dev auth-server` to rebuild routes
257+
258+
---
259+
260+
## Expected User Flow Summary
261+
262+
```text
263+
Primary User Guardian User
264+
| |
265+
| 1. Propose Guardian |
266+
|------------------------------------->|
267+
| |
268+
| 2. Share confirmation link |
269+
|------------------------------------->|
270+
| |
271+
| 3. Open link
272+
| 4. Confirm Guardian
273+
| |
274+
|<-------------------------------------|
275+
| 5. Guardian now active |
276+
| |
277+
```
278+
279+
The key insight is that:
280+
281+
1. **Primary user** initiates by proposing the guardian
282+
2. **Guardian** must actively confirm (sign transaction) to accept the role
283+
3. Both actions require on-chain transactions
284+
4. Once confirmed, guardian can initiate recovery if primary user loses access
285+
286+
---
287+
288+
## Future Testing: Recovery Execution
289+
290+
> **Note**: Full recovery testing (initiating and executing recovery) requires
291+
> additional implementation. This guide covers the guardian management portion
292+
> only.
293+
294+
Recovery execution would involve:
295+
296+
1. Guardian initiates recovery for a lost account
297+
2. Wait for timelock period
298+
3. Execute recovery to change account ownership
299+
4. These flows are planned for future implementation

‎packages/auth-server/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,16 @@ pnpm --dir packages/contracts run deploy
1313
pnpm nx dev auth-server
1414
```
1515

16+
## Testing Guardian Recovery
17+
18+
See [GUARDIAN_TESTING.md](./GUARDIAN_TESTING.md) for a comprehensive manual
19+
testing guide for the guardian recovery feature, including:
20+
21+
- Setting up SSO accounts as guardians
22+
- Using external wallets as guardians
23+
- Managing multiple guardians
24+
- Edge cases and troubleshooting
25+
1626
## How to deploy to a new chain
1727

1828
If you are a ZKsync chain operator, there are a few more updates to make to

0 commit comments

Comments
 (0)