TzCompose Automation Framework

TzCompose is a tool for defining and running complex transaction sequences on Tezos. With TzCompose, you use a YAML file to configure pipelines from different kinds of tasks and then run a single command to execute these pipelines.

TzCompose works on all Tezos networks and makes it easy to clone contracts and transaction sequences between them.

Developers can use TzCompose for

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

How to use TzCompose

The easiest way to run TzCompose is

# directly from the Git repo
go run github.com/trilitech/tzgo/cmd/tzcompose

# or by installing it
go install github.com/trilitech/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.

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.

TzCompose can execute configurations from a single file -f file.yaml, a single directory -f ./examples/fa or all subdirectories -f ./examples/... in which cases all yaml files will be read in filesystem order.

go run github.com/trilitech/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

• 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

TzCompose relies on the Tezos Node RPC, and on the TzIndex API for its clone feature. Both are publicly available via https://tzpro.io with a free subscription. Export your API key as follows:

export TZCOMPOSE_API_KEY=<your-api-key>

Available Tasks

• batch - send multiple transactions as single operation
• call - send smart contract call
• delegate - delegate to baker
• deploy - create smart contract
• double_endorse - force a double endorsement slash
• register_baker - register as baker
• token_approve - approve token spender
• token_revoke - revoke token spender
• token_transfer - send token transfer(s)
• transfer - send tez transfer(s)
• undelegate - remove delegation from baker
• wait - wait for condition

Configuration

TzCompose YAML files contain different sections to define accounts, variables and pipelines. Pipelines can be composed from different tasks which will generate transactions when executed. A compose file may contain multiple pipelines and each pipeline virtually unlimited tasks.

# Available engines: alpha
version: <engine-version>

# Specify alias names for tz1 user accounts and optional key id
accounts:
  - name: alias
    id: 1

# Specify contract addresses or other data as variables and later
# reference them inside pipelines
variables:
  - <name>: KT1...

# Specify transaction sequences as pipelines. Each sequence consists of tasks
# of a specifed type and corresponding input parameters
pipelines:
  <name>:
    - task: deploy | call | transfer | register_baker | token_transfer | ...
      source: $var | address
      destination: $var | address

Dive Deeper

Consult the full TzCompose README. It includes a section on how Tzcompose works and a task reference with detailed descriptions.