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.
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
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:
nctl-view-faucet-account- Get the faucet's account hashcasper-client get-state-root-hash- Get the state root hashcasper-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.
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!