diff --git a/docs-gitbook/README.md b/docs-gitbook/README.md index 332116efb1..8808b01674 100644 --- a/docs-gitbook/README.md +++ b/docs-gitbook/README.md @@ -1,29 +1,23 @@ # Introduction -With IPC, dApps can reach planetary scale through recursively scalable subnets, sub-second transactions, robust compute workloads, and highly adaptable WebAssembly runtimes tailored to developer requirements. +Inter-Planetary Consensus (IPC) provides **extensible, customizable** blockchain infrastructure through autonomous sidechains — subnets. Each subnet is a **sovereign** blockchain with its own validators, governance, and data. Subnet state is cryptographically anchored through checkpoints that serve as **objective trust anchors**, securing cross-chain messaging and guarding against long-range attacks. Failures are **contained** within individual security boundaries. The architecture is **recursive**: subnets can themselves be extended with lower-level subnets. -## What is IPC? +## What IPC enables -[Interplanetary Consensus (IPC)](https://www.ipc.space/) is a framework that enables on-demand horizontal scalability of networks, by deploying "subnets" running different consensus algorithms depending on the application's requirements. +- **Scalability** — delegate operations to subnets optimized for performance: faster finality, higher throughput, cheaper block space. Subnets can be launched and terminated programmatically to match demand. -Let's break that down. +- **Customizability** — tailor the consensus mechanism, execution environment, fee model, governance, and data availability strategy to the application's requirements. Subnets can be permissioned or permissionless. -### What is horizontal scalability and why is it important for dApps? +- **Interoperability** — native cross-chain communication through protocol-level bridging. Asset deposits, withdrawals, and general message passing across chains, without external bridges. -[Horizontal scalability](https://en.wikipedia.org/wiki/Scalability#Horizontal\_or\_scale\_out) generally refers to the addition of nodes to a system, to increase its performance. For example, adding more nodes to a compute network helps distribute the effort needed to run a single compute task. This reduces cost per task and decreases latency, while improving overall throughput. +- **Autonomy** — subnets operate as sovereign blockchains, owning their data and governance. No centralized sequencers, no posting bulk data to parent chains. Partition-tolerant: subnets keep running when temporarily disconnected. -In web3, horizontal scalability refers to _scaling_ blockchains, for _desired_ performance. More specifically, _scaling_ the ability of a blockchain to process transactions and achieve consensus, across an increasing number of users, at _desired_ latencies and throughput. IPC is one such scaling solution, alongside other popular layer 2 solutions, like [sidechains](https://ethereum.org/en/developers/docs/scaling/sidechains/) and [rollups](https://ethereum.org/en/developers/docs/scaling/#rollups). +- **Objective security** — checkpoint-based objectivity secures against long-range attacks and enables trustless bootstrapping. Risk is contained: failures in one subnet do not propagate to others. -For decentralized applications (dApps), there are several key motivations to adopt scaling - performance, decentralization, security. The challenge is that these factors are known to be conflicting goals. +## Documentation overview -### How does IPC achieve horizontal scalability? - -IPC is a scaling solution intentionally designed to achieve considerable performance, decentralization and security for dApps. - -It achieves scaling through the permission-less spawning of new blockchain sub-systems, which are composed of subnets. - -[Subnets](concepts/subnets/README.md) are organized in a hierarchy, with one parent subnet being able to spawn infinite child subnets. Within a hierarchical subsystem, subnets can seamlessly communicate with each other, reducing the need for cross-chain bridges. - -Subnets also have their own specific consensus algorithms, whilst leveraging security features from parent subnets. This allows dApps to use subnets for hosting sets of applications or to [shard](https://en.wikipedia.org/wiki/Shard\_\(database\_architecture\)) a single application, according to its various cost or performance needs. \ -\ -IPC-powered networks will also be able to dynamically adjust their throughput by spawning and closing temporary subnets as needed. +- [**Protocol**](protocol/README.md) — how the IPC protocol works: core concepts, mechanisms, architecture, workflows, security model. +- [**Getting Started**](quickstarts/deploy-a-subnet.md) — deploy your first subnet. +- [**Guides**](user-guides/performing-transactions-in-a-subnet.md) — transacting in subnets, customizing and upgrading subnets, deploying an explorer. +- [**Specifications**](../specs/addressing.md) — implementation-level specs. +- [**Reference**](reference/networks.md) — networks, CLI usage, glossary, troubleshooting, FAQ. diff --git a/docs-gitbook/SUMMARY.md b/docs-gitbook/SUMMARY.md index 9e4ab6e337..5155aa2743 100644 --- a/docs-gitbook/SUMMARY.md +++ b/docs-gitbook/SUMMARY.md @@ -3,32 +3,30 @@ ## Overview - [Introduction](README.md) -- [How IPC works](overview/how-it-works.md) -- [Use cases](overview/use-cases.md) -- [How IPC compares](overview/how-ipc-compares.md) -- [Architecture](overview/architecture.md) +- [How IPC Compares](overview/how-ipc-compares.md) +- [Use Cases](overview/use-cases.md) -## Quickstarts +## Protocol -- [Deploy a subnet](quickstarts/deploy-a-subnet.md) +- [Protocol Overview](protocol/README.md) +- [Requirements & Guarantees](protocol/requirements-and-guarantees.md) +- [Core Mechanisms](protocol/core-mechanisms.md) +- [Architecture](protocol/architecture.md) +- [Workflows](protocol/workflows.md) +- [Security & Economics](protocol/security-and-economics.md) -## Concepts +## Getting Started -- [Subnets](concepts/subnets/README.md) - - [Parent-child interactions](concepts/subnets/parent-child-interactions.md) -- [Circulating supply](concepts/circulating-supply.md) +- [Deploy a Subnet](quickstarts/deploy-a-subnet.md) -## User guides +## Guides -- [Performing transactions in a subnet](user-guides/performing-transactions-in-a-subnet.md) - -## Developer Guides - -- [Customizing a subnet](developer-guides/pluggable-syscall-tutorial.md) -- [Upgrading a subnet](developer-guides/upgrades/README.md) +- [Performing Transactions in a Subnet](user-guides/performing-transactions-in-a-subnet.md) +- [Customizing a Subnet](developer-guides/pluggable-syscall-tutorial.md) +- [Upgrading a Subnet](developer-guides/upgrades/README.md) - [Example: Patching actor state](developer-guides/upgrades/patch-state.md) - [Example: Upgrading Wasm actor](developer-guides/upgrades/upgrade-wasm-actor.md) -- [Deploying an explorer](developer-guides/deploy-blockscout.md) +- [Deploying an Explorer](developer-guides/deploy-blockscout.md) ## Specifications @@ -43,5 +41,6 @@ - [Networks](reference/networks.md) - [IPC CLI](reference/ipc-cli-usage.md) +- [Glossary](reference/glossary.md) - [Troubleshooting](reference/troubleshooting.md) - [FAQ](reference/faq.md) diff --git a/docs-gitbook/concepts/circulating-supply.md b/docs-gitbook/concepts/circulating-supply.md deleted file mode 100644 index 3096a64d8e..0000000000 --- a/docs-gitbook/concepts/circulating-supply.md +++ /dev/null @@ -1,31 +0,0 @@ -# Circulating supply - -## Supply sources - -At the moment, there are 2 supply sources possible in IPC: _native_ and _ERC20_. - -The native source means that funds in parent's native coin are moved to the subnet. - -The ERC20 source means that there is an ERC20 contracts on the parent, which is configured as subnet's supply source. When funds are to be moved to the subnet, they are locked in ERC20 contract and then minted on the parent. - -Other than this, the flows for depositing and withdrawing funds are equivalent. - -## Depositing funds - -The flow of depositing funds from the address on the parent to the address on the subnet consists of the following steps: - -1. One of fund functions is called on the _parent's_ Gateway Actor -2. Funds are locked on the parent's subnet. -3. A top-down message is enqueued in the parent to move funds. -4. The subnet's validator fetches top-down messages and executes them, including the message related to depositing funds. -5. As part of the message execution funds are credited to the specified address in the subnet. - -## Withdrawing funds - -The flow of withdrawing funds from the address on the subnet to the address on the parent consists of the following steps: - -1. A release function is called on the _subnet's_ Gateway Actor. -2. The release function burns the funds which are going to be withdrawn. -3. A top-down message is enqueued in the subnet to move funds. -4. The relayer, which is responsible for submitting checkpoints containing bottom-up messages, propagates the messages to the parent, including the message related to withdrawing funds. -5. As part of the message execution funds are credited to the specified address in the parent. diff --git a/docs-gitbook/concepts/subnets/README.md b/docs-gitbook/concepts/subnets/README.md deleted file mode 100644 index 594bf34953..0000000000 --- a/docs-gitbook/concepts/subnets/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Subnets - -## Definition - -A subnet is a new subsystem that a user can spawn from a parent subnet in a permissionless and on-demand way, depending on scalability requirements. Subnets have separate consensus algorithms and cryptoeconomic rules from their parent subnet. Subnets are firewalled from the parent network. - -## Hierarchy trees - -Subnets begin with a chosen "rootnet". Rootnets refer to a layer 1 blockchain, such as Filecoin or Ethereum. Child subnets are spawned from the rootnet and the rootnet becomes the parent subnet. - -Each subnet can have any number of child subnets, while each child subnet only has one parent subnet. Subnets can scale infinitely, to layer 2 and beyond. A single hierarchy tree begins at the chosen rootnet. - -Subnets within a single hierarchy tree have native communication protocols and are able to transfer assets and state without a custom bridge. - -## Lifecycle - -The lifecycle of a subnet begins when it’s established and ends when the subnet is closed. - -At the time of subnet creation, a minimum collateral requirement is set by the subnet creator. A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. - -Conditions for closing a subnet include: - -* A child subnet cannot be killed until its circulating supply is zero, which can be achieved when all users send their funds back to a parent. -* If all validators leave a subnet even when their are still users of the subnet, the users will have to either run their own validator or wait for a validator to return to the subnet. -* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee. - -## Staking - -It’s likely that many IPC subnets will be subnets of proof-of-stake chains, or the subnets themselves will be proof of stake chains to other types of chains. For this reason, IPC has native functionality that is intended to handle staking with respect to subnets. These native functionalities include staking and releasing collateral associated with subnet validators and slashing collateral associated with a provably misbehaving subnet validator. - -## Fees - -### Establishing a subnet - -There are a number of fees that are paid when a subnet is established: - -* At the time of subnet creation, a minimum collateral requirement is set by the subnet creator. -* A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. -* When a participant or validator (other than the subnet creator) joins the subnet, initial funds for their participation in the subnet should be moved from their respective account in the parent by using the `join` command. This also enables the signing of checkpoint transactions. - -### Closing a Subnet - -The conditions for closing a subnet are as follows: - -* A child subnet cannot be killed untill its circulating supply is zero, which can be achieved when all users send their funds back to a parent. -* If all validators leave a subnet even when their are still users of the subnet, the users will have to either run their own validator or wait for a validator to return to the subnet. -* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee. diff --git a/docs-gitbook/concepts/subnets/parent-child-interactions.md b/docs-gitbook/concepts/subnets/parent-child-interactions.md deleted file mode 100644 index 8d4ef686b7..0000000000 --- a/docs-gitbook/concepts/subnets/parent-child-interactions.md +++ /dev/null @@ -1,46 +0,0 @@ -# Parent-child interactions - -The interaction between two subnets in a parent-child relation, is the basic building block of the recursive IPC hierarchy. - -There are following parent-child interactions available in IPC - -1\. Creating child subnets in the IPC hierarchy. - -2\. Depositing funds from an account in a subnet to an account in its child. - -3\. Withdrawing funds from an account in a subnet to an account in its parent. - -4\. Checkpointing a subnet’s replicated state in the replicated state of its parent. - -5\. Invoking actor functions across subnets. - -6\. Removing child subnets from the IPC hierarchy. - -## Checkpointing - -Checkpointing is a method for a parent subnet to keep a record of the evolution of its child subnet’s state by including snapshots of the child’s state (called checkpoints) in the parent’s state. If, for some reason, the child subnet misbehaves as a whole, agreement can be reached in the parent subnet about how to proceed. - -Checkpointed history of a child subnet cannot be reverted as long as a parent subnet operates as expected. Checkpoints are propagated in a recursive way all the way to the rootnet (L1), which makes child subnets benefit from security of their ancestor subnets. - -In case of subnet failure, checkpointing enables participants (e.g., former users of the failed subnet) to agree on picking up an older version of the child subnet’s state from before the occurrence of the failure and, say, use that version as the initial state of a new, more robust subnet.\ - -### Checkpointing fees - -There are a number of fees that are paid during checkpointing: - -* When a subnet checkpoints its state to a parent, this is the equivalent of a transaction on the parent. The usual transaction fees of the parent are paid to accomplish this. -* In order for a subnet to be considered _anchored_ to the parent, relayers must have sufficient funds in their respective wallets in the parent to be able to pay for a checkpointed transaction. -* When a cross-net transaction is included in a subnet's checkpoint to a parent, the fees for that transaction are distributed as a reward equally among all the relayers that have submitted an instance of that checkpoint. -* Relayers are allowed to submit a checkpoint and eligible for rewards from the commitment of the first checkpoint in, e.g. epoch \`h\`, to the first submission of a checkpoint of epoch \`h+1\`. From this point on, no new valid submissions for checkpoint \`h\` will be accepted. - -## Parent finality - -Parent finality is a mechanism for proving that a subnet irreversibly reached a certain state. - -It is achieved in the following way - -* Validators in the child subnet periodically listen to new blocks from the parent. On the implementation level it is performed by Fendermint node of subnet validator subscribing to events via parent's ETH RPC. -* As part of the consensus algorithm in the child, the leader of the consensus proposes the height and hash of the parent’s block that they currently consider final. -* The rest of the validators agree or reject this finality from the parent as part of the process of voting the validity of a block (i.e. validators implicitly agree on the finality of the parent through the block validation). -* As part of the execution of the block, validators implicitly commit the finality seen in the parent. This triggers the execution of all top-down messages from the latest finality to the one committed, as well as any changes on the validator set or collateral that may need to be propagated down. -* When a user performs a top-down message, it is added to a queue in the parent chain. Top-down messages are indexed in the parent by the height where they were committed. This index is used by child subnet validators to determine when a top-down message commitment can be considered as final and their execution can be triggered in the child (when their corresponding finality has been triggered). diff --git a/docs-gitbook/overview/architecture.md b/docs-gitbook/overview/architecture.md deleted file mode 100644 index 2cd7e9f3f8..0000000000 --- a/docs-gitbook/overview/architecture.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: Architectural components in the IPC framework. ---- - -# Architecture - -\ -![](https://github.com/consensus-shipyard/docs/blob/main/assets/architecture.png?raw=true) - -## Validator nodes - -Operators of a subnet run a full validator node for both the parent and the child subnet. Requiring the nodes of child subnets to run the nodes of parents is a security parameter to ensure [checkpointed](../key-concepts/broken-reference/) states of the subnet are appropriately stored, at the right time in the parent. - -The following components make up a node: - -### Tendermint - -[Tendermint Core](https://tendermint.com/) is a byzantine fault tolerant (BFT) consensus engine for blockchains. It acts as a generic [state machine replication](https://en.wikipedia.org/wiki/State\_machine\_replication) (SMR) in a subnet, talking to other Tendermint instances in the subnet and ensuring a consistent ledger is maintained across validator nodes. It talks to the Application in the node, via ABCI++. - -### ABCI++ - -The [ABCI++](https://members.delphidigital.io/learn/abci) interface is implemented in order to handle the IPC ledger logic and transaction handling, using the [Filecoin Virtual Machine](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm) (or Ethereum-compatible FVM). The ABCI can pass [checkpointed](../key-concepts/broken-reference/) headers to the parent and use the ledger to gather relevant signatures. - -An ABCI++ application can contact the [IPLD](https://docs.filecoin.io/basics/project-and-community/related-projects#ipld) [resolver & store](broken-reference) to read and write data so that it is IPLD addressable. - -### Filecoin Virtual Machine (FVM) - -The [FVM](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm) enables on-chain programmability and is built as a polyglot VM. It is currently compatible with Filecoin and Ethereum and has plans to support more chains in its [roadmap](https://fvm.filecoin.io/). - -FVM is included as a transaction execution later in the subnet, allowing use cases enabled by smart contracts to be built on top of subnets. - -You may want to build an dApp on FVM that requires a transaction throughput higher than Filecoin provides. You can deploy a subnet that has a higher transaction settling frequency, and deploy the dApp on the subnet with FVM. - -### IPC Actors - -Communication between subnets on IPC is done by two [actors](https://docs.filecoin.io/basics/the-blockchain/actors) instantiated in each subnet--the _IPC Subnet Actor (ISA)_ and the _IPC Gateway Actor (IGA)_. - -The IGA is an actor that contains all IPC-related information and logic associated with a subnet that needs to be replicated within the subnet. The IGA implements the hierarchical consensus logic and enforces some level of security for account balances, e.g. by ensuring that it is not possible to withdraw more native tokens from the subnet than were used to fund the subnet. - -The ISA is the IGA’s parent-side counterpart; that is, it is deployed to a subnet’s parent and contains all data and logic associated with the particular child subnet. For a subnet to be able to interact with its parent, it needs to have a registered subnet actor on the parent network. - -Primitives enabling cross-subnet communication include those for transferring funds between accounts in different subnets, saving checkpoints of a child's state in a parent chain, and submitting transactions on one subnet based on inputs from actors on another subnet. - -### Relayer - -The role of relayers is to pass messages between parent and child subnets. They have to follow both the parent and the child consensus, subscribe to events, re-package the messages in the appropriate formats and resend them. Relayers can be incentivized. Both parent and child subnets can have an entirely different block structure and consensus, and only the relayers understand both, by being purposefully constructed to act between certain combinations. - -### Lotus rootnet - -[Lotus](https://lotus.filecoin.io/lotus/get-started/what-is-lotus/) currently serves as the rootnet for IPC subnets. It is the reference implementation for Filecoin nodes. diff --git a/docs-gitbook/overview/how-ipc-compares.md b/docs-gitbook/overview/how-ipc-compares.md index be370438ae..b3603a294f 100644 --- a/docs-gitbook/overview/how-ipc-compares.md +++ b/docs-gitbook/overview/how-ipc-compares.md @@ -1,33 +1,59 @@ ---- -description: >- - IPC is a standout framework that strikes a considerable balance, to achieve - breakthroughs in scaling. ---- +# How IPC Compares -# How IPC compares +IPC is one approach among several for scaling and extending blockchains, each making different trade-offs between security, sovereignty, performance, and operational complexity. This page positions IPC within the broader landscape; for IPC's own capabilities in detail, see the [Protocol Overview](../protocol/README.md). -## **Benefits of IPC Design** +## Scaling Approaches -The IPC framework offers several significant benefits: +Blockchain scaling generally works by moving execution off a slow, expensive base chain. The approaches differ in where execution happens, who is trusted for correctness, and how the base chain relates to the executing chain. (For a detailed taxonomy, see Vitalik Buterin's [Different types of layer 2s](https://vitalik.eth.limo/general/2023/10/31/l2types.html).) -- **Scalability**: By enabling the creation of subnets, IPC allows for on-demand horizontal scalability, effectively managing increased network load by distributing transactions across multiple chains. -- **Flexibility**: The ability to tailor stakeholder incentives per subnet caters to diverse application needs, optimizing performance and security. However, switching consensus mechanisms may not be straightforward at the current stage. -- **Interoperability**: Full EVM compatibility ensures that subnets can seamlessly integrate with the broader Ethereum ecosystem, leveraging existing development tools and community resources. -- **Decentralization and Security**: The hierarchical structure of subnets supports a robust security architecture while promoting greater decentralization, as subnets can operate independently but are still connected to the main network. +**[Rollups](https://ethereum.org/en/developers/docs/scaling/#rollups)** execute transactions off-chain and post transaction data (or compressed state differences) back to the base chain, along with a correctness guarantee: either a validity proof verified on-chain (ZK rollups) or a challenge window during which fraud can be proven (optimistic rollups). Because the base chain verifies state transition correctness, rollup security is derived from the base chain. Users can, in principle, reconstruct the rollup's state and withdraw assets from base chain data, though blob pruning ([EIP-4844](https://eips.ethereum.org/EIPS/eip-4844)) means long-term reconstruction requires archival infrastructure. -## **Highly customizable without compromising security** +**[Sidechains](https://ethereum.org/en/developers/docs/scaling/sidechains/)** are independent blockchains connected to a base chain through a bridge. They run their own consensus and manage their own state; the base chain does not verify their state transitions. Security depends on the sidechain's own validator set, and the bridge mechanism (ranging from multisig federations to light-client-based verification) determines how trust is managed for cross-chain asset transfers. The term covers a wide spectrum of designs with varying trust properties. -Most L2 scaling solutions today either inherit the L1's security features but don't have their own consensus algorithms (e.g. rollups), or do the reverse (e.g. sidechains). They are also deployed in isolation and require custom bridges or protocols to transfer assets and state between L2s that share a common L1, which are vulnerable to attacks. In contrast, IPC subnets have their own consensus algorithms, inherit security features from the parent subnet and have native cross-net communication, eliminating the need for bridges. +**Appchain frameworks** provide infrastructure for deploying application-specific or special-purpose blockchains. They differ substantially in security model. [Cosmos](https://docs.cosmos.network/) zones are sovereign chains with independent validator sets, communicating via the [IBC protocol](https://ibcprotocol.dev/) and optionally opting into shared security from the Cosmos Hub. [Polkadot](https://wiki.polkadot.network/) parachains share security with the relay chain, which assigns validators to verify parachain state transitions, providing strong inherited security but constraining consensus sovereignty while preserving broad execution and governance autonomy. [Avalanche L1s](https://build.avax.network/) (formerly subnets) run their own validation with configurable rules and communicate via [Interchain Messaging (ICM)](https://docs.avax.network/build/cross-chain/awm/overview), built on Avalanche Warp Messaging. -## **Multi-chain interoperability** +**State and payment channels** (e.g., [Lightning Network](https://lightning.network/)) enable off-chain interactions that settle on-chain only upon disagreement. They provide near-instant finality for the interaction patterns they support but are limited in the types of state transitions they can handle. -- IPC uses [Tendermint Core](https://tendermint.com/core/) as a generic blockchain SMR system, without defaulting to the Cosmos SDK (written in Go). This allows IPC to plug in our own application logic regardless of what language it’s written in: it can be Go, Rust, Java, Haskell, Scheme, etc. -- IPC uses the [Filecoin Virtual Machine (FVM)](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm) as its transaction execution layer. The FVM is a WASM-based polyglot execution environment for IPLD data and is designed to support smart contracts written in any programming language, compiled to WebAssembly. This enables multi-chain support and gives developers the flexibility to build with familiar tools. Today, IPC is fully compatible with Filecoin and Ethereum and can use either as a rootnet, with more multi-chain support in the roadmap. +**[Validiums](https://ethereum.org/en/developers/docs/scaling/validium/)** use validity proofs like ZK rollups but store transaction data off-chain (e.g., with a data availability committee). The base chain verifies state transition correctness but cannot reconstruct state from on-chain data alone, trading data availability guarantees for lower cost. -## **Compute-Storage Interoperability with Filecoin and more** +## Where IPC Sits -IPC is designed to seamlessly integrate with Filecoin and EVM-compatible chains (with more to come), allowing developers to embed IPC subnets within these ecosystems. In particular, IPC unlocks new compute possibilities with the data-centric L1, [Filecoin](https://docs.filecoin.io/basics/what-is-filecoin), which is the largest decentralized storage network. IPC can leverage its storage primitives, like [IPLD](https://spec.filecoin.io/libraries/ipld/) data integration, to deliver enhanced solutions for data availability and more. +IPC follows the **sidechain model**: subnets are autonomous blockchains with their own consensus, connected to parent chains. More broadly, IPC is an extensibility and scalability framework whose protocol can support configurations along a wider spectrum (see Design Trade-offs below). What distinguishes IPC from generic sidechains are the following design choices. -## **Increased performance** +**Checkpoint-based objectivity.** Subnets periodically commit cryptographic state commitments, [checkpoints](../protocol/core-mechanisms.md#checkpointing), to their parent chains. These serve as objective trust anchors: anyone can determine a recent valid state of the subnet (as attested by a quorum of its validators) by examining checkpoints on the parent chain, without running a subnet node or relying on social consensus. Checkpoints mitigate long-range attacks and enable trustless bootstrapping, since an attacker cannot rewrite history beyond the last committed checkpoint without compromising the parent chain, and new participants can join by verifying a recent checkpoint rather than relying on [weak subjectivity](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/weak-subjectivity/). -IPC’s modular runtime enables the creation of truly flexible blockchains to increase throughput while managing gas efficiency. Developers can dynamically adjust their throughput by spawning and closing temporary subnets as needed. +**Protocol-native [bridging](../protocol/core-mechanisms.md#bridging) secured by checkpoints.** Cross-chain communication in IPC is not an external bridge added to otherwise independent chains. Bottom-up messages (subnet to parent) are batched with checkpoints and verified against them on the parent chain. Top-down messages (parent to subnet) are delivered as the subnet tracks and verifies parent chain finality. In both directions, the lock-mint-burn-release cycle for asset transfers is enforced by on-chain logic on both sides, with per-subnet supply accounting limiting the impact of any subnet compromise to its own circulating supply. + +**Recursive hierarchy.** Subnets can themselves serve as parent chains for further subnets, forming a recursive tree. Transitive checkpointing into a common chain establishes eventual consistency across subnets, enabling cross-chain coordination without requiring all subnets to coordinate directly. + +**Minimal parent chain requirements.** IPC imposes minimal requirements on the parent chain's capabilities at the protocol level: recording arbitrary data, basic asset operations (lock/release), and governance enforcement. A general-purpose smart contract environment is not required in principle, though the standard implementation relies on EVM smart contracts on the parent chain. Anchoring into chains with limited programmability is possible but requires specialized extensions, as [demonstrated for Bitcoin](https://arxiv.org/abs/2512.23439) using SegWit/OP_RETURN encoding. + +## Comparison Along Key Dimensions + +**Security.** Rollups verify state transition correctness on the base chain; a compromised operator cannot cause acceptance of invalid state (though most deployments [haven't fully achieved this](https://l2beat.com/scaling/summary) due to upgradeable contracts, security councils, and immature proof systems). IPC verifies checkpoint authenticity (quorum signatures) but not state transition correctness; security rests on the subnet's own consensus, with damage bounded to the subnet's circulating supply. Polkadot parachains inherit relay chain security (randomly assigned validators with reshuffling and approval voting). Cosmos zones and Avalanche L1s are sovereign like IPC. + +**Data.** Rollups post data to the base chain, enabling independent state reconstruction at significant cost. IPC checkpoints are compact cryptographic commitments; the parent chain cannot reconstruct subnet state, but subnets avoid data posting costs and maintain data sovereignty. The protocol could be extended with data availability proofs, moving toward a validium-like model. + +**Ordering.** Most rollup deployments currently use centralized sequencers, with escape hatches (forced inclusion via L1) that involve significant delays. IPC subnets run their own consensus, with no architectural dependency on a centralized sequencer. + +**Cross-chain messaging.** IPC provides protocol-native messaging secured by checkpoints (multi-hop routing through intermediate chains is specified in the foundational design but not yet implemented). Cosmos [IBC](https://ibcprotocol.dev/) is the most mature cross-chain protocol (115+ chains, light-client-based, peer-to-peer). Polkadot's [XCM](https://wiki.polkadot.network/docs/learn-xcm) defines a message format, currently relay-routed via [HRMP](https://wiki.polkadot.network/docs/learn-hrmp). Rollups lack standardized cross-rollup messaging. + +**Partition tolerance.** IPC subnets continue operating with local finality when disconnected from parent chains; cross-chain operations stall but internal operations are unaffected. Rollups achieve soft finality but cannot settle without L1. Polkadot parachains depend on the relay chain. Cosmos zones are similarly partition-tolerant. + +**Customizability.** IPC and Cosmos offer comparable flexibility (consensus, execution, fees, governance, permissioning), enabling application-specific or special-purpose subnets tailored to particular workloads. Polkadot parachains can customize execution logic broadly but cede consensus sovereignty. Rollups are constrained by their proof system's verification capabilities. + +## Design Trade-offs + +IPC's design choices involve explicit trade-offs, discussed further in [Security & Economics](../protocol/security-and-economics.md). Some are fundamental to the sovereignty-oriented sidechain approach; others are current design boundaries that the protocol could be extended beyond. + +**Quorum-based trust for checkpoints.** The parent chain verifies that checkpoints are properly signed by the subnet's recognized validator set, but does not independently verify the correctness of the state transitions they commit to. A compromised subnet quorum can therefore submit false checkpoints that the parent chain would accept. This is the central security trade-off relative to rollups, which verify state transitions at the base chain level. The protocol is architecturally compatible with augmenting checkpoints with state transition proofs (validity proofs or fraud proof mechanisms), which would move the security model toward that of a validium or optimium, where the parent chain verifies state transition correctness while data remains with the subnet. Such an extension would strengthen the security guarantee at the cost of additional complexity, computational overhead, and stronger requirements on the parent chain. + +**Per-subnet validator sets.** Each subnet requires its own validator set and consensus mechanism. This provides sovereignty and partition tolerance but incurs bootstrapping and operational overhead compared to shared-security models. Validator sets of different subnets may overlap, and the protocol supports a range of configurations (from small federated deployments to open, collateral-based sets), but each subnet must independently assemble sufficient validation capacity. + +**Cross-chain latency.** Bottom-up cross-chain operations are bounded by the checkpoint period, the interval at which checkpoints are committed to the parent chain. Top-down operations are bounded by the parent chain's finality time and the subnet's monitoring cycle, which is independent of the checkpoint period. More frequent bottom-up checkpoints reduce latency but increase parent chain overhead. This periodic anchoring differs from rollups (where state updates can be reflected on the base chain with each proof or batch submission) and from IBC (where light client updates can be frequent and event-driven). + +**Risk scoping.** A compromised subnet can extract assets delegated to it, bounded by the subnet's circulating supply. Per-subnet supply accounting limits the blast radius, preventing a compromised subnet from affecting the parent chain or sibling subnets. This is the fundamental trade-off of any system that does not verify state transitions at the parent chain level. + +## Bottom Line + +IPC sits between fully inherited security (rollups) and fully independent chains (plain sidechains). It adds checkpoint-based objectivity, protocol-native bridging, recursive extensibility, and risk containment to the sidechain model. The central trade-off is that subnet security rests on the subnet's own consensus rather than parent chain verification, though the protocol leaves room for strengthening this through state transition proofs. Best suited for deploying application-specific or special-purpose chains that need autonomy, configurable trust, and partition tolerance, rather than maximal inherited security from a single base chain. diff --git a/docs-gitbook/overview/how-it-works.md b/docs-gitbook/overview/how-it-works.md deleted file mode 100644 index 17798b9329..0000000000 --- a/docs-gitbook/overview/how-it-works.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: >- - Overview of how IPC works. ---- - -# How IPC Works - -## **Interplanetary Consensus (IPC)** - -IPC is designed to scale blockchains through the creation of child chains, each with its own unique consensus mechanism, known as a subnet. This scalable architecture is facilitated by a parent chain, which runs a set of Solidity smart contracts—referred to as [actors](https://docs.filecoin.io/basics/the-blockchain/actors)—that manage the creation, recording, and oversight of subnets along with their validator and staking mechanisms. - -## **Initialization and Operation of Subnets** - -Each subnet is deployed as a standalone chain utilizing [CometBFT](https://docs.cometbft.com/) for its consensus process. The chain is initially configured within the parent chain, where the base validators set and their stakes are also recorded. Following this initial setup, the chain nodes must be started and connected to the parent chain to begin operations. The subnet deploys its own actors (smart contracts) on the [Filecoin Virtual Machine (FVM)](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm), which manage subnet-specific operations. Additionally, subnets are fully [EVM (Ethereum Virtual Machine)](https://ethereum.org/en/developers/docs/evm/) compatible, allowing for seamless integration with existing Ethereum-based tools and systems. This design allows subnets to operate semi-independently while still being part of a larger network managed by the parent chain. - -## **Communication Between Chains** - -Communication between the parent chain and its subnets can occur in both directions—top-down (from parent to subnet) and bottom-up (from subnet to parent). This inter-chain communication is facilitated by a component known as the relayer, which transmits messages between actors on different chains. Typical communications include actor-to-actor messages, updates to the validator set, and periodic checkpoints sent from the subnet to the parent chain. - -## **Data Handling with IPLD and IPFS** - -Instead of transmitting actual data directly, IPC utilizes [InterPlanetary Linked Data (IPLD)](https://spec.filecoin.io/libraries/ipld/) to create data links. These links are then resolved using a resolver that fetches the actual data stored on the [InterPlanetary File System (IPFS)](https://docs.ipfs.tech/), ensuring efficient and secure data management across the network. Additionally, the CometBFT validators run a quorum to agree on the top-down messages from the parent chain, ensuring they can achieve consensus and end up with the same state. - -## **Architecture** - -For a detailed exploration of the IPC's underlying structure and design principles, please refer to the [Architecture section](overview/architecture.md). This section provides in-depth coverage of the technical framework and operational guidelines for IPC. diff --git a/docs-gitbook/overview/use-cases.md b/docs-gitbook/overview/use-cases.md index b7172338de..e93c1b1505 100644 --- a/docs-gitbook/overview/use-cases.md +++ b/docs-gitbook/overview/use-cases.md @@ -1,18 +1,20 @@ -# Use cases +# Use Cases ## Applications of IPC -Here are some practical examples of how IPC improves the performance of dApps: +IPC's combination of dynamic scalability, customizability, autonomy, and partition tolerance enables a range of applications. -* **Distributed Computation**: Spawn ephemeral subnets to run distributed computation jobs. +* **Distributed Computation**: Spawn ephemeral subnets to run distributed computation jobs, leveraging faster finality and greater computational capacity. * **Coordination**: Assemble into smaller subnets for decentralized orchestration with high throughput and low fees. * **Localization**: Leverage proximity to improve performance and operate with very low latency in geographically constrained settings. -* **Partition tolerance**: Deploy blockchain substrates in mobile settings or other environments with limited connectivity. +* **Partition tolerance**: Deploy blockchain substrates in mobile settings or other environments with limited connectivity — subnets continue operating autonomously and synchronize upon reconnection. With better performance, lower fees and faster transactions, IPC can rapidly improve horizontal and vertical markets with decentralized technology: -* **Artificial Intelligence:** IPC is fully compatible with [Filecoin](https://docs.filecoin.io/basics/what-is-filecoin), the world’s largest decentralized data storage. Leveraging Filecoin, IPC can enable distributed computation to power hundreds of innovative AI models. +* **Artificial Intelligence:** IPC is fully compatible with [Filecoin](https://docs.filecoin.io/basics/what-is-filecoin), the world's largest decentralized data storage. Leveraging Filecoin, IPC can enable distributed computation to power hundreds of innovative AI models. * **Decentralized Finance (DeFi):** Enabling truly high-frequency trading and traditional backends with verifiability and privacy. * **Big Data and Data Science:** Multiple teams are creating global-scale distributed compute networks to enable Data Science analysis on Exabytes of decentralized stored data. * **Metaverse/Gaming:** Enabling real-time tracking of player interactions in virtual worlds. -* **DAOs:** Assemble into smaller subnets for decentralized orchestration with high throughput and low fees. Partition tolerance: Deploy blockchain substrates in mobile settings or other environments with limited connectivity. +* **DAOs:** Assemble into smaller subnets for decentralized orchestration with high throughput and low fees. +* **Partition tolerance:** Deploy blockchain substrates in mobile settings or other +environments with limited connectivity. \ No newline at end of file diff --git a/docs-gitbook/protocol/README.md b/docs-gitbook/protocol/README.md new file mode 100644 index 0000000000..666fc33197 --- /dev/null +++ b/docs-gitbook/protocol/README.md @@ -0,0 +1,80 @@ +# Protocol Overview + +
+TL;DR + +IPC is a protocol for extending blockchains with autonomous sidechains — subnets — that can provide *faster, cheaper, and more specialized* functionality. Subnet state is periodically anchored into higher-security chains through cryptographic checkpoints that serve as *objective, verifiable trust anchors*. Subnets are full, *decentralized* blockchains that *own their data*, are highly *configurable*, and impose *minimal requirements* on the chains they anchor into. Secured by checkpoints, cross-net messages enable *transfer of assets and information* between chains. The architecture is *recursive*: subnets can themselves be extended with lower-level subnets, with transitive checkpointing enabling *eventual consistency* across them. + +
+ +Inter-Planetary Consensus (IPC) is a flexible blockchain **extensibility** and **scalability** solution. In a nutshell, it can be thought of as a **sidechain system** in which users can delegate operations to dedicated *autonomous* blockchains, subnets — typically faster and cheaper — whose state is anchored back into higher-security but less capable chains. Moreover, IPC subnets can be further extended with lower-level subnets, in a **recursive** way. + +IPC subnets are meant to be full, sufficiently **decentralized** blockchains **owning their data**, unlike rollups, which still largely rely on centralized sequencers and post significant amount of data to the main chain. Subnets can provide faster finality, higher throughput, cheaper block space, and can host specialized functionality beyond what the parent chain supports. IPC subnets are highly **configurable**; they can be heavily **customized**, **specialized**, and **fine-tuned**. Moreover, IPC strives to impose **minimal requirements** on the target chain's capabilities; in fact, [IPC subnets can even be anchored into Bitcoin](https://arxiv.org/abs/2512.23439), despite its quite limited support for on-chain programmability. These capabilities enable building layered sidechain systems in a **recursive** manner, where lower-level, even more capable or specialized subnets can be anchored into higher-level subnets. Anchoring the subnet state into higher-security chains provides **checkpoint-based objectivity**, which facilitates dynamic joining into subnets or instantiating light clients for them, secured against [long-range attacks](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/attack-and-defense/#long-range) without relying on social consensus, as opposed to the [weak subjectivity](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/weak-subjectivity/) approach. IPC chains can **exchange assets and information** through cross-net messages, secured by the checkpointing mechanism. In addition to that, transitively checkpointing into a common chain helps establish **eventual consistency** across autonomous subnets, further facilitating coordination of cross-chain operations. + +## Core Concepts + +The main concept in IPC is **subnet**, which represents an autonomous blockchain whose state is anchored into another blockchain referred to as the subnet's **parent chain**. Subnets can act as parent chains for other subnets, in a recursive manner. A blockchain that has no parent chain is referred to as **rootnet**. Each subnet in IPC is assigned a **subnet ID**, which acts as an address identifying the subnet as a whole. + +A subnet's state is anchored into the parent chain by periodically committing **checkpoints** to the parent chain. Each newly created checkpoint contains a cryptographic reference (e.g. block hash) to a recently finalized head of the subnet's chain and may also contain further cryptographic commitments to the subnet's state. Committed checkpoints thus cryptographically bind the subnet state to the parent chain and serve as an objective trust anchor for determining a recent subnet state. Similarly, subnets also periodically checkpoint their parent chain's finalized state, enabling secure cross-chain bridging in both directions. + +Autonomous blockchains in IPC can interact by sending each other **cross-net messages**, which can carry arbitrary information as well as assets. Messages from the parent chain to the subnet are called **top-down messages**; messages from the subnet to the parent chain are called **bottom-up messages**. Messages carrying assets are also referred to as **deposits** (when locking & minting assets, typically top-down) or **withdrawals** (when burning & releasing assets, typically bottom-up). + +*Note that, currently, sending cross-net messages is only supported for directly linked chains, i.e. single-hop parent-to-subnet or subnet-to-parent. Moreover, only deposits from and withdrawals back to parent chains are currently supported.* + +## How IPC Works + +On a conceptual level, the IPC protocol can be thought of as a combination of [mechanisms](core-mechanisms.md) working together. The checkpointing and bridging mechanisms play a central role in IPC: [**checkpointing**](core-mechanisms.md#checkpointing) ensures that the state of one chain remains anchored into another, whereas [**bridging**](core-mechanisms.md#bridging) secures the transfer of information and assets between chains. The subnet ID, lifecycle, and configuration management are auxiliary governance mechanisms: [**subnet ID management**](core-mechanisms.md#subnet-id-management) governs subnet ID namespaces and assignment of individual subnet IDs; [**subnet lifecycle management**](core-mechanisms.md#subnet-lifecycle-management) governs registration of new subnets, changing their operational status, and eventual termination of subnets; [**subnet configuration management**](core-mechanisms.md#subnet-configuration-management) regulates the process of updating the subnet configuration, such as its validator set and the allocation of voting power. + +**Rootnet and Network Extension.** As a prerequisite, IPC assumes a preexisting blockchain network, a rootnet, which all participants have access to and treat as a root of trust. Such rootnet is supposed to be highly decentralized and secure, albeit slow and expensive. Given this basis, the IPC network can be progressively extended with new subnets. + +**Subnet Lifecycle Flow.** Each new subnet first needs to obtain a subnet ID through the subnet ID management mechanism and then get registered through the lifecycle management mechanism. Depending on the subnet type and effective policies, the subnet lifecycle management mechanism may require further steps for the subnet to become active, e.g. locking initial subnet validators' collateral for PoS subnets. The activation determines the subnet's initial configuration, which is then handled by and may be updated through the subnet configuration management mechanism. Eventually, the subnet may be terminated, which is, like subnet activation, governed by the subnet lifecycle management mechanism. + +**Checkpointing and State Anchoring.** For the most part, individual subnets operate as autonomous blockchains. However, in order to maintain objective trust anchors to subnets, the current state of subnets is cryptographically bound to their parent chains by means of checkpoints that are periodically committed there through the checkpointing mechanism. Conversely, subnets also periodically commit checkpoints of their parent chain's finalized state. Each checkpoint carries a cryptographic commitment (e.g. block hash) to a recently finalized subnet chain's head and may also contain further succinct cryptographic commitments to specific pieces of the subnet's state (e.g. the subnet's configuration, sub-subnet's checkpoints, etc.) The checkpointing mechanism ensures that the checkpoints committed on the parent chain objectively correspond to the subnet's actual state. Moreover, subnets follow their parent chains and also regularly commit checkpoints of recently finalized parent chain state. These checkpoints are used for cross-chain bridging, namely to secure transferring of information and assets from subnets to their parent chains and vice versa. Checkpoints also allow instantly joining and following the corresponding chain, without relying on more subjective trust anchors like social consensus or centralized services. + +**Bridging and Cross-Net Messaging.** The bridging mechanism allows secure transfer of information and assets from one chain into another. This mechanism relies on sending chains continuously checkpointing into receiving chains. Both information and asset transfer use the same underlying carrier — cross-net messages. Cross-net messages can be used for depositing and withdrawal of assets as well as for pure general message passing. Depositing of assets from one chain into another is achieved, as usual, by locking assets on the origin chain and minting equivalent (wrapped) assets on the target chain; withdrawing deposited assets back to the origin chain is achieved by burning some of the previously minted assets on the target chain and releasing equivalent locked assets on the origin chain. General messages with information payload can trigger arbitrary on-chain logic. + +## Key Capabilities & Properties + +The IPC protocol provides the following key capabilities and properties. + +
+Dynamic scalability + +IPC enables scaling by allowing users to delegate operations from secure but slow and expensive chains to subnets optimized for performance, which can provide faster finality, higher throughput, and cheaper block space. Checkpoint-based objectivity through periodic state anchoring enables trustless bootstrapping: new subnets are immediately verifiable against their parent chain, so participants can join subnets without relying on trusted sources or social consensus. Thus, new subnets can be launched programmatically to handle increased workload and terminated when no longer needed, allowing the network to elastically adapt to varying demands. Scaling extends in multiple dimensions through parallel sibling subnets and recursive lower-level subnets. + +
+ +
+Customizability + +IPC subnets are meant to be highly configurable, allowing builders to tailor virtually every aspect of the blockchain stack to their specific requirements. This includes the consensus mechanism (e.g. enabling fast finality or other performance fine-tuning), the execution environment (supporting custom VM runtimes, e.g. [Wasm](https://webassembly.org/) & [EVM](https://ethereum.org/en/developers/docs/evm/)-compatible [FVM](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm)), tokenomics and fee structures (e.g. enabling subsidized or fee-free transactions), data availability strategies, and governance models. Subnets can be configured as permissioned (federated) or permissionless (open, with collateralized validators), and can enforce custom policies for validator admission and power allocation. This flexibility extends to the network topology itself, enabling regional or application-specific deployments. Subnets can also be extended with specialized functionality such as decentralized data storage, or compute-over-data workflows that can leverage faster subnet finality and greater computational capacity. + +
+ +
+Seamless interoperability + +IPC provides native cross-chain communication through protocol-native bridging secured by the checkpointing mechanism. Cross-net messages support general message passing, as well as asset deposits and withdrawals. Subnets that transitively checkpoint into a common chain establish eventual consistency with each other, facilitating coordination of cross-chain operations. IPC's minimal requirements on parent chain capabilities enable interoperability across heterogeneous environments, including chains with limited programmability. Furthermore, subnets' high customizability allows tailoring them for tighter integration with specific ecosystems, such as leveraging [IPLD](https://ipld.io/) for seamless data exchange with [Filecoin](https://docs.filecoin.io/). + +
+ +
+Autonomy & sovereignty + +IPC subnets operating as largely autonomous blockchains own their data and control their own governance. Subnets govern their own lifecycle, configuration, and validator sets through dedicated management mechanisms, without relying on centralized components like sequencers or posting significant amounts of data to parent chains. Subnets can achieve the level of decentralization appropriate to their use case, from small federated deployments to fully open, large validator sets. Subnet autonomy includes partition tolerance: subnets can continue operating and achieving local finality even when temporarily disconnected from their parent chains, with consistency restored upon reconnection. + +
+ +
+Objective security + +IPC provides checkpoint-based objectivity by periodically anchoring subnet state into parent chains. Checkpoints serve as objective trust anchors that anyone can verify without relying on social consensus or trusted third parties. This secures against long-range attacks: an attacker cannot rewrite history beyond the last committed checkpoint without also compromising the parent chain. New participants can instantly join or follow subnets by obtaining a recent checkpoint on a parent chain, facilitating trustless light clients and dynamic validator set extensions without weak subjectivity. + +
+ +
+Risk containment + +IPC creates natural security boundaries between subnets. Failures, attacks, or misbehavior within one subnet are confined to that subnet's security domain and do not propagate to sibling subnets or compromise the integrity of parent chains. This limits the scope of potential incidents to the assets and operations entrusted to the affected subnet, preventing failures from cascading throughout the network. + +
diff --git a/docs-gitbook/protocol/architecture.md b/docs-gitbook/protocol/architecture.md new file mode 100644 index 0000000000..a5114133bb --- /dev/null +++ b/docs-gitbook/protocol/architecture.md @@ -0,0 +1,61 @@ +# Protocol Architecture + +The fundamental mechanisms of the IPC protocol — what the protocol accomplishes from a conceptual perspective — are described in [Core Mechanisms](core-mechanisms.md). This section focuses on the protocol's architecture — the structural components through which those mechanisms manifest. + +The IPC protocol can be realized through three kinds of components: **on-chain logic**, **subnet validator nodes**, and **cross-chain proxies**. The distribution of responsibilities among these components and their forms depends on the capabilities of the participating chains and architectural decisions. As a result, a single IPC chain can be realized in multiple architectural roles—for example, a subnet may also act as a parent chain to its own child subnets, thus fulfilling multiple architectural roles. + +## On-chain Logic + +On-chain logic is the IPC-specific **transition logic of the replicated state** — the chain state — that makes a chain an IPC participant. It may manifest as built-in or user-deployable smart contracts, built-in protocol rules, or state encoded within a chain's native data structures, depending on the chain's capabilities. On-chain logic does not include coordination mechanisms such as the consensus protocol, where individual validators' state may differ; rather, it encompasses the deterministic state transition rules that all validators agree upon and execute identically. + +The core role of on-chain logic is **verifying** cross-chain data, **enforcing** protocol rules, and **recording** protocol state. The form and sophistication of these operations varies with the chain's programmability — from rich smart contract environments to minimal scripting — but the core verification and rule enforcement are always present in IPC's on-chain logic. + +**Core responsibilities.** On-chain logic is present on both parent chains and subnets: each IPC chain, with respect to each connected chain, performs the following functions. + +- *Checkpoint verification and recording* — verifying the authenticity of checkpoints received from connected chains (e.g. by validating quorum signatures or finality certificates against the recognized configuration of the checkpointed chain) and storing the verified checkpoint data as part of the chain's own state. Stored checkpoints serve as trust anchors for all subsequent cross-chain operations. + +- *Cross-net message handling* — for outgoing messages, recording and batching messages initiated on this chain with checkpoints; for incoming messages validating them against the relevant checkpoint, then either forwarding them or, if addressed to this chain, executing the corresponding state changes such as asset operations or contract calls. + +- *Asset bridging invariant enforcement* — tracking locked and minted assets per connected chain and enforcing that assets released never exceed those previously locked, and assets burned never exceed those previously minted, ensuring the consistency of the lock-mint-burn-release cycle across the bridge. + +- *Reflection of connected chain configuration* — maintaining the configuration parameters of connected chains (such as validator sets and finality requirements) necessary for cross-chain data verification. The reflected configuration is updated via cross-chain operations, for example by processing configuration commitments included in checkpoints or by receiving updates through dedicated cross-net messages. + +- *Own configuration management* — managing the chain's own operational parameters (such as the validator set, consensus settings, and checkpoint period) as part of the replicated state, governing activation points for configuration transitions. + +**Parent-specific responsibilities.** In addition to the above, parent chains carry responsibilities specific to managing their child subnets: maintaining child subnets' identity and registration (the parent acts as a registry), governing subnet lifecycle transitions (activation conditions, operational status, termination procedures), and establishing the initial recognized subnet configuration at activation. + +**Architecture-dependent aspects.** Certain aspects of on-chain logic may vary depending on architectural choices. Subnet ID allocation may follow coordinated on-chain assignment or coordination-less derivation. Checkpoint content assembly — constructing the cryptographic commitments that constitute a checkpoint — may be handled by on-chain logic during periodic state transitions or by other components such as validator nodes or cross-chain proxies. + +*In the current implementation,* on-chain logic is realized through a combination of user-deployed and built-in native smart contracts executed within a general-purpose VM. On the parent chain, a shared per-chain contract handles cross-net message routing, supply accounting, and parent finality tracking, while per-subnet contracts manage validators, collateral, lifecycle, and checkpoint verification. On subnet chains, equivalent contracts handle parent finality, message processing, and checkpoint assembly, with native contracts supporting auxiliary functions such as gas market management and validator activity tracking. + +## Subnet Validator Node + +The subnet validator node is the software run by subnet validators that operates the subnet as a blockchain. It hosts the execution environment in which the subnet-side on-chain logic runs. Although the on-chain logic executes within the validator node, they are conceptually distinct: the node provides the consensus, networking, and execution infrastructure around the on-chain state transition logic. + +**Core blockchain operation.** The validator node's fundamental responsibilities are those of any blockchain node: participating in the consensus protocol to agree on block contents and ordering, executing transactions and producing state transitions (including on-chain IPC logic), and maintaining the subnet's replicated (chain) state. Additionally, the node typically produces justification material — such as block signatures or finality certificates from the consensus mechanism — that can serve as proof of finalized state. This material can later be collected by cross-chain proxies for checkpoint submission to connected chains, or used by connected chains directly for verification. + +**Cross-chain interaction.** Beyond core blockchain operation, validator nodes may participate in cross-chain coordination. How cross-chain data enters the subnet's block processing pipeline is an architectural choice, with two principal approaches. + +In the *direct observation* approach, validator nodes independently monitor the parent chains and coordinate among themselves — for example, through voting within the consensus process — to agree on which parent chain state should be considered finalized. The agreed-upon finality is then recorded via on-chain logic. + +In the *proxy-mediated* approach, validator nodes receive updates from connected chains through cross-chain proxies, accompanied by justification material such as finality certificates and data integrity proofs. The on-chain logic verifies and records this data without the node needing to interact with the connected chains directly. This approach requires the checkpointed chain to produce native finality certificates that the receiving chain's on-chain logic can verify independently. + +These approaches can coexist within the same deployment — for instance, a subnet would typically use direct observation for parent chain finality tracking while relying on a separate cross-chain proxy for submitting checkpoints to the parent. + +*In the current implementation,* the validator node combines a BFT consensus engine ([CometBFT](https://docs.cometbft.com/)) with a general-purpose VM for execution ([FVM](https://docs.filecoin.io/smart-contracts/fundamentals/the-fvm)). Validators directly poll the parent chain, reaching agreement on parent finality through an internal voting protocol or by verifying the parent chain's native finality certificates. Top-down messages and validator set changes are fetched from the parent and incorporated into block proposals. Bottom-up checkpoint content is assembled by on-chain logic during block execution; submission to the parent chain is handled by a separate cross-chain proxy (relay). + +## Cross-Chain Proxy + +The cross-chain proxy acts as an intermediary between connected IPC chains, observing protocol-relevant state on one chain, optionally processing or preparing the data, and then submitting it to another chain. + +**What the proxy does.** The proxy operates through three main tasks: + +- *Observation* — monitoring a chain's finalized state for protocol-relevant data such as checkpoints, cross-net message batches, finality markers, and configuration changes. +- *Preparation* — packaging the observed data for submission to the receiving chain. This may involve collecting justification material (consensus artifacts, finality certificates), constructing data integrity and inclusion proofs, and formatting data according to the receiving chain's verification requirements. +- *Submission* — delivering the prepared data to the receiving chain's network, triggering on-chain protocol operations such as checkpoint recording, message verification and processing, or configuration updates. + +**Trust model.** The proxy is untrusted for correctness: all submitted data is ultimately verified by the receiving chain's state transition logic, and the proxy cannot cause acceptance of invalid data, regardless of the receiving chain's programmability level. The proxy may perform computation such as proof construction or data pre-processing, but this constitutes preparation, not authoritative verification. The proxy is, however, responsible for liveness: if no proxy operates, cross-chain data flow stalls and dependent protocol operations are delayed — but no incorrect state can be introduced through proxy failure. The proxy role is normally permissionless; multiple independent proxies can operate concurrently for reliability. + +**Deployment and scope.** A proxy is typically necessary for the bottom-up direction, since parent chains are generally passive and do not actively track their subnets' state. For the top-down direction, a proxy may or may not be needed, depending on whether subnet validator nodes directly observe the parent chain. A proxy can operate as a standalone process, or its functionality can be embedded within validator nodes or other infrastructure. A single proxy may serve one direction, both directions, or a specific subset of cross-chain data flows. + +*In the current implementation,* a separate proxy process handles the bottom-up direction: it reads BFT-signed block headers and checkpoint data from the subnet and submits them, along with message batch inclusion proofs, to the parent chain's contracts for on-chain verification and processing. No separate proxy handles the top-down direction; validator nodes poll the parent chain directly. diff --git a/docs-gitbook/protocol/core-mechanisms.md b/docs-gitbook/protocol/core-mechanisms.md new file mode 100644 index 0000000000..076d55ddf4 --- /dev/null +++ b/docs-gitbook/protocol/core-mechanisms.md @@ -0,0 +1,83 @@ +# Core Mechanisms + +This section describes IPC's core mechanisms at a conceptual level, explaining what each accomplishes, how it operates, and how it relates to the others. The mechanisms form distinct but complementary parts of the IPC protocol. + +## Checkpointing + +**Purpose and role.** Checkpointing is the foundational mechanism in the IPC protocol that establishes objective trust anchors between IPC chains through periodic state commitments. Its role is to make cross-chain [bridging](#bridging) secure for both asset transfers and general message passing, as well as to enable checkpoint-based objectivity—establishing up-to-date cross-chain state reference points that can be verified without additional trust assumptions. + +**What gets checkpointed.** A checkpoint contains a cryptographic commitment to finalized state of the checkpointed chain. Checkpoints are compact commitments—not full state or transaction data. At minimum, this includes a cryptographic reference uniquely identifying a point in the chain's history (e.g., finalized block's height & hash). Checkpoints may include additional succinct commitments to protocol-relevant state (e.g., validator configurations, cross-net message queues, child subnet checkpoints). + +**How checkpointing operates.** Checkpointing happens periodically and relies on eventual cross-chain connectivity. Finality criteria are applied relative to each chain's own finality mechanism, producing stable reference points that can be checkpointed. These checkpoints are committed to and become part of the target chain's state, serving as verifiable anchors. The initial checkpoint is established during subnet registration, according to the [lifecycle management](#subnet-lifecycle-management) mechanism. The mechanism may operate differently, depending on the protocols adopted in the chains involved and the direction of checkpointing. + +For top-down checkpointing: Normally, subnets would actively track the finality of their parent chains. This may require reaching a prior agreement within the subnet on which parent chain state should be considered finalized and referred to by the next checkpoint. Checkpoints are usually accompanied by justification according to the subnet's finality criteria for the parent chain—such as subnet validator signatures or native parent chain finality certificates. Once determined, corresponding checkpoints are verified and committed by the subnet, making parent state transitions verifiable within the subnet context. + +For bottom-up checkpointing: Since parent chains are assumed more conservative, they typically remain passive in the checkpointing process — their consensus mechanism and validators need no IPC-specific awareness. Finalized subnet state is captured in checkpoints and submitted to the parent chain, accompanied by justification—such as subnet validator signatures—demonstrating the validity of the checkpoint. The parent chain accepts valid checkpoints and stores them without actively tracking subnets. + +**Ensuring correctness.** Checkpoint correctness relies on trust assumptions that the IPC protocol relies upon. IPC chains are assumed to operate correctly within their security domain, and when committing checkpoints, they verify the validity of the new checkpoints with respect to the previous ones. Once checkpoints are committed to the target chain, their immutability depends on the security of that chain; committed checkpoints cannot be revised without compromising the chain storing them. + +**Relationship to other mechanisms.** The [bridging](#bridging) mechanism fundamentally relies on checkpoints—cross-net messages, as well as asset transfers, are verified against checkpointed state and depend on checkpoint-secured state commitments. During subnet registration, [lifecycle management](#subnet-lifecycle-management) facilitates the establishment of initial checkpoints in both directions: checkpoints from subnets to parent chains and checkpoints from parent chains that subnets begin tracking. [Configuration management](#subnet-configuration-management) may use checkpointing to propagate subnet configuration (e.g., validator set changes) from parent chains to subnets. + +## Bridging + +**Purpose and role.** Secured by the [checkpointing](#checkpointing) mechanism, bridging enables cross-chain communication between IPC chains—for both asset transfers and general message passing. This makes subnets interoperable, one of IPC's key capabilities. Beyond basic communication, bridging allows building various coordination patterns (e.g., cross-subnet workflows, atomic operations) that can take advantage of eventual consistency from transitive checkpointing. + +*Note: The current IPC implementation supports only single-hop, i.e. direct parent-to-subnet or subnet-to-parent, cross-net messages.* + +**What gets bridged.** The carrier in all bridging operations are cross-net messages. Top-down messages are those flowing from parent chains to subnets; whereas bottom-up messages flow in the opposite direction. Cross-net messages specify source chain, destination chain, as well as assets to be transferred and/or arbitrary information payload; thus cross-net messages may carry an arbitrary information payload, assets, or both. Messages carrying only assets follow the usual lock-mint-burn-release semantics; messages carrying an information payload — with or without accompanying assets — can trigger arbitrary state transitions (e.g., on-chain contract invocations) on the target chain. Messages with an information payload are referred to as general-purpose (or general) cross-net messages. + +**How bridging operates.** Cross-net messages are initiated as part of state transitions (transactions) on the source chain. Justified with checkpoints from the source chain, cross-net messages are batched and relayed between chains periodically (typically together with checkpoint processing). Once verified against the corresponding checkpoints, cross-net messages are applied to the target chain, triggering corresponding state changes (e.g., contract invocations). + +Asset-carrying cross-net messages are handled according to the usual lock-mint-burn-release semantics. For deposits: assets are locked on the source chain, i.e. held in escrow/custody, and equivalent (wrapped) assets are minted on the destination chain. For withdrawals: (wrapped) assets are burned on the source chain and equivalent assets are released from the escrow/custody on the destination chain. The amount minted in a deposit matches the amount locked; the amount released in a withdrawal matches the amount burned. Thus each asset transfer forms a consistent logical operation spanning both chains. + +**Ensuring correctness.** Chains processing cross-net messages are assumed to operate correctly within their security domain, following protocol rules for message validation and execution. Verification against checkpoints ensures cross-net messages correspond to the actual finalized state of the source chain. + +**Relationship to other mechanisms.** Bridging depends fundamentally on [checkpointing](#checkpointing) for ensuring cross-net message integrity. [Subnet ID management](#subnet-id-management) defines the addressing scheme that enables path resolution and routing of cross-net messages across IPC chains. + +## Subnet ID Management + +**Purpose and role.** Subnet ID management provides unambiguous identification for subnets across IPC chains. This identification supports addressing and routing for cross-chain communication, as well as subnet discovery for nodes joining or following subnets. The mechanism governs ID namespace management and subnet ID assignment. + +**Key elements and properties.** Subnet IDs are identifiers that designate subnets within IPC. Subnet IDs could be organized and scoped using namespaces (which in principle may differ from subnet topology), with each subnet uniquely identified within its scope. Subnet IDs are unambiguous and stable across time, enabling reliable addressing and routing. Different ID schemes may have additional characteristics (e.g., they may reflect parent-child relationships between subnets). + +**Operating principles.** Unambiguous identification requires uniqueness within the ID's scope—no two subnets can share the same identifier in their namespace. Moreover, once assigned, subnet IDs must remain stable and cannot change. When applicable, governance rules can enforce specific policies within namespaces (e.g., permissioned ID allocation). Structured ID schemes could enable direct mapping from subnet IDs for subnet discovery and routing mechanisms. Subnet ID assignment can follow different approaches, e.g. coordinated ID allocation during subnet registration on parent chain, or coordination-less ID assignment with collision-resistant derivation from subnet's genesis state. For example, the current implementation favors coordinated assignment on the parent chain with hierarchical ID structure that corresponds to subnet topology. Validity of subnet IDs depends on the assignment mechanism: coordinated schemes validate through parent chain records, while derivation-based schemes could allow direct verification against genesis state. Additional format constraints (e.g., hierarchy depth or length limits) may apply depending on the adopted scheme. + +**Relationship to other mechanisms.** Subnet ID assignment occurs as part of subnet registration managed by [lifecycle management](#subnet-lifecycle-management). [Bridging](#bridging) depends on subnet IDs for addressing and routing cross-net messages. [Checkpointing](#checkpointing) may also use subnet IDs to identify which chain's state is being checkpointed. + +## Subnet Lifecycle Management + +**Purpose and role.** Subnet lifecycle management governs the operational status of a parent chain's subnets. This mechanism covers how new subnets are registered, how they become active, and how they are eventually terminated. These transitions determine when a subnet begins and ceases participating in [checkpointing](#checkpointing) and [bridging](#bridging), and must account for cross-chain obligations such as locked assets and pending messages. + +**Key elements and properties.** A subnet's lifecycle on the parent chain begins with registration and proceeds through further transitions. Registration makes the subnet known to the parent chain; a subnet ID is assigned as part of this process. + +Initial activation marks the point at which the subnet begins participating in checkpointing and bridging. The activation may occur at registration time or as a separate transition, depending on the policies in effect. Activation may be conditioned on subnet configuration-level criteria, such as a minimum number of validators or a collateral threshold being met. In either case, activation establishes the subnet's initial configuration on the parent chain and marks the beginning of the checkpointing relationship between the subnet and parent chains. + +Termination concludes the subnet's operation, with any remaining cross-chain obligations resolved. Termination may occur upon request or as a consequence of the subnet no longer meeting the conditions required to remain active. + +Lifecycle transitions are secured by the parent chain, which records and enforces the subnet's operational status. The policies governing these transitions are highly customizable, allowing different subnet types to define their own registration, activation, and termination criteria. Because lifecycle is managed on-chain, subnets can be created and terminated programmatically, enabling the network to expand and contract in response to demand. Lifecycle transitions properly account for cross-chain obligations such as locked assets and pending messages. + +**Operating principles.** Lifecycle transitions are recorded on the parent chain, but certain transitions, particularly termination, may require the subnet's cooperation or agreement. The effect of a lifecycle transition on the parent chain is propagated to the subnet through top-down checkpointing and cross-net messaging. The subnet must recognize and act on lifecycle transitions that affect its own operation. + +Upon activation, the subnet and its parent chain establish their checkpointing relationship: the subnet begins tracking finalized parent chain state, and the parent chain begins accepting checkpoints from the subnet. Bridging becomes available once this relationship is established. + +Termination requires that pending cross-net messages are processed and that locked assets are properly released before the subnet is considered fully terminated. Active checkpointing and bridging cease as part of the termination process. Until termination is complete, the relevant cross-chain mechanisms continue operating as needed to resolve remaining obligations. + +**Relationship to other mechanisms.** A subnet ID is assigned during the registration process, as governed by the [subnet ID management](#subnet-id-management) mechanism. Lifecycle and [configuration management](#subnet-configuration-management) are closely related; activation may depend on configuration-level criteria, and configuration changes may in turn trigger lifecycle transitions such as deactivation. Checkpointing and bridging operate while the subnet is active; activation establishes the initial checkpointing relationship, and termination brings it to an end. Lifecycle transitions account for in-flight cross-net messages and locked assets managed by the bridging mechanism. + +## Subnet Configuration Management + +**Purpose and role.** Subnet configuration management governs how the operational parameters of a subnet chain as a whole are defined, updated, and take effect. Such parameters include, for example, the validator set and power allocation, consensus parameters, fee settings, etc. The role of this mechanism is to ensure orderly transitions between subnet configurations, so that all participants in the subnet and its parent chain maintain a consistent view of the subnet's current operational parameters. + +**Key elements and properties.** A subnet's configuration encompasses the operational parameters that define the overall behavior and security of the subnet chain, as opposed to the state of individual accounts or smart contracts running on it. These parameters typically include the validator set and allocation of voting power, consensus parameters, checkpoint period, governance and fee settings, among others. + +Configuration authority — the governance of how configuration changes are proposed, validated, and approved — may reside on the parent chain, within the subnet itself, or involve both, depending on the policies adopted for a given subnet. In the current implementation, for instance, validator membership and collateral are managed through parent chain contracts, representing a parent-governed approach, though their activation for bottom-up checkpoint validation requires a round-trip acknowledgment from the child subnet. + +Configuration changes take effect at well-defined activation points, such as checkpoint or epoch boundaries, to ensure that all participants transition to the new configuration consistently, and may additionally be subject to an activation delay. + +**Operating principles.** The initial subnet configuration, which needs to be reflected on the parent chain, is established at subnet activation, as governed by the [lifecycle management](#subnet-lifecycle-management) mechanism. Subsequent configuration changes are governed according to the subnet's policies, which determine who may propose and approve changes, under what conditions, and through what process. + +When configuration authority resides on the parent chain, proposed changes are validated, enforced, and maintained there, and propagated to the subnet through cross-net messages. The subnet applies the new configuration at a designated activation point and would normally acknowledge this in subsequent bottom-up checkpoints. In case configuration authority resides within the subnet, changes are applied directly to the subnet chain and communicated to the parent chain through cross-net messages and/or checkpoints carrying configuration commitments. The parent chain accepts such updates, having verified them against the configuration it currently recognizes. Hybrid approaches, combining elements of both parent-governed and subnet-governed configuration management, are also possible. + +Regardless of where configuration authority resides, configuration changes may be subject to an activation delay between approval and taking effect, giving participants time to observe and prepare for upcoming transitions. + +**Relationship to other mechanisms.** The IPC on-chain logic on the parent chain typically needs to be aware of the subnet's current configuration in order to verify the authenticity of bottom-up checkpoints — for example, to validate signatures in PoS or PoA subnets. Bottom-up checkpoints may carry configuration commitments, serving as a vehicle for communicating subnet configuration updates to the parent chain. Cross-net messaging, as part of the [bridging](#bridging) mechanism, may serve as the carrier for propagating configuration changes between chains. At subnet activation on the parent chain, [lifecycle management](#subnet-lifecycle-management) establishes the initial subnet configuration as reflected there. Configuration changes may have lifecycle implications — for example, the validator set falling below a required minimum may cause the subnet to be deactivated. Conversely, lifecycle transitions may be reflected in configuration updates. diff --git a/docs-gitbook/protocol/requirements-and-guarantees.md b/docs-gitbook/protocol/requirements-and-guarantees.md new file mode 100644 index 0000000000..4e49a535ba --- /dev/null +++ b/docs-gitbook/protocol/requirements-and-guarantees.md @@ -0,0 +1,45 @@ +# Requirements & Guarantees + +IPC operates under specific requirements and assumptions while providing corresponding security and operational guarantees. + +## Requirements + +- **Stable reference points.** + + IPC chains must produce state commitments that become stable and serve as reliable anchors for checkpoints. Whether achieved through deterministic or probabilistic mechanisms, stable commitments are considered practically final and immutable. + +- **Minimal chain capabilities.** + + IPC chains must support: recording arbitrary data on-chain (e.g., checkpoints, cross-net messages); trust-minimized asset bridging (lock-mint-burn-release operations); and enforcement of IPC governance mechanisms (i.e. subnet ID assignment, subnet lifecycle management, and subnet configuration updates). The required on-chain programmability is minimal by design to support diverse blockchain environments. + +- **Cross-chain connectivity.** + + Subnets maintain eventual connectivity with their parent chain networks for checkpointing and bridging, tolerating temporary partitions. Continuous connectivity is not required—subnets can operate autonomously during poor connectivity periods and synchronize once connectivity is restored. + +## Assumptions + +- **Parent chain security dominance.** + + Parent chains are assumed more secure than their subnets. This security relationship holds recursively up to the rootnet. + +- **Parent chain conservativeness.** + + Parent chains are assumed to be more conservative in adopting changes than their subnets. Parent chains maintain higher protocol stability while subnets can be heavily specialized or adopt experimental functionality. + +- **Bounded subnet security.** + + Subnets are assumed to operate correctly in managing delegated assets and their own state, within subnet's security strength. Users delegating assets accept risks according to the subnet's security parameters. + +## Core Guarantees + +- **Checkpoint-based objectivity.** + + Checkpoints committed to a trusted chain establish objective reference points to recent state of the checkpointed chain, verifiable without trust assumptions beyond the security of the chain they are committed to. Those reference points objectively mitigate long-range attacks, i.e. attempts to create alternative chain histories beyond the last committed checkpoint. + +- **Risk containment.** + + The impact of any subnet misbehavior is limited to assets and operations delegated to that subnet, with no further propagation to parent chains or sibling subnets. Failures within a subnet affect only that subnet's security domain. + +- **Eventual consistency.** + + Transitively checkpointing IPC chains into a common trusted chain establishes eventual consistency among them. Chains sharing common trusted checkpoint anchors can verify each other's state and coordinate cross-chain operations. diff --git a/docs-gitbook/protocol/security-and-economics.md b/docs-gitbook/protocol/security-and-economics.md new file mode 100644 index 0000000000..794d45f5e4 --- /dev/null +++ b/docs-gitbook/protocol/security-and-economics.md @@ -0,0 +1,87 @@ +# Security & Economics + +## Security Model & Properties + +This section provides a unified security perspective on the IPC protocol, building on the [requirements, assumptions, and guarantees](requirements-and-guarantees.md) and the correctness arguments in [Core Mechanisms](core-mechanisms.md). + +**Adversary model.** The IPC security model considers the following classes of adversarial behavior. + +- **Byzantine faults within subnets.** Up to some threshold of validators may exhibit [Byzantine faults](https://en.wikipedia.org/wiki/Byzantine_fault), as determined by the subnet's consensus mechanism (e.g., up to one-third of voting power for typical BFT-based consensus). Below this threshold, the protocol's security guarantees hold; above it, the subnet may make incorrect state transitions, but the resulting damage is bounded to the subnet's own security domain. + +- **Full subnet compromise.** In the worst case, validators may collude beyond the consensus threshold. A compromised subnet could produce arbitrary state, submit false checkpoints, and even steal assets delegated to it. However, it cannot affect sibling subnets or parent chains beyond the subnet's circulating supply, due to the bridge safety invariants enforced by on-chain logic. + +- **Cross-chain proxy misbehavior.** Proxies may exhibit arbitrary behavior. A proxy that fabricates data has no effect: all submitted data is verified by the receiving chain's on-chain logic, which rejects invalid submissions. A proxy that withholds data (omission) could stall cross-chain communication but cannot cause incorrect state transitions. Redundancy through multiple independent proxies readily mitigates omission. + +- **Out of scope.** The security model does not consider breaks in cryptographic primitives, parent chain compromise (assumed secure for this analysis), or social-layer and client-side attacks. + +**Trust hierarchy.** IPC establishes a layered trust structure with the following properties. + +- **Rootnet as root of trust.** The rootnet has no parent chain and requires the highest level of security. Each parent chain is assumed to be strictly more secure and more conservative than its subnets, recursively up to the rootnet. + +- **Subnet anchoring.** Subnets are anchored into their parent chains through periodic checkpoints, which provide objective, verifiable reference points for the subnet's state. This anchoring does not fully transfer the parent's security properties to the subnet; the subnet's own security depends on its own validators and consensus mechanism. Rather, the anchoring provides an objective basis for verifying the subnet's state from outside the subnet. + +- **Upward risk containment.** A subnet cannot compromise its parent chain's integrity. This containment is enforced by on-chain logic on the parent chain, specifically checkpoint and cross-net message verification, as well as per-subnet supply accounting. + +- **User risk acceptance.** Users who deposit assets into a subnet accept the security domain of that subnet; their exposure is limited to the assets they have delegated to it. + +- **Independent evaluability.** The security of any individual subnet can be assessed based on its own validator set, consensus mechanism, and governance policies, independently of other subnets. + +**Security properties.** The IPC protocol offers the following guarantees, each grounded in the mechanisms and assumptions described throughout the protocol description. + +- **Checkpoint integrity.** Committed checkpoints faithfully reflect the finalized state of the checkpointed chain. This relies on two complementary factors: the checkpointed chain operating correctly within its security domain, producing genuine checkpoints; and the receiving chain verifying incoming checkpoints against the recognized configuration of the checkpointed chain (e.g., validating quorum signatures against the known validator set). Checkpoint integrity is foundational — all cross-chain operations built on checkpoints, including bridging and message verification, depend on this property. + +- **Checkpoint-based objectivity.** Checkpoints committed to a trusted chain serve as objective, independently verifiable reference points to the checkpointed chain's recent state. This mitigates long-range attacks: an adversary cannot rewrite a chain's history beyond the last committed checkpoint without also compromising the chain storing it. Checkpoint-based objectivity also enables trustless bootstrapping, allowing new participants to verify and join a chain by obtaining a recent checkpoint from a trusted chain, without relying on social consensus. + +- **Bridge safety.** The lock-mint-burn-release cycle is consistent across chains. On-chain supply accounting enforces the invariant that released amounts never exceed previously locked amounts and burned amounts never exceed previously minted amounts. Each deposit and withdrawal forms a matching pair across both chains. Cross-net messages carrying assets are verified against the corresponding checkpoints before execution. + +- **Risk containment.** A compromised subnet can only affect assets and operations that have been delegated to it. It cannot inflate the parent chain's supply or corrupt sibling subnets' state. This is enforced through per-subnet supply accounting and verification of cross-net messages against checkpoints. + +- **Liveness.** Proxy or relayer failure can delay cross-chain data flow but cannot cause incorrect state transitions. A subnet that becomes temporarily partitioned from its parent chain continues operating autonomously, achieving local finality; consistency is restored upon reconnection. + +**Security boundaries and risk analysis.** The following discusses the consequences of different component failures and violations of protocol assumptions. + +- **Subnet compromise.** If too many subnet validators collude, they can cause invalid state transitions and submit false checkpoints, potentially leading to unauthorized extraction of assets from the subnet. While the parent chain would accept these checkpoints if they pass quorum verification, the impact remains capped by on-chain logic that limits asset release to the subnet's circulating supply. The risk does not propagate to the parent chain or sibling subnets. This threat can be effectively mitigated by ensuring robust validator diversity, requiring adequate collateral from subnet validators, and enforcing slashing mechanisms for provable misbehavior (see open questions below). + +- **Proxy/relayer failure.** If proxies fail or withhold data, cross-chain communication could stall — checkpoints and cross-net messages delayed. However, no incorrect state can be introduced. To ensure reliability, multiple independent proxies can operate concurrently for redundancy. + +- **Temporary partition.** If a subnet becomes disconnected from its parent chain, it continues operating and achieving local finality. But cross-chain operations — deposits, withdrawals, and configuration updates — would stall until connectivity is restored. Staleness of cross-chain state is bounded by the duration of partitioning. Mitigations include resilient network connectivity, monitoring, and automatic reconnection. + +- **Parent chain reorg beyond checkpoint.** If the parent chain reverts state beyond what the subnet has already checkpointed, this violates the stable reference points requirement. The subnet may have committed state based on now-reverted parent state. With immediate-finality parent chains, this scenario does not arise. With probabilistic finality, conservative confirmation depth mitigates the risk. Choosing finality criteria conservatively and monitoring for parent chain divergence are the primary mitigations. + +**Open questions and limitations.** There are some areas where the current security model could be further developed or refined. + +- **Accountability.** No formal accountability mechanism is specified yet. Such a mechanism is critical for deterring validator misbehavior. The protocol will include slashing of collateral upon provable misbehavior as a core deterrent. + +- **Fraud and validity proofs.** The protocol achieves simplicity and efficiency by relying on quorum-based trust for checkpoints rather than performing verification of subnets' full state transitions. + +- **Multi-hop routing security.** Security of routing cross-net messages through intermediate chains is not yet fully analyzed. Only single-hop messaging (direct parent-to-subnet or subnet-to-parent) is currently enabled. + +- **Timing and latency bounds.** Formal bounds on checkpoint latency, finality propagation delay, and partition tolerance are not yet specified. + +## Economic Incentives + +The IPC protocol involves several participant roles — subnet validators, cross-chain proxies, and users who delegate assets and operations to subnets — each with distinct incentive requirements. Economic mechanisms serve to align these participants' behavior with correct protocol operation and sustained participation. Three main categories of economic mechanisms are relevant: collateral and slashing, transaction fees, and cross-chain proxy incentivization. These mechanisms are highly customizable per subnet; their specific parameters form part of the subnet's configuration. + +**Collateral and slashing.** Validator collateral, introduced in [Subnet Lifecycle Management](core-mechanisms.md#subnet-lifecycle-management) and [Joining & Leaving Subnets](workflows.md#joining--leaving-subnets), is a prerequisite for validator participation in collateral-based subnets. Collateral is locked on a chain capable of enforcing it against validators — typically the parent chain, given its higher security, though the choice depends on where configuration authority resides. The key property is that validators cannot unilaterally reclaim their collateral; its release is governed by protocol rules. Collateral thus creates direct financial exposure to the subnet's correct operation, aligning validators' economic interest with honest behavior. The collateral amount may determine a validator's voting power allocation or be uniform across validators, depending on the subnet's policies. + +Slashing — partial or full forfeiture of collateral upon provable misbehavior — complements consensus-level fault tolerance with economic consequences. Slashing targets behaviors that are verifiable on-chain or provable to the enforcing chain, such as equivocation. The conditions under which slashing is triggered, the severity of penalties, and the adjudication process — including what constitutes sufficient proof and who evaluates it — are customizable per subnet. + +Collateral also serves a lifecycle function: it may gate subnet activation and is subject to unbonding delays upon validator departure, ensuring that validators remain accountable for recent behavior before reclaiming their stake. + +*In the current implementation,* collateral is managed through IPC contracts on the parent chain. In collateral-based (permissionless) subnets, voting power is proportional to staked collateral; federated subnets have power assigned by the subnet owner; a static mode fixes power at the initial collateral amounts. Departed validators' collateral enters a timed release queue and must be explicitly claimed. Slashing is not yet implemented. + +**Fees.** Subnets define their own fee models as part of their configuration. Transaction fees generally serve two purposes: preventing spam and denial-of-service by imposing a cost on consuming chain resources, and compensating validators for the computational and infrastructure costs of operating the subnet. Fee parameters — including the pricing mechanism (e.g. fixed fees, auction-based pricing, or dynamic gas markets), fee recipient policies, and fee levels — are customizable per subnet. This flexibility enables a range of fee models, from conventional gas markets to subsidized or entirely fee-free operation for specialized or private subnets. The fee model is internal to each subnet; the IPC protocol does not prescribe a specific fee structure. + +*In the current implementation,* subnets use an [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)-style dynamic gas market, with base fee adjustment driven by block utilization and gas premiums routed to the block producer. Validator rewards are additionally supported through an activity-tracking pipeline: per-validator consensus participation is recorded on the subnet, propagated to the parent chain via checkpoints, and used for reward distribution through a pluggable reward contract supplied at subnet deployment. No default reward policy is prescribed. Cross-net message fees are not currently charged. + +**Cross-chain proxy incentivization.** Cross-chain proxies bear operational costs, including transaction fees on receiving chains and the infrastructure required for monitoring and data submission. Although the proxy role is permissionless, sustained and reliable operation requires positive economic incentive. In practice, subnet validators often serve as cross-chain proxies as well, since they already maintain the necessary infrastructure and have a direct economic stake in the subnet's cross-chain liveness. Dedicated incentivization mechanisms can additionally support independent proxy operators, improving redundancy and reliability of cross-chain data flow. No specific proxy incentivization mechanism is currently specified in the protocol. + +*Currently,* cross-chain proxies receive no on-chain incentives; validators are expected to handle relaying as part of their normal operations. + +**Open questions.** +- *Slashing conditions and adjudication.* Specific conditions for slashing, evidence requirements, and adjudication mechanisms remain to be defined. +- *Reward distribution.* Models for distributing rewards to validators — such as block rewards, fee sharing, or inflation-based subsidies — are not yet specified. +- *Cross-chain fee coordination.* It is not yet determined how fees for cross-net message execution on the destination chain are accounted for and settled. +- *Proxy incentivization mechanism.* A concrete mechanism for compensating cross-chain proxies — and its interaction with validator incentives — has not been designed. +- *Economic parameter propagation.* How economic parameters (e.g. fee policies, slashing rules) propagate and interact across the subnet hierarchy is an open area. +- *MEV considerations.* The implications of [maximal extractable value](https://ethereum.org/en/developers/docs/mev/) in cross-chain message ordering have not yet been analyzed. diff --git a/docs-gitbook/protocol/workflows.md b/docs-gitbook/protocol/workflows.md new file mode 100644 index 0000000000..6e8dcf2d70 --- /dev/null +++ b/docs-gitbook/protocol/workflows.md @@ -0,0 +1,45 @@ +# Protocol Workflows + +This section describes the key workflows of the IPC protocol — the end-to-end processes through which subnets are created and terminated, validators join and leave, assets are deposited and withdrawn, and chains exchange messages. + +## Creating & Terminating Subnets + +**Creating a subnet.** The process begins with **registration** on the parent chain, which assigns a subnet ID and records the subnet's parameters — such as its permission mode, checkpoint period, and supply asset types. The parent chain maintains the authoritative record of the subnet as its child. + +Registration may be followed by a separate **activation** step, depending on the policies in effect. Activation may be gated by configuration-level criteria — for example, a minimum number of validators or a collateral threshold. Until these criteria are met, the subnet remains registered but inactive. Once activation occurs, the subnet's initial configuration is established on the parent chain, and the checkpointing relationship between the subnet and its parent begins; bridging becomes available. The subnet network is normally instantiated as part of activation. In principle, support for anchoring an already-running chain as a new subnet could also be implemented, allowing such chains to integrate into the IPC hierarchy. + +**Terminating a subnet.** Termination concludes a subnet's participation in IPC. Before the subnet can be fully terminated, all cross-chain obligations need to be resolved: locked assets released and pending messages processed. Checkpointing and bridging should continue until these obligations are fulfilled. Termination may be initiated explicitly or triggered by lifecycle rules — for example, the validator count dropping below a threshold. The termination process may require the subnet's cooperation. + +*In the current implementation,* IPC contracts on the parent deploy a per-subnet contract; registration additionally requires approval from the parent chain's IPC contract owner. Activation occurs automatically when collateral and validator thresholds are met, or when the owner designates a federated validator set. Termination requires all validators to have departed and the parent's recorded circulating supply for the subnet to be zero. + +## Joining & Leaving Subnets + +**Joining.** The policies governing validator admission may range from open to restricted. Open policies may require locking assets (collateral) on the parent chain as a condition of participation; restricted policies may limit validator set changes to a designated authority. The specific policies are part of the subnet's settings. + +Before activation, validator set composition feeds into the subnet's initial configuration, assembling the set that will operate the subnet from its start. After activation, validator set changes follow the rules of [configuration management](core-mechanisms.md#subnet-configuration-management): both the parent chain and the subnet need a consistent view of the current validator set, and cross-chain confirmation ensures this consistency. Changes take effect at designated activation points. + +**Leaving.** Departure conditions mirror the joining policy. Any resources committed during joining — such as collateral — become reclaimable according to the applicable rules, which may impose delays or conditions such as waiting for cross-chain confirmation or an unbonding period. Validator departures may also have lifecycle implications: if the departure causes the subnet to fall below its activation thresholds, the subnet may be deactivated. + +*In the current implementation,* collateral-based subnets allow permissionless joining by locking collateral via IPC contracts on the parent; federated subnets have their validator set managed by the subnet owner. Post-activation changes are confirmed through bottom-up checkpoints carrying configuration numbers. An active validator limit caps the consensus set, with excess validators placed in a waiting pool. Collateral from departed validators enters a release queue and must be explicitly claimed. + +## Depositing & Withdrawing Assets + +**Depositing.** To deposit assets into a connected chain, assets are locked on the origin chain — held in custody — and a cross-net message triggers minting of equivalent assets on the destination. The locked assets remain in custody on the origin chain for the lifetime of the deposit. The types of assets accepted are determined by the chain capabilities and bridging settings. + +**Withdrawing.** Withdrawals reverse the deposit process: assets are burned on the source chain, and a cross-net message triggers release of equivalent locked assets on the origin. Withdrawal messages are verified against checkpoints before assets are released. + +**Supply accounting.** Each side of the bridge tracks the amounts locked and minted per connected chain, enforcing that released or burned amounts never exceed what was previously locked and minted, respectively. This invariant preserves the integrity of the lock-mint-burn-release cycle across the bridge. Initial circulating supply may be established at activation. Participants may commit assets before activation, forming the subnet's starting supply; these commitments can be reclaimed if activation does not proceed. + +*In the current implementation,* deposits lock native or [ERC-20](https://eips.ethereum.org/EIPS/eip-20) assets via IPC contracts on the parent and commit a top-down transfer message; the subnet credits the recipient in its native asset after observing parent finality. Withdrawals burn native assets on the subnet and batch the resulting bottom-up messages into periodic checkpoints; IPC contracts on the parent verify the batch against the checkpoint commitment, decrease the subnet's recorded circulating supply, and release assets to the recipient. Pre-activation funding allows participants to commit assets to the subnet's genesis circulating supply. + +## General Message Passing + +Cross-net messages can carry an information payload, assets, or both. Deposits and withdrawals, described in [Depositing & Withdrawing Assets](#depositing--withdrawing-assets), are a specialization — a single message can also combine a value transfer with an information payload, enabling patterns such as invoking on-chain logic on another chain while simultaneously transferring assets. + +**Message flow.** Top-down and bottom-up flows share the same message structure and routing infrastructure. Top-down messages are typically applied on the subnet after it observes and checkpoints finalized parent state. Bottom-up messages are batched and verified against checkpoints on the parent. + +**Execution and results.** At the destination, message execution can trigger on-chain logic. Result messages route back to the sender, enabling request-response patterns across chains. Results for result messages are not generated, preventing infinite loops. + +**Multi-hop routing.** Messages between non-adjacent chains can route through the hierarchy via their common ancestor. At each intermediate chain, the message is validated and forwarded; the common ancestor serves as the pivot where routing transitions from bottom-up to top-down. + +*In the current implementation,* messages use a uniform envelope with kind (transfer, call, result), source and destination addresses, value, and an encoded payload. Top-down messages are committed on the parent and applied on the subnet after parent finality is observed; bottom-up messages are batched per checkpoint period and verified via [Merkle proofs](https://en.wikipedia.org/wiki/Merkle_tree) on the parent. General-purpose messages invoke a handler interface on the destination contract. Only single-hop messaging is currently fully supported. diff --git a/docs-gitbook/reference/glossary.md b/docs-gitbook/reference/glossary.md new file mode 100644 index 0000000000..682bd1ec06 --- /dev/null +++ b/docs-gitbook/reference/glossary.md @@ -0,0 +1,61 @@ +# Glossary + +**Activation (subnet).** The lifecycle transition at which a registered subnet becomes operational and its checkpointing relationship with the parent chain begins. + +**Activation point (subnet configuration).** A well-defined boundary — such as a checkpoint or epoch boundary — at which configuration changes take effect. + +**Bottom-up message.** A cross-net message flowing from a subnet to its parent chain. + +**Bridging.** The IPC mechanism for secure transfer of information and assets between connected chains. + +**Checkpoint.** A compact cryptographic commitment to a chain's finalized state, submitted to and recorded on a connected chain. + +**Checkpoint-based objectivity.** The property that checkpoints committed to a trusted chain serve as objective, independently verifiable reference points to the checkpointed chain's state — without relying on social consensus or trusted third parties. + +**Circulating supply (subnet).** The amount of assets currently locked on the parent chain on behalf of a subnet — increased by deposits and decreased by withdrawals. + +**Collateral.** Assets locked on the parent chain as a condition for validator participation in a subnet. + +**Cross-chain proxy.** An intermediary that observes protocol-relevant state on one IPC chain, prepares the data (e.g. constructing proofs), and submits it to another chain. Untrusted for correctness but responsible for liveness. + +**Cross-net message.** The carrier for all bridging operations between IPC chains, specifying source and destination chains, and carrying assets, an arbitrary information payload, or both. + +**Deposit.** A cross-net message that locks assets on the origin chain and mints equivalent (wrapped) assets on the destination chain. + +**Eventual consistency.** The property that IPC chains transitively checkpointing into a common trusted chain can verify each other's state and coordinate cross-chain operations. + +**Finality certificate.** Cryptographic justification — such as quorum signatures or native finality proofs — demonstrating that a checkpoint corresponds to finalized state of the checkpointed chain. + +**General (cross-net) message.** A cross-net message carrying an information payload — with or without accompanying assets — that can trigger arbitrary state transitions (e.g. contract invocations) on the destination chain. + +**IPC chain.** Any blockchain participating in the IPC protocol, whether a rootnet or a subnet. + +**Multi-hop routing.** Routing a cross-net message between non-adjacent chains through intermediate chains via their common ancestor. + +**On-chain logic.** The deterministic transition logic of a chain's replicated state. It may manifest as smart contracts, built-in protocol rules, or native data structures, depending on the chain's capabilities. + +**Parent chain.** The blockchain into which a subnet's state is anchored via periodic checkpoints. Parent chains are assumed to be more secure and more conservative than their subnets. + +**Registration (subnet).** The initial lifecycle step that makes a subnet known to its parent chain by recording the subnet's parameters and assigning it a subnet ID. + +**Risk containment.** The guarantee that failures, attacks, or misbehavior within one subnet are confined to that subnet's security domain and do not propagate to parent chains or sibling subnets. + +**Rootnet.** An IPC chain with no parent chain, serving as the root of trust for the IPC hierarchy. + +**Subnet.** An autonomous blockchain whose state is anchored into a parent chain via periodic checkpoints. + +**Subnet configuration.** The operational parameters defining a subnet chain's overall behavior and security — such as the validator set and voting power allocation, consensus parameters, checkpoint period, and fee settings — as opposed to the state of individual accounts or contracts. + +**Subnet ID.** An unambiguous, stable identifier assigned to a subnet, used for addressing and routing of cross-net messages as well as subnet discovery. + +**Subnet validator node.** The software run by subnet validators that operates the subnet as a blockchain, hosting consensus, networking, and execution infrastructure around the on-chain state transition logic. + +**Supply accounting.** Tracking the amounts of assets locked and minted per connected chain to enforce that released or burned amounts never exceed what was previously locked and minted, respectively. + +**Termination (subnet).** The lifecycle transition that concludes a subnet's operation, after resolving all cross-chain obligations. + +**Top-down message.** A cross-net message flowing from a parent chain to a subnet. + +**Validator set.** The set of validators operating a subnet, along with their voting power allocation. + +**Withdrawal.** A cross-net message that burns (wrapped) assets on the source chain and releases equivalent locked assets on the origin chain.