Skip to main content

Testnets

note

This document details the configuration and use of Tezos testnets. If you are looking for information on running or originating to a sandbox, please see the Flextesa documentation here

Introduction​

Taqueria provides support to interact with Tezos networks in a simplified and streamlined manner. Taqueria provides a centralized configuration for testnets (including faucet keys) which can then be targeted by Taqueria commands through the use of Taqueria environments

To work with Taqueria networks, these are the basic steps you need to take:

  1. Configure and name a network in the Taqueria config.json file
  2. Add a faucet key
  3. Add the created network to an environment
  4. Target the network in Taqueria by passing the environment name to the CLI command (ie. taq originate --env ithacanet)

Requirements​

note

Currently Taqueria only supports testnets. Support for mainnet will be added in a future release

To configure and use a Taqueria network, you will require the following:

  1. Configuration details for the network you wish to target (Can be found at teztnets.xyz)
  2. A faucet key for the network you wish to target (Also found at teztnets.xyz)
  3. The Taquito plugin (Used for originating to a network)

Supported Protocols​

Taqueria will support all protocols available on the teztnets.xyz site. If you notice an issue with a recent protocol update, please report it as a bug here

Configuration​

note

The network configuration for various protocols, as well as the faucet for each can be found at teztnets.xyz.

To configure a network for use, you will need to configure the network, and then add that network to an environment. To illustrate the configuration of a network, we will use the ithaca testnet as an example in this document and will configure a network named ithaca, and an environment named ithacanet

Taqueria does not have a default network configured, so a freshly initialized project will have a config.json file that looks like this:

{
    "language": "en",
    "plugins": [],
    "contractsDir": "contracts",
    "testsDir": "tests",
    "artifactsDir": "artifacts",
    "environment": {
        "default": "development",
        "development": {
            "networks": [],
            "sandboxes": [
                "local"
            ],
            "storage": {}
        }
    },
    "sandbox": {
        "local": {
            "label": "Local Tezos Sandbox",
            "protocol": "Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
            "rpcUrl": "http://localhost:20000"
        }
    },
    "network": {},
    "accounts": {
        "bob": "3_000_000_000",
        "alice": "3_000_000_000",
        "john": "3_000_000_000",
        "jane": "3_000_000_000",
        "joe": "3_000_000_000"
    }
}

Network Configuration​

The first step is to add a named network configuration to your config.json file

Add the following entry ("ithacanet": {...}) to the network property::

{
   "network":{
      "ithacanet":{
         "label":"Ithaca Protocol Testnet",
         "rpcUrl":"https://rpc.ithacanet.teztnets.xyz",
         "protocol":"Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
         "faucet":{  }
      }
   }
note

The information for rpcUrl andprotocol are taken from the https://teztnets.xyz/ithacanet-about page

Faucets​

In order to interact with the network, you will need some Tez in an account. The way this is done on Tezos is to provide a faucet key. The faucet key provides Tez on a particular testnet, which can then be used to interact with the network

To get your own unique faucet key for testing, visit https://teztnets.xyz/ithacanet-faucet, and complete the captcha validation. Once this is done, you will see the faucet key shown as a JSON object

To add the faucet key to your Taqueria project, simply copy and paste the JSON object into the faucet field of the network configuration shown above

Your network property should now look something like this:

{
   "network":{
      "ithaca":{
         "label":"Ithaca Protocol Testnet",
         "rpcUrl":"https://rpc.ithacanet.teztnets.xyz",
         "protocol":"Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
         "faucet":{
            "key": {
                "pkh": "tz1cEqJmGnzcGDa9cyj437RmLL5GYPiawiUc",
                "mnemonic": [
                    "other",
                    "nerve",
                    "awkward",
                    "jaguar",
                    "anchor",
                    "conduct",
                    "drill",
                    "upon",
                    "roof",
                    "planet",
                    "glass",
                    "among",
                    "turkey",
                    "also",
                    "urban"
                ],
                "email": "kgwzskbc.tootktlz@teztnets.xyz",
                "password": "JTMMX6FPNM",
                "amount": "2006437205",
                "activation_code": "50fe648444288c8dd1fe1e976ca26160536fda94"
            }
         }
      }
   }
}

Environment Configuration​

The final step in configuration is to add the network to an environment. In this example, we will create a new environment named ithacanet which will contain the ithaca network

To do this, find the environment property in your config.json file. By default it will look something like this:

    "environment": {
        "default": "development",
        "development": {
            "networks": [],
            "sandboxes": [
                "local"
            ],
            "storage": {}
        },
    },

Add a new environment named ithacanet, and add the named network ithaca to its networks array:

    "environment": {
        "default": "development",
        "development": {
            "networks": [],
            "sandboxes": [
                "local"
            ],
            "storage": {}
        },
        "ithacanet": {
            "networks": [
                "ithaca"
            ],
            "sandboxes": [
                "local"
            ],
            "storage": {}
        }
    },
note

For additional information regarding Taqueria Environments, please see the documentation here

Finished Configuration​

At this point, you should have a fully configured network named ithaca which is configured to target Ithacanet using a faucet, and an environment named ithacanet which can be used to target the network from the CLI

Your config.json file should look something like this: 

{
    "language": "en",
    "plugins": [],
    "contractsDir": "contracts",
    "testsDir": "tests",
    "artifactsDir": "artifacts",
    "environment": {
        "default": "development",
        "development": {
            "networks": [],
            "sandboxes": [
                "local"
            ],
            "storage": {}
        },
        "ithacanet": {
            "networks": [
                "ithaca"
            ],
            "sandboxes": [],
            "storage": {}
        }
    },
    "sandbox": {
        "local": {
            "label": "Local Tezos Sandbox",
            "protocol": "Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
            "rpcUrl": "http://localhost:20000"
        }
    },
    "network": {
        "ithaca":{
            "label":"Ithaca Protocol Testnet",
            "rpcUrl":"https://rpc.ithacanet.teztnets.xyz",
            "protocol":"Psithaca2MLRFYargivpo7YvUr7wUDqyxrdhC5CQq78mRvimz6A",
            "faucet":{
               "key": {
                   "pkh": "tz1cEqJmGnzcGDa9cyj437RmLL5GYPiawiUc",
                   "mnemonic": [
                       "other",
                       "nerve",
                       "awkward",
                       "jaguar",
                       "anchor",
                       "conduct",
                       "drill",
                       "upon",
                       "roof",
                       "planet",
                       "glass",
                       "among",
                       "turkey",
                       "also",
                       "urban"
                   ],
                   "email": "kgwzskbc.tootktlz@teztnets.xyz",
                   "password": "JTMMX6FPNM",
                   "amount": "2006437205",
                   "activation_code": "50fe648444288c8dd1fe1e976ca26160536fda94"
               }
            }
         }
      }
    },
    "accounts": {
        "bob": "3_000_000_000",
        "alice": "3_000_000_000",
        "john": "3_000_000_000",
        "jane": "3_000_000_000",
        "joe": "3_000_000_000"
    }
}

Targeting a Network​

Taqueria uses Environments to target a specific network or sandbox. An environment is a named collection of network configurations which can be passed to the CLI using the --env flag

To target the ithaca network we configured above using the ithacanet environment, simply run the following command:

taq originate --env ithacanet