Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

TIP-29 Milestone Payload (Stardust) #69

Merged
merged 21 commits into from
Sep 8, 2022
Merged

TIP-29 Milestone Payload (Stardust) #69

Changes from 18 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
d85fd9b
add TIP-30
Wollac Mar 25, 2022
d7241c8
Merge remote-tracking branch 'upstream/main' into milestone-with-sign…
Wollac Mar 25, 2022
c09bd70
Swap TIP number
lzpap Mar 25, 2022
612d963
Introduce new payload type value
Wollac Mar 26, 2022
a4f3cbb
Add metadata
Wollac Apr 1, 2022
8e4642b
Update with milestone options
Wollac Apr 21, 2022
900a770
update receipt TIP
Wollac Apr 21, 2022
c1f88e4
Clarify encapsulating message
Wollac Apr 21, 2022
c3ab001
Remove PoW Milestone Option
Wollac Apr 25, 2022
ff9d8a4
Changes "Last Milestone ID" to "Previous Milestone ID"
lzpap Apr 26, 2022
a60274b
Rename "messages" to "blocks"
lzpap May 19, 2022
a577cb9
Add WIP Protocol Parameteres Milestone Option
lzpap May 19, 2022
6505585
Add Protocol Version to Milestone Essence
lzpap May 20, 2022
75cc4bc
describe Protocol Parameters Milestone Option validation
Wollac Jul 7, 2022
68c26e2
add Metadata limit
Wollac Jul 7, 2022
13d84da
Fix typo
Wollac Jul 7, 2022
f2a84e2
Remove PoW option comment
Wollac Jul 19, 2022
051a20c
remove nonce reference
Wollac Jul 19, 2022
ff05c48
Update tips/TIP-0029/tip-0029.md
lzpap Jul 21, 2022
3835532
Update tips/TIP-0029/tip-0029.md
lzpap Jul 21, 2022
d2ee439
remove leagacy IOTA reference
Wollac Aug 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 295 additions & 0 deletions tips/TIP-0029/tip-0029.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,295 @@
---
tip: 29
title: Milestone Payload
description: Coordinator issued milestone payload with Ed25519 authentication
author: Angelo Capossele (@capossele) <angelo.capossele@iota.org>, Wolfgang Welz (@Wollac) <wolfgang.welz@iota.org>
discussions-to: https://github.com/iotaledger/tips/pull/69
status: Draft
type: Standards
layer: Core
created: 2022-03-25
replaces: 8
---

# Abstract

In IOTA, nodes use the milestones issued by the Coordinator to reach a consensus on which transactions are confirmed. This TIP proposes a milestone payload for the blocks described in the IOTA protocol [TIP-24](../TIP-0024/tip-0024.md). It uses Edwards-curve Digital Signature Algorithm (EdDSA) to authenticate the milestones.

# Motivation

In order to integrate the concept of milestones consistently into Tangle blocks, this TIP describes a dedicated payload type for milestones. It contains the same essential data fields that were part of a milestone bundle in the legacy IOTA protocol. Additionally, this document also describes how Ed25519 signatures are used to assure authenticity of the issued milestones. In order to make the management and security of the used private keys easier, simple multisignature features with support for key rotation have been added.
Wollac marked this conversation as resolved.
Show resolved Hide resolved

# Specification

The [BLAKE2b-256](https://tools.ietf.org/html/rfc7693) hash of the _Milestone Essence_, consisting of the actual milestone information (like its index number or position in the tangle), is signed using the Ed25519 signature scheme as described in the IRTF [RFC 8032](https://tools.ietf.org/html/rfc8032).

To increase the security of the design, a milestone can (optionally) be independently signed by multiple keys at once. These keys should be operated by detached signature provider services running on independent infrastructure elements. This assists in mitigating the risk of an attacker having access to all the key material necessary for forging milestones. While the Coordinator takes responsibility for forming Milestone Payload Blocks, it delegates signing in to these providers through an ad-hoc RPC connector. Mutual authentication should be enforced between the Coordinator and the signature providers: a [client-authenticated TLS handshake](https://en.wikipedia.org/wiki/Transport_Layer_Security#Client-authenticated_TLS_handshake) scheme is advisable. To increase the flexibility of the mechanism, nodes can be configured to require a quorum of valid signatures to consider a milestone as genuine.
Wollac marked this conversation as resolved.
Show resolved Hide resolved

In addition, a key rotation policy can also be enforced by limiting key validity to certain milestone intervals. Accordingly, nodes need to know which public keys are applicable for which milestone index. This can be provided by configuring a list of entries consisting of the following fields:
- _Index Range_ providing the interval of milestone indices for which this entry is valid. The interval must not overlap with any other entry.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not how it is implemented!
Key ranges are allowed to overlap.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked the Hornet config and there it seems we have (@muXxer please correct if wrong):

  • A list of key ranges, each element with:
    • public key
    • (potentially overlapping) range
  • A global config for the threshold (which is then applied to all key ranges)

Technically, it is equivalent to either have an overlapping list of single keys or a non-overlapping list of sets of key (like in the TIP).
@muXxer, I suppose you are suggesting to change the TIP to reflect the configuration format which is already implemented in Hornet?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I misunderstood that part. Thats even better than it is implemented right now in hornet, because you can specify the threshold per range. And it's easier to read.

So the TIP is fine, maybe we should change the format in hornet in an upcoming version.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

iotaledger/hornet#1733

- _Applicable Public Keys_ defining the set of valid public keys.
- _Signature Threshold_ specifying the minimum number of valid signatures. Must be at least one and not greater than the number of _Applicable Public Keys_.

## Milestone ID

The _Milestone ID_ is the BLAKE2b-256 hash of the serialized _Milestone Essence_.
It is important to note that the signatures do not impact the _Milestone ID_.

## Structure

### Serialized Layout

All values are serialized in little-endian encoding. The serialized form of the milestone is deterministic, meaning the same logical milestone always results in the same serialized byte sequence.

The following table describes the entirety of a _Milestone Payload_ in its serialized form following the notation from [TIP-21](../TIP-0021/tip-0021.md):

<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Payload Type</td>
<td>uint32</td>
<td>Set to <strong>value 7</strong> to denote a <i>Milestone Payload</i>.</td>
</tr>
<tr>
<td valign="top">Essence <code>oneOf</code></td>
<td colspan="2">
<details open="true">
<summary>Milestone Essence</summary>
<blockquote>Describes the signed part of a <i>Milestone Payload</i>.</blockquote>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Index Number</td>
<td>uint32</td>
<td>The index number of the milestone.</td>
</tr>
<tr>
<td>Timestamp</td>
<td>uint32</td>
<td>The Unix time (seconds since Unix epoch) at which the milestone was issued.</td>
</tr>
<tr>
<td>Protocol Version</td>
<td>uint8</td>
<td>The protocol version of the Milestone Payload and its block.</td>
</tr>
<tr>
<td>Previous Milestone ID</td>
<td>ByteArray[32]</td>
<td>The Milestone ID of the milestone with <code>Index Number - 1</code>.</td>
</tr>
<tr>
<td>Parents Count</td>
<td>uint8</td>
<td>The number of parents referenced by this milestone.</td>
</tr>
<tr>
<td valign="top">Parents <code>anyOf</code></td>
<td colspan="2">
<details>
<summary>Parent</summary>
<blockquote>A block that is directly referenced by this milestone.</blockquote>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Block ID</td>
<td>ByteArray[32]</td>
<td>The Block ID of the parent.</td>
</tr>
</table>
</details>
</td>
</tr>
<tr>
<td>Inclusion Merkle Root</td>
<td>ByteArray[32]</td>
<td>The Merkle tree hash (BLAKE2b-256) of the Block IDs of all blocks included by this milestone.</td>
<tr>
<td>Applied Merkle Root</td>
<td>ByteArray[32]</td>
<td>The Merkle tree hash (BLAKE2b-256) of the Block IDs of all blocks applied by this milestone that contain a state-mutating transaction (see <a href="../TIP-0004/tip-0004.md">TIP-4</a>).</td>
</tr>
<tr>
<td>Metadata</td>
Wollac marked this conversation as resolved.
Show resolved Hide resolved
<td>(uint16)ByteArray</td>
<td>Binary data only relevant to the milestone issuer, e.g. internal state. A leading uint16 denotes its length.</td>
</tr>
<tr>
<td>Options Count</td>
<td>uint8</td>
<td>The number of milestone options following.</td>
</tr>
<tr>
<td valign="top">Options <code>atMostOneOfEach</code></td>
<td colspan="2">
<details>
<summary>Receipts Milestone Option</summary>
<blockquote>Defines UTXOs for newly migrated funds.</blockquote>
</details>
<details>
<summary>Protocol Parameters Milestone Option</summary>
<blockquote>Defines dynamic changes to the protocol parameters.</blockquote>
</details>
</td>
</tr>
</table>
</details>
</td>
</tr>
<tr>
<td>Signatures Count</td>
<td>uint8</td>
<td>The number of signature entries following.</td>
</tr>
<tr>
<td valign="top">Signatures <code>anyOf</code></td>
<td colspan="2">
<details open="true">
<summary>Ed25519 Signature</summary>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Signature Type</td>
<td>uint8</td>
<td>
Set to <strong>value 0</strong> to denote an <i>Ed25519 Signature</i>.
</td>
</tr>
<tr>
<td>Public Key</td>
<td>ByteArray[32]</td>
<td>The Ed25519 public key of the signature.</td>
</tr>
<tr>
<td>Signature</td>
<td>ByteArray[64]</td>
<td>The Ed25519 signature signing the BLAKE2b-256 hash of the serialized <i>Milestone Essence</i>.</td>
</tr>
</table>
</details>
</td>
</tr>
</table>

### Milestone options

The `Options` field holds additional data authenticated by the milestone.

The following table lists all the `Milestone Option Type` that are currently supported as well as links to the corresponding specification:

| Payload Name | Type Value | TIP |
|---------------------|------------|-------------------------------------------------------------|
| Receipt | 0 | [TIP-34](../TIP-0034/tip-0034.md#receipt-milestone-option) |
| Protocol Parameters | 1 | [TIP-29](#protocol-parameters-milestone-option) |

#### Protocol Parameters Milestone Option

This `Milestone Option` is used to signal to nodes the commencing of new protocol parameters, including new protocol
version or PoW difficulty.

<details>
<summary>Protocol Parameters Milestone Option</summary>
<blockquote>
Defines changing protocol parameters.
</blockquote>
</details>

<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td>Milestone Option Type</td>
<td>uint8</td>
<td>Set to <strong>value 1</strong> to denote a <i>Protocol Parameters Milestone Option</i>.</td>
</tr>
<tr>
<td>Target Milestone Index</td>
<td>uint32</td>
<td>The milestone index at which these protocol parameters become active.</td>
</tr>
<tr>
<td>Protocol Version</td>
<td>uint8</td>
<td>The to be applied protocol version.</td>
</tr>
<tr>
<td>Parameters</td>
<td>(uint16)ByteArray</td>
<td>The protocol parameters in binary, serialized form.</td>
</tr>
</table>

##### Syntactic Validation
- `Target Milestone Index` must be greater than `Index Number` of the milestone it is contained in.
- `Target Milestone Index` must be less than or equal to `Index Number` + 30. (This value is fixed and technically not a protocol parameter as defined in [TIP-22](../TIP-0022/tip-0022.md), as it should not be subject to protocol parameter changes induced by this option.)
- `length(Parameters)` must not exceed `Max Metadata Length`.

## Milestone Validation

Similar to transaction validation, milestone validation has been separated into two classes. For a milestone to be valid, both of them need to be true.

### Syntactic validation

Syntactic validation can be checked from the _Milestone Essence_ plus the blocks in the past cone referenced by it.

- Essence:
- `Index Number` must not be smaller than `First Milestone Index`.
- If `Index Number` equals `First Milestone Index`, the following fields must be zeroed out:
- `Previous Milestone ID`
- `Inlcusion Merkle Root`
lzpap marked this conversation as resolved.
Show resolved Hide resolved
- `Applied Merkle Root`
- If `Index Number` is greater than `First Milestone Index`, the milestone must reference (i.e. one of the `Parents` must contain or reference) another syntactically valid milestone whose _Milestone ID_ matches `Previous Milestone ID`. With respect to that referenced milestone, the following must hold:
- `Index Number` must increment by `1`.
- `Timestamp` must be strictly larger (i.e. at least one second later).
- `Inlcusion Merkle Root` must match the Merkle tree hash of the IDs of all blocks in _White Flag Ordering_ (as described in <a href="../TIP-0002/tip-0002.md#deterministically-ordering-the-tangle">TIP-2</a>) that are newly referenced. (This always includes at least one valid milestone block with `Previous Milestone ID`.)
- `Applied Merkle Root` must match the Merkle tree hash of the not-ignored state-mutating transactions that are newly referenced (see <a href="../TIP-0002/tip-0002.md">TIP-2</a>).
- `Parents` must match the `Parents` field of the encapsulating _Block_, i.e. the _Block_ that contains the _Milestone Payload_.
- `length(Metadata)` must not exceed `Max Metadata Length`.
- Options:
- `Milestone Option Type` must match one of the values described under [Milestone Options](#milestone-options).
- The option itself must pass syntactic validation.
- The options must be sorted in ascending order based on their `Milestone Option Type`.
- Signatures:
- `Signatures Count` must be at least the _Signature Threshold_ and at most the number of _Applicable Public Keys_ for the current milestone index.
- For each signature block the following must be true:
- `Signature Type` value must denote an `Ed25519 Signature`.
- `Public Key` must be contained in _Applicable Public Keys_ for the current milestone index.
- `Signature` must contain a valid signature for `Public Key`.
- The signature blocks must be sorted with respect to their `Public Key` in lexicographical order.
- Each `Public Key` must be unique.
- Given the type and length information, the _Milestone Payload_ must consume the entire byte array of the `Payload` field of the _Block_.

### Semantic validation

Semantic validation is defined in the context of all available blocks.

- The milestone chain must not fork, i.e. there must not be two different, syntactically valid milestones with the same `Index Number`. In case of a fork, the correct state of the ledger cannot be derived from the milestones alone and usually the node implementation should alert the user and halt.

# Rationale

- Due to the layered design of blocks and payloads, it is practically not possible to prevent reattachments of _Milestone Payloads_. Hence, this payload has been designed in a way to be independent from the block it is contained in. A milestone should be considered as a virtual marker (referencing `Parents`) rather than an actual block in the Tangle. This concept is compatible with reattachments and supports a cleaner separation of the block layers.
- Forcing matching `Parents` in the _Milestone Payload_ and its block makes it impossible to reattach the same payload at different positions in the Tangle. Strictly speaking, this violates the separation of payload and block. However, it simplifies milestone processing as the position of the block will be the same as the position encoded in the Milestone Payload. Having these clear structural properties seems to be more desirable than a strict separation of layers.
- While it is always possible to cryptographically prove that a block was confirmed by a given milestone by supplying all the blocks of a path from the milestone to the block, such a proof can become rather large (depending on the blocks). To simplify such proof-of-inclusions, the `Inlcusion Merkle Root` of all the included blocks has been added.
lzpap marked this conversation as resolved.
Show resolved Hide resolved

# Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).