Tutorial Walkthrough

Now that you are familiar with the basic commands, you can begin the tutorial walkthrough.

Clone the Repository

First, you will need to clone the counter contract repository on our local machine.

git clone https://github.com/casper-ecosystem/counter

If you explore the source code, you will see that there are three versions of the counter contract and one file with session code that calls the contract's entry-points:

• contract-v1

  • This is the first version of the counter contract.
  • It defines two named keys:
    • counter: References the contract itself.
    • count: Stores the current counter value.
  • It provides functions for:
    • get_count: Retrieves the current counter value.
    • counter_inc: Increments the counter value by 1.

• contract-v2 (Not Used in This Tutorial)

  • An extension of contract-v1. It demonstrates decrementing the counter and contract upgrades.

• contract-v3 (Not Used in This Tutorial)

  • This version showcases how to add new functionalities during smart contract upgrades. It extends contract-v1 and contract-v2 by introducing:
    • A new named key: last_updated_at - Tracks the timestamp of the last counter update.
    • A new entry point: get_last_updated_at - Retrieves the last_updated_at timestamp.
  • It focuses on the process of adding new fields like last_updated_at to existing contracts.

• counter-call

  • Session code that retrieves the specific contract version (e.g., contract-v1), interacts with its functions (e.g., get_count, counter_inc), and verifies the expected behavior.

Create a Local Network

After getting familiar with the counter source code, you need to create a local Casper network to install the contract. If you completed the NCTL tutorial, all you need to do is allocate the network assets and then start the network.

If you run the following line in your terminal, you should be able to spin up a network effortlessly.

nctl-assets-setup && nctl-start

note

If it fails for any reason, please refer the NCTL tutorial and make sure that all your packages are up to date.

View the Network State

With a network up and running, you can use the casper-client query-global-state command to check the status of the network. However, you first need an AccountHash and the state-root-hash so that you can get the current snapshot. Once you have that information, check the status of the network.

You will need to use the following three commands:

1. nctl-view-faucet-account - Get the faucet's account hash
2. casper-client get-state-root-hash - Get the state root hash
3. casper-client query-global-state - Get the network state

Run through these commands in order.

nctl-view-faucet-account

If NCTL is correctly up and running, this command should return quite a bit of information about the faucet account. Feel free to look through the records and make a note of the account-hash field and the secret_key.pem path because you will often use both.

Get the state root hash:

casper-client get-state-root-hash --node-address http://localhost:11101

You are using localhost as the node server since the network is running on our local machine. Make a note of the state-root-hash that is returned, but keep in mind that this hash value will need to be updated every time you modify the network state.

Finally, query the actual state:

casper-client query-global-state \
    --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH]

Substitute the state root hash and account hash values you just retrieved into this command and execute it. Do not be surprised if you see nothing on the network. That is because you have not sent anything to the network yet.

Install the Contract

Before installing the contract on the chain, you will need to compile it to Wasm.

The Makefile included in the repository makes compilation trivial. With these two commands, you can build (in release mode) and test the contract before installing it. make prepare sets the Wasm target and make test builds the contracts and verifies them.

cd counter
make prepare
make test

With the compiled contract, you can call the casper-client put-deploy command to install the contract on the chain.

casper-client put-deploy \
    --node-address http://localhost:11101 \
    --chain-name casper-net-1 \
    --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
    --payment-amount [PAYMENT_AMOUNT_IN_MOTES] \
    --session-path ./contract-v1/target/wasm32-unknown-unknown/release/counter-v1.wasm

• Replace the [PATH_TO_YOUR_KEY] field with the actual path of where your secret key is stored. It is one of the fields that gets returned when you call nctl-view-faucet-account.
• The session-path argument should point to wherever you compiled the counter-v1.wasm on your computer. The code snippet shows you the default path if the counter folder is in the same directory.

Once you call this command, it will return a deploy hash. You can use this hash to verify that the deploy successfully took place.

casper-client get-deploy \
    --node-address http://localhost:11101 [DEPLOY_HASH]

View the Updated Network State

Hopefully, the deploy was successful. Call the casper-client query-global-state command to check if the named key is visible on the chain.

note

You must get the new state root hash since you just wrote a deploy to the chain.

If you run these two commands, there will be a new counter named key on the chain.

Get the NEW state-root-hash:

casper-client get-state-root-hash --node-address http://localhost:11101

Get the network state:

casper-client query-global-state \
    --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH]

You can actually dive further into the data stored on the chain using the query path argument or directly querying the deploy hash. Try the following commands and notice that each one gives you a different level of detail.

Retrieve the specific counter contract details:

casper-client query-global-state --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH] -q "counter"

Retrieve the specific count value:

casper-client query-global-state --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH] -q "counter/count"

Retrieve the specific deploy details:

casper-client query-global-state --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] --key deploy-[DEPLOY_HASH]

The first two commands access the counter and count named keys, respectively, using the query path argument. The third command uses the deploy hash (the return value of put-deploy) to query the state of that specific deploy only.

Increment the Counter

You now have a counter on the chain, and you can increment it by calling the entry-point counter_inc, the function defined in the contract. You can call an entry-point in an installed contract by using the put-deploy command as illustrated here:

casper-client put-deploy \
    --node-address http://localhost:11101 \
    --chain-name casper-net-1 \
    --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
    --payment-amount [PAYMENT_AMOUNT_IN_MOTES] \
    --session-name "counter" \
    --session-entry-point "counter_inc"

Notice that this command is nearly identical to the command used to install the contract. However, instead of session-path pointing to the Wasm binary, you have session-name and session-entry-point identifying the on-chain contract and its associated entry-point to execute.

View the Updated Network State Again

After calling the entry-point, theoretically, the count value should increment by one, but how can you be sure of that? You can query the network again, however, remember that you have to get a new state root hash. Check if the count was incremented by looking at it with the query argument.

Get the NEW state-root-hash:

casper-client get-state-root-hash --node-address http://localhost:11101

Get the network state, specifically for the count variable this time:

casper-client query-global-state --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH] -q "counter/count"

You should be able to see the count value and observe that it has increased.

Increment the Counter Again

If you recall, in the repository there is session code called counter-call. Try to increment the count using that session code instead of the session entry-point used above.

Keep in mind, this is another put-deploy call just like when you installed the contract. The session-path is once again going to be different for you depending on where you compiled the contract.

casper-client put-deploy \
    --node-address http://localhost:11101 \
    --chain-name casper-net-1 \
    --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
    --payment-amount [PAYMENT_AMOUNT_IN_MOTES] \
    --session-path ./counter/counter-call/target/wasm32-unknown-unknown/release/counter-call.wasm

View the Final Network State

To make sure that the session code ran successfully, get the new state root hash and query the network.

casper-client get-state-root-hash --node-address http://localhost:11101

Get the network state, specifically for the count variable this time:

casper-client query-global-state --node-address http://localhost:11101 \
    --state-root-hash [STATE_ROOT_HASH]
    --key [ACCOUNT_HASH] -q "counter/count"

If all went according to plan, your count value should be 2 at this point.

Congratulations on building, installing, and using a smart contract on your local network!