diff --git a/README.md b/README.md
index e6fe1d6f96..ee621ea4e9 100644
--- a/README.md
+++ b/README.md
@@ -95,16 +95,28 @@ source scripts/aliases.sh  # Adds anvil-start, anvil-stop, etc.
 
 **We've prepared a [quick start guide](https://docs.ipc.space/quickstarts/deploy-a-subnet) that will have you running and validating on your own subnet quickly, at the cost of detailed explanations.**
 
-For further documentation, see:
+### Architecture Documentation
 
-- [docs/contracts.md](./docs/ipc/contracts.md) for instructions on how to deploy FEVM actors on subnets.
-- [docs/usage.md](./docs/ipc/usage.md) for instructions on how to use the `ipc-cli` to interact with subnets (from managing your identities, to sending funds to a subnet).
-- [docs/deploying-hierarchy.md](./docs/ipc/deploying-hierarchy.md) for instructions on how to deploy your own instance of IPC on a network.
-- [docs/contract-errors.md](./docs/ipc/contract-errors.md) for a comprehensive reference of all possible contract errors and how to resolve them.
+- **[docs/ipc/architecture-overview.md](./docs/ipc/architecture-overview.md)** - Comprehensive architecture guide with detailed diagrams showing:
+  - All system components and their responsibilities
+  - How subnets connect to L1 and each other
+  - Top-down and bottom-up communication flows
+  - Validator lifecycle and operations
+  - Security model and trust assumptions
+  
+- **[docs/ipc/architecture-quick-reference.md](./docs/ipc/architecture-quick-reference.md)** - Quick reference card with CLI commands, concepts, and troubleshooting
 
-If you are a developer, see:
+### User Documentation
 
-- [docs/developers.md](./docs/ipc/developers.md) for useful tips and guides targeted for IPC developers.
+- [docs/ipc/usage.md](./docs/ipc/usage.md) for instructions on how to use the `ipc-cli` to interact with subnets (from managing your identities, to sending funds to a subnet).
+- [docs/ipc/contracts.md](./docs/ipc/contracts.md) for instructions on how to deploy FEVM actors on subnets.
+- [docs/ipc/deploying-hierarchy.md](./docs/ipc/deploying-hierarchy.md) for instructions on how to deploy your own instance of IPC on a network.
+- [docs/ipc/contract-errors.md](./docs/ipc/contract-errors.md) for a comprehensive reference of all possible contract errors and how to resolve them.
+
+### Developer Documentation
+
+- [docs/ipc/developers.md](./docs/ipc/developers.md) for useful tips and guides targeted for IPC developers.
+- [docs/ipc/README.md](./docs/ipc/README.md) for a complete index of all IPC documentation.
 
 ## Connecting to a rootnet
 
diff --git a/docs/ipc/README.md b/docs/ipc/README.md
new file mode 100644
index 0000000000..9c1c1474d0
--- /dev/null
+++ b/docs/ipc/README.md
@@ -0,0 +1,199 @@
+# IPC Documentation
+
+This directory contains comprehensive documentation for the InterPlanetary Consensus (IPC) framework.
+
+## Architecture Documentation
+
+### 📐 [Architecture Overview](./architecture-overview.md)
+Comprehensive guide to IPC architecture, components, and their interactions. Includes:
+- Detailed component descriptions and responsibilities
+- Communication flows (top-down and bottom-up)
+- Subnet lifecycle management
+- Security model and trust assumptions
+- Configuration parameters and deployment scenarios
+
+**Includes 4 diagrams:**
+1. Detailed architecture diagram
+2. Simplified high-level view
+3. Message flow sequences (fund and release)
+4. Validator lifecycle state machine
+
+### 📜 [Protocol Capture](./protocol-capture.md)
+Protocol capture document describing how IPC works:
+- Components (actors, contracts, node, relayer)
+- Concepts and mechanisms (messaging, bridging, checkpointing, consensus)
+- Security guarantees and trust assumptions
+- Configuration, terms, dependencies
+
+### 📋 [Architecture Quick Reference](./architecture-quick-reference.md)
+Quick reference card with:
+- Core concepts glossary
+- CLI command cheat sheet
+- Common operations and workflows
+- Configuration templates
+- Troubleshooting guide
+- Performance tuning tips
+
+## User Guides
+
+### 🚀 [Usage Guide](./usage.md)
+Complete guide to using the `ipc-cli`:
+- Wallet management (create, import, export)
+- Subnet operations (join, leave, stake)
+- Cross-net messaging (fund, release)
+- Running relayers
+- Checkpoint monitoring
+
+### 📝 [Contract Documentation](./contracts.md)
+Smart contract deployment and interaction:
+- Deploying FEVM actors on subnets
+- Contract interfaces and ABIs
+- Integration examples
+
+### 🏗️ [Deploying Hierarchy](./deploying-hierarchy.md)
+Step-by-step guide for deploying your own IPC instance:
+- Network setup and prerequisites
+- Contract deployment process
+- Validator configuration
+- Bootstrap node setup
+
+### ⚠️ [Contract Errors](./contract-errors.md)
+Comprehensive reference of contract errors:
+- Error codes and meanings
+- Common causes
+- Resolution steps
+
+## Developer Guides
+
+### 💻 [Developers Guide](./developers.md)
+For IPC core developers:
+- Development setup
+- Testing procedures
+- Contributing guidelines
+- Code structure and patterns
+
+### 🔄 [Subnet Creation Flow](./subnet-creation-flow.md)
+Technical details of subnet creation process
+
+### 🔐 [Validator Gater](./validator-gater.md)
+Validator permission and access control
+
+### 🎯 [Querying Subnet Permission Mode](./querying-subnet-permission-mode.md)
+How to check and interact with subnet permission settings
+
+## Operational Guides
+
+### 🏁 [Node Initialization](./node-init.md)
+Setting up a Fendermint node
+
+### ▶️ [Node Start](./node-start.md)
+Starting and managing Fendermint nodes
+
+### 📊 [Subnet Initialization](./subnet-init.md)
+Initializing subnet infrastructure
+
+### 🌐 [Web App Design](./webapp-design.md)
+IPC web application architecture and design
+
+### 🚀 [Quickstart Calibration](./quickstart-calibration.md)
+Quick start guide for Calibration testnet
+
+## Visual Reference
+
+All architecture diagrams are available in the documentation and include:
+
+### Main Architecture Diagrams
+1. **Detailed Architecture**: Complete component view with internal structures
+2. **Simplified Architecture**: High-level layers and communication flows
+3. **Message Flows**: Sequence diagrams for fund and release operations
+4. **Validator Lifecycle**: State machine for validator operations
+
+### Existing IPC Actor Diagrams
+Located in `../../specs/`:
+- Architecture design overview
+- Subnet registry pattern
+- Software stack and relayers
+- Create subnet flow
+- Top-down messaging
+- Stake and membership changes
+- Checkpoint submission
+- Bottom-up messaging
+
+## Getting Started
+
+### New Users
+1. Read the [Architecture Quick Reference](./architecture-quick-reference.md) for core concepts
+2. Follow the [Quickstart Calibration](./quickstart-calibration.md) guide
+3. Learn common operations from the [Usage Guide](./usage.md)
+
+### Validators
+1. Understand the architecture from [Architecture Overview](./architecture-overview.md)
+2. Review the [Validator Lifecycle](./architecture-overview.md#subnet-lifecycle)
+3. Follow deployment steps in [Deploying Hierarchy](./deploying-hierarchy.md)
+4. Set up nodes using [Node Initialization](./node-init.md) and [Node Start](./node-start.md)
+
+### Developers
+1. Study the [Architecture Overview](./architecture-overview.md) for system design
+2. Review [Developers Guide](./developers.md) for contribution guidelines
+3. Understand smart contracts from [Contract Documentation](./contracts.md)
+4. Check [Contract Errors](./contract-errors.md) for debugging
+
+### Subnet Creators
+1. Understand [Subnet Creation Flow](./subnet-creation-flow.md)
+2. Review configuration options in [Architecture Quick Reference](./architecture-quick-reference.md)
+3. Follow [Deploying Hierarchy](./deploying-hierarchy.md) guide
+4. Configure permissions using [Validator Gater](./validator-gater.md)
+
+## External Resources
+
+- **IPC Website**: https://www.ipc.space/
+- **GitHub Repository**: https://github.com/consensus-shipyard/ipc
+- **Calibration Faucet**: https://faucet.calibration.fildev.network/funds.html
+- **Filecoin Documentation**: https://docs.filecoin.io/
+- **CometBFT Documentation**: https://docs.cometbft.com/
+
+## Related Documentation
+
+### Fendermint Documentation
+Located in `../fendermint/`:
+- [Architecture](../fendermint/architecture.md)
+- [IPC Infrastructure](../fendermint/ipc.md)
+- [Checkpointing](../fendermint/checkpointing.md)
+- [Running Fendermint](../fendermint/running.md)
+- [Local Network Testing](../fendermint/localnet.md)
+
+### Specifications
+Located in `../../specs/`:
+- [IPC Actors](../../specs/ipc-actors.md)
+- [Bottom-Up Interaction](../../specs/bottom-up-interaction.md)
+- [Top-Down Finality](../../specs/topdown.md)
+- [Addressing](../../specs/addressing.md)
+- [Executions](../../specs/executions.md)
+
+### Troubleshooting
+- [Troubleshooting Subnet Deployment](../troubleshooting-subnet-deployment.md)
+- [Contract Errors Reference](./contract-errors.md)
+
+## Documentation Maintenance
+
+This documentation is actively maintained. If you find errors or have suggestions:
+
+1. **Report Issues**: Open an issue on GitHub
+2. **Contribute**: Submit a pull request with improvements
+3. **Ask Questions**: Join #ipc-help in [Filecoin Slack](https://filecoin.io/slack)
+
+## Document Status
+
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| Architecture Overview | ✅ Complete | Jan 2026 |
+| Architecture Quick Reference | ✅ Complete | Jan 2026 |
+| Usage Guide | ✅ Complete | - |
+| Contract Documentation | ✅ Complete | - |
+| Deploying Hierarchy | ✅ Complete | - |
+| Contract Errors | ✅ Complete | - |
+| Developers Guide | ✅ Complete | - |
+
+---
+
+**Navigation**: [Main README](../../README.md) | [Fendermint Docs](../fendermint/) | [Specifications](../../specs/)
diff --git a/docs/ipc/architecture-overview.md b/docs/ipc/architecture-overview.md
new file mode 100644
index 0000000000..8b79c4c195
--- /dev/null
+++ b/docs/ipc/architecture-overview.md
@@ -0,0 +1,672 @@
+# IPC Architecture Overview
+
+## Introduction
+
+This document provides a comprehensive overview of the InterPlanetary Consensus (IPC) architecture, describing the components, their responsibilities, and how they connect subnets to the L1 root network.
+
+**InterPlanetary Consensus (IPC)** is a framework that enables on-demand horizontal scalability of blockchain networks by deploying "subnets" that can run different consensus algorithms and customize their execution environment. IPC provides:
+
+- **Recursive scalability**: Subnets can spawn child subnets indefinitely
+- **Cross-net communication**: Secure message passing between parent and child networks
+- **Flexible consensus**: Each subnet can customize block time, validator requirements, and consensus parameters
+- **Ethereum compatibility**: Full FEVM support for Solidity smart contracts
+- **Native FVM support**: Access to Filecoin's actor model and built-in capabilities
+
+## Architecture Diagrams
+
+This document includes three complementary diagrams:
+
+### 1. Detailed Architecture Diagram
+Shows all components, internal structure, and detailed interactions.
+
+![IPC Detailed Architecture](../../.cursor/projects/Users-philip-github-ipc/assets/ipc-architecture-diagram.png)
+
+### 2. Simplified Architecture Diagram
+High-level view of the key layers and primary communication flows.
+
+![IPC Simplified Architecture](../../.cursor/projects/Users-philip-github-ipc/assets/ipc-architecture-simple.png)
+
+### 3. Message Flow Sequences
+Step-by-step flows for common operations (fund and release).
+
+![IPC Message Flows](../../.cursor/projects/Users-philip-github-ipc/assets/ipc-message-flows.png)
+
+### 4. Validator Lifecycle Diagram
+State transitions and operations for validators throughout their lifecycle.
+
+![IPC Validator Lifecycle](../../.cursor/projects/Users-philip-github-ipc/assets/ipc-validator-lifecycle.png)
+
+## System Components
+
+### 1. L1 Root Network (Filecoin/Calibration)
+
+**Responsibility**: The root network serves as the trust anchor for the entire IPC hierarchy.
+
+**Components**:
+- **Lotus/FEVM Node**: The Filecoin node implementation that provides the foundational blockchain
+- **Gateway Contract**: Singleton contract managing IPC protocol logic, collateral, firewalls, and cross-net interactions
+- **Subnet Actor Contract**: User-defined contract implementing subnet-specific logic (one per child subnet)
+- **Registry Contract**: Factory contract for deploying reference implementations of subnet actors
+
+**Key Functions**:
+- Source of truth for validator sets and collateral
+- Execution environment for top-down messages
+- Reception point for bottom-up checkpoints from child subnets
+- RPC endpoint for subnet validators to query parent state
+
+### 2. Fendermint Nodes (Subnet Validators)
+
+**Responsibility**: Peer implementation of IPC subnets, running the actual subnet blockchain.
+
+**Architecture**: Each Fendermint node is composed of:
+
+#### a. CometBFT Consensus Layer
+- Byzantine Fault Tolerant consensus engine (formerly Tendermint)
+- Handles block proposal, voting, and finalization
+- Provides networking layer for validator P2P communication
+- Uses ABCI++ interface to communicate with application layer
+
+#### b. ABCI++ Application Layer
+- Implements ABCI++ interface methods (`PrepareProposal`, `ProcessProposal`, `FinalizeBlock`)
+- Manages transaction lifecycle from mempool to execution
+- Validates proposals including parent finality commitments
+- Coordinates between consensus and execution layers
+
+#### c. FVM/FEVM Execution Layer
+- Filecoin Virtual Machine for smart contract execution
+- Supports both native FVM actors and FEVM (Ethereum compatibility)
+- Executes top-down messages from parent
+- Manages state transitions and storage
+
+#### d. Parent Syncer Module
+- Polls parent network RPC for finalized state
+- Caches parent blocks with configurable finality delay
+- Publishes votes on observed parent blocks via GossipSub
+- Implements quorum detection via VoteTally mechanism
+- Two implementations: `LotusParentSyncer` and `TendermintAwareSyncer`
+
+#### e. IPLD Resolver Module
+- Resolves Content Identifiers (CIDs) across the network
+- Stores and retrieves IPLD data from distributed store
+- Facilitates data availability for checkpoint validation
+- Maintains connections with nodes in parent/child/peer subnets
+
+#### f. Gateway & Registry Contracts (Deployed per subnet)
+- Each subnet deploys its own Gateway and Registry at genesis
+- Enables recursive subnet creation
+- Manages child subnet interactions
+
+### 3. User Interaction Layer
+
+#### a. ipc-cli (Command Line Interface)
+**Responsibility**: Primary user interface for interacting with IPC
+
+**Key Commands**:
+- Wallet management: `wallet new`, `wallet import`, `wallet export`
+- Subnet operations: `subnet create`, `subnet join`, `subnet leave`, `subnet list`
+- Cross-net messages: `cross-msg fund`, `cross-msg release`
+- Validator operations: `subnet stake`, `subnet unstake`, `subnet claim`
+- Checkpoint operations: `checkpoint relayer`, `checkpoint list-bottomup`
+
+#### b. IpcProvider Library
+**Responsibility**: Rust library providing programmatic access to IPC functionality
+
+**Features**:
+- Used internally by ipc-cli
+- Available for building custom IPC applications
+- Handles transaction signing and submission
+- Manages interaction with Gateway and Subnet Actor contracts
+
+#### c. Wallet/Key Management
+**Responsibility**: Secure storage and management of cryptographic keys
+
+**Features**:
+- EVM wallet with keystore in `~/.ipc`
+- Support for multiple addresses and default key configuration
+- Key export in multiple formats (hex, base64, fendermint-compatible)
+- Integration with Metamask and other wallets
+
+### 4. Relayer Processes
+
+**Responsibility**: Bridge bottom-up information from child subnets to parent.
+
+**Operation Flow**:
+1. Monitor child subnet for `QuorumReached` events via RPC
+2. Retrieve signed checkpoint with validator signatures
+3. Submit checkpoint to parent subnet's Gateway contract
+4. Execute bottom-up messages as part of checkpoint submission
+
+**Incentivization**:
+- Relayers receive cross-net message fees for checkpoint submissions
+- Rewards claimed via `ipc-cli subnet claim --reward`
+- Anyone can run a relayer (permissionless design)
+- Redundancy encouraged for network resilience
+
+**Key Properties**:
+- Trustless operation (cryptographic verification via quorum signatures)
+- No single point of failure (multiple relayers can operate)
+- Economically incentivized but not required to be validators
+
+## Cross-Net Communication Flows
+
+### Top-Down Flow (Parent → Child)
+
+**Purpose**: Propagate parent state, messages, and validator changes to child subnet.
+
+**Components**:
+1. **Parent Finality Proposal**:
+   - Validators poll parent via RPC
+   - Parent Syncer caches blocks with finality delay
+   - Validators vote on parent block height + hash via GossipSub
+   - Quorum detected by VoteTally
+   - Block proposer includes `ParentFinality` in proposal
+
+2. **Proposal Validation**:
+   - Each validator checks proposed height exists in cache or RPC
+   - Validates block hash matches
+   - Rejects if invalid, accepts if valid
+
+3. **Proposal Execution**:
+   - Commit new parent finality to ledger
+   - Fetch and apply validator changes (join/leave/stake)
+   - Fetch and execute top-down messages (fund operations)
+   - Indexed by parent block height for deterministic execution
+
+**Message Types**:
+- `fund`: Send tokens from parent address to child address
+- `pre-fund`: Include balance in child subnet genesis (before bootstrap)
+- Validator changes: join, leave, stake, unstake, setFederatedPower
+
+**Key Parameters**:
+- Finality delay: Number of parent blocks to wait before considering final
+- Max proposal range: Limits how far ahead proposal can be from last committed
+
+### Bottom-Up Flow (Child → Parent)
+
+**Purpose**: Propagate checkpoints and messages from child to parent.
+
+**Checkpoint Creation Flow**:
+
+1. **Trigger Conditions** (any of these):
+   - Fixed period reached (`bottomup-check-period`)
+   - Message queue exceeds `MAX_MSGS_PER_BATCH`
+   - Maximum wait time exceeded with pending messages
+
+2. **Checkpoint Creation**:
+   - Deterministic process during block execution
+   - All validators call `createCheckpoint` on Gateway contract
+   - Checkpoint contains:
+     - `subnet_id`: Child subnet identifier
+     - `block_height`: Child block height
+     - `block_hash`: Child block hash (prevents long-range attacks)
+     - `prev_checkpoint_height`: Links checkpoints in chain
+     - `next_configuration_number`: Validator set for next checkpoint
+     - `cross_messages`: Bottom-up messages (or CID commitment)
+
+3. **Signature Collection**:
+   - After checkpoint committed in block, validators broadcast signature transactions
+   - Validators call `addCheckpointSignature` with their signature
+   - Signatures accumulate in child ledger
+   - Includes Merkle proof of validator membership (power table)
+
+4. **Quorum Reached**:
+   - When >2/3 of validator power has signed
+   - Gateway emits `QuorumReached` event
+   - Checkpoint ready for relayer pickup
+
+5. **Relayer Submission**:
+   - Relayer queries `QuorumReached` events
+   - Calls `submitCheckpoint` in parent Gateway with:
+     - Checkpoint data
+     - Bundle of validator signatures (quorum certificate)
+   - Parent validates signatures against last known validator set
+   - Updates `next_configuration_number` to apply validator changes
+
+6. **Parent Execution**:
+   - Bottom-up messages executed in parent
+   - Validator set synchronized to child's confirmed state
+   - Relayer receives rewards from message fees
+
+**Message Types**:
+- `release`: Send tokens from child address to parent address
+- `pre-release`: Reclaim genesis balance before subnet bootstrap
+- General cross-net messages (planned for future)
+
+**Configuration Updates**:
+- Child reports `next_configuration_number` in checkpoint
+- Parent confirms stake changes when checkpoint committed
+- Creates deterministic ordering of validator set evolution
+
+## Subnet Lifecycle
+
+### 1. Subnet Creation
+
+```bash
+# Deploy subnet actor (via registry or custom)
+ipc-cli subnet create --parent /r314159 --min-validators 4
+
+# For federated subnets
+ipc-cli subnet set-federated-validators --subnet <SUBNET_ID> --validators <ADDRS>
+```
+
+**Process**:
+1. User deploys Subnet Actor contract in parent
+2. Subnet Actor registered in parent's Registry
+3. Subnet waits for minimum collateral/validators (collateral mode)
+4. Once conditions met, subnet calls `register` on parent Gateway
+5. Subnet is bootstrapped and can start producing blocks
+
+### 2. Joining as Validator
+
+```bash
+# Join subnet with collateral
+ipc-cli subnet join --subnet <SUBNET_ID> --collateral 10
+
+# Add more collateral
+ipc-cli subnet stake --subnet <SUBNET_ID> --collateral 5
+```
+
+**Process**:
+1. Validator calls `join` on Subnet Actor with collateral
+2. Creates `StakeChangeRequest` with configuration number
+3. Change propagated to child via top-down finality
+4. Child executes membership change
+5. Child confirms in next checkpoint via `next_configuration_number`
+6. Parent confirms collateral change when checkpoint committed
+
+### 3. Running Validator Node
+
+```bash
+# Start Fendermint validator
+fendermint run --home-dir ~/.fendermint \
+  --network <NETWORK_CONFIG> \
+  --subnet-id <SUBNET_ID>
+```
+
+**Components Started**:
+- CometBFT consensus node
+- ABCI++ application server
+- Ethereum RPC API (for user transactions)
+- Parent Syncer (background task)
+- IPLD Resolver (background task)
+
+### 4. Cross-Net Operations
+
+#### Fund (Parent → Child)
+```bash
+# Send funds to child subnet
+ipc-cli cross-msg fund --subnet <SUBNET_ID> --to <ADDR> 100
+
+# Check parent finality in child
+ipc-cli cross-msg parent-finality --subnet <SUBNET_ID>
+```
+
+**Flow**:
+1. User calls `fund` on parent Gateway
+2. Message added to top-down queue
+3. Validators include parent finality in child blocks
+4. When finality committed, message executed in child
+5. Funds appear in child address
+
+#### Release (Child → Parent)
+```bash
+# Send funds back to parent
+ipc-cli cross-msg release --subnet <SUBNET_ID> --to <ADDR> 50
+
+# Monitor checkpoint submission
+ipc-cli checkpoint list-bottomup --subnet <SUBNET_ID> --from-epoch 0 --to-epoch 100
+```
+
+**Flow**:
+1. User calls `release` on child Gateway
+2. Message added to bottom-up queue
+3. Checkpoint created at period boundary
+4. Validators sign checkpoint
+5. Relayer submits to parent
+6. Message executed in parent, funds released
+
+### 5. Running Relayer
+
+```bash
+# Start relayer for subnet
+ipc-cli checkpoint relayer --subnet <SUBNET_ID>
+
+# Claim rewards
+ipc-cli subnet claim --subnet <SUBNET_ID> --reward
+```
+
+### 6. Leaving Subnet
+
+```bash
+# Reduce stake
+ipc-cli subnet unstake --subnet <SUBNET_ID> --collateral 5
+
+# Leave entirely
+ipc-cli subnet leave --subnet <SUBNET_ID>
+
+# Claim returned collateral
+ipc-cli subnet claim --subnet <SUBNET_ID>
+```
+
+**Process**:
+1. Validator calls `leave` or `unstake`
+2. Creates `StakeChangeRequest`
+3. Propagated to child via top-down finality
+4. Child removes validator or reduces power
+5. Child confirms in checkpoint
+6. Parent releases collateral when checkpoint committed
+7. Validator claims collateral
+
+## Recursive Subnet Architecture
+
+**Key Property**: Any subnet can spawn child subnets, creating a tree hierarchy.
+
+**Implications**:
+- Each subnet level has its own Gateway and Registry
+- Subnets can customize consensus parameters (block time, checkpoint period)
+- Cross-net messages can traverse multiple levels
+- Validators at each level are independent
+- Security decreases with depth (trust assumptions compound)
+
+**Example Hierarchy**:
+```
+L1 (Filecoin Mainnet)
+├─ Subnet A (Gaming subnet, fast blocks)
+│  ├─ Subnet A1 (Game instance 1)
+│  └─ Subnet A2 (Game instance 2)
+└─ Subnet B (DeFi subnet, EVM compatible)
+   └─ Subnet B1 (Lending protocol subnet)
+```
+
+## Security Model
+
+### Trust Assumptions
+
+1. **L1 Security**: Root network (Filecoin) is trusted and secure
+2. **Validator Honesty**: >2/3 of validator power is honest in each subnet
+3. **Economic Security**: Collateral requirements discourage malicious behavior
+4. **Finality Delay**: Parent blocks delayed sufficiently to avoid reorgs
+5. **RPC Reliability**: Validators have access to reliable parent RPC nodes
+
+### Attack Mitigations
+
+1. **Long-Range Attacks**: Prevented by anchoring block hash in checkpoints
+2. **Double-Spend**: Prevented by BFT consensus and checkpoint finality
+3. **Validator Collusion**: Requires >2/3 stake, economically irrational
+4. **Checkpoint Censorship**: Multiple relayers provide redundancy
+5. **Parent Reorg**: Finality delay ensures parent state is stable
+
+### Gas Economics
+
+**Top-Down Messages**:
+- Gas paid in parent subnet
+- Execution cost in child (no additional fee)
+
+**Bottom-Up Messages**:
+- Cross-message fee paid by sender (rewards relayer)
+- Execution gas paid by relayer (compensated by fee)
+- Fee amount set by subnet policy
+
+## Network Types and Modes
+
+### Permission Modes
+
+1. **Collateral Mode**:
+   - Permissionless (anyone can join)
+   - Requires minimum collateral stake
+   - Voting power proportional to stake
+   - Typical for public subnets
+
+2. **Federated Mode**:
+   - Permissioned (admin sets validators)
+   - Admin calls `setFederatedPower` to set validator set
+   - Voting power set by admin
+   - Typical for consortium/private subnets
+
+### Network Types
+
+1. **FEVM** (Filecoin EVM):
+   - Ethereum Virtual Machine compatibility
+   - Supports Solidity smart contracts
+   - Standard Ethereum RPC API
+   - Compatible with Web3 tooling
+
+2. **FVM** (Filecoin VM):
+   - Native Filecoin execution environment
+   - Actor-based programming model
+   - WASM runtime
+   - Access to Filecoin built-in actors
+
+## Configuration Parameters
+
+### Subnet Creation Parameters
+
+- `min_validators`: Minimum validators required to bootstrap
+- `min_collateral`: Minimum total collateral required
+- `bottomup_check_period`: Blocks between checkpoints
+- `active_validators_limit`: Maximum active validators
+- `majority_percentage`: Quorum threshold (typically 67%)
+
+### Operational Parameters
+
+- **Finality Delay**: Blocks to wait before considering parent block final (e.g., 10-20 blocks)
+- **Max Proposal Range**: Maximum parent height advance per child block (prevents stalls)
+- **Max Messages Per Batch**: Triggers intermediate checkpoint if exceeded
+- **Checkpoint Period**: Fixed interval between checkpoints (e.g., every 100 blocks)
+
+## Monitoring and Observability
+
+### Key Metrics
+
+1. **Checkpoint Health**:
+   - Time since last checkpoint submitted
+   - Percentage of checkpoints with quorum
+   - Average checkpoint submission delay
+
+2. **Validator Performance**:
+   - Signature submission rate
+   - Uptime and block participation
+   - Parent syncer cache hit rate
+
+3. **Cross-Net Message Flow**:
+   - Top-down message execution lag
+   - Bottom-up message queue depth
+   - Message fee statistics
+
+4. **Network Connectivity**:
+   - P2P peer count
+   - Parent RPC latency and availability
+   - IPLD resolver data availability
+
+### Debugging Commands
+
+```bash
+# Check subnet status
+ipc-cli subnet list --subnet <PARENT_ID>
+
+# View checkpoint history
+ipc-cli checkpoint list-bottomup --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+
+# Check validator changes
+ipc-cli checkpoint list-validator-changes --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+
+# Check quorum events
+ipc-cli checkpoint quorum-reached-events --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+
+# Check if checkpoint submitted
+ipc-cli checkpoint has-submitted-bottomup-height --subnet <SUBNET_ID> --submitter <ADDR>
+
+# Get latest checkpoint height
+ipc-cli checkpoint last-bottomup-checkpoint-height --subnet <SUBNET_ID>
+
+# Check wallet balances
+ipc-cli wallet balances --wallet-type evm --subnet <SUBNET_ID>
+
+# View parent finality
+ipc-cli cross-msg parent-finality --subnet <SUBNET_ID>
+
+# List top-down messages
+ipc-cli cross-msg list-topdown-msgs --subnet <SUBNET_ID> --epoch <EPOCH>
+```
+
+## Technical Implementation Details
+
+### Smart Contract Architecture (Diamond Pattern)
+
+IPC uses the Diamond Pattern (EIP-2535) for upgradeable contracts:
+
+**Components**:
+- **Diamond**: Main contract with storage and router
+- **Facets**: Separate contracts with function implementations
+- **DiamondCut**: Upgrade mechanism for adding/replacing facets
+
+**Contracts**:
+- `GatewayDiamond.sol`: Main IPC protocol logic
+- `SubnetActorDiamond.sol`: Subnet-specific governance
+- `SubnetRegistryDiamond.sol`: Subnet actor factory
+
+**Storage Patterns**:
+- AppStorage pattern for shared storage in facets
+- Diamond Storage for library-specific storage
+- Reentrancy guards adapted for Diamond pattern
+
+### IPLD and Data Availability
+
+**CID Resolution**:
+- Checkpoint may contain CID instead of full message list
+- IPLD Resolver fetches data from IPLD network
+- Validators verify data availability before voting
+- Uses Bitswap protocol for data exchange
+
+**NC-Max Approach**:
+- CIDs proposed for resolution in advance
+- Data dissemination moved out of critical consensus path
+- Validators reject proposals with unavailable data
+
+### Signature and Verification
+
+**Checkpoint Signatures**:
+- Validators sign using their validator key (BLS or ECDSA)
+- Merkle proof of power table membership included
+- Parent verifies quorum threshold met (>2/3 total power)
+- Signature aggregation possible for efficiency
+
+**Power Table**:
+- Merkle tree of validator public keys and power
+- Root hash included in checkpoint
+- Enables efficient verification of validator membership
+- Updated incrementally as validators join/leave
+
+## Deployment Scenarios
+
+### Local Development (Anvil)
+
+```bash
+# Start Anvil with IPC accounts funded
+./scripts/setup-anvil-with-ipc-keys.sh
+
+# Deploy IPC contracts
+cd contracts && forge script script/DeployGateway.s.sol
+
+# Configure ipc-cli for local
+ipc-cli config init
+```
+
+### Calibration Testnet
+
+**Configuration** (`~/.ipc/config.toml`):
+```toml
+keystore_path = "~/.ipc"
+
+[[subnets]]
+id = "/r314159"
+
+[subnets.config]
+network_type = "fevm"
+provider_http = "https://api.calibration.node.glif.io/rpc/v1"
+gateway_addr = "0x1AEe8A878a22280fc2753b3C63571C8F895D2FE3"
+registry_addr = "0x0b4e239FF21b40120cDa817fba77bD1B366c1bcD"
+```
+
+**Steps**:
+1. Get tFIL from [Calibration Faucet](https://faucet.calibration.fildev.network/funds.html)
+2. Create subnet and join as validator
+3. Deploy Fendermint infrastructure
+4. Start validating and relay checkpoints
+
+### Production (Mainnet)
+
+**Considerations**:
+- Use reliable RPC infrastructure (load balanced, redundant)
+- Monitor validator performance and checkpoint submission
+- Run multiple relayers for redundancy
+- Implement alerting for checkpoint delays
+- Regular validator key rotation and security audits
+- Backup and disaster recovery procedures
+
+## Future Enhancements
+
+### Planned Features
+
+1. **General Cross-Net Messages**: Beyond fund/release, arbitrary contract calls
+2. **Message Inbox Pattern**: Decouple message delivery from execution
+3. **Improved Relayer Rewards**: More sophisticated incentive mechanisms
+4. **Light Client Verification**: Parent state verification without full RPC trust
+5. **Cross-Subnet Atomic Swaps**: Multi-hop cross-net transactions
+6. **Subnet Sharding**: Horizontal scaling within subnet level
+7. **Checkpoint Compression**: Reduce checkpoint size via commitment schemes
+
+### Research Areas
+
+1. **Finality Gadgets**: Faster finality without compromising security
+2. **Zero-Knowledge Checkpoints**: Privacy-preserving cross-net messages
+3. **Optimistic Checkpoints**: Faster confirmation with fraud proofs
+4. **Dynamic Validator Selection**: Reputation-based validator sets
+5. **Cross-Chain Bridges**: Integration with non-IPC blockchains
+
+## References
+
+### Documentation
+- [IPC Main README](../../README.md)
+- [IPC Usage Guide](./usage.md)
+- [Contract Documentation](./contracts.md)
+- [Fendermint Architecture](../fendermint/architecture.md)
+- [Deploying Hierarchy](./deploying-hierarchy.md)
+
+### Specifications
+- [IPC Actors Spec](../../specs/ipc-actors.md)
+- [Bottom-Up Interactions](../../specs/bottom-up-interaction.md)
+- [Top-Down Finality](../../specs/topdown.md)
+- [Checkpointing](../fendermint/checkpointing.md)
+
+### External Resources
+- [Tendermint/CometBFT Documentation](https://docs.cometbft.com/)
+- [ABCI++ Specification](https://github.com/cometbft/cometbft/tree/main/spec/abci)
+- [EIP-2535 Diamond Standard](https://eips.ethereum.org/EIPS/eip-2535)
+- [IPLD Specification](https://ipld.io/specs/)
+
+## Glossary
+
+- **ABCI++**: Application Blockchain Interface, protocol for CometBFT to communicate with application
+- **Bottom-Up**: Information flow from child subnet to parent
+- **Checkpoint**: Batch of messages and state commitments from child to parent
+- **Configuration ID**: Identifier for validator set version
+- **CID**: Content Identifier in IPLD
+- **Facet**: Function implementation contract in Diamond pattern
+- **Fendermint**: IPC subnet node implementation
+- **FEVM**: Filecoin EVM, Ethereum-compatible execution environment
+- **FVM**: Filecoin Virtual Machine
+- **Gateway**: Singleton contract managing IPC protocol in each subnet
+- **IPC**: InterPlanetary Consensus
+- **IPLD**: InterPlanetary Linked Data
+- **Quorum**: >2/3 of validator power threshold
+- **Relayer**: Process submitting checkpoints from child to parent
+- **Subnet Actor**: Contract governing a specific child subnet
+- **Top-Down**: Information flow from parent to child subnet
+- **Vote Tally**: Component tracking validator votes on parent finality
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: January 2026  
+**Status**: Living Document
diff --git a/docs/ipc/architecture-quick-reference.md b/docs/ipc/architecture-quick-reference.md
new file mode 100644
index 0000000000..90de20703c
--- /dev/null
+++ b/docs/ipc/architecture-quick-reference.md
@@ -0,0 +1,421 @@
+# IPC Architecture Quick Reference
+
+> Quick reference guide for IPC architecture, components, and common operations
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Root Network (L1)** | Trust anchor (Filecoin/Calibration) running Gateway and Subnet Actor contracts |
+| **Subnet** | Child blockchain with own validators, consensus, and execution environment |
+| **Gateway Contract** | Singleton managing IPC protocol, collateral, and cross-net messages (one per subnet) |
+| **Subnet Actor** | Contract governing specific child subnet (deployed in parent) |
+| **Fendermint** | Subnet node implementation (CometBFT + ABCI++ + FVM/FEVM) |
+| **Top-Down** | Parent → Child information flow (finality, messages, validator changes) |
+| **Bottom-Up** | Child → Parent information flow (checkpoints, messages, confirmations) |
+| **Checkpoint** | Batch of child state + messages submitted to parent with validator signatures |
+| **Relayer** | Process that submits checkpoints from child to parent (permissionless) |
+| **Configuration ID** | Version number for validator set (tracks membership changes) |
+
+## Component Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ L1 Root Network (Filecoin)                              │
+│ ┌─────────┐  ┌──────────────┐  ┌──────────┐           │
+│ │ Gateway │  │ Subnet Actors│  │ Registry │           │
+│ └─────────┘  └──────────────┘  └──────────┘           │
+└────────────────────┬─────────────────────────┬──────────┘
+            ▲ Top-Down (Finality)     Bottom-Up (Checkpoints) ▼
+            │                                  │
+┌───────────┴──────────────────────────────────┴─────────┐
+│ Subnet Level 1                                          │
+│ ┌───────────────────────────────────────────────┐      │
+│ │ Fendermint Node (Validator)                   │      │
+│ │ ┌──────────────┐                              │      │
+│ │ │  CometBFT    │ ← Byzantine Fault Tolerance  │      │
+│ │ ├──────────────┤                              │      │
+│ │ │  ABCI++ App  │ ← Transaction coordination   │      │
+│ │ ├──────────────┤                              │      │
+│ │ │  FVM/FEVM    │ ← Smart contract execution   │      │
+│ │ └──────────────┘                              │      │
+│ │ │ Parent Syncer │ IPLD Resolver │             │      │
+│ │ └───────────────┴───────────────┘             │      │
+│ └───────────────────────────────────────────────┘      │
+│ ┌─────────┐  ┌──────────────┐                          │
+│ │ Gateway │  │  Registry    │                          │
+│ └─────────┘  └──────────────┘                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Key Communication Flows
+
+### Top-Down (Parent → Child)
+
+```
+Parent RPC
+    ↓ (polling)
+Parent Syncer (cache parent blocks)
+    ↓ (publish votes)
+Vote Tally (GossipSub)
+    ↓ (quorum detected)
+Block Proposer (include ParentFinality)
+    ↓ (consensus)
+Block Validation (verify finality)
+    ↓ (execution)
+Apply Validator Changes + Execute Top-Down Messages
+```
+
+**What flows down:**
+- Parent block height + hash (finality commitment)
+- Top-down messages: `fund`, `pre-fund`
+- Validator changes: join, leave, stake, unstake
+- Configuration updates
+
+**Timing**: ~2-5 minutes (depends on finality delay)
+
+### Bottom-Up (Child → Parent)
+
+```
+User triggers release
+    ↓
+Message queued in child
+    ↓
+Checkpoint period reached OR message limit hit
+    ↓
+Validators create checkpoint
+    ↓
+Each validator signs checkpoint
+    ↓
+Quorum reached (>2/3 power)
+    ↓
+QuorumEvent emitted
+    ↓
+Relayer monitors event
+    ↓
+Relayer submits to parent Gateway
+    ↓
+Parent validates signatures + executes messages
+```
+
+**What flows up:**
+- Bottom-up messages: `release`, `pre-release`
+- Configuration confirmations (validator set sync)
+- Child block anchoring (height + hash)
+
+**Timing**: ~5-10 minutes (depends on checkpoint period)
+
+## CLI Command Reference
+
+### Wallet Management
+```bash
+# Create new wallet
+ipc-cli wallet new --wallet-type evm
+
+# Import wallet
+ipc-cli wallet import --wallet-type evm --private-key <KEY>
+
+# Export wallet (hex format for Metamask)
+ipc-cli wallet export --wallet-type evm --address <ADDR> --hex -o key.txt
+
+# Set default wallet
+ipc-cli wallet set-default --address <ADDR> --wallet-type evm
+
+# Check balances
+ipc-cli wallet balances --wallet-type evm --subnet <SUBNET_ID>
+```
+
+### Subnet Operations
+```bash
+# List active subnets
+ipc-cli subnet list --subnet <PARENT_ID>
+
+# Join as validator
+ipc-cli subnet join --subnet <SUBNET_ID> --collateral 10
+
+# Add more stake
+ipc-cli subnet stake --subnet <SUBNET_ID> --collateral 5
+
+# Reduce stake
+ipc-cli subnet unstake --subnet <SUBNET_ID> --collateral 3
+
+# Leave subnet
+ipc-cli subnet leave --subnet <SUBNET_ID>
+
+# Claim collateral/rewards
+ipc-cli subnet claim --subnet <SUBNET_ID> [--reward]
+```
+
+### Cross-Net Messages
+```bash
+# Send funds to child subnet
+ipc-cli cross-msg fund --subnet <SUBNET_ID> --to <ADDR> 100
+
+# Send funds to parent subnet
+ipc-cli cross-msg release --subnet <SUBNET_ID> --to <ADDR> 50
+
+# Pre-fund before subnet bootstrap
+ipc-cli cross-msg pre-fund --subnet <SUBNET_ID> 10
+
+# Pre-release before subnet starts
+ipc-cli cross-msg pre-release --subnet <SUBNET_ID> 5
+
+# Check parent finality in child
+ipc-cli cross-msg parent-finality --subnet <SUBNET_ID>
+
+# List top-down messages
+ipc-cli cross-msg list-topdown-msgs --subnet <SUBNET_ID> --epoch <N>
+```
+
+### Checkpoint Operations
+```bash
+# Run relayer
+ipc-cli checkpoint relayer --subnet <SUBNET_ID>
+
+# List bottom-up checkpoints
+ipc-cli checkpoint list-bottomup --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+
+# Check quorum events
+ipc-cli checkpoint quorum-reached-events --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+
+# Check if checkpoint submitted
+ipc-cli checkpoint has-submitted-bottomup-height --subnet <SUBNET_ID> --submitter <ADDR>
+
+# Get latest checkpoint height
+ipc-cli checkpoint last-bottomup-checkpoint-height --subnet <SUBNET_ID>
+
+# List validator changes
+ipc-cli checkpoint list-validator-changes --from-epoch <N> --to-epoch <M> --subnet <SUBNET_ID>
+```
+
+### Send Value Within Subnet
+```bash
+# Transfer tokens to another address in same subnet
+ipc-cli subnet send-value --subnet <SUBNET_ID> --to <ADDR> 10
+```
+
+## Fendermint Infrastructure
+
+### Deploy Bootstrap Node
+```bash
+cargo make --makefile infra/Makefile.toml \
+    -e SUBNET_ID=<SUBNET_ID> \
+    -e CMT_P2P_HOST_PORT=26656 \
+    -e CMT_RPC_HOST_PORT=26657 \
+    -e BOOTSTRAPS=<SEED_NODES> \
+    -e PARENT_REGISTRY=<REGISTRY_ADDR> \
+    -e PARENT_GATEWAY=<GATEWAY_ADDR> \
+    bootstrap
+```
+
+### Deploy Validator Node
+```bash
+cargo make --makefile infra/Makefile.toml \
+    -e PRIVATE_KEY_PATH=<KEY_FILE> \
+    -e SUBNET_ID=<SUBNET_ID> \
+    -e CMT_P2P_HOST_PORT=26656 \
+    -e CMT_RPC_HOST_PORT=26657 \
+    -e ETHAPI_HOST_PORT=8545 \
+    -e BOOTSTRAPS=<SEED_NODES> \
+    -e PARENT_REGISTRY=<REGISTRY_ADDR> \
+    -e PARENT_GATEWAY=<GATEWAY_ADDR> \
+    child-validator
+```
+
+### Deploy Full Node
+```bash
+cargo make --makefile infra/Makefile.toml \
+    -e SUBNET_ID=<SUBNET_ID> \
+    -e BOOTSTRAPS=<SEED_NODES> \
+    -e PARENT_REGISTRY=<REGISTRY_ADDR> \
+    -e PARENT_GATEWAY=<GATEWAY_ADDR> \
+    child-fullnode
+```
+
+## Configuration Files
+
+### ipc-cli Config (`~/.ipc/config.toml`)
+```toml
+keystore_path = "~/.ipc"
+
+# Filecoin Calibration Testnet
+[[subnets]]
+id = "/r314159"
+
+[subnets.config]
+network_type = "fevm"
+provider_http = "https://api.calibration.node.glif.io/rpc/v1"
+gateway_addr = "0x1AEe8A878a22280fc2753b3C63571C8F895D2FE3"
+registry_addr = "0x0b4e239FF21b40120cDa817fba77bD1B366c1bcD"
+
+# Local Anvil (for development)
+[[subnets]]
+id = "/r31337"
+
+[subnets.config]
+network_type = "fevm"
+provider_http = "http://127.0.0.1:8545"
+gateway_addr = "<DEPLOYED_GATEWAY_ADDR>"
+registry_addr = "<DEPLOYED_REGISTRY_ADDR>"
+```
+
+### Fendermint Config (`~/.fendermint/config/default.toml`)
+```toml
+[abci]
+[abci.listen]
+host = "0.0.0.0"
+port = 26658
+
+[db]
+state_hist_size = 1000
+
+[resolver]
+network = "mainnet"
+
+[eth.listen]
+host = "0.0.0.0"
+port = 8545
+```
+
+## Smart Contract Addresses
+
+### Calibration Testnet (r314159)
+| Contract | Address |
+|----------|---------|
+| Gateway | `0x1AEe8A878a22280fc2753b3C63571C8F895D2FE3` |
+| Registry | `0x0b4e239FF21b40120cDa817fba77bD1B366c1bcD` |
+
+## Subnet ID Format
+
+```
+/r<chainid>/<subnet-actor-address>/<subnet-actor-address>/...
+```
+
+**Examples:**
+- Root: `/r314159` (Calibration)
+- Level 1: `/r314159/t410fexample...`
+- Level 2: `/r314159/t410fexample.../t410fchild...`
+
+## Key Parameters
+
+| Parameter | Typical Value | Description |
+|-----------|---------------|-------------|
+| `bottomup_check_period` | 100 blocks | Frequency of checkpoint creation |
+| `min_validators` | 3-5 | Minimum validators to bootstrap subnet |
+| `min_collateral` | 1-10 FIL | Minimum total collateral required |
+| `majority_percentage` | 67% | Quorum threshold (>2/3) |
+| `finality_delay` | 10-20 blocks | Parent blocks to wait before final |
+| `max_proposal_range` | 50 blocks | Max parent height advance per child block |
+| `MAX_MSGS_PER_BATCH` | 100 | Triggers intermediate checkpoint |
+
+## Security Model
+
+### Trust Assumptions
+- ✅ L1 root network is secure
+- ✅ >2/3 of validator power is honest
+- ✅ Economic security via collateral
+- ✅ Finality delay prevents parent reorgs
+- ✅ Cryptographic signatures are unforgeable
+
+### Attack Mitigations
+- **Long-range attacks**: Block hash anchoring in checkpoints
+- **Double-spend**: BFT consensus + checkpoint finality
+- **Validator collusion**: Requires >2/3 stake (economically irrational)
+- **Checkpoint censorship**: Multiple relayers provide redundancy
+- **Parent reorg**: Finality delay ensures stability
+
+## Common Issues & Debugging
+
+### Issue: Cross-net message not executing
+**Check:**
+1. Message included in checkpoint? `ipc-cli checkpoint list-bottomup`
+2. Checkpoint submitted? `ipc-cli checkpoint last-bottomup-checkpoint-height`
+3. Relayer running? Check for `QuorumReached` events
+4. Parent finality committed? `ipc-cli cross-msg parent-finality`
+
+### Issue: Validator not signing checkpoints
+**Check:**
+1. Validator has funds for gas? `ipc-cli wallet balances`
+2. Validator in current power table? `ipc-cli subnet list`
+3. Configuration ID confirmed? Check validator changes
+4. Fendermint node running? Check logs
+
+### Issue: Subnet won't bootstrap
+**Check:**
+1. Minimum validators joined? `ipc-cli subnet list`
+2. Minimum collateral met? Check total collateral
+3. All validators funded? Each needs genesis balance
+4. Subnet Actor registered? Should appear in list
+
+## Performance Tuning
+
+### Optimize Checkpoint Submission
+- Reduce `bottomup_check_period` for faster cross-net messages
+- Increase `MAX_MSGS_PER_BATCH` to batch more messages
+- Run multiple relayers for redundancy
+
+### Optimize Finality
+- Reduce finality delay (but increase reorg risk)
+- Increase validator count for faster quorum
+- Use faster parent RPC endpoint
+
+### Optimize Network
+- Deploy bootstrap nodes geographically distributed
+- Use persistent peer connections
+- Enable Prometheus metrics for monitoring
+
+## Monitoring Metrics
+
+### Critical Metrics
+- Time since last checkpoint submitted
+- Parent finality lag (child view vs actual)
+- Validator signing rate
+- Cross-net message queue depth
+- Relayer submission success rate
+
+### Alerting Thresholds
+- ⚠️ No checkpoint submitted in 2x checkpoint period
+- ⚠️ Parent finality lag > 100 blocks
+- ⚠️ Validator missed >10% of checkpoint signatures
+- ⚠️ Message queue > 80% of MAX_MSGS_PER_BATCH
+
+## Useful Links
+
+- **Documentation**: [docs/ipc/](.)
+- **Architecture Details**: [architecture-overview.md](./architecture-overview.md)
+- **Usage Guide**: [usage.md](./usage.md)
+- **Contract Reference**: [contracts.md](./contracts.md)
+- **Troubleshooting**: [../troubleshooting-subnet-deployment.md](../troubleshooting-subnet-deployment.md)
+- **IPC Website**: https://www.ipc.space/
+- **Calibration Faucet**: https://faucet.calibration.fildev.network/funds.html
+
+## Quick Start Checklist
+
+### For Users
+- [ ] Install IPC CLI: `make build`
+- [ ] Initialize config: `ipc-cli config init`
+- [ ] Create wallet: `ipc-cli wallet new --wallet-type evm`
+- [ ] Get testnet FIL from faucet
+- [ ] Join existing subnet: `ipc-cli subnet join --subnet <ID> --collateral 10`
+- [ ] Test cross-net: `ipc-cli cross-msg fund --subnet <ID> 1`
+
+### For Validators
+- [ ] Export validator key: `ipc-cli wallet export --wallet-type evm --address <ADDR> --hex`
+- [ ] Join subnet with collateral: `ipc-cli subnet join --subnet <ID> --collateral 10`
+- [ ] Deploy Fendermint node: `cargo make child-validator`
+- [ ] Monitor node logs: `docker logs -f fendermint`
+- [ ] Run relayer: `ipc-cli checkpoint relayer --subnet <ID>`
+
+### For Subnet Creators
+- [ ] Design subnet parameters (validators, collateral, period)
+- [ ] Deploy subnet actor via registry
+- [ ] Fund initial validators: `ipc-cli cross-msg pre-fund`
+- [ ] Wait for minimum validators to join
+- [ ] Coordinate validator node deployment
+- [ ] Bootstrap subnet and deploy infrastructure
+- [ ] Monitor checkpoint submissions
+
+---
+
+**Version**: 1.0  
+**Last Updated**: January 2026
diff --git a/docs/ipc/img/ipc-detailed-architecture.png b/docs/ipc/img/ipc-detailed-architecture.png
new file mode 100644
index 0000000000..59deba0843
Binary files /dev/null and b/docs/ipc/img/ipc-detailed-architecture.png differ
diff --git a/docs/ipc/img/ipc-fund-release-sequences.png b/docs/ipc/img/ipc-fund-release-sequences.png
new file mode 100644
index 0000000000..efb4340a91
Binary files /dev/null and b/docs/ipc/img/ipc-fund-release-sequences.png differ
diff --git a/docs/ipc/img/ipc-simplified-architecture.png b/docs/ipc/img/ipc-simplified-architecture.png
new file mode 100644
index 0000000000..34ab6a549c
Binary files /dev/null and b/docs/ipc/img/ipc-simplified-architecture.png differ
diff --git a/docs/ipc/img/ipc-validator-lifecycle.png b/docs/ipc/img/ipc-validator-lifecycle.png
new file mode 100644
index 0000000000..adee56e99a
Binary files /dev/null and b/docs/ipc/img/ipc-validator-lifecycle.png differ
diff --git a/docs/ipc/protocol-capture.md b/docs/ipc/protocol-capture.md
new file mode 100644
index 0000000000..8ad9e716bc
--- /dev/null
+++ b/docs/ipc/protocol-capture.md
@@ -0,0 +1,489 @@
+# IPC Protocol Capture
+
+> Protocol capture document describing how IPC works, components, mechanisms, status, open questions, and dependencies.
+
+## Table of Contents
+
+1. [Intro / Overview](#intro--overview)
+2. [Primitives & Definitions](#primitives--definitions)
+3. [Concepts (Mechanisms)](#concepts-mechanisms)
+4. [Components](#components)
+5. [Operation](#operation)
+6. [Security Guarantees](#security-guarantees)
+7. [Configuration](#configuration)
+8. [Dependencies](#dependencies)
+9. [Appendices](#appendices)
+
+---
+
+## Intro / Overview
+
+### Introduction
+
+**InterPlanetary Consensus (IPC)** is a flexible blockchain extensibility solution—a **sidechain system** in which users can delegate operations to dedicated autonomous blockchains (subnets) whose state is anchored back into higher-security, less-capable chains. Subnets can be further extended with lower-level subnets in a **recursive** manner.
+
+IPC subnets are full, sufficiently **decentralized** blockchains **owning their data**, unlike rollups that rely on centralized sequencers and post significant data to the main chain. Subnets are **highly configurable**, **specialized**, and **fine-tuned**. IPC imposes **minimal requirements** on the target chain’s capabilities; subnets can even be anchored into chains with limited programmability (e.g., Bitcoin). Anchoring subnet state into higher-security chains provides **checkpoint-based objectivity**, facilitating dynamic joining and light clients secured against long-range attacks without social consensus. Transitively checkpointing into a common chain establishes **eventual consistency** across autonomous subnets, improving **composability** and coordination of cross-chain operations.
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| **Recursive scalability** | Subnets can spawn child subnets indefinitely, forming a tree hierarchy |
+| **Cross-net communication** | Secure message passing between parent and child (top-down and bottom-up) |
+| **Flexible consensus** | Each subnet can customize block time, validator requirements, and consensus parameters. *Currently only CometBFT is implemented; rollups and sequencer-based subnets are intended.* |
+| **Ethereum compatibility** | Full FEVM support for Solidity smart contracts |
+| **Native FVM support** | Access to Filecoin's actor model and built-in capabilities |
+
+**Expanded capability areas** (from conceptual framing):
+
+- **Dynamic scalability**: Subnets optimized for performance; checkpoint-based objectivity enables trustless bootstrapping; elastic scaling through programmatic launch/termination
+- **Customizability**: Configurable consensus, execution (WASM & EVM), tokenomics, data availability, governance; permissioned or permissionless; regional or application-specific
+- **Seamless interoperability**: Native cross-chain communication; protocol-native bridging secured by checkpointing; eventual consistency across subnets
+- **Autonomy & sovereignty**: Subnets govern lifecycle, configuration, validator sets; partition tolerance (local finality when disconnected)
+- **Objective security**: Checkpoint-based objectivity; trust anchors verifiable without social consensus; long-range attack mitigation
+- **Risk containment**: Security boundaries between subnets; failures confined to affected subnet
+
+### Core Concepts
+
+| Concept | Definition |
+|---------|------------|
+| [Subnet](#subnet) | Autonomous blockchain whose state is anchored into a parent chain |
+| [Parent chain](#parent-chain) | Blockchain that a subnet anchors into |
+| [Rootnet](#rootnet) | Blockchain with no parent (e.g., Filecoin) |
+| [Subnet ID](#subnet-id) | Address identifying the subnet (root chain ID + route of subnet actor addresses) |
+| [Checkpoint](#checkpoint) | Periodic commitment of subnet state to parent; cryptographic reference to finalized chain head |
+| [Cross-net messages](#cross-net-message) | Messages between chains; top-down (e.g., deposits) and bottom-up (e.g., withdrawals) |
+
+> **Note**: Currently, cross-net messages are supported for directly linked chains only (single-hop parent↔subnet). See [Primitives & Definitions](#primitives--definitions) for fuller definitions.
+>
+> **Implementation status**: Only CometBFT-based subnets are implemented today. The protocol is designed to support other consensus mechanisms (e.g., rollups, sequencer-based subnets); these are intended but not yet implemented.
+
+### How IPC Works (Conceptual)
+
+IPC combines several mechanisms:
+
+- **Checkpointing**: Anchors subnet state into parent; ensures checkpoints correspond to actual state; enables bridging
+- **Bridging**: Secures transfer of information and assets; relies on checkpointing; uses cross-net messages
+- **Subnet ID management**: Governs subnet ID namespaces and assignment
+- **Subnet lifecycle management**: Registration, activation, termination
+- **Subnet configuration management**: Validator set, voting power, config updates
+
+**Flow**: Given a rootnet (root of trust), new subnets obtain a subnet ID and register. Lifecycle management governs activation (e.g., collateral for PoS). Configuration management handles validator set and updates. Subnets operate autonomously; checkpoints periodically bind state to parent. Bridging uses the same cross-net message carrier for deposits (lock+mint) and withdrawals (burn+release).
+
+![IPC Simplified Architecture](./img/ipc-simplified-architecture.png)
+
+### Key Principles
+
+*Proposed from protocol design goals—to be refined:*
+
+- **Objectivity**: Checkpoint-based trust anchors; no social consensus required
+- **Autonomy**: Self-governance, self-sovereignty; subnets own their data
+- **Impact containment**: Firewalling; failures isolated to affected subnet
+- **Flexibility**: Modularity, customizability, extensibility
+- **Dynamicity**: On-demand scaling, elasticity
+- **Partition tolerance**: Local finality when disconnected; consistency restored on reconnection
+- **Seamless interoperability**: Native cross-net communication; eventual consistency
+
+### Requirements & Properties
+
+*Proposed placement: overlaps with [Security Guarantees](#security-guarantees) (trust assumptions) and [Configuration](#configuration) (constraints). Could be a short subsection here or consolidated there.*
+
+- **Core assumptions**: Rootnet exists and is trusted; >2/3 validator honesty; reliable parent RPC
+- **Constraints**: Single-hop messaging (current); supply source immutability
+- **Guarantees**: Message integrity, ordering, value safety, risk containment
+
+---
+
+## Primitives & Definitions
+
+*Canonical definitions—reference these from [Concepts](#concepts-mechanisms) and [Components](#components) to avoid repetition.*
+
+### ABCI++
+
+Application Blockchain Interface. Protocol for CometBFT to communicate with the application layer. Defines `PrepareProposal`, `ProcessProposal`, and `FinalizeBlock`.
+
+### Bottom-up
+
+Information flow from child subnet to parent. Includes [checkpoints](#checkpoint) and bottom-up messages (e.g., [withdrawals](#withdrawal)). Propagated by the [Relayer](#relayer).
+
+### Checkpoint
+
+Batch of child subnet state and bottom-up messages submitted to the parent with validator signatures. Contains: subnet_id, block_height, block_hash, prev_checkpoint_height, cross_messages, next_configuration_number. Block hash anchors against long-range attacks. Created by validators; submitted by the [Relayer](#relayer); validated by the parent [Gateway](#gateway).
+
+### Configuration ID
+
+Version number for the validator set. Increments when [StakeChangeRequest](#stakechangerequest)s (join, leave, stake, unstake) are applied. Child confirms adoption via `next_configuration_number` in [checkpoints](#checkpoint); parent releases collateral when checkpoint is committed.
+
+### Cross-net message
+
+Message sent between chains. [Top-down](#top-down) (parent→child) or [bottom-up](#bottom-up) (child→parent). Carried in an [IpcEnvelope](#ipcenvelope). Currently single-hop (direct parent↔child) only.
+
+### Deposit
+
+[Top-down](#top-down) message carrying assets. Implemented as `fund` (native) or `fundWithToken` (ERC20) on the [Gateway](#gateway).
+
+### Gateway
+
+Singleton contract in every subnet. Manages collateral, firewall, cross-net routing, and [checkpoint](#checkpoint) validation. Executes top-down and bottom-up messages. Participates in [checkpointing](#checkpointing), [messaging](#messaging), and [bridging](#bridging).
+
+### IpcEnvelope
+
+Structure carrying a cross-net message: kind (Transfer, Call, Result), from/to ([Subnet ID](#subnet-id) + address), value, message bytes, nonces. Used for routing via [postbox](#postbox) and [LCA](#lca-lowest-common-ancestor) determination.
+
+### LCA (Lowest Common Ancestor)
+
+Subnet in the hierarchy that is an ancestor of both source and destination. Used to route [cross-net messages](#cross-net-message) and determine top-down vs bottom-up direction.
+
+### Parent chain
+
+Blockchain that a subnet anchors into. Hosts the [Subnet Actor](#subnet-actor) for each child; receives [checkpoints](#checkpoint) from children.
+
+### Parent finality
+
+Child subnet’s committed view of which parent block is final. Validators vote on parent (height, hash) via GossipSub; VoteTally detects quorum; proposer includes `ParentFinality` in the child block. Triggers execution of top-down messages.
+
+### Postbox
+
+Storage on intermediate subnets for [cross-net messages](#cross-net-message) in transit. Messages are propagated from the postbox to the next hop (parent or child) based on routing.
+
+### Quorum
+
+>2/3 of validator power. Threshold for checkpoint signing, parent finality votes, and BFT consensus.
+
+### Registry
+
+Factory contract for deploying reference [Subnet Actor](#subnet-actor) implementations. One per subnet.
+
+### Relayer
+
+Off-chain process that monitors the child subnet for `QuorumReached` events, retrieves the signed [checkpoint](#checkpoint) and validator signatures, and submits it to the parent [Gateway](#gateway). Performs the submission step of [checkpointing](#checkpointing). Permissionless; requires L1 funds.
+
+### Rootnet
+
+Blockchain with no parent (e.g., Filecoin). Root of trust for the IPC hierarchy.
+
+### StakeChangeRequest
+
+Request for validator set change (join, leave, stake, unstake, setFederatedPower). Identified by [configuration ID](#configuration-id). Propagated via [parent finality](#parent-finality); executed in child; confirmed in [checkpoint](#checkpoint).
+
+### Subnet
+
+Autonomous blockchain whose state is anchored into a [parent chain](#parent-chain). Has its own validators, consensus, and execution. Can spawn child subnets recursively.
+
+### Subnet Actor
+
+Contract governing a specific child subnet. Deployed in the parent. Defines [supply source](#supply-source), genesis, permission mode. One [Subnet Actor](#subnet-actor) per child subnet. Calls `register` on parent [Gateway](#gateway) when bootstrap conditions are met.
+
+### Subnet ID
+
+Address identifying a subnet. Format: root (chain ID) + route (array of [Subnet Actor](#subnet-actor) addresses top-to-bottom). String representation: `/r314159/t410f.../t410f...`. Assigned when [Subnet Actor](#subnet-actor) is deployed.
+
+### Supply Source
+
+Source of subnet native coin. **Native**: parent’s native coin (e.g., FIL). **ERC20**: ERC20 on parent locked, minted in subnet. Set at subnet creation; immutable.
+
+### Top-down
+
+Information flow from parent to child. Includes [parent finality](#parent-finality), top-down messages (e.g., [deposits](#deposit)), and validator set changes. Propagated via parent finality commitment in child blocks.
+
+### VoteTally
+
+*Deprecated — will be removed soon.* Mechanism tracking validator votes on [parent finality](#parent-finality). Detects quorum; informs block proposer which parent block to include.
+
+### Withdrawal
+
+[Bottom-up](#bottom-up) message carrying assets. Implemented as `release` on the [Gateway](#gateway). Batched in [checkpoint](#checkpoint); submitted by [Relayer](#relayer); executed on parent.
+
+---
+
+## Concepts (Mechanisms)
+
+*Abstract/conceptual level—spans multiple components.*
+
+### Subnet ID Management
+
+See [Subnet ID](#subnet-id) for definition. Assigned when [Subnet Actor](#subnet-actor) is deployed (via [Registry](#registry) or custom). Route grows as child subnets are created. Binary: `keccak256(abi.encode(SubnetID))` for equality checks and storage.
+
+### Subnet Lifecycle Management
+
+1. **Creation**: Deploy [Subnet Actor](#subnet-actor) in [parent chain](#parent-chain) (via [Registry](#registry) or custom); configure [supply source](#supply-source), permission mode, genesis
+2. **Registration**: Once min validators/collateral met, [Subnet Actor](#subnet-actor) calls `register` on parent [Gateway](#gateway)
+3. **Active**: Subnet produces blocks, creates [checkpoints](#checkpoint), processes messages
+4. **Termination**: Subnet can be killed (governance-dependent); collateral released per [checkpoint](#checkpoint) confirmation
+
+### Subnet Configuration Management
+
+Validator set and voting power managed on parent, propagated via [top-down](#top-down):
+
+- [StakeChangeRequest](#stakechangerequest)s identified by [configuration ID](#configuration-id)
+- Propagated via [parent finality](#parent-finality) commitment in child blocks
+- Child executes changes; confirms via `next_configuration_number` in [checkpoint](#checkpoint)
+- Parent confirms collateral release when [checkpoint](#checkpoint) is committed
+
+### Checkpointing
+
+Periodically anchors subnet state into parent. See [Checkpoint](#checkpoint) for structure.
+
+**Flow**:
+1. Every `bottomup_check_period` blocks (or when `MAX_MSGS_PER_BATCH` hit), validators create [checkpoint](#checkpoint)
+2. Validators call `addCheckpointSignature`; [quorum](#quorum) triggers `QuorumReached` event
+3. [Relayer](#relayer) submits [checkpoint](#checkpoint) + signatures to parent [Gateway](#gateway)
+4. Parent verifies against last known validator set, executes [bottom-up](#bottom-up) messages
+
+### Messaging
+
+Transport layer for cross-subnet communication. [Bridging](#bridging) uses this as transport.
+
+**Flows**: [Top-down](#top-down) (propagated via [parent finality](#parent-finality)) and [bottom-up](#bottom-up) (batched in [checkpoints](#checkpoint), submitted by [Relayer](#relayer)).
+
+**Types**: Transfer ([deposit](#deposit)/[withdrawal](#withdrawal)), Call (general contract-to-contract), Result (response). Mechanisms: [IpcEnvelope](#ipcenvelope), [postbox](#postbox), [LCA](#lca-lowest-common-ancestor) routing.
+
+### Bridging
+
+Moving value/assets between subnets—built on [messaging](#messaging). Uses [Gateway](#gateway) for native flows.
+
+**Native**: [Supply source](#supply-source). [Deposit](#deposit)/[withdrawal](#withdrawal) for native; lock+mint / burn+release for ERC20.
+
+**Custom**: Linked Token pattern for arbitrary ERC20s via general [cross-net messages](#cross-net-message). Lock on origin, mint on target; burn on target, release on origin.
+
+### Consensus
+
+- **Subnet consensus**: CometBFT (BFT, [quorum](#quorum)) — *currently the only implemented consensus mechanism*. Rollups and sequencer-based subnets are intended future implementations.
+- **[Parent finality](#parent-finality)**: Validators poll parent, vote via GossipSub; [VoteTally](#votetally) detects quorum; proposer includes `ParentFinality` in block
+
+### On-Chain vs Off-Chain
+
+| Aspect | On-Chain | Off-Chain |
+|--------|----------|-----------|
+| [Gateway](#gateway), [Subnet Actor](#subnet-actor), [Registry](#registry) | ✓ | |
+| Message execution, [checkpoint](#checkpoint) validation | ✓ | |
+| Consensus (CometBFT) | Runs on nodes | |
+| Parent Syncer, IPLD Resolver | | Polls/resolves |
+| [Relayer](#relayer), IPC Provider, ipc-cli | | Submits, queries, signs |
+
+---
+
+## Components
+
+![IPC Detailed Architecture](./img/ipc-detailed-architecture.png)
+
+### Actors (WASM)
+
+IPC subnets run the **FVM**, which executes **WASM-based actors** (Filecoin execution model):
+
+- Built-in actors (Account, Init, EVM, etc.)
+- Custom actors deployable by subnets
+- Shared across root (Lotus) and child subnets (Fendermint)
+
+### Contracts (Solidity) — Onchain Actors
+
+**Status**: 🔴 *Needs consolidation with implementation details*
+
+| Contract | Location | Responsibility |
+|----------|----------|----------------|
+| **[Gateway](#gateway)** | Singleton in every subnet | Collateral, firewall, cross-net routing, [checkpoint](#checkpoint) validation |
+| **[Subnet Actor](#subnet-actor)** | One per child, deployed in parent | [Supply source](#supply-source), genesis, permission mode, validator set |
+| **[Registry](#registry)** | Per subnet | Factory for [Subnet Actor](#subnet-actor) implementations |
+
+**Architecture**: Diamond pattern (EIP-2535), AppStorage for shared state. Participates in [checkpointing](#checkpointing), [messaging](#messaging), [bridging](#bridging).
+
+### Node (Subnet Validator Node)
+
+**Fendermint** — subnet peer implementation:
+
+| Layer | Component | Responsibility |
+|-------|-----------|----------------|
+| 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) |
+| Data | IPLD Resolver | CID resolution, data availability |
+
+**Node lifecycle**: Genesis → Bootstrap (register) → Validation → Shutdown (leave/unstake).
+
+### IPC Provider (Parent Chain Provider)
+
+**Status**: 🟢 [needs review]  
+**Code**: [ipc/provider/src/lib.rs](https://github.com/consensus-shipyard/ipc/blob/main/ipc/provider/src/lib.rs)
+
+Wraps ethers library and contract ABIs for parent chain interaction. Used by ipc-cli and relayer.
+
+**Responsibilities**:
+- Calling parent contracts ([Gateway](#gateway), [Subnet Actor](#subnet-actor), [Registry](#registry))
+- Subnet lifecycle interaction (create, join, leave, list)
+- Fetching subnet genesis and [top-down](#top-down) queries (messages, validator changes)
+- Enabling [Relayer](#relayer) to interact with parent and child
+
+### Relayer (Off-Chain)
+
+**Status**: 🟡
+
+**Overview**: Performs the submission step of [checkpointing](#checkpointing). Monitors child subnet for `QuorumReached` events; assembles [checkpoint](#checkpoint) + validator signatures; submits to parent [Gateway](#gateway) via `submitCheckpoint`.
+
+**Flow**: L2 contract event → retrieve signed [checkpoint](#checkpoint) → construct proofs (CometBFT light client) → submit to L1 for execution.
+
+**Dependencies**: Requires funds on L1 to submit transactions.
+
+**Known issues / improvement areas**:
+- Needs better events/observability
+- No rewards system for incentivization (message fees exist but mechanism needs refinement)
+- First-come-first-serve: issues if relayer goes down; no built-in redundancy protocol
+
+---
+
+## Operation
+
+### Creating & Destroying Subnets
+
+**Create**: Deploy [Subnet Actor](#subnet-actor) via [Registry](#registry) or custom; configure min_validators, min_collateral, [supply source](#supply-source); wait for bootstrap (join + collateral). [Subnet Actor](#subnet-actor) calls `register` on [Gateway](#gateway) when ready.
+
+**Destroy**: Governance-dependent; subnet can be killed; validators leave; collateral released as [checkpoints](#checkpoint) confirm.
+
+### Joining & Leaving Subnets
+
+![IPC Validator Lifecycle](./img/ipc-validator-lifecycle.png)
+
+**Join**: Call `join` on [Subnet Actor](#subnet-actor) with collateral; creates [StakeChangeRequest](#stakechangerequest); propagated via [top-down](#top-down) [parent finality](#parent-finality); child executes; confirmed in [checkpoint](#checkpoint). ~5–10 min.
+
+**Leave**: Call `leave` or `unstake`; same propagation; child removes/reduces; parent releases collateral when [checkpoint](#checkpoint) committed. Claim via `ipc-cli subnet claim`. ~5–10 min to leave; claim is immediate once confirmed.
+
+### Depositing & Withdrawing Assets
+
+![IPC Fund and Release Operations](./img/ipc-fund-release-sequences.png)
+
+**Deposit (fund)**: [Deposit](#deposit)—call `fund` (or `fundWithToken` for ERC20) on parent [Gateway](#gateway); [top-down](#top-down) message; executed in child when [parent finality](#parent-finality) committed. ~2–5 min depending on finality delay.
+
+**Withdraw (release)**: [Withdrawal](#withdrawal)—call `release` on child [Gateway](#gateway); [bottom-up](#bottom-up) message; batched in [checkpoint](#checkpoint); [Relayer](#relayer) submits; executed on parent. ~5–10 min depending on checkpoint period.
+
+### General Message Passing
+
+Contract-to-contract via `sendContractXnetMessage` (Call kind). [IpcEnvelope](#ipcenvelope) carries payload; [postbox](#postbox) routes at intermediate subnets; destination contract implements `handleIpcMessage`. Result messages propagate back. *Currently single-hop for direct parent-child; multi-hop routing supported in protocol.*
+
+---
+
+## Security Guarantees
+
+### Trust Assumptions
+
+1. **L1 Security**: Root network (e.g., Filecoin) is trusted and secure
+2. **Validator honesty**: >2/3 of validator power is honest in each subnet
+3. **Economic security**: Collateral discourages malicious behavior
+4. **Finality delay**: Parent blocks delayed sufficiently to avoid reorgs
+5. **RPC reliability**: Validators have access to reliable parent RPC
+
+### Attack Mitigations
+
+| Threat | Mitigation |
+|--------|------------|
+| Long-range attacks | Block hash anchored in checkpoints |
+| Double-spend | BFT consensus + checkpoint finality |
+| Validator collusion | Requires >2/3 stake; economically irrational |
+| Checkpoint censorship | Multiple relayers provide redundancy |
+| Parent reorg | Finality delay ensures stability |
+
+### Guarantees Provided
+
+- **Message integrity**: Envelopes signed/verified
+- **Ordering**: Deterministic execution via parent finality and checkpoint ordering
+- **Value safety**: Lock-before-mint; burn-before-release
+- **Validator set sync**: Configuration number confirms membership; parent releases collateral only after child confirms
+- **Risk containment**: Failures isolated to affected subnet
+
+### Caveats
+
+- Security decreases with hierarchy depth
+- Federated subnets rely on admin honesty
+- Gateway/Registry upgrades may introduce trust
+
+### Economic Incentives
+
+**Top-down**: Gas paid in parent; no additional fee in child.
+
+**Bottom-up**: Cross-message fee paid by sender (rewards relayer); execution gas paid by relayer (compensated by fee); fee set by subnet policy.
+
+**Collateral**: Required for collateral mode; slashing/penalties depend on subnet governance.
+
+---
+
+## Configuration
+
+### Subnet Creation Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `min_validators` | Minimum validators to bootstrap |
+| `min_collateral` | Minimum total collateral |
+| `bottomup_check_period` | Blocks between checkpoints |
+| `active_validators_limit` | Max active validators |
+| `majority_percentage` | Quorum threshold (typically 67%) |
+| `supply_source_kind` | Native or ERC20 |
+| `supply_source_address` | ERC20 address (if ERC20) |
+
+### Operational Parameters
+
+| Parameter | Typical Value | Description |
+|-----------|---------------|-------------|
+| `finality_delay` | 10–20 blocks | Parent blocks before final |
+| `max_proposal_range` | ~50 blocks | Max parent height advance per child block |
+| `MAX_MSGS_PER_BATCH` | 100 | Triggers intermediate checkpoint |
+
+### Configuration Files
+
+- **ipc-cli**: `~/.ipc/config.toml` — subnets, keystore_path
+- **Fendermint**: `~/.fendermint/config/` — ABCI, DB, resolver, eth RPC
+
+---
+
+## Dependencies
+
+### CometBFT
+
+Consensus engine for subnet blocks. ABCI++ interface. Critical for block production, P2P, proposal/vote flow. *Currently the only implemented subnet consensus mechanism; rollups and sequencer-based subnets are planned.*
+
+### Other Key Dependencies
+
+| Dependency | Usage |
+|------------|-------|
+| FVM | Execution (WASM, FEVM) |
+| IPLD / Bitswap | Data availability, CID resolution |
+| Ethers / Foundry | Contracts, testing |
+| Filecoin / Lotus | Root network |
+
+---
+
+## Appendices
+
+*Supplementary information: detailed specs, diagrams, implementation notes.*
+
+- [IPC Actors Spec](../../specs/ipc-actors.md)
+- [Supply Sources](../../specs/supply-sources.md)
+- [Addressing](../../specs/addressing.md)
+- [Architecture Overview](./architecture-overview.md)
+- [Architecture Quick Reference](./architecture-quick-reference.md)
+
+---
+
+## 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 |
+
+---
+
+**Document Version**: 2.0  
+**Last Updated**: February 2026  
+**Status**: Living document — merge of protocol capture v1 with enriched source. Expand status, issues, open questions per section as needed.