From 5c79432e4091c20fa5ea057261f0bf528ea70a7c Mon Sep 17 00:00:00 2001 From: Hadrien Croubois Date: Thu, 12 Jun 2025 02:19:56 +0200 Subject: [PATCH] ERC20Bridgable (ERC-7802) (#5735) Co-authored-by: ernestognw Co-authored-by: Arr00 <13561405+arr00@users.noreply.github.com> --- .changeset/ripe-bears-hide.md | 5 ++ contracts/interfaces/README.adoc | 3 + contracts/interfaces/draft-IERC7802.sol | 30 +++++++ contracts/mocks/token/ERC20BridgeableMock.sol | 26 ++++++ contracts/token/ERC20/README.adoc | 3 + .../extensions/draft-ERC20Bridgeable.sol | 50 +++++++++++ .../extensions/draft-ERC20Bridgeable.test.js | 89 +++++++++++++++++++ 7 files changed, 206 insertions(+) create mode 100644 .changeset/ripe-bears-hide.md create mode 100644 contracts/interfaces/draft-IERC7802.sol create mode 100644 contracts/mocks/token/ERC20BridgeableMock.sol create mode 100644 contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol create mode 100644 test/token/ERC20/extensions/draft-ERC20Bridgeable.test.js diff --git a/.changeset/ripe-bears-hide.md b/.changeset/ripe-bears-hide.md new file mode 100644 index 000000000..7fa165492 --- /dev/null +++ b/.changeset/ripe-bears-hide.md @@ -0,0 +1,5 @@ +--- +'openzeppelin-solidity': minor +--- + +`ERC20Bridgeable`: Implementation of ERC-7802 that makes an ERC-20 compatible with crosschain bridges. diff --git a/contracts/interfaces/README.adoc b/contracts/interfaces/README.adoc index 703cd15b5..9cb4d9a24 100644 --- a/contracts/interfaces/README.adoc +++ b/contracts/interfaces/README.adoc @@ -45,6 +45,7 @@ are useful to interact with third party contracts that implement them. - {IERC6909Metadata} - {IERC6909TokenSupply} - {IERC7674} +- {IERC7802} == Detailed ABI @@ -97,3 +98,5 @@ are useful to interact with third party contracts that implement them. {{IERC6909TokenSupply}} {{IERC7674}} + +{{IERC7802}} diff --git a/contracts/interfaces/draft-IERC7802.sol b/contracts/interfaces/draft-IERC7802.sol new file mode 100644 index 000000000..b0ad767e4 --- /dev/null +++ b/contracts/interfaces/draft-IERC7802.sol @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: MIT +pragma solidity >=0.6.2; + +import {IERC165} from "./IERC165.sol"; + +/// @title IERC7802 +/// @notice Defines the interface for crosschain ERC20 transfers. +interface IERC7802 is IERC165 { + /// @notice Emitted when a crosschain transfer mints tokens. + /// @param to Address of the account tokens are being minted for. + /// @param amount Amount of tokens minted. + /// @param sender Address of the caller (msg.sender) who invoked crosschainMint. + event CrosschainMint(address indexed to, uint256 amount, address indexed sender); + + /// @notice Emitted when a crosschain transfer burns tokens. + /// @param from Address of the account tokens are being burned from. + /// @param amount Amount of tokens burned. + /// @param sender Address of the caller (msg.sender) who invoked crosschainBurn. + event CrosschainBurn(address indexed from, uint256 amount, address indexed sender); + + /// @notice Mint tokens through a crosschain transfer. + /// @param _to Address to mint tokens to. + /// @param _amount Amount of tokens to mint. + function crosschainMint(address _to, uint256 _amount) external; + + /// @notice Burn tokens through a crosschain transfer. + /// @param _from Address to burn tokens from. + /// @param _amount Amount of tokens to burn. + function crosschainBurn(address _from, uint256 _amount) external; +} diff --git a/contracts/mocks/token/ERC20BridgeableMock.sol b/contracts/mocks/token/ERC20BridgeableMock.sol new file mode 100644 index 000000000..6249cb668 --- /dev/null +++ b/contracts/mocks/token/ERC20BridgeableMock.sol @@ -0,0 +1,26 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20, ERC20Bridgeable} from "../../token/ERC20/extensions/draft-ERC20Bridgeable.sol"; + +abstract contract ERC20BridgeableMock is ERC20Bridgeable { + address private _bridge; + + error OnlyTokenBridge(); + event OnlyTokenBridgeFnCalled(address caller); + + constructor(address bridge) { + _bridge = bridge; + } + + function onlyTokenBridgeFn() external onlyTokenBridge { + emit OnlyTokenBridgeFnCalled(msg.sender); + } + + function _checkTokenBridge(address sender) internal view override { + if (sender != _bridge) { + revert OnlyTokenBridge(); + } + } +} diff --git a/contracts/token/ERC20/README.adoc b/contracts/token/ERC20/README.adoc index 1b4d31d2e..e7c981e23 100644 --- a/contracts/token/ERC20/README.adoc +++ b/contracts/token/ERC20/README.adoc @@ -16,6 +16,7 @@ There are a few core contracts that implement the behavior specified in the ERC- Additionally there are multiple custom extensions, including: * {ERC20Permit}: gasless approval of tokens (standardized as ERC-2612). +* {ERC20Bridgeable}: compatibility with crosschain bridges through ERC-7802. * {ERC20Burnable}: destruction of own tokens. * {ERC20Capped}: enforcement of a cap to the total supply when minting tokens. * {ERC20Pausable}: ability to pause token transfers. @@ -50,6 +51,8 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel {{ERC20Permit}} +{{ERC20Bridgeable}} + {{ERC20Burnable}} {{ERC20Capped}} diff --git a/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol b/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol new file mode 100644 index 000000000..411d5b007 --- /dev/null +++ b/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol @@ -0,0 +1,50 @@ +// SPDX-License-Identifier: MIT + +pragma solidity ^0.8.20; + +import {ERC20} from "../ERC20.sol"; +import {ERC165, IERC165} from "../../../utils/introspection/ERC165.sol"; +import {IERC7802} from "../../../interfaces/draft-IERC7802.sol"; + +/** + * @dev ERC20 extension that implements the standard token interface according to + * https://eips.ethereum.org/EIPS/eip-7802[ERC-7802]. + */ +abstract contract ERC20Bridgeable is ERC20, ERC165, IERC7802 { + /// @dev Modifier to restrict access to the token bridge. + modifier onlyTokenBridge() { + // Token bridge should never be impersonated using a relayer/forwarder. Using msg.sender is preferable to + // _msgSender() for security reasons. + _checkTokenBridge(msg.sender); + _; + } + + /// @inheritdoc ERC165 + function supportsInterface(bytes4 interfaceId) public view virtual override(ERC165, IERC165) returns (bool) { + return interfaceId == type(IERC7802).interfaceId || super.supportsInterface(interfaceId); + } + + /** + * @dev See {IERC7802-crosschainMint}. Emits a {IERC7802-CrosschainMint} event. + */ + function crosschainMint(address to, uint256 value) public virtual override onlyTokenBridge { + _mint(to, value); + emit CrosschainMint(to, value, _msgSender()); + } + + /** + * @dev See {IERC7802-crosschainBurn}. Emits a {IERC7802-CrosschainBurn} event. + */ + function crosschainBurn(address from, uint256 value) public virtual override onlyTokenBridge { + _burn(from, value); + emit CrosschainBurn(from, value, _msgSender()); + } + + /** + * @dev Checks if the caller is a trusted token bridge. MUST revert otherwise. + * + * Developers should implement this function using an access control mechanism that allows + * customizing the list of allowed senders. Consider using {AccessControl} or {AccessManaged}. + */ + function _checkTokenBridge(address caller) internal virtual; +} diff --git a/test/token/ERC20/extensions/draft-ERC20Bridgeable.test.js b/test/token/ERC20/extensions/draft-ERC20Bridgeable.test.js new file mode 100644 index 000000000..06c3bb290 --- /dev/null +++ b/test/token/ERC20/extensions/draft-ERC20Bridgeable.test.js @@ -0,0 +1,89 @@ +const { ethers } = require('hardhat'); +const { expect } = require('chai'); +const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers'); + +const { shouldBehaveLikeERC20 } = require('../ERC20.behavior.js'); +const { shouldSupportInterfaces } = require('../../../utils/introspection/SupportsInterface.behavior'); + +const name = 'My Token'; +const symbol = 'MTKN'; +const initialSupply = 100n; + +async function fixture() { + const [other, bridge, ...accounts] = await ethers.getSigners(); + + const token = await ethers.deployContract('$ERC20BridgeableMock', [name, symbol, bridge]); + await token.$_mint(accounts[0], initialSupply); + + return { bridge, other, accounts, token }; +} + +describe('ERC20Bridgeable', function () { + beforeEach(async function () { + Object.assign(this, await loadFixture(fixture)); + }); + + describe('onlyTokenBridgeFn', function () { + it('reverts when called by non-bridge', async function () { + await expect(this.token.onlyTokenBridgeFn()).to.be.revertedWithCustomError(this.token, 'OnlyTokenBridge'); + }); + + it('does not revert when called by bridge', async function () { + await expect(this.token.connect(this.bridge).onlyTokenBridgeFn()) + .to.emit(this.token, 'OnlyTokenBridgeFnCalled') + .withArgs(this.bridge); + }); + }); + + describe('crosschainMint', function () { + it('reverts when called by non-bridge', async function () { + await expect(this.token.crosschainMint(this.other, 100n)).to.be.revertedWithCustomError( + this.token, + 'OnlyTokenBridge', + ); + }); + + it('mints amount provided by the bridge when calling crosschainMint', async function () { + const amount = 100n; + await expect(this.token.connect(this.bridge).crosschainMint(this.other, amount)) + .to.emit(this.token, 'CrosschainMint') + .withArgs(this.other, amount, this.bridge) + .to.emit(this.token, 'Transfer') + .withArgs(ethers.ZeroAddress, this.other, amount); + + await expect(this.token.balanceOf(this.other)).to.eventually.equal(amount); + }); + }); + + describe('crosschainBurn', function () { + it('reverts when called by non-bridge', async function () { + await expect(this.token.crosschainBurn(this.other, 100n)).to.be.revertedWithCustomError( + this.token, + 'OnlyTokenBridge', + ); + }); + + it('burns amount provided by the bridge when calling crosschainBurn', async function () { + const amount = 100n; + await this.token.$_mint(this.other, amount); + + await expect(this.token.connect(this.bridge).crosschainBurn(this.other, amount)) + .to.emit(this.token, 'CrosschainBurn') + .withArgs(this.other, amount, this.bridge) + .to.emit(this.token, 'Transfer') + .withArgs(this.other, ethers.ZeroAddress, amount); + + await expect(this.token.balanceOf(this.other)).to.eventually.equal(0); + }); + }); + + describe('ERC165', function () { + shouldSupportInterfaces({ + ERC7802: ['crosschainMint(address,uint256)', 'crosschainBurn(address,uint256)'], + }); + }); + + describe('ERC20 behavior', function () { + shouldBehaveLikeERC20(initialSupply); + }); +});