We're thrilled to announce the latest addition to the Blockwatch TzGo SDK: TzCompose, an automation framework for complex transaction sequences on Tezos.

With TzCompose, you write YAML files to configure pipelines from different kinds of tasks, then run a single command that automatically executes these pipelines on-chain. TzCompose works across all Tezos networks and even supports cloning contracts and transaction sequences between them.

Use TzCompose for automating workflows such as:

  • smart contract deployment and maintenance
  • traffic generation for protocol and application testing
  • test-case setups
  • cloning contract deployments and setup logic between networks

💡 Whether you're a dapp developer, protocol engineer, generative artist or any other enthusiast building on Tezos – TzCompose will make your life so much easier.

Getting Started

TzCompose is available as part of the Blockwatch TzGo SDK  and you need a Go compiler >=1.18 to use it. The easiest way to run TzCompose is 

# directly from the Git repo
go run blockwatch.cc/tzgo/cmd/tzcompose

# or by installing it
go install blockwatch.cc/tzgo/cmd/tzcompose

Then, set an environment variable containing a private key TZCOMPOSE_BASE_KEY, which will serve as your base account from which any other account will be derived and funded. See Wallets for details. TzCompose works with any RPC node (-rpc url), but if you use clone or connect the default TzPro servers, keep in mind that you need a 🔑 TzPro API key (simply export it via TZCOMPOSE_API_KEY). Don't have a key yet? No problem, you can create one for free at TzPro.

Testnets

If you're deploying on a public testnet such as Ghostnet, use Teztnets faucets provided by Oxhead Alpha to fund your base account. You can create a fresh key directly with TzGo: 

go run blockwatch.cc/tzgo/examples/key gen edsk

Sandbox

If you're running tzcompose with a local sandbox this is not necessary as your sandbox environment will take care of funding your accounts. We've added a simple script for starting and stopping a local Flextesa sandbox to TzGo at ./scripts/sandbox.sh. To find an account's key on a sandbox run

docker exec tezos_sandbox flextesa key-of-name alice

Using TzCompose

TzCompose executes configurations from a single file -f file.yaml, a single directory -f ./examples/fa, or all subdirectories -f ./examples/.../ in which case all YAML files will be read in filesystem order. Specify your Tezos Node URL with the -rpc flag, e.g. https://rpc.ghost.tzpro.io or http://localhost:20000.

go run blockwatch.cc/tzgo/cmd/tzcompose [cmd] [flags]

Env
  TZCOMPOSE_BASE_KEY  private key for base account
  TZCOMPOSE_API_KEY   API key for RPC and index calls (optional)

Flags
  -f file
      configuration file or path (default "tzcompose.yaml")
  -file file
      configuration file or path (default "tzcompose.yaml")
  -resume
      continue pipeline execution
  -rpc string
      Tezos node RPC url (default "https://rpc.tzpro.io")
  -h  print help and exit
  -v  be verbose (default true)
  -vv
      debug mode
  -vvv
      trace mode

Available Commands

tzcompose offers several commands to create, test, and run pipelines.

  • clone: clone transactions starting from the origination of a contract
  • validate: validate compose file syntax and parameters
  • simulate: simulate compose file execution against a blockchain node
  • run: execute compose file(s) sending signed transactions to a blockchain node
  • version: print version and exit

Available Tasks

A pipeline defines a list of tasks that are processed in order. Each task produces a transaction.

Deployment Examples

You can find a list of example files under examples/tzcompose/ which give you an idea about how various deployment scenarios work. Feel free to test them on a sandbox or public testnet.

  • Transfer – simply transfers tez between accounts
  • Delegate – registers a baker and delegates to it
  • Token – launches FA1.2 and FA2 token ledgers, mints and transfers tokens
  • Tether –  deploys a copy of Tether USDt
  • HicEtNunc – deploys Hic and Teia markets for NFT trading
  • Quipu-v2 – deploys a Quipuswap V2 DEX for token trading

Dive Deeper

Read our documentation and start building your own scenarios. We tried making tzcompose as easy to use as possible, but it may still have a few rough edges. Please report back to us if you find yourself lost with transaction errors or if you have ideas on how to improve tzcompose further. After all the current release is an alpha and we're just getting started.

To contribute and ask questions contact us on X and Discord or send us a PR on Github. We highly value your contribution.

Stay safe out there.