/
print.html
1807 lines (1648 loc) · 114 KB
/
print.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 lang="en" class="sidebar-visible no-js ayu">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Cardano Community managed Documentation for Pool Operators</title>
<meta name="robots" content="noindex" />
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "ayu";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="Home.html">Getting Started</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="architecture.html">Architecture</a></li><li class="chapter-item expanded "><a href="Common.html">Common</a></li><li class="chapter-item expanded "><a href="build-and-run.html">Build and Run</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Build/node-cli.html">Node and CLI</a></li><li class="chapter-item expanded "><a href="Build/wallet.html">Wallet</a></li><li class="chapter-item expanded "><a href="Build/rest.html">REST</a></li><li class="chapter-item expanded "><a href="Build/dbsync.html">DBSync tool</a></li><li class="chapter-item expanded "><a href="Build/graphql.html">GraphQL</a></li></ol></li><li class="chapter-item expanded "><a href="Setup-Node.html">Set up node as pool operator</a></li><li class="chapter-item expanded "><a href="cli-scripts.html">Useful Scripts</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Scripts/cntools.html">CNTools</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="Scripts/cntools-common.html">Common tasks</a></li><li class="chapter-item "><a href="Scripts/cntools-blocks.html">Block Collector</a></li></ol></li><li class="chapter-item expanded "><a href="Scripts/createAddr.html">Create Keys/Address</a></li><li class="chapter-item expanded "><a href="Scripts/sendADA.html">Make Transactions</a></li><li class="chapter-item expanded "><a href="Scripts/topologyupdater.html">topology Updater</a></li></ol></li><li class="chapter-item expanded "><a href="Staking/Main.html">Guide to the Staking</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Staking/Keys.html">Keys</a></li><li class="chapter-item expanded "><a href="Staking/Addresses.html">Addresses</a></li><li class="chapter-item expanded "><a href="Staking/Certificates.html">Certificates</a></li><li class="chapter-item expanded "><a href="Staking/StakeHolders.html">StakeHolders</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item "><a href="Staking/Owners.html">Owners</a></li><li class="chapter-item "><a href="Staking/Operators.html">Operators</a></li><li class="chapter-item "><a href="Staking/Delegates.html">Delegates</a></li></ol></li></ol></li></ol></li><li class="chapter-item expanded "><a href="Home.html">Appendix</a><a class="toggle"><div>❱</div></a></li><li><ol class="section"><li class="chapter-item expanded "><a href="Appendix/monitoring.html">Monitoring using Prometheus and Grafana</a></li><li class="chapter-item expanded "><a href="Appendix/postgres.html">Sample Postgres Setup</a></li><li class="chapter-item expanded "><a href="Appendix/Setup-Node-Genesis.html">Set up node as BFT member defined in Genesis</a></li></ol></li><li class="chapter-item expanded "><a href="Contributors.html">Contributors</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu (default)</button></li>
</ul>
</div>
<h1 class="menu-title">Cardano Community managed Documentation for Pool Operators</h1>
<div class="right-buttons">
<a href="https://github.com/cardano-community/guild-operators/blob/master/docs/print.md" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h3><a class="header" href="#welcome" id="welcome">Welcome!!</a></h3>
<p>This documentation (rather the repository itself) is created by some of the community members and serves as an easy means to add documentation or scripts that make more sense to users. The target audience for this document are mainly experienced stake pool operators.</p>
<p>The repository is already open to collaboration from many members within community. We would love community contributions and verification of the instructions, rather than having 100 versions of documentation. If there are any discrepancies/suggestions/contributions for this document, please open an Issue and one of the collaborators should be able to add the changes in.</p>
<h4><a class="header" href="#getting-started-with-haskell-node" id="getting-started-with-haskell-node">Getting Started with Haskell Node</a></h4>
<p>Use the sidebar to navigate through the topics. Note that the instructions assume the folder structure as per the Next topic. You're expected to update the folder reference as per your environment.
Also, since you cannot run a Praos node yet, the instructions here-in allow you to join a private haskell testnet network (phtn). We will gradually update to Praos version and update the phtn references.</p>
<p>*Note that the shelley (Praos) codebase is still being cooked in the oven while we're trying to taste it, expect hand burns if not careful
Since we're just trying to keep up with codebase, expect rapid changes (some breaking, requiring redo of network - but that's always the intent of keeping up with bleeding tech). Feedback/Contribution and ownership of tasks is always welcome.</p>
<h3><a class="header" href="#architecture" id="architecture">Architecture</a></h3>
<p>The architecture and description of various components are best described at <a href="https://input-output-hk.github.io/adrestia/docs/architecture/">Adrestia User Guide</a> by IOHK, which you can also view below.</p>
<div>
<iframe src="https://input-output-hk.github.io/adrestia/docs/architecture/" frameborder="0" class="adrestia-arch"></iframe></div>
<h3><a class="header" href="#pre-requisites" id="pre-requisites">Pre-Requisites</a></h3>
<h4><a class="header" href="#dependencies-and-folder-structure-setup" id="dependencies-and-folder-structure-setup">Dependencies and Folder Structure setup</a></h4>
<p>The pre-requisites for Linux systems are automated to be executed as a single script. Note that the guide assumes you do <em>NOT</em> change working directory or mix multiple SSH sessions.
Please ensure to <em>READ</em> the output if you execute something and investigate/raise issue if you receive an error. Do not continue bypassing any errors.
Follow the instructions below to deploy the same:</p>
<pre><code class="language-bash">mkdir "$HOME/tmp";cd "$HOME/tmp"
# Install wget
# CentOS / RedHat - sudo dnf -y install wget
# Ubuntu / Debian - sudo apt -y install wget
wget https://raw.githubusercontent.com/cardano-community/guild-operators/master/files/ptn0/scripts/prereqs.sh
chmod 755 prereqs.sh
# Ensure you can run sudo commands with your user before execution
./prereqs.sh
## Follow the prompts for execution. To make sure environment variables are available for session you're running, make sure to source bashrc
. "${HOME}/.bashrc"
</code></pre>
<h4><a class="header" href="#connect-to-public-haskell-testnet-network-htn" id="connect-to-public-haskell-testnet-network-htn">Connect to public Haskell Testnet Network (HTN)</a></h4>
<p>The prereqs script above will connect you to guild network. If you would like to connect to public HTN instead, kindly execute the below before you proceed after you've executed the above:</p>
<pre><code class="language-bash">wget -O $CNODE_HOME/files/topology.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/shelley_testnet-topology.json
wget -O $CNODE_HOME/files/genesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/shelley_testnet-genesis.json
</code></pre>
<p>If you were already running a node on guild network and would like to <em>replace</em> by moving to HTN, but continue using scripts - follow instructions below:</p>
<ul>
<li>Stop your node (if running).</li>
<li>Ensure you've run commands above which will place updated files at correct location.</li>
<li>Delete your existing DB folder by executing <code>rm -rf $CNODE_HOME/db/*</code> (or alternately - you can rename the folder to switch back later).</li>
<li>Start the node</li>
</ul>
<p>Eventually, you should be able to maintain different versions by tweaking scripts as desired. But for simplicity and reducing manual interventions, we will keep the guide using uniform paths.</p>
<h4><a class="header" href="#folder-structure" id="folder-structure">Folder structure</a></h4>
<p>Running the script above will create the folder structure as per below, for your reference.</p>
<pre><code>/opt/cardano/cnode # Top-Level Folder
├── ...
├── files # Config, genesis and topology files
│ ├── ...
│ ├── genesis.json # Genesis file referenced in ptn0.yaml
│ ├── ptn0.yaml # Config file used by cardano-node
│ └── topology.json # Map of chain for cardano-node to boot from
├── db # DB Store for cardano-node
├── logs # Logs for cardano-node
├── priv # Folder to store your keys (permission: 600)
├── scripts # Scripts to start and interact with cardano-node
├── sockets # Socket files created by cardano-node
└── ...
</code></pre>
<h3><a class="header" href="#build-and-run" id="build-and-run">Build and Run</a></h3>
<p>This document is built using instructions from <a href="https://github.com/input-output-hk">IOHK repositories</a> as a foundation, with additional info/clarification which we can contribute to where appropriate. Note that not everyone needs to build each component. You can refer to <a href="./architecture.html">architecture</a> to understand and qualify which components you want to run. For most Pool Operators, simply building <a href="./Build/node-cli.html">cardano-node</a> might be enough.</p>
<p><strong>The instructions are intentionally limited to cabal</strong> to avoid wait times/availability of nix/docker/stack.yaml files on, what we expect to be, a rapidly developing codebase - this will also help prevent managing multiple versions of instructions (at least for now).</p>
<p>Note that the instructions are predominantly focused around building Cardano components and OS/3rd-party software (eg: postgres) setup instructions are intended to provide build-level information only.</p>
<p>Of course, we can always add links with specific best practices related to those instructions - for those who would like to contribute, please open a PR directly on the <a href="https://github.com/cardano-community/guild-operators/tree/master/docs">github repo</a> to do so.</p>
<h4><a class="header" href="#docker-builds" id="docker-builds">Docker Builds:</a></h4>
<p>If you would like to go down the Docker route, the basic instructions to get you set up with Docker itself are below. Additionally, you can follow <a href="https://input-output-hk.github.io/adrestia/docs/installation/">IOHK Adrestia documentation</a> for the latest release information:</p>
<pre><code class="language-bash"># CentOS
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install https://download.docker.com/linux/centos/7/x86_64/stable/Packages/containerd.io-1.2.6-3.3.el7.x86_64.rpm
sudo yum install -y docker-ce docker-ce-cli
sudo systemctl enable docker
sudo chkconfig docker on
## These steps would be automatically performed by the install above
# sudo groupadd docker
# sudo usermod -aG docker $USER
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/bin/docker-compose;chmod 755 /usr/bin/docker-compose
</code></pre>
<h3><a class="header" href="#cardano-node-and-cardano-cli" id="cardano-node-and-cardano-cli">Cardano Node and Cardano CLI</a></h3>
<p>Ensure the <a href="Build/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<h4><a class="header" href="#build-instructions" id="build-instructions">Build Instructions</a></h4>
<p>Run the commands below to clone the Cardano Node git repository and build the binaries:</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/input-output-hk/cardano-node
cd cardano-node
##### Temporary step for end-users, since master is often broken incompatible with new networks
git fetch --tags -all
git checkout release/1.14.x
#####
### Please ensure you have run the *UPDATED* prereqs.sh (see link at top of this document) before continuing
echo -e "package cardano-crypto-praos\n flags: -external-libsodium-vrf" > cabal.project.local
$CNODE_HOME/scripts/cabal-build-all.sh
</code></pre>
<p>The above would copy the binaries built into ~/.cabal/bin folder.</p>
<h4><a class="header" href="#verify" id="verify">Verify</a></h4>
<p>Execute cardano-cli and cardano-node to verify output as below:</p>
<pre><code class="language-bash">cardano-cli version
# cardano-cli 1.11.0 - linux-x86_64 - ghc-8.6
cardano-node
#Usage: cardano-node (run | run-mock) [--help]
# Start node of the Cardano blockchain.
#
#Available options:
# --help Show this help text
#
#Execute node with a real protocol.
# run Execute node with a real protocol.
#
#Execute node with a mock protocol.
# run-mock Execute node with a mock protocol.
</code></pre>
<h3><a class="header" href="#cardano-wallet" id="cardano-wallet">Cardano Wallet</a></h3>
<p><strong>Note: Cardano Wallet does not support TPraos network yet (it does support BFT networks and ITN Praos) - but as soon as it does, instructions below should still remain valid</strong></p>
<p>Ensure the <a href="Build/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<h4><a class="header" href="#build-instructions-1" id="build-instructions-1">Build Instructions</a></h4>
<p>Follow instructions below for building the cardano-wallet binary:</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/input-output-hk/cardano-wallet
cd cardano-wallet
# Note: The cardano-wallet repo does not work yet with cabal, hence alternate for now is using stack to build
# In case you do not have stack installed, you can install it using command below:
# curl -sSL https://get.haskellstack.org/ | sh
$CNODE_HOME/scripts/stack-build.sh
</code></pre>
<p>The above would copy the binaries into ~/.cabal/bin folder.</p>
<h4><a class="header" href="#start-the-wallet-server" id="start-the-wallet-server">Start the wallet server</a></h4>
<pre><code class="language-bash">cardano-wallet-byron serve --node-socket $CNODE_HOME/sockets/node0.socket --testnet $CNODE_HOME/files/genesis.json --database $CNODE_HOME/priv/wallet
</code></pre>
<h4><a class="header" href="#verify-the-wallet-is-handling-requests" id="verify-the-wallet-is-handling-requests">Verify the wallet is handling requests</a></h4>
<pre><code class="language-bash">cardano-wallet-byron network information
</code></pre>
<p>Expected output should be similar to the following</p>
<pre><code class="language-json">Ok.
{
"network_tip": {
"epoch_number": 4,
"slot_number": 730
},
"node_tip": {
"height": {
"quantity": 2390,
"unit": "block"
},
"epoch_number": 4,
"slot_number": 728
},
"sync_progress": {
"status": "ready"
},
"next_epoch": {
"epoch_start_time": "2020-04-27T09:48:35Z",
"epoch_number": 5
}
}
</code></pre>
<h4><a class="header" href="#create-a-new-wallet" id="create-a-new-wallet">Create a new wallet</a></h4>
<h5><a class="header" href="#first-generate-a-mnemonic-phrase" id="first-generate-a-mnemonic-phrase">First generate a mnemonic phrase</a></h5>
<pre><code class="language-bash">cardano-wallet-byron mnemonic generate
# false brother typical saddle settle phrase foster sauce ask sunset firm gate service render burger
</code></pre>
<h5><a class="header" href="#generate-a-new-byron-wallet-from-your-mnemonic-phrase" id="generate-a-new-byron-wallet-from-your-mnemonic-phrase">Generate a new byron wallet from your mnemonic phrase</a></h5>
<pre><code class="language-bash">cardano-wallet-byron wallet create from-mnemonic --wallet-style icarus "Guild Test Wallet"
</code></pre>
<h5><a class="header" href="#expected-output" id="expected-output">Expected output:</a></h5>
<pre><code class="language-text">Please enter 15 mnemonic words : false brother typical saddle settle phrase foster sauce ask sunset firm gate service render burger
Please enter a passphrase: ******************
Enter the passphrase a second time: ******************
Ok.
{
"passphrase": {
"last_updated_at": "2020-04-27T06:35:19.48354187Z"
},
"state": {
"status": "syncing",
"progress": {
"quantity": 0,
"unit": "percent"
}
},
"discovery": "sequential",
"balance": {
"total": {
"quantity": 0,
"unit": "lovelace"
},
"available": {
"quantity": 0,
"unit": "lovelace"
}
},
"name": "Guild Test Wallet",
"id": "0854da56dd00ae2099a499303681826506527ac7",
"tip": {
"height": {
"quantity": 0,
"unit": "block"
},
"epoch_number": 0,
"slot_number": 0
}
}
</code></pre>
<h3><a class="header" href="#cardano-rest" id="cardano-rest">Cardano Rest</a></h3>
<p>Ensure the <a href="Build/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<h4><a class="header" href="#build-instructions-2" id="build-instructions-2">Build Instructions</a></h4>
<p>Clone the cardano-rest repository from github</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/input-output-hk/cardano-rest.git
cd cardano-rest
$CNODE_HOME/scripts/cabal-build-all.sh
</code></pre>
<p>The above would copy the binaries into ~/.cabal/bin folder.</p>
<h4><a class="header" href="#start-the-rest-server" id="start-the-rest-server">Start the REST server</a></h4>
<p>Execute the below to start the Cardano Explorer API Server:</p>
<pre><code class="language-bash">export PGPASSFILE=$CNODE_HOME/priv/.pgpass
cardano-explorer-api
# Running full server on http://localhost:8100/
</code></pre>
<h4><a class="header" href="#verify-the-rest-server-is-functioning" id="verify-the-rest-server-is-functioning">Verify the REST server is functioning</a></h4>
<p>Verify that you can query the API Server using instruction below:</p>
<pre><code class="language-bash">curl http://localhost:8100/api/blocks/pages
</code></pre>
<p>Expected output should be similar to the following:</p>
<pre><code class="language-json">{"Right":[261,[{"cbeEpoch":4,"cbeSlot":9345,"cbeBlkHeight":2605,"cbeBlkHash":"9026612cfa53b7f8a84ff62c4e897830db9ab6ce24b19e0059f4b4db7a14c0f9","cbeTimeIssued":1587974365,"cbeTxNum":0,"cbeTotalSent":{"getCoin":"0"},"cbeSize":631,"cbeBlockLead":"464835a0904109be93d7996b9b4acc486f6c8f75a595b2c4392f9521","cbeFees":{"getCoin":"0"}},{"cbeEpoch":4,"cbeSlot":9341,"cbeBlkHeight":2604,"cbeBlkHash":"24000e2986bbfbfd610cb105d3697cce7582b8570469c4ff944b91d7dd0dc58f","cbeTimeIssued":1587974325,"cbeTxNum":0,"cbeTotalSent":{"getCoin":"0"},"cbeSize":631,"cbeBlockLead":"1ce88674d08d7813c5281e38e8a43b51550292f0bd8907b17a62eef2","cbeFees":{"getCoin":"0"}},{"cbeEpoch":4,"cbeSlot":9338,"cbeBlkHeight":2603,"cbeBlkHash":"5c2737421b223d1ab67f1046f8841d57d7f8456b77a841702fbb18bccf71a216","cbeTimeIssued":1587974295,"cbeTxNum":0,"cbeTotalSent":{"getCoin":"0"},"cbeSize":631,"cbeBlockLead":"f6a4cfa43cef5ebed8fbd0527153f9896d1f9dd83bd1d55e609d622b","cbeFees":{"getCoin":"0"}},{"cbeEpoch":4,"cbeSlot":9333,"cbeBlkHeight":2602,"cbeBlkHash":"496db1bc19d609687185e394cfcb8fa15e8df652c7dc40a58a347e30b9e4a25f","cbeTimeIssued":1587974245,"cbeTxNum":0,"cbeTotalSent":{"getCoin":"0"},"cbeSize":631,"cbeBlockLead":"a7cad2c48edecff1627bac50aab5fcc6831f6ab91131721269850805","cbeFees":{"getCoin":"0"}},{"cbeEpoch":4,"cbeSlot":9332,"cbeBlkHeight":2601,"cbeBlkHash":"8a837d43685dd350c6f1773b1ede7843d56d093a425ff4ccd799f7ff1b76204d","cbeTimeIssued":1587974235,"cbeTxNum":0,"cbeTotalSent":{"getCoin":"0"},"cbeSize":631,"cbeBlockLead":"a18aa0130f67053ed1cb346813054e160687a8ee7602a549f8ae165b","cbeFees":{"getCoin":"0"}}]]}
</code></pre>
<h3><a class="header" href="#dbsync-tool" id="dbsync-tool">DBSync tool</a></h3>
<p>Cardano DB Sync tool relies on an existing PostgreSQL server. To keep the focus on building dbsync tool, and not how to setup postgres itself, you can refer to <a href="Build/../Appendix/postgres.html">Sample Local PostgreSQL Server Deployment instructions</a> for setting up Postgres instance.</p>
<p>Ensure the <a href="Build/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<h4><a class="header" href="#build-cardano-db-sync" id="build-cardano-db-sync">Build cardano-db-sync</a></h4>
<p>To build instructions for cardano-db-sync tool will be similar to cardano-node:</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/input-output-hk/cardano-db-sync
cd cardano-db-sync
$CNODE_HOME/scripts/cabal-build-all.sh
</code></pre>
<p>Similar to before, <code>cardano-db-sync</code> and <code>cardano-db-sync-extended</code> should now be available in ~/.cabal/bin folder.</p>
<h4><a class="header" href="#prepare-db-for-cardano-db-sync-" id="prepare-db-for-cardano-db-sync-">Prepare DB for cardano-db-sync :</a></h4>
<pre><code class="language-bash">cd ~/git/cardano-db-sync
# scripts/postgresql-setup.sh --dropdb #if exists already, will fail if it doesnt - thats OK
scripts/postgresql-setup.sh --createdb
# Password:
# Password:
# All good!
## Verify you can see "All good!" as above
</code></pre>
<h4><a class="header" href="#start-cardano-db-sync-tool" id="start-cardano-db-sync-tool">Start cardano-db-sync-tool</a></h4>
<pre><code class="language-bash">cd ~/git/cardano-db-sync
PGPASSFILE=$CNODE_HOME/priv/.pgpass cardano-db-sync-extended --config $CNODE_HOME/files/ptn0.yaml --genesis-file $CNODE_HOME/files/genesis.json --socket-path $CNODE_HOME/sockets/node0.socket --schema-dir schema/
</code></pre>
<p>You can use same instructions above to repeat and execute <code>cardano-db-sync</code> as well, but <a href="Build/./graphql.html">cardano-graphql</a> uses <code>cardano-db-sync-extended</code>, so we'll stick to it</p>
<h4><a class="header" href="#validation" id="validation">Validation</a></h4>
<p>To validate, connect to postgres instance and execute commands as per below:</p>
<pre><code class="language-bash">export PGPASSFILE=$CNODE_HOME/priv/.pgpass
psql cexplorer_phtn
</code></pre>
<p>You should be at the psql prompt, you can check the tables and verify they're populated:</p>
<pre><code class="language-sql">\dt
# List of relations
# Schema | Name | Type | Owner
#--------+----------------+-------+-------
# public | block | table | <username>
# public | epoch | table | <username>
# public | meta | table | <username>
# public | schema_version | table | <username>
# public | slot_leader | table | <username>
# public | tx | table | <username>
# public | tx_in | table | <username>
# public | tx_out | table | <username>
#(8 rows)
select * from meta;
# id | protocol_const | slot_duration | start_time | network_name
#----+----------------+---------------+---------------------+--------------
# 1 | 43200 | 20000 | 2020-04-12 13:55:37 | pHTN
#(1 row)
select * from tx;
# id | hash | block | fee | out_sum | size
#----+--------------------------------------------------------------------+-------+-----+------------------+------
# 1 | \x26b63ce785b16fc53ba3ab882ac0e5342a77b33f355ba82982e3e2d5e05500df | 1 | 0 | 1000000000 | 0
# 2 | \xbd8f661658dabbb557d4b5e23264d34fda2a2304daccdac283e337581a88c479 | 1 | 0 | 62499975000000 | 0
# 3 | \x17fbf571b7d091e9cfb6853cd5fb603031831ce7e5e3acbb4b842960e90ba419 | 1 | 0 | 62499975000000 | 0
# 4 | \x3e7e3c1105d3bd76a2b5ae897e1b79b86c7834e68409e533afc318112405ff69 | 1 | 0 | 62499975000000 | 0
# ...
# (36 rows)
</code></pre>
<h3><a class="header" href="#graphql" id="graphql">GraphQL</a></h3>
<p>Ensure the <a href="Build/Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<h4><a class="header" href="#build-hasura-graphql-engine" id="build-hasura-graphql-engine">Build Hasura graphql-engine</a></h4>
<p>Going with the spirit of the documentation here, instruction to build the graphql-engine binary :)</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/hasura/graphql-engine
cd graphql-engine/server
$CNODE_HOME/scripts/cabal-build-all.sh
</code></pre>
<p>This should make <code>graphql-engine</code> available at ~/.cabal/bin.</p>
<h4><a class="header" href="#build-cardano-graphql" id="build-cardano-graphql">Build cardano-graphql</a></h4>
<p>The build will fail if you are running a version of node.js earlier than 10.0.0 (which could happen if you have a conflicting version in your $PATH). You can verify your node version by executing the below:</p>
<pre><code class="language-bash">#check your version of node.js
node -v
#if response is 10.0.0 or higher build can proceed.
</code></pre>
<p>The commands below will help you compile the cardano-graphql node:</p>
<pre><code class="language-bash">cd ~/git
git clone https://github.com/input-output-hk/cardano-graphql
cd cardano-graphql
git checkout v1.1.1
yarn
#yarn install v1.22.4
# [1/4] Resolving packages...
# [2/4] Fetching packages...
# info fsevents@2.1.2: The platform "linux" is incompatible with this module.
# info "fsevents@2.1.2" is an optional dependency and failed compatibility check. Excluding it from installation.
# info fsevents@1.2.12: The platform "linux" is incompatible with this module.
# info "fsevents@1.2.12" is an optional dependency and failed compatibility check. Excluding it from installation.
# [3/4] Linking dependencies...
# warning " > graphql-type-datetime@0.2.4" has incorrect peer dependency "graphql@^0.13.2".
# warning " > @typescript-eslint/eslint-plugin@1.13.0" has incorrect peer dependency "eslint@^5.0.0".
# warning " > @typescript-eslint/parser@1.13.0" has incorrect peer dependency "eslint@^5.0.0".
# [4/4] Building fresh packages...
# Done in 20.70s.
yarn build
# yarn run v1.22.4
# $ yarn codegen:internal && yarn codegen:external && tsc -p . && shx cp src/schema.graphql dist/
# $ graphql-codegen
# ✔ Parse configuration
# ✔ Generate outputs
# $ graphql-codegen --config ./codegen.external.yml
# ✔ Parse configuration
# ✔ Generate outputs
# Done in 38.11s.
cd dist
rsync -arvh ../node_modules ./
</code></pre>
<h4><a class="header" href="#set-up-environment-for-cardano-graphql" id="set-up-environment-for-cardano-graphql">Set up environment for cardano-graphql</a></h4>
<p>cardano-graphql requires cardano-node, cardano-db-sync-extended, postgresql and graphql-engine to be set up and running.
The below will help you map the components:</p>
<pre><code class="language-bash">export PGPASSFILE=$CNODE_HOME/priv/.pgpass
IFS=':' read -r -a PGPASS <<< $(cat $PGPASSFILE)
export HASURA_GRAPHQL_ENABLE_TELEMETRY=false # Optional. To send usage data to Hasura, set to true.
export HASURA_GRAPHQL_DATABASE_URL=postgres://${PGPASS[3]}:${PGPASS[4]}@${PGPASS[0]}:${PGPASS[1]}/${PGPASS[2]}
export HASURA_GRAPHQL_ENABLE_CONSOLE=true
export HASURA_GRAPHQL_ENABLED_LOG_TYPES="startup, http-log, webhook-log, websocket-log, query-log"
export HASURA_GRAPHQL_SERVER_PORT=4080
export HASURA_GRAPHQL_SERVER_HOST=0.0.0.0
export CACHE_ENABLED=true
export HASURA_URI=http://127.0.0.1:4080
cd ~/git/cardano-graphql/dist
graphql-engine serve &
node index.js
</code></pre>
<p>Note that if you do not want your node to be publicly available, you can change <code>--host-addr</code> to <code>127.0.0.1</code></p>
<h3><a class="header" href="#run-a-passive-node" id="run-a-passive-node">Run a passive node</a></h3>
<p>This document helps you to set a basic Passive Node connecting to the network. This would also be a first step if you do not have a genesis (BFT) keys for TPraos network, to allow you to register your pool.
Ensure the <a href="Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> are in place before you proceed.</p>
<p>To start the node in passive mode, execute the steps as below:</p>
<h4><a class="header" href="#start-passive-node" id="start-passive-node">Start Passive Node</a></h4>
<p>To start the node in passive mode, execute the steps as below:</p>
<pre><code class="language-bash">cardano-node run \
--config $CNODE_HOME/files/ptn0.yaml \
--database-path $CNODE_HOME/db \
--host-addr 0.0.0.0 \
--port 5001 \
--socket-path $CNODE_HOME/sockets/node0.socket \
--topology $CNODE_HOME/files/topology.json
</code></pre>
<h4><a class="header" href="#start-as-pool-operator" id="start-as-pool-operator">Start as Pool Operator</a></h4>
<p>To start the node as a block producing pool, execute the steps as below:</p>
<pre><code class="language-bash"># TODO: Add reference to key creations.
# POOLNAME=POOL123
POOLKEYSPATH=$CNODE_HOME/priv/pool/$POOLNAME
cardano-node run \
--config $CNODE_HOME/files/ptn0.yaml \
--database-path $CNODE_HOME/db \
--host-addr 0.0.0.0 \
--port 5001 \
--socket-path $CNODE_HOME/sockets/node0.socket \
--topology $CNODE_HOME/files/topology.json \
--shelley-kes-key $CNODE_HOME/priv/pool/$POOLNAME/hot.skey \
--shelley-vrf-key $CNODE_HOME/priv/pool/$POOLNAME/vrf.skey \
--shelley-operational-certificate $CNODE_HOME/priv/pool/$POOLNAME/op.cert
</code></pre>
<p>Note that if you do not want your node to be publicly available, you can change <code>--host-addr</code> to <code>127.0.0.1</code>
If this is your relay node, you can update topology.json to link to your core node.</p>
<h3><a class="header" href="#collection-of-value-added-scripts" id="collection-of-value-added-scripts">Collection of Value-added scripts</a></h3>
<p>A place to collect scripts that are supposed to help with usage of Cardano-node. The attempt with these scripts is to keep things similar to the popular jormungandr scripts that pool operators in ITN have been accustomed to. Use the navigation menu on the left to drill down to specific script.</p>
<h1><a class="header" href="#cntools" id="cntools">CNTools</a></h1>
<p>CNTools is a shell script that will simplify typical operations for wallets and pool management. The tool is developed against the latest master branch of <a href="https://github.com/input-output-hk/cardano-node">cardano-node</a> and as such may contain breaking changes not compatible with all testnet networks running against a specific tag. As the code matures these breaking changes should be less frequent. Please note that this tool is tested on Linux platforms only at this point.</p>
<p>The script assumes the <a href="Scripts/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> have already been run.</p>
<ul>
<li><a href="Scripts/cntools.html#overview">Overview</a></li>
<li><a href="Scripts/cntools.html#download-and-update">Download and Update</a></li>
<li><a href="Scripts/cntools.html#start">Start CNTools</a></li>
<li><a href="Scripts/cntools.html#navigation">Navigation</a></li>
</ul>
<h4><a class="header" href="#overview" id="overview">Overview</a></h4>
<p>The tool consist of four files.</p>
<ul>
<li><strong><code>cntools.sh</code></strong><br />
the main script to launch cntools.</li>
<li><strong><code>cntools.library</code></strong><br />
internal script with helper functions.</li>
<li><strong><code>cntools.config</code></strong><br />
configuration file to modify certain behaviours, paths and name schema used.</li>
<li><strong><code>cntoolsBlockCollector.sh</code></strong><br />
a script to be run in background on core node parsing log file for block traces.<br />
see <a href="Scripts/cntools-blocks.html">Block Collector</a> section for more details.</li>
</ul>
<p>In addition to the above files, there is also a dependency on the common <code>env</code> file. CNTools connects to your node through the configuration in the <code>env</code> file located in the same directory as the script. Customize <code>env</code> and <code>cntools.config</code> files for your needs. CNTools will start even if your node is offline, but don't expect to get very far.</p>
<h4><a class="header" href="#download-and-update" id="download-and-update">Download and Update</a></h4>
<p>If you have run <code>prereqs.sh</code>, this should already be available in your scripts folder and make this step unnecessary. </p>
<p>To download cntools manually you can execute the commands below:</p>
<pre><code class="language-bash">cd $CNODE_HOME/scripts
wget -O cntools.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/cntools.sh
wget -O cntools.config https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/cntools.config
wget -O cntools.library https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/cntools.library
wget -O cntoolsBlockCollector.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/cntoolsBlockCollector.sh
wget -O env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env
chmod 750 cntools.sh cntoolsBlockCollector.sh
chmod 640 cntools.config cntools.library env
</code></pre>
<h4><a class="header" href="#start" id="start">Start</a></h4>
<p><code>$ ./cntools.sh</code></p>
<p>You should get a screen that looks something like this:</p>
<pre><code> >> CNTOOLS 0.1 << A Guild Operators collaboration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Main Menu
) Wallet - create, show, remove and protect wallets
) Funds - send, withdraw and delegate
) Pool - pool creation and management
) Blocks - show core node leader slots
) Update - update cntools script and library config files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What would you like to do?
[w] Wallet
[f] Funds
[p] Pool
[b] Blocks
[u] Update
[q] Quit
</code></pre>
<h4><a class="header" href="#navigation" id="navigation">Navigation</a></h4>
<p>The scripts menu supports both arrow key navigation and shortcut key selection. The character within the square brackets is the shortcut to press for quick navigation. For other selections like wallet and pool menu that doesn't contain shortcuts, there is a third way to navigate. Key pressed is compared to the first character of the menu option and if there is a match selection jumps to this location. A handy way to quickly navigate a large menu. </p>
<h1><a class="header" href="#common-tasks" id="common-tasks">Common tasks</a></h1>
<p>This chapter describes some common tasks for wallet and pool creation.<br />
CNTools contains more functionality not described here. </p>
<p>Step by Step guide to create a pool with CNTools</p>
<ul>
<li><a href="Scripts/cntools-common.html#stake-wallet">Stake Wallet</a><br />
a stake wallet is needed for delegation/pledge</li>
<li><a href="Scripts/cntools-common.html#create-pool">Create Pool</a><br />
create the necessary pool keys </li>
<li><a href="Scripts/cntools-common.html#create-pool">Register Pool</a><br />
register the pool on-chain</li>
</ul>
<h4><a class="header" href="#stake-wallet" id="stake-wallet">Stake Wallet</a></h4>
<p><strong>1.</strong> <code>Choose Wallet [w]</code> and you will be presented with the following menu:</p>
<pre><code> >> WALLET
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Wallet Management
) New - create a new payment wallet or upgrade existing to a stake wallet
) List - list all available wallets in a compact view
) Show - show detailed view of a specific wallet
) Remove - remove a wallet
) Decrypt - remove write protection and decrypt wallet
) Encrypt - encrypt wallet keys and make all files immutable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Select wallet operation
[n] New
[l] List
[s] Show
[r] Remove
[d] Decrypt
[e] Encrypt
[h] Home
</code></pre>
<p><strong>2.</strong> Choose <code>New [n]</code> to go to submenu for creating a new wallet</p>
<pre><code> >> WALLET >> NEW
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Wallet Type
) Payment - First step for a new wallet
A payment wallet can send and receive funds but not delegate/pledge.
) Stake - Upgrade existing payment wallet to a stake wallet
Make sure there are funds available in payment wallet before upgrade
as this is needed to pay for the stake wallet registration fee.
A stake wallet is needed to be able to delegate and pledge to a pool.
All funds from payment address will be moved to base address.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Choose wallet type
[p] Payment
[s] Stake
[h] Home
</code></pre>
<p><strong>3.</strong> Choose <code>Payment [p]</code> type of wallet<br />
<strong>4.</strong> Give the wallet a name<br />
<strong>5.</strong> CNTools will give you your payment address. For example:</p>
<pre><code> >> WALLET >> NEW >> PAYMENT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Name of new wallet: bob
New Wallet: bob
Payment Address: 60f8a4bed2e379cf8ee5aa28bb7b227362b38694368b767b270720760503132fc5
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</code></pre>
<p><strong>6.</strong> Send some money to this wallet. Either through the faucet or have a friend send you some.<br />
<strong>IMPORTANT</strong> - The wallet must have funds in it before you can proceed.<br />
<strong>7.</strong> From the main menu choose <code>Wallet >> New</code> and then this time choose <code>Stake [s]</code> to upgrade your wallet<br />
<strong>8.</strong> CNTools will give you a list of wallets you can upgrade. Choose the wallet you created in step 4. In this example case, that wallet is called <code>bob</code>. This will send a transaction to the blockchain to upgrade your wallet to a staking wallet. The result should look something like this:</p>
<pre><code>New block was created - 23386
New Stake Wallet : bob
Payment Address : 60f8a4bed2e379cf8ee5aa28bb7b227362b38694368b767b270720760503132fc5
Payment Balance : 0 ADA
Base Address : 00f8a4bed2e379cf8ee5aa28bb7b227362b38694368b767b270720760503132fc545bdb48005781a47a864347843654fd58c1363695453697b5b59fd7ca2af3dc8
Base Balance : 99.428691 ADA
Reward Address : 5821e045bdb48005781a47a864347843654fd58c1363695453697b5b59fd7ca2af3dc8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</code></pre>
<p>The total balance is 0 for the payment address because ALL funds have been moved to the base address.</p>
<h4><a class="header" href="#create-pool" id="create-pool">Create Pool</a></h4>
<p><strong>1.</strong> From the main menu select <code>Pool [p]</code></p>
<pre><code> >> POOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pool Management
) New - create a new pool
) Register - register created pool on chain using a stake wallet (pledge wallet)
) Modify - change pool parameters and register updated pool values on chain
) Retire - de-register stake pool from chain in specified epoch
) List - a compact list view of available local pools
) Show - detailed view of specified pool
) Rotate - rotate pool KES keys
) Decrypt - remove write protection and decrypt pool
) Encrypt - encrypt pool cold keys and make all files immutable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Select wallet operation
[n] New
[r] Register
[m] Modify
[x] Retire
[l] List
[s] Show
[o] Rotate
[d] Decrypt
[e] Encrypt
[h] Home
</code></pre>
<p><strong>2.</strong> Select <code>New [n]</code> to create a new pool<br />
<strong>3.</strong> Give the pool a name. In our case, we call it LOVE. The result should look something like this:</p>
<pre><code> >> POOL >> NEW
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pool Name: LOVE
Pool: LOVE
PoolPubKey: 687c3f588d996ee5fc751cc581826f63c407b1c46514ef9fe3001fa96d3a75bc
Start cardano node with the following run arguments:
--shelley-kes-key /opt/cardano/cnode/priv/pool/LOVE/hot.skey
--shelley-vrf-key /opt/cardano/cnode/priv/pool/LOVE/vrf.skey
--shelley-operational-certificate /opt/cardano/cnode/priv/pool/LOVE/op.cert
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</code></pre>
<ol start="4">
<li>Start or restart your cardano-node with the parameters as shown. This will ensure your node has all the information necessary to create blocks.<br />
<strong>IMPORTANT</strong> - If you do not start your node with these parameters you won't be able to make blocks.</li>
</ol>
<h4><a class="header" href="#register-pool" id="register-pool">Register Pool</a></h4>
<p><strong>1.</strong> From the main menu select <code>Pool [p]</code><br />
<strong>2.</strong> Select <code>Register [r]</code><br />
<strong>3.</strong> Select the pool you just created in step 11 above<br />
<strong>4.</strong> CNTools will give you prompts to set metadata, pledge, margin and cost. Enter values that are useful to you.<br />
<strong>IMPORTANT</strong> - Make sure you set your pledge low enough to insure your funds in your wallet will cover pledge plus pool registration fees.</p>
<p>It will look something like this:</p>
<pre><code> >> POOL >> REGISTER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Select Pool:
LOVE
[c] Cancel
Pledge (in ADA, default: 50000): 899
Margin (in %, default: 7.5): 10
Cost (in ADA, default: 256): 500
Enter Pool's Name (default: LOVE):
Enter Pool's Ticker , should be between 3-5 characters (default: LOVE):
Enter Pool's Description (default: No Description): My custom description
Enter Pool's Homepage (default: https://foo.com): https://love.fake.com
Enter Pool's JSON URL to host metadata file - URL length should be less than 64 chars (default: https://foo.bat/poolmeta.json): https://love.fake.com/poolmeta.json
Please make sure you host your metadata JSON file (with contents as below) at https://love.fake.com/poolmeta.json :
{
"name": "LOVE",
"ticker": "LOVE",
"description": "My custom description",
"homepage": "https://love.fake.com"
}
</code></pre>
<p><strong>5.</strong> Select the wallet you want to register the pool with.<br />
<strong>6.</strong> DONE!</p>
<p>The final output on successful registration should look something like this:</p>
<pre><code>New block was created - 23414
Pool LOVE successfully registered using wallet bob for pledge
Pledge : 899 ADA
Margin : 10%
Cost : 500 ADA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</code></pre>
<h1><a class="header" href="#block-collector" id="block-collector">Block Collector</a></h1>
<p>For the core node(block producer) the <code>cntoolsBlockCollector.sh</code> script can be run to monitor the json log file created by cardano-node for traces related to leader slots and block creation. Data collected is stored in a json file, one for each epoch. To view the collected data the main CNTools script is used.</p>
<p>This collector does not in any way replace a proper database like db-sync but can be a good lightweight way of keeping track of slots assigned and if blocks were successfully created. It currently does not verify that the block created makes it onto the chain. If possible this will be added at a later stage.</p>
<ul>
<li><a href="Scripts/cntools-blocks.html#prerequisites">Prerequisites</a></li>
<li><a href="Scripts/cntools-blocks.html#installation-and-configuration">Installation and Configuration</a></li>
<li><a href="Scripts/cntools-blocks.html#view-collected-blocks">View Collected Blocks</a></li>
</ul>
<h3><a class="header" href="#prerequisites" id="prerequisites">Prerequisites</a></h3>
<p>It's assumed the <a href="Scripts/../Common.html#dependencies-and-folder-structure-setup">Pre-Requisites</a> have already been run.</p>
<p>As the block collector relies on the cardano-node log file for block traces the node configuration file has to be set up in a certain way for it to work. The file used comes from <code>CONFIG</code> parameter in <code>env</code> file.</p>
<ul>
<li>setupScribes configured with <code>scKind: FileSK</code> and <code>scFormat: ScJson</code> as well as a file extension of <code>.json</code></li>
<li>Blocks traces enabled. The script is looking for the following block traces in the log file, more block traces might be added in the future.<br />
<code>TraceNodeIsLeader TraceAdoptedBlock TraceForgedInvalidBlock</code></li>
</ul>
<h3><a class="header" href="#installation-and-configuration" id="installation-and-configuration">Installation and Configuration</a></h3>
<p>The script is best run as a background process. This can be accomplished in many ways but the preferred method is to run it as a systemd service. A terminal multiplexer like tmux or screen could also be used but not covered here.</p>
<p>sudo/root access needed to configure systemd.</p>
<p>In this example normal output from the <code>cntoolsBlockCollector.sh</code> script is ignored. Error output is logged using syslog and end up in the systems standard syslog file, normally <code>/var/log/syslog</code>. Other logging configurations are not covered here. </p>
<p><strong>1. Create systemd service file</strong><br />
Replace <code>$USER</code> with the correct user for your system. Copy & paste all code below to create the service file.</p>
<pre><code class="language-bash">sudo bash -c 'cat <<EOF > /etc/systemd/system/cntools-blockcollector.service
[Unit]
Description=CNTools - Block Collector
After=network.target
[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=$USER
WorkingDirectory=/opt/cardano/cnode/scripts
ExecStart=/opt/cardano/cnode/scripts/cntoolsBlockCollector.sh
SuccessExitStatus=143
StandardOutput=null
StandardError=syslog
SyslogIdentifier=cntools-blockcollector
[Install]
WantedBy=multi-user.target
EOF'
</code></pre>
<p><strong>2. Reload systemd</strong></p>
<pre><code>sudo systemctl daemon-reload
</code></pre>
<p><strong>3. Start block collector</strong><br />
Run below commands to enable automatic start of service on startup and start it.</p>
<pre><code>sudo systemctl enable cntools-blockcollector.service
sudo systemctl start cntools-blockcollector.service
</code></pre>
<h3><a class="header" href="#view-collected-blocks" id="view-collected-blocks">View Collected Blocks</a></h3>
<p>Start CNTools and choose <code>Blocks [b]</code> to open the block viewer.<br />
Enter the epoch you want to see or press <code>enter</code> to see the current epoch.</p>
<p>If the node was elected to create blocks in the selected epoch it could look something like this:</p>
<pre><code> >> BLOCKS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Current epoch: 92
Enter epoch to list (enter for current):
7 blocks created in epoch 92
Slot At Size Hash
82809 2020-06-26 12:15:18 UTC 3 bd86e0358fbc929daeb0a877052149bcb57e2b2d7da573ea025c78cc2ed6896b
82811 2020-06-26 12:15:22 UTC 3 fcd8e33f56b7a7d0c3a426570b8a1fba045266fd1a40ff63951c0f00fc7fbeb4
82829 2020-06-26 12:15:58 UTC 3 d0804a37eee8dfaaeb39a06e3373adef51459b1429b838288291014a69c37c04
82851 2020-06-26 12:16:42 UTC 3 d18c27edfdc2870d7922039d48764502f9b27b157b92b0dbe7171c35b1c94f5f
82859 2020-06-26 12:16:58 UTC 3 e9a1efdd3aef257ea07c55e102ad976c2259ee3cacc9a1d45f7c9dc55db189e9
82881 2020-06-26 12:17:42 UTC 3 d5bf67db9bcb6a26968b69dc9e65c540402bed985b46e98a925aa679adb51c88
82913 2020-06-26 12:18:46 UTC 3 1bf29f81d8087ded9f268a2b89aef2c7c6eeda077e5b84941aa4732bea1c3e0c
</code></pre>
<h3><a class="header" href="#create-keysaddress" id="create-keysaddress">Create Keys/Address</a></h3>
<p>This script assists you to create a Private key file and generates a corresponding address script for it</p>
<pre><code class="language-bash">cd $CNODE_HOME/scripts
./createAddr.sh key1
# Sample output to enter passphrase (can be left empty, you will need this passphrase to access the key if filled):
# Enter password to encrypt 'key1':
# Repeat to validate:
</code></pre>
<h3><a class="header" href="#check-balance" id="check-balance">Check Balance</a></h3>
<p>This script will check balance of address specified as command line argument</p>
<pre><code class="language-bash">cd $CNODE_HOME/scripts
./balance.sh 61WKMJemoBa....ssL7fzhq
TxHash TxIx Lovelace
----------------------------------------------------------------------------------------
WKMJemoBa4a9dc77d6d36cfbd90ae0e693e5e99ad59c09a8455169assL7fzhq 0 1000000000
Total balance in 1 UTxO is 1000000000 Lovelace or 1000 ADA
</code></pre>
<h3><a class="header" href="#make-transactions" id="make-transactions">Make Transactions</a></h3>
<p>This script will create and submit a transaction to send ADA from source address to destination address, it assumes the <a href="Scripts/Common.html#dependencies-and-folder-structure-setup">pre-requisites</a> are already in place.<br />
The script can also be used to defrag address by setting destination and source address to the same and amount to the string 'all'</p>
<pre><code class="language-bash">cd $CNODE_HOME/scripts
./sendADA.sh
Usage: sendADA.sh <Destination Address> <Amount> <Source Address> <Source Sign Key> [--include-fee]
Destination Address Address or path to Address file.
Amount Amount in ADA, number(fraction of ADA valid) or the string 'all'.
Source Address Address or path to Address file.
Source Sign Key Path to Signature (skey) file. For staking address payment skey is to be used.
--include-fee Optional argument to specify that amount to send should be reduced by fee instead of payed by sender.
</code></pre>
<h1><a class="header" href="#quickstart-for-using-topology-updater" id="quickstart-for-using-topology-updater">Quickstart for using TOPOLOGY-UPDATER</a></h1>
<p>Since the test network has to get along without the P2P network module for the time being, it needs static topology files. This "TopologyUpdater" service, which is far from being perfect due to its centralization factor, is intended to be a temporary solution to allow everyone to activate their relay nodes without having to postpone and wait for manual topology completion requests.</p>
<p>The topologyupdater shell script must be executed on the relay node as a cronjob exactly every 60 minutes. After 4 consecutive requests (3 hours) the node is considered a new relay node in listed in the topology file. If the node is turned off, it's automatically delisted after 3 hours.</p>
<h4><a class="header" href="#download-and-configure-topologyupdatersh" id="download-and-configure-topologyupdatersh">Download and Configure topologyUpdater.sh</a></h4>
<p>If you have run <code>prereqs.sh</code>, this should already be available in your scripts folder and make this step unnecessary. </p>
<p>Before the updater can make a valid request to the central topology service, he must query the current tip/blockNo from the well synced local node. It connects to your node through the configuration in the script (note: not the usual env file, as cronjobs don't run in the same environment). Customize this file for your needs.</p>
<p>To download topologyupdater.sh manually you can execute the commands below:</p>
<pre><code class="language-bash">cd $CNODE_HOME/scripts
curl -s -o topologyUpdater.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/topologyUpdater.sh
chmod 750 topologyUpdater.sh
</code></pre>
<h4><a class="header" href="#start-1" id="start-1">Start</a></h4>
<p>Then add the script to be executed once per hour at a minute of your choice (eg xx:25 o'clock in the example below)</p>
<pre><code>25 * * * * /opt/cardano/cnode/scripts/topologyUpdater.sh
</code></pre>
<p>you can check the last result in <code>logs/topologyUpdater_lastresult.json</code></p>
<h1><a class="header" href="#step-by-step-to-have-your-relay-node-listed-in-the-topology" id="step-by-step-to-have-your-relay-node-listed-in-the-topology">Step by Step to have your relay node listed in the topology</a></h1>
<p><em>Note:</em> You don't need to execute this for your pool nodes. </p>
<p>You need to execute it once for every relay node you run. (IP:PORT combination)</p>
<p>If one of the parameters is outside the allowed ranges, invalid or missing the returned json will tell you what needs to be fixed.</p>
<p>Don't try to execute the script more often than once per hour. It's completely useless and may lead to a temporary blacklisting.</p>
<h1><a class="header" href="#where-is-the-topology-file" id="where-is-the-topology-file">Where is the topology file?</a></h1>
<p>Each subscribed node (4 consecutive requests) is allowed to fetch a subset of other nodes. </p>
<p>Engineers of cardano-node network stack suggested to use around 20 peers. More peers create unnecessary and unwanted system load and delays.</p>
<p>The URL to fetch the peer list is <a href="https://api.clio.one/htopology/v1/fetch/">https://api.clio.one/htopology/v1/fetch/</a></p>
<p>In it's default setting it returns a list of 15 remote peers. The <code>max</code> parameter allows to define a number between 1 and 20 remote peers.</p>
<p>you can request the file from you node by using the curl command</p>
<pre><code>curl -s -o path/to/topology.json "https://api.clio.one/htopology/v1/fetch/?max=14"
</code></pre>
<p>Don't forget to restart your node to load the new topology. </p>
<h2><a class="header" href="#and-my-custom-peers-internal-pools-" id="and-my-custom-peers-internal-pools-">and my custom peers (internal pools) ?</a></h2>
<p>There is also a <code>customPeers</code> parameter, to include also some custom peers you want included in the topology json file. Every custom peer is defined in the form [address]:[port] and optional :[valancy]. Multiple custom peers are separated by | </p>
<p>A complete example looks like</p>
<pre><code>curl -s -o topology.json "https://api.clio.one/htopology/v1/fetch/?max=12&customPeers=10.0.0.1:3001|10.0.0.2:3002|relays.mydomain.com:3003:3"
</code></pre>
<p>Might think about including the curl command in your startup script before cardano-node.</p>
<h2><a class="header" href="#how-are-the-peers-for-my-topology-file-selected" id="how-are-the-peers-for-my-topology-file-selected">How are the peers for my topology file selected?</a></h2>
<p>We calculate the distance on the earth's surface from your nodes IP to all subscribed peers. We then order by distance (closest first) and start selecting one peer. Then skip some, pick the next, skip, pick, skip, pick ... until we reach the end of the list (furthest away). The number of skipped records is calculated in a way to have the desired number of peers at the end.</p>
<p>Every requesting node has his personal distances to all other nodes. </p>
<p>We assume this should result in a well distributed and interconnected peering network.</p>
<h1><a class="header" href="#shelley-staking" id="shelley-staking">Shelley Staking</a></h1>
<p>This guide's chapter targets the pool operators for getting their head around of Shelley staking. The network references used for this guide are for Friends anf Family Network, and the user is expected to update testnet-magic as desired.
To fully understand the staking mechanism we need to define and interpret the following key concepts:</p>
<ul>
<li>What are the <a href="Staking/./Keys.html">keys</a></li>
<li>What are the <a href="Staking/./Addresses.html">addresses</a></li>
<li>What are the <a href="Staking/./Certificates.html">certificates</a> and </li>
<li>Who are the <a href="Staking/./StakeHolders.html">stake holders</a> that are participanting in staking.</li>
</ul>
<h2><a class="header" href="#keys-addresses-and-certifications" id="keys-addresses-and-certifications">Keys, Addresses and Certifications</a></h2>
<p>The following picture helps to understand the relations between keys, addresses and certificates.</p>
<p><img src="https://raw.githubusercontent.com/ilap/ShelleyStuffs/master/images/ShelleyKeyAndAddresses.png" alt="ShelleyKeyAndAddresses" /></p>
<h2><a class="header" href="#key-types-and-their-functions" id="key-types-and-their-functions">Key Types and their functions</a></h2>
<p>Keys are just simply asymmetric cryptography key pairs (private/public, signing/verifying) that are used for signing and validating payments and staking related certificates and identifying, defining addresses on the Cardano blockchain.</p>
<p>As it can be seen in the picture there are two main type of keys in Shelley:</p>
<ul>
<li><strong>Node keys</strong> and</li>
<li><strong>Address keys</strong>.</li>
</ul>
<p>The node keys are relevant to the security of the blockchain while the address keys are relevant to the functions of the addresses derived from the keys for identifying funds on the blockchain.
See details below and above in the picture.</p>
<ol>
<li>Node Keys
<ul>
<li>Operator/operational key: operator's offline key pair with cert counter for new certificates. </li>
<li>Hot KES key: operator's hot KES key pair.</li>
<li>Block signing key: operational VRF key pair, it participates in the "lottery" i.e. right to create and sign the block for the specific slot.</li>
</ul>
</li>
<li>Address (Payment, Staking etc.) keys
<ul>
<li>Payment key: single address key pair (usually for generating UtxO addresses)</li>
<li>Staking key: stake/reward address key pair (usually generating account/reward addresses)</li>
</ul>
</li>
</ol>
<h2><a class="header" href="#addresses-and-their-functions" id="addresses-and-their-functions">Addresses and their functions</a></h2>
<p>The addresses, as of now, are just a simple <code>blake2b-256</code> hash of the relevant veryifying/public keys contatenated with some metadata that are or can be stored on the <code>Cardano</code> blockchain. </p>
<blockquote>
<p>Addresses in this context are only relevant to the ledger specification and not to any wallet addresses.
So, the wallets <code>m/44'/1852'/0'/{0,1,2}</code> <code>bech32</code> addresses (e.g. <code>ca1hg9...</code>) are irrelevant here.</p>
</blockquote>
<p>Currently there are three main type of addresses and a reserved <em>address space</em> for future use:</p>
<ol>
<li><strong>Payment addresses</strong>:
<ul>
<li>base addresses (can participate in staking, a.k.a goup addresses in ITN jorm terminology)</li>
<li>pointer addresses (need to check whether it can or cannot participate in staking)</li>
<li>enterprise addresses (cannot participate in staking a.k.a UtxO address)</li>
</ul>
</li>
<li><strong>Reward addresses</strong>: Reward/account addresses (can participate in staking)</li>
<li><strong>Byron addresses</strong>: The legacy addresses, for backward compatibility (cannot participate in staking)</li>
<li><strong>Future addresses</strong>: possible 5 main /w 16 subtypes or 80 additional address types)</li>
</ol>
<p>Therefore addresses, in Cardano Shelley (only in Haskell code), are some serialised data specified in the ledger specification that are stored in the blockhain's blocks (e.g. an UtxO address).</p>
<p>The serialised data (address) contains two parts the <strong>metadata</strong> and <strong>payload</strong> (i.e. <code>address = metadata + payload</code>): </p>
<ul>
<li>metadata: is for interpreting the</li>
<li>payload: the raw or encoded bytes. For example the verifying/public keys or their hashes or even scripts (e.g. plutus smart contract) hashes.</li>
</ul>
<p><em>Therefore, in layman definition (by removing some complexity for easy understanding):
<strong>Addresses are serialised public/verifying keys</strong></em> </p>
<p>See,the <a href="https://github.com/input-output-hk/cardano-ledger-specs/blob/master/shelley/chain-and-ledger/executable-spec/cddl-files/shelley.cddl#L66">detailed address specification here</a>.</p>
<blockquote>
<p>Pls, keep in mind, that it does not mean that the specification is currently is used, implemented and/or finalised.</p>
</blockquote>
<h2><a class="header" href="#certificates" id="certificates">Certificates</a></h2>
<p>Shelley's PoS protocol requires different certificates posted to the blockhain; which will be pulbicyl available for all participants. Those are valids until explicitly overwritten or revoked.</p>
<p>There are four main type of certificates are in Shelley:</p>
<ol>
<li>Operational key certificates (<strong>off chain</strong>),</li>
<li>Stake Key registration certificates (<strong>on chain</strong>),</li>
<li>Delegation certificates (<strong>on chain</strong>) and</li>
<li>Stake pool certificates (<strong>on chain</strong>).</li>
</ol>
<h3><a class="header" href="#operational-key-certificates" id="operational-key-certificates">Operational key certificates</a></h3>
<p>The <code>operational key certificate</code>'s is created from a <code>staking key</code>
used by stake pool operators for protecting their pool(s) and keys, signing bocke, participating in the lottery and not for delegating staking rights.