---
# System prepended metadata

title: Hierarchical Consensus FIP
tags: [B, HC, B3, Spec]

---

Hierarchical Consensus FIP
===
###### tags: `HC`, `B`, `B3`, `Spec`

## Introducing Hierarchical Consensus

## Simple Summary
To increase the range of use cases that the Filecion network can support, and to overcome future scalability limitations in terms of throughput and finality of the Filecoin blockchain, this FIP introduces Hierarchical Consensus (HC), a framework to scale Filecoin horizontally.

HC enables Filecoin users to spawn new subnets from the Filecoin network. Subnets instantiate new independent state and are able to run their own consensus algorithm. Subnets interact seamlessly with the Filecoin mainnet while parallelizing the validation (and execution) of messages. Our framework enables application developers to host their applications in networks with the appropriate security-performance trade-off.

This FIP introduces:
- The architecture of Hierarchical Consensus, and how it integrates with the Filecoin network.
- A new `Consensus` interface that decouples the specific consensus implementation used for the different networks, and allows the Filecoin stack to interact and use any consensus implementation that follows the interface. This interface is shared by all HC-compatible subnets and consensus algorithms.
- A new built-in actor, the `Subnet Coordinator Actor (SCA)`, which implements the core logic of HC and governs the interaction of subnets with other networks in the hierarchy.
- A new type of address, the hierarchical address, which attaches subnet information to raw Filecoin addresses.
- The mechanics to spawn new subnets and to propagate and execute cross-net messages.
- A new subnet content resolution protocol to resolve objects behind a `CID` stored in the state of other subnets.

We foresee proposing future FIPs for HC-related topics, including its gas and cryptoeconomic model.

## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->

Consensus poses a major scalability bottleneck in blockchain networks. This is particularly the case when all validators are required to process all transactions, as is the case for Filecoin, which renders the network unable to increase its performance by adding more participants (scale-out). Even more, not every application benefits from using the same consensus algorithm: different applications may have different performance and security requriements, making it difficult for a single blockchain network with a single consensus layer to accommodate any type of web3 application. 

With __Hierarchical Consensus (HC)__, we implement a framework to enable on-demand horizontal scalability of Filecoin through the deployment of subnets (self-governing chains) that spawn their own state, validate messages in parallel, and seamlessly interact with any network in the hierarchy, as well as the Filecoin mainnet. Subnets can run different consensus algorithms, adjusting to the needs of the application.

This FIP introduces the architecture and essential building blocks for the operation of the protocol. It can be seen as complementary to the programmability introduced by FVM, in that it provides a framework to further program the Filecoin network, accommodating a wide variety of use cases while overcoming potential consensus bottlenecks.


## Change Motivation
With the release of FVM, we should expect additional load and more diverse use cases in the Filecoin network. These use cases may push the Filecoin network's throughput to the limit. Even more, some use cases may not be compatible with the current block finality times of the Filecoin consensus. Providing a way to horizontally scale the Filecoin network while letting users determine the security-performance trade-off they want for their application can attract innovative use cases to the network.

This framework not only unlocks unlimited scalability for the Filecoin network through the on-demand horizontal scaling of the network, but it also provides additional benefits:
- It allows for _market-tunable_ applications, as developers can configure the blockchain substrate to the needs of their application while still being able to interoperate with the root network and other networks in the system.
- HC enables the deployment of use cases with fast local finality, as users can deploy their application in a specific subnet with a consensus engine with fast (and configurable) finality while leveraging the native storage and security of the Filecoin mainnet and the _global finality_ of the root network. 
- The architecture of HC builds the foundation for a partition-tolerant blockchain substrate. Subnets are able to operate on their own without a permanent connection to the rest of the hierarchy and can propagate required changes when connectivity resumes.
- It increases the modularity and flexibility of the blockchain substrate. Users can deploy compute-specific or payment-channel-specific subnets, or subnets that host new and interoperable storage markets. The Filecoin community could also choose to deploy a specific subnet used to commit control messages (PoST, etc.) without being affected by the user-defined load.
-  It offers the foundation for the deployment of a gamut of interoperable decentralized services over the Filecoin network. 
- It fosters innovation on new consensus engines. Researchers and developers can design and implement new consensus algorithms and deploy them in a real-world environment as an HC subnet.

## Specification
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Filecoin implementations. -->
The spec for HC has been drafted [here](https://github.com/protocol/ConsensusLab/blob/main/specs/hierarchical_consensus.md). Instead of copy-pasting the spec in this discussion, we refer to [the link](https://github.com/protocol/ConsensusLab/blob/main/specs/hierarchical_consensus.md) for the spec of the proposed changes for the FIP. The sections in bold are more closely attached to the current Filecoin consensus and should warrant more care. A brief explanation of the reasoning is included below the link. We'll follow the feedback of this discussion but if you want to give feedback or propose a change over the spec feel free to directly open a PR in the aforementioned repo. 

-   [Architecture](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Architecture "Architecture")
-   [Subnet Actor (SA)](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Subnet-Actor-SA "Subnet Actor (SA)")
-   [__Subnet Coordinator Actor (SCA)__](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Subnet-Coordinator-Actor-SCA "Subnet Coordinator Actor (SCA)")
    - _Includes a new builtin-actor into the builtin-actors bundle._
-   [__Consensus Interface__](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Consensus-Interface "Consensus Interface")
    - _Decouples a consensus interface from the main consensus to be shared by every consensus implementation. It is an implementation detail and it shouldn't change anything in the Filecion protocol._
-   [Spawning and joining a subnet](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Spawning-and-joining-a-subnet "Spawning and joining a subnet")
-   [Leaving and killing a subnet](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Leaving-and-killing-a-subnet "Leaving and killing a subnet")
-   [Handling the state of killed subnets](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Handling-the-state-of-killed-subnets "Handling the state of killed subnets")
-   [Naming](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Naming "Naming")
-   [SubnetID](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#SubnetID "SubnetID")
-   [__Hierarchical Address__](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Hierarchical-Address "Hierarchical Address")
    - _Introduces a new type of address to the Filecoin network. This change is backward-compatible._
-   [Checkpointing](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Checkpointing "Checkpointing")
-   [Checkpoint Commitment](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Checkpoint-Commitment "Checkpoint Commitment")
-   [Checkpoints data structure](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Checkpoints-data-structure "Checkpoints data structure")
-   [Cross-net messages](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Cross-net-messages "Cross-net messages")
-   [Cross-message pool](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Cross-message-pool "Cross-message pool")
-   [__Cross-message execution__](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Cross-message-execution "Cross-message execution")
    - _Includes an alternative way to execute messages in the network when they originated in some other subnet_
-   [Top-down messages](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Top-down-messages "Top-down messages")
-   [Bottom-up messages](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Bottom-up-messages "Bottom-up messages")
-   [Path messages](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Path-messages "Path messages")
-   [__Minting and burning native tokens in subnets__](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Minting-and-burning-native-tokens-in-subnets "Minting and burning native tokens in subnets")
    - _Adds a new `SubnetMint` method in the `RewardActor` to mint new native tokens (FIL) into subnets after a top-down message. We can use a custom builtin-actors bundle in subnets to avoid including this method in the `RewardActor` of the root network._
-   [Subnet Content Resolution Protocol](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Subnet-Content-Resolution-Protocol "Subnet Content Resolution Protocol")
-   [Resolution approaches](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Resolution-approaches "Resolution approaches")
-   [Data availability](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Data-availability "Data availability")
-   [Atomic Execution Protocol](https://github.com/protocol/ConsensusLab/blob/hc/spec/specs/hierarchical_consensus.md#Atomic-Execution-Protocol "Atomic Execution Protocol")

## Design Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->

In traditional distributed computing, one possible approach to overcoming scalability limitations is to resort to the partitioning, or sharding, of state processing and transaction ordering (like other projects in the space are doing). In a sharded system, the blockchain stack is divided into different groups called shards, each operated by its own set of nodes, which keep a subset of the state and are responsible for processing a part of the transactions sent to the system. 

The main challenge with applying traditional sharding to the Byzantine fault-tolerant context of the blockchain lies in the security/performance trade-off. As miners are assigned to shards, there is a danger of diluting security when compared to the original single-chain (single-shard) solution. In both proof-of-work and proof-of-stake (PoS) blockchains, sharding may give the attacker the ability to compromise a single shard with only a  fraction of the mining power, potentially compromising the system as a whole. Such attacks are often referred to as _1\% attacks_. To circumvent them, sharding systems need to periodically reassign miners to shards in an unpredictable way, so as to cope with a semi-dynamic adversary. We believe that this traditional approach to scaling, which considers the system as a monolith, is not suitable for decentralized blockchains due to their complexity and the fact that sharded systems reshuffle state without the consent of its owners, disrupting use cases that benefit from finer control over the system topology.

With __Hierarchical Consensus__, we depart from the traditional sharding approach and, instead of algorithmically assigning node membership and load balancing the distribution of the state, we follow an approach where users and miners are grouped into subnets in which they can freely partake. Users (i.e. network participants) can spawn new blockchain networks, or child subnets, from the one they are operating in, according to their needs and become miners there if they fulfill all the requirements set by the protocol. __Each subnet can run its own independent consensus algorithm and set its own security and performance guarantees.__ Subnets in the system are organized hierarchically: each has one parent subnet and any number of child subnets, except for the root subnet (called _root network_ or _rootnet_), which has no parent and is the initial anchor of trust. To circumvent the 1\% attacks pertinent to traditional sharding, subnets in hierarchical consensus are firewalled, in the sense that a security violation in a given subnet is limited, in effect, to that particular subnet and its children, with bounded economic impact on its ancestors. This bounded impact of an attack is, at most, the circulating supply of the parent token in the child subnet. Moreover, ancestor subnets help secure their descendant subnets through _checkpointing_, which helps alleviate attacks on a child subnet, such as long-range and related attacks in the case of a PoS-based subnet.

Scalability proposals explored by other projects and used to inspire this work include:

- Sharding
    - [A Secure Sharding Protocol For Open Blockchains](https://dl.acm.org/doi/10.1145/2976749.2978389)
    - [OmniLedger: A Secure, Scale-Out, Decentralized Ledger via Sharding](https://ieeexplore.ieee.org/abstract/document/8418625?casa_token=rR_VwAt63GoAAAAA:-5YS9Py1s7FWOCPEQScCC2hJNksGe4Qh0s1zd0EqhQUIdHA4yngqwUzdD1YWZ6hKWwaqI6eh2Q)
    - [Dankrad Sharding](https://notes.ethereum.org/@dankrad/new_sharding)
    - [Shard Scheduler: object placement and migration in sharded account-based blockchains](https://arxiv.org/abs/2107.07297)
- Payment channels
- L2 Rollups
    - [Fractal scaling](https://hackmd.io/@kalmanlajko/rkgg9GLG5#Liquid-consensus)
- Side-chains
    - [Proof-of-stake sidechains](https://ieeexplore.ieee.org/abstract/document/8835275)

> More references will be included here as we get additional pointers and work related to this protocol.

## Backwards Compatibility
<!--All FIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The FIP must explain how the author proposes to deal with these incompatibilities. FIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
All the changes in this FIP are incremental. There shouldn't be any issues of backward compatibility.

## Test Cases
<!--Test cases for an implementation are mandatory for FIPs that are affecting consensus changes. Other FIPs can choose to include links to test cases if applicable.-->
> WIP

## Security Considerations
<!--All FIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. FIP submissions missing the "Security Considerations" section will be rejected. A FIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.-->
> WIP

## Incentive Considerations
<!--All FIPs must contain a section that discusses the incentive implications/considerations relative to the proposed change. Include information that might be important for incentive discussion. A discussion on how the proposed change will incentivize reliable and useful storage is required. FIP submissions missing the "Incentive Considerations" section will be rejected. An FIP cannot proceed to status "Final" without a Incentive Considerations discussion deemed sufficient by the reviewers.-->

This FIP will greatly increase the capacity of the Filecoin network, by enabling the spawning of subnets, as well as message execution within these subnets. This can simultaneously result in a large increase to the overall transaction volume and in a decrease of utilisation of the main chain, thereby potentially impacting the base fee. Moreover, collateral used to secure the subnets will impact the FIL circulating supply. 

Note, however, that all subnets are required to checkpoint on their parents and that cross-net transactions will also traverse the network hierarchy, thereby maintaining coupling and generating activity on the root network.

Work on cryptoeconomic modelling for subnets is currently ongoing, and incentive considerations related thereto will be introduced in an additional FIP. The relevant parts of the spec are:
-   [Collateral and slashing](https://hackmd.io/Gwb6IgFjQByzBFLq8iq9mQ?both#Collateral-and-slashing "Collateral and slashing")
-   [Detectable misbehaviors](https://hackmd.io/Gwb6IgFjQByzBFLq8iq9mQ?both#Detectable-misbehaviors "Detectable misbehaviors")
-   [Cross-net routing gas price](https://hackmd.io/Gwb6IgFjQByzBFLq8iq9mQ?both#Cross-net-routing-gas-price "Cross-net routing gas price")

## Product Considerations
<!--All FIPs must contain a section that discusses the product implications/considerations relative to the proposed change. Include information that might be important for product discussion. A discussion on how the proposed change will enable better storage-related goods and services to be developed on Filecoin. FIP submissions missing the "Product Considerations" section will be rejected. An FIP cannot proceed to status "Final" without a Product Considerations discussion deemed sufficient by the reviewers.-->
As described in the [Change Motivation](#Change-Motivation) section, HC offers newfound flexibility and the potential of unlimited scalability for the Filecoin network. This will foster innovation at the consensus layer and beyond, and it may attract brand new and existing use cases to the network.

This change also opens the door to deeper innovation in the blockchain space (like the support for partitioned networks, the complex routing of messages between networks, the deployment of use-case-specific network interoperable _"by-design"_ with existing ones, etc.).

It is impossible to foresee all future uses of HC, but we will monitor its usage once it becomes part of the network, in order to prioritize work on future evolutions of the protocol. 

## Implementation
<!--The implementations must be completed before any core FIP is given status "Final", but it need not be completed before the FIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
A reference implementation of the HC over a Lotus fork using the Legacy VM (including the SCA and a reference subnet actor implementation as specs-actors) can be found in this repo: https://github.com/filecoin-project/eudico/
- [Code with all the peer-specific implementation of HC](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus/hierarchical)
- [HC actors target the `LegacyMV`](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus/hierarchical/actors)
- [HC-compatible consensus implementations](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus)
- [Subnet manager and subnet-specific processes](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus/hierarchical/subnet)
- [Subnet content-resolution protocol](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus/hierarchical/subnet/resolver)
- [Atomic execution protocol primitives](https://github.com/filecoin-project/eudico/tree/eudico/chain/consensus/hierarchical/atomic)

An MVP to test the compatibility of the HC framework targeting FVM can be found in the following forks (these forks may not be feature complete; we are targeting feature completeness for FVM-M2. With the recent updates in all FVM-related repos, these forks may be temporarily broken. We'll fix them and post them in the final FIP submission):
- Modified builtin-actors: https://github.com/adlrocha/builtin-actors
- ref-fvm including f04 adresss: https://github.com/adlrocha/ref-fvm
- Subnet actor reference implementation: https://github.com/adlrocha/hc-subnet-actor
- Branch of Eudico for testing FVM-M2: https://github.com/filecoin-project/eudico/tree/experimental/fvm-m2

And we are working on an implementation of HC over a fork of Forest (some of the changes and refactors are also being upstreamed for `ChainSafe/forest`): https://github.com/aakoshh/forest/

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