Migrating from Defender to Open Source

Overview

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.

This guide covers:

• Migrating from Defender Monitor to OpenZeppelin Monitor
• Migrating from Defender Relayer to OpenZeppelin Relayer

Both tools are designed to be self-hosted, giving you full control over your infrastructure while maintaining the functionality you rely on.

Migration Strategy

Planning Your Migration

1. Review your current usage: Identify which Defender modules you're actively using
2. Export configurations: Use Defender UI to export Monitors and Relayers configuration
3. Set up infrastructure: Configure the open source tools on your own infrastructure
4. Test thoroughly: Run both systems in parallel during the transition period
5. Migrate traffic gradually: Switch over when you're confident everything works correctly

Timeline Considerations

• Plan for adequate testing time before fully switching over
• Consider running both systems in parallel during migration
• Schedule migration during low-traffic periods if possible

Monitor Migration

From Defender Monitor to OpenZeppelin Monitor

OpenZeppelin Monitor offers similar functionality to Defender Monitor:

• Event and function monitoring: Monitor smart contract events and function calls
• Custom filtering: Write custom JavaScript, Python or Bash filters to match specific conditions
• Multiple notification channels: Integrate with Slack, Telegram, Discord, webhooks and emails

Getting Started

To begin your Monitor migration:

1. Review your existing monitors: Export your Defender Monitor configurations using the "Download OpenZeppelin Monitor Configurations" button
2. Import your configurations: Use the exported configurations to recreate your monitors in OpenZeppelin Monitor
3. Set up OpenZeppelin Monitor: Follow the installation guide to set up the Monitor.

The "OpenZeppelin Monitor Configurations" button will download a .zip file containing configuration files for every monitor in your Defender account (If for any reason you don't want a specific monitor to be migrated, we recommend you delete the monitor before clicking on the OpenZeppelin Monitor Configurations button ). These configurations are ready to copy and paste directly into OpenZeppelin Monitor. Before running the monitors, make sure to review and update any placeholder values in the configuration files, such as:

• API keys and secrets
• RPC URLs and endpoint addresses
• Webhook URLs for notifications
• Service integration credentials (Slack, Telegram, Discord, etc.)

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.

Here's a video with the process step by step: https://www.loom.com/share/6de3d269f92c4df6abe951af69c64feb

4. Test your monitors: Verify that alerts trigger correctly before decommissioning Defender monitors

For detailed migration instructions and support, visit the OpenZeppelin Monitor documentation.

Relayer Migration

From Defender Relayer to OpenZeppelin Relayer

OpenZeppelin Relayer offers similar functionality to Defender Relayer:

• Transaction relaying: Submit transactions to supported blockchain networks efficiently
• Transaction signing: Securely sign transactions using configurable key management
• Nonce management: Handle nonce management to ensure transaction order
• Gas pricing: Automatic gas price estimation and configuration
• Multi-chain support: Interact with EVM, Solana, and Stellar networks
• SDK integration: Easily interact with the relayer through a companion JavaScript/TypeScript SDK
• Configurable policies: Define and enforce network-specific policies for transaction processing

Getting Started

To begin your Relayer migration:

1. Review your existing relayers: Export your Defender Relayer configurations using the "OpenZeppelin Relayer Configurations" button

The "OpenZeppelin Relayer Configurations" button will download a .zip file containing configuration files for every relayer in your Defender account (If for any reason you don't want a specific relayer to be migrated, we recommend you delete the relayer before clicking on the OpenZeppelin Relayer Configurations button ). These configurations are ready to copy and paste directly into OpenZeppelin Relayer. Before running the relayers, make sure to review and update any placeholder values in the configuration files, such as:

• RPC URLs and endpoint addresses
• Signer configurations and private keys
• Network-specific policies
• Webhook URLs for notifications

2. Set up OpenZeppelin Relayer: Follow the installation guide to deploy the Relayer on your infrastructure

3. Import your configurations: Use the exported configurations to recreate your relayers in OpenZeppelin Relayer

4. Test your relayers: Verify that transactions are processed correctly before decommissioning Defender relayers

5. Transfer funds: Once your OpenZeppelin Relayers are fully configured and running, transfer the funds from your Defender relayers to your new OpenZeppelin Relayer addresses using the Withdraw functionality

6. Gradually move volume: Shift traffic from Defender relayer to OpenZeppelin Relayer incrementally

Here's a video with the process step by step: https://www.loom.com/share/cb5e0f5d8c064a71abc8c18fac273cf0

Understanding Signer Migration

Choosing a Signer Type

OpenZeppelin Relayer supports multiple signer types to accommodate different security requirements and infrastructure setups. Each relayer must be configured with a signer that manages the private key for transaction signing.

Available Signer Options

Migration Steps for Signers

1. Select a signer type that matches your security and infrastructure requirements
2. Generate new keys using your chosen signer service (refer to the Signer Configuration documentation for detailed setup instructions)
3. Configure your relayers to use the new signers in your OpenZeppelin Relayer configuration
4. Update smart contract permissions: Since you'll have new addresses, update any:
   • Access control lists
   • Whitelist entries
   • Role assignments
   • Trusted forwarder configurations
5. Transfer funds from old Defender Relayer addresses to new OpenZeppelin Relayer addresses
6. Test thoroughly before switching production traffic

SDK Migration

If you are using the Defender SDK (@openzeppelin/defender-sdk) to interact with Defender Relayers programmatically, you will need to migrate to the OpenZeppelin Relayer SDK (@openzeppelin/relayer-sdk).

Installation

Replace the Defender SDK with the OpenZeppelin Relayer SDK:

# Remove Defender SDK
npm uninstall @openzeppelin/defender-sdk @openzeppelin/defender-sdk-relay-client @openzeppelin/defender-sdk-relay-signer-client

# Install OpenZeppelin Relayer SDK
npm install @openzeppelin/relayer-sdk

Code Migration Examples

Sending a Transaction

Before (Defender SDK):

const { Defender } = require('@openzeppelin/defender-sdk');
const client = new Defender({
  relayerApiKey: 'YOUR_API_KEY',
  relayerApiSecret: 'YOUR_API_SECRET'
});

const tx = await client.relaySigner.sendTransaction({
  to: '0x...',
  value: '1000000000000000000',
  data: '0x',
  gasLimit: 21000,
  speed: 'fast'
});

After (OpenZeppelin Relayer SDK):

import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';

const config = new Configuration({
  basePath: 'http://localhost:8080/api/v1',
  accessToken: 'YOUR_API_KEY'
});

const relayerApi = new RelayerApi(config);

const tx = await relayerApi.sendTransaction('your-relayer-id', {
  to: '0x...',
  value: '1000000000000000000',
  data: '0x',
  gas_limit: 21000,
  speed: 'fast'
});

Getting Transaction Status

Before (Defender SDK):

import { Relayer } from '@openzeppelin/defender-sdk-relay-signer-client';
const relayer = new Relayer({ apiKey: API_KEY, apiSecret: API_SECRET });
const tx = await relayer.getTransaction(transactionId);

After (OpenZeppelin Relayer SDK):

import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';

const config = new Configuration({
  basePath: 'http://localhost:8080/api/v1',
  accessToken: 'YOUR_API_KEY'
});

const relayerApi = new RelayerApi(config);
const tx = await relayerApi.getTransactionById('your-relayer-id', transactionId);

Listing Relayers

Before (Defender SDK):

const { Defender } = require('@openzeppelin/defender-sdk');
const client = new Defender({
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET'
});

const relayers = await client.relay.list();

After (OpenZeppelin Relayer SDK):

import { RelayerApi, Configuration } from '@openzeppelin/relayer-sdk';

const config = new Configuration({
  basePath: 'http://localhost:8080/api/v1',
  accessToken: 'YOUR_API_KEY'
});

const relayerApi = new RelayerApi(config);
const relayers = await relayerApi.listRelayers();

API Method Mapping

For detailed migration instructions and support, visit the OpenZeppelin Relayer documentation.

Support and Resources

Documentation

• OpenZeppelin Monitor Documentation
• OpenZeppelin Relayer Documentation

Getting Help

If you encounter issues during migration or have questions:

• Review the respective documentation for each tool
• Check GitHub repositories for issues and discussions
• Reach out to the OpenZeppelin community

Migration Checklist

Use this checklist to track your migration progress:

Monitor Migration

• Export Monitor configurations from Defender
• Review and update placeholder values (API keys, RPC URLs, etc.)
• Set up OpenZeppelin Monitor infrastructure
• Import and configure monitors
• Recreate custom action logic
• Test alert triggers
• Run in parallel with Defender Monitor
• Switch over and decommission Defender monitors

Relayer Migration

• Export Relayer configurations from Defender
• Review and update placeholder values (signers, RPC URLs, policies)
• Set up OpenZeppelin Relayer infrastructure
• Import and configure relayers
• Update SDK integration code (if applicable)
• Test transaction processing
• Run in parallel with Defender Relayers
• Transfer funds from Defender Relayers
• Gradually move traffic to OpenZeppelin Relayers
• Decommission Defender Relayers