feat: Erc20Wrapper extension

CHANGELOG.md

@@ -5,12 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
 ## [Unreleased]
 
 ### Added
 
 - Implement `AddAssignChecked` for `StorageUint`. #474
 - `Erc20FlashMint` extension. #407
+- `Erc20Wrapper` "Token Wrapping contract". #498
 
 ### Changed
 

Cargo.toml

@@ -8,6 +8,7 @@ members = [
   "examples/erc20",
   "examples/erc20-permit",
   "examples/erc20-flash-mint",
+  "examples/erc20-wrapper",
   "examples/erc721",
   "examples/erc721-consecutive",
   "examples/erc721-metadata",
@@ -34,6 +35,7 @@ default-members = [
   "examples/erc20",
   "examples/erc20-permit",
   "examples/erc20-flash-mint",
+  "examples/erc20-wrapper",
   "examples/erc721",
   "examples/erc721-consecutive",
   "examples/erc721-metadata",

contracts/src/token/erc20/extensions/mod.rs

@@ -4,9 +4,11 @@ pub mod capped;
 pub mod flash_mint;
 pub mod metadata;
 pub mod permit;
+pub mod wrapper;
 
 pub use burnable::IErc20Burnable;
 pub use capped::Capped;
 pub use flash_mint::{Erc20FlashMint, IErc3156FlashLender};
 pub use metadata::{Erc20Metadata, IErc20Metadata};
 pub use permit::Erc20Permit;
+pub use wrapper::{Erc20Wrapper, IERC20Wrapper};

contracts/src/token/erc20/extensions/wrapper.rs

@@ -0,0 +1,232 @@
+//! Extension of the ERC-20 token contract to support token wrapping.
+//!
+//! Users can deposit and withdraw "underlying tokens" and receive a matching
+//! number of "wrapped tokens". This is useful in conjunction with other
+//! modules. For example, combining this wrapping mechanism with {ERC20Votes}
+//! will allow the wrapping of an existing "basic" ERC-20 into a governance
+//! token.
+//!
+//! WARNING: Any mechanism in which the underlying token changes the {balanceOf}
+//! of an account without an explicit transfer may desynchronize this contract's
+//! supply and its underlying balance. Please exercise caution when wrapping
+//! tokens that may undercollateralize the wrapper (i.e. wrapper's total supply
+//! is higher than its underlying balance). See {_recover} for recovering value
+//! accrued to the wrapper.
+
+use alloy_primitives::{Address, U256};
+use alloy_sol_macro::sol;
+use stylus_sdk::{
+    call::Call,
+    contract, msg,
+    prelude::storage,
+    storage::{StorageAddress, TopLevelStorage},
+    stylus_proc::SolidityError,
+};
+
+use crate::token::erc20::{
+    self,
+    utils::{
+        safe_erc20::{self, ISafeErc20},
+        SafeErc20,
+    },
+    Erc20,
+};
+
+mod token {
+
+    #![allow(missing_docs)]
+    #![cfg_attr(coverage_nightly, coverage(off))]
+
+    use alloc::vec;
+
+    use stylus_sdk::stylus_proc::sol_interface;
+
+    sol_interface! {
+        /// Solidity Interface of the ERC-20 token.
+        interface IErc20 {
+            function balanceOf(address account) external view returns (uint256);
+            function totalSupply() external view returns (uint256);
+        }
+    }
+}
+
+use token::IErc20 as IErc20Solidity;
+
+sol! {
+    #[derive(Debug)]
+    #[allow(missing_docs)]
+    error ERC20InvalidUnderlying(address token);
+
+    #[derive(Debug)]
+    #[allow(missing_docs)]
+    error ERC20InvalidSender(address sender);
+
+    /// The address is not a valid ERC-20 token.
+    ///
+    /// * `asset` - Address of the invalid ERC-20 token.
+    #[derive(Debug)]
+    #[allow(missing_docs)]
+    error InvalidAsset(address asset);
+
+    #[derive(Debug)]
+    #[allow(missing_docs)]
+    error ERC20InvalidReceiver(address receiver);
+
+}
+
+/// An [`Erc20Wrapper`] error.
+#[derive(SolidityError, Debug)]
+pub enum Error {
+    /// Error type from [`SafeErc20`] contract [`safe_erc20::Error`].
+    SafeErc20(safe_erc20::Error),
+
+    /// The Sender Address is not valid.
+    InvalidSender(ERC20InvalidSender),
+
+    /// The Reciver Address is not valid.
+    InvalidReceiver(ERC20InvalidReceiver),
+
+    /// The underlying token couldn't be wrapped.
+    InvalidUnderlying(ERC20InvalidUnderlying),
+
+    /// The address is not a valid ERC-20 token.
+    InvalidAsset(InvalidAsset),
+
+    /// Error type from [`Erc20`] contract [`erc20::Error`].
+    Erc20(erc20::Error),
+}
+/// State of an [`Erc20Wrapper`] token.
+#[storage]
+pub struct Erc20Wrapper {
+    /// Token Address of the  underline token
+    #[allow(clippy::used_underscore_binding)]
+    pub(crate) _underlying: StorageAddress,
+
+    /// [`SafeErc20`] contract
+    safe_erc20: SafeErc20,
+}
+
+/// ERC-4626 Tokenized Vault Standard Interface
+pub trait IERC20Wrapper {
+    /// The error type associated to this ERC20Wrapper trait implementation.
+    type Error: Into<alloc::vec::Vec<u8>>;
+
+    /// Returns the address of the underlying token that is been wrapped.
+    fn underlying(&self) -> Address;
+
+    /// Allow a user to deposit underlying tokens and mint the corresponding
+    /// number of wrapped token
+    ///
+    /// Arguments:
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `account` - The account to deposit tokens to.
+    /// * `value` - The amount of tokens to deposit.
+    fn deposit_to(
+        &mut self,
+        account: Address,
+        value: U256,
+        erc20: &mut Erc20,
+    ) -> Result<bool, Self::Error>;
+
+    /// Allow a user to burn a number of wrapped tokens and withdraw the
+    /// corresponding number of underlying tokens.
+    ///
+    /// Arguments:
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `account` - The account to withdraw tokens to.
+    /// * `value` - The amount of tokens to withdraw.
+    /// * `erc20` - A mutable reference to the Erc20 contract.
+    fn withdraw_to(
+        &mut self,
+        account: Address,
+        value: U256,
+        erc20: &mut Erc20,
+    ) -> Result<bool, Self::Error>;
+}
+
+/// NOTE: Implementation of [`TopLevelStorage`] to be able use `&mut self` when
+/// calling other contracts and not `&mut (impl TopLevelStorage +
+/// BorrowMut<Self>)`. Should be fixed in the future by the Stylus team.
+unsafe impl TopLevelStorage for Erc20Wrapper {}
+
+impl IERC20Wrapper for Erc20Wrapper {
+    type Error = Error;
+
+    fn underlying(&self) -> Address {
+        self._underlying.get()
+    }
+
+    fn deposit_to(
+        &mut self,
+        account: Address,
+        value: U256,
+        erc20: &mut Erc20,
+    ) -> Result<bool, Error> {
+        let underlined_token = self._underlying.get();
+        let sender = msg::sender();
+        if account == contract::address() {
+            return Err(Error::InvalidUnderlying(ERC20InvalidUnderlying {
+                token: contract::address(),
+            }));
+        }
+
+        if sender == contract::address() {
+            return Err(Error::InvalidUnderlying(ERC20InvalidUnderlying {
+                token: account,
+            }));
+        }
+        self.safe_erc20.safe_transfer_from(
+            underlined_token,
+            sender,
+            contract::address(),
+            value,
+        )?;
+        erc20._mint(account, value)?;
+        Ok(true)
+    }
+
+    fn withdraw_to(
+        &mut self,
+        account: Address,
+        value: U256,
+        erc20: &mut Erc20,
+    ) -> Result<bool, Error> {
+        let underlined_token = self._underlying.get();
+        if account == contract::address() {
+            return Err(Error::InvalidUnderlying(ERC20InvalidUnderlying {
+                token: contract::address(),
+            }));
+        }
+        erc20._burn(account, value)?;
+        self.safe_erc20.safe_transfer(underlined_token, account, value)?;
+        Ok(true)
+    }
+}
+
+impl Erc20Wrapper {
+    /// Mints wrapped tokens to cover any underlying tokens that might have been
+    /// mistakenly transferred or acquired through rebasing mechanisms.
+    ///
+    /// This is an internal function that can be exposed with access control if
+    /// required.
+    ///
+    /// Arguments:
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `account` - The account to mint tokens to.
+    /// * `erc20` - A mutable reference to the Erc20 contract.
+    pub fn _recover(
+        &mut self,
+        account: Address,
+        erc20: &mut Erc20,
+    ) -> Result<U256, Error> {
+        let token = IErc20Solidity::new(self.underlying());
+        let value = token
+            .balance_of(Call::new_in(self), contract::address())
+            .map_err(|_| InvalidAsset { asset: contract::address() })?;
+        erc20._mint(account, value)?;
+        Ok(U256::from(value))
+    }
+}

docs/modules/ROOT/pages/erc20-wrapper.adoc

@@ -0,0 +1,57 @@
+= ERC-20 Wrapper
+
+Extension of the ERC-20 token contract to support token wrapping.
+
+Users can deposit and withdraw "underlying tokens" and receive a matching number of "wrapped tokens". 
+This is useful in conjunction with other modules. 
+
+
+[[usage]]
+== Usage
+
+In order to make your ERC20 `wrapped token`:
+
+[source,rust]
+----
+use alloy_primitives::{Address, U256};
+use openzeppelin_stylus::token::erc20::{
+    extensions::{Erc20Metadata, Erc20Wrapper, IERC20Wrapper},
+    Erc20,
+};
+use stylus_sdk::prelude::{entrypoint, public, storage};
+
+#[entrypoint]
+#[storage]
+struct Erc20WrapperExample {
+    #[borrow]
+    pub erc20: Erc20,
+    #[borrow]
+    pub metadata: Erc20Metadata,
+    #[borrow]
+    pub wrapper: Erc20Wrapper,
+}
+
+#[public]
+#[inherit(Erc20, Erc20Metadata)]
+impl Erc20WrapperExample {
+    fn underlying(&self) -> Address {
+        self.wrapper.underlying()
+    }
+
+    fn deposit_to(
+        &mut self,
+        account: Address,
+        value: U256,
+    ) -> Result<bool, Vec<u8>> {
+        Ok(self.wrapper.deposit_to(account, value, &mut self.erc20)?)
+    }
+
+    fn withdraw_to(
+        &mut self,
+        account: Address,
+        value: U256,
+    ) -> Result<bool, Vec<u8>> {
+        Ok(self.wrapper.withdraw_to(account, value, &mut self.erc20)?)
+    }
+}
+----

docs/modules/ROOT/pages/erc20.adoc

@@ -84,3 +84,5 @@ Additionally, there are multiple custom extensions, including:
  * xref:erc20-permit.adoc[ERC-20 Permit]: gasless approval of tokens (standardized as https://eips.ethereum.org/EIPS/eip-2612[`EIP-2612`]).
 
  * xref:erc20-flash-mint.adoc[ERC-20 Flash-Mint]: token level support for flash loans through the minting and burning of ephemeral tokens (standardized as https://eips.ethereum.org/EIPS/eip-3156[`EIP-3156`]).
+
+ * xref:erc20-wrapper.adoc[ERC-20 Wrapper]: Extension of the ERC-20 token contract to support token wrapping .

examples/erc20-wrapper/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "erc20-wrapper"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+version.workspace = true
+
+[dependencies]
+openzeppelin-stylus.workspace = true
+alloy-primitives.workspace = true
+stylus-sdk.workspace = true
+
+[dev-dependencies]
+alloy.workspace = true
+eyre.workspace = true
+tokio.workspace = true
+e2e.workspace = true
+
+[features]
+e2e = []
+
+[lib]
+crate-type = ["lib", "cdylib"]