diff --git a/docs/source/core_concepts/index.rst b/docs/source/core_concepts/index.rst index f6f39e5f8f..471375325e 100644 --- a/docs/source/core_concepts/index.rst +++ b/docs/source/core_concepts/index.rst @@ -1,3 +1,5 @@ +.. _core-concepts: + Core concepts ============= diff --git a/docs/source/getting_started/cli-guide.rst b/docs/source/getting_started/cli-guide.rst new file mode 100644 index 0000000000..7e833e5058 --- /dev/null +++ b/docs/source/getting_started/cli-guide.rst @@ -0,0 +1,136 @@ +CLI guide: sending your first transactions and queries +====================================================== + +You can interact with Iroha using various ways. You can use our client libraries +to write code in various programming languages (e.g. Java, Python, Javascript, +Swift) which communicates with Iroha. Alternatively, you can use ``iroha-cli`` – +our command-line tool for interacting with Iroha. As a part of this guide, +let's get familiar with ``iroha-cli`` + +.. Attention:: Despite that ``iroha-cli`` is arguably the simplest way to start + working with Iroha, ``iroha-cli`` was engineered very fast and lacks tests, + so user experience might not be the best. For example, the order of menu items + can differ from that you see in this guide. In the future, we will deliver a + better version and appreciate contributions. + +.. raw:: html + + + +Open a new terminal (note that Iroha container and ``irohad`` should be up and +running) and attach to an ``iroha`` docker container: + +.. code-block:: shell + + docker exec -it iroha /bin/bash + +Now you are in the interactive shell of Iroha's container again. We need to +launch ``iroha-cli`` and pass an account name of the desired user. In our example, +the account ``admin`` is already created in a ``test`` domain. Let's use this +account to work with Iroha. + +.. code-block:: shell + + iroha-cli -account_name admin@test + +.. note:: Full account name has a ``@`` symbol between name and domain. Note + that the keypair has the same name. + +Creating the First Transaction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can see the interface of ``iroha-cli`` now. Let's create a new asset, add +some asset to the admin account and transfer it to other account. To achieve +this, please choose option ``1. New transaction (tx)`` by writing ``tx`` or +``1`` to a console. + +Now you can see a list of available commands. Let's try creating a new asset. +Select ``14. Create Asset (crt_ast)``. Now enter a name for your asset, for +example ``coolcoin``. Next, enter a Domain ID. In our example we already have a +domain ``test``, so let's use it. Then we need to enter an asset precision +– the amount of numbers in a fractional part. Let's set precision to ``2``. + +Congratulations, you have created your first command and added it to a +transaction! You can either send it to Iroha or add some more commands +``1. Add one more command to the transaction (add)``. Let's add more commands, +so we can do everything in one shot. Type ``add``. + +Now try adding some ``coolcoins`` to our account. Select ``16. Add Asset +Quantity (add_ast_qty)``, enter Account ID – ``admin@test``, asset ID – +``coolcoin#test``, integer part and precision. For example, to add 200.50 +``coolcoins``, we need to enter integer part as ``20050`` and precision as +``2``, so it becomes ``200.50``. + +.. note:: Full asset name has a ``#`` symbol between name and domain. + +Let's transfer 100.50 ``coolcoins`` from ``admin@test`` to ``test@test`` +by adding one more command and choosing ``5. Transfer Assets (tran_ast)``. +Enter Source Account and Destination Account, in our case ``admin@test`` and +``test@test``, Asset ID (``coolcoin#test``), integer part and precision +(``10050`` and ``2`` accordingly). + +Now we need to send our transaction to Iroha peer (``2. Send to Iroha peer +(send)``). Enter peer address (in our case ``localhost``) and port (``50051``). +Congratulations, your transaction is submitted and you can see your transaction +hash. You can use it to check transaction's status. + +Go back to a terminal where ``irohad`` is running. You can see logs of your +transaction. + +Congratulations! You have submitted your first transaction to Iroha. + +Creating the First Query +^^^^^^^^^^^^^^^^^^^^^^^^ + +Now let's check if ``coolcoins`` were successfully transferred from +``admin@test`` to ``test@test``. Choose ``2. New query +(qry)``. ``7. Get Account's Assets (get_acc_ast)`` can help you to check if +``test@test`` now has ``coolcoin``. Form a query in a similar way you did with +commands you did with commands and ``1. Send to Iroha peer (send)``. Now you +can see information about how many ``coolcoin`` does ``test@test`` have. +It will look similar to this: + +.. code:: + + [2018-03-21 12:33:23.179275525][th:36][info] QueryResponseHandler [Account Assets] + [2018-03-21 12:33:23.179329199][th:36][info] QueryResponseHandler -Account Id:- test@test + [2018-03-21 12:33:23.179338394][th:36][info] QueryResponseHandler -Asset Id- coolcoin#test + [2018-03-21 12:33:23.179387969][th:36][info] QueryResponseHandler -Balance- 100.50`` + +Congratulations! You have submitted your first query to Iroha and got a +response! + +.. hint:: To get information about all available commands and queries + please check our API section. + +Being Badass +^^^^^^^^^^^^ + +Let's try being badass and cheat Iroha. For example, let's transfer more +``coolcoins`` than ``admin@test`` has. Try to transfer 100000.00 ``coolcoins`` +from ``admin@test`` to ``test@test``. Again, proceed to ``1. New transaction +(tx)``, ``5. Transfer Assets (tran_ast)``, enter Source Account and Destination +Account, in our case ``admin@test`` and ``test@test``, Asset ID +(``coolcoin#test``), integer part and precision (``10000000`` and ``2`` +accordingly). Send a transaction to Iroha peer as you did before. Well, it says + +.. code:: + + [2018-03-21 12:58:40.791297963][th:520][info] TransactionResponseHandler Transaction successfully sent + Congratulation, your transaction was accepted for processing. + Its hash is fc1c23f2de1b6fccbfe1166805e31697118b57d7bb5b1f583f2d96e78f60c241 + +`Your transaction was accepted for processing`. Does it mean that we +had successfully cheated Iroha? Let's try to see transaction's status. Choose +``3. New transaction status request (st)`` and enter transaction's hash which +you can get in the console after the previous command. Let's send it to Iroha. +It replies with: + +.. code:: + + Transaction has not passed stateful validation. + +Apparently no. Our transaction was not accepted because it did not pass +stateful validation and ``coolcoins`` were not transferred. You can check +the status of ``admin@test`` and ``test@test`` with queries to be sure +(like we did earlier). diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index 252bc047cf..6ef8a06730 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -8,18 +8,19 @@ couple of transactions, and check the data written in the ledger. To keep things simple, we will use Docker. .. note:: Ledger is the synonym for a blockchain, and Hyperledger Iroha is - known also as Distributed Ledger Technology — which in essence is the same + known also as Distributed Ledger Technology framework — which in essence is the same as "blockchain framework". You can check the rest of terminology used in - the Glossary section. + the :ref:`core-concepts` section. Prerequisites ------------- -For this guide, you need a computer running Unix-like system with ``docker`` +For this guide, you need a machine with ``Docker`` installed. You can read how to install it on a `Docker's website `_. -.. note:: Please note that you can use Iroha without ``docker`` as well. You - can read about it in other parts of documentation. +.. note:: Of course you can build Iroha from scratch, modify its code and launch a customized node! + If you are curious how to do that — you can check :ref:`build-guide` section. + In this guide we will use a standard distribution of Iroha available as a docker image. Starting Iroha Node ------------------- @@ -53,7 +54,8 @@ have created before, and expose ports for communication: -e POSTGRES_PASSWORD=mysecretpassword \ -p 5432:5432 \ --network=iroha-network \ - -d postgres:9.5 + -d postgres:9.5 \ + -c 'max_prepared_transactions=100' .. note:: If you already have Postgres running on a host system on default port (5432), then you should pick another free port that will be occupied. For @@ -61,66 +63,66 @@ have created before, and expose ports for communication: Creating Blockstore ^^^^^^^^^^^^^^^^^^^ -Before we run Iroha container, we should create persistent volume to store +Before we run Iroha container, we may create a persistent volume to store files, storing blocks for the chain. It is done via the following command: .. code-block:: shell docker volume create blockstore -Configuring Iroha Network -^^^^^^^^^^^^^^^^^^^^^^^^^ +Preparing the configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: To keep things simple, in this guide we will create a network - containing only one node. To understand how to run several peers, follow - `this guide. `_ + containing only a single node. To understand how to run several peers, follow + :ref:`deploy-guide` Now we need to configure our Iroha network. This includes creating a configuration file, generating keypairs for a users, writing a list of peers -and creating a genesis block. However, we have prepared an example -configuration for this guide, so you can start playing with Iroha faster. -In order to get those files, you need to clone the -`Iroha repository `_ from Github. +and creating a genesis block. + +Don't be scared away — we have prepared an example configuration for this guide, so you can start testing Iroha node now. +In order to get those files, you need to clone the `Iroha repository `_ from Github or copy them manually (cloning is faster, though). .. code-block:: shell git clone -b master https://github.com/hyperledger/iroha --depth=1 -.. hint:: ``--depth=1`` option allows us to download only latest commit and +.. hint:: ``--depth=1`` option allows us to download only the latest commit and save some time and bandwidth. If you want to get a full commit history, you can omit this option. +There is a guide on how to set up the parameters and tune them with respect to your environment and load expectations: :ref:`configuration`. +We don't need to do this at the moment. + Starting Iroha Container ^^^^^^^^^^^^^^^^^^^^^^^^ -We are ready to launch our Iroha container. Let's do it with the following -command +We are almost ready to launch our Iroha container. +You just need to know the path to configuration files (from the step above). + +Let's start Iroha node in Docker container via the following command: .. code-block:: shell - docker run -it --name iroha \ + docker run --name iroha \ -p 50051:50051 \ - -v $(pwd)/iroha/example:/opt/iroha_data \ + -v YOUR_PATH_TO_CONF_FILES:/opt/iroha_data \ -v blockstore:/tmp/block_store \ --network=iroha-network \ - --entrypoint=/bin/bash \ + -e KEY='node0' \ hyperledger/iroha:latest -Let's look in detail what this command does: - -- ``docker run -it --name iroha \`` attaches you to docker container called - ``iroha`` -- with ``$(pwd)/iroha/example:/opt/iroha_data \`` we add a folder containing - our prepared configuration to a docker container into ``/opt/iroha_data``. -- ``-v blockstore:/tmp/block_store \`` adds a persistent block storage which - we created before to a container, so our blocks won't be lost after we stop - the container -- ``--network=iroha-network \`` adds our container to previously created - ``iroha-network``, so Iroha and Postgres could see each other. -- ``--entrypoint=/bin/bash \`` Because ``hyperledger/iroha`` has - the custom script which runs after starting the container, we want to - override it so we can start Iroha Daemon manually. -- ``hyperledger/iroha:latest`` is the image which has the ``master`` - branch. +If you started the node successfully you would see the logs in the same console where you started the container. + +Let's look in details what this command does: + +- ``docker run --name iroha \`` creates a container ``iroha`` +- ``-p 50051:50051 \`` exposes a port for communication with a client (we will use this later) +- ``-v YOUR_PATH_TO_CONF_FILES:/opt/iroha_data \`` is how we pass our configuration files to docker container. If you want to use an example to try Iroha out, you can use ``$(pwd)/iroha/example:/opt/iroha_data \`` +- ``-v blockstore:/tmp/block_store \`` adds persistent block storage (Docker volume) to a container, so that the blocks aren't lost after we stop the container +- ``--network=iroha-network \`` adds our container to previously created ``iroha-network`` for communication with PostgreSQL server +- ``hyperledger/iroha:latest`` is a reference to the image pointing to the last `release `__ + Launching Iroha Daemon ^^^^^^^^^^^^^^^^^^^^^^ @@ -136,144 +138,14 @@ Iroha, we need to launch Iroha daemon – ``irohad``. example configuration for you. Please do not use these settings in a production. You can read more about configuration here. -Congratulations! You have an Iroha node up and running! In the next section, we -will test it by sending some transactions. - -.. hint:: You can get more information about ``irohad`` and its launch options - in this section - -Interacting with Iroha Network ------------------------------- -You can interact with Iroha using various ways. You can use our client libraries -to write code in various programming languages (e.g. Java, Python, Javascript, -Swift) which communicates with Iroha. Alternatively, you can use ``iroha-cli`` – -our command-line tool for interacting with Iroha. As a part of this guide, -let's get familiar with ``iroha-cli`` - -.. Attention:: Despite that ``iroha-cli`` is arguably the simplest way to start - working with Iroha, ``iroha-cli`` was engineered very fast and lacks tests, - so user experience might not be the best. For example, the order of menu items - can differ from that you see in this guide. In the future, we will deliver a - better version and appreciate contributions. - -.. raw:: html - - - -Open a new terminal (note that Iroha container and ``irohad`` should be up and -running) and attach to an ``iroha`` docker container: - -.. code-block:: shell - - docker exec -it iroha /bin/bash - -Now you are in the interactive shell of Iroha's container again. We need to -launch ``iroha-cli`` and pass an account name of the desired user. In our example, -the account ``admin`` is already created in a ``test`` domain. Let's use this -account to work with Iroha. - -.. code-block:: shell - - iroha-cli -account_name admin@test - -.. note:: Full account name has a ``@`` symbol between name and domain. Note - that the keypair has the same name. - -Creating the First Transaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can see the interface of ``iroha-cli`` now. Let's create a new asset, add -some asset to the admin account and transfer it to other account. To achieve -this, please choose option ``1. New transaction (tx)`` by writing ``tx`` or -``1`` to a console. - -Now you can see a list of available commands. Let's try creating a new asset. -Select ``14. Create Asset (crt_ast)``. Now enter a name for your asset, for -example ``coolcoin``. Next, enter a Domain ID. In our example we already have a -domain ``test``, so let's use it. Then we need to enter an asset precision -– the amount of numbers in a fractional part. Let's set precision to ``2``. - -Congratulations, you have created your first command and added it to a -transaction! You can either send it to Iroha or add some more commands -``1. Add one more command to the transaction (add)``. Let's add more commands, -so we can do everything in one shot. Type ``add``. - -Now try adding some ``coolcoins`` to our account. Select ``16. Add Asset -Quantity (add_ast_qty)``, enter Account ID – ``admin@test``, asset ID – -``coolcoin#test``, integer part and precision. For example, to add 200.50 -``coolcoins``, we need to enter integer part as ``20050`` and precision as -``2``, so it becomes ``200.50``. - -.. note:: Full asset name has a ``#`` symbol between name and domain. - -Let's transfer 100.50 ``coolcoins`` from ``admin@test`` to ``test@test`` -by adding one more command and choosing ``5. Transfer Assets (tran_ast)``. -Enter Source Account and Destination Account, in our case ``admin@test`` and -``test@test``, Asset ID (``coolcoin#test``), integer part and precision -(``10050`` and ``2`` accordingly). - -Now we need to send our transaction to Iroha peer (``2. Send to Iroha peer -(send)``). Enter peer address (in our case ``localhost``) and port (``50051``). -Congratulations, your transaction is submitted and you can see your transaction -hash. You can use it to check transaction's status. - -Go back to a terminal where ``irohad`` is running. You can see logs of your -transaction. - -Congratulations! You have submitted your first transaction to Iroha. - -Creating the First Query -^^^^^^^^^^^^^^^^^^^^^^^^ - -Now let's check if ``coolcoins`` were successfully transferred from -``admin@test`` to ``test@test``. Choose ``2. New query -(qry)``. ``7. Get Account's Assets (get_acc_ast)`` can help you to check if -``test@test`` now has ``coolcoin``. Form a query in a similar way you did with -commands you did with commands and ``1. Send to Iroha peer (send)``. Now you -can see information about how many ``coolcoin`` does ``test@test`` have. -It will look similar to this: - -.. code:: - - [2018-03-21 12:33:23.179275525][th:36][info] QueryResponseHandler [Account Assets] - [2018-03-21 12:33:23.179329199][th:36][info] QueryResponseHandler -Account Id:- test@test - [2018-03-21 12:33:23.179338394][th:36][info] QueryResponseHandler -Asset Id- coolcoin#test - [2018-03-21 12:33:23.179387969][th:36][info] QueryResponseHandler -Balance- 100.50`` - -Congratulations! You have submitted your first query to Iroha and got a -response! - -.. hint:: To get information about all available commands and queries - please check our API section. - -Being Badass -^^^^^^^^^^^^ - -Let's try being badass and cheat Iroha. For example, let's transfer more -``coolcoins`` than ``admin@test`` has. Try to transfer 100000.00 ``coolcoins`` -from ``admin@test`` to ``test@test``. Again, proceed to ``1. New transaction -(tx)``, ``5. Transfer Assets (tran_ast)``, enter Source Account and Destination -Account, in our case ``admin@test`` and ``test@test``, Asset ID -(``coolcoin#test``), integer part and precision (``10000000`` and ``2`` -accordingly). Send a transaction to Iroha peer as you did before. Well, it says - -.. code:: - - [2018-03-21 12:58:40.791297963][th:520][info] TransactionResponseHandler Transaction successfully sent - Congratulation, your transaction was accepted for processing. - Its hash is fc1c23f2de1b6fccbfe1166805e31697118b57d7bb5b1f583f2d96e78f60c241 - -`Your transaction was accepted for processing`. Does it mean that we -had successfully cheated Iroha? Let's try to see transaction's status. Choose -``3. New transaction status request (st)`` and enter transaction's hash which -you can get in the console after the previous command. Let's send it to Iroha. -It replies with: +Congratulations! You have an Iroha node up and running! +You can try using one of many sample guides in order to send some transactions to Iroha and query its state. -.. code:: +Try other guides +---------------- - Transaction has not passed stateful validation. +.. toctree:: + :maxdepth: 1 -Apparently no. Our transaction was not accepted because it did not pass -stateful validation and ``coolcoins`` were not transferred. You can check -the status of ``admin@test`` and ``test@test`` with queries to be sure -(like we did earlier). + cli-guide.rst + python-guide.rst diff --git a/docs/source/getting_started/python-guide.rst b/docs/source/getting_started/python-guide.rst new file mode 100644 index 0000000000..0422deb2fa --- /dev/null +++ b/docs/source/getting_started/python-guide.rst @@ -0,0 +1,81 @@ +Sending transactions with Python library +======================================== + +Prerequisites +------------- + +.. note:: the library only works in Python 3 environment (Python 2 is not supported now). + +To use Iroha Python library, you need to get it from the `repository `_ or via pip3: + +.. code-block:: shell + + pip3 install iroha + +Now, as we have the library, we can start sending the actual transactions. + +Running example transactions +---------------------------- + +If you only want to try what Iroha transactions would look like, you can simply go to the examples from the repository `here `_. Let's check out the `tx-example.py` file. + +Here are Iroha dependancies. Python library generally consists of 3 parts: Iroha, IrohaCrypto and IrohaGrpc which we need to import: + +.. code-block:: shell + from iroha.primitive_pb2 import can_set_my_account_detail + from iroha import Iroha, IrohaGrpc + from iroha import IrohaCrypto + +The line `from iroha.primitive_pb2 import can_set_my_account_detail` is actually about the permissions you might be using for the transaction. You can find a full list here: ref:`Permissions`. + +In the next block we can see the following: + +.. code-block:: shell + admin_private_key = 'f101537e319568c765b2cc89698325604991dca57b9716b58016b253506cab70' + user_private_key = IrohaCrypto.private_key() + user_public_key = IrohaCrypto.derive_public_key(user_private_key) + iroha = Iroha('admin@test') + net = IrohaGrpc() + +Here you can see the example account information. It will be used later with the commands. +If you change the commands in the transaction, the set of data in this part might also change depending on what you need. + +Defining the commands +--------------------- + +Let's look at the first of the difined commands: + +.. code-block:: shell + def create_domain_and_asset(): + commands = [ + iroha.command('CreateDomain', domain_id='domain', default_role='user'), + iroha.command('CreateAsset', asset_name='coin', + domain_id='domain', precision=2) + ] + tx = IrohaCrypto.sign_transaction( + iroha.transaction(commands), admin_private_key) + send_transaction_and_print_status(tx) + +Here we define a transaction made of 2 commands: CreateDomain and CreateAsset. You can find a full list here: ref:`commands`. +Each of Iroha commands has its own set of parameters. You can check them in command descriptions in ref:`iroha-api-reference`. + +Then we sign the transaction with the parameters defined earlier. + +You can define ref:`queries` the same way. + +Running the commands +-------------------- + +Last lines + +.. code-block:: shell + create_domain_and_asset() + add_coin_to_admin() + create_account_userone() + ... + +run the commands defined previously. + +Now, if you have `irohad` running, you can run the example or you own file by simply opening the .py file in another tab. + + diff --git a/docs/source/guides/build.rst b/docs/source/guides/build.rst index 3e36150b76..4193ab222e 100644 --- a/docs/source/guides/build.rst +++ b/docs/source/guides/build.rst @@ -1,3 +1,5 @@ +.. _build-guide: + Building Iroha ============== diff --git a/docs/source/guides/configuration.rst b/docs/source/guides/configuration.rst index 35a310a801..fd527747db 100644 --- a/docs/source/guides/configuration.rst +++ b/docs/source/guides/configuration.rst @@ -1,3 +1,5 @@ +.. _configuration: + Configuration ============= diff --git a/docs/source/guides/deployment.rst b/docs/source/guides/deployment.rst index ee40b861df..bc85783d5e 100644 --- a/docs/source/guides/deployment.rst +++ b/docs/source/guides/deployment.rst @@ -1,3 +1,5 @@ +.. _deploy-guide: + Deploying Iroha =============== diff --git a/docs/source/maintenance/permissions.rst b/docs/source/maintenance/permissions.rst index b1cd060a6a..fffc00ac2a 100644 --- a/docs/source/maintenance/permissions.rst +++ b/docs/source/maintenance/permissions.rst @@ -374,7 +374,7 @@ The corresponding `command <../core_concepts/glossary.html#command>`__ can be ex .. literalinclude:: ../../../example/python/permissions/can_add_domain_asset_qty.py :language: python :linenos: - :lines: 1-8 + :lines: 1-10 can_subtract_domain_asset_qty ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -388,7 +388,7 @@ The corresponding `command <../core_concepts/glossary.html#command>`__ can be ex .. literalinclude:: ../../../example/python/permissions/can_subtract_domain_asset_qty.py :language: python :linenos: - :lines: 1-8 + :lines: 1-10 Domain ------