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 two 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.
  • Defines two named keys: counter to reference the contract and an associated variable count to store a value.
  • Provides a function to get the current count (count_get).
  • Provides a function to increment the current count (counter_inc).

• contract-v2

  • This is a second version of the counter contract, which will not be used in this tutorial.
  • This version provides an additional function to decrement the counter and to demonstrate contract upgrades in another tutorial.

• counter-call

• This is session code that retrieves the contract-v1 contract, gets the current count value, increments it, and ensures the count was incremented by 1.

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 account hash and the state-root-hash so that you can get the current snapshot. Once you have that information, you can check the status of the network.

You will need to use the following three commands:

1. casper-client account-address --public-key [PATH_TO_PUBLIC_KEY] - Get the account-hash
2. casper-client get-state-root-hash - Get the state-root-hash
3. casper-client query-state - Query the network state

Run through these commands in order.

casper-client account-address --public-key [PATH_TO_PUBLIC_KEY]

You will need to specify the location of your public-key files. If you used the block explorer to generate the keys, you will need to download them first.

Next, get the state-root-hash:

casper-client get-state-root-hash --node-address http://[NODE_IP]:7777

You need to use the IP address of one of the connected peers on the Testnet as the node server since the network is running in a decentralized fashion. Make a note of the returned state root hash, but keep in mind that this hash value will need to be updated every time you modify the network state.

Please be mindful of the node address format when using the casper-client get-state-root-hash command.

While browsing the connected peers list, you might encounter entries similar to 44.222.236.237:35000. These entries only provide the IP address and port used for peer-to-peer communication within the network.

For the casper-client get-state-root-hash command, you need to modify the address slightly:

1. Add the http:// prefix: This indicates that you're communicating with the node using the HTTP protocol.
2. Replace the port: While the peers list might show a different port (e.g., 35000), the Casper node uses port 7777 for state queries.

Following these steps, the correct command format for your example address would be:

casper-client get-state-root-hash --node-address http://44.222.236.237:7777

Remember to apply this modification to any node address you use with the get-state-root-hash command.

Finally, query the actual state:

casper-client query-global-state \
    --node-address http://[NODE_IP]:7777 \
    --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://[NODE_IP]:7777 \
    --chain-name casper-test \
    --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.
• 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://[NODE_IP]:7777 [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://[NODE_IP]:7777

Get the network state:

casper-client query-global-state \
    --node-address http://[NODE_IP]:7777 \
    --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://[NODE_IP]:7777 \
    --state-root-hash [STATE_ROOT_HASH] \
    --key [ACCOUNT_HASH] -q "counter"

Retrieve the specific count value:

casper-client query-global-state --node-address http://[NODE_IP]:7777 \
    --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://[NODE_IP]:7777 \
    --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://[NODE_IP]:7777 \
    --chain-name casper-test \
    --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 deploy 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://[NODE_IP]:7777

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

casper-client query-global-state --node-address http://[NODE_IP]:7777 \
    --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://[NODE_IP]:7777 \
    --chain-name casper-test \
    --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
    --payment-amount [PAYMENT_AMOUNT_IN_MOTES] \
    --session-path ./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://[NODE_IP]:7777

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

casper-client query-global-state --node-address http://[NODE_IP]:7777 \
    --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 the Testnet!