tip: 29
title: Milestone Payload
description: Coordinator issued milestone payload with Ed25519 authentication
author: Angelo Capossele (@capossele) , Wolfgang Welz (@Wollac) 
discussions-to: https://github.com/iotaledger/tips/pull/69
status: Proposed
type: Standards
layer: Core
created: 2022-03-25
replaces: 8


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. It uses Edwards-curve Digital Signature Algorithm (EdDSA) to authenticate the milestones.


In order to integrate the concept of milestones consistently into Tangle blocks, this TIP describes a dedicated payload type for milestones. In this context, the 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.


The BLAKE2b-256 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.

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 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.

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.
  • 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.


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:

Name Type Description
Payload Type uint32 Set to value 7 to denote a Milestone Payload.
Essence oneOf
Milestone Essence
Describes the signed part of a Milestone Payload.
Name Type Description
Index Number uint32 The index number of the milestone.
Timestamp uint32 The Unix time (seconds since Unix epoch) at which the milestone was issued.
Protocol Version uint8 The protocol version of the Milestone Payload and its block.
Previous Milestone ID ByteArray[32] The Milestone ID of the milestone with Index Number - 1.
Parents Count uint8 The number of parents referenced by this milestone.
Parents anyOf
A block that is directly referenced by this milestone.
Name Type Description
Block ID ByteArray[32] The Block ID of the parent.
Inclusion Merkle Root ByteArray[32] The Merkle tree hash (BLAKE2b-256) of the Block IDs of all blocks included by this milestone.
Applied Merkle Root ByteArray[32] The Merkle tree hash (BLAKE2b-256) of the Block IDs of all blocks applied by this milestone that contain a state-mutating transaction┬╣
Metadata (uint16)ByteArray Binary data only relevant to the milestone issuer, e.g. internal state. A leading uint16 denotes its length.
Options Count uint8 The number of milestone options following.
Options atMostOneOfEach
Receipts Milestone Option
Defines UTXOs for newly migrated funds.
Protocol Parameters Milestone Option
Defines dynamic changes to the protocol parameters.
Signatures Count uint8 The number of signature entries following.
Signatures anyOf
Ed25519 Signature
Name Type Description
Signature Type uint8 Set to value 0 to denote an Ed25519 Signature.
Public Key ByteArray[32] The Ed25519 public key of the signature.
Signature ByteArray[64] The Ed25519 signature signing the BLAKE2b-256 hash of the serialized Milestone Essence.

┬╣: See TIP-4.

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 NameType ValueTIP
Protocol Parameters1TIP-29

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.

Protocol Parameters Milestone Option
Defines changing protocol parameters.
Name Type Description
Milestone Option Type uint8 Set to value 1 to denote a Protocol Parameters Milestone Option.
Target Milestone Index uint32 The milestone index at which these protocol parameters become active.
Protocol Version uint8 The to be applied protocol version.
Parameters (uint16)ByteArray The protocol parameters in binary, serialized form.
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, 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
      • Inclusion Merkle Root
      • 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 TIP-2) 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 TIP-2).
    • 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.
      • 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.


  • 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 Inclusion Merkle Root of all the included blocks has been added.


Copyright and related rights waived via CC0.