docs: proxy contract cookbook

.changeset/friendly-cooks-appear.md

@@ -0,0 +1,5 @@
+---
+"@internal/benchmarks": patch
+---
+
+docs: proxy contract cookbook

apps/docs-snippets/src/guide/contracts/proxy-contracts.test.ts

@@ -0,0 +1,105 @@
+import { Provider, Wallet } from 'fuels';
+import { launchTestNode } from 'fuels/test-utils';
+
+import {
+  Counter,
+  CounterFactory,
+  CounterV2,
+  CounterV2Factory,
+  ProxyContract,
+  ProxyContractFactory,
+} from '../../../test/typegen';
+
+/**
+ * @group node
+ * @group browser
+ */
+describe('Proxy Contracts', () => {
+  it('deploys and upgrades a contracts using a proxy', async () => {
+    using launched = await launchTestNode();
+
+    const {
+      provider: testProvider,
+      wallets: [testWallet],
+    } = launched;
+    const providerUrl = testProvider.url;
+    const WALLET_PVT_KEY = testWallet.privateKey;
+
+    // #region proxy-2
+    // #import { Provider, Wallet };
+    // #context import { WALLET_PVT_KEY } from 'path/to/my/env/file';
+    // #context import { CounterFactory, Counter, ProxyFactory, CounterV2Factory } from 'path/to/typegen/outputs';
+
+    const provider = await Provider.create(providerUrl);
+    const wallet = Wallet.fromPrivateKey(WALLET_PVT_KEY, provider);
+
+    const counterContractFactory = new CounterFactory(wallet);
+    const { waitForResult: waitForCounterContract } = await counterContractFactory.deploy();
+    const { contract: counterContract } = await waitForCounterContract();
+    // #endregion proxy-2
+
+    // #region proxy-3
+    // It is important to pass the pass all storage slots to the proxy in order to initialize the storage slots.
+    const storageSlots = Counter.storageSlots.concat(ProxyContract.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 ProxyContractFactory(wallet);
+    const { waitForResult: waitForProxyContract } = await proxyContractFactory.deploy({
+      storageSlots,
+      configurableConstants,
+    });
+    const { contract: proxyContract } = await waitForProxyContract();
+
+    const { waitForResult: waitForProxyInit } = await proxyContract.functions
+      .initialize_proxy()
+      .call();
+    await waitForProxyInit();
+    // #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 initialContract = new Counter(proxyContract.id, wallet);
+
+    const { waitForResult: waitForIncrement } = await initialContract.functions
+      .increment_counter(1)
+      .call();
+    await waitForIncrement();
+
+    const { value: count } = await initialContract.functions.get_count().get();
+    // #endregion proxy-4
+
+    // #region proxy-6
+    const { waitForResult: waitForCounterContractV2 } = await CounterV2Factory.deploy(wallet);
+    const { contract: counterContractV2 } = await waitForCounterContractV2();
+
+    const { waitForResult: waitForUpdateTarget } = await proxyContract.functions
+      .set_proxy_target({ bits: counterContractV2.id.toB256() })
+      .call();
+
+    await waitForUpdateTarget();
+    // #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 { waitForResult: waitForSecondIncrement } = await upgradedContract.functions
+      .increment_counter(1)
+      .call();
+    await waitForSecondIncrement();
+
+    const { value: increments } = await upgradedContract.functions.get_increments().get();
+    const { value: secondCount } = await upgradedContract.functions.get_count().get();
+    // #endregion proxy-7
+
+    expect(count.toNumber()).toBe(1);
+    expect(secondCount.toNumber()).toBe(2);
+    expect(increments.toNumber()).toBe(1);
+  });
+});

apps/docs-snippets/test/fixtures/forc-projects/Forc.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
   "counter",
+  "counter-v2",
   "echo-enum",
   "liquidity-pool",
   "log-values",
@@ -34,4 +35,5 @@ members = [
   "input-output-types",
   "bytecode-input",
   "configurable-pin",
+  "proxy-contract",
 ]

apps/docs-snippets/test/fixtures/forc-projects/counter-v2/Forc.toml

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

apps/docs-snippets/test/fixtures/forc-projects/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_counter(amount: u64) -> u64;
+
+    #[storage(write, read)]
+    fn decrement_counter(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_counter(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_counter(amount: u64) -> u64 {
+        let current = storage.counter.read();
+        storage.counter.write(current - amount);
+        storage.counter.read()
+    }
+}
+// #endregion proxy-5

apps/docs-snippets/test/fixtures/forc-projects/counter/src/main.sw

@@ -1,3 +1,4 @@
+// #region proxy-1
 contract;
 
 abi Counter {
@@ -18,20 +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_counter(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_counter(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()
     }
 }
+// #endregion proxy-1

apps/docs-snippets/test/fixtures/forc-projects/proxy-contract/Forc.toml

@@ -0,0 +1,9 @@
+[project]
+authors = ["Fuel Labs <contact@fuel.sh>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "proxy-contract"
+
+[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-snippets/test/fixtures/forc-projects/proxy-contract/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);
+}