feat: IProxy & Erc1967

Cargo.toml

@@ -8,6 +8,7 @@ members = [
   "lib/e2e-proc",
   "examples/access-control",
   "examples/ecdsa",
+  "examples/erc1967",
   "examples/erc20",
   "examples/erc20-permit",
   "examples/erc20-flash-mint",
@@ -26,6 +27,7 @@ members = [
   "examples/vesting-wallet",
   "examples/ownable-two-step",
   "examples/poseidon",
+  "examples/proxy",
   "examples/pedersen",
   "examples/basic/token",
   "examples/basic/script",
@@ -37,6 +39,7 @@ default-members = [
   "lib/e2e-proc",
   "examples/access-control",
   "examples/ecdsa",
+  "examples/erc1967",
   "examples/erc20",
   "examples/erc20-permit",
   "examples/erc20-flash-mint",
@@ -55,6 +58,7 @@ default-members = [
   "examples/vesting-wallet",
   "examples/ownable-two-step",
   "examples/poseidon",
+  "examples/proxy",
   "examples/pedersen",
   "examples/basic/token",
 ]

GUIDELINES.md

@@ -3,8 +3,6 @@
 ## Setup
 
 1. Install [Docker].
-1. Install the [Solidity Compiler] version `0.8.24`.
-(NOTE: it is important to use this exact version to avoid compatibility issues).
 1. Install toolchain providing `cargo` using [rustup].
 1. Install the cargo stylus tool with `cargo install --force cargo-stylus`.
 
@@ -15,8 +13,6 @@ and retry installing the stylus tool.
 
 [Docker]: https://docs.docker.com/engine/install/
 
-[Solidity Compiler]: https://docs.soliditylang.org/en/v0.8.28/installing-solidity.html#linux-packages
-
 [rustup]: https://rustup.rs/
 
 ## Testing

contracts/src/proxy/beacon/mod.rs

@@ -1,5 +1,23 @@
 //! Solidity Interface of `BeaconProxy`.
-pub use beacon::*;
+
+use alloy_primitives::Address;
+
+mod proxy;
+mod upgradeable;
+
+pub use beacon::IBeaconInterface;
+pub use proxy::BeaconProxy;
+pub use upgradeable::{IUpgradeableBeacon, UpgradeableBeacon};
+
+/// This is the interface that [BeaconProxy][BeaconProxy] expects of its beacon.
+///
+/// [BeaconProxy]: crate::proxy::beacon::BeaconProxy
+pub trait IBeacon {
+    /// Must return an address that can be used as a delegate call target.
+    ///
+    /// [`UpgradeableBeacon`] will check that this address is a contract.
+    fn implementation(&self) -> Result<Address, stylus_sdk::call::Error>;
+}
 
 mod beacon {
     #![allow(missing_docs)]
@@ -9,7 +27,7 @@
 
     use stylus_sdk::prelude::sol_interface;
     sol_interface! {
-        interface IBeacon {
+        interface IBeaconInterface {
             function implementation() external view returns (address);
         }
     }

contracts/src/proxy/beacon/proxy.rs

@@ -0,0 +1,89 @@
+//! This contract implements a proxy that gets the implementation address for
+//! each call from an [UpgradeableBeacon][UpgradeableBeacon].
+//!
+//! The beacon address can only be set once during construction, and cannot be
+//! changed afterwards. It is stored in an immutable variable to avoid
+//! unnecessary storage reads, and also in the beacon storage slot specified by
+//! [ERC-1967] so that it can be accessed externally.
+//!
+//! CAUTION: Since the beacon address can never be changed, you must ensure that
+//! you either control the beacon, or trust the beacon to not upgrade the
+//! implementation maliciously.
+//!
+//! IMPORTANT: Do not use the implementation logic to modify the beacon storage
+//! slot. Doing so would leave the proxy in an inconsistent state where the
+//! beacon storage slot does not match the beacon address.
+//!
+//! [UpgradeableBeacon]: crate::proxy::beacon::UpgradeableBeacon
+//! [ERC-1967]: https://eips.ethereum.org/EIPS/eip-1967
+
+use alloc::{vec, vec::Vec};
+
+use alloy_primitives::Address;
+use stylus_sdk::{abi::Bytes, prelude::*, storage::StorageAddress};
+
+use crate::proxy::{
+    beacon::IBeaconInterface,
+    erc1967::{Erc1967Utils, Error},
+    IProxy,
+};
+
+/// State of an [`BeaconProxy`] token.
+#[storage]
+pub struct BeaconProxy {
+    beacon: StorageAddress,
+}
+
+/// 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 BeaconProxy {}
+
+impl BeaconProxy {
+    /// Initializes the proxy with `beacon`.
+    ///
+    /// If `data` is nonempty, it's used as data in a delegate call to the
+    /// implementation returned by the beacon. This will typically be an
+    /// encoded function call, and allows initializing the storage of the proxy
+    /// like a Solidity constructor.
+    ///
+    /// # Arguments
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `beacon` - The beacon address.
+    /// * `data` - The data to pass to the beacon.
+    ///
+    /// # Errors
+    ///
+    /// * [`Error::InvalidBeacon`] - If the beacon is not a contract with the
+    ///   interface [IBeacon][IBeacon].
+    /// * [`Error::NonPayable`] - If the data is empty and
+    ///   [msg::value][msg_value] is not [`U256::ZERO`].
+    ///
+    /// [msg_value]: stylus_sdk::msg::value
+    /// [IBeacon]: crate::proxy::beacon::IBeacon
+    pub fn constructor(
+        &mut self,
+        beacon: Address,
+        data: Bytes,
+    ) -> Result<(), Error> {
+        Erc1967Utils::upgrade_beacon_to_and_call(self, beacon, data)?;
+        self.beacon.set(beacon);
+        Ok(())
+    }
+
+    /// Returns the beacon.
+    ///
+    /// # Arguments
+    ///
+    /// * `&self` - Read access to the contract's state.
+    pub fn get_beacon(&self) -> Address {
+        self.beacon.get()
+    }
+}
+
+impl IProxy for BeaconProxy {
+    fn implementation(&self) -> Result<Address, stylus_sdk::call::Error> {
+        IBeaconInterface::new(self.get_beacon()).implementation(self)
+    }
+}

contracts/src/proxy/beacon/upgradeable.rs

@@ -0,0 +1,24 @@
+use alloc::{vec, vec::Vec};
+
+use stylus_sdk::{prelude::*, storage::StorageAddress};
+
+use crate::{access::ownable::IOwnable, proxy::beacon::IBeacon};
+
+/// This contract is used in conjunction with one or more instances of
+/// [BeaconProxy][BeaconProxy] to determine their implementation contract, which
+/// is where they will delegate all function calls.
+///
+/// An owner is able to change the implementation the beacon points to, thus
+/// upgrading the proxies that use this beacon.
+///
+/// [BeaconProxy]: crate::proxy::beacon::BeaconProxy
+pub trait IUpgradeableBeacon: IBeacon + IOwnable {}
+
+/// State of an [`UpgradeableBeacon`] contract.
+#[storage]
+pub struct UpgradeableBeacon {
+    /// The address of the implementation contract.
+    implementation: StorageAddress,
+    /// The address of the owner of the contract.
+    owner: StorageAddress,
+}

contracts/src/proxy/erc1967/mod.rs

@@ -1,11 +1,22 @@
-//! Proxy Storage Slots and the events as defined in
-//! the [ERC-1967].
+//! This contract implements an upgradeable proxy. It is upgradeable because
+//! calls are delegated to an implementation address that can be changed. This
+//! address is stored in storage in the location specified by
+//! [ERC-1967], so that it doesn't conflict with the storage layout of the
+//! implementation behind the proxy.
+//!
+//! [ERC-1967]: https://eips.ethereum.org/EIPS/eip-1967
+use alloc::{vec, vec::Vec};
+
+use alloy_primitives::Address;
+use stylus_sdk::{abi::Bytes, prelude::*};
+
+use crate::proxy::IProxy;
 
-//! [ERC-1967]: <https://eips.ethereum.org/EIPS/eip-1967>
-pub mod proxy;
 pub mod utils;
 
 pub use sol::*;
+pub use utils::{Erc1967Utils, Error};
+
 #[cfg_attr(coverage_nightly, coverage(off))]
 mod sol {
     use alloy_sol_macro::sol;
@@ -27,3 +38,40 @@
         event BeaconUpgraded(address indexed beacon);
     }
 }
+
+/// State of an [`Erc1967Proxy`] token.
+#[storage]
+pub struct Erc1967Proxy;
+
+/// 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 Erc1967Proxy {}
+
+impl Erc1967Proxy {
+    /// Constructor.
+    ///
+    /// # Arguments
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    /// * `implementation` - Address of the implementation contract.
+    /// * `data` - Data to pass to the implementation contract.
+    pub fn constructor(
+        &mut self,
+        implementation: Address,
+        data: Bytes,
+    ) -> Result<(), Error> {
+        Erc1967Utils::upgrade_to_and_call(implementation, data)
+    }
+}
+
+impl IProxy for Erc1967Proxy {
+    /**
+     * @dev This is a virtual function that should be overridden so it
+     * returns the address to which the fallback function and
+     * {_fallback} should delegate.
+     */
+    fn implementation(&self) -> Result<Address, stylus_sdk::call::Error> {
+        Ok(Erc1967Utils::get_implementation())
+    }
+}