# Quick Start

This section describes how to get started with the miyabi-cli tool. To illustrate its usage, we will walk through the process of creating and managing a coin on Miyabi. An asset module will be used to manage this new coin. For the sake of this guide, we will use bitFlyer Blockchain coin as an example. We will need to create and manage an asset table for the bitFlyer Blockchain coin. This table will store the mapping for a public key address and the corresponding coin balance.

Let's walk through the steps one by one and see how we can achieve this.

# Step 1. Generate Key Pairs

To manage the table, we have prepared 3 key pairs.

File name Description
owner.p12 Owner of the asset table who is authorized to generate assets and delete the table
user1.p12 User who can move its assets
user2.p12 User who can move its assets

The following commands show how to generate these files. -d specifies output directory, and -f specifies the PKCS12 file name.


$ ./miyabi-cli generatepkcs12 -d . -f owner
$ ./miyabi-cli generatepkcs12 -d . -f user1
$ ./miyabi-cli generatepkcs12 -d . -f user2

The next step is to extract private keys by parsing each PKCS12 file. Public keys are calculated from the private keys by using the getpublickey command.


$ ./miyabi-cli parsepkcs12 -f owner.p12
c302dfe03e9c70f925349d8a235bdf60c57f254407ec4d331d6fffd910738781
$ ./miyabi-cli getpublickey c302dfe03e9c70f925349d8a235bdf60c57f254407ec4d331d6fffd910738781
034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac32839116118

The following table summarizes the cryptographic key pairs result for each of the three roles. The result may vary depending on your environment.

File Private key Public key
owner.p12 c302dfe03e9c70f925349d8a235bdf60c57f254407ec4d331d6fffd910738781 034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac32839116118
user1.p12 44bdca3f57e095ac565667ee057983b3441c9f36e0f64e9a29a0b6cd1242c185 033f4654afe65504ed1fe697f997c273b7c30d7e05d5086db0ade47345149815e9
user2.p12 7c0761fc50d18b1eda307803cc8e57cf6b7df1c70d58c74ac904baab74469814 03a9914fa341da4357ae0db2d19eb6377d4956f0c3284946fff932313be925444b

# Step 2. Create an Asset Table

To handle coins, we start by creating an asset table. Only the asset owner can transfer its asset.

The asset holder is represented by their public key. The asset can only be transferred by someone who has the corresponding private key of the public key.

The token admins permission are required when generating new assets. Additionally, table insert permission may be required if the address does not have record in the table. Through createassettable command, table owners will have both permissions.


$ ./miyabi-cli sendtransaction createassettable -t bFBC_coin -o 034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac32839116118 -p 10425b7e6ebf5e0d5918717f77ce8a66aaf92bc64b65996f885ff12bd94ef529
95129ef2f448e4204b335428fa23ed22252d0b42f9df3d8f455a0accfe16efff

The -t option represents the table name. The -o option represents the table owner's public key. The -p option represents the table admin's private key that is used to sign the transaction (the table admin's private key is assigned by Miyabi consensus node operators). Miyabi consensus nodes check whether the table admin is valid by checking Blockchain Config and executing the request.

The return value 95129e... represents the transaction Id.

# Step 3. Confirm the Status of the Transaction

gettransactioninfo is used to get the transaction's current status from a Miyabi node. The details of the transaction are in the entries details, where all commands' parameters, Except private key will be displayed. If the transaction is stored in any block, the height of that block will be shown in the txptr.


$ ./miyabi-cli --pretty gettransactioninfo 95129ef2f448e4204b335428fa23ed22252d0b42f9df3d8f455a0accfe16efff
{
  "value": {
    "tx": {
      "entryDetails": [
        {
          "typeName": "CreateAssetTable",
          "entryDetails": {
            "tokenAdmins": [
              "034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac32839116118"
            ],
            "trustedEntities": [],
            "rules": [
              0,
              1,
              2
            ],
            "voidAddress": "00",
            "granularity": {
              "maximumMove": 10000000000.0,
              "minimumMove": 0.01,
              "unit": 0.01
            },
            "name": "bFBC_coin",
            "tracked": false,
            "supportProofs": false,
            "tableAcl": {
              "tableOwners": [
                "034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac32839116118"
              ],
              "permissions": [],
              "multiKeyPermissions": []
            },
            "isReadRestricted": false,
            "permissionModel": 1
          }
        }
      ],
      "timestamp": "2022-08-23T02:16:38.7855394Z",
      "validFrom": "2022-08-23T02:16:38.7855394Z",
      "validTo": "2022-08-23T03:16:38.7855394Z",
      "entries": [
        "d2a55e0022029ba9624642435f636f696ec2c29391c421034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac328391161189090c20191c421034cdae9dd567b23d29c9affef3ce7ff5c1d16d35512bb72a9008ac328391161189093000102c4010093ab3130303030303030303030a4302e3031a4302e3031"
      ],
      "requiredCredentials": [
        "02e3c13b6862eda179ac49d03b334ef17cf654c05bd3fa6dc0cf6078fefe82aea2"
      ],
      "evidence": [
        "3045022100fe098f8f15a7d93df534b99d9af808c79a0a501f2d6e049b0cf9d7f9431edc3a0220746daff151d3d39376d4cfa166c5e503f1878d694b8332ab6bc168ca56b513f9"
      ],
      "id": "95129ef2f448e4204b335428fa23ed22252d0b42f9df3d8f455a0accfe16efff",
      "witId": "d4c003f8727d28844139de5a7827b11a27ef231dcaee104e9756af8f3b03a6e4"
    },
    "txPtr": {
      "height": 952,
      "idx": 0
    },
    "result": "Success"
  },
  "atHeight": 960
}

The result field provides the execution result of the transaction. If the result is Pending, the transaction is still not committed to the blockchain. If the result is Success, the transaction has been executed and stored in the specified block. Other results show that the transaction has failed, and it is stored at a specific height. The user needs to update the transaction according to the message provided, like InvalidCredentials, TimeOut, etc. General failure is displayed as Failed.

# Step 4. Check Tables

To verify that the table was successfully created and exists in the world state, the user can use the gettables command. This command returns the table descriptors of all the tables that exist. A table descriptor represents the metadata information about the table (table name, table owners, etc.).


$ ./miyabi-cli --pretty gettables
[
  ...
  {
    "admins": [
      ...
    ],
    "rules": [
      0,
      1,
      2
    ],
    "voidAddress": "00",
    "trustedEntities": [],
    "name": "bFBC_coin",
    "tracked": false,
    "supportProofs": false,
    "type": "AssetTable"
  },
  ...

# Step 5. Generate Coins

generateasset can generate coins in the asset table.


$ ./miyabi-cli sendtransaction generateasset -p c302dfe03e9c70f925349d8a235bdf60c57f254407ec4d331d6fffd910738781 -t bFBC_coin -a 033f4654afe65504ed1fe697f997c273b7c30d7e05d5086db0ade47345149815e9 -m 1000
db2daf3abb4ba4120368f763bdd8b216a349436e72cf1491b2337673e3bad903

-p specifies the private key of the table owner(s), whose public key was specified in the -o option of the createassettable command. -t specifies the table name and -a specifies the public key address of the user who will receive the coins. -m denotes the number of coins to be generated.

# Step 6. Check Coins

By using the getassettable command, the user can check the contents of the whole table.


$ ./miyabi-cli --pretty getassettable -t bFBC_coin
{
	"00": -1000
	"033f4654afe65504ed1fe697f997c273b7c30d7e05d5086db0ade47345149815e9": 1000
}

-t specifies the name of the table to be checked. The result of the table is shown in a key-value pair where the key is the public key of a user and the value is the amount of coins. The void address is represented by 00. It cannot be changed by the clients. All generated coins are moved from the void address to ensure the whole table holds zero balance.

# Step 7. Move Coins


$ ./miyabi-cli sendtransaction moveasset -t bFBC_coin --from 033f4654afe65504ed1fe697f997c273b7c30d7e05d5086db0ade47345149815e9 --to 03a9914fa341da4357ae0db2d19eb6377d4956f0c3284946fff932313be925444b -m 100 -p 44bdca3f57e095ac565667ee057983b3441c9f36e0f64e9a29a0b6cd1242c185
e07a8e5e5c1b59fbc3bb93ff5c4c7355ab2f6aa64fd5fb3f3cf1522a10114c70

The moveasset command is used to move assets from one address (denoted by --from) to another address (denoted by --to). The private key of the --from address should be provided in the -p option. The -m option represents the number of coins to be moved, which should be no more than the total amount of --from address.

# Step 8. Confirm Coins

Use the getassettable command. The balance is as expected.


$ ./miyabi-cli --pretty getassettable -t bFBC_coin
{
	"00": -1000
	"033f4654afe65504ed1fe697f997c273b7c30d7e05d5086db0ade47345149815e9": 900
	"03a9914fa341da4357ae0db2d19eb6377d4956f0c3284946fff932313be925444b": 100
}

← CLI Options →