This repository has been archived by the owner on Jan 18, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 25
/
index.html
2416 lines (2331 loc) · 128 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>Iroha API reference</title>
<style>
.highlight table td { padding: 5px; }
.highlight table pre { margin: 0; }
.highlight .gh {
color: #999999;
}
.highlight .sr {
color: #f6aa11;
}
.highlight .go {
color: #888888;
}
.highlight .gp {
color: #555555;
}
.highlight .gs {
}
.highlight .gu {
color: #aaaaaa;
}
.highlight .nb {
color: #f6aa11;
}
.highlight .cm {
color: #75715e;
}
.highlight .cp {
color: #75715e;
}
.highlight .c1 {
color: #75715e;
}
.highlight .cs {
color: #75715e;
}
.highlight .c, .highlight .cd {
color: #75715e;
}
.highlight .err {
color: #960050;
}
.highlight .gr {
color: #960050;
}
.highlight .gt {
color: #960050;
}
.highlight .gd {
color: #49483e;
}
.highlight .gi {
color: #49483e;
}
.highlight .ge {
color: #49483e;
}
.highlight .kc {
color: #66d9ef;
}
.highlight .kd {
color: #66d9ef;
}
.highlight .kr {
color: #66d9ef;
}
.highlight .no {
color: #66d9ef;
}
.highlight .kt {
color: #66d9ef;
}
.highlight .mf {
color: #ae81ff;
}
.highlight .mh {
color: #ae81ff;
}
.highlight .il {
color: #ae81ff;
}
.highlight .mi {
color: #ae81ff;
}
.highlight .mo {
color: #ae81ff;
}
.highlight .m, .highlight .mb, .highlight .mx {
color: #ae81ff;
}
.highlight .sc {
color: #ae81ff;
}
.highlight .se {
color: #ae81ff;
}
.highlight .ss {
color: #ae81ff;
}
.highlight .sd {
color: #e6db74;
}
.highlight .s2 {
color: #e6db74;
}
.highlight .sb {
color: #e6db74;
}
.highlight .sh {
color: #e6db74;
}
.highlight .si {
color: #e6db74;
}
.highlight .sx {
color: #e6db74;
}
.highlight .s1 {
color: #e6db74;
}
.highlight .s {
color: #e6db74;
}
.highlight .na {
color: #a6e22e;
}
.highlight .nc {
color: #a6e22e;
}
.highlight .nd {
color: #a6e22e;
}
.highlight .ne {
color: #a6e22e;
}
.highlight .nf {
color: #a6e22e;
}
.highlight .vc {
color: #ffffff;
}
.highlight .nn {
color: #ffffff;
}
.highlight .nl {
color: #ffffff;
}
.highlight .ni {
color: #ffffff;
}
.highlight .bp {
color: #ffffff;
}
.highlight .vg {
color: #ffffff;
}
.highlight .vi {
color: #ffffff;
}
.highlight .nv {
color: #ffffff;
}
.highlight .w {
color: #ffffff;
}
.highlight {
color: #ffffff;
}
.highlight .n, .highlight .py, .highlight .nx {
color: #ffffff;
}
.highlight .ow {
color: #f92672;
}
.highlight .nt {
color: #f92672;
}
.highlight .k, .highlight .kv {
color: #f92672;
}
.highlight .kn {
color: #f92672;
}
.highlight .kp {
color: #f92672;
}
.highlight .o {
color: #f92672;
}
</style>
<link href="stylesheets/screen.css" rel="stylesheet" media="screen" />
<link href="stylesheets/print.css" rel="stylesheet" media="print" />
<script src="javascripts/all.js"></script>
<script>
((window.gitter = {}).chat = {}).options = {
room: 'hyperledger-iroha/Lobby'
};
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
</head>
<body class="index" data-languages="["protobuf","json"]">
<a href="#" id="nav-button">
<span>
NAV
<img src="images/navbar.png" alt="Navbar" />
</span>
</a>
<div class="toc-wrapper">
<img src="images/logo.png" class="logo" alt="Logo" />
<div class="lang-selector">
<a href="#" data-language-name="protobuf">protobuf</a>
<a href="#" data-language-name="json">json</a>
</div>
<div class="search">
<input type="text" class="search" id="input-search" placeholder="Search">
</div>
<ul class="search-results"></ul>
<div id="toc" class="toc-list-h1">
<li>
<a href="#overview" class="toc-h1 toc-link" data-title="Overview">Overview</a>
<ul class="toc-list-h2">
<li>
<a href="#elevator-pitch-for-iroha" class="toc-h2 toc-link" data-title="Overview">Elevator pitch for Iroha</a>
</li>
<li>
<a href="#purpose-of-the-docs-you-are-reading" class="toc-h2 toc-link" data-title="Overview">Purpose of the docs you are reading</a>
</li>
<li>
<a href="#try-it-yourself" class="toc-h2 toc-link" data-title="Overview">Try it yourself</a>
</li>
</ul>
</li>
<li>
<a href="#build" class="toc-h1 toc-link" data-title="Build">Build</a>
<ul class="toc-list-h2">
<li>
<a href="#docker" class="toc-h2 toc-link" data-title="Build">Docker</a>
</li>
<li>
<a href="#linux-or-macos" class="toc-h2 toc-link" data-title="Build">Linux or macOS</a>
</li>
</ul>
</li>
<li>
<a href="#run-the-daemon-irohad" class="toc-h1 toc-link" data-title="Run the daemon (irohad)">Run the daemon (irohad)</a>
<ul class="toc-list-h2">
<li>
<a href="#create-genesis-block" class="toc-h2 toc-link" data-title="Run the daemon (irohad)">Create genesis block</a>
</li>
<li>
<a href="#prepare-configuration-file" class="toc-h2 toc-link" data-title="Run the daemon (irohad)">Prepare configuration file</a>
</li>
<li>
<a href="#launch-irohad" class="toc-h2 toc-link" data-title="Run the daemon (irohad)">Launch irohad</a>
</li>
</ul>
</li>
<li>
<a href="#block-structure" class="toc-h1 toc-link" data-title="Block structure">Block structure</a>
<ul class="toc-list-h2">
<li>
<a href="#outside-payload" class="toc-h2 toc-link" data-title="Block structure">Outside payload</a>
</li>
<li>
<a href="#inside-payload" class="toc-h2 toc-link" data-title="Block structure">Inside payload</a>
</li>
</ul>
</li>
<li>
<a href="#transactions" class="toc-h1 toc-link" data-title="Transactions">Transactions</a>
<ul class="toc-list-h2">
<li>
<a href="#transaction-structure" class="toc-h2 toc-link" data-title="Transactions">Transaction structure</a>
</li>
<li>
<a href="#transaction-statuses" class="toc-h2 toc-link" data-title="Transactions">Transaction statuses</a>
</li>
</ul>
</li>
<li>
<a href="#commands" class="toc-h1 toc-link" data-title="Commands">Commands</a>
<ul class="toc-list-h2">
<li>
<a href="#add-asset-quantity" class="toc-h2 toc-link" data-title="Commands">Add asset quantity</a>
</li>
<li>
<a href="#add-peer" class="toc-h2 toc-link" data-title="Commands">Add peer</a>
</li>
<li>
<a href="#add-signatory" class="toc-h2 toc-link" data-title="Commands">Add signatory</a>
</li>
<li>
<a href="#append-role" class="toc-h2 toc-link" data-title="Commands">Append role</a>
</li>
<li>
<a href="#create-account" class="toc-h2 toc-link" data-title="Commands">Create account</a>
</li>
<li>
<a href="#create-asset" class="toc-h2 toc-link" data-title="Commands">Create asset</a>
</li>
<li>
<a href="#create-domain" class="toc-h2 toc-link" data-title="Commands">Create domain</a>
</li>
<li>
<a href="#create-role" class="toc-h2 toc-link" data-title="Commands">Create role</a>
</li>
<li>
<a href="#detach-role" class="toc-h2 toc-link" data-title="Commands">Detach role</a>
</li>
<li>
<a href="#grant-permission" class="toc-h2 toc-link" data-title="Commands">Grant permission</a>
</li>
<li>
<a href="#remove-signatory" class="toc-h2 toc-link" data-title="Commands">Remove signatory</a>
</li>
<li>
<a href="#revoke-permission" class="toc-h2 toc-link" data-title="Commands">Revoke permission</a>
</li>
<li>
<a href="#set-account-detail" class="toc-h2 toc-link" data-title="Commands">Set account detail</a>
</li>
<li>
<a href="#set-account-quorum" class="toc-h2 toc-link" data-title="Commands">Set account quorum</a>
</li>
<li>
<a href="#subtract-asset-quantity" class="toc-h2 toc-link" data-title="Commands">Subtract asset quantity</a>
</li>
<li>
<a href="#transfer-asset" class="toc-h2 toc-link" data-title="Commands">Transfer asset</a>
</li>
</ul>
</li>
<li>
<a href="#queries" class="toc-h1 toc-link" data-title="Queries">Queries</a>
<ul class="toc-list-h2">
<li>
<a href="#query-structure" class="toc-h2 toc-link" data-title="Queries">Query structure</a>
</li>
<li>
<a href="#validation" class="toc-h2 toc-link" data-title="Queries">Validation</a>
</li>
<li>
<a href="#get-account" class="toc-h2 toc-link" data-title="Queries">Get account</a>
</li>
<li>
<a href="#get-signatories" class="toc-h2 toc-link" data-title="Queries">Get signatories</a>
</li>
<li>
<a href="#get-account-transactions" class="toc-h2 toc-link" data-title="Queries">Get account transactions</a>
</li>
<li>
<a href="#get-account-asset-transactions" class="toc-h2 toc-link" data-title="Queries">Get account asset transactions</a>
</li>
<li>
<a href="#get-transactions" class="toc-h2 toc-link" data-title="Queries">Get transactions</a>
</li>
<li>
<a href="#get-account-assets" class="toc-h2 toc-link" data-title="Queries">Get account assets</a>
</li>
<li>
<a href="#get-asset-info" class="toc-h2 toc-link" data-title="Queries">Get asset info</a>
</li>
<li>
<a href="#get-roles" class="toc-h2 toc-link" data-title="Queries">Get roles</a>
</li>
<li>
<a href="#get-role-permissions" class="toc-h2 toc-link" data-title="Queries">Get role permissions</a>
</li>
</ul>
</li>
<li>
<a href="#entity-relationship-model" class="toc-h1 toc-link" data-title="Entity-relationship model">Entity-relationship model</a>
<ul class="toc-list-h2">
<li>
<a href="#peer" class="toc-h2 toc-link" data-title="Entity-relationship model">Peer</a>
</li>
<li>
<a href="#asset" class="toc-h2 toc-link" data-title="Entity-relationship model">Asset</a>
</li>
<li>
<a href="#signatory" class="toc-h2 toc-link" data-title="Entity-relationship model">Signatory</a>
</li>
<li>
<a href="#domain" class="toc-h2 toc-link" data-title="Entity-relationship model">Domain</a>
</li>
<li>
<a href="#role" class="toc-h2 toc-link" data-title="Entity-relationship model">Role</a>
</li>
<li>
<a href="#account" class="toc-h2 toc-link" data-title="Entity-relationship model">Account</a>
</li>
</ul>
</li>
<li>
<a href="#command-line-interface" class="toc-h1 toc-link" data-title="Command Line Interface">Command Line Interface</a>
<ul class="toc-list-h2">
<li>
<a href="#keypair-generation" class="toc-h2 toc-link" data-title="Command Line Interface">Keypair generation</a>
</li>
<li>
<a href="#interactive-mode" class="toc-h2 toc-link" data-title="Command Line Interface">Interactive mode </a>
</li>
<li>
<a href="#starting-menu" class="toc-h2 toc-link" data-title="Command Line Interface">Starting menu </a>
</li>
<li>
<a href="#transaction-cli" class="toc-h2 toc-link" data-title="Command Line Interface">Transaction CLI</a>
</li>
<li>
<a href="#query-cli" class="toc-h2 toc-link" data-title="Command Line Interface">Query CLI</a>
</li>
</ul>
</li>
</div>
<ul class="toc-footer">
<li><a href='https://github.com/hyperledger/iroha'>Hyperledger Iroha GitHub</a></li>
<li><a href='https://github.com/tripit/slate'>Documentation Powered by Slate</a></li>
</ul>
</div>
<div class="page-wrapper">
<div class="dark-box"></div>
<div class="content">
<h1 id='overview'>Overview</h1>
<p>Welcome to the Hyperledger Iroha API docs!</p>
<h2 id='elevator-pitch-for-iroha'>Elevator pitch for Iroha</h2>
<p>The system is a distributed ledger platform, capable of storing all history of state-changing actions (called transactions) in immutable linear history (called blockchain). The system is intended to be used in enterprise or between untrusted agents as <strong>private chain platform</strong>, but not as a public chain — key difference is that not everyone is allowed to store the whole history. A subset of users can only query some data (perform a query) if their accounts have required permissions, while others maintain a peer (Iroha is a peer network), which stores history. </p>
<p>Reliability and security are provided with cryptographic capabilities and <strong>Byzantine Fault Tolerant</strong> consensus algorithm. The system is targeted to environments, where client applications are very diverse (desktop, various mobile platforms), and peer hardware varies from embedded systems to enterprise-class servers.</p>
<h2 id='purpose-of-the-docs-you-are-reading'>Purpose of the docs you are reading</h2>
<p>The documentation describes the endpoints for users to send transactions to peer network, containing one or many commands to perform allowed actions in the system, and also make queries to know the current state. Also the documentation contains explanation how to build the system, how to run it and other applicable tutorials. </p>
<p>The API is organized around protobuf format, as Iroha is using gRPC in transport level. Iroha CLI and block store use JSON format to provide developer-friendly experience for contributors. Feel free to check both sections for protobuf and JSON while exploring docs.</p>
<h2 id='try-it-yourself'>Try it yourself</h2>
<p>To try out a basic API functionality, do the following:</p>
<aside class="notice">
In case you have troubles understanding some specific terminology used — refer to the <a href="#glossary">glossary</a>.
</aside>
<ol>
<li>Run the system (<code>irohad</code> daemon) on a single node.</li>
<li>Run iroha-cli in interactive mode. Command Line Interface app is a client, showing the capabilities of the system.</li>
<li>Select a necessary action to perform. As you created an initial configuration in genesis block — use the account from genesis block to send transaction or make a query.</li>
<li>When you fill all the necessary details for commands and formed a transaction; or if you formed a query — you are ready to send it to Iroha peer. Tell the network address and port (by default it is 50051).</li>
</ol>
<aside class="success">
If everything went well and you were successful to form transaction or query with valid fields — you will get either transaction hash, which is used for querying transaction state, or query response object (see query subsection for more details).
</aside>
<h1 id='build'>Build</h1>
<p>To launch Iroha peer network, an executable daemon should be launched. Currently we support Unix-like systems (we are basically targeting at popular Linux distros and macOS), while Windows remains to be a challenge for community and we don't have any plans to support it so far.</p>
<p>If you happen to have Windows or you don't want to spend time figuring out troubles with dependencies on your system — please use Docker environment, made with care for new contributors of Iroha (and hostages of Windows).</p>
<h2 id='docker'>Docker</h2>
<p>Please, use latest available docker daemon and docker-compose. If you have troubles launching Docker container — it is likely that you have an outdated version.</p>
<h3 id='clone-git-repository'>Clone Git repository</h3>
<p>Clone Iroha <a href="https://github.com/hyperledger/iroha">repository</a> in any convenient folder on your machine.</p>
<blockquote>
<p>Cloning Iroha</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>git clone -b develop --depth<span class="o">=</span>1 <span class="se">\</span>
https://github.com/hyperledger/iroha
</code></pre><h3 id='how-to-run-development-environment'>How to run development environment</h3>
<p>Run the script <code>run-iroha-dev.sh</code>, contained in the folder <code>scripts</code>: <code>sh .../iroha/scripts/run-iroha-dev.sh</code></p>
<p>After you execute this script, following things happen:</p>
<ol>
<li>The script checks if you don't have containers with Iroha already running. It ends up with reattaching you to interactive shell upon succesful completion.</li>
<li>The script will download iroha-docker-develop, redis and postgres images. Iroha image contains all development dependencies, and is based on top of ubuntu:16.04.</li>
<li>Three containers are created and launched.</li>
<li>The user is attached to the interactive environment for development and testing with <code>iroha</code> folder mounted from the host machine. Iroha folder is mounted to <code>/opt/iroha</code> in Docker container.</li>
</ol>
<aside class="notice">
Docker environment will be removed when you detach from the container.
</aside>
<h3 id='build-project-and-run-tests'>Build project and run tests</h3>
<blockquote>
<p>Build</p>
</blockquote>
<pre class="highlight shell"><code>cmake -H. -Bbuild;
cmake --build build -- -j<span class="k">$(</span>nproc<span class="k">)</span>
</code></pre>
<aside class="notice">
On macOS $(nproc) variable does not work. Check number of logical cores with <code>sysctl -n hw.ncpu</code>
</aside>
<p>Run shell commands from "Build" section on the right. Built binaries (<code>irohad</code> and <code>iroha-cli</code>) will be in <code>./build/bin</code> directory.</p>
<p>After you built the project — please run tests to check the operability of the daemon.</p>
<h3 id='cmake-parameters'>Cmake parameters</h3>
<p>We use CMake to build platform-dependent build files. It has numerous of the flags for configuring the final build. Note that beside the listed params <a href="https://cmake.org/Wiki/CMake_Useful_Variables">cmake's vars</a> can be useful as well. Also as long as this page can be deprecated (or just not complete) you can browse custom flags via <code>cmake -L</code>, <code>cmake-gui</code>, or <code>ccmake</code>.</p>
<aside class="notice">
You can specify parameters at the <code>cmake</code> configuring stage (e.g <code>cmake -DTESTING=ON</code>).
</aside>
<h4 id='main-params'>Main params</h4>
<table><thead>
<tr>
<th>Parameter</th>
<th>Possible values</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>TESTING</td>
<td>ON/OFF</td>
<td>ON</td>
<td>Enables or disables build of the tests</td>
</tr>
<tr>
<td>BENCHMARKING</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables build of the benchmarks</td>
</tr>
<tr>
<td>COVERAGE</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables coverage</td>
</tr>
<tr>
<td>SWIG_PYTHON</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables libraries and native interface bindings for python</td>
</tr>
<tr>
<td>SWIG_JAVA</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables libraries and native interface bindings for java</td>
</tr>
</tbody></table>
<h4 id='packaging-specific-params'>Packaging specific params</h4>
<table><thead>
<tr>
<th>Parameter</th>
<th>Possible values</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>ENABLE_LIBS_PACKAGING</td>
<td>ON/OFF</td>
<td>ON</td>
<td>Enables or disables all types of packaging</td>
</tr>
<tr>
<td>PACKAGE_ZIP</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables zip packaging</td>
</tr>
<tr>
<td>PACKAGE_TGZ</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables tar.gz packaging</td>
</tr>
<tr>
<td>PACKAGE_RPM</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables rpm packaging</td>
</tr>
<tr>
<td>PACKAGE_DEB</td>
<td>ON/OFF</td>
<td>OFF</td>
<td>Enables or disables deb packaging</td>
</tr>
</tbody></table>
<h3 id='add-to-irohad-and-iroha-cli-to-path-optional'>Add to irohad and iroha-cli to path (optional)</h3>
<p><code>export PATH=.../iroha/build/bin:$PATH</code></p>
<aside class="notice">
Write this to your shell configuration to make it persistent.
</aside>
<blockquote>
<p>How to run tests method #1</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>cmake --build build --target <span class="nb">test</span>
</code></pre>
<blockquote>
<p>How to run tests method #2</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>ctest . <span class="c"># in build folder</span>
</code></pre><h3 id='execute-code-iroha-cli-code-with-code-irohad-code-running'>Execute <code>iroha-cli</code> with <code>irohad</code> running</h3>
<p>Execute <code>run-iroha-dev.sh</code> again to attach to existing container.</p>
<h2 id='linux-or-macos'>Linux or macOS</h2>
<blockquote>
<p>Launching Docker and Postgres in Docker</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>docker run --name some-redis <span class="se">\</span>
-p 6379:6379 <span class="se">\</span>
-d redis:3.2.8
docker run --name some-postgres <span class="se">\</span>
-e <span class="nv">POSTGRES_USER</span><span class="o">=</span>postgres <span class="se">\</span>
-e <span class="nv">POSTGRES_PASSWORD</span><span class="o">=</span>mysecretpassword <span class="se">\</span>
-p 5432:5432 <span class="se">\</span>
-d postgres:9.5
</code></pre>
<p>To launch Iroha daemon, running postgres and redis services are required. You may launch them on your local machine, or use docker containers, as provided on the right side.</p>
<h3 id='linux-debian-based'>Linux (debian-based)</h3>
<p>To install dependencies, clone, and build the project, please use this code:
<script src="https://gist.github.com/neewy/39557aa444c3317aeffbdedd9f0f51e2.js"></script></p>
<h4 id='outdated-dependencies'>Outdated dependencies</h4>
<p>In case that some dependencies are outdated in apt, you are advised to use following sources to install dependencies:</p>
<h5 id='boost'>Boost</h5>
<p>To install Boost libraries (<code>libboost-all-dev</code>), use <a href="http://www.boost.org/users/download/">current release</a> from Boost webpage, or use <a href="https://packages.debian.org/sid/libboost-all-dev">debian repository</a> for latest library.
The only dependencies are system and filesystem, so use <code>./bootstrap.sh --with-libraries=system,filesystem</code> when you are building the project.</p>
<h5 id='cmake'>CMake</h5>
<p>To install CMake tool (<code>cmake</code>), use <a href="https://cmake.org/download/">latest release</a> from CMake webpage.</p>
<h3 id='macos'>macOS</h3>
<blockquote>
<p>macOS brew</p>
</blockquote>
<pre class="highlight shell tab-shell"><code>brew tap soramitsu/iroha
brew install iroha
</code></pre>
<p>To install dependencies, clone, and build the project, please use this code:
<script src="https://gist.github.com/neewy/bc0fea777592a5381aa4ab6e68bfe699.js"></script></p>
<h1 id='run-the-daemon-irohad'>Run the daemon (irohad)</h1><h2 id='create-genesis-block'>Create genesis block</h2>
<p>A genesis block is the first block in the chain.</p>
<p><b>Important:</b> each peer in the initialized network should have exactly the same genesis block, so create it once and distribute across peers. This block may have <b>any</b> data, as no-one validates it in the peer network.</p>
<h3 id='using-iroha-cli'>Using iroha-cli</h3><h4 id='create-list-of-peers'>Create list of peers</h4>
<p>Create peers.list file containing network addresses of peers' internal ports in the network (<code>10001</code> by default) a single peer address goes on new line. If you want to run Iroha on single peer, it is sufficient to mention only localhost: <br> <code>$ echo 'localhost:10001' > peers.list</code></p>
<p>As an example, for 4 peers the file will look like the following:
<ul>
<li>10.128.13.1:10001</li>
<li>10.128.13.2:10001</li>
<li>10.128.13.3:10001</li>
<li>10.128.13.4:10001</li>
</ul></p>
<aside class="notice">
Internal port is used for communication of internal components. Each peer potentially may have different, adjustable internal port numbers.
</aside>
<h4 id='use-iroha-cli'>Use iroha-cli</h4>
<p>Generate genesis block using iroha-cli (see shell command on the right side).</p>
<p>Iroha-cli tool is used to generate keypairs for every peer, mentioned in the peers list. This is done only for convenience — in production environment please consider using manual or more trusted approach.</p>
<blockquote>
<p>Generating genesis block</p>
</blockquote>
<pre class="highlight shell"><code><span class="gp">$ </span>iroha-cli --genesis_block <span class="se">\ </span>
--peers_address peers.list
</code></pre>
<p>Executing this command will result in generation of following files:</p>
<ul>
<li><code>[email protected]</code> and <code>[email protected]</code> — keypair for user with admin and asset creator rights</li>
<li><code>[email protected]</code> and <code>[email protected]</code> — keypair for user with user rights</li>
<li><code>node0.priv</code> and <code>node0.pub</code> — keypair for first node, mentioned in the <code>peers.list</code></li>
<li>If mentioned more than one peer address in <code>peers.list</code>: <code>nodeX.priv</code> and <code>nodeX.pub</code> — keypair for #X node, mentioned in the peers.list, (where X is starts from 1) </li>
<li><code>genesis.block</code> — genesis block itself</li>
</ul>
<aside class="notice">
What are those asset creator, admin, user rights? Iroha supports role-based access control, so initial roles for accounts should be created in genesis block. Check <a href="#permission-model">permission model</a> section of the documentation to find out more.
</aside>
<h3 id='manually'>Manually</h3>
<p>Follow JSON structure of the block, as it is reflected in <a href="https://gist.github.com/neewy/4e347bc8493951733998e01af633dbbb">JSON schema for the block</a>.</p>
<h2 id='prepare-configuration-file'>Prepare configuration file</h2>
<p>Configuration file keeps information about storage credentials and irohad parameters:</p>
<table><thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Meaning</th>
</tr>
</thead><tbody>
<tr>
<td>block_store_path</td>
<td>string</td>
<td>Path to store blocks of committed transactions (flat file storage)</td>
</tr>
<tr>
<td>torii_port</td>
<td>integer</td>
<td>Port to access iroha node gRPC (default 50051)</td>
</tr>
<tr>
<td>internal_port</td>
<td>integer</td>
<td>Port for communication between ordering service, YAC consensus and block loader for synchronization (default 10001)</td>
</tr>
<tr>
<td>pg_opt</td>
<td>string</td>
<td>Postgres credentials</td>
</tr>
<tr>
<td>redis_host</td>
<td>string</td>
<td>Redis host IP address</td>
</tr>
<tr>
<td>redis_port</td>
<td>integer</td>
<td>Port to access redis storage</td>
</tr>
<tr>
<td>max_proposal_size</td>
<td>integer</td>
<td>Maximum size of created proposals</td>
</tr>
<tr>
<td>proposal_delay</td>
<td>integer</td>
<td>The period of time (in ms) used to prepare proposal of transactions</td>
</tr>
<tr>
<td>vote_delay</td>
<td>integer</td>
<td>The period of time (in ms) of spreading vote across the network</td>
</tr>
<tr>
<td>load_delay</td>
<td>integer</td>
<td>The period of time (in ms) between synchronizations between peers</td>
</tr>
</tbody></table>
<p>Example:</p>
<script src="https://gist.github.com/neewy/1ebe653de074dac1675f74eb19824b2e.js"></script>
<h2 id='launch-irohad'>Launch irohad</h2>
<p>To launch irohad daemon, following parameters must be passed:</p>
<table><thead>
<tr>
<th>Parameter</th>
<th>Meaning</th>
</tr>
</thead><tbody>
<tr>
<td>config</td>
<td>configuration file, containing postgres, and redis connection, and values to tune the system</td>
</tr>
<tr>
<td>genesis_block</td>
<td>initial block in the ledger</td>
</tr>
<tr>
<td>keypair_name</td>
<td>private and public key file names without file extension. Used by peer to sign the blocks</td>
</tr>
</tbody></table>
<p>Use this command to launch iroha:</p>
<p><code>irohad --config example/config.sample --genesis_block example/genesis.block --keypair_name example/node0</code></p>
<h1 id='block-structure'>Block structure</h1>
<p><img src="images/block.png" title="Block structure" alt="Block" /></p>
<p>In order to understand contents of the block better, this section tells about its parts:</p>
<h3 id='outside-payload'>Outside payload</h3>
<ul>
<li>hash — SHA3-512 hash of block protobuf payload</li>
<li>signatures — signatures of peers, which voted for the block during consensus round</li>
</ul>
<h3 id='inside-payload'>Inside payload</h3>
<ul>
<li>height — a quantity of blocks in the chain up to the block</li>
<li>timestamp — unix time (in millis) of block forming by a peer</li>
<li>body — transactions, which successfully passed validation and consensus step</li>
<li>transactions quantity</li>
<li>previous hash of block</li>
</ul>
<h1 id='transactions'>Transactions</h1>
<blockquote>
<p>Transaction </p>
</blockquote>
<pre class="highlight protobuf tab-protobuf"><code><span class="kd">message</span> <span class="nc">Transaction</span> <span class="p">{</span>
<span class="n">Payload</span> <span class="na">payload</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="k">repeated</span> <span class="n">Signature</span> <span class="na">signature</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="p">}</span>
</code></pre><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="err">/*</span><span class="w"> </span><span class="err">Transaction</span><span class="w"> </span><span class="err">*/</span><span class="w">
</span><span class="s2">"signatures"</span><span class="p">:</span><span class="w"> </span><span class="err">array</span><span class="w"> </span><span class="err">of</span><span class="w"> </span><span class="err">objects</span><span class="p">,</span><span class="w">
</span><span class="s2">"created_ts"</span><span class="p">:</span><span class="w"> </span><span class="err">int(</span><span class="mi">13</span><span class="err">)</span><span class="p">,</span><span class="w">
</span><span class="s2">"creator_account_id"</span><span class="p">:</span><span class="w"> </span><span class="err">string(?)</span><span class="p">,</span><span class="w">
</span><span class="s2">"tx_counter"</span><span class="p">:</span><span class="w"> </span><span class="err">int</span><span class="p">,</span><span class="w">
</span><span class="s2">"commands"</span><span class="p">:</span><span class="w"> </span><span class="err">array</span><span class="w"> </span><span class="err">of</span><span class="w"> </span><span class="err">objects</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
<p>A transaction is a state-changing set of actions in the system. When a transaction passes validation and consensus stages, it is written in a block and saved in immutable block store (blockchain). </p>
<p>Transactions consist of commands, performing an action over an entity in the system. The entity might be an account, asset, etc. — more in <a href="#er-model">entity-relationship model</a> page. </p>
<aside class="notice">
Iroha API follows command-query separation principle, which is described <a href="https://en.wikipedia.org/wiki/Command–query_separation">here</a>.
</aside>
<p>Communication between Iroha peer and a client application is maintained via <a href="https://grpc.io/about/">gRPC framework</a>.
Client applications should follow described protocol and form transactions accordingly to the description below.</p>
<h2 id='transaction-structure'>Transaction structure</h2>
<p>Each transaction consists of two parts:
<ul>
<li> Payload </li>
<li> Signature </li>
</ul></p>
<blockquote>
<p>Payload</p>
</blockquote>
<pre class="highlight protobuf tab-protobuf"><code><span class="kd">message</span> <span class="nc">Payload</span> <span class="p">{</span>
<span class="k">repeated</span> <span class="n">Command</span> <span class="na">commands</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">string</span> <span class="na">creator_account_id</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="kt">uint64</span> <span class="na">tx_counter</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
<span class="kt">uint64</span> <span class="na">created_time</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
<span class="p">}</span>
</code></pre><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="s2">"commands"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"command_type"</span><span class="p">:</span><span class="w"> </span><span class="err">string(?)</span><span class="p">,</span><span class="w">
</span><span class="err">/*</span><span class="w"> </span><span class="err">other</span><span class="w"> </span><span class="err">command-specific</span><span class="w"> </span><span class="err">fields</span><span class="w"> </span><span class="err">*/</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="s2">"creator_account_id"</span><span class="p">:</span><span class="w"> </span><span class="err">string(?)</span><span class="p">,</span><span class="w">
</span><span class="s2">"tx_counter"</span><span class="p">:</span><span class="w"> </span><span class="err">int</span><span class="p">,</span><span class="w">
</span><span class="s2">"created_ts"</span><span class="p">:</span><span class="w"> </span><span class="err">int(</span><span class="mi">13</span><span class="err">)</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
<blockquote>
<p>Signature </p>
</blockquote>
<pre class="highlight protobuf tab-protobuf"><code><span class="kd">message</span> <span class="nc">Signature</span> <span class="p">{</span>
<span class="kt">bytes</span> <span class="na">pubkey</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">bytes</span> <span class="na">signature</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="p">}</span>
</code></pre><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="s2">"signatures"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"pubkey"</span><span class="p">:</span><span class="w"> </span><span class="err">string(</span><span class="mi">64</span><span class="err">)</span><span class="p">,</span><span class="w">
</span><span class="s2">"signature"</span><span class="p">:</span><span class="w"> </span><span class="err">string(</span><span class="mi">128</span><span class="err">)</span><span class="p">,</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">],</span><span class="w"> </span><span class="err">…</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
<p><strong>Payload</strong> stores all transaction fields, except signatures:
<ul>
<li> Time of creation (unix time, in milliseconds) </li>
<li> Account ID of transaction creator (username@domain) </li>
<li> Transaction counter. It counts how many times transaction creator sent transactions in total. Counter is used to prevent replay attack, and is formed on client side </li>
<li> Repeated commands which are described in details in <a href="#commands">commands section</a> </li>
</ul></p>
<p><strong>Signatures</strong> contain one or many signatures (ed25519 public key + signature):</p>
<aside class="notice">
In the current version, there is no way to get current transaction counter by any means. You have to remember it on a client side and increment it. In a future version, this will be changed, and client application may retrieve this information.
</aside>
<h2 id='transaction-statuses'>Transaction statuses</h2>
<p>The current version of Iroha peer follows client <a href="https://en.wikipedia.org/wiki/Pull_technology">pull principle</a> for networking. It means that client should be proactive and request the state of a transaction from a peer. </p>
<p>This section describes the set of states and matches them with transaction lifecycle.</p>
<p><img src="images/tx_status.png" title="Block structure" alt="Block" /></p>
<ul>
<li><code>NOT_RECEIVED</code>: the peer does not have this transaction.</li>
<li><code>STATELESS_VALIDATION_FAILED</code>: the transaction was formed with some fields, not meeting constraints. This status is returned to a client, who formed transaction, right after the transaction was sent. </li>
<li><code>STATELESS_VALIDATION_SUCCESS</code>: the transaction has successfully passed stateless validation. This status is returned to a client, who formed transaction, right after the transaction was sent. </li>
<li><code>STATEFUL_VALIDATION_FAILED</code>: the transaction has commands, which violate validation rules, checking state of the chain (e.g. asset balance, account permissions, etc.) </li>
<li><code>STATEFUL_VALIDATION_SUCCESS</code>: the transaction has successfully passed stateful validation.</li>
<li><code>IN_PROGRESS</code>: the transaction was received, but not yet processed by stateless validator</li>
<li><code>COMMITTED</code>: the transaction is the part of a block, which gained enough votes and is in the block store at the moment. </li>
</ul>
<h1 id='commands'>Commands</h1>
<p>A command changes the state, called World State View, by performing an action over an entity (asset, account) in the system. Any command should be included in a transaction to perform an action.</p>
<h2 id='add-asset-quantity'>Add asset quantity</h2><h3 id='purpose'>Purpose</h3>
<p>The purpose of <em>add asset quantity</em> command is to increase the quantity of an asset on account of transaction creator. Use case scenario is to increase the number of mutable asset in the system, which can act as a claim on a commodity (e.g. money, gold, etc.)</p>
<h3 id='structure'>Structure</h3><pre class="highlight protobuf tab-protobuf"><code><span class="kd">message</span> <span class="nc">AddAssetQuantity</span> <span class="p">{</span>
<span class="kt">string</span> <span class="na">account_id</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">string</span> <span class="na">asset_id</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="n">Amount</span> <span class="na">amount</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">message</span> <span class="nc">uint256</span> <span class="p">{</span>
<span class="kt">uint64</span> <span class="na">first</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">uint64</span> <span class="na">second</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="kt">uint64</span> <span class="na">third</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
<span class="kt">uint64</span> <span class="na">fourth</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">message</span> <span class="nc">Amount</span> <span class="p">{</span>
<span class="n">uint256</span> <span class="na">value</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">uint32</span> <span class="na">precision</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="p">}</span>
</code></pre><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="s2">"commands"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"command_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"AddAssetQuantity"</span><span class="p">,</span><span class="w">
</span><span class="s2">"account_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"test@test"</span><span class="p">,</span><span class="w">
</span><span class="s2">"asset_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"coin#test"</span><span class="p">,</span><span class="w">
</span><span class="s2">"amount"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"value"</span><span class="p">:</span><span class="w"> </span><span class="err">string</span><span class="p">,</span><span class="w">
</span><span class="s2">"precision"</span><span class="p">:</span><span class="w"> </span><span class="err">int</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">],</span><span class="w"> </span><span class="err">…</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
<table><thead>
<tr>
<th>Field</th>
<th>Description</th>
<th>Constraint</th>
</tr>
</thead><tbody>
<tr>
<td>Account ID</td>
<td>account id in which to add asset</td>
<td>account_name@domain</td>
</tr>
<tr>
<td>Asset ID</td>
<td>id of the asset</td>
<td>asset#account</td>
</tr>
<tr>
<td>Amount</td>
<td>positive amount of the asset to add</td>
<td>> 0</td>
</tr>
</tbody></table>
<h3 id='validation'>Validation</h3>
<ol>
<li>Asset and account should exist</li>
<li>Added quantity precision should be equal to asset precision</li>
<li>Creator of transaction should have role which has permissions for issuing assets</li>
<li>Creator of transaction adds account quantity to his/her account only</li>
</ol>
<h2 id='add-peer'>Add peer</h2><h3 id='purpose-2'>Purpose</h3>
<p>The purpose of <em>add peer</em> command is to write into ledger the fact of peer addition into the peer network. After the peer was added, consensus and synchronization components will start using it.</p>
<h3 id='structure-2'>Structure</h3><pre class="highlight protobuf tab-protobuf"><code><span class="kd">message</span> <span class="nc">AddPeer</span> <span class="p">{</span>
<span class="n">Peer</span> <span class="na">peer</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">message</span> <span class="nc">Peer</span> <span class="p">{</span>
<span class="kt">string</span> <span class="na">address</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="kt">bytes</span> <span class="na">peer_key</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
<span class="p">}</span>
</code></pre><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
</span><span class="s2">"commands"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="s2">"command_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"AddPeer"</span><span class="p">,</span><span class="w">
</span><span class="s2">"peer"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"address"</span><span class="p">:</span><span class="w"> </span><span class="s2">"192.168.1.1:50001"</span><span class="p">,</span><span class="w">
</span><span class="s2">"peer_key"</span><span class="p">:</span><span class="w"> </span><span class="err">string(</span><span class="mi">64</span><span class="err">)</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">],</span><span class="w"> </span><span class="err">…</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
<table><thead>
<tr>
<th>Field</th>
<th>Description</th>
<th>Constraint</th>
</tr>
</thead><tbody>
<tr>
<td>Address</td>
<td>resolvable address in network (IPv4, IPv6, domain name, etc.)</td>
<td>should be resolvable</td>
</tr>
<tr>
<td>Peer key</td>
<td>peer public key, which will be used in consensus algorithm to sign-off vote, commit, reject messages</td>
<td>ed25519 public key</td>
</tr>
</tbody></table>
<h3 id='validation-2'>Validation</h3>
<ol>
<li>Creator of the transaction has a role which has CanAddPeer permission.</li>