The Tezos Developers' Handbook

Table of contents


Introduction

Dear reader, as of early 2020, the Tezos platform is becoming mature enough that functional and resilient applications can be built with it. Cryptonomic has been building tools for Tezos since late 2017 with the intention of creating a seamless end to end experience for Tezos developers. In this handbook, we provide a variety of resources, tutorials and overviews that will help any blockchain developer get up and running quickly with the Tezos platform.

The quickest way to become productive is to first read the Cryptonomic Stack section followed by the twenty minute tour tutorial. More detailed information about the tools mentioned can be found in the Documentation section. Support is available through Matrix / Riot and email.

This handbook is a living document so it will keep evolving as we add new content, enhance our tools and add new capabilities. Of course, we are also highly receptive to user feedback so expect us to add more content in response to user requests. Speaking of, if you have any ideas for content we should add here, do not hesitate to open a GitHub issue.


The Cryptonomic Stack

The Cryptonomic stack consists of several tools which are build to work seamlessly together. Odds are if you start working with any one of the tools, the rest will be easy for you to adopt.

The stack is great for fetching and viewing blockchain data, deploying and managing smart contracts, building wallets and visualizations and various kinds of developer tooling.

The stack isn't great yet for building user-facing dApps as battle-tested equivalents for MetaMask and other browser plugins are still under development. As we get closer to release for these tools, we will update the documentation here. Maybe you can be the one to build your own tools to make it easy to build Tezos dApps. :)

Nautilus Cloud

Setting up a development environment for blockchains is notoriously hard. It can be quite arduous and time-consuming to stand up blockchain and indexer nodes. Worry not, we do the hard work so you can focus purely on your work. Nautilus Cloud provides hosted Tezos and Conseil nodes so you can use them and get started right away. Once your application is ready for production, you can decide how decentralized you want to be and either continue using Nautilus Cloud or stand up your own nodes.

If you are an Ethereum developer, you can simply think of Nautilus Cloud as an equivalent of Infura, except instead of simply offering you blockchain nodes, Nautilus Cloud also offers indexers and others services to make your dApp more powerful and your life much easier.

Conseil

Pulling data out of blockchains can also be notoriously difficult. Many developers choose to pull data out of their blockchain nodes and store it in a database for easy querying. This is call indexing. Conseil serves as an indexer for the Tezos blockchain. Not only does it provide blockchain data using REST but it also provides metadata to help developers identify and pull the data they need. Nautilus Cloud provides access to Conseil nodes for the major Tezos networks. See the Tutorials section for guides on querying data with Conseil. Conseil is written in the functional style using the Scala programming language.

Notable third-party development libraries which integrate with Conseil include ConseilPy (Python) and TezosKit (Swift) and TezosJ (Android).

ConseilJS

Most front end developers these days like to work with Node libraries. ConseilJS is an NPM library written in TypeScript that allows developers to read from and write to the Tezos blockchain. A variety of applications can be built using ConseilJS. At Cryptonomic, we have used it to build Galleon, Arronax and Mininax, among other projects. ConseilJS is also available as a standalone JavaScript file.

For Ethereum developers, ConseilJS is a rough analogue of web3.js but supports a greater class of functionalities, including key management, hardware wallet connectivity and blockchain data queries.

Galleon

Galleon is a wallet for the Tezos platform. It works equally well with real tez from mainnet and play tez from the major testnet faucets. Developers will find Galleon useful for deploying and invoking smart contracts without writing front end code. This is especially useful if you are simply trying to prototype smart contract code using a tool like SmartPy.

Arronax

Block explorers can be fairly limiting if you are not a regular wallet users. Blockchain developers need to run rich queries to check on their application's behavior, debug issues and get analytics information about app usage. This is why we created Arronax (using Conseil as its data provider). Arronax will allow you to run queries and generate reports tailored to your specific needs. It will help you find your top users, find your biggest transactions and most popular smart contract entry points. Go ahead and give Arronax a spin right now!

Mininax

Sometimes you just want to keep things simple and use a good old block explorer. We built Mininax as a retro mininax explorer serving as an entrypoint into Arronax as a fun summer project using ReasonML. Now it's evolving into a full-fledged explorer in its own right. Soon, there will be features which will make viewing and investigating smart contracts much more intuitive.


Tutorials

The twenty minute tour

In this tutorial, we are going to get a quick taste of the Cryptonomic stack by deploying and examining a simple Tezos smart contract.

If you are not at least mildly familiar with the Cryptonomic stack, it might be worthwhile reading our overview.

We need to get access to the blockchain and its data by visiting Nautilus Cloud and logging in with our GitHub account. Once you are logged in you should see something like this:

List of servers and keys on Nautilus Cloud

Nautilus Cloud offers two environments, 'prod' which runs against the Tezos mainnet and 'dev' which runs against a testnet. For each environment, we get the URL to use to access Conseil and Tezos nodes along with the API keys we need to use. In this tutorial, we will be working with a testnet so let's note the URLs and the Conseil API key (in this case 'ab682065-864a-4f11-bc77-0ef4e9493fa1').

Now we need to get some testnet funds with which we can originate a contract and play with it. Let's download the Galleon wallet and install it on our system. Once the wallet is up, we'll need to click on 'Settings' on the top right and make the wallet point to the testnet by changing the settings for both the Tezos and Conseil nodes:

The Galleon settings page

Let's click on "Back to Wallet" and then "Create new Wallet" to get a new wallet going. Pick a file location and provide a strong password as requested. On the next screen, we'll use the "Import Fundraiser Wallet" option to import a free faucet account with tez for us to play with. Visit the Tezos Faucet and download a JSON document. The document should look something like this:

        {
            "mnemonic": [
                "avocado",
                "settle",
                "lounge",
                "midnight",
                "frozen",
                "fortune",
                "caution",
                "conduct",
                "turtle",
                "slim",
                "repair",
                "venture",
                "short",
                "idea",
                "dawn"
            ],
            "secret": "774ee65fd9cc68c1368e921fd3c5ef0a9368701e",
            "amount": "17214214921",
            "pkh": "tz1RQS5JmG93Cm3tcg7ciWbVTzNTBQT7Qf99",
            "password": "cmaWby2yF6",
            "email": "[email protected]"
            }
    

Transfer the contents of the JSON document into the Galleon import screen so it looks something like this:

Galleon import page

After you hit the Import button and wait for a couple of minutes, you should see your account address and non-zero tez balance:

Galleon home page showing an account with balance

Not bad! We have 17,214 tez to play with!

Now we'll write a very simple Tezos smart contract in SmartPy using the online SmartPy IDE. Here is the code we are going to use:

        import smartpy as sp

        class MyContract(sp.Contract):
            # Sets stored string at initialization.
            def __init__(self, param1):
                self.init(contents = param1)

            # Updates stored string when called.
            @sp.entry_point
            def update(self, params):
                self.data.contents = params

        # Test
        @sp.add_test(name = "TheTest")
        def test():
            # We define a test scenario, together with some outputs and checks
            scenario = sp.test_scenario()

            # We first define a contract and add it to the scenario
            c1 = MyContract("Hello")
            scenario += c1

            # And call some of its entry points
            scenario += c1.update("Goodbye")

            # Finally, we check its final storage
            scenario.verify(c1.data.contents == "Goodbye")
    

This contract simply stores a string. It's given an initial value during origination and it has a function which allows that value to be updated. In the test above, the contract is initialized with "Hello" and is later updated to "World". Very simple! Paste this code into the SmartPy editor and hit the green play button. You should see something like this:

SmartPy editor showing code

The SmartPy editor is a great tool for prototyping Tezos smart contracts. Not only is SmartPy an intuitive Python-like language but the editor allows us to write unit tests to validate our functionality. On the right side, we can see the initial state of the contract as well as the effect of each test. Neat! Feel free to play around with SmartPy later to get a sense of the language and all the functionality of the editor.

Of course, Michelson is the official language of Tezos smart contracts and our code so far is in SmartPy. Click on the Michelson tab in the editor and then 'Code' to get the Michelson code corresponding to the SmartPy code we just wrote:

SmartPy editor showing Michelson

Now we will use Galleon to deploy this contract and, later, call it once. In Galleon, click on "Interact with Contracts" and then "Deploy a New Contract". Change the format to "Michelson", paste in the code from above, set the initial storage to "Hello", pick a high fee and set the gas and storage limits as shown and deploy the contract:

Contract deployment with Galleon

It's a good idea to use high fees on testnets but feel free to choose any appropriate fee during mainnet deployments. After waiting for a couple of minutes, click on the link that shows up and it will direct you to a Mininax page showing details of the origination. Indeed, the initial storage of the deployed contract on the blockchain contains the string "Hello":

Viewing an originated contract in Mininax

Let's invoke the update() function of the smart contract so that the storage contains "Goodbye" instead of "Hello". In Galleon, click on "Interact with contracts" and then "Invoke an Existing Contract". Use the settings shown below:

Contract invocation with Galleon

Once again, we'll wait a couple of minutes before clicking on the link that shows up. Mininax now shows the updated storage value!

Viewing an invoked contract in Mininax

Of course, many of us prefer to deploy and interact with contracts programatically instead of using a GUI wallet. Worry not, we have ConseilJS at our disposal! As you can see in this GitHub gist, both the actions above can be done with a few lines of code. As this is a twenty minute tour, we are not going to look at the specific of the code but here are the most relevant bits for your reference:

      const nodeResult = await TezosNodeWriter.sendContractOriginationOperation(tezosNode, keystore, 0, undefined, fee, '', 1000, 100000, contract, storage, TezosParameterFormat.Michelson);

      const nodeResult = await TezosNodeWriter.sendContractInvocationOperation(tezosNode, keystore, address, 10000, fee, '', freight, gas, entrypoint, parameter, TezosParameterFormat.Michelson);
    

Observe these lines use the settings we obtained from Nautilus Cloud:

      const tezosNode = 'https://tezos-dev.cryptonomic-infra.tech:443';
      const conseilServer = { url: 'https://conseil-dev.cryptonomic-infra.tech:443', apiKey: 'ab682065-864a-4f11-bc77-0ef4e9493fa1', network: 'carthagenet' };
    

Some of the materials in the Documentation section go over the details of contract interaction with ConseilJS.

Now for the final step we can run some simple analytics on our contract using Arronax. A shared report shows us all the invocations of the contract with address KT1EhyNUyAUG42udmJzfAz7WDL2daDNb2cwv deployed and invoked by the ConseilJS code above. The report should look something like this:

Contract invocations in Arronax

Observe, at the time this tutorial was last updated, there were four invocations of the contract and a new string was stored each time. Click the Filter button and see how we are specifically looking at transactions sent to KT1EhyNUyAUG42udmJzfAz7WDL2daDNb2cwv. Feel free to click on columns and try different combinations of columns to explore the dataset. Once you deploy your own smart contracts, you can set up a bunch of reports to analyze things like your contract's top callers, the functions used the most and the peak times when your contract is used. Remember, Arronax runs off Conseil so a Conseil query is being submitted each time you run an Arronax report.

So there you have it, a lightening round through the Cryptonomic stack. Don't hesitate to seek help if any of these bits were confusing for you. Check out the Documentation section to get more in depth information about each product. Happy hacking!

Deploying an FA1.2 fungible token contract

Coming soon..

Analyzing blockchain data using Conseil

Visit the tutorial on the Conseil wiki.

Interacting with the Tezos baker registry

Coming soon..


More Documentation

Coming very soon!