IOTA Improvement Proposal (IIP) Repository

IIPs are improvement proposals for bettering the IOTA technology stack.

Building the IOTA ecosystem is a community effort, therefore we welcome anyone to propose, discuss and debate ideas that will later become formalized IIPs.

Propose new ideas

Do you have an idea how to improve the IOTA technology stack?

• Head over to the discussions page to browse already submitted ideas or share yours!
• Once your idea is discussed, you can submit a draft IIP (template here as a PR to the repository.
• You will receive feedback from the IIP Editors, core devs and community members to refine your proposal.
• Once accepted, your IIP is merged as Draft.
• It is your responsibility to drive its implementation and to present a clear plan on how the new feature will be adopted by the network.
• Once implementation is ready and testing yields satisfactory result, the IIP becomes Proposed.
• Proposed IIPs that are supported by majority of the network become Active.

You may find more information about the IIP Process in IIP-1.

List of IIPs

• Last updated: 2025-04-18
• The Status of a IIP reflects its current state with respect to its progression to being supported on the IOTA Mainnet.
  • Draft IIPs are work in progress. They may or may not have a working implementation on a testnet.
  • Proposed IIPs are demonstrated to have a working implementation on the IOTA Devnet or Testnet.
  • Active IIPs are supported on the IOTA Mainnet.
  • Replaced IIPs have been replaced by a newer IIP.
  • Obsolete IIPs are no longer in use.

Need help?

If you want to get involved in the community, need help getting started, have any issues related to the repository or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our IOTA Builder Discord.

iip: 1
title: IIP Process
description:  Purpose and guidelines of the contribution framework
author: Levente Pap (@lzpap) 
discussions-to: https://github.com/iotaledger/iips/discussions
status: Active
type: Process
created: 2025-02-12

Abstract

An IOTA Improvement Proposal (IIP) is a design document providing information to the IOTA community, or describing a new feature for IOTA or its processes or environment. The IIP should provide a high level technical design or specification and the rationale of the feature.

IIPs are the primary mechanism for proposing new features and standards to the IOTA protocol and related applications, furthermore for collecting input from the wider community and documenting the design decisions that go into the IOTA technology.

IIPs are maintained as text files inside the repository, therefore the history and evolution of protocol features are transparent and well documented.

This IIP defines the IIP Process itself to establish a common way of working.

Motivation

The motivation of this IIP is to create a public platform to discuss improvement ideas related to the IOTA technology and define an easy-to-follow process of contributing to their development and implementation.

Design / Specification

IIP Types

There are 3 types of IIPs:

• A Standards Track IIP describes any change that affects most or all IOTA node implementations, such as a change to the network protocol, a change in transaction validity rules, or any change or addition that affects the interoperability of applications using IOTA. Standards Track IIPs consist of two parts, a design document and a reference implementation. Standards Track IIPs can be broken down into following layers:
  1. Core: Changes or additions to core features of IOTA, including consensus, execution, storage, and account signatures
  2. Networking: Changes or additions to IOTA's mempool or network protocols
  3. Interface: Changes or additions to RPC or API specifications or lower-level naming conventions
  4. Framework: Changes or additions to IOTA Move contracts and primitives included within the codebase, such as within the IOTA Framework
  5. Application: Proposals of new IOTA Move standards or primitives that would not be included within the IOTA codebase but are of significant interest to the developer community
• An Informational IIP describes an IOTA design issue, or provides general guidelines or information to the IOTA community, but does not propose a new feature. Informational IIPs do not necessarily represent an IOTA community consensus or recommendation, so users and implementors are free to ignore Informational IIPs or follow their advice.
• A Process IIP describes a process surrounding IOTA, or proposes a change to (or an event in) a process. Process IIPs are like Standards Track IIPs but apply to areas other than the IOTA protocol itself. They may propose an implementation, but not to IOTA's codebase; they often require community consensus; unlike Informational IIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in IOTA development.

It is highly recommended that an IIP outlines a single key proposal, idea or feature; the narrower the scope of the IIP is, the easier it becomes to reach consensus on the proposed feature and incorporate it into the protocol. Several IIPs can form a bundle of changes when linked to each other.

IIP Format and Structure

IIPs must adhere to the format and structure requirements that are outlined in this document. A IIP is written in Markdown format and should have the following parts (optional parts are marked with a *):

IIP Template

The template to follow for new IIPs is located in the repository.

IIP Process

Parties involved in the process are:

• IIP author: you, the champion who proposes a new IIP. It is the responsibility of the IIP author to drive the progression of the IIP to Active status. This includes initiating public discussion and implementing the proposal as well.
• IIP editor: they deal with administering the IIP process and ensure process requirements are fulfilled.
• Core contributors: technical experts of IOTA who evaluate new IIPs, provide feedback and ensure that only sound and secure features are added to the protocol.

IIP Statuses

The status of the IIP describes its current stage in the IIP process.

IIP Workflow

How are new proposal get added to the protocol?

1. All IIPs begin life as an Idea proposed in the public IOTA discussion forum, that is the GitHub Discussion page of the IIP repository. A public, open discussion should predate any formal IIP submission. If you want to propel your proposal to acceptance, you should make sure to build consensus and support in the community around your proposed changes already in the idea stage.

2. Once the idea has been vetted, your next task is to submit a Draft IIP to the IIP repository as a pull request. Do not assign a IIP number yet to the draft, but make sure that the proposal is technically sound and follows the format and style guides of the IIP Process. Create a sub-folder under iips folder with the title of the draft (iips/title_of_draft/) and put all assets in this folder.

3. A IIP editor reviews your PR and assigns a IIP number to the draft.

4. Core contributors as well as the broader public evaluate the draft proposal and might ask for modifications or clarifications. The proposal can only be merged into the repository as a draft if it represents a net improvement and does not complicate the protocol unduly.

5. The IIP is merged into the repo with Draft status by IIP editor/author.

6. When a working implementation is presented and there are clear plans on how to progress the IIP to completion, the IIP author submits a subsequent PR that links its implementation to the IIP and progresses it to Proposed stage. The IIP is ready to be deployed on testnet.

7. When a Proposed IIP is deemed to have met all appropriate criteria and its implementation has been demonstrated to work reliably in testnet environment, it is ready to be moved to the main network. Upon deployment, the IIP status must change to Active.

How can a IIP transition from one status to another?

A Draft IIP might be moved to Deferred status by the IIP author(s) when they are no longer working on the proposal, but plan to continue it in the future. IIP editors might also move any IIPs to Deferred if the proposal is not making progress.

A Draft IIP might be moved to Withdrawn status by the IIP author(s).

A Draft IIP might be moved to Rejected status by IIP editor(s) or Core contributors if it does not meet the appropriate IIP criteria, or no relevant progress has been demonstrated on the IIP for at least 3 years.

A Draft IIP might be moved to Proposed status by IIP author(s) if it is considered complete, has a working implementation and clear plans on how to progress it to Active status.

A Proposed IIP might be moved to Active status if a IIP specific adoption criteria has been met. For Core IIPs this means deployment on the main network.

A Proposed IIP might be moved to Rejected status by IIP editor(s) or Core contributors if its implementation puts unduly burden and complexity on the protocol, or other significant problems are discovered during testing.

An Active IIP might be moved to Replaced status by a newer IIP. The replaced IIP must point to the IIP that replaces it.

An Active IIP might be moved to Obsolete status when the feature is deprecated.

How to champion the IIP Process as a IIP author?

• Browse the idea discussion forum before posting a new IIP idea. Someone else might already have proposed your idea, or a similar one. Take inspiration from previous ideas and discussions.
• It is your responsibility as a IIP author to build community consensus around your idea. Involve as many people in the discussion as you can. Use social media platforms, Discord or Reddit to raise awareness of your idea.
• Submit a draft IIP as a PR to the IIP repository. Put extra care into following IIP guidelines and formats. IIPs must contain a link to previous discussions on the topic, otherwise your submissions might be rejected. IIPs that do not present convincing motivation, demonstrate lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly-received.
• Your draft IIP gets a IIP number assigned by a IIP editor and receives review and feedback from the larger community as well as from Core contributors. Be prepared to revise your draft based on this input.
• IIPs that have broad support are much more likely to make progress than those that don't receive any comments. Feel free to reach out to the IIP editors in particular to get help to identify stakeholders and obstacles.
• Submitted draft IIPs rarely go through the process unchanged, especially as alternatives and drawbacks are shown. You can make edits, big and small, to the draft IIP to clarify or change the design, but make changes as new commits to the pull request, and leave a comment on the pull request explaining your changes. Specifically, do not squash or rebase commits after they are visible on the pull request.
• When your draft IIP PR gets enough approvals from IIP editors and Core contributors, it can be merged into the repository, however, your job is far from complete! To move the draft into the next status (proposed), you have to demonstrate a working implementation of your IIP. For Core IIPs, seek help from protocol developers and/or client teams to coordinate the feature implementation. For IRCs for example you need to provide their implementation yourself.
• You also need to present a clear plan on how the IIP will be moved to the Active status, by for example agreeing on a IIP deployment strategy with Core contributors.
• To move your Draft IIP to the Proposed phase, submit a subsequent PR that links its implementation and devises its route to become Active. The latter might be an additional document in the IIP's folder, a link to a public discussion or a short description or comment on the PR itself.
• To move your Proposed IIP to Active status you need to demonstrate that it has met its specific adoption criteria. For Core IIPs, this means that majority of network nodes support it. For other IIPs, especially for IRCs, adoption might mean that the standard is publicly available, well documented and there are applications building on it.

IIP Header Preamble

Each IIPs must have an RFC 822 style header preamble preceded and followed by three hyphens (---). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.

Linking IIPs

References to other IIPs should follow the format IIP-N where N is the IIP number you are referring to. Each IIP that is referenced in an IIP MUST be accompanied by a relative Markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in this GitHub repository or forks of this repository. For example, you would link to this IIP with [IIP-1](../IIP-0001/iip-0001.md).

Auxiliary Files

Images, diagrams and auxiliary files should be included in the subdirectory of the IIP. When linking to an image in the IIP, use relative links such as [IIP Process Diagram](../IIP-0001/process.png).

Linking to external resources

External links should not be included, except to the IOTA repository.

Transferring IIP Ownership

It occasionally becomes necessary to transfer ownership of IIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred IIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the IIP process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the IIP. We try to build consensus around a IIP, but if that's not possible, you can always submit a competing IIP.

If you are interested in assuming ownership of a IIP, send a message asking to take over, addressed to both the original author and the IIP editors. If the original author doesn't respond to the email in a timely manner, the IIP editors will make a unilateral decision (it's not like such decisions can't be reversed :)).

IIP Editors

IIP Editor Responsibilities

IIP editors' essential role is to assist and guard the process of contributing to the IOTA ecosystem, provide help and directions to community members as well as to external contributors. If you have a question regarding the IIP process, reach out to them, they will point you to the right direction.

They ensure that only quality contributions are added as IIPs, provide support for IIP authors, furthermore monitor that the IIP process is fair, objective and well documented.

For each new IIP that comes in, an editor does the following:

• Read the IIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to Active status.
• The title should accurately describe the content.
• Check the IIP for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style.

If the IIP isn't ready, the editor will send it back to the author for revision, with specific instructions.

Once the IIP is ready to be merged as a draft, the editor will:

• Assign a IIP number that does not conflict with other IIP numbers. It might be the PR number, but might also be selected as the next unused IIP number in line.
• Merge the corresponding pull request.
• Send a message back to the IIP author with the next step.

The editors don't pass judgment on IIPs. We merely do the administrative & editorial part.

Core Contributors

Core contributors consists of several core developers of the IOTA ecosystem. Their job is to evaluate technical details of IIPs, judge their technical feasibility and safeguard the evolution of the protocol. Core improvement ideas must be carefully thought through and their benefits must outweigh their drawbacks.

In order for a draft IIP to be accepted into the repo, it must be signed-off by Core contributors. It is also this group that gives the green light for drafts to become proposed or active.

Rationale

The IIP process is intended to replace the formerly adopted Tangle Improvement Proposal (TIP) process due the underlying technological shift.

TIPs refer to the previous generation of IOTA technology and hence are outdated. In order not to confuse contributors, IIP is introduced as a new process to propose, discuss and implement new ideas for the IOTA technology stack.

In order not to reinvent the wheel, the IIP Process draws heavily on the BIP and EIP processes.

Backwards Compatibility

• The current iotaledger/tips repository will be archived.
• All TIPs become Obsolete and are no longer in use.

References

• BIP-1 and BIP-2, Bitcoin Improvement Proposal Purpose and Guidelines
• EIP-1, Ethereum Improvement Proposal Purpose and Guidelines
• CIP-1, Cardano Improvement Proposal Process

Copyright

Copyright and related rights waived via CC0.

iip: 2
title: Starfish Consensus Protocol
description: A DAG-based consensus protocol improving liveness and efficiency
author: Nikita Polianskii (@polinikita) 
discussions-to: https://github.com/iotaledger/IIPs/discussions/10
status: Draft
type: Standards Track
layer: Core
created: 2025-04-16
requires: None

Abstract

This IIP proposes Starfish, a DAG-based consensus protocol enhancing Mysticeti. Starfish decouples block headers from transaction data, enabling push-based header dissemination, and encodes transaction data into Reed-Solomon shards for efficient reconstruction. These mechanisms improve liveness, reduce communication complexity to linear, and lower storage overhead, even in Byzantine environments.

Motivation

Starfish addresses three limitations in Mysticeti:

Liveness. Because of Byzantine behaviour, slow or deadlocked network connection and/or slow computational capability, some validators, hereafter called slow validators, can share its own block to only a few selected peers in time. Blocks that reference blocks of slow validators can stay suspended in the block managers for a long time depending on the depth of the missing causal history. In Mysticeti, the blocks of the recent DAG are fetched by explicit requesting the missing parents of a given suspended block. This slow synchronization of the recent DAG can trigger liveness issues in Mysticeti. Starfish allows for faster synchronization of the recent DAG.

Communication complexity. For n=3f+1, we can observe in the network with f slow validators situations when each block of a slow validator, while being disseminated to f not-slow validators, will be requested from these validators by other validators. This may lead to impractical quadratic communication complexity O(n^2). Starfish keeps the communication complexity linear for all circumstances by using Reed-Solomon codes and using shards in dissemination of other blocks.

Storage overhead. Now each validator store the whole transaction data associated with a block. With Starfish, we can store block headers with only one shard of transaction data, reducing the size of the consensus database.

Specification

Starfish requires implementation of a new crate as it contains many new components in consensus and modifies existing modules. Below, we sum up the most important changes compared to the current version of Mysticeti:

• Block Structure:
  • Separation of Header and Data: Blocks are split into headers (containing metadata) and body optionally containing transaction data or shard. Only headers are signed, and the block digest is calculated solely from the header.
  • Data Commitment: Blocks include a Merkle root commitment to encoded transaction data.
  • Data Acknowledgment: Once the transaction data of a block is available by a validator, it should acknowledge that in next block.
  • Sharding with Reed-Solomon Codes: Transaction data is encoded into shards using Reed-Solomon codes, allowing reconstruction from a subset of shards. The commitment could be a Merkle tree on the encoded shards. For own blocks, send full transaction data; for blocks of other validators, send shards together with proofs.
• Encoder/Decoder: block verifier, core and data manager should be equipped by [n,f+1] Reed-Solomon encoders and decoders to a) ensure the correctness of the computed transaction commitment, b) be able to decode the transaction data from locally available shards, c) create new blocks
• Block Verifier: Validates incoming block headers independently. If transaction data is received, verifies its commitment against the header to ensure correctness.
• Data Manager: Handles transaction data retrieval and reconstruction. Requests missing data from the block author first (full data with sharding) or from nodes acknowledging the data (shards). Once reconstructed, data is forwarded to the DagState for storage and future serving.
• Block Creation: Generates blocks with separate headers and transaction data. The data commitment should be computed based on the encoded transaction data by using some commitment scheme that allow for proofs, e.g. Merkle tree. Includes in a block header pending data acknowledgments.
• Dag State: In addition, it should track for which blocks, a validator has transaction data (pending acknowledgments). Another important structure should provide information about who knows which block headers to disseminate only those block headers that are indeed needed.
• Linearizer: Tracks data acknowledgments for past blocks, including only quorum-acknowledged data in new commits.
• Streaming own blocks: Broadcast own blocks with their transaction data and block headers potentially missing by peers.
• Storage: Separates storage for headers and shards and own transaction data. Triggers data storage upon availability to minimize overhead.
• Commit Structure: Includes references to headers traversed by the Linearizer for data acknowledgment collection. Lists data blocks with a quorum of acknowledgments with optional bitmaps of acknowledging nodes to optimize data retrieval.

Starfish can be enabled via protocol parameters.

For theoretical details, see eprint.iacr.org/2025/567.

Rationale

Starfish’s design is driven by the need to enhance Mysticeti’s performance in bad network conditions and/or adversarial environment. Key decisions include:

• Header-Data Decoupling: Since the constructed DAG in Mysticeti is uncertified, the block propogation is one of the key issues. We decouple the header from data in the block structure to ensure that we can push all the required block headers. Only block headers are needed for driving the consensus. The transaction data can be retrieved once sequenced.
• Data Acknowledgments: Since we decouple headers from data, we can't simply sequence the data associated with a block by a vanilla Mysticeti commit rule as it might be unavailable by a majority of the network. Thereby, one needs to include in block headers acknowledgments about transaction data availability for past blocks. In addition, for sequencing transactions one needs to get a quorum of acknowledgments.
• Reed-Solomon Sharding: Chosen for its ability to reconstruct data from any f+1 shards, ensuring linear communication complexity. Reed-Solomon codes are optimal in terms of recoverability and this is a primary reason why we stick with them. In addition, there are libraries (e.g. https://crates.io/crates/reed-solomon-simd) that are very CPU efficient and consume little memory.
• Merkle Tree Commitments: Preferred for their simple proof generation, enabling shard verification without full data.
• Data Manager: To ensure live consensus decisions, it is enough to have available all block headers in the causal history of blocks. Data manager is needed to fetch potentially missing transaction data from peers once it is sequenced and available to a quorum of the network.

Backwards Compatibility

Starfish introduces backwards incompatibilities with Mysticeti consensus crate:

• Block Structure: The new header-data split and sharding are incompatible with Mysticeti’s monolithic blocks.
• Storage: Mysticeti’s full-data storage is replaced by header-shard storage. This storage is not replacable across validators.
• Protocol Logic: Components like block verifier and linearizer require updates, breaking compatibility with Mysticeti’s logic.

Mitigation:

• Use crate iotaledger/iota/crates/starfish and enable Starfish with protocol parameters.
• Test compatibility in a public testnet to ensure node upgrades are seamless.
• Remove iotaledger/iota/consensus at a later point

Test Cases

The new consensus crate will need to be extensively tested. In particular, all exising modules, e.g. block verifier, will require modifications in existing tests. All new modules (e.g. encoder/decoder) will require testing of typical possible scenarios. To ensure that the new consensus serves its purposes, there should be tests mimicking slow validators that fail to properly disseminate their blocks and this behaviour should not affect the liveness of the consensus.

Reference Implementation

A prototype implementation is available at github.com/iotaledger/starfish. It includes:

• A new crate with core Starfish-specific components (tracking who knows which block headers, encoding/decoding, data fetcher, Starfish linearizer sequencer, etc.).
• Modified Mysticeti modules (Block store, Linearizer, Block Verifier).
• Simulation scripts to test latency, throughput and bandwidth efficiency locally and in a geo-distributed network.

This draft aids consensus developers and will be refined for production.

Copyright

Copyright and related rights waived via CC0.