ERC-7786 based crosschain bridge for ERC-20 tokens

[Amxx]

Based of #5904
Fixes #5900

PR Checklist

• Tests
• Coverage
• Documentation
• Changeset entry (run npx changeset add)

[changeset-bot]

🦋 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]

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]

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.

[Amxx]

Added changeset.

@frangio can you have a look ?

@ernestognw & @james-toussaint, if one of you could give this a review that would be great. If you trust @frangio 's technical expertise on the code, at least have a look at the documentation part!