[Feature]: ERC721Wrapper extension

Cargo.toml

@@ -11,6 +11,7 @@ members = [
   "examples/erc721",
   "examples/erc721-consecutive",
   "examples/erc721-metadata",
+  "examples/erc721-wrapper",
   "examples/erc1155",
   "examples/erc1155-metadata-uri",
   "examples/erc1155-supply",
@@ -38,6 +39,7 @@ default-members = [
   "examples/erc721",
   "examples/erc721-consecutive",
   "examples/erc721-metadata",
+  "examples/erc721-wrapper",
   "examples/erc1155",
   "examples/erc1155-metadata-uri",
   "examples/erc1155-supply",

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

@@ -4,8 +4,10 @@ pub mod consecutive;
 pub mod enumerable;
 pub mod metadata;
 pub mod uri_storage;
+pub mod wrapper;
 
 pub use burnable::IErc721Burnable;
 pub use enumerable::{Erc721Enumerable, IErc721Enumerable};
 pub use metadata::{Erc721Metadata, IErc721Metadata};
 pub use uri_storage::Erc721UriStorage;
+pub use wrapper::Erc721Wrapper;

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

@@ -0,0 +1,213 @@
+//! Extension of the ERC-721 token contract to support token wrapping.
+//!
+//! Users can deposit and withdraw an "underlying token" and receive a "wrapped
+//! token" with a matching tokenId. This is useful in conjunction with other
+//! modules.
+use alloc::{vec, vec::Vec};
+
+use alloy_primitives::{Address, U256};
+use stylus_sdk::{
+    abi::Bytes,
+    call::Call,
+    contract, msg,
+    prelude::storage,
+    storage::{StorageAddress, TopLevelStorage},
+    stylus_proc::SolidityError,
+};
+
+use crate::token::erc721::{
+    self, Erc721, IErc721 as IErc721Solidity, RECEIVER_FN_SELECTOR,
+};
+
+/// State of an [`Erc721Wrapper`] token.
+#[storage]
+pub struct Erc721Wrapper {
+    /// Erc721 contract storage.
+    pub underlying_address: StorageAddress,
+    /// The ERC-721 token.
+    pub erc721: Erc721,
+}
+
+unsafe impl TopLevelStorage for Erc721Wrapper {}
+
+pub use sol::*;
+#[cfg_attr(coverage_nightly, coverage(off))]
+mod sol {
+    use alloy_sol_macro::sol;
+
+    sol! {
+        /// The received ERC-721 token couldn't be wrapped.
+        ///
+        /// * `token_id` - Token id as a number.
+        #[derive(Debug)]
+        #[allow(missing_docs)]
+        error ERC721UnsupportedToken(uint256 token_id);
+
+        /// Indicates an error related to the ownership over a particular token.
+        /// Used in transfers.
+        ///
+        /// * `sender` - Address whose tokens are being transferred.
+        /// * `token_id` - Token id as a number.
+        /// * `owner` - Address of the owner of the token.
+        #[derive(Debug)]
+        #[allow(missing_docs)]
+        error ERC721IncorrectOwner(address sender, uint256 token_id, address owner);
+    }
+}
+
+/// An [`Erc721Wrapper`] error.
+#[derive(SolidityError, Debug)]
+pub enum Error {
+    /// Error type from [`Erc721`] contract [`erc721::Error`].
+    Erc721(erc721::Error),
+    /// The received ERC-721 token couldn't be wrapped.
+    UnsupportedToken(ERC721UnsupportedToken),
+    /// Indicates an error related to the ownership over a particular token.
+    IncorrectOwner(ERC721IncorrectOwner),
+}
+
+pub use token::IErc721;
+mod token {
+    #![allow(missing_docs)]
+    #![cfg_attr(coverage_nightly, coverage(off))]
+    use alloc::vec;
+
+    stylus_sdk::stylus_proc::sol_interface! {
+        /// Interface of the ERC-721 token.
+        interface IErc721 {
+            function ownerOf(uint256 token_id) external view returns (address);
+        }
+    }
+}
+
+impl Erc721Wrapper {
+    /// Allow a user to deposit underlying tokens and mint the corresponding
+    /// tokenIds.
+    ///
+    /// Arguments:
+    ///
+    /// * `account` - The account to deposit tokens to.
+    /// * `token_ids` - The tokenIds of the underlying tokens to deposit.
+    /// * `erc721` - A mutable reference to the Erc721 contract.
+    pub fn deposit_for(
+        &mut self,
+        account: Address,
+        token_ids: Vec<U256>,
+        erc721: &mut Erc721,
+    ) -> Result<bool, Error> {
+        let sender = msg::sender();
+
+        token_ids.iter().for_each(|&token_id| {
+            self.erc721
+                .transfer_from(sender, contract::address(), token_id)
+                .expect("transfer failed");
+            erc721
+                ._safe_mint(account, token_id, &vec![].into())
+                .expect("mint failed");
+        });
+
+        Ok(true)
+    }
+
+    /// Allow a user to burn wrapped tokens and withdraw the corresponding
+    /// tokenIds of the underlying tokens.
+    ///
+    /// Arguments:
+    ///
+    /// * `account` - The account to withdraw tokens to.
+    /// * `token_ids` - The tokenIds of the underlying tokens to withdraw.
+    /// * `erc721` - A mutable reference to the Erc721 contract.
+    pub fn withdraw_to(
+        &mut self,
+        account: Address,
+        token_ids: Vec<U256>,
+        erc721: &mut Erc721,
+    ) -> Result<bool, Error> {
+        let sender = msg::sender();
+
+        token_ids.iter().for_each(|&token_id| {
+            erc721
+                ._update(Address::ZERO, token_id, sender)
+                .expect("update failed");
+            self.erc721
+                .safe_transfer_from(contract::address(), account, token_id)
+                .expect("transfer failed");
+        });
+
+        Ok(true)
+    }
+
+    /// Overrides [`erc721::IERC721Receiver::on_erc_721_received`] to allow
+    /// minting on direct ERC-721 transfers to this contract.
+    pub fn on_erc721_received(
+        &mut self,
+        operator: Address,
+        from: Address,
+        token_id: U256,
+        data: Bytes,
+    ) -> Result<(), Error> {
+        let sender = msg::sender();
+
+        if self.underlying() != sender {
+            return Err(Error::UnsupportedToken(ERC721UnsupportedToken {
+                token_id,
+            }));
+        }
+
+        self.erc721._safe_mint(from, token_id, &data)?;
+        // RECEIVER_FN_SELECTOR
+        Ok(())
+    }
+
+    /// Returns the underlying token.
+    pub fn underlying(&self) -> Address {
+        self.underlying_address.get()
+    }
+}
+
+// ************** ERC-721 Internal **************
+
+impl Erc721Wrapper {
+    /// Mints wrapped tokens to cover any underlying tokens that would have been
+    /// function taht can be exposed with access control if desired.
+    ///
+    /// Arguments:
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `account` - The account to mint tokens to.
+    /// * `token_id` - A mutable reference to the Erc20 contract.
+    ///
+    /// # Errors
+    ///
+    /// If the underlying token is not owned by the contract, the error
+    /// [`Error::`] is returned.
+    fn _recover(
+        &mut self,
+        account: Address,
+        token_id: U256,
+    ) -> Result<U256, Error> {
+        let underlying = IErc721::new(self.underlying());
+        let owner = match underlying.owner_of(Call::new_in(self), token_id) {
+            Ok(owner) => owner,
+            Err(e) => return Err(Error::Erc721(e.into())),
+        };
+        if owner != contract::address() {
+            return Err(Error::IncorrectOwner(ERC721IncorrectOwner {
+                sender: contract::address(),
+                token_id,
+                owner,
+            }));
+        }
+        self.erc721._safe_mint(account, token_id, &vec![].into())?;
+        Ok(token_id)
+    }
+}
+
+#[cfg(all(test, feature = "std"))]
+mod tests {
+    use alloy_primitives::{address, uint, Address, U256};
+    use stylus_sdk::msg;
+
+    #[motsu::test]
+    fn recover(contract: Erc721Wrapper) {}
+}

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

@@ -0,0 +1 @@
+= ERC-721 Wrapper

docs/modules/ROOT/pages/erc721.adoc

@@ -74,3 +74,5 @@ Additionally, there are multiple custom extensions, including:
 * xref:erc721-pausable.adoc[ERC-721 Pausable]: A primitive to pause contract operation.
 
 * xref:erc721-uri-storage.adoc[ERC-721 Uri Storage]: A more flexible but more expensive way of storing metadata.
+
+* xref:erc721-wrapper.adoc[ERC-721 Wrapper]: Wrapper to create an ERC-721 backed by another ERC-721, with deposit and withdraw methods. 

examples/erc721-wrapper/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "erc721-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"]

examples/erc721-wrapper/src/constructor.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.21;
+
+contract Erc721WrapperExample {
+    mapping(address account => uint256) private _balances;
+    mapping(address account => mapping(address spender => uint256))
+        private _allowances;
+    uint256 private _totalSupply;
+
+    address private _underlyingToken;
+
+    constructor(address underlyingToken_) {
+        _underlyingToken = underlyingToken_;
+    }
+}

examples/erc721-wrapper/src/lib.rs

@@ -0,0 +1,39 @@
+#![cfg_attr(not(test), no_main)]
+extern crate alloc;
+
+use alloy_primitives::{Address, U256};
+use openzeppelin_stylus::token::erc721::{extensions::Erc721Wrapper, Erc721};
+use stylus_sdk::prelude::{entrypoint, public, storage};
+
+#[entrypoint]
+#[storage]
+struct Erc721WrapperExample {
+    #[borrow]
+    pub erc721: Erc721,
+    #[borrow]
+    pub wrapper: Erc721Wrapper,
+}
+
+#[public]
+#[inherit(Erc721)]
+impl Erc721WrapperExample {
+    fn underlying(&self) -> Address {
+        self.wrapper.underlying()
+    }
+
+    fn deposit_for(
+        &mut self,
+        account: Address,
+        values: Vec<U256>,
+    ) -> Result<bool, Vec<u8>> {
+        Ok(self.wrapper.deposit_for(account, values, &mut self.erc721)?)
+    }
+
+    fn withdraw_to(
+        &mut self,
+        account: Address,
+        values: Vec<U256>,
+    ) -> Result<bool, Vec<u8>> {
+        Ok(self.wrapper.withdraw_to(account, values, &mut self.erc721)?)
+    }
+}

examples/erc721-wrapper/tests/abi/mod.rs

@@ -0,0 +1,39 @@
+#![allow(dead_code)]
+use alloy::sol;
+
+sol!(
+    #[sol(rpc)]
+    contract Erc20Wrapper {
+        function name() external view returns (string name);
+        function symbol() external view returns (string symbol);
+        function totalSupply() external view returns (uint256 totalSupply);
+        function balanceOf(address account) external view returns (uint256 balance);
+        function transfer(address recipient, uint256 amount) external returns (bool);
+        function allowance(address owner, address spender) external view returns (uint256 allowance);
+        function approve(address spender, uint256 amount) external returns (bool);
+        function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
+
+        #[derive(Debug)]
+        function decimals() external view returns (uint8 decimals);
+        #[derive(Debug)]
+        function underlying() external view returns (address underlying);
+        #[derive(Debug)]
+        function depositFor(address account, uint256 value) external  returns (bool);
+        #[derive(Debug)]
+        function withdrawTo(address account, uint256 value) external  returns (bool);
+
+        error ERC721InvalidOwner(address owner);
+        error ERC721NonexistentToken(uint256 tokenId);
+        error ERC721IncorrectOwner(address sender, uint256 tokenId, address owner);
+        error ERC721InvalidSender(address sender);
+        error ERC721InvalidReceiver(address receiver);
+        error ERC721InsufficientApproval(address operator, uint256 tokenId);
+        error ERC721InvalidApprover(address approver);
+        error ERC721InvalidOperator(address operator);
+
+        #[derive(Debug, PartialEq)]
+        event Transfer(address indexed from, address indexed to, uint256 value);
+        #[derive(Debug, PartialEq)]
+        event Approval(address indexed owner, address indexed spender, uint256 value);
+    }
+);