Skip to content

Commit ec1e21c

Browse files
NicoMolinaOZNicoMolinaOZ
committed
chore: Improvements
1 parent 2474350 commit ec1e21c

1 file changed

Lines changed: 88 additions & 74 deletions

File tree

‎content/defender/migration.mdx‎

Lines changed: 88 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ title: Migrating from Defender to Open Source
77
Defender is now in maintenance mode. To continue using monitoring and relaying capabilities with the latest features and updates, we recommend migrating to OpenZeppelin's open source tools.
88

99
This guide covers:
10+
1011
- Migrating from **Defender Monitor** to [OpenZeppelin Monitor](/monitor)
1112
- Migrating from **Defender Relayer** to [OpenZeppelin Relayer](/relayer)
1213

@@ -57,8 +58,11 @@ The "OpenZeppelin Monitor Configurations" button will download a .zip file conta
5758
- Webhook URLs for notifications
5859
- Service integration credentials (Slack, Telegram, Discord, etc.)
5960

60-
<Callout type='warn'>
61-
Custom Actions attached to your Defender monitors will not be automatically migrated. You will need to manually recreate any custom action logic following the [OpenZeppelin Monitor documentation](/monitor) for trigger handlers and custom notifications.
61+
<Callout type="warn">
62+
Custom Actions attached to your Defender monitors will not be automatically
63+
migrated. You will need to manually recreate any custom action logic following
64+
the [OpenZeppelin Monitor documentation](/monitor) for trigger handlers and
65+
custom notifications.
6266
</Callout>
6367

6468
Alternatively, if you don't want to download all the monitors configurations at once, you can navigate to each individual monitor and download its configuration separately. This gives you more control over which monitors to migrate and when.
@@ -99,33 +103,30 @@ Export your Defender Relayer configurations using the "OpenZeppelin Relayer Conf
99103

100104
![Defender Relayer Migration Button](/defender/relayer-migration-button.png)
101105

102-
<Callout type='info'>
103-
If you don't want a specific relayer to be migrated, delete that relayer before clicking the download button.
106+
<Callout type="info">
107+
If you don't want a specific relayer to be migrated, delete that relayer
108+
before clicking the download button.
104109
</Callout>
105110

106111
**What you'll download:**
107112

108-
- **ZIP file**: Downloaded if you have relayers on forked or private networks. The ZIP contains a `config.json` file and a `networks/` folder with custom network definitions.
109-
- **JSON file**: Downloaded if all your relayers are on standard public networks. This is a single `config.json` file.
113+
A **ZIP file** containing:
114+
115+
- `config.json` - Your relayer configurations
116+
- `networks/` folder - Custom network definitions (if you have relayers on forked or private networks)
110117

111118
#### Step 2: Set Up OpenZeppelin Relayer
112119

113120
Before importing your configurations, set up the OpenZeppelin Relayer infrastructure by following the [OpenZeppelin Relayer Quick Start Guide](/relayer/quickstart).
114121

115122
#### Step 3: Place Configuration Files
116123

117-
**If you downloaded a ZIP file:**
118-
119-
1. Extract the ZIP file
124+
1. Extract the downloaded ZIP file
120125
2. Copy `config.json` to the `config/` directory in your OpenZeppelin Relayer project
121-
3. Copy the `networks/` folder contents to `config/networks/`
122-
123-
**If you downloaded a plain JSON file:**
124-
125-
1. Copy the downloaded file to the `config/` directory
126-
2. Rename it to `config.json`
126+
3. If you have custom networks, copy the `networks/` folder contents to `config/networks/`
127127

128128
Your directory structure should look like:
129+
129130
```
130131
openzeppelin-relayer/
131132
├── config/
@@ -139,26 +140,25 @@ openzeppelin-relayer/
139140

140141
After placing the files, you need to update several configuration values:
141142

142-
**For custom networks (if you downloaded a ZIP file):**
143+
**For custom networks:**
143144

144-
Update the RPC URLs in each network definition file under `config/networks/`. Replace placeholder values with your actual RPC endpoint URLs:
145+
If you have forked or private networks, update the RPC URLs in each network definition file under `config/networks/`. Replace placeholder values with your actual RPC endpoint URLs:
145146

146147
```json
147148
{
148149
"network": "my-custom-network",
149-
"rpc_urls": [
150-
"https://your-rpc-endpoint.com"
151-
]
150+
"rpc_urls": ["https://your-rpc-endpoint.com"]
152151
}
153152
```
154153

155-
**For all migrations (both ZIP and JSON):**
154+
**For all relayers:**
156155

157156
Edit `config/config.json` to update:
158157

159158
1. **Signer configuration**: Each relayer needs a signer configured. See [Choosing a Signer Type](#choosing-a-signer-type) below for options and setup instructions.
160159

161160
2. **Notification webhooks**: Update the `notifications` section with your webhook URLs:
161+
162162
```json
163163
"notifications": [
164164
{
@@ -175,8 +175,9 @@ Edit `config/config.json` to update:
175175

176176
3. **Network-specific policies**: Review and adjust policies for each relayer as needed (gas price caps, minimum balance thresholds, whitelist receivers, etc.).
177177

178-
<Callout type='info'>
179-
For detailed configuration options, see the [OpenZeppelin Relayer Configuration documentation](/relayer/configuration).
178+
<Callout type="info">
179+
For detailed configuration options, see the [OpenZeppelin Relayer
180+
Configuration documentation](/relayer/configuration).
180181
</Callout>
181182

182183
#### Step 5: Verify OpenZeppelin Relayer Works
@@ -219,8 +220,11 @@ Once OpenZeppelin Relayer is running correctly:
219220
5. **Recommended**: Transfer a small amount first and test with a transaction
220221
6. If the test transaction succeeds, transfer the remaining funds
221222

222-
<Callout type='warn'>
223-
Since you're creating new relayer addresses (see [Understanding Signer Migration](#understanding-signer-migration)), make sure to update any smart contract permissions, whitelists, or access control lists to include the new addresses before transferring all funds.
223+
<Callout type="warn">
224+
Since you're creating new relayer addresses (see [Understanding Signer
225+
Migration](#understanding-signer-migration)), make sure to update any smart
226+
contract permissions, whitelists, or access control lists to include the new
227+
addresses before transferring all funds.
224228
</Callout>
225229

226230
#### Step 7: Gradually Move Traffic
@@ -246,6 +250,7 @@ Defender Relayers use AWS Key Management Service (AWS KMS) to secure private key
246250
- You **must create new relayers with new addresses** when migrating to OpenZeppelin Relayer
247251

248252
This is a fundamental security feature of AWS KMS that protects your keys from unauthorized access.
253+
249254
</Callout>
250255

251256
### Choosing a Signer Type
@@ -254,15 +259,15 @@ OpenZeppelin Relayer supports multiple signer types to accommodate different sec
254259

255260
#### Available Signer Options
256261

257-
| Signer Type | Description |
258-
|------------|-------------|
259-
| **Local** | Encrypted keystore file stored on the filesystem |
260-
| **AWS KMS** | Amazon Web Services Key Management Service |
261-
| **Google Cloud KMS** | Google Cloud Key Management Service |
262-
| **HashiCorp Vault** | Vault secret engine for private key storage |
263-
| **HashiCorp Vault Transit** | Vault Transit encryption engine |
264-
| **Turnkey** | Third-party key management service |
265-
| **Coinbase Developer Platform (CDP)** | Coinbase's managed key solution |
262+
| Signer Type | Description |
263+
| ------------------------------------- | ------------------------------------------------ |
264+
| **Local** | Encrypted keystore file stored on the filesystem |
265+
| **AWS KMS** | Amazon Web Services Key Management Service |
266+
| **Google Cloud KMS** | Google Cloud Key Management Service |
267+
| **HashiCorp Vault** | Vault secret engine for private key storage |
268+
| **HashiCorp Vault Transit** | Vault Transit encryption engine |
269+
| **Turnkey** | Third-party key management service |
270+
| **Coinbase Developer Platform (CDP)** | Coinbase's managed key solution |
266271

267272
#### Migration Steps for Signers
268273

@@ -277,8 +282,10 @@ OpenZeppelin Relayer supports multiple signer types to accommodate different sec
277282
5. **Transfer funds** from old Defender Relayer addresses to new OpenZeppelin Relayer addresses
278283
6. **Test thoroughly** before switching production traffic
279284

280-
<Callout type='info'>
281-
For detailed configuration instructions for each signer type, see the [OpenZeppelin Relayer Signer Configuration documentation](/relayer/configuration/signers).
285+
<Callout type="info">
286+
For detailed configuration instructions for each signer type, see the
287+
[OpenZeppelin Relayer Signer Configuration
288+
documentation](/relayer/configuration/signers).
282289
</Callout>
283290

284291
### SDK Migration
@@ -304,39 +311,39 @@ npm install @openzeppelin/relayer-sdk
304311
Before (Defender SDK):
305312

306313
```jsx
307-
const { Defender } = require('@openzeppelin/defender-sdk');
314+
const { Defender } = require("@openzeppelin/defender-sdk");
308315
const client = new Defender({
309-
relayerApiKey: 'YOUR_API_KEY',
310-
relayerApiSecret: 'YOUR_API_SECRET'
316+
relayerApiKey: "YOUR_API_KEY",
317+
relayerApiSecret: "YOUR_API_SECRET",
311318
});
312319

313320
const tx = await client.relaySigner.sendTransaction({
314-
to: '0x...',
315-
value: '1000000000000000000',
316-
data: '0x',
321+
to: "0x...",
322+
value: "1000000000000000000",
323+
data: "0x",
317324
gasLimit: 21000,
318-
speed: 'fast'
325+
speed: "fast",
319326
});
320327
```
321328

322329
After (OpenZeppelin Relayer SDK):
323330

324331
```typescript
325-
import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';
332+
import { RelayerApi, Configuration } from "@openzeppelin/relayer-sdk";
326333

327334
const config = new Configuration({
328-
basePath: 'http://localhost:8080/api/v1',
329-
accessToken: 'YOUR_API_KEY'
335+
basePath: "http://localhost:8080/api/v1",
336+
accessToken: "YOUR_API_KEY",
330337
});
331338

332339
const relayerApi = new RelayerApi(config);
333340

334-
const tx = await relayerApi.sendTransaction('your-relayer-id', {
335-
to: '0x...',
336-
value: '1000000000000000000',
337-
data: '0x',
341+
const tx = await relayerApi.sendTransaction("your-relayer-id", {
342+
to: "0x...",
343+
value: "1000000000000000000",
344+
data: "0x",
338345
gas_limit: 21000,
339-
speed: 'fast'
346+
speed: "fast",
340347
});
341348
```
342349

@@ -345,34 +352,37 @@ const tx = await relayerApi.sendTransaction('your-relayer-id', {
345352
Before (Defender SDK):
346353

347354
```jsx
348-
import { Relayer } from '@openzeppelin/defender-sdk-relay-signer-client';
355+
import { Relayer } from "@openzeppelin/defender-sdk-relay-signer-client";
349356
const relayer = new Relayer({ apiKey: API_KEY, apiSecret: API_SECRET });
350357
const tx = await relayer.getTransaction(transactionId);
351358
```
352359

353360
After (OpenZeppelin Relayer SDK):
354361

355362
```typescript
356-
import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';
363+
import { RelayerApi, Configuration } from "@openzeppelin/relayer-sdk";
357364

358365
const config = new Configuration({
359-
basePath: 'http://localhost:8080/api/v1',
360-
accessToken: 'YOUR_API_KEY'
366+
basePath: "http://localhost:8080/api/v1",
367+
accessToken: "YOUR_API_KEY",
361368
});
362369

363370
const relayerApi = new RelayerApi(config);
364-
const tx = await relayerApi.getTransactionById('your-relayer-id', transactionId);
371+
const tx = await relayerApi.getTransactionById(
372+
"your-relayer-id",
373+
transactionId
374+
);
365375
```
366376

367377
**Listing Relayers**
368378

369379
Before (Defender SDK):
370380

371381
```jsx
372-
const { Defender } = require('@openzeppelin/defender-sdk');
382+
const { Defender } = require("@openzeppelin/defender-sdk");
373383
const client = new Defender({
374-
apiKey: 'YOUR_API_KEY',
375-
apiSecret: 'YOUR_API_SECRET'
384+
apiKey: "YOUR_API_KEY",
385+
apiSecret: "YOUR_API_SECRET",
376386
});
377387

378388
const relayers = await client.relay.list();
@@ -381,11 +391,11 @@ const relayers = await client.relay.list();
381391
After (OpenZeppelin Relayer SDK):
382392

383393
```typescript
384-
import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';
394+
import { RelayerApi, Configuration } from "@openzeppelin/relayer-sdk";
385395

386396
const config = new Configuration({
387-
basePath: 'http://localhost:8080/api/v1',
388-
accessToken: 'YOUR_API_KEY'
397+
basePath: "http://localhost:8080/api/v1",
398+
accessToken: "YOUR_API_KEY",
389399
});
390400

391401
const relayerApi = new RelayerApi(config);
@@ -394,17 +404,17 @@ const relayers = await relayerApi.listRelayers();
394404

395405
#### API Method Mapping
396406

397-
| Defender SDK Method | OpenZeppelin Relayer SDK Method |
398-
|--------------------|--------------------------------|
399-
| `client.relaySigner.sendTransaction()` | `relayerApi.sendTransaction()` |
400-
| `relayer.getTransaction()` | `relayerApi.getTransactionById()` |
401-
| `relayer.list()` | `relayerApi.listTransactions()` |
402-
| `relayer.replaceTransactionById()` | `relayerApi.replaceTransaction()` |
403-
| `relayer.cancelTransactionById()` | `relayerApi.cancelTransaction()` |
404-
| `relayer.sign()` | `relayerApi.sign()` |
405-
| `relayer.signTypedData()` | `relayerApi.signTypedData()` |
406-
| `relayer.getRelayer()` | `relayerApi.getRelayer()` |
407-
| `relayer.getRelayerStatus()` | `relayerApi.getRelayerStatus()` |
407+
| Defender SDK Method | OpenZeppelin Relayer SDK Method |
408+
| -------------------------------------- | --------------------------------- |
409+
| `client.relaySigner.sendTransaction()` | `relayerApi.sendTransaction()` |
410+
| `relayer.getTransaction()` | `relayerApi.getTransactionById()` |
411+
| `relayer.list()` | `relayerApi.listTransactions()` |
412+
| `relayer.replaceTransactionById()` | `relayerApi.replaceTransaction()` |
413+
| `relayer.cancelTransactionById()` | `relayerApi.cancelTransaction()` |
414+
| `relayer.sign()` | `relayerApi.sign()` |
415+
| `relayer.signTypedData()` | `relayerApi.signTypedData()` |
416+
| `relayer.getRelayer()` | `relayerApi.getRelayer()` |
417+
| `relayer.getRelayerStatus()` | `relayerApi.getRelayerStatus()` |
408418

409419
For detailed migration instructions and support, visit the [OpenZeppelin Relayer documentation](/relayer).
410420

@@ -413,11 +423,14 @@ For detailed migration instructions and support, visit the [OpenZeppelin Relayer
413423
## Support and Resources
414424

415425
### Documentation
426+
416427
- [OpenZeppelin Monitor Documentation](/monitor)
417428
- [OpenZeppelin Relayer Documentation](/relayer)
418429

419430
### Getting Help
431+
420432
If you encounter issues during migration or have questions:
433+
421434
- Review the respective documentation for each tool
422435
- Check GitHub repositories for issues and discussions
423436
- Reach out to the OpenZeppelin community
@@ -427,6 +440,7 @@ If you encounter issues during migration or have questions:
427440
Use this checklist to track your migration progress:
428441

429442
#### Monitor Migration
443+
430444
- [ ] Export Monitor configurations from Defender
431445
- [ ] Review and update placeholder values (API keys, RPC URLs, etc.)
432446
- [ ] Set up OpenZeppelin Monitor infrastructure
@@ -437,6 +451,7 @@ Use this checklist to track your migration progress:
437451
- [ ] Switch over and decommission Defender monitors
438452

439453
#### Relayer Migration
454+
440455
- [ ] Export Relayer configurations from Defender
441456
- [ ] Review and update placeholder values (signers, RPC URLs, policies)
442457
- [ ] Set up OpenZeppelin Relayer infrastructure
@@ -447,4 +462,3 @@ Use this checklist to track your migration progress:
447462
- [ ] Transfer funds from Defender Relayers
448463
- [ ] Gradually move traffic to OpenZeppelin Relayers
449464
- [ ] Decommission Defender Relayers
450-

0 commit comments

Comments
 (0)