Skip to content

Commit e27d4cd

Browse files
ukstvukstv
committed
readme
1 parent f27fadd commit e27d4cd

File tree

2 files changed

+378
-8
lines changed

2 files changed

+378
-8
lines changed

‎script/RevokeRecallRole.README.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
# Recall Role Revocation Script
2+
3+
This directory contains Forge scripts for revoking roles on deployed Recall token contracts.
4+
5+
## Overview
6+
7+
The `RevokeRecallRole.s.sol` script provides three different contracts for role management:
8+
9+
1. **RevokeRoleScript** - Revoke a single role from one account
10+
2. **BatchRevokeScript** - Revoke multiple roles from one account
11+
3. **MultiAccountRevokeScript** - Revoke one role from multiple accounts
12+
13+
## Prerequisites
14+
15+
- Foundry installed and configured
16+
- Access to an account with `ADMIN_ROLE` on the Recall contract
17+
- The deployed Recall proxy contract address
18+
19+
## Available Roles
20+
21+
The Recall contract has three roles:
22+
- `ADMIN` - Can authorize upgrades, unpause, and manage other roles
23+
- `MINTER` - Can mint new tokens
24+
- `PAUSER` - Can pause the contract
25+
26+
## Usage
27+
28+
### 1. Single Role Revocation
29+
30+
Revoke one role from one account.
31+
32+
#### With Private Key
33+
34+
```bash
35+
PROXY_ADDR=0x1234... \
36+
ROLE_TYPE=MINTER \
37+
ACCOUNT=0x5678... \
38+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
39+
--rpc-url https://your-rpc-url \
40+
--broadcast \
41+
--private-key $PRIVATE_KEY
42+
```
43+
44+
#### With Ledger Hardware Wallet
45+
46+
```bash
47+
PROXY_ADDR=0x1234... \
48+
ROLE_TYPE=MINTER \
49+
ACCOUNT=0x5678... \
50+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
51+
--rpc-url https://your-rpc-url \
52+
--broadcast \
53+
--ledger \
54+
--sender 0xYourLedgerAddress
55+
```
56+
57+
**Ledger Setup:**
58+
1. Connect your Ledger device via USB
59+
2. Unlock the device with your PIN
60+
3. Open the Ethereum app on your Ledger
61+
4. Run the command above
62+
5. Review and confirm the transaction on your Ledger device
63+
64+
#### With Trezor Hardware Wallet
65+
66+
```bash
67+
PROXY_ADDR=0x1234... \
68+
ROLE_TYPE=MINTER \
69+
ACCOUNT=0x5678... \
70+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
71+
--rpc-url https://your-rpc-url \
72+
--broadcast \
73+
--trezor \
74+
--sender 0xYourTrezorAddress
75+
```
76+
77+
#### Using Function Parameters (Alternative)
78+
79+
Instead of environment variables, you can pass parameters directly:
80+
81+
```bash
82+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
83+
--rpc-url https://your-rpc-url \
84+
--broadcast \
85+
--ledger \
86+
--sender 0xYourLedgerAddress \
87+
-s "run(address,string,address)" \
88+
0xProxyAddress "MINTER" 0xAccountToRevoke
89+
```
90+
91+
### 2. Batch Role Revocation
92+
93+
Revoke multiple roles from a single account in one transaction.
94+
95+
```bash
96+
PROXY_ADDR=0x1234... \
97+
ACCOUNT=0x5678... \
98+
REVOKE_ADMIN=false \
99+
REVOKE_MINTER=true \
100+
REVOKE_PAUSER=true \
101+
forge script script/RevokeRecallRole.s.sol:BatchRevokeScript \
102+
--rpc-url https://your-rpc-url \
103+
--broadcast \
104+
--ledger \
105+
--sender 0xYourLedgerAddress
106+
```
107+
108+
### 3. Multi-Account Role Revocation
109+
110+
Revoke one role from multiple accounts.
111+
112+
```bash
113+
PROXY_ADDR=0x1234... \
114+
ROLE_TYPE=MINTER \
115+
ACCOUNTS="0x5678...,0x9abc...,0xdef0..." \
116+
forge script script/RevokeRecallRole.s.sol:MultiAccountRevokeScript \
117+
--rpc-url https://your-rpc-url \
118+
--broadcast \
119+
--ledger \
120+
--sender 0xYourLedgerAddress
121+
```
122+
123+
## Hardware Wallet Configuration
124+
125+
### Custom HD Derivation Path
126+
127+
If you need to use a non-standard derivation path:
128+
129+
```bash
130+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
131+
--rpc-url https://your-rpc-url \
132+
--broadcast \
133+
--ledger \
134+
--hd-paths "m/44'/60'/0'/0/1" \
135+
--sender 0xYourLedgerAddress
136+
```
137+
138+
### Multiple Ledger Accounts
139+
140+
To use a specific account from your Ledger:
141+
142+
```bash
143+
# List available accounts
144+
cast wallet list --ledger
145+
146+
# Use specific account
147+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
148+
--rpc-url https://your-rpc-url \
149+
--broadcast \
150+
--ledger \
151+
--hd-paths "m/44'/60'/0'/0/2" \
152+
--sender 0xYourSpecificAddress
153+
```
154+
155+
## Dry Run (Simulation)
156+
157+
Test the script without broadcasting transactions by omitting the `--broadcast` flag:
158+
159+
```bash
160+
PROXY_ADDR=0x1234... \
161+
ROLE_TYPE=MINTER \
162+
ACCOUNT=0x5678... \
163+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
164+
--rpc-url https://your-rpc-url \
165+
--ledger \
166+
--sender 0xYourLedgerAddress
167+
```
168+
169+
This will simulate the transaction and show you what would happen without actually executing it.
170+
171+
## Safety Features
172+
173+
### 1. Admin Role Self-Revocation Protection
174+
175+
By default, the script prevents you from revoking your own `ADMIN_ROLE` to avoid locking yourself out. To override this:
176+
177+
```bash
178+
ALLOW_SELF_ADMIN_REVOKE=true \
179+
PROXY_ADDR=0x1234... \
180+
ROLE_TYPE=ADMIN \
181+
ACCOUNT=0xYourOwnAddress \
182+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
183+
--rpc-url https://your-rpc-url \
184+
--broadcast \
185+
--ledger \
186+
--sender 0xYourLedgerAddress
187+
```
188+
189+
### 2. Pre-flight Checks
190+
191+
The script performs several checks before executing:
192+
- Verifies the caller has `ADMIN_ROLE`
193+
- Confirms the target account has the role to be revoked
194+
- Displays current role status before and after revocation
195+
- Prevents self-admin revocation (unless explicitly allowed)
196+
197+
### 3. Verbose Logging
198+
199+
All scripts provide detailed console output showing:
200+
- Contract addresses
201+
- Role types and accounts
202+
- Current role status
203+
- Transaction results
204+
- Updated role status
205+
206+
## Environment Variables Reference
207+
208+
| Variable | Required | Description | Example |
209+
|----------|----------|-------------|---------|
210+
| `PROXY_ADDR` | Yes | Recall proxy contract address | `0x1234...` |
211+
| `ROLE_TYPE` | Yes* | Role to revoke: ADMIN, MINTER, or PAUSER | `MINTER` |
212+
| `ACCOUNT` | Yes* | Address to revoke role from | `0x5678...` |
213+
| `ACCOUNTS` | Yes** | Comma-separated addresses | `0x123...,0x456...` |
214+
| `REVOKE_ADMIN` | No | Revoke ADMIN_ROLE (batch only) | `true` or `false` |
215+
| `REVOKE_MINTER` | No | Revoke MINTER_ROLE (batch only) | `true` or `false` |
216+
| `REVOKE_PAUSER` | No | Revoke PAUSER_ROLE (batch only) | `true` or `false` |
217+
| `ALLOW_SELF_ADMIN_REVOKE` | No | Allow self-admin revocation | `true` or `false` |
218+
| `PRIVATE_KEY` | No*** | Private key (if not using hardware wallet) | `0xabc...` |
219+
220+
\* Required for `RevokeRoleScript`
221+
\** Required for `MultiAccountRevokeScript`
222+
\*** Not needed when using `--ledger` or `--trezor`
223+
224+
## Troubleshooting
225+
226+
### Ledger Not Detected
227+
228+
```bash
229+
# Check if Ledger is connected
230+
cast wallet list --ledger
231+
232+
# If not detected, try:
233+
# 1. Reconnect the device
234+
# 2. Unlock with PIN
235+
# 3. Open Ethereum app
236+
# 4. Enable "Contract data" in Ethereum app settings
237+
```
238+
239+
### Transaction Rejected on Device
240+
241+
Make sure:
242+
1. The Ethereum app is open (not Bitcoin or another app)
243+
2. "Contract data" is enabled in the Ethereum app settings
244+
3. You're using the correct derivation path
245+
4. The device firmware is up to date
246+
247+
### "Caller Not Admin" Error
248+
249+
The address you're using doesn't have `ADMIN_ROLE`. Verify:
250+
```bash
251+
cast call $PROXY_ADDR "hasRole(bytes32,address)(bool)" \
252+
$(cast keccak "ADMIN_ROLE") \
253+
$YOUR_ADDRESS \
254+
--rpc-url $RPC_URL
255+
```
256+
257+
### "Account Does Not Have Role" Error
258+
259+
The target account doesn't have the role you're trying to revoke. Check current roles:
260+
```bash
261+
cast call $PROXY_ADDR "hasRole(bytes32,address)(bool)" \
262+
$(cast keccak "MINTER_ROLE") \
263+
$TARGET_ADDRESS \
264+
--rpc-url $RPC_URL
265+
```
266+
267+
## Examples
268+
269+
### Example 1: Remove Minter from Old Admin
270+
271+
```bash
272+
# Using Ledger
273+
PROXY_ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
274+
ROLE_TYPE=MINTER \
275+
ACCOUNT=0x1234567890123456789012345678901234567890 \
276+
forge script script/RevokeRecallRole.s.sol:RevokeRoleScript \
277+
--rpc-url https://api.calibration.node.glif.io/rpc/v1 \
278+
--broadcast \
279+
--ledger \
280+
--sender 0xYourLedgerAddress
281+
```
282+
283+
### Example 2: Remove All Roles from Compromised Account
284+
285+
```bash
286+
# Using Ledger
287+
PROXY_ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
288+
ACCOUNT=0x1234567890123456789012345678901234567890 \
289+
REVOKE_ADMIN=true \
290+
REVOKE_MINTER=true \
291+
REVOKE_PAUSER=true \
292+
forge script script/RevokeRecallRole.s.sol:BatchRevokeScript \
293+
--rpc-url https://api.calibration.node.glif.io/rpc/v1 \
294+
--broadcast \
295+
--ledger \
296+
--sender 0xYourLedgerAddress
297+
```
298+
299+
### Example 3: Revoke Minter from Multiple Test Accounts
300+
301+
```bash
302+
# Using Ledger
303+
PROXY_ADDR=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
304+
ROLE_TYPE=MINTER \
305+
ACCOUNTS="0x1111...,0x2222...,0x3333..." \
306+
forge script script/RevokeRecallRole.s.sol:MultiAccountRevokeScript \
307+
--rpc-url https://api.calibration.node.glif.io/rpc/v1 \
308+
--broadcast \
309+
--ledger \
310+
--sender 0xYourLedgerAddress
311+
```
312+
313+
## Security Best Practices
314+
315+
1. **Always dry run first** - Test without `--broadcast` to verify behavior
316+
2. **Use hardware wallets** - Ledger/Trezor provide better security than private keys
317+
3. **Verify addresses** - Double-check all addresses before broadcasting
318+
4. **Keep admin access** - Don't revoke all admin roles without a replacement
319+
5. **Document changes** - Keep records of role changes for audit purposes
320+
6. **Test on testnet** - Try on testnet before mainnet operations
321+
322+
## Support
323+
324+
For issues or questions:
325+
- Check the [Foundry documentation](https://book.getfoundry.sh/)
326+
- Review the [Ledger Ethereum app guide](https://support.ledger.com/hc/en-us/articles/360009576554)
327+
- Examine the script source code for detailed comments

0 commit comments

Comments
 (0)