Merge pull request #8 from FuelLabs/K1-R1/usage-scripts-and-docs

feat: SRC-14 owned proxy usage scripts and docs

.github/workflows/ci.yml

@@ -22,10 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        project:
-          [
-            "src14/owned_proxy",
-          ]
+        project: ["src14/owned_proxy/contract"]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -76,7 +73,7 @@ jobs:
 
       - name: Check Clippy Linter
         run: cargo clippy --manifest-path tests/Cargo.toml --all-features --all-targets -- -D warnings
-        
+
       - name: Cargo Test sway-lib
         run: cargo test --manifest-path tests/Cargo.toml
 
@@ -103,4 +100,37 @@ jobs:
     steps:
       - uses: tarides/changelog-check-action@v2
         with:
-          changelog: CHANGELOG.md
+          changelog: CHANGELOG.md
+
+  build-scripts:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        project: ["src14/owned_proxy/scripts"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Init cache
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ env.RUST_VERSION }}
+          components: clippy, rustfmt
+
+      - name: Check Rust formatting
+        run: |
+          cd ${{ matrix.project }}
+          cargo fmt --verbose --check
+
+      - name: Cargo Build scripts
+        run: |
+          cd ${{ matrix.project }}
+          cargo build
+
+      - name: Check Clippy Linter
+        run: |
+          cd ${{ matrix.project }}
+          cargo clippy --all-features --all-targets -- -D warnings

CHANGELOG.md

@@ -13,6 +13,7 @@ Description of the upcoming release here.
 
 - [#4](https://github.com/FuelLabs/sway-standard-implementations/pull/4) Adds initial CI.
 - [#1](https://github.com/FuelLabs/sway-standard-implementations/pull/1) Adds an implementation of SRC-14: Owned Proxy.
+- [#8](https://github.com/FuelLabs/sway-standard-implementations/pull/8) Adds SRC-14 owned proxy usage scripts and docs.
 
 ### Changed
 

README.md

@@ -20,7 +20,7 @@ The purpose of this repository is to contain production ready implementations of
 
 #### SRC-14: Owned Proxy Contract
 
-- [Owned Proxy Contract](./src14/owned_proxy/) is an opinionated implementation of the [extended SRC-14 standard](https://docs.fuel.network/docs/sway-standards/src-14-simple-upgradeable-proxies/). It utilises the [Upgradability library from sway-libs](https://github.com/FuelLabs/sway-libs) and includes initialization functionality that allows for secure ownership upon deployment.
+- The [Owned Proxy Contract](./src14/owned_proxy/) is an opinionated implementation of the [extended SRC-14 standard](https://docs.fuel.network/docs/sway-standards/src-14-simple-upgradeable-proxies/). It utilises the [Upgradability library from sway-libs](https://github.com/FuelLabs/sway-libs) and includes initialization functionality that allows for secure ownership upon deployment.
 
 ## Tests
 

src14/owned_proxy/README.md

@@ -0,0 +1,59 @@
+# SRC-14: Owned Proxy Contract
+
+- The [Owned Proxy Contract](./contract/src/main.sw) is an opinionated implementation of the [extended SRC-14 standard](https://docs.fuel.network/docs/sway-standards/src-14-simple-upgradeable-proxies/). It utilises the [Upgradability library from sway-libs](https://github.com/FuelLabs/sway-libs) and includes initialization functionality that allows for secure ownership upon deployment.
+
+## Usage instructions
+
+Clone the repository and move into it:
+
+```bash
+git clone -b master https://github.com/FuelLabs/sway-standard-implementations.git && cd sway-standard-implementations
+```
+
+### Rust scripts
+
+> **Warning:** These scripts are temporary. Proxy contract deployment and interactions will be integrated into `Forc` in the near future.
+
+A suite of Rust scripts are included to assist in the usage of the contract. In order to use them navigate to the [owned-proxy/scripts](./scripts/) directory. From `sway-standard-implementations/<you are here>`:
+
+```bash
+cd src14/owned_proxy/scripts
+```
+
+#### Deploy and initialize
+
+As described in the [SRC-14 standard](https://docs.fuel.network/docs/sway-standards/src-14-simple-upgradeable-proxies/); this proxy contract implementation works via The FuelVM's LDC instruction that is used by Sway's `std::execution::run_external` functionality to execute instructions from a target contract while retaining the proxy contract's storage context. As such a target contract must be deployed to be used alongside this proxy contract. There are two options to achieve this:
+
+- The target contract can be deployed _before_ the proxy contract; in this case set the target contract's ID as the `<INITIAL_TARGET>` when deploying the proxy contract.
+- The target contract can be deployed _after_ the proxy contract; in this case set the target contract via the `set_proxy_target` method, a script for which is provided [below](#updating-the-target-contract).
+
+To deploy and initialize the proxy contract the `deploy_and_init` script is available. It will use the arguments `--initial-target` and `--initial-owner` as configurables in the proxy contract. From `sway-standard-implementations/src14/owned_proxy/scripts/<you are here>`:
+
+```bash
+SIGNING_KEY=<SIGNING_KEY> cargo run -r --bin deploy_and_init -- --initial-target <INITIAL_TARGET> --initial-owner <INITIAL_OWNER> --provider-url <PROVIDER_URL>
+```
+
+> **Note:** The optional flag `--provider-url <PROVIDER_URL>` sets the URL of the provider to be used in the script. If not manually set, it defaults to `127.0.0.1:4000` which is the default `fuel-core` URL.
+> **Note:** There is also the optional flag `--signing-key <SIGNING_KEY>` which can be used instead of the environment variable `SIGNING_KEY`. However use of the environment variable `SIGNING_KEY` is preferred.
+
+#### Updating the proxy owner
+
+To update the proxy contract's owner the `set_proxy_owner` script is available. It will use the argument `--new-owner` as the new owner in the proxy contract. From `sway-standard-implementations/src14/owned_proxy/scripts/<you are here>`:
+
+```bash
+SIGNING_KEY=<SIGNING_KEY> cargo run -r --bin set_proxy_owner -- --proxy-contract-id <PROXY_CONTRACT_ID> --new-owner <NEW_OWNER> --provider-url <PROVIDER_URL>
+```
+
+> **Note:** The optional flag `--provider-url <PROVIDER_URL>` sets the URL of the provider to be used in the script. If not manually set, it defaults to `127.0.0.1:4000` which is the default `fuel-core` URL.
+> **Note:** There is also the optional flag `--signing-key <SIGNING_KEY>` which can be used instead of the environment variable `SIGNING_KEY`. However use of the environment variable `SIGNING_KEY` is preferred.
+
+#### Updating the target contract
+
+To update the proxy contract's target the `set_proxy_target` script is available. It will use the argument `--new-target-id` as the new target contract in the proxy contract. From `sway-standard-implementations/src14/owned_proxy/scripts/<you are here>`:
+
+```bash
+SIGNING_KEY=<SIGNING_KEY> cargo run -r --bin set_proxy_target -- --proxy-contract-id <PROXY_CONTRACT_ID> --new-target-id <NEW_TARGET_ID> --provider-url <PROVIDER_URL>
+```
+
+> **Note:** The optional flag `--provider-url <PROVIDER_URL>` sets the URL of the provider to be used in the script. If not manually set, it defaults to `127.0.0.1:4000` which is the default `fuel-core` URL.
+> **Note:** There is also the optional flag `--signing-key <SIGNING_KEY>` which can be used instead of the environment variable `SIGNING_KEY`. However use of the environment variable `SIGNING_KEY` is preferred.

src14/owned_proxy/Forc.lock → src14/owned_proxy/contract/Forc.lock

@@ -28,7 +28,7 @@ dependencies = ["core"]
 
 [[package]]
 name = "sway_libs"
-source = "git+https://github.com/FuelLabs/sway-libs?branch=master#2a869c583d2ab9fbe8de17a3301d928b224062c7"
+source = "git+https://github.com/FuelLabs/sway-libs?branch=master#51876797c76b8d1777b1c179e5f5725ae1b2cbb3"
 dependencies = [
     "standards git+https://github.com/FuelLabs/sway-standards?tag=v0.5.0#348f7175df4c012b23c86cdb18aab79025ca1f18",
     "std",

src14/owned_proxy/scripts/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "src14-owned-proxy-scripts"
+version = "0.0.0"
+authors = ["Fuel Labs <[email protected]>"]
+edition = "2021"
+license = "Apache-2.0"
+
+[dependencies]
+clap = { version = "4.5", features = ["env"] }
+fuels = { version = "0.65", features = ["fuel-core-lib"] }
+tokio = { version = "1.39", features = ["rt", "macros"] }
+
+[lib]
+name = "proxy_script_utils"
+path = "src/utils.rs"
+
+[[bin]]
+name = "deploy_and_init"
+path = "src/deploy_and_init.rs"
+
+[[bin]]
+name = "set_proxy_owner"
+path = "src/set_proxy_owner.rs"
+
+[[bin]]
+name = "set_proxy_target"
+path = "src/set_proxy_target.rs"

src14/owned_proxy/scripts/src/deploy_and_init.rs

@@ -0,0 +1,80 @@
+use clap::Parser;
+use fuels::{
+    programs::contract::{Contract, LoadConfiguration, StorageConfiguration},
+    types::{transaction::TxPolicies, Address, ContractId},
+};
+use proxy_script_utils::{setup_signing_wallet, ProxyContract, ProxyContractConfigurables, State};
+use std::str::FromStr;
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Provider URL
+    #[arg(short, long, default_value = "127.0.0.1:4000")]
+    provider_url: String,
+    /// Signing key
+    #[arg(short, long, required = true, env = "SIGNING_KEY")]
+    signing_key: String,
+    /// Initial target ContractId
+    #[arg(long, required = true)]
+    initial_target: String,
+    /// Initial owner Id
+    #[arg(long, required = true)]
+    initial_owner: String,
+}
+
+#[tokio::main]
+async fn main() {
+    println!("\n|||||||||||||||||||||||||||||||||||||||||||||||||\n-|- Deploying and Initializing Proxy Contract -|-\n|||||||||||||||||||||||||||||||||||||||||||||||||");
+    let args = Args::parse();
+
+    let signing_wallet = setup_signing_wallet(&args.provider_url, &args.signing_key).await;
+
+    // Deploy proxy with args as configurables
+    let storage_configuration = StorageConfiguration::default()
+        .add_slot_overrides_from_file(
+            "../contract/out/release/src14_owned_proxy-storage_slots.json",
+        )
+        .unwrap();
+
+    let configurables = ProxyContractConfigurables::default()
+        .with_INITIAL_TARGET(Some(
+            ContractId::from_str(&args.initial_target)
+                .expect("Initial target ContractId could not be parsed"),
+        ))
+        .unwrap()
+        .with_INITIAL_OWNER(State::Initialized(
+            Address::from_str(&args.initial_owner)
+                .expect("Initial owner Id could not be parsed")
+                .into(),
+        ))
+        .unwrap();
+
+    let configuration = LoadConfiguration::default()
+        .with_storage_configuration(storage_configuration)
+        .with_configurables(configurables);
+
+    println!("\n - Deploying proxy contract...");
+    let proxy_contract_id = Contract::load_from(
+        "../contract/out/release/src14_owned_proxy.bin",
+        configuration,
+    )
+    .unwrap()
+    .deploy(&signing_wallet, TxPolicies::default())
+    .await
+    .unwrap();
+    println!(
+        " - Proxy Contract Deployed with ContractId: {}",
+        ContractId::from(&proxy_contract_id)
+    );
+
+    // Initialize proxy
+    println!(" - Initializing proxy contract...");
+    ProxyContract::new(proxy_contract_id, signing_wallet)
+        .methods()
+        .initialize_proxy()
+        .call()
+        .await
+        .unwrap();
+    println!(" - Proxy Contract initialized\n");
+}

src14/owned_proxy/scripts/src/set_proxy_owner.rs

@@ -0,0 +1,64 @@
+use clap::Parser;
+use fuels::types::Address;
+use proxy_script_utils::{get_proxy_instance, setup_signing_wallet, State};
+use std::str::FromStr;
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Provider URL
+    #[arg(long, default_value = "testnet.fuel.network")]
+    provider_url: String,
+    /// Signing key
+    #[arg(short, long, required = true, env = "SIGNING_KEY")]
+    signing_key: String,
+    /// Proxy Contract Id
+    #[arg(long, required = true)]
+    proxy_contract_id: String,
+    /// New Owner Id
+    #[arg(short, long, required = true)]
+    new_owner: String,
+}
+
+#[tokio::main]
+async fn main() {
+    println!("\n|||||||||||||||||||||||||||||||||\n-|- Setting a new proxy owner -|-\n|||||||||||||||||||||||||||||||||");
+
+    let args = Args::parse();
+
+    let signing_wallet = setup_signing_wallet(&args.provider_url, &args.signing_key).await;
+
+    let proxy_contract = get_proxy_instance(&args.proxy_contract_id, signing_wallet);
+
+    let current_owner = proxy_contract
+        .methods()
+        .proxy_owner()
+        .simulate()
+        .await
+        .unwrap()
+        .value;
+    println!("\n - The current proxy owner: {:?}", current_owner);
+
+    let new_owner = State::Initialized(
+        Address::from_str(&args.new_owner)
+            .expect("New owner Id could not be parsed")
+            .into(),
+    );
+
+    println!(" - Proxy owner is being updated...");
+    proxy_contract
+        .methods()
+        .set_proxy_owner(new_owner)
+        .call()
+        .await
+        .unwrap();
+
+    let new_owner = proxy_contract
+        .methods()
+        .proxy_owner()
+        .simulate()
+        .await
+        .unwrap()
+        .value;
+    println!(" - The new proxy owner: {:?}\n", new_owner);
+}

src14/owned_proxy/scripts/src/set_proxy_target.rs

@@ -0,0 +1,61 @@
+use clap::Parser;
+use fuels::types::ContractId;
+use proxy_script_utils::{get_proxy_instance, setup_signing_wallet};
+use std::str::FromStr;
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Provider URL
+    #[arg(long, default_value = "testnet.fuel.network")]
+    provider_url: String,
+    /// Signing key
+    #[arg(short, long, required = true, env = "SIGNING_KEY")]
+    signing_key: String,
+    /// Proxy Contract Id
+    #[arg(long, required = true)]
+    proxy_contract_id: String,
+    /// New Target Contract Id
+    #[arg(short, long, required = true)]
+    new_target_id: String,
+}
+
+#[tokio::main]
+async fn main() {
+    println!("\n||||||||||||||||||||||||||||||||||\n-|- Setting a new proxy target -|-\n||||||||||||||||||||||||||||||||||");
+
+    let args = Args::parse();
+
+    let signing_wallet = setup_signing_wallet(&args.provider_url, &args.signing_key).await;
+
+    let proxy_contract = get_proxy_instance(&args.proxy_contract_id, signing_wallet);
+
+    let current_target = proxy_contract
+        .methods()
+        .proxy_target()
+        .simulate()
+        .await
+        .unwrap()
+        .value;
+    println!("\n - The current target contract ID: {:?}", current_target);
+
+    let new_target =
+        ContractId::from_str(&args.new_target_id).expect("New Target Id could not be parsed");
+
+    println!(" - Proxy target is being updated...");
+    proxy_contract
+        .methods()
+        .set_proxy_target(new_target)
+        .call()
+        .await
+        .unwrap();
+
+    let new_target = proxy_contract
+        .methods()
+        .proxy_target()
+        .simulate()
+        .await
+        .unwrap()
+        .value;
+    println!(" - The new target contract ID: {:?}\n", new_target);
+}