docs: proxy contract cookbook

.changeset/friendly-cooks-appear.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: proxy contract cookbook

apps/docs-snippets2/src/contracts/proxy-contracts.ts

@@ -0,0 +1,102 @@
+// #region proxy-2
+import { Provider, Wallet } from 'fuels';
+
+import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from '../env';
+import {
+  Counter,
+  CounterFactory,
+  CounterV2,
+  CounterV2Factory,
+  Proxy,
+  ProxyFactory,
+} from '../typegend';
+
+const provider = await Provider.create(LOCAL_NETWORK_URL);
+const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+const counterContractFactory = new CounterFactory(wallet);
+const deploy = await counterContractFactory.deploy();
+const { contract: counterContract } = await deploy.waitForResult();
+// #endregion proxy-2
+
+// #region proxy-3
+/**
+ * It is important to pass all storage slots to the proxy in order to
+ * initialize the storage slots.
+ */
+const storageSlots = Counter.storageSlots.concat(Proxy.storageSlots);
+
+/**
+ * These configurables are specific to our recommended SRC14 compliant
+ * contract. They must be passed on deploy and then `initialize_proxy`
+ * must be called to setup the proxy contract.
+ */
+const configurableConstants = {
+  INITIAL_TARGET: { bits: counterContract.id.toB256() },
+  INITIAL_OWNER: {
+    Initialized: { Address: { bits: wallet.address.toB256() } },
+  },
+};
+
+const proxyContractFactory = new ProxyFactory(wallet);
+const proxyDeploy = await proxyContractFactory.deploy({
+  storageSlots,
+  configurableConstants,
+});
+
+const { contract: proxyContract } = await proxyDeploy.waitForResult();
+const { waitForResult } = await proxyContract.functions
+  .initialize_proxy()
+  .call();
+
+await waitForResult();
+// #endregion proxy-3
+
+// #region proxy-4
+/**
+ * Make sure to use only the contract ID of the proxy when instantiating
+ * the contract as this will remain static even with future upgrades.
+ */
+const proxiedContract = new Counter(proxyContract.id, wallet);
+
+const incrementCall = await proxiedContract.functions.increment_count(1).call();
+await incrementCall.waitForResult();
+
+const { value: count } = await proxiedContract.functions.get_count().get();
+// #endregion proxy-4
+
+console.log('count:', count.toNumber() === 1);
+
+// #region proxy-6
+const deployV2 = await CounterV2Factory.deploy(wallet);
+const { contract: contractV2 } = await deployV2.waitForResult();
+
+const updateTargetCall = await proxyContract.functions
+  .set_proxy_target({ bits: contractV2.id.toB256() })
+  .call();
+
+await updateTargetCall.waitForResult();
+// #endregion proxy-6
+
+// #region proxy-7
+/**
+ * Again, we are instantiating the contract with the same proxy ID
+ * but using a new contract instance.
+ */
+const upgradedContract = new CounterV2(proxyContract.id, wallet);
+
+const incrementCall2 = await upgradedContract.functions
+  .increment_count(1)
+  .call();
+
+await incrementCall2.waitForResult();
+
+const { value: increments } = await upgradedContract.functions
+  .get_increments()
+  .get();
+
+const { value: count2 } = await upgradedContract.functions.get_count().get();
+// #endregion proxy-7
+
+console.log('secondCount', count2.toNumber() === 2);
+console.log('increments', increments);

apps/docs-snippets2/sway/Forc.toml

@@ -1,2 +1,2 @@
 [workspace]
-members = ["counter", "script-sum"]
+members = ["counter", "counter-v2", "proxy", "script-sum"]

apps/docs-snippets2/sway/counter-v2/Forc.toml

@@ -0,0 +1,7 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "counter-v2"
+
+[dependencies]

apps/docs-snippets2/sway/counter-v2/src/main.sw

@@ -0,0 +1,52 @@
+// #region proxy-5
+contract;
+
+abi Counter {
+    #[storage(read)]
+    fn get_count() -> u64;
+
+    #[storage(read)]
+    fn get_increments() -> u64;
+
+    #[storage(write, read)]
+    fn increment_count(amount: u64) -> u64;
+
+    #[storage(write, read)]
+    fn decrement_count(amount: u64) -> u64;
+}
+
+storage {
+    counter: u64 = 0,
+    increments: u64 = 0,
+}
+
+impl Counter for Contract {
+    #[storage(read)]
+    fn get_count() -> u64 {
+        storage.counter.try_read().unwrap_or(0)
+    }
+
+    #[storage(read)]
+    fn get_increments() -> u64 {
+        storage.increments.try_read().unwrap_or(0)
+    }
+
+    #[storage(write, read)]
+    fn increment_count(amount: u64) -> u64 {
+        let current = storage.counter.try_read().unwrap_or(0);
+        storage.counter.write(current + amount);
+
+        let current_iteration: u64 = storage.increments.try_read().unwrap_or(0);
+        storage.increments.write(current_iteration + 1);
+
+        storage.counter.read()
+    }
+
+    #[storage(write, read)]
+    fn decrement_count(amount: u64) -> u64 {
+        let current = storage.counter.try_read().unwrap_or(0);
+        storage.counter.write(current - amount);
+        storage.counter.read()
+    }
+}
+// #endregion proxy-5

apps/docs-snippets2/sway/counter/src/main.sw

@@ -1,3 +1,4 @@
+// #region proxy-1
 contract;
 
 abi Counter {
@@ -6,6 +7,9 @@ abi Counter {
 
     #[storage(write, read)]
     fn increment_count(amount: u64) -> u64;
+
+    #[storage(write, read)]
+    fn decrement_count(amount: u64) -> u64;
 }
 
 storage {
@@ -15,13 +19,21 @@ storage {
 impl Counter for Contract {
     #[storage(read)]
     fn get_count() -> u64 {
-        storage.counter.read()
+        storage.counter.try_read().unwrap_or(0)
     }
 
     #[storage(write, read)]
     fn increment_count(amount: u64) -> u64 {
-        let current = storage.counter.read();
+        let current = storage.counter.try_read().unwrap_or(0);
         storage.counter.write(current + amount);
         storage.counter.read()
     }
+
+    #[storage(write, read)]
+    fn decrement_count(amount: u64) -> u64 {
+        let current = storage.counter.try_read().unwrap_or(0);
+        storage.counter.write(current - amount);
+        storage.counter.read()
+    }
 }
+// #endregion proxy-1

apps/docs-snippets2/sway/proxy/Forc.toml

@@ -0,0 +1,9 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "proxy"
+
+[dependencies]
+standards = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.6.0" }
+sway_libs = { git = "https://github.com/FuelLabs/sway-libs", tag = "v0.24.0" }

apps/docs-snippets2/sway/proxy/src/interface.sw

@@ -0,0 +1,11 @@
+library;
+
+use standards::src5::State;
+
+abi OwnedProxy {
+    #[storage(write)]
+    fn initialize_proxy();
+
+    #[storage(write)]
+    fn set_proxy_owner(new_proxy_owner: State);
+}

apps/docs-snippets2/sway/proxy/src/main.sw

@@ -0,0 +1,160 @@
+contract;
+
+mod interface;
+
+use interface::OwnedProxy;
+use ::sway_libs::{
+    ownership::errors::InitializationError,
+    upgradability::{
+        _proxy_owner,
+        _proxy_target,
+        _set_proxy_owner,
+        _set_proxy_target,
+        only_proxy_owner,
+    },
+};
+use standards::{src14::{SRC14, SRC14Extension}, src5::State};
+use std::execution::run_external;
+
+configurable {
+    /// The initial value of `storage::SRC14.target`.
+    INITIAL_TARGET: Option<ContractId> = None,
+    /// The initial value of `storage::SRC14.proxy_owner`.
+    INITIAL_OWNER: State = State::Uninitialized,
+}
+
+storage {
+    SRC14 {
+        /// The [ContractId] of the target contract.
+        ///
+        /// # Additional Information
+        ///
+        /// `target` is stored at sha256("storage_SRC14_0")
+        target in 0x7bb458adc1d118713319a5baa00a2d049dd64d2916477d2688d76970c898cd55: Option<ContractId> = None,
+        /// The [State] of the proxy owner.
+        ///
+        /// # Additional Information
+        ///
+        /// `proxy_owner` is stored at sha256("storage_SRC14_1")
+        proxy_owner in 0xbb79927b15d9259ea316f2ecb2297d6cc8851888a98278c0a2e03e1a091ea754: State = State::Uninitialized,
+    },
+}
+
+impl SRC14 for Contract {
+    /// Change the target contract of the proxy contract.
+    ///
+    /// # Additional Information
+    ///
+    /// This method can only be called by the `proxy_owner`.
+    ///
+    /// # Arguments
+    ///
+    /// * `new_target`: [ContractId] - The new proxy contract to which all fallback calls will be passed.
+    ///
+    /// # Reverts
+    ///
+    /// * When not called by `proxy_owner`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    /// * Write: `1`
+    #[storage(read, write)]
+    fn set_proxy_target(new_target: ContractId) {
+        only_proxy_owner();
+        _set_proxy_target(new_target);
+    }
+
+    /// Returns the target contract of the proxy contract.
+    ///
+    /// # Returns
+    ///
+    /// * [Option<ContractId>] - The new proxy contract to which all fallback calls will be passed or `None`.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    #[storage(read)]
+    fn proxy_target() -> Option<ContractId> {
+        _proxy_target()
+    }
+}
+
+impl SRC14Extension for Contract {
+    /// Returns the owner of the proxy contract.
+    ///
+    /// # Returns
+    ///
+    /// * [State] - Represents the state of ownership for this contract.
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    #[storage(read)]
+    fn proxy_owner() -> State {
+        _proxy_owner()
+    }
+}
+
+impl OwnedProxy for Contract {
+    /// Initializes the proxy contract.
+    ///
+    /// # Additional Information
+    ///
+    /// This method sets the storage values using the values of the configurable constants `INITIAL_TARGET` and `INITIAL_OWNER`.
+    /// This then allows methods that write to storage to be called.
+    /// This method can only be called once.
+    ///
+    /// # Reverts
+    ///
+    /// * When `storage::SRC14.proxy_owner` is not [State::Uninitialized].
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Writes: `2`
+    #[storage(write)]
+    fn initialize_proxy() {
+        require(
+            _proxy_owner() == State::Uninitialized,
+            InitializationError::CannotReinitialized,
+        );
+
+        storage::SRC14.target.write(INITIAL_TARGET);
+        storage::SRC14.proxy_owner.write(INITIAL_OWNER);
+    }
+
+    /// Changes proxy ownership to the passed State.
+    ///
+    /// # Additional Information
+    ///
+    /// This method can be used to transfer ownership between Identities or to revoke ownership.
+    ///
+    /// # Arguments
+    ///
+    /// * `new_proxy_owner`: [State] - The new state of the proxy ownership.
+    ///
+    /// # Reverts
+    ///
+    /// * When the sender is not the current proxy owner.
+    /// * When the new state of the proxy ownership is [State::Uninitialized].
+    ///
+    /// # Number of Storage Accesses
+    ///
+    /// * Reads: `1`
+    /// * Writes: `1`
+    #[storage(write)]
+    fn set_proxy_owner(new_proxy_owner: State) {
+        _set_proxy_owner(new_proxy_owner);
+    }
+}
+
+/// Loads and runs the target contract's code within the proxy contract's context.
+///
+/// # Additional Information
+///
+/// Used when a method that does not exist in the proxy contract is called.
+#[fallback]
+#[storage(read)]
+fn fallback() {
+    run_external(_proxy_target().expect("FallbackError::TargetNotSet"))
+}