themelio-node 0.11.0

Reference implementation of Themelio
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

# themelio-node: Themelio's reference implementation

[![](https://img.shields.io/crates/v/themelio-node)](https://crates.io/crates/themelio-node)
![](https://img.shields.io/crates/l/themelio-node)

[Themelio](https://themelio.org) is a new public blockchain focused on security, performance, and long-term stability. `themelio-node` is Themelio's reference implementation in Rust.

## Installation

For security reasons, until we have reliable reproducible build infrastructure, the only official distribution channel for `themelio-node` is its source code package on [crates.io](https://crates.io).

Fortunately, installing `themelio-node` from source is extremely easy. First, make sure [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) is installed on your machine. Then, simply run

```
$ cargo install --locked themelio-node
```

This produces an executable `themelio-node` in `~/.cargo/bin/`, which should already be in your `$PATH`.

## Hardware Requirements

### Minimum:

- 1-core CPU
- 4GB of RAM
- at least 200GB of free storage (SSD not necessary)
- 10 Mbit/sec download Internet service

### Recommended:

- 4+ core CPU
- 16GB of RAM
- 200+GB of free storage on a fast device (SSD, RAID array, etc)
- 50+ Mbit/sec up/download Internet service

Full nodes replicate every consensus-confirmed block, validating its contents and ensuring network security while providing a local cache of the entire blockchain state. Running a full node helps contribute to the security and (read) performance of the network.

There are two kinds of full nodes:

- Auditor nodes comprise the vast majority of full nodes. They replicate and verify blocks but do not vote in consensus.
- Staker nodes, the ultimate guardians of Themelio security, have Sym locked up and participate in consensus. They are analogous to miners in proof-of-work blockchains like Bitcoin.

## Auditor Full Node

### On the Themelio Mainnet:

To run an auditor on the “mainnet” (which at the moment is far from stable, but does have a persistent history), just run:

```
$ themelio-node
```

`themelio-node` will then beginning synchronizing all the blocks in the blockchain. This will take quite a while (a day or so) and store a bunch of data in in `~/.themelio-node/`.

### On the Themelio Testnet:

To run the auditor on the non-persistent testnet, where most covenant development and testing will happen during the betanet period, run instead

```
$ themelio-node --bootstrap tm-1.themelio.org:11814 --testnet
```

Note that two things were needed to connect to the testnet:

- Connecting to a testnet bootstrap node (this is the first server your full node talks to)
- Specifying --testnet, to use testnet validation rules

### Configurations

You can change the configuration of an auditor node with the following flags:

```
--bootstrap <bootstrap>...
            Bootstrap addresses. May be given as a DNS name [default: mainnet-bootstrap.themelio.org:11814]

--database <database>                        Database path [default: /tmp/themelio-mainnet]

--listen <listen>                            Listen address

--testnet                                    Use testnet validation rules

--override-genesis <override-genesis>
            If given, uses this YAML file to configure the network genesis rather than following the known
            testnet/mainnet genesis
```

### Local simnet support

**Note**: there will soon be a tool to automatically generate these configurations.

We can configure a simnet --- a "fake" network local to our computer --- by the combination of three options:

- `--bootstrap 127.0.0.1:11814` to bootstrap only with ourselves instead of any remote node
- `--override-genesis network-config.yaml`, where `custom-config.yaml` contains configuration for a _custom network_ of the following form:
  ```yaml
  network: custom02 # anything from custom02..custom08
  # specifies the "initial stash" of money in the genesis block
  init_coindata:
    # what address gets the initial supply of money
    covhash: t5xw3qvzvfezkb748d3zt929zkbt7szgt6jr3zfxxnewj1rtajpjx0
    # how many units (in millionths)
    value: 1000000
    # denomination
    denom: Mel
    # additional data in the UTXO
    additional_data: []
  # specifies all the stakers with consensus power.
  # we need to specify ourselves in order to produce any blocks; "themelio-crypttool generate-ed25519" (install via cargo) can generate a keypair for us
  stakes:
    deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef:
      pubkey: 4ce983d241f1d40b0e5b65e0bd1a6877a35acaec5182f110810f1276103c829e
      e_start: 0
      e_post_end: 100000 # essentially never end the stake
      syms_staked: 10000 # does not matter
  ```
- `--staker-cfg staker-config.yaml` must contain a _staker_ configuration like this:
  ```yaml
  # secret key; must correspond to "stakes.dead[...]beef.pubkey" in the network config
  signing_secret: 5b4c8873cbdb089439d025e9fa817b1df1128231699131c245c0027be880d4d44ce983d241f1d40b0e5b65e0bd1a6877a35acaec5182f110810f1276103c829e
  # address for staker-network communication, this can be arbitrary
  listen: 127.0.0.1:20000
  # must be same as "listen"
  bootstrap: 127.0.0.1:20000
  # where block rewards are sent
  payout_addr: t5xw3qvzvfezkb748d3zt929zkbt7szgt6jr3zfxxnewj1rtajpjx0
  # vote for this fee multiplier (higher values charge more fees)
  target_fee_multiplier: 10000
  ```

A more detailed explanation of `--staker-cfg` requires explaining the staker and consensus system, as follows:

## Staker Full Node

### On the Themelio Mainnet:

WIP

### On the Themelio Testnet:

WIP

### Configuration

WIP

## Contributing

Thank you for considering contributing to the Themelio source code! We welcome all contributions from absolutely anyone on the internet.

For minor changes, simply fork, fix, and submit a pull request. If you want to propose a larger change, be sure to get in touch with our dev team on [Discord]() to make sure your change aligns with Themelio's overarching philosophy. This will likely save you a significant amount of time and effort, as well as speed up the review process of your change.

Finally, make sure your code adheres to the following guidelines:

- Your code must adhere to the official Rust [style guide](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md)
- Your code must be documented per the official Rust [documentation guidelines](https://rust-lang.github.io/api-guidelines/documentation.html)
- Pull requests must be based on and opened against the `master` branch
- Commit messages must be descriptive
- Any protocol changes (whether consensus-breaking or not) must start as a TIP (e.g. [TIP-101](https://github.com/themeliolabs/themelio-node/issues/87))

## License

The license of the project is the Mozilla Public License, version 2.

---

## Source code structure

`themelio-node` is a highly concurrent program where different tasks are done by separate _actors_, which are "active" structs that own background async tasks or threads. They concurrently run and communicate both with other actors and with "plain data" types like `Mempool`. They are represented as green boxes in the following diagram illustrating the _data flows_ of the whole program:

![](diagram.png)

There are the following primary types in themelio-node:

- `NodeProtocol` is the **core node actor**. It implements the core auditor/full node logic: gossiping with other through the `melnet`-based auditor P2P network (via the `themelio-nodeprot` crate) to synchronize the latest blockchain state.
  - Pushes new blocks to `Storage`
  - Pushes new transactions to `Mempool`; they are only gossipped further if `Mempool` accepts them
  - Pulls data from `Storage` to gossip to other nodes
  - Pulls data from `BlockIndexer` to answer queries about coin lists (which coins do this address "own")
- `BlockIndexer` indexes "nonessential" information about blocks. It continually pulls blocks out of `Storage`, and indexes them, keeping track of information such as which coins do which address own.
- `Storage` encapsulates all persistent storage in the system. It is not an actor, so it does not initiate any data flows.
  - Stores data using `meshanina` (for sparse Merkle tree nodes) and `boringdb` (for blocks and other metadata)
  - `Mempool` is a non-persistent field that keeps track of _the most likely next block_. This is based on the existing blockchain state plus unconfirmed transactions seen in the network.
- `StakerProtocol` is the **core staker actor**, which is only started in staker mode. It runs the Streamlet consensus protocol (implemented in the `novasymph` crate) over a separate melnet P2P.
  - Pushes freshly finalized blocks, with their consensus proofs (a quorum of signatures), into `Storage` (where `NodeProtocol` will pick them up and gossip them)
  - When proposing a block, pulls a candidate from `Mempool`

## Metrics

Themelio Labs runs a worldwide network of Themelio full nodes --- `themelio-node` can also be compiled to report metrics for this network.

Read [here](Metrics.md).