(WIP) docs revamp.

CHANGELOG.md

@@ -178,7 +178,7 @@ _Full changelog below._
 
 IPC now emits events during execution. These events are recorded in the Journal, and are transformed into Prometheus metrics. Observability configuration is performed via `config.toml`.
 
-Refer to full observability documentation [here](./docs/fendermint/observability.md).
+Refer to full observability documentation [here](docs/00-learn/01-concepts/observability.md).
 
 ### New events and metrics
 

README.md

@@ -67,13 +67,13 @@ make test
 
 For further documentation, see:
 
-- [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/contracts.md](docs/02-develop/contracts.md) for instructions on how to deploy FEVM actors on subnets.
+- [docs/usage.md](docs/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/01-setup/deploying-hierarchy.md) for instructions on how to deploy your own instance of IPC on a network.
 
 If you are a developer, see:
 
-- [docs/developers.md](./docs/ipc/developers.md) for useful tips and guides targeted for IPC developers.
+- [docs/developers.md](docs/04-troubleshoot/developers.md) for useful tips and guides targeted for IPC developers.
 
 ## Connecting to a rootnet
 

docs/ipc/quickstart-calibration.md

@@ -1 +0,0 @@
-# Moved to [IPC Docs](https://docs.ipc.space/quickstarts/deploy-a-subnet)

docs/fendermint/architecture.md → docs/site/00-overview/architecture-2.md

@@ -3,8 +3,6 @@
 The following diagrams show preliminary vision for the collaboration between the Filecoin rootnet and the subnets,
 some of which can be implemented using Fendermint:
 
-![Architecture](images/IPC%20with%20Tendermint%20Core.jpg)
-
 The components in a nutshell:
 
 * __Lotus rootnet__: Lotus has to support IPC to act as the rootnet for its child subnets. There are competing proposals with regards to this being in the form of mostly user-deployed smart contracts, or built-in (privileged) capabilities.

docs/fendermint/checkpointing.md → docs/site/01-concepts/checkpointing.md

@@ -8,18 +8,12 @@ Bottom-up checkpoints are periodically submitted to the parent subnet, carrying:
 * the identity of the checkpointed block height
 
 The high level steps are implemented in the [checkpoint](../fendermint/vm/interpreter/src/fvm/checkpoint.rs) module,
-which calls various methods on the [Gateway actor](https://github.com/consensus-shipyard/ipc-solidity-actors/tree/dev/src/gateway),
-but the end-to-end flow also relies on a working [IPC Agent](https://github.com/consensus-shipyard/ipc/)
-and potentially the [IPLD Resolver](https://github.com/consensus-shipyard/ipc-ipld-resolver).
+which calls various methods on the [Gateway actor](https://github.com/consensus-shipyard/ipc-solidity-actors/tree/dev/src/gateway), but the end-to-end flow also relies on a working [IPC Agent](https://github.com/consensus-shipyard/ipc/) and potentially the [IPLD Resolver](https://github.com/consensus-shipyard/ipc-ipld-resolver).
 
 The following diagram illustrates the sequence of events in detail:
 
 ![Checkpointing](diagrams/checkpointing.png)
 
-The above scenario assumes that the parent subnet is running Lotus, where we are restricted to using Solidity actors,
-and therefore the relayers include all bottom-up messages in their transaction, which creates redundancy but makes the
-messages trivially available for execution.
+The above scenario assumes that the parent subnet is running Lotus, where we are restricted to using Solidity actors, and therefore the relayers include all bottom-up messages in their transaction, which creates redundancy but makes the messages trivially available for execution.
 
-If both the parent and the child were Fendermint nodes, we'd have the option to use the IPLD Resolver to only include the CID
-of the messages in the relayed checkpoint messages, and let Fendermint make sure the data is available before proposing it
-for execution.
+If both the parent and the child were Fendermint nodes, we'd have the option to use the IPLD Resolver to only include the CID of the messages in the relayed checkpoint messages, and let Fendermint make sure the data is available before proposing it for execution.

docs/fendermint/observability.md → docs/site/01-concepts/observability.md

@@ -6,7 +6,7 @@ IPC's observability framework emits events throughout execution, which are recor
 This enables detailed monitoring and analysis of system behavior.
 This is achieved through the use of the `ipc-observability` crate/library, which provides all the necessary helpers and tools to facilitate this process.
 
-### How it works
+## Key features
 
 1. **Events**: Specific events are defined and triggered throughout the codebase to capture significant occurrences or actions.
    These events encapsulate relevant data and context about what is happening within the system.

docs-gitbook/concepts/subnets/parent-child-interactions.md → docs/site/01-concepts/parent-child-interactions.md

@@ -4,17 +4,12 @@ The interaction between two subnets in a parent-child relation, is the basic bui
 
 There are following parent-child interactions available in IPC
 
-1\. Creating child subnets in the IPC hierarchy. 
-
-2\. Depositing funds from an account in a subnet to an account in its child. 
-
-3\. Withdrawing funds from an account in a subnet to an account in its parent. 
-
-4\. Checkpointing a subnet’s replicated state in the replicated state of its parent.
-
-5\. Invoking actor functions across subnets.
-
-6\. Removing child subnets from the IPC hierarchy.
+1. Creating child subnets in the IPC hierarchy.
+2. Depositing funds from an account in a subnet to an account in its child.
+3. Withdrawing funds from an account in a subnet to an account in its parent.
+4. Checkpointing a subnet's replicated state in the replicated state of its parent.
+5. Invoking actor functions across subnets.
+6. Removing child subnets from the IPC hierarchy.
 
 ## Checkpointing
 
@@ -26,18 +21,18 @@ In case of subnet failure, checkpointing enables participants (e.g., former user
 
 ### Checkpointing fees
 
-There are a number of fees that are paid during checkpointing: 
+There are a number of fees that are paid during checkpointing:
 
-* When a subnet checkpoints its state to a parent, this is the equivalent of a transaction on the parent.  The usual transaction fees of the parent are paid to accomplish this. 
-* In order for a subnet to be considered _anchored_ to the parent, relayers must have sufficient funds in their respective wallets in the parent to be able to pay for a checkpointed transaction. 
-* When a cross-net transaction is included in a subnet's checkpoint to a parent, the fees for that transaction are distributed as a reward equally among all the relayers that have submitted an instance of that checkpoint.   
+* When a subnet checkpoints its state to a parent, this is the equivalent of a transaction on the parent.  The usual transaction fees of the parent are paid to accomplish this.
+* In order for a subnet to be considered _anchored_ to the parent, relayers must have sufficient funds in their respective wallets in the parent to be able to pay for a checkpointed transaction.
+* When a cross-net transaction is included in a subnet's checkpoint to a parent, the fees for that transaction are distributed as a reward equally among all the relayers that have submitted an instance of that checkpoint.  
 * Relayers are allowed to submit a checkpoint and eligible for rewards from the commitment of the first checkpoint in, e.g. epoch \`h\`, to the first submission of a checkpoint of epoch \`h+1\`. From this point on, no new valid submissions for checkpoint \`h\` will be accepted.
 
 ## Parent finality
 
 Parent finality is a mechanism for proving that a subnet irreversibly reached a certain state.
 
-It is achieved in the following way 
+It is achieved in the following way
 
 * Validators in the child subnet periodically listen to new blocks from the parent. On the implementation level it is performed by Fendermint node of subnet validator subscribing to events via parent's ETH RPC.
 * As part of the consensus algorithm in the child, the leader of the consensus proposes the height and hash of the parent’s block that they currently consider final.

docs-gitbook/concepts/subnets/README.md → docs/site/01-concepts/subnets.md

@@ -6,42 +6,42 @@ A subnet is a new subsystem that a user can spawn from a parent subnet in a perm
 
 ## Hierarchy trees
 
-Subnets begin with a chosen "rootnet". Rootnets refer to a layer 1 blockchain, such as Filecoin or Ethereum. Child subnets are spawned from the rootnet and the rootnet becomes the parent subnet. 
+Subnets begin with a chosen "rootnet". Rootnets refer to a layer 1 blockchain, such as Filecoin or Ethereum. Child subnets are spawned from the rootnet and the rootnet becomes the parent subnet.
 
-Each subnet can have any number of child subnets, while each child subnet only has one parent subnet. Subnets can scale infinitely, to layer 2 and beyond. A single hierarchy tree begins at the chosen rootnet. 
+Each subnet can have any number of child subnets, while each child subnet only has one parent subnet. Subnets can scale infinitely, to layer 2 and beyond. A single hierarchy tree begins at the chosen rootnet.
 
 Subnets within a single hierarchy tree have native communication protocols and are able to transfer assets and state without a custom bridge.
 
 ## Lifecycle
 
-The lifecycle of a subnet begins when it’s established and ends when the subnet is closed.  
+The lifecycle of a subnet begins when it’s established and ends when the subnet is closed. 
 
 At the time of subnet creation, a minimum collateral requirement is set by the subnet creator.  A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet.
 
-Conditions for closing a subnet include: 
+Conditions for closing a subnet include:
 
 * A child subnet cannot be killed until its circulating supply is zero, which can be achieved when all users send their funds back to a parent.
 * If all validators leave a subnet even when their are still users of the subnet, the users will have to either run their own validator or wait for a validator to return to the subnet.
-* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee. 
+* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee.
 
 ## Staking
 
-It’s likely that many IPC subnets will be subnets of proof-of-stake chains, or the subnets themselves will be proof of stake chains to other types of chains.  For this reason, IPC has native functionality that is intended to handle staking with respect to subnets.  These native functionalities include staking and releasing collateral associated with subnet validators and slashing collateral associated with a provably misbehaving subnet validator. 
+It’s likely that many IPC subnets will be subnets of proof-of-stake chains, or the subnets themselves will be proof of stake chains to other types of chains.  For this reason, IPC has native functionality that is intended to handle staking with respect to subnets.  These native functionalities include staking and releasing collateral associated with subnet validators and slashing collateral associated with a provably misbehaving subnet validator.
 
-## Fees 
+## Fees
 
 ### Establishing a subnet
 
-There are a number of fees that are paid when a subnet is established: 
+There are a number of fees that are paid when a subnet is established:
 
-* At the time of subnet creation, a minimum collateral requirement is set by the subnet creator. 
-* A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. 
-* When a participant or validator (other than the subnet creator) joins the subnet, initial funds for their participation in the subnet should be moved from their respective account in the parent by using the `join` command.  This also enables the signing of checkpoint transactions. 
+* At the time of subnet creation, a minimum collateral requirement is set by the subnet creator.
+* A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet.
+* When a participant or validator (other than the subnet creator) joins the subnet, initial funds for their participation in the subnet should be moved from their respective account in the parent by using the `join` command.  This also enables the signing of checkpoint transactions.
 
 ### Closing a Subnet
 
-The conditions for closing a subnet are as follows: 
+The conditions for closing a subnet are as follows:
 
-* A child subnet cannot be killed untill its circulating supply is zero, which can be achieved when all users send their funds back to a parent. 
-* If all validators leave a subnet even when their are still users of the subnet, the users will have to either run their own validator or wait for a validator to return to the subnet. 
-* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee. 
+* A child subnet cannot be killed untill its circulating supply is zero, which can be achieved when all users send their funds back to a parent.
+* If all validators leave a subnet even when their are still users of the subnet, the users will have to either run their own validator or wait for a validator to return to the subnet.
+* If a bug causes the subnet to fail, there is no way to recover funds in the subnet without a valid checkpoint signed by the latest validator committee.