Testnet - First Steps - Tezos Developer Portal

Reading Time: 32 min

It is now time to participate in a Tezos network. The Mainnet has been live and open since 30 June 2018. In addition, there are several testnets.

The Mainnet is the main Tezos blockchain, where Tezos tokens (tez) have real value - so play with it only when you are confident in what you are doing.

The easiest way to maintain a Tezos node is to use the docker images that are generated from the Tezos repository on GitLab. They are published on DockerHub and the repository offers a script called tezos-docker-manager.sh, which can pull the necessary images and start a Docker Compose network.

We just need to rename the script into mainnet.sh if we want to participate on the mainnet. After all, the program name called from the Terminal is the first parameter passed to the process.

Docker

Docker offers so-called "software containers" to execute applications. "Container" is a similar concept to that of virtual machines (VM) and uses libcontainer. The isolation level is not as strong as with a VM because Docker containers share the host OS kernel. On the other hand, containers are lighter in weight (Storage, RAM, and CPU) and faster in execution compared to a VM.

Dockerfiles are blueprints for creating Docker Images, which are used to start containers. You can find public images on Docker Hub.

First steps

We will begin our Tezos development on the testnet.

Make sure you have installed Docker!

First, we are going to download the testnet script, make it executable, and run it. Open a terminal (when you see a $ it means it is a terminal command, do not paste the $) and paste the following commands:

$ wget -O hangzhounet.sh https://gitlab.com/tezos/tezos/raw/latest-release/scripts/tezos-docker-manager.sh
$ chmod +x hangzhounet.sh
$ ./hangzhounet.sh start --rpc-port 8732

As the script spins up Docker images, it first needs to download them, and this may take some time. When the images are on your machine, it will start multiple containers. You can inspect them with:

$ docker ps

You should now see something similar to:

In case docker complains about the connection pool, run export COMPOSE_PARALLEL_LIMIT=25 and restart the network.

You can find each component's description in the previous section, Tezos Architecture, and list supported protocols with ./hangzhounet.sh client list understood protocols. Notice, only one protocol is activated at any given time.

From time to time, the tezos-docker-manager.sh script will be updated, and, when you want the latest version, instead of downloading it again with the wget command, you can enter:

$ ./hangzhounet.sh update_script

$ ./hangzhounet.sh restart

Which will stop the network, update the script, and start the network again. In case you want to disable automatic update when restarting, you can use:

$ export TEZOS_ALPHANET_DO_NOT_PULL=yes

When the script is being updated, you may again need the command chmod +x hangzhounet.sh to make it executable.

Wait a few minutes for the node container to start synchronizing with the testnet and then check its logs with:

$ docker logs hangzhounet_node_1 --follow

You should be able to see how it syncs up. To stop the endless logs, press CTRL-C.

Any command starting with ./hangzhounet.sh client will behave as a tezos-client. So, this will be our way to interact with the node container we started.

You can get a list of the commands with:

$ ./hangzhounet.sh client man

You can find the reference for the client commands in the client manual of the Tezos Developer Documentation.

First private key

Before you can send anything on this network, you will need a public-private key pair.

Let us do something basic and create a new key pair, which our local node will know as myFirstKey:

$ ./hangzhounet.sh client gen keys "myFirstKey"

Now, let us take a look at the balance of the test account we just created:

$ ./hangzhounet.sh client get balance for myFirstKey
Warning:
  
                 This is NOT the Tezos Mainnet.
  
          Do NOT use your fundraiser keys on this network.

0 ꜩ

Zero tez! There is no free lunch. Because we do not even have any tez, we cannot pay gas for a transfer or a smart contract operation and there is not much we can do with this account right now.

Adding testnet tez (XTZ)

Let us get some testnet tez to work with! The easiest way to get some testnet tez is through the faucet. It will not only give you free tez but also a brand new wallet (public-private key pair) on Hangzhounet, which you will have to copy into your node container.

Yes, the faucet website created a private key for you and you had to download it. This means that someone, somewhere, could have a copy of your private key. That would not be safe if we were using tez on the mainnet. But we are using Hangzhounet, so we will let it slide this time.

Also remember: The private key created by the faucet is only meant for the testnet. Thus, they are not meant to be used in the mainnet.

Let us say the file you got is tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1.json.

How does the content of this file look?

{
  "mnemonic": [
    "hollow",
    "fruit",
    "ticket",
    "yellow",
    "flush",
    "mule",
    "wrap",
    "used",
    "sound",
    "about",
    "flavor",
    "embody",
    "carry",
    "car",
    "estate"
  ],
  "secret": "caaf49e039da94487321601b2eb1301db959831f",
  "amount": "12710245904",
  "pkh": "tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1",
  "password": "Ww4fHJlnQS",
  "email": "dtubyufk.vxacwchy@tezos.example.org"
}

In it, all seed words, or "secrets", are contained, which we need to create the private key for the public key hash tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1. At a later point in time, we will see how this works when we write a client. As long as we use the tezos-client, we do not need to take care of it.

In a terminal, go to the folder where the file is, and run:

$ docker exec hangzhounet_node_1 whoami                              
tezos
# Just confirming what is the default user

$ docker exec hangzhounet_node_1 id -g -n tezos
nogroup
# Just confirming the group of the default user

$ docker cp tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1.json hangzhounet_node_1:/home/tezos/

# Assigning the account to the tezos account
$ docker exec hangzhounet_node_1 sudo chown tezos:nogroup /home/tezos/tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1.json

Then activate an account with this wallet:

$ ./hangzhounet.sh client activate account faucetWallet with /home/tezos/tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1.json
Node is bootstrapped.
Operation successfully injected in the node.
Operation hash is 'ooZjAiGJcRR3sM26DAnNB6bGbVMuoViKmVthXSAjqzVmTCJn4z5'
Waiting for the operation to be included...
Operation found in block: BLHoZxUARaeQw26DdZLNXWn4vZDM6gnCTpDhUV4s7v5uzEFW1cH (pass: 2, offset: 0)
This sequence of operations was run:
  Genesis account activation:
    Account: tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1
    Balance updates:
      tz1Z47xv2h6GnFvuUUbBz3qTgoNqmiRxZNm1 ... +ꜩ22906.629056

If you want to deploy a contract with this account, make sure your node is sync'd up. You can check if the node is sync'd up with ./hangzhounet.sh client bootstrapped.

If you have difficulties syncing up, you can try to import a snapshot.

Just download a rolling or full snapshot for the testnet, stop the node:

$ ./hangzhounet.sh stop

and import it with:

$ ./hangzhounet.sh clear
$ ./hangzhounet.sh snapshot import FULLPATH/snapshot.full

Please replace FULLPATH with the path of the file, it needs to be an absolute path.

IMPORTANT:

./hangzhounet.sh clear

will remove all blockchain data. So please, if you made good progress with the syncing up and you can estimate the time left, it will be better to wait.

We said that there is a chance that this faucetWallet may be compromised, so it is within the realm of the reasonable to protect our tez in a local-only wallet. Let us do that and transfer some tez from faucetWallet to our myFirstKey account:

$ ./hangzhounet.sh client transfer 1 from faucetWallet to myFirstKey --burn-cap 0.5

After your transaction has been included in a block, your myFirstKey account should have received 1 tez, which you can check again with:

$ ./hangzhounet.sh client get balance for myFirstKey
1 ꜩ

Discuss on Slack

Rate this Page

Thank you for your Feedback!

Testnet - First Steps

Let's participate in a Tezos network

Docker

First steps

First private key

Adding testnet tez (XTZ)