Merge pull request #27 from fabricwave/update/july_2024

July 2024 Documentation Update

Author: dtlkelvin

docs/for_developers/smart_contracts/getting_started.md

@@ -139,7 +139,7 @@ You can deploy the contract using the pchain_client command line tool. You shoul
 
 === "Linux / macOS"
     ```bash
-    ./pchain_client transaction create
+    ./pchain_client transaction create \
     --nonce <NONCE> \
     --gas-limit <GAS_LIMIT> \
     --max-base-fee-per-gas <MAX_BASE_FEE_PER_GAS> \
@@ -160,7 +160,7 @@ You can deploy the contract using the pchain_client command line tool. You shoul
     --cbi-version <CBI_VERSION> 
     ```
 
-You can follow the instruction in [Create Transaction](../../for_users/pchain_client_cli/creating_transaction.md) about submiting a transaction through `pchain-client`.
+You can refer to the instruction and example arguments in [Create & Submit Transaction](../../for_users/pchain_client_cli/creating_transaction.md) to create and submit a transaction through `pchain-client`.
 
 ## Checking Contract In State
 
@@ -237,7 +237,7 @@ The command argument `arguments` is the JSON file that contains the method argum
 
 The gas limit required for the transaction depends on the complexity of the smart contract. For safety reasons, you can always set a higher gas limit. You can also test contract calls on testnet to reassure.
 
-You can follow the instruction in [Create Transaction](../../for_users/pchain_client_cli/creating_transaction.md) about submiting a transaction through `pchain-client`.
+You can refer to the instruction and example arguments in [Create & Submit Transaction](../../for_users/pchain_client_cli/creating_transaction.md) to create and submit a transaction through `pchain-client`.
 
 To query the resulting receipt of the transaction, 
 
@@ -256,15 +256,15 @@ The commands stored in `transaction` and command receipts in `receipt` are follo
 
 To parse the response from the contract method, represented in the field named `return value` , which is in `CallResult` format, you can use the `parse call-result` command in ParallelChain Client.
 
-For example, if the contract method returns a u32 integer, the `return value` is "BAAAAAUAAAA" you can parse the `CallResult` data structure using the `--data-type u32` flag:
+For example, if the contract method returns a u32 integer, the `return value` is "BQAAAA" you can parse the `CallResult` data structure using the `--data-type u32` flag:
 
 === "Linux / macOS"
     ```bash
-    pchain_client parse call-result --value BAAAAAUAAAA --data-type u32
+    pchain_client parse call-result --value BQAAAA --data-type u32
     ```
 === "Windows PowerShell"
     ```PowerShell
-    ./pchain_client.exe parse call-result --value BAAAAAUAAAA --data-type u32
+    ./pchain_client.exe parse call-result --value BQAAAA --data-type u32
     ```
 
-The output will be the parsed value of the `CallResult`, which in this case is `4`. For more details, you can use the `help` command to see the usage of the tool or take a look at the example `argument,json`.
+The output will be the parsed value of the `CallResult`, which in this case is `5`. For more details, you can use the `help` command to see the usage of the tool or take a look at the example `argument,json`.

docs/for_developers/smart_contracts/smart_contract_examples/4_contract_proxy.md

@@ -20,13 +20,16 @@ Recall that we have a deployed contract called `MyLittlePony` that consists of t
 `self_introduction()`, `grow_up()`, and `change_person()`. We are going to use `grow_up()` in 
 `ContractProxy`, so we can comment out the rest of them. 
 
+!!! Pre-requisites
+    Deploy [My Little Pony](./2_my_little_pony.md) smart contract, and then replace the address supplied to `use_contract` macro with the smart contract address of My Little Pony.
+
 ### lib.rs: define a trait
 ```rust
 use pchain_sdk::{
     use_contract, call, contract, contract_methods
 };
 
-#[use_contract("-jUt6jrEfMRD1JM9n6_yAASl2cwsc4tg1Bqp07gvQpU")]
+#[use_contract("xxT5OXMonFm8wcDw-io1jeyAEnxSddGPOG-ZezArCV4")]
 pub trait MyLittlePony {
     //fn self_introduction() -> String;
     fn grow_up();
@@ -59,11 +62,14 @@ The above example has shown how we can use the `use_contract` macro to do [cross
 to use `pchain_sdk::call_untyped()` to do so. We pass the contract address as an argument so that the contract
 address does not need to be hard-coded in the contract.
 
+!!! note
+    Add `base64url = "0.1.0"` under `[Dependency]` in `Cargo.toml` for the project.
+
 ### lib.rs: pchain_sdk::call_untyped()
 ```rust
 #[call]
 fn grow_up_2(address: String) {
-    let contract_address = base64url::decode(address).unwrap().try_into().unwrap();
+    let contract_address = base64url::decode(&address).unwrap().try_into().unwrap();
     pchain_sdk::call_untyped(
         contract_address,
         "grow_up", 
@@ -80,7 +86,7 @@ contract to a specific address by `pchain_sdk::transfer()` (see [Transferring Ba
 ```rust
 #[call]
 fn send_tokens(to_address: String, value :u64){
-    let contract_address = base64url::decode(to_address).unwrap().try_into().unwrap();
+    let contract_address = base64url::decode(&to_address).unwrap().try_into().unwrap();
     pchain_sdk::transfer(
         contract_address,
         value

docs/for_developers/smart_contracts/smart_contract_examples/5_my_collections.md

@@ -11,7 +11,7 @@ We are going to demonstrate the use of module [collections](https://github.com/p
 
 `collections` are designed as a data structure for gas efficiency:
 
-- Cacher: allows lazy initialization
+- Cacher: allows lazy loading of a field in contract storage
 - Vector: lazily stores a list of items
 - FastMap: lazily stores items into a key-value map
 - IterableMap: lazily stores items into an iterable key-value map
@@ -37,7 +37,7 @@ pub struct MyCollections {
 ```
 
 ### Cacher
-`Cacher` is a data wrapper to support Lazy Read and Lazy Write to Contract Storage.
+`Cacher` is a data wrapper to support Lazy Read and Lazy Write to a field in Contract Storage.
 
 ```rust
 #[contract_methods]

docs/for_developers/smart_contracts/smart_contract_examples/6_my_pool.md

@@ -59,8 +59,7 @@ After adding the `init()` function, we can try creating a deposit into the pool.
 The staking commands are "deferred" because the actual execution of such commands occurs after the execution of a successful call. 
 
 !!! Note 
-    The deposit is created on behalf of the contract address, not from your account address, so make sure to transfer
-sufficient balance to the contract for the operation.
+    The deposit is created on behalf of the contract address, not from your account address, so make sure to transfer sufficient balance to the contract for the operation.
 
 
 To check if the deposit is successful, you can check the deposit using `pchain-client` with the following [command](../../../for_users/pchain_client_cli/querying_blockchain.md#get-deposit-and-stake):

docs/for_users/pchain_client_cli/creating_transaction.md

@@ -99,7 +99,7 @@ Example - Deploy contract and save to designated file `deposit-tx.json`:
     ./pchain_client transaction create \
     --destination ~/Documents/deposit-tx.json \
     --nonce 0 \
-    --gas-limit 100000 \
+    --gas-limit 500000000 \
     --max-base-fee-per-gas 8 \
     --priority-fee-per-gas 0 \
     deploy \
@@ -111,7 +111,7 @@ Example - Deploy contract and save to designated file `deposit-tx.json`:
     ./pchain_client.exe transaction create `
     --destination ~/Documents/deposit-tx.json `
     --nonce 0 `
-    --gas-limit 100000 `
+    --gas-limit 500000000 `
     --max-base-fee-per-gas 8 `
     --priority-fee-per-gas 0 `
     deploy `
@@ -144,7 +144,10 @@ Example:
     ```
 
 ### Submit Transaction to ParallelChain
-After preparing the transaction json file, you can now submit the transaction with keypair.
+After preparing the transaction json file, you can now submit the transaction with [keypair](../../for_users/pchain_client_cli/managing_account.md/).
+
+!!! Note
+    Executing transactions may require paying for gas fees. If you are testing transactions on Parallelchain Testnet, you can get free testnet tokens from the [Faucet Service](../../fundamentals/networks.md#faucet-service) to pay for the gas fees.
 
 Example:
 

docs/for_users/pchain_client_cli/getting_started.md

@@ -11,7 +11,7 @@ For a detailed description of all available commands, execute `pchain_client --h
 **Usage**
 
 ```terminal
-ParallelChain Client CLI 0.4.3
+ParallelChain Client CLI 0.4.4
 <ParallelChain Lab>
 ParallelChain client (`pchain_client`) is a command-line tool for you to connect and interact with
 the ParallelChain Mainnet/Testnet.
@@ -44,7 +44,7 @@ SUBCOMMANDS:
 2. Unzip the file to extract the executable `pchain_client.exe`.
 3. Open Powershell by pressing *WIN+R* and typing `powershell`.
 4. Navigate to the directory where `pchain_client.exe` is located using the `cd` command. For example, if the executable is located at `C:\Development`, type `cd C:\Development`.
-5. Follow the instructions in Section [Prepare Environment](#prepare-environment) to get ready for interacting with the blockchain.
+5. Follow the instructions in Section [Preparing Environment](#preparing-environment) to get ready for interacting with the blockchain.
 
 ### Linux / macOS
 
@@ -56,14 +56,14 @@ The installation process for Linux and macOS is similar. To install `pchain_clie
 
     === "Linux"
         ```bash
-        tar -xvf pchain_client_linux_v0.4.3.tar.gz 
+        tar -xvf pchain_client_linux_v0.4.4.tar.gz
         ```
     === "macOS"
         ```bash
-        tar -xvf pchain_client_mac_v0.4.3.tar.gz 
+        tar -xvf pchain_client_mac_v0.4.4.tar.gz
         ```
 
-3. Follow the instructions in Section [Prepare Environment](#prepare-environment) to get ready for interacting with the blockchain.
+3. Follow the instructions in Section [Preparing Environment](#preparing-environment) to get ready for interacting with the blockchain.
 
 
 !!! Tips
@@ -85,34 +85,6 @@ The installation process for Linux and macOS is similar. To install `pchain_clie
 !!! note
     If this is your first time using `pchain_client`, you need to set up `$PCHAIN_CLI_HOME` in environment variables to specify the home path. See more [here](https://chlee.co/how-to-setup-environment-variables-for-windows-mac-and-linux/).
 
-## Running pchain_client
-
-### Create Password
-
-For the first time to use `pchain_client`, you need to create your password for using it. The terminal should prompt you as follows:
-
-```text
-First time using ParallelChain Client CLI. Please set up a password to protect your keypairs.
-Your password: 
-```
-
-This password is only used by the CLI, and **NOT** associated with the blockchain. It is used for encryption and decryption of your keypairs so that the keypairs are stored in your computer more securely. Alternatively, you can skip the password protection by simply pressing **Enter**.
-
-You will be required to enter your password twice. If your password is set successfully, you will see a return message with the `pchain_client` version shown on the console.
-
-=== "Linux / macOS"
-    ```bash
-    ./pchain_client --version
-    ```
-=== "Windows PowerShell"
-    ```PowerShell
-    ./pchain_client.exe --version
-    ```
-
-!!! warning
-    The password is not sent and saved anywhere. You won't be able to recover the password if you lose it. Please keep your password safe. You will be required to provide this password to submit transactions and manage keypairs later.
-
-
 ## Preparing Environment
 
 ### Set Environmental Variables
@@ -179,3 +151,30 @@ This would check the status of your chosen provider. If `pchain_client` cannot c
 A `config.toml` file will be created in the folder specified by the environment variable `PCHAIN_CLI_HOME` upon success. It only needs to be executed once.
 
 Now you can start the journey to play around with `pchain_client`!
+
+## Running pchain_client
+
+### Create Password
+
+For the first time to use `pchain_client`, you need to create your password for using it. The terminal should prompt you as follows:
+
+```text
+First time using ParallelChain Client CLI. Please set up a password to protect your keypairs.
+Your password: 
+```
+
+This password is only used by the CLI, and **NOT** associated with the blockchain. It is used for encryption and decryption of your keypairs so that the keypairs are stored in your computer more securely. Alternatively, you can skip the password protection by simply pressing **Enter**.
+
+You will be required to enter your password twice. If your password is set successfully, you will see a return message with the `pchain_client` version shown on the console.
+
+=== "Linux / macOS"
+    ```bash
+    ./pchain_client --version
+    ```
+=== "Windows PowerShell"
+    ```PowerShell
+    ./pchain_client.exe --version
+    ```
+
+!!! warning
+    The password is not sent and saved anywhere. You won't be able to recover the password if you lose it. Please keep your password safe. You will be required to provide this password to submit transactions and manage keypairs later.

docs/for_users/pchain_client_cli/querying_blockchain.md

@@ -10,6 +10,10 @@ tags:
 Use `pchain_client query --help` to check the full list available to query.
 
 ### Check Account Related Information
+
+!!! Note
+    If you don't have access to an account yet, check "See also" under [How Account Works](../../fundamentals/accounts.md#how-account-works) to create an account.
+
 To check Externally Owned Accounts (EOA) information such as balance and nonce, your account address (public key) is always needed.
 
 Commands: