feat: add ERC-6909 Token and Supply extension (#777)

<!--
Thank you for your interest in contributing to OpenZeppelin!

Consider opening an issue for discussion prior to submitting a PR. New
features will be merged faster if they were first discussed and designed
with the team.

Describe the changes introduced in this pull request. Include any
context necessary for understanding the PR's purpose.
-->

<!-- Fill in with issue number -->

#### PR Checklist

<!--
Before merging the pull request all of the following must be completed.
Feel free to submit a PR or Draft PR even if some items are pending.
Some of the items may not apply.
-->

- [x] Tests
- [x] Documentation
- [x] Changelog

# ERC6909 Implementation in rust-contracts-stylus

## Summary

This PR implements the
[ERC-6909](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.3.0/contracts/token/ERC6909/draft-ERC6909.sol)
token and [Supply
extension](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.3.0/contracts/token/ERC6909/extensions/draft-ERC6909TokenSupply.sol)
in Rust for Arbitrum Stylus.

The following implementation is provided in this PR:

- ERC-6909 + unit tests with motsu
- Supply Extension + unit tests with motsu
- Example usage of ERC-6909 and Supply Extension
- Integration Tests for ERC-6909 and Supply Extension
- Benchmark for both ERC6909 and Supply Extension

### Comments
Integration tests and the benchmarks inside
[rust-contracts-stylus](https://github.com/OpenZeppelin/rust-contracts-stylus),
which use
[nitro-testnode](https://github.com/OffchainLabs/nitro-testnode), didn't
work with the M3 Pro Chip (would be an issue related to Docker). To
solve the problem, firstly, [nitro-devnode] is tried to use. However, I
observed that it is not suitable for the `e2e::test` workflow. So, an
LTS Ubuntu machine is rented on AWS to run the integration tests and the
benchmark.

For the Supply Extension implementation, `Deref` traits are implemented.
Using `Deref` allows direct access to Erc6909 methods, improving
readability and maintainability. However, deferencing operations might
increase the gas. Designing Supply Token Extension in this way increases
the abstraction and makes it easy to use for users who would like to use
the Supply Extension with ERC-6909 Token Contract.

### Future Improvements

Currently, this PR does not include other ERC-6909 Extensions,
specifically ContentURI and Metadata. Their example usage and the
benchmarks should be added to the repository.

The unit tests that differentiate the `id` should be added.

### Benchmark

Benchmarks for ERC-6909 can be seen as follows:

```
| Contract::function                                                        | WASM Opt & Cached | Cached | Not Cached |
| ------------------------------------------------------------------------- | ----------------- | ------ | ---------- |
| Erc6909::mint(address,uint256,uint256)                                    |             27925 |  29307 |      45089 |
| Erc6909::balanceOf(address,uint256)                                       |              5101 |   6448 |      22230 |
| Erc6909::allowance(address,address,uint256)                               |              5875 |   7228 |      23010 |
| Erc6909::isOperator(address,address)                                      |              5322 |   6666 |      22448 |
| Erc6909::setOperator(address,bool)                                        |             27045 |  28433 |      44215 |
| Erc6909::transfer(address,uint256,uint256)                                |             34364 |  35786 |      51568 |
| Erc6909::approve(address,uint256,uint256)                                 |             27939 |  29332 |      45114 |
| Erc6909::transferFrom(address,address,uint256,uint256)                    |             20503 |  21943 |      37725 |
| Erc6909::burn(address,uint256,uint256)                                    |             11495 |  12893 |      28675 |

```

---------

Co-authored-by: Daniel Bigos <[email protected]>
Co-authored-by: Alisander Qoshqosh <[email protected]>
Co-authored-by: Daniel Bigos <[email protected]>
Co-authored-by: Nenad <[email protected]>

Author: 4 people

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Erc6909**: `Erc6909` contract and `Erc6909TokenSupply` extension. #777
+
 ### Changed (Breaking)
 
 - `IErc721Wrapper` returns `Vec<u8>` instead of typed `Error`. #822

Cargo.lock

@@ -22,6 +22,8 @@ members = [
   "examples/erc1155-metadata-uri",
   "examples/erc1155-supply",
   "examples/erc4626",
+  "examples/erc6909",
+  "examples/erc6909-supply",
   "examples/safe-erc20",
   "examples/merkle-proofs",
   "examples/ownable",
@@ -62,6 +64,8 @@ default-members = [
   "examples/erc1155-metadata-uri",
   "examples/erc1155-supply",
   "examples/erc4626",
+  "examples/erc6909",
+  "examples/erc6909-supply",
   "examples/safe-erc20",
   "examples/merkle-proofs",
   "examples/ownable",

Cargo.toml

@@ -0,0 +1,84 @@
+use alloy::{
+    network::{AnyNetwork, EthereumWallet},
+    primitives::Address,
+    providers::ProviderBuilder,
+    sol,
+    sol_types::SolCall,
+    uint,
+};
+use e2e::{receipt, Account};
+
+use crate::{
+    report::{ContractReport, FunctionReport},
+    Opt,
+};
+
+sol!(
+    #[sol(rpc)]
+    contract Erc6909 {
+        function balanceOf(address owner, uint256 id) external view returns (uint256 balance);
+        function allowance(address owner, address spender, uint256 id) external view returns (uint256 allowance);
+        function isOperator(address owner, address spender) external view returns (bool approved);
+        function approve(address spender, uint256 id, uint256 amount) external returns (bool);
+        function setOperator(address spender, bool approved) external returns (bool);
+        function transfer(address receiver, uint256 id, uint256 amount) external returns (bool);
+        function transferFrom(address sender, address receiver, uint256 id, uint256 amount) external returns (bool);
+        function mint(address to, uint256 id, uint256 amount) external;
+        function burn(address from, uint256 id, uint256 amount) external;
+    }
+);
+
+pub async fn bench() -> eyre::Result<ContractReport> {
+    ContractReport::generate("Erc6909", run).await
+}
+
+pub async fn run(cache_opt: Opt) -> eyre::Result<Vec<FunctionReport>> {
+    let alice = Account::new().await?;
+    let alice_addr = alice.address();
+    let alice_wallet = ProviderBuilder::new()
+        .network::<AnyNetwork>()
+        .with_recommended_fillers()
+        .wallet(EthereumWallet::from(alice.signer.clone()))
+        .on_http(alice.url().parse()?);
+
+    let bob = Account::new().await?;
+    let bob_addr = bob.address();
+    let bob_wallet = ProviderBuilder::new()
+        .network::<AnyNetwork>()
+        .with_recommended_fillers()
+        .wallet(EthereumWallet::from(bob.signer.clone()))
+        .on_http(bob.url().parse()?);
+
+    let contract_addr = deploy(&alice, cache_opt).await?;
+
+    let contract = Erc6909::new(contract_addr, &alice_wallet);
+    let contract_bob = Erc6909::new(contract_addr, &bob_wallet);
+
+    let token_id = uint!(1_U256);
+    let amount = uint!(100_U256);
+    let one = uint!(1_U256);
+
+    // IMPORTANT: Order matters!
+    use Erc6909::*;
+    #[rustfmt::skip]
+    let receipts = vec![
+        (mintCall::SIGNATURE, receipt!(contract.mint(alice_addr, token_id, amount))?),
+        (balanceOfCall::SIGNATURE, receipt!(contract.balanceOf(alice_addr, token_id))?),
+        (allowanceCall::SIGNATURE, receipt!(contract.allowance(alice_addr, bob_addr, token_id))?),
+        (isOperatorCall::SIGNATURE, receipt!(contract.isOperator(alice_addr, bob_addr))?),
+        (setOperatorCall::SIGNATURE, receipt!(contract.setOperator(bob_addr, true))?),
+        (transferCall::SIGNATURE, receipt!(contract.transfer(bob_addr, token_id, one))?),
+        (approveCall::SIGNATURE, receipt!(contract.approve(bob_addr, token_id, one))?),
+        (transferFromCall::SIGNATURE, receipt!(contract_bob.transferFrom(alice_addr, bob_addr, token_id, one))?),
+        (burnCall::SIGNATURE, receipt!(contract.burn(alice_addr, token_id, one))?),
+    ];
+
+    receipts
+        .into_iter()
+        .map(FunctionReport::new)
+        .collect::<eyre::Result<Vec<_>>>()
+}
+
+async fn deploy(account: &Account, cache_opt: Opt) -> eyre::Result<Address> {
+    crate::deploy(account, "erc6909", None, cache_opt).await
+}

benches/src/erc6909.rs

@@ -0,0 +1,62 @@
+use alloy::{
+    network::{AnyNetwork, EthereumWallet},
+    primitives::Address,
+    providers::ProviderBuilder,
+    sol,
+    sol_types::SolCall,
+    uint,
+};
+use e2e::{receipt, Account};
+
+use crate::{
+    report::{ContractReport, FunctionReport},
+    Opt,
+};
+
+sol!(
+    #[sol(rpc)]
+    contract Erc6909TokenSupply {
+        function totalSupply(uint256 id) external view returns (uint256 totalSupply);
+        function mint(address to, uint256 id, uint256 amount) external;
+        function burn(address from, uint256 id, uint256 amount) external;
+    }
+);
+
+pub async fn bench() -> eyre::Result<ContractReport> {
+    ContractReport::generate("Erc6909TokenSupply", run).await
+}
+
+pub async fn run(cache_opt: Opt) -> eyre::Result<Vec<FunctionReport>> {
+    let alice = Account::new().await?;
+    let alice_addr = alice.address();
+    let alice_wallet = ProviderBuilder::new()
+        .network::<AnyNetwork>()
+        .with_recommended_fillers()
+        .wallet(EthereumWallet::from(alice.signer.clone()))
+        .on_http(alice.url().parse()?);
+
+    let contract_addr = deploy(&alice, cache_opt).await?;
+
+    let contract = Erc6909TokenSupply::new(contract_addr, &alice_wallet);
+
+    let token_id = uint!(1_U256);
+    let amount = uint!(100_U256);
+
+    // IMPORTANT: Order matters!
+    use Erc6909TokenSupply::*;
+    #[rustfmt::skip]
+    let receipts = vec![
+        (mintCall::SIGNATURE, receipt!(contract.mint(alice_addr, token_id, amount))?),
+        (totalSupplyCall::SIGNATURE, receipt!(contract.totalSupply(token_id))?),
+        (burnCall::SIGNATURE, receipt!(contract.burn(alice_addr, token_id, amount))?),
+    ];
+
+    receipts
+        .into_iter()
+        .map(FunctionReport::new)
+        .collect::<eyre::Result<Vec<_>>>()
+}
+
+async fn deploy(account: &Account, cache_opt: Opt) -> eyre::Result<Address> {
+    crate::deploy(account, "erc6909-supply", None, cache_opt).await
+}

benches/src/erc6909_supply.rs

@@ -12,6 +12,8 @@ pub mod erc1155;
 pub mod erc1155_metadata_uri;
 pub mod erc1155_supply;
 pub mod erc20;
+pub mod erc6909;
+pub mod erc6909_supply;
 pub mod erc721;
 pub mod merkle_proofs;
 pub mod ownable;

benches/src/lib.rs

@@ -1,7 +1,7 @@
 use benches::{
-    access_control, eddsa, erc1155, erc1155_metadata_uri, erc20, erc721,
-    merkle_proofs, ownable, pedersen, poseidon, poseidon_asm_sol, poseidon_sol,
-    report::BenchmarkReport,
+    access_control, eddsa, erc1155, erc1155_metadata_uri, erc20, erc6909,
+    erc6909_supply, erc721, merkle_proofs, ownable, pedersen, poseidon,
+    poseidon_asm_sol, poseidon_sol, report::BenchmarkReport,
 };
 use futures::FutureExt;
 use itertools::Itertools;
@@ -16,6 +16,8 @@ async fn main() -> eyre::Result<()> {
         ownable::bench().boxed(),
         erc1155::bench().boxed(),
         erc1155_metadata_uri::bench().boxed(),
+        erc6909::bench().boxed(),
+        erc6909_supply::bench().boxed(),
         pedersen::bench().boxed(),
         poseidon_sol::bench().boxed(),
         poseidon_asm_sol::bench().boxed(),

benches/src/main.rs

@@ -237,7 +237,7 @@ impl Erc1155Supply {
     /// # Panics
     ///
     /// * If updated balance and/or supply exceeds [`U256::MAX`], may happen
-    ///   during the `mint` operation.
+    ///   during the [`Self::_mint`] operation.
     fn _update(
         &mut self,
         from: Address,

contracts/src/token/erc1155/extensions/supply.rs

@@ -0,0 +1,4 @@
+//! Common extensions to the ERC-6909 standard.
+pub mod token_supply;
+
+pub use token_supply::{Erc6909TokenSupply, IErc6909TokenSupply};