Tutorial

Introduction

mijin is an versatille platform that is developed and designed for any kind of audience to freely use a 'blockchain' as a private P2P network.

In order to start to the tutorial, make sure the P2P network of mijin has been already built-on since this tutorial will be based on a prepared environment.

General Information on 'mijin'

First of all, please take a look at the following figure:

The dotted lines are either blocks or transactions. The figure shows that mijin has been installed to all four servers and noted as node 1,2,3 and 4. Blocks and transaction are synchronised by communicating each other through Port:7895.

No authoritative roles exist in each node for mijin's blockchain unlike the other blockchains do. Authoritative role can be; #1 client; #2 non-verification peer; #4 verification peer; and #8 audit. Each node shares blocks and transactions and verifies oneself, shares, and eventually it connects to a blockchain by oneself.

In other words, it is possible to place a role to each node as it is shown in the figure below. node:4 receives a transaction from a general user, and node:2 receives a transaction from a corporate.

For example, it is also possible to build an application as it is shown in the figure below based on the roles described above.

Interaction of mijin

The data interaction for mijin is performed via API. The communication method is 'POST/GET'.
Like ordinary websites, POST/GET will be runned from the HTML form under the host which mijin has been already installed.

About POST/GET

POST/GET are used as the following:

  • POST ... sending transaction
  • GET ... receiving various types of information

GET method will be runned like ordinary websites by using addresses and public keys as a parameter.

http://:7895/account/transfers/incoming?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS

However, POST method differs from ordinary websites.
The data which are entered in the form are sent to the host via POST method as it is for an ordinary website. Though, in terms of mijin, POST is runned with a JSON object as described below. It is runned with a combination of; creating a data that has been serialised by each parameter; and the digital signatures that are created by the private key which belongs to the transaction creator.

{"data": "01010000010000604781b90320000000462ee976890916e54f…0000000000000000000000000000000000000000000000000", "signature": "8584d64446316cafbfa6ea92b772a21cdcb18b72b36ae5f91f…d8605c09c06a3faf905f02de8b68b1069e49e631382c70a09"}

POST method is possible to transact the followings, however, in order to POST on a node, it is necessary to use the POST method after converting it into a JSON object as it is described in above.

Possible Transaction through POST method
  • remittance (including mosaic)
  • creating a multisig account
  • creating a multisig transaction
  • signing a multisig transaction
  • creating a namespace
  • creating mosaics

It can be described as a figure below:

So, where should the digital signatured JSON object be created?

The API Path: /transaction/prepare-announce which will be needed to create a JSON object from each parameter is already settled in mijin. However, the private key information will be broadcasted on the communication when each parameters are granted and giving a call to this API towards the node.

Use under the local environment of the servers that mijin has been already installed, and in case of other environment, make sure to; use the JavaScript on the client side; create a JSON object; and POST the created JSON object towards the node when using. This enables to send transactions to a node without broadcasting the private key on the communication.

About Tutorial

In this tutorial a symplified app. which was created based on the jQuery will be used.

The specs of this app. are as listed as below:

  1. Convert the information which was entered in the entry form into a JSON object which comes with a digital signature
  2. Send a transaction to a node
  3. Output the results into the Response Column

The instruction on how to use the application and other related information will be described at the bottom.
Let's get started on the tutorial now.

What is an Account on Blockchain?

Issue Account

In order to exchange the data on mijin, it is necessary to create an account. With a unique account, the following value will be issued:

  • address
  • public key
  • private key

When creating an account, many users often find it very stressful since it takes time to fill in the needed information. It is common to enter; a name; an e-mail address; home/office address; and a phone number; when creating an account on ordinary websites. After entering all information, an account will be created by clicking 'submit' button.

In case of mijin, an account will be issued just by clicking on to the following URL link.

http://:7895/account/generate

This is it, nothing else. Nothing could more simple than this.

However, if anyone can create an account, there might be a possibility that an unknown person may create a huge number of accounts and may misuse for inappropriate purpose (however, since the possessing coins are zero, so nothing else can be done).
Also, it would mean that address, public key, and private key can be broadcasted on the communication when creating an account.

Therefore, there would be a limit to IP addresses, and mijin would consider as a failure for the APIs that would broadcast the private key on communication. The steps to create an account are as followed:

Preparation on Issuing an Account

  1. Log-in to the node with SHH
  2. Open config-user.properties
    $ vi config-user.properties
  3. Add an IP address that permits nis.additionalLocallps (when one or more is being added, make sure to mark off by a valve,|)
    nis.additionalLocalIps = XX.XX.XX.XX|XX.XX.XX.XX
  4. Restart mijin
    ps aux | grep java
    kill -9 process number
    $ screen -S mijin -d -m /home/[account]/mijin/startnem.sh or
    $ nohup ./startnem.sh &

Once this process is done, it is now ready to create an account from the registered IP address. As a test, enter the connecting host and click onto 'Create Account'.

/account/generate

The address, public key, and private key of the registered account must appear in the Response Results.

Same infomation on the results can be also looked up by accessing to http:///account/generate .

Information Stored on Blockchain

Account address, public key, and private key are not stored on the blockchain.
The storage of each information is entrusted to an app. or to the users side.

Send and Receive

Remittance Preparation

Here is a method on how to proceed a remittance between the addresses.

Remittance Method

  1. Prepare the information on the address of sender(remitter) and recipient(remittee)
  2. Prepare an HTML form to enter the necessary parameter value
  3. POST it onto a node

Let's proceed a remittance to the new account.

Click and Send

A Form for remittance is now prepared.
Let's send XEM to the other party (recipient). XEM is a defaulted currency (coins) for mijin. Its unit is milli-micro.

A commission will be charged when proceeding a remittance.
In blockchains, some currencies are gifted as a reward for the accounts who have cooperated on the consensus algorithm (= mining).
This reward is paid and comes from the commission of when generating the transaction. Since mijin has a same idea, it is necessary to grant a commission when transaction is generated.The commission that occurs when generating the transaction can be freely set with a little restriction: with a minimum value of 0.1 is required. In case of remittance for XEM, the value can be set to 0 by setting it by config-user.properties. (However, in case of remittance for mosaic, minimum of 1 XEM is required).

So now, let's proceed the remittance. Copy and Paste the necessary information, and click the 'Send (button)'.

It is only asked to copy and paste within the format in this app. to reduce the difficulty to check information. (Though when omitting a workload for users to enter private key and pubic key, it is common to save it in the browser's local storage to find the value from the internal process).

/transaction/announce

*In this test, the unit of remittance amount of original coin is fixed to 1 = 1,000,000

Remittance is completed.
In case of mijin, in order to check whether the correct amount has been sent without any iniquity, the check-up process is done between the nodes, and to check whether it has been completed properly is done via API. In general websites, these check-ups are proceeded through an app. located in the server.

Incoming Check

This is a process to check whether the remittee (recipient) has received the currency (coin).
In order to check, the API Path: account/transfers/incoming is used. Copy and paste the recipient's address into the form, and click the 'Check Incoming (button)'.

/account/transfers/incoming

Check Outgoing

Same as incoming check, the outgoing check is done via API as well.
In order to check, the API Path: account/transfers/outgoing is used. Copy and paste the sender's address into the form, and click the 'Check Outgoing (button)'.

/account/transfers/outgoing

Check Sync between Nodes

Here, it explains how to check whether the transactions above has been syncronised with other nodes or not.
Enter the name of the nodes in the host name of the URL: http:///account/transfers/incoming?address=address , then access from a browser. If the information on transactions have been syncronised between the other nodes, the same results as above will appear on the page.

Issue and Distribution on Original Coin/Token

Previously, the process in order to send and receive has been explained. Meantime, the defaulted currency that was used in mijin is XEM. Perhaps, there might be some requests that one would prefer to send and recieve original coins. For example, corporate tokens and regional coins.

It is possible to define original coins, and distribute the currency on the blockchain as the Mint by using the function called Mosaic of mijin. The maximum number of coin or token that can be issued is up to 9,000,000,000 units each.

How to Issue Currency

The following is the instruction in order to distribute original coins:

Currency Issue Method

  1. Create a namespace
  2. Define mosaic (Original Coin)

Borrow Space

namespace is a space where the original coins to secure the distribution on mijin's blockchains.

It will be a utility form of rental. Therefore, it is necessary to pay the rental commission to a defined account in XEM when creating a namespace. The rental commission is fixed to the rate of 5,000 micro XEM.

So let's create a namespace. The namespace that will be created in this app. is sub-namespace. Sub-namespace is literally secondary namespace created under the initial (root-level) namespace. We keep the initial namespace blank in this app..

/transaction/announce

API Path: /account/namespace/page will be used in order to check whether the namespace has been secured or not.

Enter the creator's address, and click 'Check namespace' button.

/account/namespace/page

Issue Coins

Once the namespace is secured, the next step would be to define and issue the original coins. These coins will be issued by using a function called mosaic. mosaic is a unit for coins (= name of the coins). The defined coins will be maintained on the namespace. The name of the coins and the sending amount will be given together with namespace info to a parameter when sending the coins.

Now let's issue original currency (coins).

Look up in API Creating mosaic for items.
Enter the namespace that has been created in the namespace.
The minimum value of sub unit that can divide the mosaic, would be the decimal places that can be choosed when remitting. It is possible to set and collect the defined original currency for the commission instead of XEM. For this instance, 1 XEM (= a namespace for NEM) is collected as a commission.
Also, it is possible to set one's own address as a recipient of the commission when sending a mosaic.

/transaction/announce



  • 1...commission is always needed when transfer the original coin.
  • 2...commission is depended on the amount of transferred original coin.

Here is an explanation on how to check whether the peculiar original (coins) has been issued or not.

API Path: /account/mosaic/definition/page is used. In the following form, enter the creator's address and click 'Check mosaic'.

/account/mosaic/owned

Distribute Coins

Let's send the coins to the other party.
The initial holder of the coins is the initial account (creator's account) that has been created. Therefore, it is necessary to send the original coins from the initial account (creator's account) to other accounts.

In this instance, 1 XEM will be collected as a commission. 1 XEM will be remitted together with mosaic. If a currency besides XEM is used to collect the commission, such as a original currency (coins), it is necessary to array a original currency by remitting mosaic, and then transact to remit.
Only XEM and a single mosaic are valid to send within the JavaScript that is used in this tutorial.

Enter the Mosaic's Namespace and the Mosaic's name, which were created in the previsous steps, into the form. Then copy and paste the remittee (recipient)'s address, and click 'Send (button)'.

/transaction/announce


Check Received Coins

In order to check the incoming of the original coins, it is necessary to check through API Path: /account/transfers/incoming like when remitting XEM.

/account/transfers/incoming

The holding status on coins, including mosaic, can be checked by API Path: /account/mosaic/owned .

/account/mosaic/owned

If the coins have been received without any problems, the received mosaics should appear on 'mosaics' of the 'transaction' in the refund results. In order to check the opposite, whether XEM has been sent properly or not, can be checked by API path: /account/transfers/outgoing .

And this is the end of the Tutorial.


Revision history

  • 2017 March:1st edition

Transaction

				

Response

				

Posted JSON object