diff --git a/0002-binary-protocol.md b/rfc/0002 New binary Duniter protocol.md similarity index 52% rename from 0002-binary-protocol.md rename to rfc/0002 New binary Duniter protocol.md index 90455329e0645e7f00d0545bef4caff37a97f8c8..beb33333fea0931ff2915025cb22a7e31b6ad0f3 100644 --- a/0002-binary-protocol.md +++ b/rfc/0002 New binary Duniter protocol.md @@ -1,91 +1,107 @@ -``` -DUIP: 2 (Update 2) +# New binary Duniter protocol + +```txt +RFC: 2 (Update 2) Title: New binary Duniter protocol -Author: Nanocryk <nanocryk@gmail.com> -Status: Proposition -Type: Hard-fork (documents format) -Dependency : DUIP-0001 (Update 2) +Type: Protocol change (Hardfork) +Parent: #1 (Abstract Syntax Tree-based output script locks) +Status: WIP +Author: nanocryk <nanocryk@gmail.com> Created: 2017-11-27 -License: GPL-3 +Last edited: 2017-12-20 +License: AGPL-3 ``` > This document is currently being written and thus it's not complete. Specifications may change in the future. -# Abstract +## Abstract In the current Duniter protocol all documents are managed in a textual format. While being practical as readable and verifiable by humans, it's less beneficial for programs usage since it needs parsing, fields content verifications and waste space with unused codepoints of text formats. We propose a new protocol format which reuses ideas of the current protocol while providing a more concise and less error-prone structure while staying simple enough so it can be analysed with appropriate tools or even converted to text. -# Table of Contents +## Table of Contents 1. [Introduction](#1-introduction) -2. [Conventions](#2-conventions) - 2.1 [Endianness](#21-endianness) - 2.2 [Bases](#22-bases) - 2.3 [Hashes](#23-hashes) - 2.4 [Block identifiers](#24-block-identifiers) - 2.5 [Dates](#25-dates) - 2.6 [Keys and signatures](#26-keys-and-signatures) - 2.7 [Identities](#27-identities) -3. [Documents](#3-documents) - 3.1 [Document structure](#31-document-structure) - 3.2 [Embeded documents format](#32-embeded-documents-format) - 3.3 [`Identity` document body](#33-identity-document-body) - 3.4 [`Certification` document body](#34-certification-document-body) - 3.5 [`Membership` document body](#35-membership-document-body) - 3.6 [`Revocation` document body](#36-revocation-document-body) - 3.7 [`RevocationV10` document body](#37-revocationv10-document-body) - 3.8 [`Transaction` document body](#38-transaction-document-body) - 3.9 [`Block` document body](#39-block-document-body) - -# 1. Introduction - -The Duniter protocol is composed of a set of documents describing actions in a distributed ledger of transactions and identities : +1. [Conventions](#2-conventions) + 1. [Endianness](#21-endianness) + 1. [Bases](#22-bases) + 1. [Hashes](#23-hashes) + 1. [Block identifiers](#24-block-identifiers) + 1. [Dates](#25-dates) + 1. [Keys and signatures](#26-keys-and-signatures) + 1. [Identities](#27-identities) +1. [Documents](#3-documents) + 1. [Document structure](#31-document-structure) + 1. [Embeded documents format](#32-embeded-documents-format) + 1. [`Identity` document body](#33-identity-document-body) + 1. [`Certification` document body](#34-certification-document-body) + 1. [`Membership` document body](#35-membership-document-body) + 1. [`Revocation` document body](#36-revocation-document-body) + 1. [`RevocationV10` document body](#37-revocationv10-document-body) + 1. [`Transaction` document body](#38-transaction-document-body) + 1. [`Block` document body](#39-block-document-body) + +## 1. Introduction + +The Duniter protocol is composed of a set of documents describing actions in a distributed ledger of transactions and identities : + - The `Transaction` document allow to move funds from **inputs** to **outputs**. Each **output** is created with a **script** describing unlocking conditions. This conditions must be fullfilled to be used as an transaction **input**. Since Duniter is made to run libre cryptocurrencies, its possible to list Universal Dividends to use. + - The `Identity` document allow an individual to create an identity in the system with a username and a cryptographic public key. Each individual must have only one Identity, the certification procedure being a way to prevent most multi-identities per individual attemps. + - The `Certification` document allow other individuals to certify this identity so it can enter the Web of Trust, a *directed graph* storing trust and knownledge between identities. -- The `Membership` document signals regularly the state of the issuer (new in the WoT, still active or leaving). + +- The `Membership` document signals regularly the state of the issuer (new in the WoT, still active or leaving). + - The `Revocation` document allow an individual to invalidate its `Identity` document. It can be used if he no longer want to be part of the WoT, if his key is compromised or he just want to change its username or key. + - The `Revocation` entity is a compatibility document for textual document curently being used. Since a revocation document must be valid for any period of time, it's necessary that current document stay valid with this new format. + - The `Block` document store these documents and the hash of the previous block, creating a blockchain. With some constraints on the hash of this document, it prevent users to revert or change previous validated documents. It acts as an immutable history of all documents since the currency creation. Since this blockchain is present on all nodes of the network, it's also indestructible. Details of each document structure are defined later in this document. -# 2. Conventions +## 2. Conventions -## 2.1. Endianness +### 2.1. Endianness All data fields are big-endian unless otherwise specified. -## 2.2. Bases +### 2.2. Bases Some data are stored or display using specific bases : -- **Base58** : Mainly used for public keys, it avoids using close looking characters and allow whole content selection with double-clicking. -Alphabet : `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz` -- **Base58Check** : Data stored in **Base58** with some metadata and a checksum to avoid manual copy errors. Should be used for any error-prone informations, such as public keys used displayed in clients. This format will be stricly detailed further in this document. -- **Base64** : Data format used for non error-prone data such as signatures. -Alphabet : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/` -- **Name64** : Variation of **Base64** format for names formating. Allow to store names in a more concise way that raw ASCII/UTF-8 text. -Alphabet : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-` +- **Base58** : Mainly used for public keys, it avoids using close looking characters and allow whole content selection with double-clicking. + + Alphabet : `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz` -## 2.3. Hashes +- **Base58Check** : Data stored in **Base58** with some metadata and a checksum to avoid manual copy errors. Should be used for any error-prone informations, such as public keys used displayed in clients. This format will be stricly detailed further in this document. + +- **Base64** : Data format used for non error-prone data such as signatures. + + Alphabet : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/` + +- **Name64** : Variation of **Base64** format for names formating. Allow to store names in a more concise way that raw ASCII/UTF-8 text. + + Alphabet : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-` + +### 2.3. Hashes All cryptographic hashes are made with `SHA256` algorithm, stored on 32 bytes and displayed as hexadecimal. -## 2.4. Block identifiers +### 2.4. Block identifiers Each block is indexed by its `BlockID` stored as a **4 bytes unsigned integer**. Genesis block `BlockID` is `0`, and each following block get its `BlockID` incremented by `1`. -To refeer a block, we use it's `Blockstamp` made of its `BlockID` and its `Hash`. -The `Blockstamp` of the genesis block *might be* `0-883228A23F8A75B342E912DF439738450AE94F5D` and the `Blockstamp` of block `443` *might be* `433-FB11681FC1B3E36C9B7A74F4DDE2D07EC2637957`. +To refeer a block, we use it's `Blockstamp` made of its `BlockID` and its `Hash`. +The `Blockstamp` of the genesis block *might be- `0-883228A23F8A75B342E912DF439738450AE94F5D` and the `Blockstamp` of block `443` *might be- `433-FB11681FC1B3E36C9B7A74F4DDE2D07EC2637957`. Since hashes are stored on **32 bytes**, a blockstamp is stored on a **36 bytes** value. > Note that it says "might be" because the hash is not known in advance. -## 2.5. Dates +### 2.5. Dates All dates are stored in [UNIX timestamp format][unix-timestamp], as the number of seconds since 00:00:00 UTC on January 1, 1970. They are stored in a 64bit format to avoid [year 2038 problem][year-2038-problem]. In this format the counter will overflow in approximately 293 billion years. @@ -98,222 +114,275 @@ Another way to provide dates is to reference a `Blockstamp`. Dates in the blockc [unix-timestamp]: https://en.wikipedia.org/wiki/Unix_time [year-2038-problem]: https://en.wikipedia.org/wiki/Unix_time#Representing_the_number -## 2.6. Keys and signatures +### 2.6. Keys and signatures Actually only [Ed25519][ed25519] signatures are usable, but the format allow the user to choose which cryptosystem he wants to use. A 2 bytes field `Cryptosystem` specify which system to use.Keys and signatures provided depends of the cryptosytem. To avoid dealing with any sizes in documents, we use public key hashes defined as : -``` +```txt PublicKey.Hash = SHA256(Cryptosystem + Key) ``` Supported cryptosystems are : + - [Ed25519][ed25519] (`0x0000`) > More cryptosystems could be added later. [ed25519]: https://en.wikipedia.org/wiki/EdDSA -## 2.7. Identities +### 2.7. Identities Each identity is defined by an `Identity.Hash` made from the username, its `PublicKey.Hash` and the `Blockstamp` of the identity creation. -``` +```txt Identity.Hash = SHA256(Identity.Username + Identity.PublicKey.Hash + Identity.Blockstamp) ``` -Usernames can be used for only one identity registered on the blockchain. +Usernames can be used for only one identity registered on the blockchain. > It will maybe be possible in the future to use a username not used for a long time. -> As explained below, each document contains issuers raw public keys and signatures. We can hash provided public keys to find associated identities. +As explained below, each document contains issuers raw public keys and signatures. We can hash provided public keys to find associated identities. -# 3. Documents +## 3. Documents -## 3.1. Document structure +### 3.1. Document structure Each document is constructed as : -* `MagicValue` : a **4 bytes** constant (`0xDAE2D598`) used to easily recognise Duniter documents. It has been choosed randomly but contains data with low probability to find. +- `MagicValue` : a **4 bytes** constant (`0xDAE2D598`) used to easily recognise Duniter documents. It has been choosed randomly but contains data with low probability to find. + > TODO : Maybe find a better value, should be invalid UTF-8. It could also have a symbolic meaning. -* `ProtocolVersion` : a **2 bytes** value storing the current Duniter protocol version. Each new incompatible protocol change should increase this value by one. Since current text format is version `10`, we'll define this protocol version as `11` unless another upgrade is made before the application of this document. -* `Currency` : a **12 bytes** currency name in **Name64** format. Name can be up to 16 characters, unused space must be filled with `.` which will be discarded for display. -* `DocumentType` : a **1 byte** value given the type of this document. Types are : - * `0x00` : `Block` - * `0x10` : `Transaction` - * `0x20` : `Identity` - * `0x21` : `Certification` - * `0x22` : `Membership` - * `0x23` : `Revocation` - * `0x24` : `RevocationV10` -* `Blockstamp` : a **36 bytes** value targeting a blockchain and defining a precise time reference. All durations will be calculated based on this blockstamp. - * For a `Block` document this `Blockstamp` define the previous block. -* `Issuers.Count` : a **1 byte** number of issuers of this document. Issuers sign the document to prove its validity. - * For `Identity`, `Certification` and `Revocation` documents, the issuer must match provided identity. - * For `Block` documents the issuer must be a member of the Web of Trust. - * For `Transaction` documents the issuers must be used by input unlock scripts. If issuers are missing or not used by scrips, transaction is invalid. + +- `ProtocolVersion` : a **2 bytes** value storing the current Duniter protocol version. Each new incompatible protocol change should increase this value by one. Since current text format is version `10`, we'll define this protocol version as `11` unless another upgrade is made before the application of this document. + +- `Currency` : a **12 bytes** currency name in **Name64** format. Name can be up to 16 characters, unused space must be filled with `.` which will be discarded for display. + +- `DocumentType` : a **1 byte** value given the type of this document. Types are : + + - `0x00` : `Block` + - `0x10` : `Transaction` + - `0x20` : `Identity` + - `0x21` : `Certification` + - `0x22` : `Membership` + - `0x23` : `Revocation` + - `0x24` : `RevocationV10` + +- `Blockstamp` : a **36 bytes** value targeting a blockchain and defining a precise time reference. All durations will be calculated based on this blockstamp. + + - For a `Block` document this `Blockstamp` define the previous block. + +- `Issuers.Count` : a **1 byte** number of issuers of this document. Issuers sign the document to prove its validity. + + - For `Identity`, `Certification` and `Revocation` documents, the issuer must match provided identity. + - For `Block` documents the issuer must be a member of the Web of Trust. + - For `Transaction` documents the issuers must be used by input unlock scripts. If issuers are missing or not used by scrips, transaction is invalid. > Since a document need to be signed by at least one issuer, the number of issuers is stored as `issuers count - 1`. We can have up to 256 issuers (value `255`) and at least 1 issuer (value `0`). -* `Issuers.List` : list of issuers of this structure : - * `Issuer.Cryptosystem` : a **2 bytes** value defining the cryptosystem used. - * `Issuer.PublicKey` : public key of the issuer. Its size depends of the cryptosystem. +- `Issuers.List` : list of issuers of this structure : + + - `Issuer.Cryptosystem` : a **2 bytes** value defining the cryptosystem used. + - `Issuer.PublicKey` : public key of the issuer. Its size depends of the cryptosystem. + > If `Issuer.Cryptosystem` contains an unknown value the whole document is invalid (an likely unreadable). -* `Body.Size` : a **4 bytes** value storing the unsigned size in bytes of the following `Body`. + +- `Body.Size` : a **4 bytes** value storing the unsigned size in bytes of the following `Body`. + > The maximum size of the body is defined by consensus rules detailed later. -* `Body` : document body defined for each document type below. + +- `Body` : document body defined for each document type below. + > Effective body size must be equal to `Body.Size`. The parser will consider the document invalid if it try to read out of bound bytes or if bytes are left. -* `Signatures.List` : list of signatures associated with each issuers. They sign all from `MagicValue` to `Body`. - > Signatures must be provided in the same order as the issuers. +- `Signatures.List` : list of signatures associated with each issuers. They sign all from `MagicValue` to `Body`. + + > Signatures must be provided in the same order as the issuers. > Signatures must have the expected sizes for provided cryptosystems. If while reading the document we try to read out of range or some data is left, the document is invalid. -## 3.2. Embeded documents format +### 3.2. Embeded documents format Consensus is only reached with `Block` documents because they contain the previous block hash and a proof of work condition. All other documents are stored in pools, waiting to be added in blocks in the following format : -* `ProtocolVersion` -* `Blockstamp` -* `Issuers.Count` -* `Issuers.List` -* `Body.Size` -* `Body` -* `Signatures.List` + +- `ProtocolVersion` +- `Blockstamp` +- `Issuers.Count` +- `Issuers.List` +- `Body.Size` +- `Body` +- `Signatures.List` To verify signatures, the original document will be constructed with these provided informations. Missing fields will copied from the `Block` document container and `DocumentType` will be deduced from the context. > `ProtocolVersion` is needed since we can accept outdated revocation documents or documents issued just before the transition. -## 3.3. `Identity` document body +### 3.3. `Identity` document body -* `Username.Length` : a **1 byte** value containing the length of the username in characters (0 to 128) -* `Username` : username expressed in **Name64** format. Some padding may be necessary for bytes alignements and will be ignored. +- `Username.Length` : a **1 byte** value containing the length of the username in characters (0 to 128) +- `Username` : username expressed in **Name64** format. Some padding may be necessary for bytes alignements and will be ignored. The document issuer public key will be associated with this new identity and will be used to compute the virtual field `Identity.Hash`. -## 3.4. `Certification` document body +### 3.4. `Certification` document body + +- `Target.Identity.Hash` : a **32 bytes** value storing the entity hash of the certified individual. + +### 3.5. `Membership` document body + +- `Membership` : a **1 byte** value storing the state of the membership : + - `0x00` for `OUT` + - `0x01` for `IN` +- `Identity.Hash` : a **32 bytes** value storing the identity hash of the member. -* `Target.Identity.Hash` : a **32 bytes** value storing the entity hash of the certified individual. +### 3.6. `Revocation` document body -## 3.5. `Membership` document body +- `Identity.Hash` : a **32 bytes** value storing the identity hash of the member. -* `Membership` : a **1 byte** value storing the state of the membership : - * `0x00` for `OUT` - * `0x01` for `IN` -* `Identity.Hash` : a **32 bytes** value storing the identity hash of the member. +### 3.7. `RevocationV10` document body -## 3.6. `Revocation` document body +- `Text` : a UTF-8 text storing a revocation document in version `10` format. -* `Identity.Hash` : a **32 bytes** value storing the identity hash of the member. +### 3.8. `Transaction` document body -## 3.7. `RevocationV10` document body +- `Inputs.Dividend.Count` : a **1 byte** value storing the number of Universal Dividend used in this transaction. -* `Text` : a UTF-8 text storing a revocation document in version `10` format. +- `Inputs.Dividend.List` : a list of UD inputs as : -## 3.8. `Transaction` document body + - `Dividend.Identity.Hash` : a **32 bytes** value storing the identity hash of the member creating the UD. + - `Dividend.Blockstamp` : a **36 bytes** value storing the emission time of the UD. -* `Inputs.Dividend.Count` : a **1 byte** value storing the number of Universal Dividend used in this transaction. -* `Inputs.Dividend.List` : a list of UD inputs as : - * `Dividend.Identity.Hash` : a **32 bytes** value storing the identity hash of the member creating the UD. - * `Dividend.Blockstamp` : a **36 bytes** value storing the emission time of the UD. > The UD is unlocked if the public key associated with this identity signs the transaction. -* `Inputs.Unspent.Count` : a **1 byte** value storing the number of unspent output used in this transaction. -* `Inputs.Unspent.List` : a list of unspent outputs as : - * `Unspent.TransactionHash` : a **32 bytes** hash representing the transaction containing the unspent output. - * `Unspent.UnlockConditions` : list of unlock conditions as defined in [DUIP 1 (Update 2)][duip1]. -* `Outputs.Count` : a **1 byte** value storing the number of outputs of this transaction. -* `Outputs.List` : a list of outputs as : - * `Value` : a **4 bytes** unsigned currency value. - * `Base` : a **1 byte** unsigned power base. - > Monetary values are expressed as `Value * 10^Base`. When `Base` will reach `255` it will be safe to loop back to `0`; since base `0` values will be worth nothing and won't exist anymore. - * `Script` : Script to unlock funds defined in [DUIP 1 (Update 2)][duip1]. -[duip1]: https://git.duniter.org/nodes/common/duips/blob/dip/0001/0001-ast-script-lock.md +- `Inputs.Unspent.Count` : a **1 byte** value storing the number of unspent output used in this transaction. + +- `Inputs.Unspent.List` : a list of unspent outputs as : + + - `Unspent.TransactionHash` : a **32 bytes** hash representing the transaction containing the unspent output. + - `Unspent.UnlockConditions` : list of unlock conditions as defined in [RFC #1 (Update 2)][rfc1]. + +- `Outputs.Count` : a **1 byte** value storing the number of outputs of this transaction. + +- `Outputs.List` : a list of outputs as : + - `Value` : a **4 bytes** unsigned currency value. + - `Base` : a **1 byte** unsigned power base. + > Monetary values are expressed as `Value * 10^Base`. When `Base` will reach `255` it will be safe to loop back to `0`; since base `0` values will be worth nothing and won't exist anymore. + - `Script` : Script to unlock funds defined in [RFC #1 (Update 2)][rfc1]. + +[rfc1]: https://git.duniter.org/nodes/common/doc/blob/dip/0001/rfc/0001%20Abstract%20Syntax%20Tree-based%20output%20script%20locks.md -### Constraints : +#### Constraints -* All funds unlocked from inputs are used and its sum must be equal to the sum of all outputs. If a user want to use a *fraction of the funds on an address*, a must set as an output a new lock with his signatures. +- All funds unlocked from inputs are used and its sum must be equal to the sum of all outputs. If a user want to use a *fraction of the funds on an address*, a must set as an output a new lock with his signatures. > All funds are moved through transactions from unspent outputs to new ones. Addresses don't realy exists and are just a simplified representation of a locked output with a key pair. - -* Only unspent outputs can be used. The server should keep unspent outputs in a pool for efficient verifications. It means that each UD can only be used once and a non used fraction of it must be "sent" on an address. -## 3.9. `Block` document body +- Only unspent outputs can be used. The server should keep unspent outputs in a pool for efficient verifications. It means that each UD can only be used once and a non used fraction of it must be "sent" on an address. + +### 3.9. `Block` document body -* `ID` : a **4 bytes** value storing the current block id. It must be `PreviousBlock.ID + 1`. +- `ID` : a **4 bytes** value storing the current block id. It must be `PreviousBlock.ID + 1`. > Block `#0` ignore previous ID verification. -* `PreviousBlock.Issuer` : a **32 bytes** value storing previous block issuer public key. +- `PreviousBlock.Issuer` : a **32 bytes** value storing previous block issuer public key. > Block `#0` `PreviousBlock.Issuer` is filled with `0x00`s and will be ignored. -* `Time` : current time on **8 bytes**. Must be in a range of 4 hours arount average block time. -* `UpgradeBits` : a **4 bytes** bitset for upgrade signaling mechanism. Each bit should be at `0` by default. When a new upgrade is deployed, it's not yet active and receive a free signaling bit. If in the block window more than X% of blocks signals this bit, the upgrade is locked and will be activated after another window (so non signaling nodes have time to upgrade). After the upgrade is activated, this version bit is freed and will be used later for another upgrade. With a 4 bytes bitset, 32 upgrades can be planned simultaneously, which is largly enough. -* `PowMin` : a **1 byte** value storing the current minimum PoW difficulty. -* `AverageTime` : average time on **8 bytes**. -* `UnitBase` : a **1 byte** value storing the unit base. -* `IssuerFrame` : a **2 bytes** value storing the size of the frame to look for issuers. -* `IssuerFrame.Count` : a **2 bytes** signed counter to increment/decrement `IssuerFrame`. -* `MemberCount` : a **8 bytes** value storing member count. -* `Dividend` : a **4 bytes** unsigned value storing the amount of dividend created at the time of this block. For most of the blocks this field value is `0`, it is positive only for the blocks that mark the creation of the dividend. -* **If block `0`** : `CurrencyParams` composed of : - > All values are integers on **4 bytes** unless otherwise specified. - - - * `c` : the %grouwth of the UD every `dt` period (float on **8 bytes**). - * `dt` : time period between 2 UDs. - * `dtReeval` : time period between 2 re-evaluation of the UD. - * `ud0` : `UD(0)`, initial Universal Dividend. - * `udTime0` : time of first UD. - * `udReeval_time0` : time of first re-evaluation of the UD. - * `sigPeriod` : minimum delay between 2 certifications of a same issuer. - * `msPeriod` : minimum delay between 2 memberships of a same issuer. - * `sigStock` : maximum quantit of active certifications made by a member. - * `sigWindow` : maximum delay a certification can wait before expired for non-writing. - * `sigValidity` : maximum age of a valid signature. - * `sigQty` : minimum quantity of signatures to be part of the WoT. - * `idtyWindow` : maxiumum delay an identity can wait before being expired for non-writing. - * `msWindow` : maximum delay a memnership can wait before being expired for non-writing. - * `xPercent` : minimum percent of sentries to reach to match the distance rule. - * `msValidity` : maximum age of an active membership. - * `stepMax` : maxium maximum distance between each WoT member and a newcomer. - * `averageTimeBlocks` : number of blocks used to calculate average time. - * `averageGenTime` : the average/wanted time for writing 1 block. - * `dtDiffEval` : the number of blocks required to evaluate again `powMin` value. - * `percentRot` : the percent of previous issuers to reach for personalized difficulty (float on **8 bytes**) - * `txWindow` : maximum delay a transaction can wait before being expired for non-writing. - -* Identities : - * `Identities.Count` : a **8 bytes** value storing number of `Identity` documents in this block. - * `Identities.List` : list of `Identity` documents in embeded format. -* Joiners : - * `Joiners.Count` : a **8 bytes** value storing numbers of *joiners* in this block. - * `Joiners.List` : a list of *joiners* as `Membership` `IN` documents in embeded format. -* Actives : - * `Actives.Count` : a **8 bytes** value storing numbers of *actives* in this block. - * `Actives.List` : a list of *actives* as `Membership` `IN` (renewal) documents in embeded format. -* Leavers : - * `Leavers.Count` : a **8 bytes** value storing numbers of *leavers* in this block. - * `Leavers.List` : a list of *leavers* as `Membership` `OUT` documents in embeded format. -* Revoked : - * `Revoked.Count` : a **8 bytes** value storing numbers of revoked members in this block. - * `Revoked.List` : a list of revoked members as `Revocation` documents in embeded format. - * `RevokedV10.Count` : a **8 bytes** value storing numbers of revoked members (with V10 document) in this block . - * `RevokedV10.List` : a list of revoked members as `RevocationV10` documents in embeded format. -* Excluded : - * `Excluded.Count` : a **8 bytes** value storing the number of excluded members' public keys in this block. - * `Excluded.List` : a list of excluded member's public keys as `PublicKey.Hash`es. -* Certifications : - * `Certifications.Count` : a **8 bytes** value storing the number of certifications in this block. - * `Certifications.List` : a list of `Certification` documents in embeded format. -* Transactions : - * `Transactions.Count` : a **8 bytes** value storing the number of transactions in this block. - * `Transactions.List` : a list of `Transaction` documents in embeded format. -* `InnerHash` : a **32 bytes** hash of all above fields. -* `Nonce` : a **32 bytes** arbitrary value used to change the block hash for PoW. +- `Time` : current time on **8 bytes**. Must be in a range of 4 hours arount average block time. + +- `UpgradeBits` : a **4 bytes** bitset for upgrade signaling mechanism. Each bit should be at `0` by default. When a new upgrade is deployed, it's not yet active and receive a free signaling bit. If in the block window more than X% of blocks signals this bit, the upgrade is locked and will be activated after another window (so non signaling nodes have time to upgrade). After the upgrade is activated, this version bit is freed and will be used later for another upgrade. With a 4 bytes bitset, 32 upgrades can be planned simultaneously, which is largly enough. + +- `PowMin` : a **1 byte** value storing the current minimum PoW difficulty. + +- `AverageTime` : average time on **8 bytes**. + +- `UnitBase` : a **1 byte** value storing the unit base. + +- `IssuerFrame` : a **2 bytes** value storing the size of the frame to look for issuers. + +- `IssuerFrame.Count` : a **2 bytes** signed counter to increment/decrement `IssuerFrame`. + +- `MemberCount` : a **8 bytes** value storing member count. + +- `Dividend` : a **4 bytes** unsigned value storing the amount of dividend created at the time of this block. For most of the blocks this field value is `0`, it is positive only for the blocks that mark the creation of the dividend. + +- **If block `0`** : `CurrencyParams` composed of : + > All values are integers on **4 bytes** unless otherwise specified. + + - `c` : the %grouwth of the UD every `dt` period (float on **8 bytes**). + - `dt` : time period between 2 UDs. + - `dtReeval` : time period between 2 re-evaluation of the UD. + - `ud0` : `UD(0)`, initial Universal Dividend. + - `udTime0` : time of first UD. + - `udReeval_time0` : time of first re-evaluation of the UD. + - `sigPeriod` : minimum delay between 2 certifications of a same issuer. + - `msPeriod` : minimum delay between 2 memberships of a same issuer. + - `sigStock` : maximum quantit of active certifications made by a member. + - `sigWindow` : maximum delay a certification can wait before expired for non-writing. + - `sigValidity` : maximum age of a valid signature. + - `sigQty` : minimum quantity of signatures to be part of the WoT. + - `idtyWindow` : maxiumum delay an identity can wait before being expired for non-writing. + - `msWindow` : maximum delay a memnership can wait before being expired for non-writing. + - `xPercent` : minimum percent of sentries to reach to match the distance rule. + - `msValidity` : maximum age of an active membership. + - `stepMax` : maxium maximum distance between each WoT member and a newcomer. + - `averageTimeBlocks` : number of blocks used to calculate average time. + - `averageGenTime` : the average/wanted time for writing 1 block. + - `dtDiffEval` : the number of blocks required to evaluate again `powMin` value. + - `percentRot` : the percent of previous issuers to reach for personalized difficulty (float on **8 bytes**) + - `txWindow` : maximum delay a transaction can wait before being expired for non-writing. + +- Identities : + + - `Identities.Count` : a **8 bytes** value storing number of `Identity` documents in this block. + + - `Identities.List` : list of `Identity` documents in embeded format. +- Joiners : + + - `Joiners.Count` : a **8 bytes** value storing numbers of *joiners* in this block. + - `Joiners.List` : a list of *joiners* as `Membership` `IN` documents in embeded format. + +- Actives : + + - `Actives.Count` : a **8 bytes** value storing numbers of *actives* in this block. + - `Actives.List` : a list of *actives* as `Membership` `IN` (renewal) documents in embeded format. + +- Leavers : + + - `Leavers.Count` : a **8 bytes** value storing numbers of *leavers* in this block. + - `Leavers.List` : a list of *leavers* as `Membership` `OUT` documents in embeded format. + +- Revoked : + + - `Revoked.Count` : a **8 bytes** value storing numbers of revoked members in this block. + - `Revoked.List` : a list of revoked members as `Revocation` documents in embeded format. + - `RevokedV10.Count` : a **8 bytes** value storing numbers of revoked members (with V10 document) in this block . + - `RevokedV10.List` : a list of revoked members as `RevocationV10` documents in embeded format. + +- Excluded : + + - `Excluded.Count` : a **8 bytes** value storing the number of excluded members' public keys in this block. + - `Excluded.List` : a list of excluded member's public keys as `PublicKey.Hash`es. + +- Certifications : + + - `Certifications.Count` : a **8 bytes** value storing the number of certifications in this block. + - `Certifications.List` : a list of `Certification` documents in embeded format. + +- Transactions : + + - `Transactions.Count` : a **8 bytes** value storing the number of transactions in this block. + - `Transactions.List` : a list of `Transaction` documents in embeded format. + +- `InnerHash` : a **32 bytes** hash of all above fields. + +- `Nonce` : a **32 bytes** arbitrary value used to change the block hash for PoW. 2 virtual fields are considered : -* `BlockHash` : a **32 bytes** value storing the hash of the whole block. This hash must respect the difficulty rule. -* `BlockSize`: a **4 bytes** value storing the size in bytes of the whole block. Should not overflow since a maximum size limit is required. \ No newline at end of file + +- `BlockHash` : a **32 bytes** value storing the hash of the whole block. This hash must respect the difficulty rule. + +- `BlockSize`: a **4 bytes** value storing the size in bytes of the whole block. Should not overflow since a maximum size limit is required. \ No newline at end of file