Tutorial
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
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
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)
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
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
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}]
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.
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
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
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
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
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
Last modified 1yr ago