ERC-7786 based crosschain bridge for ERC-20 tokens by Amxx · Pull Request #5914 · OpenZeppelin/openzeppelin-contracts

Amxx · 2025-09-04T08:38:53Z

Based of #5904
Fixes #5900

PR Checklist

Tests
Coverage
Documentation
Changeset entry (run npx changeset add)

Co-authored-by: Ernesto García <ernestognw@gmail.com>

…BridgeERC20Bridgeable and ERC20Crosschain

changeset-bot · 2025-09-04T08:38:57Z

🦋 Changeset detected

Latest commit: 941db67

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openzeppelin-solidity	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2025-09-04T08:39:00Z

Walkthrough

Adds a cross-chain ERC-20 bridging stack built on ERC-7786. Introduces BridgeCore (link management, messaging, authorization), BridgeERC20 (token-agnostic transfer flow with send/receive events), and two implementations: BridgeERC20Bridgeable (ERC-7802 mint/burn) and BridgeERC20Custodial (custody transfers). Adds ERC20Crosschain extension that combines ERC20 with BridgeERC20 using burn/mint for lock/unlock and allowance via crosschainTransferFrom. Updates ERC20BridgeableMock constructor and adds internal _setBridge. Introduces comprehensive tests for bridges and ERC20Crosschain, plus a helper tweak for account impersonation.

Possibly related PRs

Migrate ERC7786Recipient from community #5904: Introduces ERC-7786 recipient/gateway types that this PR inherits and uses for cross-chain messaging.

Suggested labels

ignore-changeset, documentation

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR bundles extensive scaffolding (BridgeCore, BridgeERC20, custodial and bridgeable variants), mocks, test helpers, and documentation beyond the single objective of adding the ERC-7786 bridgable ERC-20 extension defined in issue #5900.	Please split the core messaging scaffolding, bridge variants, and test infrastructure into separate pull requests linked to their respective issues or limit this PR to the ERC20Crosschain extension to maintain clear scope alignment.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately highlights the core addition of an ERC-7786 based cross-chain bridge for ERC-20 tokens, which is the principal focus of the changeset.
Linked Issues Check	✅ Passed	The pull request introduces the ERC20Crosschain extension that implements the ERC-7786 bridgable ERC-20 functionality via crosschainTransferFrom with burn/mint locking, directly satisfying the primary requirement of issue #5900.
Description check	✅ Passed	The PR description is related to the changeset, referencing issue #5900 and PR #5904, with a checklist indicating completed tests, coverage, and documentation.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

sourcery-ai · 2025-09-04T08:39:05Z

Reviewer's Guide

This PR introduces a generic ERC-7786 cross-chain messaging framework and builds upon it to implement ERC20 bridging (custodial, bridgeable, and integrated token variants), accompanied by mocks, utilities, and extensive tests, along with minor helper and interface refinements.

File-Level Changes

Change	Details	Files
Add core ERC-7786 cross-chain messaging framework	Implement BridgeCore with link registry, message sending, and gateway validation Implement ERC7786Recipient with receiveMessage entrypoint and replay protection	`contracts/crosschain/bridges/BridgeCore.sol` `contracts/crosschain/ERC7786Recipient.sol`
Implement ERC20 cross-chain bridge layer	Add BridgeERC20 base contract for message encoding and transfer events Provide BridgeERC20Custodial and BridgeERC20Bridgeable implementations for lock/unlock semantics Add ERC20Crosschain token extension for integrated burn/mint support	`contracts/crosschain/bridges/BridgeERC20.sol` `contracts/crosschain/bridges/BridgeERC20Custodial.sol` `contracts/crosschain/bridges/BridgeERC20Bridgeable.sol` `contracts/token/ERC20/extensions/ERC20Crosschain.sol`
Add mocks and update helpers for cross-chain testing	Implement ERC7786GatewayMock and ERC7786RecipientMock for messaging simulation Extend ERC20BridgeableMock with dynamic bridge setter Update account helper to resolve .target addresses for impersonation	`contracts/mocks/crosschain/ERC7786GatewayMock.sol` `contracts/mocks/crosschain/ERC7786RecipientMock.sol` `contracts/mocks/token/ERC20BridgeableMock.sol` `test/helpers/account.js`
Add comprehensive cross-chain bridging test suites	Behavioral and integration tests for BridgeERC20 under various custody models Tests for ERC7786Recipient receive logic and replay protection Integration tests for ERC20Crosschain extension	`test/crosschain/BridgeERC20.behavior.js` `test/crosschain/BridgeERC20.test.js` `test/crosschain/ERC7786Recipient.test.js` `test/token/ERC20/extensions/ERC20Crosschain.test.js`
Refine ERC-7786 interface naming	Rename event parameter 'receiver' to 'recipient' Rename interface from IERC7786Receiver to IERC7786Recipient	`contracts/interfaces/draft-IERC7786.sol`
Add change log and crosschain README stub	Add .changeset entry for release notes Create README.adoc stub for cross-chain module	`.changeset/silent-zebras-press.md` `contracts/crosschain/README.adoc`

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#5900	Implement an ERC7786 Bridgable ERC20 extension, enabling ERC20 tokens to be bridged across chains using the ERC-7786 standard.	✅
#5900	Provide code and tests for the ERC7786 Bridgable ERC20 extension, including core bridge logic, recipient logic, and integration with ERC20 tokens.	✅
#5900	Add documentation and a changeset entry for the new ERC7786 Bridgable ERC20 extension.	❌	The PR includes a changeset entry for ERC7786Recipient, but does not provide documentation for the new extension (the contracts/crosschain/README.adoc file is missing or empty).

Possibly linked issues

Add ERC7786 Bridgable ERC20 extension #5900: The PR implements the ERC-7786 cross-chain messaging and ERC20 bridging features outlined in issue Add ERC7786 Bridgable ERC20 extension #5900.
Migrate ERC7786Recipient from community #5904: PR implements the ERC7786 Bridgable ERC20 extension by adding new cross-chain bridging contracts and updating the ERC7786 interface.

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

Co-authored-by: James Toussaint <33313130+james-toussaint@users.noreply.github.com>

Co-authored-by: Eric Lau <ericglau@outlook.com>

Co-authored-by: Eric Lau <ericglau@outlook.com> Co-authored-by: James Toussaint <33313130+james-toussaint@users.noreply.github.com>

Amxx and others added 19 commits August 28, 2025 16:34

Migrate ERC7786Receiver from community

4a33948

add documentation

fdb2e77

Apply suggestion from @ernestognw

3651638

Update .changeset/silent-zebras-press.md

f2abf9f

Co-authored-by: Ernesto García <ernestognw@gmail.com>

Apply suggestions from code review

ab9643f

Co-authored-by: Ernesto García <ernestognw@gmail.com>

rename ERC7786Receiver into ERC7786Recipient

d3e2223

Update .changeset/silent-zebras-press.md

9b015d3

Add CrosschainBridgeERC20, CrosschainBridgeERC20Custodial, Crosschain…

b486a81

…BridgeERC20Bridgeable and ERC20Crosschain

refactor bridges

50be369

comments

4cf52d0

remove the "with attributes" variant of crosschainTransfer + testing

bd4095c

update Bridge: use chain specific gateway

e6e5d79

refactor permission

c0c421c

Merge branch 'crosschain/erc7786receiver' into crosschain/erc20bridge

a051b91

calldata

c938d68

Merge branch 'crosschain/erc7786receiver' into crosschain/erc20bridge

69d43a7

prevent message replay at the receiver level

d39c18e

Merge branch 'crosschain/erc7786receiver' into crosschain/erc20bridge

3cc4acf

update to match new ERC7786Recipient

610362d

Amxx changed the title ~~Crosschain/erc20bridge~~ [On hold] ERC-7786 based crosschain bridge for ERC-20 tokens Sep 9, 2025

Amxx commented Sep 9, 2025

View reviewed changes

Comment thread contracts/crosschain/bridges/BridgeCore.sol Outdated

Update contracts/crosschain/bridges/BridgeCore.sol

e0a3fd0

Amxx changed the title ~~[On hold] ERC-7786 based crosschain bridge for ERC-20 tokens~~ ERC-7786 based crosschain bridge for ERC-20 tokens Sep 30, 2025

Amxx added this to the 5.6 milestone Sep 30, 2025

Merge branch 'master' into crosschain/erc20bridge

434ee70

Amxx marked this pull request as ready for review September 30, 2025 15:13

Amxx requested a review from a team as a code owner September 30, 2025 15:13

frangio previously approved these changes Nov 7, 2025

View reviewed changes

james-toussaint reviewed Nov 7, 2025

View reviewed changes

Comment thread contracts/crosschain/CrosschainLinks.sol Outdated

Comment thread contracts/crosschain/CrosschainLinks.sol Outdated

Update contracts/crosschain/CrosschainLinks.sol

771068d

Co-authored-by: James Toussaint <33313130+james-toussaint@users.noreply.github.com>

Amxx dismissed frangio’s stale review via 771068d November 10, 2025 08:49

Amxx added 2 commits November 25, 2025 17:29

Rename CrosschainLinks -> CrosschainLinked

3c922a3

move file to finish renaming

ff790ef

ericglau reviewed Nov 25, 2025

View reviewed changes

Comment thread contracts/crosschain/bridges/BridgeERC20Core.sol Outdated

Apply suggestions from code review

63ef13b

Co-authored-by: Eric Lau <ericglau@outlook.com>

Amxx added the area: crosschain label Nov 26, 2025

Amxx requested review from ericglau, ernestognw, frangio and james-toussaint November 26, 2025 15:50

Amxx commented Nov 26, 2025

View reviewed changes

Comment thread contracts/crosschain/bridges/BridgeERC20Core.sol Outdated

james-toussaint previously approved these changes Nov 27, 2025

View reviewed changes

Comment thread contracts/crosschain/bridges/BridgeERC20Core.sol Outdated

Comment thread contracts/token/ERC20/extensions/ERC20Crosschain.sol Outdated

ericglau reviewed Nov 27, 2025

View reviewed changes

Comment thread contracts/crosschain/CrosschainLinked.sol Outdated

Comment thread contracts/crosschain/README.adoc Outdated

Comment thread contracts/token/ERC20/extensions/ERC20Crosschain.sol Outdated

rename events

fc0066e

Amxx dismissed james-toussaint’s stale review via fc0066e November 27, 2025 16:51

Amxx and others added 3 commits November 27, 2025 17:52

Update contracts/crosschain/CrosschainLinked.sol

123eb19

Co-authored-by: Eric Lau <ericglau@outlook.com>

Update contracts/crosschain/README.adoc

b5331da

Co-authored-by: Eric Lau <ericglau@outlook.com>

Apply suggestions from code review

941db67

Co-authored-by: Eric Lau <ericglau@outlook.com> Co-authored-by: James Toussaint <33313130+james-toussaint@users.noreply.github.com>

Amxx requested review from ericglau and james-toussaint November 27, 2025 16:55

ericglau approved these changes Nov 27, 2025

View reviewed changes

james-toussaint approved these changes Dec 1, 2025

View reviewed changes

Amxx merged commit bacb570 into OpenZeppelin:master Dec 1, 2025
21 checks passed

Amxx deleted the crosschain/erc20bridge branch December 1, 2025 15:12

ericglau mentioned this pull request Dec 1, 2025

Add ERC-20 option for embedding ERC-7786 based crosschain bridge, use Contracts 5.6.0 OpenZeppelin/contracts-wizard#747

Merged

Amxx mentioned this pull request Jan 5, 2026

ERC-7786 based crosschain bridge for ERC-721 tokens #6259

Merged

3 tasks

Uh oh!

Conversation

Amxx commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Uh oh!

changeset-bot Bot commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Possibly related PRs

Suggested labels

Pre-merge checks and finishing touches

Uh oh!

sourcery-ai Bot commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

File-Level Changes

Assessment against linked issues

Possibly linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Amxx commented Sep 4, 2025 •

edited

Loading

changeset-bot Bot commented Sep 4, 2025 •

edited

Loading

coderabbitai Bot commented Sep 4, 2025 •

edited

Loading

sourcery-ai Bot commented Sep 4, 2025 •

edited

Loading