docs: add the Defender-to-Chainlink-CRE migration guide by stevep0z · Pull Request #250 · OpenZeppelin/docs

stevep0z · 2026-10-19T22:43:45Z

A two-part guide for teams moving Defender Monitors, Actions, and Relayers to Chainlink CRE.

/chainlink-cre — maps each kind of Defender setup to a CRE pattern and explains what changes when you move it.
/chainlink-cre/worked-example — ports a Governor notification workflow end to end, then simulates, deploys, and verifies it on Sepolia.

Unversioned. Listed under Open Source Tools in src/navigation/ethereum-evm.json only, since the guide is EVM/Sepolia-specific. No homepage card, following the Symbiotic Templates precedent for partner-integration content.

Commits

The guide — both pages, three diagrams, the nav entry, llms.txt.
Nav reorder — moves the Symbiotic Templates folder so partner integrations sit last: Relayer, Monitor, UI Builder, Role Manager, Chainlink CRE, Symbiotic Templates. Separate so it can be dropped independently.

Notes

Examples repo tag — resolved. Now pinned to v1.0.2, which carries a LICENSE and a keeper/README.md consistent with this guide's Bun 1.4 requirement.

Part 2's steps do not reach the TOC. The nine walkthrough steps are <details>/<summary> blocks preceded by <a id="step-N"> anchors, so they collapse by default and every cross-reference deep-links correctly, but they are not headings and so no step appears in the right-hand TOC. The nine collapsed summaries sit together and read as the step list. Plain ### headings are the alternative if reviewers would rather have TOC entries than collapsed-by-default steps.

Section placement. Chainlink CRE and Symbiotic Templates both sit under Open Source Tools, grouped at the end. Whether partner integrations deserve their own separator is worth deciding alongside a broader nav pass rather than here.

Validation

scripts/link-validation.ts — clean, 0 errors.
scripts/link-validation.ts --no-ignore-fragments — no errors attributable to these pages; all <a id> targets and cross-page fragments resolve.
llms.txt regenerated; the diff is the two new entries plus the nav reorder.
next build --turbo passes (1211/1211 pages).
Both routes render, with the Mermaid diagram, the callout, all three images, and every <details> block present.
biome check clean; the nav reorder is a pure block move.

🤖 Generated with Claude Code

netlify · 2026-10-19T22:43:51Z

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Name	Link
🔨 Latest commit	`1237740`
🔍 Latest deploy log	https://app.netlify.com/projects/openzeppelin-docs-v2/deploys/6ad6c5d25bbb80f6db5f7035
😎 Deploy Preview	https://deploy-preview-250--openzeppelin-docs-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

A two-part guide for teams moving Defender Monitors, Actions, and Relayers to Chainlink CRE: - /chainlink-cre maps each kind of Defender setup to a CRE pattern and explains what changes when you move it. - /chainlink-cre/worked-example ports a Governor notification workflow end to end, then simulates, deploys, and verifies it on Sepolia. Unversioned, listed under Open Source Tools in the EVM navigation. The walkthrough's nine steps are collapsible <details> blocks, each preceded by an explicit <a id> anchor so cross-references deep-link. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

OpenZeppelin's own tools keep their existing house order and partner integrations go last, alphabetical among themselves: Relayer, Monitor, UI Builder, Role Manager, Chainlink CRE, Symbiotic Templates This only moves the Symbiotic Templates folder, which currently sits first in the section. Kept as its own commit so it can be dropped independently of the Chainlink CRE guide. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

ericglau

LGTM. A few aside comments:

the new Chainlink section and the moved Symbiotic templates section appear under Open Source Tools. Would it make sense for any of these to be under a new section header?
agree with the comment about 1.0.2, seems an update is needed for that

tirumerla

Added couple of comments

tirumerla · 2026-10-19T23:16:59Z

+description: Map each kind of Defender Monitor, Action, and Relayer setup to a Chainlink CRE pattern, and see what changes when you move it
+---
+
+This guide has two parts. Part 1 (this page) maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. Part 2 walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.


May be slight adjustment

Suggested change

This guide has two parts. Part 1 (this page) maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. Part 2 walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.

This guide has two parts. Part 1 defined in this page maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. [Part 2](/chainlink-cre/worked-example) walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.

Applied, with commas. "Part 1, defined in this page, maps each kind of…". Also took the inline Part 2 link. Thanks!

tirumerla · 2026-10-19T23:17:01Z

+
+This guide has two parts. Part 1 (this page) maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. Part 2 walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.
+
+**Part 2:** [Worked Example](/chainlink-cre/worked-example)


You can remove this

Removed. Did the same on Part 2 for symmetry, as both parts are now linked inline.

tirumerla · 2026-10-19T23:49:20Z

+
+**Tested with** CRE CLI 1.34.0, `@chainlink/cre-sdk` 1.19.1, and Bun 1.4.0. **Bun 1.4 or later is required:** on Bun 1.3.x, `bun install --frozen-lockfile` in Step 1 fails with `UnknownLockfileVersion`. Check with `bun --version`. Have these ready:
+
+- The example project, [`gov-alert` in OpenZeppelin/defender-to-cre-examples](https://github.com/OpenZeppelin/defender-to-cre-examples/tree/v1.0.1/gov-alert), plus [Bun](https://bun.sh/docs/installation) 1.4 or later, [Foundry](https://www.getfoundry.sh/introduction/installation) (for the fixture and [Step 7](#step-7)'s `cast send`), and the [CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation), [logged in](https://docs.chain.link/cre/account/cli-login).


v1.0.1 doesn't have license file on v1.0.2. Please replace with v1.0.2

Do you want to do this as part of this PR or as an update?

Let's keep it in this PR. I've replaced the occurrences of this. v1.0.2 also adds the Bun 1.4 line to the keeper README, so the guide and the README are now aligned.

tirumerla · 2026-10-19T23:49:41Z

+Clone [OpenZeppelin/defender-to-cre-examples](https://github.com/OpenZeppelin/defender-to-cre-examples/tree/v1.0.1) and move into its [`gov-alert`](https://github.com/OpenZeppelin/defender-to-cre-examples/tree/v1.0.1/gov-alert) folder:
+
+```bash
+git clone --branch v1.0.1 https://github.com/OpenZeppelin/defender-to-cre-examples.git


Suggested change

git clone --branch v1.0.1 https://github.com/OpenZeppelin/defender-to-cre-examples.git

git clone --branch v1.0.2 https://github.com/OpenZeppelin/defender-to-cre-examples.git

tirumerla · 2026-10-19T23:52:03Z

+<details>
+<summary><strong>Step 2: Configure Your Governor and Notification Destination</strong></summary>
+
+Create `gov-alert/config.simulation-blog.json` with these fields. Replace the placeholder address and URL before running it:


We changed this to gov-alert/config.simulation.json, also the example already ships config.example.json with these four fields, so copying it is simpler. Copy gov-alert/config.example.json to gov-alert/config.simulation-local.json and fill in these fields?

Done! Switched to copying config.example.json to config.simulation-local.json, as suggested.

tirumerla · 2026-10-19T23:52:59Z

+    secrets-path: ""
+```
+
+Create `gov-alert/config.staging.json` with the same four fields as [Step 2](#step-2) (or edit it, if the example ships one), and set `notifyWebhookUrl` to an endpoint you can inspect. Then deploy from the project root and confirm the registration:


Suggested change

Create `gov-alert/config.staging.json` with the same four fields as [Step 2](#step-2) (or edit it, if the example ships one), and set `notifyWebhookUrl` to an endpoint you can inspect. Then deploy from the project root and confirm the registration:

Create `gov-alert/config.staging.json` from `config.example.json` with the same four fields as [Step 2](#step-2), and set `notifyWebhookUrl` to an endpoint you can inspect. Then deploy from the project root and confirm the registration:

tirumerla · 2026-10-19T23:54:32Z

+
+```json
+{
+  "text": "**New Proposal** Upgrade the treasury by 0x1234 [TX](https://sepolia.etherscan.io/tx/TRANSACTION_HASH)"


Since this is a sample

Suggested change

"text": "**New Proposal** Upgrade the treasury by 0x1234 [TX](https://sepolia.etherscan.io/tx/TRANSACTION_HASH)"

"text": "**New Proposal** Upgrade the treasury by 0x1234 [TX](<https://sepolia.etherscan.io/tx/TRANSACTION_HASH>)"

Changes made.

tirumerla · 2026-10-19T23:56:05Z

+description: Port OpenZeppelin's Defender governance alert to Chainlink CRE, then simulate, deploy, and verify it on Sepolia
+---
+
+This is Part 2 of Adapting Defender Workflows to Chainlink CRE. Part 1 maps each kind of Defender workflow to CRE and explains what changes; this part puts that into practice with one complete port you can run yourself.


"Adapting Defender Workflows to Chainlink CRE" isn't used as a title anywhere else. Please refer to Part 1 by its page title.

Right, part 1 is now referred to as "Mapping Your Defender Setup".

- Pin the examples repo to v1.0.2 - Restore the angle brackets in the Step 4 sample payload - Copy config.example.json for the simulation and staging configs - Refer to Part 1 by its page title; link both parts inline Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

stevep0z · 2026-10-20T02:05:03Z

Thanks @tirumerla and @ericglau. @ericglau we'll go ahead with a new section header in a later PR because that would potentially affect the other nav trees and is better in a reorg. I applied all other feedback.

tirumerla

lgtm

stevep0z force-pushed the docs/chainlink-cre-migration branch from 725502b to 4b6c925 Compare October 19, 2026 22:48

stevep0z marked this pull request as ready for review October 19, 2026 22:56

stevep0z requested a review from a team as a code owner October 19, 2026 22:56

stevep0z requested a review from ericglau October 19, 2026 22:56

stevep0z and others added 2 commits October 19, 2026 18:01

stevep0z force-pushed the docs/chainlink-cre-migration branch from 4b6c925 to 0155fc3 Compare October 19, 2026 23:02

ericglau approved these changes Oct 19, 2026

View reviewed changes

tirumerla approved these changes Oct 19, 2026

View reviewed changes

stevep0z and others added 2 commits October 19, 2026 19:56

docs(chainlink-cre): reword the Part 1 intro

1237740

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tirumerla approved these changes Oct 20, 2026

View reviewed changes

stevep0z merged commit 66303ed into main Oct 20, 2026
12 checks passed

stevep0z deleted the docs/chainlink-cre-migration branch October 20, 2026 02:25

github-actions Bot locked and limited conversation to collaborators Oct 20, 2026

	This guide has two parts. Part 1 (this page) maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. Part 2 walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.
	This guide has two parts. Part 1 defined in this page maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. [Part 2](/chainlink-cre/worked-example) walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.


		This guide has two parts. Part 1 (this page) maps each kind of Defender Setup to Chainlink CRE and explains what changes when you move it. Part 2 walks through a complete port of OpenZeppelin's Defender governance alert that you simulate, deploy, and verify on Sepolia.

		Part 2: [Worked Example](/chainlink-cre/worked-example)


		Tested with CRE CLI 1.34.0, `@chainlink/cre-sdk` 1.19.1, and Bun 1.4.0. Bun 1.4 or later is required: on Bun 1.3.x, `bun install --frozen-lockfile` in Step 1 fails with `UnknownLockfileVersion`. Check with `bun --version`. Have these ready:

		- The example project, [`gov-alert` in OpenZeppelin/defender-to-cre-examples](https://github.com/OpenZeppelin/defender-to-cre-examples/tree/v1.0.1/gov-alert), plus [Bun](https://bun.sh/docs/installation) 1.4 or later, [Foundry](https://www.getfoundry.sh/introduction/installation) (for the fixture and [Step 7](#step-7)'s `cast send`), and the [CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation), [logged in](https://docs.chain.link/cre/account/cli-login).

	git clone --branch v1.0.1 https://github.com/OpenZeppelin/defender-to-cre-examples.git
	git clone --branch v1.0.2 https://github.com/OpenZeppelin/defender-to-cre-examples.git

	Create `gov-alert/config.staging.json` with the same four fields as [Step 2](#step-2) (or edit it, if the example ships one), and set `notifyWebhookUrl` to an endpoint you can inspect. Then deploy from the project root and confirm the registration:
	Create `gov-alert/config.staging.json` from `config.example.json` with the same four fields as [Step 2](#step-2), and set `notifyWebhookUrl` to an endpoint you can inspect. Then deploy from the project root and confirm the registration:

	"text": "New Proposal Upgrade the treasury by 0x1234 [TX](https://sepolia.etherscan.io/tx/TRANSACTION_HASH)"
	"text": "New Proposal Upgrade the treasury by 0x1234 [TX](<https://sepolia.etherscan.io/tx/TRANSACTION_HASH>)"

Conversation

stevep0z commented Oct 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Commits

Notes

Validation

Uh oh!

netlify Bot commented Oct 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Uh oh!

ericglau left a comment

Choose a reason for hiding this comment

Uh oh!

tirumerla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevep0z commented Oct 20, 2026

Uh oh!

tirumerla left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stevep0z commented Oct 19, 2026 •

edited

Loading

netlify Bot commented Oct 19, 2026 •

edited

Loading