Enhance Documentation: Add New Section on how it works and update current docs

.gitignore

@@ -1,3 +1,4 @@
 target/
 .idea
-node_modules/
+node_modules/
+.vscode

docs-gitbook/SUMMARY.md

@@ -2,45 +2,45 @@
 
 ## Overview
 
-* [Introduction](README.md)
-* [Use cases](overview/use-cases.md)
-* [How IPC compares](overview/how-ipc-compares.md)
-* [Architecture](overview/architecture.md)
+- [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)
 
 ## Quickstarts
 
-* [Deploy a subnet](quickstarts/deploy-a-subnet.md)
+- [Deploy a subnet](quickstarts/deploy-a-subnet.md)
 
 ## Concepts
 
-* [Subnets](concepts/subnets/README.md)
-  * [Parent-child interactions](concepts/subnets/parent-child-interactions.md)
-* [Circulating supply](concepts/circulating-supply.md)
+- [Subnets](concepts/subnets/README.md)
+  - [Parent-child interactions](concepts/subnets/parent-child-interactions.md)
+- [Circulating supply](concepts/circulating-supply.md)
 
 ## User guides
 
-* [Performing transactions in a subnet](user-guides/performing-transactions-in-a-subnet.md)
+- [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)
-  * [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)
+- [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)
 
 ## Specifications
 
-* [Addressing](../specs/addressing.md)
-* [CometBFT](../specs/cometbft.md)
-* [IPLD Resolver](../specs/ipld-resolver.md)
-* [Materializer](../specs/materializer.md)
-* [Top-down Finality](../specs/topdown.md)
-
+- [Addressing](../specs/addressing.md)
+- [CometBFT](../specs/cometbft.md)
+- [IPLD Resolver](../specs/ipld-resolver.md)
+- [Materializer](../specs/materializer.md)
+- [Top-down Finality](../specs/topdown.md)
 
 ## Reference
 
-* [Networks](reference/networks.md)
-* [IPC CLI](reference/ipc-cli-usage.md)
-* [Troubleshooting](reference/troubleshooting.md)
-* [FAQ](reference/faq.md)
+- [Networks](reference/networks.md)
+- [IPC CLI](reference/ipc-cli-usage.md)
+- [Troubleshooting](reference/troubleshooting.md)
+- [FAQ](reference/faq.md)

docs-gitbook/overview/how-ipc-compares.md

@@ -6,19 +6,28 @@ description: >-
 
 # How IPC compares
 
+## **Benefits of IPC Design**
+
+The IPC framework offers several significant benefits:
+
+- **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.
+
 ## **Highly customizable without compromising security**
 
 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. 
 
 ## **Multi-chain interoperability** 
 
-* 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.
+- 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.
 
 ## **Compute-Storage Interoperability with Filecoin and more** 
 
 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.
 
 ## **Increased performance**
 
-IPC’s modular runtime enables the creation of truly flexible blockchains to increase thoughput while managing gas efficiency. Developers can dynamically adjust their throughput by spawning and closing temporary subnets as needed.
+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.

docs-gitbook/overview/how-it-works.md

@@ -0,0 +1,26 @@
+---
+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.