Merge pull request #25 from casper-ecosystem/counter_upgrade_example

Fixing 2 helpers and adding some comments
casper-ecosystem · Dec 22, 2022 · 934a452 · 934a452
2 parents 8a622cd + 87bf598
commit 934a452
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 21 deletions.
diff --git a/contract-v1/src/main.rs b/contract-v1/src/main.rs
@@ -4,41 +4,49 @@
 #[cfg(not(target_arch = "wasm32"))]
 compile_error!("target arch should be wasm32: compile with '--target wasm32-unknown-unknown'");
 
+// This code imports necessary aspects of external crates that we will use in our contract code.
 extern crate alloc;
-
+// Importing Rust types.
 use alloc::{
     string::{String, ToString},
     vec::Vec,
 };
+// Importing aspects of the Casper platform.
 use casper_contract::{
     contract_api::{runtime, storage},
     unwrap_or_revert::UnwrapOrRevert,
 };
+// Importing specific Casper types.
 use casper_types::{
     api_error::ApiError,
     contracts::{EntryPoint, EntryPointAccess, EntryPointType, EntryPoints, NamedKeys},
     CLType, CLValue, URef,
 };
 
+// Constants for the keys pointing to values stored in the account's named keys.
 const CONTRACT_PACKAGE_NAME: &str = "counter_package_name";
 const CONTRACT_ACCESS_UREF: &str = "counter_access_uref";
 
+// Creating constants for the various contract entry points.
 const ENTRY_POINT_COUNTER_INC: &str = "counter_inc";
 const ENTRY_POINT_COUNTER_GET: &str = "counter_get";
 
+// Constants for the keys pointing to values stored in the contract's named keys.
 const CONTRACT_VERSION_KEY: &str = "version";
 const CONTRACT_KEY: &str = "counter";
 const COUNT_KEY: &str = "count";
 
+// Entry point that increments the count value by 1.
 #[no_mangle]
 pub extern "C" fn counter_inc() {
     let uref: URef = runtime::get_key(COUNT_KEY)
         .unwrap_or_revert_with(ApiError::MissingKey)
         .into_uref()
         .unwrap_or_revert_with(ApiError::UnexpectedKeyVariant);
-    storage::add(uref, 1); // increment the count by 1
+    storage::add(uref, 1); // Increment the count by 1.
 }
 
+// Entry point that returns the count value.
 #[no_mangle]
 pub extern "C" fn counter_get() {
     let uref: URef = runtime::get_key(COUNT_KEY)
@@ -49,20 +57,21 @@ pub extern "C" fn counter_get() {
         .unwrap_or_revert_with(ApiError::Read)
         .unwrap_or_revert_with(ApiError::ValueNotFound);
     let typed_result = CLValue::from_t(result).unwrap_or_revert();
-    runtime::ret(typed_result); // return the count value
+    runtime::ret(typed_result); // Return the count value.
 }
 
+// Entry point that executes automatically when a caller installs the contract.
 #[no_mangle]
 pub extern "C" fn call() {
-    // Initialize the count to 0 locally
+    // Initialize the count to 0, locally.
     let count_start = storage::new_uref(0_i32);
 
-    // In the named keys of the contract, add a key for the count
+    // In the named keys of the contract, add a key for the count.
     let mut counter_named_keys = NamedKeys::new();
     let key_name = String::from(COUNT_KEY);
     counter_named_keys.insert(key_name, count_start.into());
 
-    // Create entry points for this contract
+    // Create the entry points for this contract.
     let mut counter_entry_points = EntryPoints::new();
 
     counter_entry_points.add_entry_point(EntryPoint::new(
@@ -81,22 +90,22 @@ pub extern "C" fn call() {
         EntryPointType::Contract,
     ));
 
-    // Create a new contract package that can be upgraded
+    // Create a new contract package that can be upgraded.
     let (stored_contract_hash, contract_version) = storage::new_contract(
         counter_entry_points,
         Some(counter_named_keys),
         Some(CONTRACT_PACKAGE_NAME.to_string()),
         Some(CONTRACT_ACCESS_UREF.to_string()),
     );
 
-    /* To create a locked contract instead, use new_locked_contract and throw away the contract version returned
+    /* To create a locked contract instead, use new_locked_contract and throw away the contract version returned.
     let (stored_contract_hash, _) =
         storage::new_locked_contract(counter_entry_points, Some(counter_named_keys), None, None); */
 
-    // Store the contract version in the context's named keys
+    // Store the contract version in the context's named keys.
     let version_uref = storage::new_uref(contract_version);
     runtime::put_key(CONTRACT_VERSION_KEY, version_uref.into());
 
-    // Create a named key for the contract hash
+    // Create a named key for the contract hash.
     runtime::put_key(CONTRACT_KEY, stored_contract_hash.into());
 }
diff --git a/contract-v2/src/main.rs b/contract-v2/src/main.rs
@@ -4,33 +4,41 @@
 #[cfg(not(target_arch = "wasm32"))]
 compile_error!("target arch should be wasm32: compile with '--target wasm32-unknown-unknown'");
 
+// This code imports necessary aspects of external crates that we will use in our contract code.
 extern crate alloc;
 
+// Importing Rust types.
 use alloc::{
     string::{String, ToString},
     vec::Vec,
 };
+// Importing aspects of the Casper platform.
 use casper_contract::{
     contract_api::{runtime, storage},
     unwrap_or_revert::UnwrapOrRevert,
 };
+// Importing specific Casper types.
 use casper_types::{
     api_error::ApiError,
     contracts::{EntryPoint, EntryPointAccess, EntryPointType, EntryPoints, NamedKeys},
     CLType, CLValue, URef,
 };
 
+// Creating constants for the various contract entry points.
 const ENTRY_POINT_COUNTER_INC: &str = "counter_inc";
 const ENTRY_POINT_COUNTER_GET: &str = "counter_get";
 const ENTRY_POINT_COUNTER_DECREMENT: &str = "counter_decrement";
 
+// Constants for the keys pointing to values stored in the contract's named keys.
 const CONTRACT_VERSION_KEY: &str = "version";
 const CONTRACT_KEY: &str = "counter";
 const COUNT_KEY: &str = "count";
 
+// Constants for the keys pointing to values stored in the account's named keys.
 const CONTRACT_PACKAGE_NAME: &str = "counter_package_name";
 const CONTRACT_ACCESS_UREF: &str = "counter_access_uref";
 
+// Entry point that increments the count value by 1.
 #[no_mangle]
 pub extern "C" fn counter_inc() {
     let uref: URef = runtime::get_key(COUNT_KEY)
@@ -40,6 +48,7 @@ pub extern "C" fn counter_inc() {
     storage::add(uref, 1); // Increment the count by 1.
 }
 
+// Entry point that returns the count value.
 #[no_mangle]
 pub extern "C" fn counter_get() {
     let uref: URef = runtime::get_key(COUNT_KEY)
@@ -53,6 +62,7 @@ pub extern "C" fn counter_get() {
     runtime::ret(typed_result); // Return the count value.
 }
 
+// Entry point that decrements the count value by 1.
 #[no_mangle]
 pub extern "C" fn counter_decrement() {
     let uref: URef = runtime::get_key(COUNT_KEY)
@@ -62,17 +72,17 @@ pub extern "C" fn counter_decrement() {
     storage::add(uref, -1); // Decrement the count.
 }
 
-#[no_mangle]
-pub extern "C" fn install_counter() {
-    // Initialize the count to 0 locally
+// Helper function that installs the counter contract on chain.
+fn install_counter() {
+    // Initialize the count to 0, locally.
     let count_start = storage::new_uref(0_i32);
 
-    // In the named keys of the contract, add a key for the count
+    // In the named keys of the contract, add a key for the count.
     let mut counter_named_keys = NamedKeys::new();
     let key_name = String::from(COUNT_KEY);
     counter_named_keys.insert(key_name, count_start.into());
 
-    // Create entry points for this contract
+    // Create the entry points for this contract.
     let mut counter_entry_points = EntryPoints::new();
 
     counter_entry_points.add_entry_point(EntryPoint::new(
@@ -91,7 +101,7 @@ pub extern "C" fn install_counter() {
         EntryPointType::Contract,
     ));
 
-    // Create a new contract package that can be upgraded
+    // Create a new contract package that can be upgraded.
     let (stored_contract_hash, contract_version) = storage::new_contract(
         counter_entry_points,
         Some(counter_named_keys),
@@ -103,16 +113,16 @@ pub extern "C" fn install_counter() {
     let (stored_contract_hash, _) =
         storage::new_locked_contract(counter_entry_points, Some(counter_named_keys), None, None); */
 
-    // Store the contract version in the context's named keys
+    // Store the contract version in the context's named keys.
     let version_uref = storage::new_uref(contract_version);
     runtime::put_key(CONTRACT_VERSION_KEY, version_uref.into());
 
-    // Create a named key for the contract hash
+    // Create a named key for the contract hash.
     runtime::put_key(CONTRACT_KEY, stored_contract_hash.into());
 }
 
-#[no_mangle]
-pub extern "C" fn upgrade_counter() {
+// Helper function that upgrades the contract package to a new version.
+fn upgrade_counter() {
     // In this version, we will not add any named keys.
     // The named keys from the previous version should still be available.
     // Create a new entry point list that includes counter_decrement.
@@ -168,6 +178,7 @@ pub extern "C" fn upgrade_counter() {
     runtime::put_key(CONTRACT_KEY, stored_contract_hash.into());
 }
 
+// Entry point that executes automatically when a caller installs the contract.
 #[no_mangle]
 pub extern "C" fn call() {
     match runtime::get_key(CONTRACT_ACCESS_UREF) {

diff --git a/tests/src/integration_tests.rs b/tests/src/integration_tests.rs
@@ -1,10 +1,11 @@
 #[cfg(test)]
 mod tests {
-
+    // Outlining aspects of the Casper test support crate to include.
     use casper_engine_test_support::{
         ExecuteRequestBuilder, InMemoryWasmTestBuilder, DEFAULT_ACCOUNT_ADDR,
         DEFAULT_RUN_GENESIS_REQUEST,
     };
+    // Custom Casper types that will be used within this test.
     use casper_types::{runtime_args, ContractHash, RuntimeArgs};
 
     const COUNTER_V1_WASM: &str = "counter-v1.wasm"; // The first version of the contract