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 contractvalidate
: validate compose file syntax and parameterssimulate
: simulate compose file execution against a blockchain noderun
: execute compose file(s) sending signed transactions to a blockchain nodeversion
: print version and exit
Available Tasks
A pipeline defines a list of tasks that are processed in order. Each task produces a transaction.
- 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
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.