diff --git a/CHANGELOG.md b/CHANGELOG.md index cbf239d638..f89be54652 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index d09cf704a9..fde6166eaa 100644 --- a/README.md +++ b/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 diff --git a/docs-gitbook/SUMMARY.md b/docs-gitbook/SUMMARY.md deleted file mode 100644 index 9e4ab6e337..0000000000 --- a/docs-gitbook/SUMMARY.md +++ /dev/null @@ -1,47 +0,0 @@ -# Table of contents - -## Overview - -- [Introduction](README.md) -- [How IPC works](overview/how-it-works.md) -- [Use cases](overview/use-cases.md) -- [How IPC compares](overview/how-ipc-compares.md) -- [Architecture](overview/architecture.md) - -## Quickstarts - -- [Deploy a subnet](quickstarts/deploy-a-subnet.md) - -## Concepts - -- [Subnets](concepts/subnets/README.md) - - [Parent-child interactions](concepts/subnets/parent-child-interactions.md) -- [Circulating supply](concepts/circulating-supply.md) - -## User guides - -- [Performing transactions in a subnet](user-guides/performing-transactions-in-a-subnet.md) - -## Developer Guides - -- [Customizing a subnet](developer-guides/pluggable-syscall-tutorial.md) -- [Upgrading a subnet](developer-guides/upgrades/README.md) - - [Example: Patching actor state](developer-guides/upgrades/patch-state.md) - - [Example: Upgrading Wasm actor](developer-guides/upgrades/upgrade-wasm-actor.md) -- [Deploying an explorer](developer-guides/deploy-blockscout.md) - -## Specifications - -- [Addressing](../specs/addressing.md) -- [CometBFT](../specs/cometbft.md) -- [IPLD Resolver](../specs/ipld-resolver.md) -- [Materializer](../specs/materializer.md) -- [Top-down Finality](../specs/topdown.md) -- [Bottom Up Checkpoint](../specs/bottom-up-interaction.md) - -## Reference - -- [Networks](reference/networks.md) -- [IPC CLI](reference/ipc-cli-usage.md) -- [Troubleshooting](reference/troubleshooting.md) -- [FAQ](reference/faq.md) diff --git a/docs/fendermint/diagrams/.gitignore b/docs/_deprecated/diagrams/.gitignore similarity index 100% rename from docs/fendermint/diagrams/.gitignore rename to docs/_deprecated/diagrams/.gitignore diff --git a/docs/fendermint/diagrams/Makefile b/docs/_deprecated/diagrams/Makefile similarity index 100% rename from docs/fendermint/diagrams/Makefile rename to docs/_deprecated/diagrams/Makefile diff --git a/docs/fendermint/diagrams/README.md b/docs/_deprecated/diagrams/README.md similarity index 100% rename from docs/fendermint/diagrams/README.md rename to docs/_deprecated/diagrams/README.md diff --git a/docs/fendermint/diagrams/checkpointing.png b/docs/_deprecated/diagrams/checkpointing.png similarity index 100% rename from docs/fendermint/diagrams/checkpointing.png rename to docs/_deprecated/diagrams/checkpointing.png diff --git a/docs/fendermint/diagrams/checkpointing.puml b/docs/_deprecated/diagrams/checkpointing.puml similarity index 100% rename from docs/fendermint/diagrams/checkpointing.puml rename to docs/_deprecated/diagrams/checkpointing.puml diff --git a/docs/fendermint/README.md b/docs/fendermint/README.md deleted file mode 100644 index afb5769684..0000000000 --- a/docs/fendermint/README.md +++ /dev/null @@ -1,13 +0,0 @@ -## Docs - -The following documentation should help getting oriented: - -* [Architecture Overview](./architecture.md) -* [Getting started with Tendermint](./tendermint.md) -* [Running Fendermint](./running.md) -* [Checkpointing](./checkpointing.md) -* [Running IPC infrastructure](./ipc.md) - -You can also check out the previous demos: - -* [Milestone-1 Demo](./demos/milestone-1/README.md) diff --git a/docs/fendermint/demos/milestone-1/Fendermint_Demo.pdf b/docs/fendermint/demos/milestone-1/Fendermint_Demo.pdf deleted file mode 100644 index 46e95cefe8..0000000000 Binary files a/docs/fendermint/demos/milestone-1/Fendermint_Demo.pdf and /dev/null differ diff --git a/docs/fendermint/demos/milestone-1/README.md b/docs/fendermint/demos/milestone-1/README.md deleted file mode 100644 index 741894d0cd..0000000000 --- a/docs/fendermint/demos/milestone-1/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Milestone 1 Demo - -This demo shows that FVM has been integrated into an ABCI application. It doesn't contain anything IPC specific. - -* [Overview slides](./Fendermint_Demo.pdf) -* [Overview video](https://drive.google.com/file/d/1fv1rVp9cbGuQho5jIqUCHSziJpmId57y/view?usp=sharing) -* [Demo video](https://drive.google.com/file/d/1-UvOk0qb3nQQQd2SczW6uWFRIMpBDUyB/view?usp=sharing) -* [Demo script](./fendermint-demo.sh) - -This demo was preformed with [Tendermint Core v0.37.0-rc2](https://github.com/tendermint/tendermint/blob/v0.37.0-rc2/docs/introduction/install.md) (with `git checkout v0.37.0-rc2`), before we switched to CometBFT, so we ran `tendermint` commands, not `cometbft`. diff --git a/docs/fendermint/demos/milestone-1/fendermint-demo.sh b/docs/fendermint/demos/milestone-1/fendermint-demo.sh deleted file mode 100644 index 824430fea6..0000000000 --- a/docs/fendermint/demos/milestone-1/fendermint-demo.sh +++ /dev/null @@ -1,117 +0,0 @@ -#0 -cargo install --locked --path fendermint/app - -#1 - -mkdir test-network - -#2 -fendermint genesis --genesis-file test-network/genesis.json new --network-name test --base-fee 1000 --timestamp 1680101412 - -#3 -cat test-network/genesis.json - -#4 -mkdir test-network/keys -for NAME in alice bob charlie dave; do - fendermint key gen --out-dir test-network/keys --name $NAME; -done - -#5 -ls test-network/keys -cat test-network/keys/alice.pk - -#6 -fendermint \ - genesis --genesis-file test-network/genesis.json \ - add-account --public-key test-network/keys/alice.pk \ - --balance 1000000000000000000 - -#7 -fendermint \ - genesis --genesis-file test-network/genesis.json \ - add-multisig --public-key test-network/keys/bob.pk \ - --public-key test-network/keys/charlie.pk \ - --public-key test-network/keys/dave.pk \ - --threshold 2 --vesting-start 0 --vesting-duration 1000000 \ - --balance 3000000000000000000 - -#8 -cat test-network/genesis.json | jq .accounts - -#9 -fendermint \ - genesis --genesis-file test-network/genesis.json \ - add-validator --public-key test-network/keys/bob.pk --power 1 - -#10 -rm -rf ~/.tendermint -tendermint init - -#11 -fendermint \ - genesis --genesis-file test-network/genesis.json \ - into-tendermint --out ~/.tendermint/config/genesis.json - -#12 -cat ~/.tendermint/config/genesis.json - -#13 -fendermint \ - key into-tendermint --secret-key test-network/keys/bob.sk \ - --out ~/.tendermint/config/priv_validator_key.json - -#14 -cat ~/.tendermint/config/priv_validator_key.json -cat test-network/keys/bob.pk - -#15 -make actor-bundle - -#16 -rm -rf ~/.fendermint/data -mkdir -p ~/.fendermint/data -cp -r ./fendermint/app/config ~/.fendermint/config -cp ./builtin-actors/output/bundle.car ~/.fendermint/bundle.car -cp ./actors/output/custom_actors_bundle.car ~/.fendermint/custom_actors_bundle.car - -#17 -fendermint run - -#18 -tendermint unsafe-reset-all -tendermint start - -#19 -ALICE_ADDR=$(fendermint key address --public-key test-network/keys/alice.pk) -BOB_ADDR=$(fendermint key address --public-key test-network/keys/bob.pk) - -#20 -fendermint rpc query actor-state --address $ALICE_ADDR - -#21 -STATE_CID=$(fendermint rpc query actor-state --address $ALICE_ADDR | jq -r .state.state) -fendermint rpc query ipld --cid $STATE_CID - -#22 -fendermint rpc transfer --secret-key test-network/keys/alice.sk --to $BOB_ADDR --sequence 0 --value 1000 - -#23 -fendermint rpc query actor-state --address $BOB_ADDR | jq .state.balance - -#24 -make ../builtin-actors -fendermint \ - rpc fevm --secret-key test-network/keys/alice.sk --sequence 1 \ - create --contract ../builtin-actors/actors/evm/tests/contracts/SimpleCoin.bin - -#25 -fendermint \ - rpc fevm --secret-key test-network/keys/alice.sk --sequence 2 \ - invoke --contract \ - --method f8b2cb4f --method-args 000000000000000000000000ff00000000000000000000000000000000000064 - -#26 -cargo run -p fendermint_rpc --release \ - --example simplecoin -- \ - --secret-key test-network/keys/alice.sk --verbose diff --git a/docs/fendermint/images/IPC with Tendermint Core.jpg b/docs/fendermint/images/IPC with Tendermint Core.jpg deleted file mode 100644 index 62e28e9f95..0000000000 Binary files a/docs/fendermint/images/IPC with Tendermint Core.jpg and /dev/null differ diff --git a/docs/ipc/diagrams/Makefile b/docs/ipc/diagrams/Makefile deleted file mode 100644 index 5d83b2f6a6..0000000000 --- a/docs/ipc/diagrams/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -PUMLS = $(shell find . -type f -name "*.puml") -PNGS = $(PUMLS:.puml=.png) -PUML_VER=1.2023.2 - -.PHONY: all -all: diagrams - -.PHONY: diagrams -diagrams: $(PNGS) - -plantuml.jar: - wget -O $@ https://github.com/plantuml/plantuml/releases/download/v$(PUML_VER)/plantuml-$(PUML_VER).jar --no-check-certificate --quiet - -%.png: plantuml.jar %.puml - @# Using pipelining to preserve file names. - cat $*.puml | java -jar plantuml.jar -pipe > $*.png diff --git a/docs/ipc/quickstart-calibration.md b/docs/ipc/quickstart-calibration.md index ff18ef9a72..e69de29bb2 100644 --- a/docs/ipc/quickstart-calibration.md +++ b/docs/ipc/quickstart-calibration.md @@ -1 +0,0 @@ -# Moved to [IPC Docs](https://docs.ipc.space/quickstarts/deploy-a-subnet) diff --git a/docs/fendermint/architecture.md b/docs/site/00-overview/architecture-2.md similarity index 98% rename from docs/fendermint/architecture.md rename to docs/site/00-overview/architecture-2.md index 1f20ec3492..296953ad93 100644 --- a/docs/fendermint/architecture.md +++ b/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. diff --git a/docs-gitbook/overview/architecture.md b/docs/site/00-overview/architecture.md similarity index 100% rename from docs-gitbook/overview/architecture.md rename to docs/site/00-overview/architecture.md diff --git a/docs-gitbook/overview/how-ipc-compares.md b/docs/site/00-overview/how-ipc-compares.md similarity index 100% rename from docs-gitbook/overview/how-ipc-compares.md rename to docs/site/00-overview/how-ipc-compares.md diff --git a/docs-gitbook/overview/how-it-works.md b/docs/site/00-overview/how-it-works.md similarity index 100% rename from docs-gitbook/overview/how-it-works.md rename to docs/site/00-overview/how-it-works.md diff --git a/docs-gitbook/overview/use-cases.md b/docs/site/00-overview/use-cases.md similarity index 100% rename from docs-gitbook/overview/use-cases.md rename to docs/site/00-overview/use-cases.md diff --git a/docs/fendermint/activity_rollups.md b/docs/site/01-concepts/activity_rollups.md similarity index 100% rename from docs/fendermint/activity_rollups.md rename to docs/site/01-concepts/activity_rollups.md diff --git a/docs/fendermint/checkpointing.md b/docs/site/01-concepts/checkpointing.md similarity index 56% rename from docs/fendermint/checkpointing.md rename to docs/site/01-concepts/checkpointing.md index 9ae4f2ffa9..08435527eb 100644 --- a/docs/fendermint/checkpointing.md +++ b/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. diff --git a/docs-gitbook/concepts/circulating-supply.md b/docs/site/01-concepts/circulating-supply.md similarity index 100% rename from docs-gitbook/concepts/circulating-supply.md rename to docs/site/01-concepts/circulating-supply.md diff --git a/docs/fendermint/gas_markets.md b/docs/site/01-concepts/gas_markets.md similarity index 100% rename from docs/fendermint/gas_markets.md rename to docs/site/01-concepts/gas_markets.md diff --git a/docs/fendermint/general_cross_messages.md b/docs/site/01-concepts/general_cross_messages.md similarity index 100% rename from docs/fendermint/general_cross_messages.md rename to docs/site/01-concepts/general_cross_messages.md diff --git a/docs/fendermint/observability.md b/docs/site/01-concepts/observability.md similarity index 99% rename from docs/fendermint/observability.md rename to docs/site/01-concepts/observability.md index 679f09dd93..03b2af5afd 100644 --- a/docs/fendermint/observability.md +++ b/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. diff --git a/docs-gitbook/concepts/subnets/parent-child-interactions.md b/docs/site/01-concepts/parent-child-interactions.md similarity index 84% rename from docs-gitbook/concepts/subnets/parent-child-interactions.md rename to docs/site/01-concepts/parent-child-interactions.md index 8d4ef686b7..866e062a38 100644 --- a/docs-gitbook/concepts/subnets/parent-child-interactions.md +++ b/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. diff --git a/docs-gitbook/concepts/subnets/README.md b/docs/site/01-concepts/subnets.md similarity index 85% rename from docs-gitbook/concepts/subnets/README.md rename to docs/site/01-concepts/subnets.md index 594bf34953..3821904f4e 100644 --- a/docs-gitbook/concepts/subnets/README.md +++ b/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. diff --git a/docs/ipc/validator-gater.md b/docs/site/01-concepts/validator-gater.md similarity index 84% rename from docs/ipc/validator-gater.md rename to docs/site/01-concepts/validator-gater.md index 2f8c59c5ed..4deb1c7e04 100644 --- a/docs/ipc/validator-gater.md +++ b/docs/site/01-concepts/validator-gater.md @@ -2,7 +2,13 @@ ## Overview -The Validator Gater feature allows the interception of validator-related actions, such as staking, unstaking, and explicit validator membership adjustments (federated membership), based on user-defined policies. By implementing a custom smart contract that adheres to the `IValidatorGater` interface, developers can enforce custom logic to either permit or deny these actions. +The Validator Gater feature allows the interception of validator membership actions, concretely: staking, unstaking, and explicit membership adjustments (federated membership), based on user-defined policies. + +If configured, a Validator Gater will be called by the IPC framework to enquire whether an action should be accepted or rejected. If not configured, IPC will accept all actions by default. + +Since all validator membership actions for subnet `/r314/A/B` are performed on the parent network `/r314/A`, the Validator Gater would be configured at that level too. + +Setting up a Validator Gater simply involves implementing an EVM smart contract that adheres to the `IValidatorGater` interface, and attaching it to the subnet on creation, or at a later time through an upgrade. This feature is designed to support both federated and collateral-based networks, providing flexibility to manage validator permissions and validator power assignments through an external gating contract. @@ -22,10 +28,10 @@ The core of the Validator Gater feature is the `IValidatorGater` interface. It a interface IValidatorGater { /// This intercepts the power update call. /// @param id The identifier of the subnet. - /// @param validator The address of the validator. + /// @param validator The 0x address of the validator. /// @param prevPower The previous power of the validator. /// @param newPower The new power of the validator. - /// @notice Reverts if the power update is not allowed. + /// @notice Reverts if the power update is not allowed, or succeeds if it's allowed. function interceptPowerDelta(SubnetID memory id, address validator, uint256 prevPower, uint256 newPower) external; } ``` diff --git a/docs/fendermint/localnet.md b/docs/site/02-setup/deploy-a-localnet.md similarity index 100% rename from docs/fendermint/localnet.md rename to docs/site/02-setup/deploy-a-localnet.md diff --git a/docs-gitbook/quickstarts/deploy-a-subnet.md b/docs/site/02-setup/deploy-a-subnet.md similarity index 100% rename from docs-gitbook/quickstarts/deploy-a-subnet.md rename to docs/site/02-setup/deploy-a-subnet.md diff --git a/docs-gitbook/developer-guides/deploy-blockscout.md b/docs/site/02-setup/deploy-blockscout.md similarity index 100% rename from docs-gitbook/developer-guides/deploy-blockscout.md rename to docs/site/02-setup/deploy-blockscout.md diff --git a/docs/fendermint/ipc.md b/docs/site/02-setup/deploy-misc-instructions.md similarity index 95% rename from docs/fendermint/ipc.md rename to docs/site/02-setup/deploy-misc-instructions.md index fa865675ed..3ca0aeed63 100644 --- a/docs/fendermint/ipc.md +++ b/docs/site/02-setup/deploy-misc-instructions.md @@ -2,11 +2,11 @@ This documentation will guide you through the different utils provided in Fendermint for the deployment of Fendermint-based IPC subnets. All node processes are run inside Docker containers in your local environment. -This docs are only focused on the infrastructure deployment, for an end-to-end walk through of spawning IPC subnets refer to the [IPC quickstart](https://github.com/consensus-shipyard/ipc/blob/main/docs/quickstart-calibration.md). +These docs are only focused on the infrastructure deployment, for an end-to-end walk through of spawning IPC subnets refer to the [IPC quickstart](https://github.com/consensus-shipyard/ipc/blob/main/docs/quickstart-calibration.md). ## Prerequisites -* Install the basic requirements for IPC (see [README](../../README.md#Prerequisites)) +* Install the basic requirements for IPC (see [README](../README.md#Prerequisites)) ## Deploy subnet bootstrap diff --git a/docs/ipc/deploying-hierarchy.md b/docs/site/02-setup/deploying-hierarchy.md similarity index 95% rename from docs/ipc/deploying-hierarchy.md rename to docs/site/02-setup/deploying-hierarchy.md index 9696220e4d..94091312a6 100644 --- a/docs/ipc/deploying-hierarchy.md +++ b/docs/site/02-setup/deploying-hierarchy.md @@ -1,10 +1,10 @@ # Deploying a new IPC hierarchy -We recommend that you connect to the existing contracts on CalibrationNet. Nevertheless, this document provides instructions for deploying a new root contract. +We recommend that you connect to the existing contracts on Calibrationnet. Nevertheless, this document provides instructions for deploying a new root contract. ## Install prerequisites -- Install the basic requirements for IPC (see [README](../../README.md#Prerequisites)) +- Install the basic requirements for IPC (see [README](../README.md#Prerequisites)) - Install Node.js [Ubuntu] ([details](https://github.com/nodesource/distributions)) diff --git a/docs/fendermint/running.md b/docs/site/02-setup/full-setup.md similarity index 99% rename from docs/fendermint/running.md rename to docs/site/02-setup/full-setup.md index c3e1a8de47..4d29e699ca 100644 --- a/docs/fendermint/running.md +++ b/docs/site/02-setup/full-setup.md @@ -66,7 +66,7 @@ $ cat test-network/genesis.json ### Create some keys -Next, let's create some cryptographic key pairs we want want to use either for accounts or validators at Genesis. +Next, let's create some cryptographic key pairs we want to use either for accounts or validators at Genesis. ```shell mkdir test-network/keys @@ -85,7 +85,7 @@ $ cat test-network/keys/alice.pk Ak5Juk793ZAg/7Ojj4bzOmIFGpwLhET1vg2ROihUJFkq ``` -If you want to use existing ethereum private key, perform the following: +If you want to use existing Ethereum private key, perform the following: ```shell cargo run -p fendermint_app --release -- key eth-to-fendermint --secret-key --name eth --out-dir test-network/keys @@ -746,6 +746,8 @@ Note that the script figures out the Alice's nonce on its own, so we don't have ## Deploy IPC child subnet +### Create genesis from parent + ### Crate genesis from parent Fendermint includes a command to automatically create the genesis file for an IPC child subnet according to the information for the subnet available in its parent. Here's an example of the generation of a genesis file for a subnet that has already been bootstrapped in the parent. diff --git a/docs/fendermint/tendermint.md b/docs/site/02-setup/tendermint.md similarity index 100% rename from docs/fendermint/tendermint.md rename to docs/site/02-setup/tendermint.md diff --git a/docs/ipc/contracts.md b/docs/site/03-develop/contracts.md similarity index 99% rename from docs/ipc/contracts.md rename to docs/site/03-develop/contracts.md index 8b178acbd7..024f08129f 100644 --- a/docs/ipc/contracts.md +++ b/docs/site/03-develop/contracts.md @@ -37,7 +37,7 @@ With this your Metamask should be successfully connected to your subnet, and you ## Deploying a contract in your subnet -To deploy a smart contract in your subnet the only pre-requirement is to have some funds in the subnet to pay for the gas. To inject funds in your subnet you can follow the steps described [here](./usage.md). +To deploy a smart contract in your subnet the only pre-requirement is to have some funds in the subnet to pay for the gas. To inject funds in your subnet you can follow the steps described [here](usage.md). It is important to note that the IPC agent doesn't understand Ethereum addresses directly, which means that to send funds to an Ethereum address, you will need to send funds to their underlying f4 address. You can use the following command from the IPC agent to get the f4 address for an Ethereum address: diff --git a/docs-gitbook/developer-guides/pluggable-syscall-tutorial.md b/docs/site/03-develop/customizations/pluggable-syscall-tutorial.md similarity index 100% rename from docs-gitbook/developer-guides/pluggable-syscall-tutorial.md rename to docs/site/03-develop/customizations/pluggable-syscall-tutorial.md diff --git a/docs-gitbook/developer-guides/upgrades/README.md b/docs/site/03-develop/upgrades/README.md similarity index 100% rename from docs-gitbook/developer-guides/upgrades/README.md rename to docs/site/03-develop/upgrades/README.md diff --git a/docs-gitbook/developer-guides/upgrades/patch-state.md b/docs/site/03-develop/upgrades/patch-state.md similarity index 100% rename from docs-gitbook/developer-guides/upgrades/patch-state.md rename to docs/site/03-develop/upgrades/patch-state.md diff --git a/docs-gitbook/developer-guides/upgrades/upgrade-wasm-actor.md b/docs/site/03-develop/upgrades/upgrade-wasm-actor.md similarity index 100% rename from docs-gitbook/developer-guides/upgrades/upgrade-wasm-actor.md rename to docs/site/03-develop/upgrades/upgrade-wasm-actor.md diff --git a/docs-gitbook/user-guides/performing-transactions-in-a-subnet.md b/docs/site/04-usage/performing-transactions-in-a-subnet.md similarity index 75% rename from docs-gitbook/user-guides/performing-transactions-in-a-subnet.md rename to docs/site/04-usage/performing-transactions-in-a-subnet.md index 6e28e774a5..7c70b7808c 100644 --- a/docs-gitbook/user-guides/performing-transactions-in-a-subnet.md +++ b/docs/site/04-usage/performing-transactions-in-a-subnet.md @@ -8,65 +8,67 @@ description: >- ### Connecting to a subnet -Assuming the process of launching a custom IPC Subnet with at least one validator node is complete, the custom IPC Subnet is now available for a user (defined here as a wallet on the subnet that is does not necessarily represent a validator) to perform transactions. +Assuming the process of launching a custom IPC Subnet with at least one validator node is complete, the custom IPC Subnet is now available for a user (defined here as a wallet on the subnet that is does not necessarily represent a validator) to perform transactions. -* A user would begin by launching Metamask, and manually adding the custom IPC Network to their Metamask networks list using “Add a network manually.” + + +* A user would begin by launching MetaMask, and manually adding the custom IPC Network to their MetaMask networks list using "Add a network manually." \ ![](https://github.com/consensus-shipyard/docs/blob/main/assets/add_network_manually.png?raw=true) -* Name the network, include the local New RPC URL and relevant ChainID (both of which are provided when you successfully launch the validator node), and name the currency symbol (for Filecoin subnets, tFIL is used). +* Name the network, include the local New RPC URL and relevant ChainID (both of which are provided when you successfully launch the validator node), and name the currency symbol (for Filecoin subnets, tFIL is used). \ ![](https://github.com/consensus-shipyard/docs/blob/main/assets/ipc_local_subnet.png?raw=true) -* Once, the network is added successfully, "Switch to IPC Local Subnet," or whatever you named your subnet. +* Once, the network is added successfully, "Switch to IPC Local Subnet," or whatever you named your subnet. ![](https://github.com/consensus-shipyard/docs/blob/main/assets/network_added.png?raw=true) -* Now, an account on this custom IPC Subnet can be imported to MetaMask. Select “+ Add account or hardware wallet.” +* Now, an account on this custom IPC Subnet can be imported to MetaMask. Select "+ Add account or hardware wallet." \ ![](https://github.com/consensus-shipyard/docs/blob/main/assets/add_account.png?raw=true) -* Select "Import account". +* Select "Import account". ![](https://github.com/consensus-shipyard/docs/blob/main/assets/import_account.png?raw=true) -* Enter the private key for the account, which is generated when establishing the subnet, and select “import.” +* Enter the private key for the account, which is generated when establishing the subnet, and select "import." \ ![](https://github.com/consensus-shipyard/docs/blob/main/assets/import.png?raw=true) -Note: The private key can be retrieved on the command line by the user that deployed the subnet using the following command: +Note: The private key can be retrieved on the command line by the user that deployed the subnet using the following command: ``` ipc % cat ~/.ipc/validator_1.sk ``` -The user now has a wallet address available for transactions in the custom IPC subnet. +The user now has a wallet address available for transactions in the custom IPC subnet. ### Deploying Smart Contracts in a Subnet -Consider the deployment of a simple smart contract that issues ERC20 tokens in the IPC subnet --these tokens will be acquired by a user's IPC subnet MetaMask wallet. The steps for achieving this are as follows: +Consider the deployment of a simple smart contract that issues ERC20 tokens in the IPC subnet --these tokens will be acquired by a user's IPC subnet MetaMask wallet. The steps for achieving this are as follows: -* Open Remix and a simple contract .sol file for issuing ERC20 tokens. +* Open Remix and a simple contract .sol file for issuing ERC20 tokens. ![](https://github.com/consensus-shipyard/docs/blob/main/assets/token.png?raw=true) -* For the environment, connect the IPC Subnet using the “Injected provider - Metamask” custom network. Connect the relevant account on the IPC Subnet. +* For the environment, connect the IPC Subnet using the "Injected provider - MetaMask" custom network. Connect the relevant account on the IPC Subnet. ![](https://github.com/consensus-shipyard/docs/blob/main/assets/injected_provider.png?raw=true) -* Select the relevant account and set the gas limit. +* Select the relevant account and set the gas limit. ![](https://github.com/consensus-shipyard/docs/blob/main/assets/injected_provider.png?raw=true) -* Compile and deploy the contract. Mint new tokens by specifying the address you want the tokens to go to, and the number of tokens you wish to mint. Click “Transact.” +* Compile and deploy the contract. Mint new tokens by specifying the address you want the tokens to go to, and the number of tokens you wish to mint. Click "Transact." ![](https://github.com/consensus-shipyard/docs/blob/main/assets/deploy_run.png?raw=true) -* Copy the token address and import the token to the MetaMask wallet on the custom IPC subnet. +* Copy the token address and import the token to the MetaMask wallet on the custom IPC subnet. ![](https://github.com/consensus-shipyard/docs/blob/main/assets/deploy_metamask.png?raw=true) @@ -74,5 +76,5 @@ Consider the deployment of a simple smart contract that issues ERC20 tokens in t ### Block Explorers -Currently, browsing a custom subnet using a block explorer is not possible. However, a block explorer that can browse custom subnets should be released soon. \ - +Currently, browsing a custom subnet using a block explorer is not possible. However, a block explorer that can browse custom subnets should be released soon. + diff --git a/docs/ipc/developers.md b/docs/site/05-troubleshoot/build-issues.md similarity index 100% rename from docs/ipc/developers.md rename to docs/site/05-troubleshoot/build-issues.md diff --git a/docs-gitbook/reference/faq.md b/docs/site/98-reference/faq.md similarity index 100% rename from docs-gitbook/reference/faq.md rename to docs/site/98-reference/faq.md diff --git a/docs/ipc/usage.md b/docs/site/98-reference/ipc-cli-usage-2.md similarity index 99% rename from docs/ipc/usage.md rename to docs/site/98-reference/ipc-cli-usage-2.md index 556f2b9319..0cbb239018 100644 --- a/docs/ipc/usage.md +++ b/docs/site/98-reference/ipc-cli-usage-2.md @@ -18,7 +18,7 @@ The `ipc-cli` has internally an EVM wallet that it uses to sign transactions and "0x406a7a1d002b71ece175cc7e067620ae5b58e9ec" ``` -* Exporting a key stored in the IPC cli keystore. +* Exporting a key stored in the IPC cli keystore ```bash ./bin/ipc-cli wallet export --wallet-type evm --address > diff --git a/docs-gitbook/reference/ipc-cli-usage.md b/docs/site/98-reference/ipc-cli-usage.md similarity index 100% rename from docs-gitbook/reference/ipc-cli-usage.md rename to docs/site/98-reference/ipc-cli-usage.md diff --git a/docs-gitbook/reference/networks.md b/docs/site/98-reference/networks.md similarity index 100% rename from docs-gitbook/reference/networks.md rename to docs/site/98-reference/networks.md diff --git a/docs-gitbook/reference/troubleshooting.md b/docs/site/98-reference/troubleshooting.md similarity index 100% rename from docs-gitbook/reference/troubleshooting.md rename to docs/site/98-reference/troubleshooting.md diff --git a/docs/site/99-specs b/docs/site/99-specs new file mode 120000 index 0000000000..88a1d60162 --- /dev/null +++ b/docs/site/99-specs @@ -0,0 +1 @@ +../specs/ \ No newline at end of file diff --git a/docs-gitbook/README.md b/docs/site/README.md similarity index 100% rename from docs-gitbook/README.md rename to docs/site/README.md diff --git a/docs/site/SUMMARY.md b/docs/site/SUMMARY.md new file mode 100644 index 0000000000..98e9fd07e7 --- /dev/null +++ b/docs/site/SUMMARY.md @@ -0,0 +1,51 @@ +# Table of contents + +## Learn + +- Overview + - [Introduction](README.md) + - [How IPC works](overview/how-it-works.md) + - [Use cases](overview/use-cases.md) + - [How IPC compares](overview/how-ipc-compares.md) + - [Architecture](overview/architecture.md) + +- Concepts + - [Subnets](concepts/subnets/README.md) + - [Parent-child interactions](01-concepts/parent-child-interactions.md) + - [Circulating supply](concepts/circulating-supply.md) + +## Setting up + +- [Deploy a subnet](02-setup/deploy-a-subnet.md) +- [Deploying an explorer](02-setup/deploy-blockscout.md) + +## Develop + +- [Customizing a subnet](03-develop/customizations/pluggable-syscall-tutorial.md) +- [Upgrading a subnet](03-develop/upgrades/README.md) + - [Example: Patching actor state](03-develop/upgrades/patch-state.md) + - [Example: Upgrading Wasm actor](03-develop/upgrades/upgrade-wasm-actor.md) + +## Usage guides + +- [Performing transactions in a subnet](04-usage/performing-transactions-in-a-subnet.md) + +## Troubleshoot + +- [Build issues](05-troubleshoot/build-issues.md) + +## Specifications + +- [Addressing](../specs/addressing.md) +- [CometBFT](../specs/cometbft.md) +- [IPLD Resolver](../specs/ipld-resolver.md) +- [Materializer](../specs/materializer.md) +- [Top-down Finality](../specs/topdown.md) +- [Bottom Up Checkpoint](../specs/bottom-up-interaction.md) + +## Reference + +- [Networks](98-reference/networks.md) +- [IPC CLI](98-reference/ipc-cli-usage.md) +- [Troubleshooting](98-reference/troubleshooting.md) +- [FAQ](98-reference/faq.md) diff --git a/docs/ipc/img/metamask_add.png b/docs/site/_img/metamask_add.png similarity index 100% rename from docs/ipc/img/metamask_add.png rename to docs/site/_img/metamask_add.png diff --git a/docs/ipc/img/metamask_network.png b/docs/site/_img/metamask_network.png similarity index 100% rename from docs/ipc/img/metamask_network.png rename to docs/site/_img/metamask_network.png diff --git a/docs/ipc/img/metamask_rpc.png b/docs/site/_img/metamask_rpc.png similarity index 100% rename from docs/ipc/img/metamask_rpc.png rename to docs/site/_img/metamask_rpc.png diff --git a/specs/addressing.md b/docs/specs/addressing.md similarity index 100% rename from specs/addressing.md rename to docs/specs/addressing.md diff --git a/specs/bottom-up-interaction.md b/docs/specs/bottom-up-interaction.md similarity index 100% rename from specs/bottom-up-interaction.md rename to docs/specs/bottom-up-interaction.md diff --git a/specs/cometbft.md b/docs/specs/cometbft.md similarity index 100% rename from specs/cometbft.md rename to docs/specs/cometbft.md diff --git a/specs/customizability.md b/docs/specs/customizability.md similarity index 100% rename from specs/customizability.md rename to docs/specs/customizability.md diff --git a/specs/drafts/contract-redesign.md b/docs/specs/drafts/contract-redesign.md similarity index 100% rename from specs/drafts/contract-redesign.md rename to docs/specs/drafts/contract-redesign.md diff --git a/specs/drafts/genesis-v2.md b/docs/specs/drafts/genesis-v2.md similarity index 100% rename from specs/drafts/genesis-v2.md rename to docs/specs/drafts/genesis-v2.md diff --git a/specs/drafts/observability.md b/docs/specs/drafts/observability.md similarity index 100% rename from specs/drafts/observability.md rename to docs/specs/drafts/observability.md diff --git a/specs/ethapi.md b/docs/specs/ethapi.md similarity index 100% rename from specs/ethapi.md rename to docs/specs/ethapi.md diff --git a/specs/executions.md b/docs/specs/executions.md similarity index 100% rename from specs/executions.md rename to docs/specs/executions.md diff --git a/specs/ipld-resolver.md b/docs/specs/ipld-resolver.md similarity index 100% rename from specs/ipld-resolver.md rename to docs/specs/ipld-resolver.md diff --git a/specs/materializer.md b/docs/specs/materializer.md similarity index 100% rename from specs/materializer.md rename to docs/specs/materializer.md diff --git a/specs/snapshots.md b/docs/specs/snapshots.md similarity index 100% rename from specs/snapshots.md rename to docs/specs/snapshots.md diff --git a/specs/subnet-validator-membership.md b/docs/specs/subnet-validator-membership.md similarity index 100% rename from specs/subnet-validator-membership.md rename to docs/specs/subnet-validator-membership.md diff --git a/specs/supply-sources.md b/docs/specs/supply-sources.md similarity index 100% rename from specs/supply-sources.md rename to docs/specs/supply-sources.md diff --git a/specs/topdown.md b/docs/specs/topdown.md similarity index 100% rename from specs/topdown.md rename to docs/specs/topdown.md diff --git a/specs/upgrades.md b/docs/specs/upgrades.md similarity index 100% rename from specs/upgrades.md rename to docs/specs/upgrades.md diff --git a/fendermint/README.md b/fendermint/README.md index 7bfe121a7a..37616116e2 100644 --- a/fendermint/README.md +++ b/fendermint/README.md @@ -8,15 +8,15 @@ Fendermint is an effort to implement [IPC with Tendermint Core](https://docs.goo ## Quick Start -- [Local testnets](../docs/fendermint/localnet.md) +- [Local testnets](../docs/01-setup/localnet.md) ## Docs -Please have a look in the [docs](../docs/fendermint/README.md) to see an overview of the project, how to run the components, and previous demos. +Please have a look in the [docs](../docs/site/README.md) to see an overview of the project, how to run the components, and previous demos. ## IPC -Fendermint is built with support for [IPC](https://github.com/consensus-shipyard/ipc) by design. If you are looking to deploy the infrastructure Fendermint-based IPC subnet, refer to the [IPC main repo](https://github.com/consensus-shipyard/ipc), or have a look at the [IPC infrastructure docs](../docs/fendermint/ipc.md). +Fendermint is built with support for [IPC](https://github.com/consensus-shipyard/ipc) by design. If you are looking to deploy the infrastructure Fendermint-based IPC subnet, refer to the [IPC main repo](https://github.com/consensus-shipyard/ipc), or have a look at the [IPC infrastructure docs](../docs/guides/ipc.md). ## Testing