Conversation
…erence, protocol capture, and user guides - Added comprehensive architecture overview detailing components, communication flows, and security model. - Introduced quick reference guide for core concepts and CLI commands. - Created protocol capture document outlining IPC mechanisms and components. - Updated README to include links to new documentation resources for users and developers.
…detail - Reorganized the table of contents for improved navigation. - Updated the introduction section to provide a clearer overview of IPC. - Expanded on core concepts and added new sections on operation and appendices. - Enhanced descriptions of IPC mechanisms, emphasizing scalability, customizability, and security features.
…nd definitions section - Renamed "Concepts" to "Primitives & Definitions" for clarity. - Added detailed definitions for key IPC concepts to enhance understanding. - Improved navigation by linking definitions to relevant sections in the document.
…tatus and consensus details - Clarified the flexible consensus section to indicate that CometBFT is currently the only implemented mechanism, with plans for rollups and sequencer-based subnets. - Added an implementation status note to highlight the current limitations and future intentions regarding consensus mechanisms. - Marked the VoteTally mechanism as deprecated, indicating its upcoming removal.
…e diagrams - Added new architecture diagrams to illustrate IPC's simplified and detailed structures, as well as the validator lifecycle and fund/release operations. - Updated sections to include visual aids for better understanding of IPC mechanisms and processes.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| ### 4. Validator Lifecycle Diagram | ||
| State transitions and operations for validators throughout their lifecycle. | ||
|
|
||
|  |
There was a problem hiding this comment.
Image paths reference local .cursor IDE directory
High Severity
All four image references in this file point to ../../.cursor/projects/Users-philip-github-ipc/assets/, which is a local Cursor IDE project path specific to one developer's machine. These images will be broken for every other reader. The sibling file protocol-capture.md correctly uses ./img/ relative paths for its images, suggesting these paths were never updated from a local workspace reference.
There was a problem hiding this comment.
Now that IPC contracts being redesigned, maybe we better refer to them more abstractly, as IPC actors/contracts?
There was a problem hiding this comment.
Similarly, we may consider renaming "Fendermint Node" to something like "IPC Subnet Node", and perhaps redact the internal details like "CometBFT", "ABCI++", etc.
There was a problem hiding this comment.
Also, IIUC, we don't really use the IPLD syncher anymore.
There was a problem hiding this comment.
There is an excessive arrow from "Subnet Level 2 (Child Subnet) to the upper "Relayer Process", which only monitors "Subnet Level 1".
There was a problem hiding this comment.
Step 4 on the left (Fund Operation) only happens in the legacy top-down; with the F3-based parent finality, subnet validators observe a new finality certificate on the parent chain instead.
There was a problem hiding this comment.
Arrow 7 on the right (Release Operation) should go from Relayer, not Child Gateway.
There was a problem hiding this comment.
There are missing blue and orange arrows (top-down & bottom-up) connecting Level 1 Subnet and Level 2 Subnet.
|
|
||
| - Built-in actors (Account, Init, EVM, etc.) | ||
| - Custom actors deployable by subnets | ||
| - Shared across root (Lotus) and child subnets (Fendermint) |
| | Application | ABCI++ | PrepareProposal, ProcessProposal, FinalizeBlock | | ||
| | Execution | FVM/FEVM | Smart contract execution | | ||
| | Parent Sync | Parent Syncer | Polls parent RPC, [VoteTally](#votetally) for [parent finality](#parent-finality) | | ||
| | Data | IPLD Resolver | CID resolution, data availability | |
There was a problem hiding this comment.
AFAIK, it's only used by deprecated VoteTally
| | Consensus | CometBFT | BFT consensus, block proposal, voting, P2P | | ||
| | Application | ABCI++ | PrepareProposal, ProcessProposal, FinalizeBlock | | ||
| | Execution | FVM/FEVM | Smart contract execution | | ||
| | Parent Sync | Parent Syncer | Polls parent RPC, [VoteTally](#votetally) for [parent finality](#parent-finality) | |
| | Dependency | Usage | | ||
| |------------|-------| | ||
| | FVM | Execution (WASM, FEVM) | | ||
| | IPLD / Bitswap | Data availability, CID resolution | |
There was a problem hiding this comment.
AFAIK, only for deprecated VoteTally
|
|
||
| ## Merge Notes (v2) | ||
|
|
||
| *Mapping from source document to this version:* | ||
|
|
||
| | Source Section | Placement | | ||
| |----------------|-----------| | ||
| | **Introduction, Features, Core Concepts, How IPC Works** | Merged into [Intro / Overview](#intro--overview) | | ||
| | **Key Principles** (was TODO) | Added with proposed principles; marked for refinement | | ||
| | **Requirements & Properties** (was TODO) | Added as short subsection with note on overlap with Security/Configuration | | ||
| | **Abstract/Conceptual Mechanisms** | Same as [Concepts (Mechanisms)](#concepts-mechanisms) — merged | | ||
| | **Subnet ID / Lifecycle / Config Management** (were TODO) | Filled from codebase; now under Concepts | | ||
| | **Components: Onchain Actors** | → [Contracts (Solidity)](#contracts-solidity--onchain-actors); added status 🔴 | | ||
| | **IPC Provider** | Added as new [Component](#ipc-provider-parent-chain-provider); status 🟢 | | ||
| | **Relayer** | Enriched with status 🟡, dependencies, known issues | | ||
| | **Operation** (was new) | Added new section: Creating/Destroying, Join/Leave, Deposit/Withdraw, General Message Passing | | ||
| | **Security & Economics** | [Security Guarantees](#security-guarantees) + new [Economic Incentives](#economic-incentives) subsection | | ||
| | **Glossary** | Expanded into [Primitives & Definitions](#primitives--definitions) | | ||
| | **Appendices** | Added with links to specs and architecture docs | | ||
|
|
||
| --- |
Co-authored-by: Sergey Fedorov <serge.fdrv@gmail.com>
2 participants
Note
Low Risk
Documentation-only change adding/reshaping IPC architecture and protocol guides; low risk aside from potential broken links to new docs/diagrams.
Overview
Expands IPC documentation by adding new long-form references:
docs/ipc/architecture-overview.md(with architecture diagrams and end-to-end lifecycle/flow descriptions),docs/ipc/architecture-quick-reference.md(CLI/concepts/troubleshooting cheat sheet), anddocs/ipc/protocol-capture.md(protocol capture covering primitives, mechanisms, components, operations, security, config, and dependencies).Improves discoverability by introducing a new
docs/ipc/README.mddocumentation index and reorganizing the rootREADME.mddocs section into Architecture, User, and Developer documentation with direct links to the new materials.Written by Cursor Bugbot for commit 621b7a6. This will update automatically on new commits. Configure here.