Links

Tutorial

Installation

taal-cli does not need a special installation. You can copy the executable to a directory and launch from there.
./taal-cli
Usage: taal-cli [--version] [--help] <command> [<args>]
Available commands are:
address Perform actions on locally-stored addresses and other addresses
airdrop Airdrop locally stored address and other addresses
config Read and write taal-cli's local configuration
regtest Launch a dockerized regtest node (default latest)
token Crate STAS contracts, mint STAS tokens and move tokens around
transfer Transfer BSVs to a beneficiary
When interacting with the WOC API, it is necessary to set the API credentials:
[taal@fedora taal-cli]$./taal-cli config set -apiusername xxxxx -apipassword yyyyy

Using Profiles (configuration sets)

If the flag “-cfgset <name>” is used, you can have different sets of stored addresses, tokens, preferences, and so on.
./taal-cli address create -cfgset dev -name Bob
Address Bob created (address:msn2zdbkcyKcu65cjc979MPMfMdLB47B1v)
[taal@fedora taal-cli]$./taal-cli address list -cfgset dev
Nickname Address
Bob msn2zdbkcyKcu65cjc979MPMfMdLB47B1v
[taal@fedora taal-cli]$./taal-cli address create -cfgset prod -name wallet
Address wallet created (address:moCNuyDfiwWjKR46xBLBLuTkPbcR3fzvrf)
[taal@fedora taal-cli]$./taal-cli address list -cfgset prod
Nickname Address
wallet moCNuyDfiwWjKR46xBLBLuTkPbcR3fzvrf

Handling Addresses

Creating an Address

A locally stored address can be created with:
./taal-cli address create -name Alice
Address Alice created (address:n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
After creation, the public address will be shown and taal-cli will save its private key.
An address can contain spaces, but it must be quoted when creating it and every time it is used:
./taal-cli address create -name "Julius Caesar"
Address Julius Caesar created (address:mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD)

Showing Information about Addresses

You can show a list of locally saved addresses:
./taal-cli address list
Nickname Address
Alice n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs
Julius Caesar mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD
and then fund them, using their name, their address or a combination thereof:
./taal-cli airdrop -name Alice mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD
Airdropped mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD
Airdropped Alice (n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
Let us verify their balances:
./taal-cli address balance -name Alice -name "Julius Caesar"
Balance of Alice (address:n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs) confirmed: 1.000.000 - unconfirmed: 0
Balance of Julius Caesar (address:mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD) confirmed: 1.000.000 - unconfirmed: 0
In more detail:
./taal-cli address balance -name Alice -name "Julius Caesar" -extended
Balance of Alice (address:n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs) confirmed: 1.000.000 - unconfirmed: 0
Unspent # 0: Satoshis: 1.000.000
Balance of Julius Caesar (address:mkjAH8VWLJCN9p8HTPa8wafbkYjtaN4KnD) confirmed: 1.000.000 - unconfirmed: 0
Unspent # 0: Satoshis: 1.000.000

Moving Funds

Let us move some funds, you will first try a dry run:
./taal-cli transfer -dry -fromname Alice -amount 1000 -toname John
from Alice (n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
to John (myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH)
Dry run terminated correctly.
If everything looks OK, you can do an actual transfer:
./taal-cli transfer -fromname Alice -amount 1000 -toname John
from Alice (n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
to John (myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH)
transfer tx ID: 8b1270270f244007205468535e3f0360ce5d27eb9355d1527b59d68475c53680
Let us verify if the transfer actually took place:
./taal-cli address balance -name Alice -name John -extended
Balance of Alice (address:n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs) confirmed: 998.887 - unconfirmed: 0
Unspent # 0: Satoshis: 998.887
Balance of John (address:myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH) confirmed: 1.000 - unconfirmed: 0
Unspent # 0: Satoshis: 1.000

Handling Tokens

Minting a Token (full command)

When minting a token, you will need the following:
  • a “token issuer” with some funds - this must be a saved address since taal-cli needs its private key
  • an issuerutxoindex - the vout containing the issuer funds (can be omitted, taal-cli will find an utxo)
  • a “token funder” with some funds (fee payer for mint transaction) -this must be a saved address since taal-cli needs its private key
  • a funderutxoindex - the vout containing the issuer funds (can be omitted, taal-cli will find an utxo)
  • a token symbol (CHK, MONEY, MYTOKEN…)
  • a token name
  • a token amount - how many tokens to issue
  • to amount - the amount of satoshis to send to a specific beneficiary
  • satsPerToken - how many satoshis a token is worth
  • one or more beneficiaries - the addresses the issued tokens will go to.
Let us create and fund an issuer and a funder:
./taal-cli address create -name myissuer -name myfunder && ./taal-cli airdrop -name myissuer -name myfunder
Address myissuer created (address:n1c6H4woF58GxwuMx87fyqHwaNFMUvBpGd)
Address myfunder created (address:n2yJ9QTeLMyMQcpVvcRem8sZ9cXLEdrPsM)
Airdropped myissuer (n1c6H4woF58GxwuMx87fyqHwaNFMUvBpGd)
Airdropped myfunder (n2yJ9QTeLMyMQcpVvcRem8sZ9cXLEdrPsM)
you can now mint a token:
./taal-cli token mint -name MYFIRSTTOKEN -symbol MFT -amount 10000 -satspertoken 1 -toname Alice -toamount 6000 -toname John -toamount 4000 -issuer myissuer -issuerutxoindex 0 -funder myfunder -funderutxoindex 0
Token ID: dc5b426600f3b16f9f9d0f75b944252db6d1a740
Token Symbol: MFT
Issuer: myissuer
Funder: myfunder
Contract TX ID: a2b692b6c61a04ee8dfb57296857cec98cc9397f12d0dbfad3a35d729fe5bdb7
Issuance TX ID: cb6f6a08b887b0f0897715cc8223185dca679ec185e4d7bec21f2e52c2c6eff7
Beneficiary Address Nickname
n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs Alice
myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH John
Token metadata saved.
Let us look at the token itself:
./taal-cli token describe MFT
Protocol: STAS
Symbol: MFT
ID: dc5b426600f3b16f9f9d0f75b944252db6d1a740
Issuer: myissuer
Funder: myfunder
SatsPerToken: 1
ContractTXID: cb6f6a08b887b0f0897715cc8223185dca679ec185e4d7bec21f2e52c2c6eff7
IssuanceTXID: a2b692b6c61a04ee8dfb57296857cec98cc9397f12d0dbfad3a35d729fe5bdb7
Issuees: [{n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs Alice} {myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH John}]

Minting a Token (easy mode)

A token can be minted with a minimal set of flags:
./taal-cli token mint -name MYSECONDTOKEN -symbol MST -amount 10000 -satspertoken 1
Error retrieving issuer UTXO:nonexisting UTXO
You are getting an error because the command is created and airdropped to an issuer and a funder, but the transactions have not propagated yet.
Let us retry the same command:
./taal-cli token mint -name MYSECONDTOKEN -symbol MST -amount 10000 -satspertoken 1
Token ID: 08bac639f9ba20ec8a8713e43ad619084f3cf5ca
Token Symbol: MST
Issuer: MST-Issuer
Funder: MST-Funder
Contract TX ID: 1d64c8ee33f4a35f89a7c693a00991293ffe30211f51c281c94ff1ff764fdadd
Issuance TX ID: 49535173b15354c71cce62302ba1b373561016c8db0105689cf78bdbf50d995f
Beneficiary Address Nickname
mn4hHXTNfQuHcGxm88BMQf33Exkr7DGpXD MST-Beneficiary
Token metadata saved.
taal-cli created an issuer, a funder, funded them, and a beneficiary for the issuance of our token.

Moving (transferring) a Token UTXO

You now have two token owners:
./taal-cli address tokens -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
In detail - two token owners with one token utxo each:
./taal-cli address tokens -extended -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
vout:0 5.000
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
vout:0 5.000
Let us give Alice’s unspent to John in easy mode:
[taal@fedora taal-cli]$./taal-cli token transfer -fromname Alice -toname John
from Alice (n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
Using original funder myfunder
to John (myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH)
Transfer TX ID: 2e4ffe959cfa6ea890b950f0442f6e071787ea8715f0367bc8464d8b5f73e9af
The result is:
./taal-cli address tokens -extended -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 0
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 10.000
vout:0 5.000
vout:1 5.000

Splitting (sending) a Token UTXO to two different Addresses

John now wants to pay Alice 3.000 MFTs:
./taal-cli token split -fromname John -toname Alice -toname John -amount 3000 -amount 2000
from John (myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH)
UTXOs for symbol
1 vout 0:5.000
2 vout 1:5.000
Please select an UTXO:[1-2]: 1
Using original funder myfunder
Split TX ID: 6ff40fa71971bf622cb413e399f588fd46d1084c9b82282331bd4110a8483fec
You now have:
./taal-cli address tokens -extended -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 3.000
vout:0 3.000
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 7.000
vout:0 2.000
vout:1 5.000

Merging (sending) two Token UTXOs and sending to one Address

John would like to send 5.000 MFTs to Alice:
./taal-cli address tokens -extended -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 0
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 10.000
vout:0 3.000
vout:1 2.000
vout:2 5.000
He then merges 2 token amounts and sends them:
./taal-cli token merge -fromname John -toname Alice
from John (myzRVMMkYquoNn2NHFggZZM6VPtC2pWzVH)
UTXOs for symbol
1 vout 0:3.000
2 vout 1:2.000
3 vout 2:5.000
Please select some UTXOs:[1-3]: 1,2
Using original funder myfunder
Merge TX ID: 73f2853fc753647c5f089f3255e9b78a9000c665dc9fa20d18af532360de1312
The result is:
./taal-cli address tokens -extended -name Alice -name John
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
vout:0 5.000
Tokens of John:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
vout:0 5.000

Merging two Token UTXOs and Splitting (sending) them to two different addresses

Alice has 5.000 MFTs and would like to send 2.000 MFTs to Wilbur and 3.000 MFTs to Mary:
./taal-cli address tokens -extended -name Alice
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 5.000
vout:0 4.000
vout:1 1.000
./taal-cli token mergesplit -fromname Alice -toname Wilbur -toname Mary -amount 2000 -amount 3000
from Alice (n4fXeM3MCUWTViLRXFJzYqayrBQDaELGQs)
UTXOs for symbol
1 vout 0:4.000
2 vout 1:1.000
Please select some UTXOs:[1-2]: 1,2
Using original funder myfunder
Mergesplit TX ID: 95f176df324fb23e4b7bf161e565466f9880150f22b17f4b2fea74f8be35f7ab
The result is:
/taal-cli address tokens -extended -name Alice -name Wilbur -name Mary
Tokens of Alice:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 0
Tokens of Wilbur:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 2.000
vout:0 2.000
Tokens of Mary:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 3.000
vout:0 3.000

Redeeming Tokens

Mary would like to redeem her MFTs, which were issued by my issuer:
./taal-cli address tokens -extended -name Mary
Tokens of Mary:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 3.000
vout:0 3.000
./taal-cli address balance -name myissuer
Balance of myissuer (address:n1c6H4woF58GxwuMx87fyqHwaNFMUvBpGd) confirmed: 0 - unconfirmed: 0
She then issues a redeem command:
./taal-cli token redeem -fromname Mary
from Mary (myfh9L432ks2Z9HBf4QxutC1XnfRnjLrqR)
Issuer myissuer
Using original funder myfunder
Redeem TX ID: c553913b9a005dcf4e080735e68380d19ff171abddc7a9602d9a6eb832ee8d08
The result is:
./taal-cli address tokens -extended -name Mary
Tokens of Mary:
Protocol Symbol Token ID Balance
STAS MFT dc5b426600f3b16f9f9d0f75b944252db6d1a740 0
./taal-cli address balance -name myissuer -extended
Balance of myissuer (address:n1c6H4woF58GxwuMx87fyqHwaNFMUvBpGd) confirmed: 3.000 - unconfirmed: 0
Unspent # 0: Satoshis: 3.000