{"id":13767671,"url":"https://github.com/blockwatch-cc/tzgo","last_synced_at":"2025-05-10T23:30:50.874Z","repository":{"id":37540421,"uuid":"350218724","full_name":"blockwatch-cc/tzgo","owner":"blockwatch-cc","description":"Golang library for the Tezos blockchain","archived":true,"fork":false,"pushed_at":"2024-05-13T11:33:27.000Z","size":2294,"stargazers_count":46,"open_issues_count":3,"forks_count":29,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-07T03:07:58.281Z","etag":null,"topics":["blockchain","sdk","tezos"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockwatch-cc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-22T05:30:38.000Z","updated_at":"2025-03-05T14:02:43.000Z","dependencies_parsed_at":"2023-10-16T23:58:28.181Z","dependency_job_id":"adeac12a-cd83-4348-a2e1-c2b3e79bcf08","html_url":"https://github.com/blockwatch-cc/tzgo","commit_stats":{"total_commits":414,"total_committers":9,"mean_commits":46.0,"dds":"0.033816425120772986","last_synced_commit":"f83c3f56b23141dc60a4241fcaa636e481907b8e"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockwatch-cc%2Ftzgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockwatch-cc%2Ftzgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockwatch-cc%2Ftzgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockwatch-cc%2Ftzgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockwatch-cc","download_url":"https://codeload.github.com/blockwatch-cc/tzgo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253497296,"owners_count":21917683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","sdk","tezos"],"created_at":"2024-08-03T16:01:10.867Z","updated_at":"2025-05-10T23:30:49.976Z","avatar_url":"https://github.com/blockwatch-cc.png","language":"Go","funding_links":[],"categories":["Development"],"sub_categories":["Libraries"],"readme":"## Blockwatch TzGo - Tezos Go SDK\n\n\u003e Note: From Tezos Paris onwards development of TzGo has moved to https://github.com/trilitech/tzgo. This repository is kept as a public archive for older versions. Please update your import paths.\n\nTzGo is [Blockwatch](https://blockwatch.cc)'s low-level Tezos Go SDK for reliable, high-performance applications. This SDK is free to use in commercial and non-commercial projects with a permissive license. Blockwatch is committed to keeping interfaces stable, providing long-term support, and updating TzGo on a regular basis to stay compliant with the most recent Tezos network protocol.\n\nTzGo's main focus is on **correctness**, **stability**, and **compliance** with Tezos mainnet. It supports binary and JSON encodings for all Tezos types including Micheline smart contract data and all transaction formats. It's an ideal fit for high-performance applications that read from and write to the Tezos blockchain.\n\nCurrent Tezos protocol support in TzGo\n\n- Oxford v018\n- Nairobi v017\n- Mumbai v016\n- Lima v015\n- Kathmandu v014\n- Jakarta v013\n- Ithaca v012\n- Hangzhou v011\n- Granada v010\n- Florence v009\n- Edo v008\n- Delphi v007\n- Carthage v006\n- Babylon v005\n- Athens v004\n- Alpha v001-v003\n\n### SDK features\n\nTzGo contains a full set of features to read, monitor, decode, translate, analyze and debug data from the Tezos blockchain, in particular from Tezos smart contracts:\n\n- a low-level **Types library** `tzgo/tezos` to handle hashes, addresses, keys, signatures other types found on-chain\n- a powerful **Micheline library** `tzgo/micheline` to decode and translate data found in smart contract calls, storage, and bigmaps\n- an **RPC library** `tzgo/rpc` for accessing the Tezos Node RPC\n- a **Codec library** `tzgo/codec` to construct and serialize operations\n- a **Contract library** `tzgo/contract` for smart contract calls and tokens\n- a **Signer library** `tzgo/signer` to sign transactions local or remote\n- helpers like an efficient base58 en/decoder, hash maps, etc\n- a **Code generator** [TzGen](https://github.com/blockwatch-cc/tzgo/tree/master/cmd/tzgen) to produce pure Go clients for smart contract interfaces\n- an **Automation Tool** [TzCompose](https://github.com/blockwatch-cc/tzgo/tree/master/cmd/tzcompose) to setup test cases and deploy complex contract ecosystems\n\n### TzGo Compatibility\n\nTzGo's RPC package attempts to be compatible with all protocols so that reading historic block data is always supported. Binary transaction encoding and signing support is limited to the most recent protocol.\n\nWe attempt to upgrade TzGo whenever new protocols are proposed and will add new protocol features as soon as practically feasible and as demand for such features exists. For example, we don't fully Sapling and BLS signatures yet, but may add support in the future.\n\n### Usage\n\n```sh\ngo get -u blockwatch.cc/tzgo\n```\n\nThen import, using\n\n```go\nimport (\n\t\"blockwatch.cc/tzgo/codec\"\n\t\"blockwatch.cc/tzgo/tezos\"\n\t\"blockwatch.cc/tzgo/micheline\"\n\t\"blockwatch.cc/tzgo/rpc\"\n\t\"blockwatch.cc/tzgo/wallet\"\n)\n```\n\n### Micheline Support\n\nTezos uses [Micheline](https://tezos.gitlab.io/shell/micheline.html) for encoding smart contract data and code. The positive is that Micheline is strongly typed, the downside is that it's complex and has a few ambiguities that make it hard to use. TzGo contains a library that lets you decode, analyze and construct compliant Micheline data structures from Go.\n\nMicheline uses basic **primitives** for encoding types and values. These primitives can be expressed in JSON and binary format and TzGo can translate between them efficiently. Micheline also supports type **annotations** which are used by high-level languages to express complex data types like records and their field names.\n\nTzGo defines a basic `Prim` data type to work with Micheline primitives directly:\n\n```go\ntype Prim struct {\n\tType      PrimType // primitive type\n\tOpCode    OpCode   // primitive opcode (invalid on sequences, strings, bytes, int)\n\tArgs      []Prim   // optional nested arguments\n\tAnno      []string // optional type annotations\n\tInt       *big.Int // decoded value when Prim is an int\n\tString    string   // decoded value when Prim is a string\n\tBytes     []byte   // decoded value when Prim is a byte sequence\n\tWasPacked bool     // true when content has been unpacked\n}\n```\n\nSince Micheline value encoding is quite verbose and can be ambiguous, TzGo supports **unfolding** of raw Micheline using the following TzGo wrapper types and their helper functions like `Map()`, `GetInt64()`, `GetAddress()`:\n\n- `Type` is a TzGo wrapper for simple or complex primitives which contain annotated type info\n- `Value` is a TzGo wrapper for simple or complex primitives representing Micheline values in combination with their Type\n- `Key` is a TzGo wrapper for special comparable values that are used as maps or bigmap keys\n\nSometimes Micheline values have been packed into byte sequences with the Michelson PACK instruction and it is desirable to unpack them before processing (e.g. to retrieve UFT8 strings or nested records). TzGo supports `Unpack()` and `UnpackAll()` functions on primitives and values and also detects the internal type of packed data which is necessary for unfolding.\n\n\n### Examples\n\nBelow are a few examples showing how to use TzGo to easily access Tezos data in your application.\n\n#### Parsing an address\n\nTo parse/decode an address and output its components you can do the following:\n\n```go\nimport \"blockwatch.cc/tzgo/tezos\"\n\n// parse and panic if invalid\naddr := tezos.MustParseAddress(\"tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9\")\n\n// parse and return error if invalid\naddr, err := tezos.ParseAddress(\"tz3RDC3Jdn4j15J7bBHZd29EUee9gVB1CxD9\")\nif err != nil {\n\tfmt.Printf(\"Invalid address: %v\\n\", err)\n}\n\n// Do smth with the address\nfmt.Printf(\"Address type = %s\\n\", addr.Type)\nfmt.Printf(\"Address bytes = %x\\n\", addr.Hash)\n\n```\n\nSee [examples/addr.go](https://github.com/blockwatch-cc/tzgo/blob/master/examples/addr/main.go) for more.\n\n#### Monitoring for new blocks\n\nA Tezos node can notify applications when new blocks are attached to the chain. The Tezos RPC calls this monitor and technically it's a long-poll implementation. Here's how to use this feature in TzGo:\n\n```go\nimport \"blockwatch.cc/tzgo/rpc\"\n\n// init SDK client\nc, _ := rpc.NewClient(\"https://rpc.tzstats.com\", nil)\n\n// create block header monitor\nmon := rpc.NewBlockHeaderMonitor()\ndefer mon.Close()\n\n// all SDK functions take a context, here we just use a dummy\nctx := context.TODO()\n\n// register the block monitor with our client\nif err := c.MonitorBlockHeader(ctx, mon); err != nil {\n\tlog.Fatalln(err)\n}\n\n// wait for new block headers\nfor {\n\thead, err := mon.Recv(ctx)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\t// do smth with the block header\n\tfmt.Printf(\"New block %s\\n\", head.Hash)\n}\n\n```\n\n#### Fetch and decode contract storage\n\n```go\nimport (\n\t\"blockwatch.cc/tzgo/micheline\"\n\t\"blockwatch.cc/tzgo/rpc\"\n\t\"blockwatch.cc/tzgo/tezos\"\n)\n\n// we use the Baker Registry on mainnet as example\naddr := tezos.MustParseAddress(\"KT1ChNsEFxwyCbJyWGSL3KdjeXE28AY1Kaog\")\n\n// init RPC client\nc, _ := rpc.NewClient(\"https://rpc.tzstats.com\", nil)\n\n// fetch the contract's script and most recent storage\nscript, _ := c.GetContractScript(ctx, addr)\n\n// unfold Micheline storage into human-readable form\nval := micheline.NewValue(script.StorageType(), script.Storage)\nm, _ := val.Map()\nbuf, _ := json.MarshalIndent(m, \"\", \"  \")\nfmt.Println(string(buf))\n```\n\n#### Decode contract call parameters\n\n```go\nimport (\n\t\"blockwatch.cc/tzgo/micheline\"\n\t\"blockwatch.cc/tzgo/rpc\"\n\t\"blockwatch.cc/tzgo/tezos\"\n)\n\n// init RPC client\nc, _ := rpc.NewClient(\"https://rpc.tzstats.com\", nil)\n\n// assuming you have this transaction\ntx := block.Operations[3][0].Contents[0].(*rpc.TransactionOp)\n\n// load the contract's script for type info\nscript, err := c.GetContractScript(ctx, tx.Destination)\n\n// unwrap params for nested entrypoints\nep, param, err := tx.Parameters.MapEntrypoint(script.ParamType())\n\n// convert Micheline param data into human-readable form\nval := micheline.NewValue(ep.Type(), param)\n\n// e.g. access individual nested fields using value helpers\nfrom, ok := val.GetAddress(\"transfer.from\")\n```\n\n#### Use TzGo's Value API\n\nMicheline type and value trees are verbose and can be ambiguous due to comb-pair optimizations. If you don't know or don't care about what that even means, you may want to use the `Value` API which helps you translate Micheline into human readable form.\n\nThere are multiple options to access decoded data:\n\n```go\n// 1/\n// decode into a Go type tree using `Map()` which produces\n// - `map[string]interface{}` for records and maps\n// - `[]interface{}` for lists and sets\n// - `time.Time` for time values\n// - `string` stringified numbers for Nat, Int, Mutez\n// - `bool` for Booleans\n// - `tezos.Address` for any string or bytes sequence that contains an address\n// - `tezos.Key` for keys\n// - `tezos.Signature` for signatures\n// - `tezos.ChainIdHash` for chain ids\n// - hex string for untyped bytes\n// - opcode names for any Michelson opcode\n// - opcode sequences for lambdas\nm, err := val.Map()\nbuf, err := json.MarshalIndent(m, \"\", \"  \")\nfmt.Println(string(buf))\n\n// when you know the concrete type you can cast directly\nfmt.Println(\"Value=\", m.(map[string]interface{})[\"transfer\"].(map[string]interface{})[\"value\"])\n\n// 2/\n// access individual nested fields using value helpers (`ok` is true when the field\n// exists and has the correct type; helpers exist for\n//   GetString() (string, bool)\n//   GetBytes() ([]byte, bool)\n//   GetInt64() (int64, bool)\n//   GetBig() (*big.Int, bool)\n//   GetBool() (bool, bool)\n//   GetTime() (time.Time, bool)\n//   GetAddress() (tezos.Address, bool)\n//   GetKey() (tezos.Key, bool)\n//   GetSignature() (tezos.Signature, bool)\nfrom, ok := val.GetAddress(\"transfer.from\")\n\n// 3/\n// unmarshal the decoded Micheline parameters into a json-tagged Go struct\ntype FA12Transfer struct {\n    From  tezos.Address `json:\"from\"`\n    To    tezos.Address `json:\"to\"`\n    Value int64         `json:\"value,string\"`\n}\n\n// FA1.2 params are nested, so we need an extra wrapper\ntype FA12TransferParams struct {\n\tTransfer FA12Transfer `json:\"transfer\"`\n}\n\nvar transfer FA12TransferParams\nerr := val.Unmarshal(\u0026transfer)\n```\n\n#### List a contract's bigmaps\n\n```go\nimport (\n\t\"blockwatch.cc/tzgo/micheline\"\n\t\"blockwatch.cc/tzgo/rpc\"\n\t\"blockwatch.cc/tzgo/tezos\"\n)\n\n// we use the hic et nunc NFT market on mainnet as example\naddr := tezos.MustParseAddress(\"KT1Hkg5qeNhfwpKW4fXvq7HGZB9z2EnmCCA9\")\n\n// init RPC client\nc, _ := rpc.NewClient(\"https://rpc.tzstats.com\", nil)\n\n// fetch the contract's script and most recent storage\nscript, _ := c.GetContractScript(ctx, addr)\n\n// bigmap pointers as []int64\nids := script.BigmapsById()\n\n// bigmap pointers as named map[string]int64 (names from type annotations)\nnamed := script.BigmapsByName()\n\n```\n\n#### Fetch and decode bigmap values\n\n```go\n// init RPC client\nc, _ := rpc.NewClient(\"https://rpc.tzstats.com\", nil)\n\n// load bigmap type info (use the Baker Registry on mainnet as example)\nbiginfo, _ := c.GetBigmapInfo(ctx, 17)\n\n// list all bigmap keys\nbigkeys, _ := c.GetBigmapKeys(ctx, 17)\n\n// visit each value\nfor _, key := range bigkeys {\n\tbigval, _ := c.GetBigmapValue(ctx, 17, key)\n\n\t// unfold Micheline type into human readable form\n\tval := micheline.NewValue(micheline.NewType(biginfo.ValueType), bigval)\n\tm, _ := val.Map()\n\tbuf, _ := json.MarshalIndent(m, \"\", \"  \")\n\tfmt.Println(string(buf))\n}\n```\n\n#### Custom RPC client configuration\n\nTzGo's `rpc.NewClient()` function takes an optional Go `http.Client` as parameter which you can configure before or after passing it to the library. The example below shows how to set custom timeouts and disable TLS certificate checks (not recommended in production, but useful if you use self-signed certificates during testing).\n\n\n```go\nimport (\n\t\"crypto/tls\"\n\t\"log\"\n\t\"net\"\n\t\"net/http\"\n\n\t\"blockwatch.cc/tzgo/rpc\"\n)\n\n\nfunc main() {\n\thc := \u0026http.Client{\n\t\tTransport: \u0026http.Transport{\n\t\t\tDial: (\u0026net.Dialer{\n\t\t\t\tTimeout:   2 * time.Second,\n\t\t\t\tKeepAlive: 180 * time.Second,\n\t\t\t}).Dial,\n\t\t\tTLSClientConfig: \u0026tls.Config{\n\t\t\t\tInsecureSkipVerify: true,\n\t\t\t}\n\t\t}\n\t}\n\n\tc, err := rpc.NewClient(\"https://my-private-node.local:8732\", hc)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n}\n```\n\n\n## License\n\nThe MIT License (MIT) Copyright (c) 2020-2024 Blockwatch Data Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is furnished\nto do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockwatch-cc%2Ftzgo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockwatch-cc%2Ftzgo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockwatch-cc%2Ftzgo/lists"}