Skip to content

Commit 7fc6ee1

Browse files
sjmackenziesjmackenzie
committed
Problem: no docs for jormungandr
Solution: initial commit it
0 parents  commit 7fc6ee1

25 files changed

+1427
-0
lines changed

‎index.adoc

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
= Fractalide Documentation
2+
:description: Fractalide Documentation
3+
:icons: font
4+
:sectnums:
5+
:toc: left
6+
:toclevels: 4
7+
:sectanchors:
8+
:nofooter:
9+
:experimental:
10+
:source-highlighter: highlightjs
11+
:highlightjsdir: highlight
12+
13+
[preface]
14+
15+
include::jormungandr/index.adoc[]

‎jormungandr/01-quickstart/01-cli.adoc

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
= Installation
2+
3+
The software bundles 2 command line programs:
4+
5+
* `jormungandr`, the node;
6+
* `jcli`, the Jormungandr Command Line Interface, a low level program that interact with the node.
7+
8+
== Install from a release
9+
10+
This is the recommended method. Releases are available at https://github.com/fractalide/jormungandr-luceo/releases[the release section].
11+
12+
== Install from source
13+
14+
Jormungandr's source code is available at https://github.com/fractalide/jormungandr-luceo#how-to-install-from-sources[github].
15+
Follow the instructions to build the software from source.
16+
17+
= Help and auto completion
18+
19+
All commands come with usage help, find out by adding `--help` or `-h` to the end of the command.
20+
21+
`jcli` has a feature which allows you to generate auto completion:
22+
23+
[source, bash]
24+
----
25+
jcli auto-completion bash ${HOME}/.bash_completion.d
26+
----
27+
28+
Supported shells are: `bash`, `fish`, `zsh`, `powershell` and `elvish`.
29+
30+
Ensure `${HOME}/.bash_completion.d` directory exists on your hard disk.
31+
In order to use auto completion you still need to:
32+
33+
[source, bash]
34+
----
35+
source ${HOME}/.bash_completion.d/jcli.bash
36+
----
37+
38+
You can also put it in your `${HOME}/.bashrc` so that it's loaded whenever you enter your shell.

‎jormungandr/01-quickstart/02-passive-node.adoc

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
= Passive Node
2+
3+
The passive Node is the most common type of node on the network, it doesn't create blocks and is mostly used for wallets, explorers or relays.
4+
5+
In order to start the node, you first need to gather the blockchain information you need to connect to.
6+
7+
1. the *hash* of the *genesis block* of the blockchain, this will be the source
8+
of truth of the blockchain. It is 64 hexadecimal characters.
9+
2. the *trusted peers* identifiers and access points.
10+
11+
The above information can be found at link:/luceo[luceo connection information].
12+
13+
This information is essential for the correct starting of your node.
14+
15+
The *genesis block* is the first block of a blockchain. It contains
16+
static initialization parameters such as the initial funds. Your node
17+
will utilise the *hash* to retrieve the *genesis block* from the other peers. Once obtained
18+
the *hash* is used to verify the integrity of the downloaded *genesis block*.
19+
20+
*Trusted peers* are public nodes in the network your node will
21+
trust in order to initialise participate in the Peer To Peer network. More details to come.
22+
23+
== The node configuration
24+
25+
Your node configuration file may look like the following:
26+
27+
**Note**
28+
29+
This config shouldn't work as it is, the ip address and port for the trusted peer should be those of an already running node.
30+
Also, the public_address ('u.x.v.t') should be a valid address (you can use an internal one, eg: 127.0.0.1).
31+
Furthermore, you need to have permission to write in the path specified by the storage config.
32+
33+
[source, yaml]
34+
----
35+
storage: "/mnt/luceo/storage"
36+
37+
rest:
38+
listen: "127.0.0.1:8443"
39+
prefix: "api"
40+
41+
peer_2_peer:
42+
trusted_peers:
43+
- id: 1
44+
address: "/ip4/104.24.28.11/tcp/8299"
45+
public_access: "/ip4/u.v.x.y/tcp/8299"
46+
topics_of_interests:
47+
messages: low
48+
blocks: normal
49+
----
50+
51+
Field definitions:
52+
53+
* *storage*: (optional) path to the storage. If omitted, the blockchain is stored in memory only.
54+
* *logger*: (optional) logger configuration,
55+
** *verbosity*: 0 - warning, 1 - info, 2 -debug, 3 and above - trace
56+
** *format*: log output format - plain or json.
57+
** *output*: log output - stderr, syslog (unix only) or journald (linux with systemd only, must be enabled during compilation)
58+
* *rest*: (optional) configuration of the rest endpoint.
59+
** *listen*: listen address
60+
** *pkcs12*: certificate file (optional)
61+
** *prefix*: (optional) api prefix
62+
* *peer_2_peer*: the P2P network settings
63+
** *trusted_peers*: (optional) the list of nodes to connect to in order to bootstrap the p2p topology (and bootstrap our local blockchain);
64+
** *public_id*: (optional) the public identifier send to the other nodes in the p2p network. If not set it will be randomly generated.
65+
** *public_access*: the address to listen from and accept connection from. This is the public address that will be distributed to other peers of the network that may find interest into participating to the blockchain dissemination with the node;
66+
** *topics_of_interests*: the different topics we are interested to hear about:
67+
*** *messages*: notify other peers this node is interested about transactions typical setting for a non mining node: `"low"`. For a stakepool: `"high"`;
68+
*** *blocks*: notify other peers this node is interested about new blocks. typical settings for a non mining node: `"normal"`. For a stakepool: `"high"`;
69+
70+
== Starting the node
71+
72+
[source, bash]
73+
----
74+
jormungandr --config config.yaml --genesis-block-hash 'abcdef987654321....'
75+
----
76+
77+
The 'abcdef987654321....' part refers to the hash of the genesis, that should be given to you from one of the peers in the network you are connecting to.
78+
79+
In case you have the genesis file (for example, because you are creating the network) you can get this hash with jcli.
80+
81+
[source, bash]
82+
----
83+
cat block-0 | jcli genesis hash
84+
----
85+
86+
or, in case you only have the yaml file
87+
88+
[source, bash]
89+
----
90+
cat genesis.yaml | jcli genesis encode | jcli genesis hash
91+
----

‎jormungandr/01-quickstart/03-rest-api.adoc

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
= REST
2+
3+
This section is unstable and will change.
4+
5+
It is possible to query the node via its REST Interface.
6+
7+
In the node configuration, one should do something like:
8+
9+
[source, yaml]
10+
----
11+
# ...
12+
13+
rest:
14+
listen: "127.0.0.1:8443"
15+
prefix: "api"
16+
17+
#...
18+
----
19+
20+
21+
This is the REST endpoint to talk to the node, to query blocks or send transaction.
22+
23+
It is possible to query the node stats with the following end point:
24+
25+
[source, bash]
26+
----
27+
curl http://127.0.0.1:8443/api/v0/node/stats
28+
----
29+
30+
Try it on the luceo endpoint
31+
32+
[source, bash]
33+
----
34+
curl https://luceo.fractalide.org/v0/node/stats
35+
----
36+
37+
38+
The result may be:
39+
40+
[source, json]
41+
----
42+
{"blockRecvCnt":120,"txRecvCnt":92,"uptime":245}
43+
----

‎jormungandr/01-quickstart/index.adoc

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
= Quickstart
2+
3+
This quickstart section will allow you to
4+
5+
* connect through to the luceo blockchain
6+
* setup your own luceo stakepool
7+
* educate you on the finer details of `jcli` subcommands.
8+
9+
include::01-cli.adoc[leveloffset=+1]
10+
11+
include::02-passive-node.adoc[leveloffset=+1]
12+
13+
include::03-rest-api.adoc[leveloffset=+1]

‎jormungandr/02-concepts/01-blockchain.adoc

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
= Blockchain concepts
2+
3+
== Time
4+
5+
Slots represent the basic unit of time in a blockchain, at each slot
6+
a block might be present.
7+
8+
Consecutive slots are grouped into epochs, with an updateable size defined
9+
by the protocol.
10+
11+
== Fragments
12+
13+
A Fragment is data representing about the blockchain, it includes updates to the protocol, transactions and certificate information.
14+
15+
== Blocks
16+
17+
Blocks are the blockchain's spine, they are safely and securely linked
18+
together into a chain, whilst grouping valid fragments together.
19+
20+
Blocks are composed of 2 parts:
21+
22+
* The header
23+
* The content
24+
25+
The header securely links the content together with the blocks.
26+
The content is effectively a sequence of fragments.
27+
28+
== Blockchain
29+
30+
A blockchain is defined by a set of rules that create blocks periodically. Rules can be changed on the fly in system updates, while others are hardcoded in the genesis block (first block of the blockchain).
31+
32+
```
33+
+-------+ +-------+
34+
|Genesis+<-----+Block 1+<--- ....
35+
|Header | |Header |
36+
+---+---+ +---+---+
37+
| |
38+
+---v---+ +---v---+
39+
|Genesis| |Block 1|
40+
|Content| |Content|
41+
+-------+ +-------+
42+
```
43+
44+
== Consensus
45+
46+
Jormungandr currently supports the following consensus protocols:
47+
48+
* Ouroboros BFT (OBFT)
49+
* Ouroboros Genesis-Praos
50+
51+
Ouroboros BFT is a simple Byzantine Fault Tolerant (BFT) protocol with known
52+
block makers that create and broadcast blocks onto the network in a round robin type fashion.
53+
54+
Ouroboros Genesis Praos is a proof of stake (PoS) protocol where block
55+
makers are selected via a sortition or lottery process. Each stake pool has a winning chance of being selected to create the next block proportional to their stake held. The sortitions are private or local to the stake pool, so other nodes don't have no prior knowledge of who can create blocks.
56+
57+
== Leadership
58+
59+
Leadership defines a set of nodes that check blocks are correctly created. New leadership is selected at the start of every epoch.
60+
61+
== Leader
62+
63+
A leader is the randomly selected actor with the ability to create a block;
64+
In OBFT mode, the leader is just the owner of a cryptographic key, whereas in Genesis-Praos mode, the leader is a stake pool.

‎jormungandr/02-concepts/02-node.adoc

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
= Node organisation
2+
3+
== Secure Enclave
4+
5+
The secure enclave is designed to securely contain secret cryptographic material, it
6+
offers safe interfaces for the rest of the node to interact with.
7+
8+
== Network
9+
10+
The node's network consists of 3 components:
11+
12+
* Intercommunication API (GRPC)
13+
* Public client API (REST)
14+
* Control client API (REST)
15+
16+
=== Intercommunication API (GRPC)
17+
18+
This interface is an binary interface using the protobuf format and GRPC standard.
19+
The protobuf files schema are available in the source code.
20+
21+
The interface is responsible to communicate with other nodes in the network:
22+
23+
* block sending and receiving
24+
* fragments (transaction, certificates) broadcast
25+
* peer2peer gossip
26+
27+
=== Public API REST
28+
29+
This interface is for simple queries for clients like:
30+
31+
* Wallet Client & Middleware
32+
* Analytics & Debugging tools
33+
* Explorer
34+
35+
it's recommended for this interface to not be opened to the public.
36+
37+
=== Control API REST
38+
39+
This interface is not finished, but is a restricted via an ACL,
40+
it allows one to perform maintenance tasks on the process such as:
41+
42+
* Node Shutdown
43+
* Load/Refresh/Retire cryptographic material

‎jormungandr/02-concepts/index.adoc

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
= General Concepts
2+
3+
This chapter covers the general concepts of the blockchain, and their application
4+
in the node, and is followed by the node organisation and the user interaction with it.
5+
6+
include::01-blockchain.adoc[leveloffset=+1]
7+
8+
include::02-node.adoc[leveloffset=+1]

‎jormungandr/03-stakepool/01-registering-stake.adoc

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
= Registering your stake
2+
3+
Without a stake key you cannot participate in the consensus process. Generating this key allows one to have a place for their funds, participate in the protocol, claim stake, reap rewards and if one desires, setup a stakepool.
4+
5+
This key pair identifies you as a potential stake owner.
6+
7+
== You stake key pair
8+
9+
It is preferable to use a key pair that is different from
10+
your wallet (for security reason). See the [`jcli key`] documentation
11+
to generate a new key pair of type `Ed25519` or `Ed25519Extended`. For example:
12+
13+
[source, bash]
14+
----
15+
$ jcli key generate --type=Ed25519Extended > stake_key.prv
16+
----
17+
18+
The file `stake_key.prv` will contain your private key.
19+
20+
[source, bash]
21+
----
22+
$ cat stake_key.prv | jcli key to-public > stake_key.pub
23+
----
24+
25+
The file `stake_key.pub` will contain your public key.

0 commit comments

Comments
 (0)