Improve upgradeable examples folder structure, explain differences

.gitlab-ci.yml

@@ -33,6 +33,7 @@ variables:
   # read more https://github.com/paritytech/scripts/pull/244
   ALL_CRATES:                      "${PURELY_STD_CRATES} ${ALSO_WASM_CRATES}"
   DELEGATOR_SUBCONTRACTS:          "accumulator adder subber"
+  UPGRADEABLE_CONTRACTS:           "forward-calls delegate-call"
   VAULT_SERVER_URL:                "https://vault.parity-mgmt-vault.parity.io"
   VAULT_AUTH_PATH:                 "gitlab-parity-io-jwt"
   VAULT_AUTH_ROLE:                 "cicd_gitlab_parity_${CI_PROJECT_NAME}"
@@ -140,11 +141,16 @@ examples-fmt:
   script:
     # Note that we disable the license header check for the examples, since they are unlicensed.
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         cargo fmt --verbose --manifest-path ${example}/Cargo.toml -- --check --config=license_template_path="";
       done
     - for contract in ${DELEGATOR_SUBCONTRACTS}; do
         cargo fmt --verbose --manifest-path ./examples/delegator/${contract}/Cargo.toml -- --check --config=license_template_path="";
       done
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        cargo fmt --verbose --manifest-path ./examples/upgradeable-contracts/${contract}/Cargo.toml -- --check --config=license_template_path="";
+      done
+    - cargo fmt --verbose --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml -- --check --config=license_template_path=""
   allow_failure:                   true
 
 clippy-std:
@@ -172,11 +178,16 @@ examples-clippy-std:
   <<:                              *test-refs
   script:
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         cargo clippy --verbose --all-targets --manifest-path ${example}/Cargo.toml -- -D warnings;
       done
     - for contract in ${DELEGATOR_SUBCONTRACTS}; do
         cargo clippy --verbose --all-targets --manifest-path ./examples/delegator/${contract}/Cargo.toml -- -D warnings;
       done
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        cargo clippy --verbose --all-targets --manifest-path ./examples/upgradeable-contracts/${contract}/Cargo.toml -- -D warnings;
+      done
+    - cargo clippy --verbose --all-targets --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml -- -D warnings;
   allow_failure:                   true
 
 examples-clippy-wasm:
@@ -185,11 +196,16 @@ examples-clippy-wasm:
   <<:                              *test-refs
   script:
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         cargo clippy --verbose --manifest-path ${example}/Cargo.toml --no-default-features --target wasm32-unknown-unknown -- -D warnings;
       done
     - for contract in ${DELEGATOR_SUBCONTRACTS}; do
         cargo clippy --verbose --manifest-path ./examples/delegator/${contract}/Cargo.toml --no-default-features --target wasm32-unknown-unknown -- -D warnings;
       done
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        cargo clippy --verbose --manifest-path ./examples/upgradeable-contracts/${contract}/Cargo.toml --no-default-features --target wasm32-unknown-unknown -- -D warnings;
+      done
+    - cargo clippy --verbose --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml --no-default-features --target wasm32-unknown-unknown -- -D warnings;
   allow_failure:                   true
 
 
@@ -335,11 +351,16 @@ examples-test:
       artifacts:                   false
   script:
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         cargo test --verbose --manifest-path ${example}/Cargo.toml;
       done
     - for contract in ${DELEGATOR_SUBCONTRACTS}; do
         cargo test --verbose --manifest-path ./examples/delegator/${contract}/Cargo.toml;
       done
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        cargo test --verbose --manifest-path ./examples/upgradeable-contracts/${contract}/Cargo.toml;
+      done
+    - cargo test --verbose --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml;
 
 examples-contract-build:
   stage:                           examples
@@ -348,11 +369,18 @@ examples-contract-build:
   script:
     - cargo contract -V
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         pushd $example &&
         cargo contract build &&
         popd;
       done
-    - cd ./examples/delegator/ && ./build-all.sh
+    - pushd ./examples/delegator/ && ./build-all.sh && popd
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        pushd $example &&
+        cargo contract build &&
+        popd;
+      done
+    - cargo contract build --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml
 
 examples-docs:
   stage:                           examples
@@ -366,11 +394,16 @@ examples-docs:
     # Once https://github.com/paritytech/ink/issues/336 has been implemented we can get rid
     # of this flag.
     - for example in examples/*/; do
+        if [ "$example" = "examples/upgradeable-contracts/" ]; then continue; fi;
         cargo doc --manifest-path ${example}/Cargo.toml --document-private-items --verbose --no-deps;
       done
     - for contract in ${DELEGATOR_SUBCONTRACTS}; do
         cargo doc --manifest-path ./examples/delegator/${contract}/Cargo.toml --document-private-items --verbose --no-deps;
       done
+    - for contract in ${UPGRADEABLE_CONTRACTS}; do
+        cargo doc --manifest-path ./examples/upgradeable-contracts/${contract}/Cargo.toml --document-private-items --verbose --no-deps;
+      done
+    - cargo doc --manifest-path ./examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml --document-private-items --verbose --no-deps
 
 
 #### stage:                        ink-waterfall

examples/upgradeable-contracts/README.md

@@ -0,0 +1,21 @@
+# Upgradeable Contracts
+
+There are two upgradeable contract examples in this folder, they differ
+in key properties outlined below.
+
+See [here](https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies) for
+more information on proxy patterns.
+
+
+## `forward-calls`
+
+* Forwards any call that does not match a selector of itself to another contract.
+* The other contract needs to be deployed on-chain.
+* State is stored in the storage of the contract to which calls are forwarded.
+
+
+## `delegate-call`
+
+* Executes any call that does not match a selector of itself with the code of another contract.
+* The other contract does not need to be deployed on-chain. 
+* State is stored in the storage of the originally called contract.

examples/upgradeable-contracts/delegate-call/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "upgradeable_contract"
+version = "3.0.0"
+authors = ["Parity Technologies <[email protected]>"]
+edition = "2021"
+
+[dependencies]
+ink_primitives = { version = "3.0.0", path = "../../../crates/primitives", default-features = false }
+ink_prelude = { version = "3.0.0", path = "../../../crates/prelude", default-features = false }
+ink_metadata = { version = "3.0.0", path = "../../../crates/metadata", default-features = false, features = ["derive"], optional = true }
+ink_env = { version = "3.0.0", path = "../../../crates/env", default-features = false }
+ink_storage = { version = "3.0.0", path = "../../../crates/storage", default-features = false }
+ink_lang = { version = "3.0.0", path = "../../../crates/lang", default-features = false }
+
+scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive"] }
+scale-info = { version = "2", default-features = false, features = ["derive"], optional = true }
+
+[lib]
+name = "upgradeable_contract"
+path = "lib.rs"
+crate-type = ["cdylib"]
+
+[features]
+default = ["std"]
+std = [
+    "ink_primitives/std",
+    "ink_metadata/std",
+    "ink_env/std",
+    "ink_storage/std",
+    "ink_lang/std",
+    "scale/std",
+    "scale-info/std",
+]
+ink-as-dependency = []

examples/upgradeable-contract/README.md → examples/upgradeable-contracts/delegate-call/README.md

@@ -12,35 +12,35 @@ In order to test it out you need to do the following:
 
 1. Build a contract containing some logic, e.g. our upgradeable flipper example:
    ```
-   cargo +nightly contract build --manifest-path=examples/upgradeable-contract/upgradeable-flipper/Cargo.toml
+   cargo +nightly contract build --manifest-path=./upgradeable-flipper/Cargo.toml
    ```
-   You will receive the respective `upgradeable_flipper.contract` bundle in the 
-   `examples/upgradeable-contract/upgradeable-flipper/target/ink/` folder.
-
-   In order to perform migrations and have proxy working for contracts with different 
-   [storage layouts](https://paritytech.github.io/ink-docs/datastructures/spread-storage-layout), 
-   we use the [`Upgradeable`](upgradeable-flipper/upgradeable.rs) type 
-   wrapper, which ensures that we write different fields of desired struct to different 
-   storage locations, while also tracking the initialization status (e.g., we uploaded 
+   You will receive the respective `upgradeable_flipper.contract` bundle in the
+   `./upgradeable-flipper/target/ink/` folder.
+
+   In order to perform migrations and have proxy working for contracts with different
+   [storage layouts](https://paritytech.github.io/ink-docs/datastructures/spread-storage-layout),
+   we use the [`Upgradeable`](upgradeable-flipper/upgradeable.rs) type
+   wrapper, which ensures that we write different fields of desired struct to different
+   storage locations, while also tracking the initialization status (e.g., we uploaded
    the code on chain, but haven't called the constructor).
 
 1. Build the proxy contract:
    ```
-   cargo +nightly contract build --manifest-path=examples/upgradeable-contract/Cargo.toml
+   cargo +nightly contract build --manifest-path=./Cargo.toml
    ```
-   You will receive the respective `upgradeable_contract.contract` bundle 
-   in the `examples/upgradeable-contract/target/ink/` folder.
+   You will receive the respective `upgradeable_contract.contract` bundle
+   in the `./target/ink/` folder.
 1. Upload the `upgradeable_flipper.contract` to the chain.
-1. Upload the `upgradeable_contract.contract` to the chain. During instantiation 
+1. Upload the `upgradeable_contract.contract` to the chain. During instantiation
    specify the just instantiated `upgradeable_flipper` contract as the `delegate_to` parameter.
-1. Switch the metadata of the just instantiated `upgradeable_contract` contract to the 
-   metadata of the `upgradeable_flipper` contract. In the `polkadot-js` UI this can be 
+1. Switch the metadata of the just instantiated `upgradeable_contract` contract to the
+   metadata of the `upgradeable_flipper` contract. In the `polkadot-js` UI this can be
    done this way:
-   1. Click the icon left of the instantiated `upgradeable_contract` contract to copy the 
+   1. Click the icon left of the instantiated `upgradeable_contract` contract to copy the
       address of it into your clipboard.
-   1. Click `Add an existing contract`, insert the just copied address, upload the 
+   1. Click `Add an existing contract`, insert the just copied address, upload the
       `upgradeable_flipper.contract` for the `Contract ABI`.
-1. Now you are able to run the operations provided by the `upgradeable_flipper` smart 
+1. Now you are able to run the operations provided by the `upgradeable_flipper` smart
    contract via the `upgradeable_contract` contract.
 
 To change the address of the smart contract where calls are forwarded to you would

examples/upgradeable-contract/upgradeable-flipper/Cargo.toml → examples/upgradeable-contracts/delegate-call/upgradeable-flipper/Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "upgradeable_flipper"
-version = "3.0.0-rc9"
+version = "3.0.0"
 authors = ["Parity Technologies <[email protected]>"]
 edition = "2021"
 
 [dependencies]
-ink_primitives = { version = "3.0.0-rc9", path = "../../../crates/primitives", default-features = false }
-ink_metadata = { version = "3.0.0-rc9", path = "../../../crates/metadata", default-features = false, features = ["derive"], optional = true }
-ink_env = { version = "3.0.0-rc9", path = "../../../crates/env", default-features = false, features = ["ink-debug"] }
-ink_storage = { version = "3.0.0-rc9", path = "../../../crates/storage", default-features = false }
-ink_lang = { version = "3.0.0-rc9", path = "../../../crates/lang", default-features = false }
+ink_primitives = { version = "3.0.0", path = "../../../../crates/primitives", default-features = false }
+ink_metadata = { version = "3.0.0", path = "../../../../crates/metadata", default-features = false, features = ["derive"], optional = true }
+ink_env = { version = "3.0.0", path = "../../../../crates/env", default-features = false, features = ["ink-debug"] }
+ink_storage = { version = "3.0.0", path = "../../../../crates/storage", default-features = false }
+ink_lang = { version = "3.0.0", path = "../../../../crates/lang", default-features = false }
 
 scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive"] }
 scale-info = { version = "2", default-features = false, features = ["derive"], optional = true }

examples/upgradeable-contracts/forward-calls/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "proxy"
+version = "3.0.0"
+authors = ["Parity Technologies <[email protected]>"]
+edition = "2021"
+
+[dependencies]
+ink_primitives = { version = "3.0.0", path = "../../../crates/primitives", default-features = false }
+ink_prelude = { version = "3.0.0", path = "../../../crates/prelude", default-features = false }
+ink_metadata = { version = "3.0.0", path = "../../../crates/metadata", default-features = false, features = ["derive"], optional = true }
+ink_env = { version = "3.0.0", path = "../../../crates/env", default-features = false }
+ink_storage = { version = "3.0.0", path = "../../../crates/storage", default-features = false }
+ink_lang = { version = "3.0.0", path = "../../../crates/lang", default-features = false }
+
+scale = { package = "parity-scale-codec", version = "3", default-features = false, features = ["derive"] }
+scale-info = { version = "2", default-features = false, features = ["derive"], optional = true }
+
+[lib]
+name = "proxy"
+path = "lib.rs"
+crate-type = ["cdylib"]
+
+[features]
+default = ["std"]
+std = [
+    "ink_primitives/std",
+    "ink_metadata/std",
+    "ink_env/std",
+    "ink_storage/std",
+    "ink_lang/std",
+    "scale/std",
+    "scale-info/std",
+]
+ink-as-dependency = []

examples/proxy/README.md → examples/upgradeable-contracts/forward-calls/README.md

@@ -19,9 +19,10 @@ In order to test it out you need to do the following:
    You will receive the respective `flipper.contract` bundle in the `examples/flipper/target/ink/` folder.
 1. Build the proxy contract:
    ```
-   cargo +nightly contract build --manifest-path=examples/proxy/Cargo.toml
+   cd upgradeable-contracts/forward-calls/
+   cargo +nightly contract build
    ```
-   You will receive the respective `proxy.contract` bundle in the `examples/proxy/target/ink/` folder.
+   You will receive the respective `proxy.contract` bundle in the `target/ink/` folder.
 1. Upload the `flipper.contract` to the chain.
 1. Upload the `proxy.contract` to the chain. During instantiation specify the just instantiated
    `flipper` contract as the `forward_to` parameter.