TzGo SDK Installation

TzGo is open-source software and available on Github at blockwatch-cc/tzgo. The complete GoDoc documentation for TzGo is available at pkg.go.dev/blockwatch.cc/tzgo.

Download and install TzGo

go get -u blockwatch.cc/tzgo

Then import, using

import (
    "blockwatch.cc/tzgo/codec"
    "blockwatch.cc/tzgo/tezos"
    "blockwatch.cc/tzgo/micheline"
    "blockwatch.cc/tzgo/rpc"
    "blockwatch.cc/tzgo/wallet"
)

Initializing the TzGo SDK Client

TzGo's RPC package exports a RPC Client object which can be used to fetch data from the Tezos RPC or send transactions. To create and configure a new client call

// create a client
c, err := rpc.NewClient("https://rpc.tzpro.io", nil)

// set an API key if you use the TzPro API
c.ApiKey = "YOUR-TZPRO-API-KEY"

You can also export your TzPro API as environment variable before launching your Go program

export TZGO_API_KEY=YOUR-TZPRO-API-KEY

It is safe to use multiple client objects in your application. Each client is also concurrency safe, meaning you can share it between multiple Goroutines.

If you're running on a sandbox network with custom parameters or you want to make sure that your app is connected to the intended network (mainnet or a testnet) you should call init:

err := c.Init(context.Background())

If you send transactions and want to stay informed about execution status, its a good idea to also start the built-in observers right away:

c.Listen()

To shutdown observers call

c.Close()

Custom RPC client configuration

TzGo's rpc.NewClient() function takes a standard Go http.Client as optional second argument. You can use this to pass a pre-configured HTTP client with custom timeouts, TLS settings and more into the library. The example below shows how to set timeouts and disable TLS certificate checks (not recommended in production, but useful if you use self-signed certificates during testing).

import (
    "crypto/tls"
    "log"
    "net"
    "net/http"

    "blockwatch.cc/tzgo/rpc"
)


func main() {
    hc := &http.Client{
        Transport: &http.Transport{
            Dial: (&net.Dialer{
                Timeout:   2 * time.Second,
                KeepAlive: 180 * time.Second,
            }).Dial,
            TLSClientConfig: &tls.Config{
                InsecureSkipVerify: true,
            }
        }
    }

    c, err := rpc.NewClient("https://my-private-node.local:8732", hc)
    if err != nil {
        log.Fatalln(err)
    }
}

History Modes

Tezos nodes can run in different history modes which keep different amounts of historic data around. All nodes, when fully synchronized, will always have state at the head and a few cycles in the past available. Only archive nodes will keep block metadata and historic account/contract states for all blocks in history, so if your application has the need to query old state it must run against an archive node. During the initial node synchronization, most RPC endpoints will return 404 or 5xx errors until the node has completed sync once.

ACL

Depending on where your TzGo application and Tezos nodes run you way want to enable localhost access --rpc-addr localhost:8732 or remote access --rpc-addr :8732. Since some RPCs may be resource intensive, the default policy in Tezos is to deny remote public access to all endpoints (only localhost access is permitted). If you experience the following error

error: The server doesn't authorize this endpoint (ACL filtering). 

you may change the ACL policy in the node's configuration setting or by adding --allow-all-rpc 0.0.0.0 when starting your node. Only do this if your node is not reachable on a public IP address or if you have additional protection in place, e.g. in a reverse proxy that blocks critical endpoints.

When running the node inside a Docker container, you must set an ACL policy (or disable it like above) since Docker uses an internal network interface and its own IP range that does not match the default localhost rules in Tezos.