GoTezos Q3 Update

6 min readSep 28, 2020

Summary

This document serves as a technical update on the progress of the GoTezos software library for Q3 (July-September).

Improvements

The focus of quarter 3 has largely been around the block structure, expansion of local forging, input validation, smart contract interaction, FA1.2 contracts, big_map’s, key management, and general refactoring.

Block Structure

Previously in GoTezos the Block structure implementation was incomplete. It was missing important details around operation results, internal operations, entry points, big_map diffs and many of the foundational ground work to ultimately support interacting with smart contracts. I’m pleased to announce that all of the missing information in the block structure has been fixed, with the addition of some helper functions that make reading and consuming operation contents pragmatically easier.

As an example the contents of an operation looks like this. There are a lot of fields in the contents structure that are only related to a certain type of operation, many of them will be omitted based on the operation type. As a developer it may get confusing to understand which fields in the contents structure belong to which operation. To help mitigate this I have created helper functions to convert the contents of an operation into an organized structure (OrganizedContents) based on operation types. You can now take an entire array of contents and organize them by kind with the contents.Organize() function.

Additionally you can take an individual content and convert it to a single operation if you are only concerned about a single element in a contents array. As an example see the content.ToTransaction() function. The function will return a Transaction structure which helps the developer identify the specific fields a Transaction operation can have.

You can also do the reverse transition by converting OrganizedContents back into the normal Contents array. Or a single operation back into a normal content. This is particularly helpful when forging operations (more on this later). Additionally the same set of features describe above for operations contents are available for BigMapDiffs to help you organize them by the type of action.

Expansion of Local Forging

In the previous version of GoTezos local forging was only fully supported for Delegations, and Revelations. And it was partially supported for Transactions and Originations. You were not able to originate a smart contract by locally forging one, or interact with a smart contract through a transfer because Michelson was unsupported. There is virtually no documentation that exists around locally forging operations in Tezos, only an RPC that requires a network call. Using a network call to forge an operation carries a significant amount of risk because of the blind signature attack.

Thanks to the Baking Bad Team I was able to reverse engineer some of their open source code to support the local forging for all Tezos operations including the forging of Michelson. Local forging now includes support for the following:

Circling back to the organization of contents and where the usefulness comes in. Say I wanted to forge a transaction but wasn’t sure what the required content fields were to do so. I would simply use the Transaction structure. Take a look at this example.

You could also use the Contents structure directly if you knew exactly what you were doing, but you would miss out on the added input validation benefits.

Input Validation

Another improvement added to GoTezos is the expansive use of input validation. Each and every function in GoTezos takes in a structure (excluding single parameter functions). And all required fields in each structure are validated before the function can successfully execute. This improves code correctness and decreases the likelihood of a developer error when invoking the RPC. Passing structures as input also improves the support for backwards compatibility between future GoTezos versions.

You can quickly see which fields are required in a structure by viewing the structure definition. Take a look at the Transaction structure again and pay special notice to the validate:”required” tag next to required fields. Any time a field in a structure has this tag, it means that when using the structure the field must be populated. If it is not populated, the function that consumes the structure will immediately return an error containing information on the missing field.

Smart Contract Interaction

As a result of the fixes with the block structure as well as the expansion of local forging, GoTezos is now completely compatible to interact with any smart contract on the Tezos network in a safe way. GoTezos supports the forging of “core” entrypoints in smart contracts such as default, root, do, set_delegate, and remove_delegate, and also any arbitrary entrypoints set by the user.

FA1.2 contracts

FA1.2 (TZIP-7) contracts are hot item in Tezos and allow for the tokenization of real world assets. Interactions with these contracts will be fairly common and because of that it made sense to include some generic FA1.2 functions to enable interaction.

This functionality might be particularly interesting because the entrypoints in an FA1.2 contract are designed in such a way that they are meant to be called from other smart contracts and not directly by a manager key.

Thanks to camlCase and a talented developer there, James Haver, building this functionality wasn’t incredibly trivial due to an existing guide.

GoTezos supports the following entrypoints for FA1.2 contracts:

getAllowance: Gets the allowance of a spender on behalf of an owner.
getBalance: Gets the balance of an owner.
getTotalSupply: Gets the total supply of the FA1.2 contract.

Big Maps

If you are unfamiliar with big_map’s, take a look at this stack exchange post. A big_map is basically an optimized and gas efficient key value storage for smart contracts. The GoTezos Block structure fixes include support for reading big_map diffs inside a block, and now GoTezos also includes support for interacting with big_maps.

This functionality is particularly challenging because of the lack of proper documentation around using the big_map’s RPC. Specifically the RPC requires a script_expr but the documentation does not describe what the script_expr is, or how to forge one.

There is a small tutorial on stack exchange that shows how to forge a script_expr with the tezos-client here. But I have struggled to find information on to forge a script_expr pragmatically.

That being said there is support for the big_map RPC in general here. I was able to reverse engineer local forging of the script_expr for big_map keys that are of the manager key type, tz1, tz2, tz3 thanks to camlCase’s reasonML lib.

You can find the GoTezos code script_exp here.

Key Management

In the previous version of GoTezos key management was fairly messy and poorly designed. Inspired by the Baking Bad Team again I have restructured key management to be similar to their key management in NeTezos (A C# lib).

General Refactoring

GoTezos V2 was becoming somewhat unorganized with everything included in a single Go Module. I refactored GoTezos V3 into 3 submodules including the rpc module, the forging module, and the keys module.

Q4 Road Map

Support other Key Types:

Add support for the following keys (tz2, tz3):

Secp256k1
NistP256

Ledger Support

Add support for interacting with Ledger products.

Increase FA1.2 Support

Missing entrypoint transfer
Missing entrypoint approve

Support For All Big Map Key Types

As discussed in the big_map section, there is limited documentation on forging script_expr. I would like to expand local forging for all supported big_map key types.

Delphinet

Assuming delphinet gets voted in through the Tezos governance process, most likely it will, I will adjust GoTezos to support the new protocol. Additionally if time permits I would like to add functions for interacting with the Sapling’s smart contract that will be available for transaction anonymity.

Conclusion

Not all additions and improvement to the library are talked about in this medium post, but all of the notable improvements were. If you would like to see the commits made during Q3 for GoTezos V3 you can find them in this pull request.

I look forward to the features to be added in Q4, and am thankful for the support of the Tezos Foundation, TQ Tezos, and the Tezos community.

Bonus

Outside of the perspective of the grant, I have also been adding additional features to tzpay. Tzpay is a baker’s tool to handle and manage payouts to their delegations and is powered by GoTezos. Because of the recent support for smart contracts and big_map’s in GoTezos, tzpay will be the first tool in the Tezos ecosystem to support payouts to participants in Dexter liquidity contracts. GoTezos is also being used to aggregate FA1.2 contract data to the dexter frontend in a service called Indexter.