UseCases_tokens_Find token authorities

Use Cases, Scenarios, Walkthroughs - for tokens

Case "Find token authorities"

Scenario: Create and distribute the GVT token according to the IEO

Feature: Scanning the UTXO set and retrieving wallet information on token authorities

Actor: Token authority owners

Summary:

By scanning spendable coins, one can create a list of all token authorities in the current state of the blockchain. There are two options:

Scanning the full public blockchain to find all currently existing token authorities
Scanning one's own wallet to find the token authorities one can currently use

The current case is written for the Guardian Validator token, but can be generalized to any other token.

Preconditions:

The token group has been created and the needed tokens have been minted. (See e.g. Case Create Management Tokens).

Steps:

A token creator can find the currently available token authorities using the following commands:

scantokens start [TOKENGROUPID]: scan the full public blockchain for all currently available token coins, including both spendable tokens and token authorities
listtokenauthorities (TOKENGROUPID): show the wallet's unspend transaction outputs that are token authorities. The scan can be limited by tokengroup.
gettokenbalance (TOKENGROUPID) (IONADDRESS): show the wallet's per-token balance, including the total of the token authorities available in the wallet. The scan can be limited by tokengroup or by tokengroup and ION address.

Look up the token group ID of Guardian Validator Scantokens needs the ID of a tokengroup as a parameter, and the other two commands may have the ID of a tokengroup as a parameter. See View information related to a token group for detailed information on how to retrieve the tokengroup ID.

$ tokeninfo ticker GVT
[
  {
    "groupID": "bytzreg1zw0tzp0x05szcvhq68gyh9d6v5zhc652q2r8al8dk3r8vauxj3vqsxstc84",
    "flags": "management",
    "specification": {
      "ticker": "GVT",
      "name": "GuardianValidator",
      "metadata_url": "https://github.com/bytzcurrency/ATP-descriptions/blob/master/BYTZ-regtest-GVT.json",
      "metadata_hash": "f5125a90bde180ef073ce1109376d977f5cbddb5582643c81424cc6cc842babd",
      "decimal_pos": 0,
      "bls_pubkey": "97c40d3489a6109b355a241cfc17863b935f84b6c435c649c6790bbec64b757553885a1cd9ccf22bad67ff04484a1df6"
    }
  }
]

Scan the blockchain for token authorities for Guardian Validator The scan command walks through each item in the UTXO set, returning those UTXO's that take the form of an unspent token.

Token authorities are a specific type of token: they do not specify an amount, but they specify a set of authorities instead.

The tokengroup ID and the token authorities are specified in the scriptPubKey, and if the transaction output holds token authorities, they are presented in readable form in the list of unspent items.

After the set of unspent items, the command returns the total amount of tokens on the blockchain and the aggregated set of token authorities that are encountered in the scan.

$ scantokens start bytzreg1zw0tzp0x05szcvhq68gyh9d6v5zhc652q2r8al8dk3r8vauxj3vqsxstc84
{
  "success": true,
  "searched_items": 566,
  "unspents": [
    {
      "txid": "e1a034469493f580e4a01084110b763c3d55e3813b4881293dfdaf18fa0fe2b7",
      "vout": 0,
      "address": "TkhfncwgMnzDqD4W14UVLgYxebuUbWuHWm",
      "scriptPubKey": "209eb105e67d202c32e0d1d04b95ba65057c6a8a02867efcedb446767786945808024700b6757576a9147cfc1b42e0f76e3d0c771f361cc6f98fa0df374288ac",
      "amount": 0.00000001,
      "amountSat": 1,
      "tokenType": "amount",
      "tokenAmount": "71",
      "tokenAmountSat": 71,
      "height": 308
    },
    {
      "txid": "e1a034469493f580e4a01084110b763c3d55e3813b4881293dfdaf18fa0fe2b7",
      "vout": 1,
      "address": "TbeT9qErDBk5BLywxEYhmPFdgN6va7mUaJ",
      "scriptPubKey": "209eb105e67d202c32e0d1d04b95ba65057c6a8a02867efcedb4467677869458080800000000000000feb6757576a91419a72e13a95e86d1be106c3ecf50815ad6ead9a088ac",
      "amount": 0.00000001,
      "amountSat": 1,
      "tokenType": "authority",
      "tokenAuthorities": "mint melt child rescript subgroup configure",
      "height": 308
    }
  ],
  "total_tokenValue": "71",
  "total_tokenValueSat": 0.00000071,
  "total_tokenAuthorities": "mint melt child rescript subgroup configure"
}

The current scan shows a very limited number of token transactions for the Guardian Validator token:

One output that is a token authority (e1a034469493f580e4a01084110b763c3d55e3813b4881293dfdaf18fa0fe2b7:0), and this coin has all possible authoritities except the mint authority.
One output that holds 71.000 Guardian Validator tokens.

Identify coins in our wallet that hold Guardian Validator token authorities

The command to list coins in our wallet that hold token authorities is: listtokenauthorities (TOKENGROUPID). To list all GuardianValidator authorities that you own, use the following command:

$ listtokenauthorities bytzreg1zw0tzp0x05szcvhq68gyh9d6v5zhc652q2r8al8dk3r8vauxj3vqsxstc84
[
  {
    "groupID": "bytzreg1zw0tzp0x05szcvhq68gyh9d6v5zhc652q2r8al8dk3r8vauxj3vqsxstc84",
    "txid": "e1a034469493f580e4a01084110b763c3d55e3813b4881293dfdaf18fa0fe2b7",
    "vout": 1,
    "ticker": "GVT",
    "address": "TbeT9qErDBk5BLywxEYhmPFdgN6va7mUaJ",
    "tokenAuthorities": "mint melt child rescript subgroup configure"
  }
]

List the token authorities that are available in the wallet

The command to show the total available tokens and token authorities in the wallet is gettokenbalance (TOKENGROUPID) (BYTZADDRESS).

$ gettokenbalance
  {
    "groupID": "bytzreg1zd4077w2tk2ct4wqfd4er3esasgxmvkeehknwumrea4h0tx3nz7sqta2cgp",
    "ticker": "RTTOK",
    "name": "RegtestToken",
    "balance": "10000",
    "authorities": "mint melt child rescript subgroup configure"
  },
  {
    "groupID": "bytzreg1zvkmxhdnss58dfscfvzv8fwx0v2m9cl2xsaqdr9zkq7avpet234qsghc0a9",
    "ticker": "MGT",
    "name": "Management",
    "balance": "500.0000",
    "authorities": "mint melt child rescript subgroup configure"
  },
  {
    "groupID": "bytzreg1zd5aj2480egxnj28563swhpzj0g0hhg3jmqgk2t9stwhdfa52rvqs979j3y",
    "ticker": "GVT",
    "name": "GuardianValidator",
    "balance": "71",
    "authorities": "melt child rescript subgroup"
  }

The command shows us that our wallet has authorities for 3 different token groups, and that we do not hold mint authorities for the 1 of those token groups. (Use the scantokens command to find out if there are other wallets that hold more token authorities).

Postconditions: