README.md 14.3 KB
Newer Older
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
1 2
# Ercoin

3
Ercoin is a proof of stake cryptocurrency written in [Erlang](https://www.erlang.org) using [Tendermint](https://tendermint.com) and released under Apache License 2.0.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
4 5 6 7 8

[Issues are tracked on GitLab.](https://gitlab.com/Ercoin/ercoin/issues) Contributions are welcome. Before submitting a patch, read [contributing guidelines](CONTRIBUTING.md).

## Development installation

9
1. Install [Tendermint](https://tendermint.com) (version 0.33.0).
10
2. Install [Erlang](https://www.erlang.org) (21 is the minimum version).
11
3. Install [libsodium](https://libsodium.org) (1.0.12 is the minimum version; when using a package manager, you may need to install a separate package containing development files).
12
4. Clone the Ercoin’s repository and enter the created directory.
13
5. `make app`
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
14
6. Initialize the chain (see below).
15 16
7. `make run`
8. In another window, run `tendermint node --home ~/.ercoin/`
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
17

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
18
### Initializing the chain
19

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
20 21 22 23 24
You can either generate a custom test network or download an existing genesis file.

#### Generating a custom testnet

You need at least two accounts: one locked which allows initial validators to be drawn and one unlocked. Create addresses and corresponding private keys and save data specification to a file, like this:
25 26 27 28 29 30 31 32 33 34 35 36 37 38

```erlang
#{accounts_opts =>
      [#{%% Addresses can be written either as Erlang binaries or as Base64 strings.
         address => "OeFZLmb5xrqc60U+/xztZxnVj3SSpKmIWzlz5U83oJU=",
         valid_for => 3600 * 24,
         balance => 100000000000000},
       #{address => "Hdu8UaISmnbiFzTtjagRNJS+FxKi72aUCW0RRsaDIiU=",
         valid_for => 3600 * 24 * 365,
         locked_for => 3600 * 24 * 365,
         balance => 1}],
 epoch_length => 3600}.
```

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
39
Assuming that the file is named `testnet-config.script`, run `make init data_opts='"testnet-config.script"'`. You can also pass the option map inline in the `data_opts` argument (no double quotes are then needed) or from standard input (when `data_opts` is not provided).
40 41 42 43

If you enter a low value of `epoch_length`, you may also want to lower the value of `create_empty_blocks_interval` in `config.toml`.

See documentation of `ercoin_genesis:testnet_data/1` for details.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
44

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
45 46 47 48 49 50 51
#### Initialization using an existing genesis file

Run `make init` with the following environment variables:

* `GENESIS_URL` — an URL of the `genesis.json` file.
* `GENESIS_SHA256` — SHA-256 sum of the `genesis.json` file. Non-mandatory, used to prevent tampering.

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
52
## Persistence and initial state
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
53

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
54 55 56 57
ABCI server dumps current state to `$ERCOIN_HOME` (with fallback to `~/.ercoin`) at the beginning of each epoch. The initial state, encoded using Base64, is contained as `app_state` in the `genesis.json` file in Tendermint config directory.

State is serialized using [Erlang’s External Term Format](http://erlang.org/doc/apps/erts/erl_ext_dist.html).

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
58 59
## Docker integration

60
To run the project using [Docker Compose](https://docs.docker.com/compose/), execute the following steps, assuming that data options for testnet are located in `testnet-config.script`:
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
61

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
62
1. `docker-compose build`
63 64 65 66
2. `docker volume create --name=ercoin_home`
3. `docker-compose run --no-deps tendermint init`
4. `docker-compose run abci-server make testnet < testnet-config.script`
5. `docker-compose up`
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
67 68 69 70 71 72 73 74 75 76 77

---

Docker images for tags and branches are automatically built in GitLab CI (unless tests are failing) and available in the [container registry](https://gitlab.com/Ercoin/ercoin/container_registry). For example, to pull an image generated from `master` branch:

```
docker pull registry.gitlab.com/ercoin/ercoin:master
```

`latest` tag points to `master`.

78 79 80
## Technical documentation

The information presented below is not a specification and does not cover every technical detail. If there is a discrepancy between the documentation and the code, it is possible that the code will prevail.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
81 82 83 84 85

All numbers are big endian.

Keys are Ed25519.

86
The smallest possible unit is microercoin (µERN). An Ercoin node operates only on microercoins and treats it as a basic unit.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
87

88 89
Timestamps are expressed in Unix time format.

90 91
Addresses from which transactions are performed are derived from signatures.

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
92 93 94
### Transfer transaction format

* Transaction type (0, 1 byte).
95
* Timestamp (4 bytes).
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
96 97 98 99
* To address (32 bytes).
* Value (8 bytes).
* Message length (1 byte).
* Message.
100
* Signature of all the previous fields.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
101 102 103 104

### Lock transaction format

* Transaction type (2, 1 byte).
105
* Locked until timestamp (4 bytes).
106
* Intended validator public key (32 bytes)
107
* Signature of all the previous fields.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
108 109 110 111

### Vote transaction format

* Transaction type (3, 1 byte).
112
* Timestamp (4 bytes).
113
* Choices.
114
* Signature of all the previous fields.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
115

116
### Choices format
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
117 118 119 120 121 122

* Price per tx (8 bytes).
* Price per 256 bytes per tx (8 bytes).
* Price of storing an account for 1 day (8 bytes).
* Protocol version (1 byte).

123 124 125
### Burn transaction format

* Transaction type (4, 1 byte).
126
* Timestamp (4 bytes).
127 128 129 130 131
* Value (8 bytes).
* Message length (1 byte).
* Message.
* Signature of all the previous fields.

132 133
### Signature format

134 135 136 137
* Number of keys (at least one) that signed the message (1 byte).
* A sequence of public keys (32 bytes each).
* A Merkle path (may be empty) proving that either the public key (when singular key is used) or the hash of concatenated public keys is contained in the address.
* A sequence of Ed25519 signatures corresponding to the public keys, signing the message concatenated with previous signature fields, up to and including Merkle path (64 bytes each).
138

139
#### Merkle path format
140 141

* Non-empty sequence of the following:
142
  * A value indicating whether the following value needs to be appended (1) or prepended (0) to obtain next hash (1 byte).
143 144
  * Value contributing to the hash.

145 146 147 148 149
### Tags

The following tags are set for successfully delivered transactions:

* From (Base64-encoded address).
150 151
* Fee.
* Message (Base64-encoded) — if present.
152
* To (Base64-encoded address) — if present.
153
* Type.
154 155
* Value.

156
### Account serialization format
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
157 158

Key:
159
* Address (32 bytes).
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
160 161 162

Value:

163
* Valid until (4 bytes).
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
164
* Balance (8 bytes).
165
* Locked until (optional, 4 bytes).
166
* Intended validator public key (32 bytes) — present if the “locked until” field is present.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
167

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
168 169 170 171 172 173 174 175
### Error codes

* 0 — ok.
* 1 — bad request.
* 2 — not found.
* 3 — forbidden.
* 4 — insufficient funds.
* 5 — invalid timestamp.
176
* 6 — already executed.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
177

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
178 179 180 181 182 183 184
### Application hash

The following Merkle tree is formed when calculating an application hash:

* Accounts’ root hash.
* Other data hash:
  * Protocol number.
185 186
  * Timestamp of previous block.
  * Timestamp of current block.
187 188
  * Timestamp of the last block in previous epoch.
  * Epoch stage number (1-indexed).
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
189
  * Fee deposit.
190
  * Hash of validators for the next block.
191 192
  * Future validators’ hash.
  * Fresh transactions’ hash.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
193 194 195

### State machine mechanism

196
#### Time passing
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
197

198 199 200 201 202 203 204 205
Blocks are divided into epochs, during which validator set is immutable. Epochs are divided into stages. Stage progress is done sequentially at the end of `BeginBlock` and depends mainly on the block timestamp in relation to the end of the last epoch.

For a specification of conditions for achieving particular stages and lists of actions that are taken when stages are achieved, consult the functions `should_we_step/1` and `stage_actions/1` from the `ercoin_epoch` module.

Other actions, like removing expired accounts, are performed every block.

#### Transactions

206
Validators are responsible for providing replay protection. Transactions which provide timestamps are valid only for the epoch length. Due to [issue #2840 in Tendermint](https://github.com/tendermint/tendermint/issues/2840), timestamps from the near future (up to and including epoch length) are also allowed.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
207

208
Transfer transactions modify accounts’ balances. They may not be performed from a locked account, but they can transfer funds to a locked account.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
209

210
Lock transactions lock accounts and specify intended validator public keys. They may be performed by locked accounts. Note that while it is technically possible for a complex address to become a validator, only an address being a public key will be able to sign blocks.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
211

212
Vote transactions can be performed by validators or yielded future validators to vote for fee sizes and protocol changes.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
213

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
214
#### Accounts
215

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
216
Accounts are initially created by transfer transactions, with “valid until” field set to current timestamp. If account’s validity ends and it has non-zero balance, it is automatically extended for a month or for its total balance, whichever value results in lower fee.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
217

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
218 219 220
#### Fees

Fees are charged for extending accounts and for transactions, except vote transactions. Applicable fee amounts are calculated as medians of weighted validators’ votes, with higher middle values chosen if sum of weights is even.
221

222
Fees are put into fee deposit. At the end of every epoch, it is divided between validators proportionally to their voting power. If a validator has at least 1⁄3 absencies in the passing epoch, its reward is destroyed.
223

224
#### Validators’ drawing
225

226
Drawing of validators is performed with scores proportional to:
227 228

* account balance;
229
* time for which an account will be locked, counting from the estimated start of the second next epoch, with a cap of three years.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
230

231
Partial seats are distributed randomly, proportionally to the remainders.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
232

233
### Initial data
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
234

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
235 236 237
SHA256 sum of [the generated genesis file](https://ercoin.tech/genesis.json) is `e62f25c883e33a1920cda9b147540734982fc018b5e079a01bbd47528e3350fd`.

Original rules for obtaining initial data are listed below. After the distribution period ended, some issues were revealed and a voting has been scheduled to resolve them and make a decision about the launch date.
238

239
Initial amount of coins will be distributed proportionally to the associated amounts of [BlackCoin](https://blackcoin.org) burnt in a selected time window. To participate in the distribution, create an output with the following script:
240 241 242 243 244 245 246

* 106 — [`OP_RETURN`](https://en.bitcoin.it/wiki/OP_RETURN) opcode, 1 byte.
* one of the following:
  - 76 — `OP_PUSHDATA1`
  - 77 — `OP_PUSHDATA2`
  - 78 — `OP_PUSHDATA4`
* length of the rest of the script — 1, 2 or 4 bytes, depending on the previous field.
247
* string “<code>Ercoin </code>” — 7 bytes.
248 249
* length of the “locked for” field — 0 to 4, 1 byte. (Tip: use 0 unless the account is going to be locked).
* locked for (in seconds) — 0 to 4 bytes, depending on the previous field. All values are valid, but a cap of 3.5 years is applied in regard to created account.
250
* intended validator public key — 32 bytes, present if the “locked until” field is greater than 0.
251
* signature of all the fields starting from “<code>Ercoin </code>”.
252

253
Transaction needs to be included in a BlackCoin block with a block timestamp from 2019-11-08 00:00:00 UTC to 2019-12-07 23:59:59 UTC. All accounts participating in the initial distribution will be initially valid for 3 days. If an account has multiple associated outputs, then “locked for” and “intended validator public key” will be picked from the output with highest “locked for”, with order of inclusion used as a secondary method of comparison. Amount of ercoins will be proportional to the sum of blackcoins burnt in all outputs, with total number of ERNs created being 2.6 billion. The minimum required burnt amount per Ercoin address is 3 BLK.
254

255
Initial validators will be drawn using ordinary rules, with data timestamp for obtaining entropy being the declared timestamp for the burning end plus 120. Future validators will be able to put vote transactions into BlackCoin blockchain, analogously to the genesis transaction described above, in blocks with a timestamp starting from a week to a day before genesis timestamp (which will be 2019-12-15 00:00:00 UTC if everything goes well). Transactions will be checked and applied in the order of inclusion and it will be the last step of creating genesis data.
Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
256

257
#### Voting rules
258 259 260 261 262 263 264 265 266 267 268 269

A rescheduled period of fee voting will be used to make some decisions. Each decision will be binary (yes/no), encoded using one bit of the protocol field (it will not affect the actual protocol number in production), starting from the most significant bit. The following questions will be answered:

1. Do you accept the described method of proceeding (including this set of questions)?
2. Should we wait until Tendermint 0.33 is released? If so, then launch will happen a week after that release happens, rounded up to midnight (UTC). Fee voting will end a day before the launch. If the decision is made to not wait, then the launch time will likely need a separate voting.
3. Should we accept transactions confirmed shortly after the distribution deadline, but with creation timestamps before the deadline? To be precise: there is only one such transaction. If yes, then problematic outputs will have the missing part of the fee (amount that would be sufficient to confirm the transaction quickly, i.e. to make it relayed by the BlackCoin Original wallet) deducted from their value.
4. Should we accept transactions containing burn outputs resembling unlocked Ercoin accounts, but with incomplete (invalid) signatures? If yes, then problematic outputs will have the missing part of the fee (amount which would be additionally needed if a transaction contained a complete signature in case of a simple address) deducted from their value. Note that there are no transaction outputs for locked accounts and which contain incomplete signatures.

Remaining bits should be set to zero. Voting on points 1, 3 and 4 ends on 2020-01-19 00:00:00 UTC. Initial decision on point 2 is made at the same time, but it may be changed (by putting fresher votes) until the release of Tendermint 0.33 happens.

Validators will be drawn using the original rules (including original distribution). Note that problematic burn transactions do not involve locked accounts.

270 271 272 273
#### Voting outcome

All questions were answered positively. Tendermint 0.33 was released on 2020-01-15 (UTC), hence the launch has been scheduled to 2020-01-23 00:00:00 (UTC).

Krzysztof Jurewicz's avatar
Krzysztof Jurewicz committed
274 275 276
## License

This software is licensed under under [the Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) (the “License”); you may not use this software except in compliance with the License. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.