From 3c239260317628eb58acf2b74b01b3a3dc262f84 Mon Sep 17 00:00:00 2001 From: cryptoAtwill Date: Tue, 7 May 2024 21:41:04 +0800 Subject: [PATCH 1/5] add subnet lifecycle --- spec/subnets-lifecycle.md | 68 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 spec/subnets-lifecycle.md diff --git a/spec/subnets-lifecycle.md b/spec/subnets-lifecycle.md new file mode 100644 index 000000000..e363b5e83 --- /dev/null +++ b/spec/subnets-lifecycle.md @@ -0,0 +1,68 @@ +# Subnet Lifecycle +A subnet is a new subsystem that a user can spawn from a parent subnet in a permissionless and on-demand way, depending on scalability requirements. Subnets have separate consensus algorithms and cryptoeconomic rules from their parent subnet. Subnets are firewalled from the parent network. + +Subnets begin with a chosen "rootnet". In case of L2 subnets, “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. + +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 deployed and ends when the subnet is closed. + +Before a subnet is created, one must specify the validator power allocation mode, which is called the `PermissionMode`. There are three kinds of permission mode at the moment: + +- `Collateral`: This means the power of the validator comes from the collateral staked. New validators can `join` the subnet, also `stake` more collateral, `unstake` collateral and finally `leave` the subnet +- `Federated`: The power of the validator is set by the owner of the subnet +- `Static`: The power of the validator is set when the subnet is created. This mode is used mainly for debugging and testing + +At the time of subnet creation, a minimum validator count requirement is set by the subnet creator. If the subnet’s permission mode is collateral, the creator could also set the minimum collateral requirement for the subnet to be bootstrapped. A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. + +Before the minimal requirements are met, the subnet is in a `preBootstrap` state, once those conditions are met, the subnet is in a `postBootstap` state. Any operations performed on the subnet in `preBootstrap` state is recorded in the subnet `genesis`. + +For normal users, they can perform: + +- Prefund: Provide genesis balance to the subnet +- Fund: Send fund from the parent to an address in the child subnet. The parent will track the total circulating supply of the subnet. +- Release: Send fund from the child subnet to an address in the parent subnet +- Cross Message Call: Call another contract in another subnet + +For validators in `Collateral` permission mode, they can: + +- Join: Put some stake into the subnet and becomes a validator +- State: Add more stake into the subnet +- Unstake: WIthdraw stake from the subnet +- Leave: WIthdraw all stake from the subnet + +For detailed explanation on how `Collateral` and `FederatedPower` affect the validator’s voting power, see `SubnetValidation`. + +### Deployment + +For ipc powered subnet, it’s deployed through `SubnetRegistry`. This contract should be deployed together with the gateway. One can simply call [newSubnetActor](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/subnetregistry/RegisterSubnetFacet.sol#L22) method to deploy a new subnet under the gateway contract. But do note that this method requires permission. The creator of this registry could limit the access on who can deploy new subnets or there are no restrictions at all, see [line](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/subnetregistry/RegisterSubnetFacet.sol#L95). + +### Genesis + +The genesis state of the subnet is tracked in the [SubnetActorStorage](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/lib/LibSubnetActorStorage.sol#L10) struct of the subnet, any field that starts with `genesis*`. + +For `Collateral` permission mode, validators’ stake can be updated and is directly reflected in the validator’s genesis weight until the subnet is bootstrapped. However, for `Federated` permission mode, the owner must make sure the minimum number of validators are met, see [check](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/lib/LibSubnetActor.sol#L82). + +The child subnet blockchain, i.e. fendermint, can query the parent subnet actor to [obtain](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/fendermint/app/src/cmd/genesis.rs#L33) the genesis information. + +For detailed breakdown on the genesis file, see SubnetConfiguration. + +### Bootstrap + +The subnet is bootstrapped once the minimal validator requirement and, for `Collateral` permission mode, the minimal collateral requirement, are met. + +The `bootstrapped` state of the subnet will become `true` and the `genesis` of the subnet will now be immutable. One need to note that once the subnet is bootstrapped, the `SubnetActor` will [register](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/gateway/GatewayManagerFacet.sol#L33) itself to the corresponding gateway contract. The `SubnetActor` will transfer its fund to the gateway and the gateway will manage the funds for each registered subnet. + +This is the current trust model for IPC. The gateway is transparent, trustworthy and manages the routing/funding for each subnet. + +### **Closing a Subnet** + +The conditions for closing a subnet are as follows: + +- 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 there 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. \ No newline at end of file From 053044a09515b954584689315c4df404188a4aff Mon Sep 17 00:00:00 2001 From: cryptoAtwill <108330426+cryptoAtwill@users.noreply.github.com> Date: Mon, 13 May 2024 14:23:58 +0800 Subject: [PATCH 2/5] Update spec/subnets-lifecycle.md Co-authored-by: folex <0xdxdy@gmail.com> --- spec/subnets-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/subnets-lifecycle.md b/spec/subnets-lifecycle.md index e363b5e83..6f3a4b9f4 100644 --- a/spec/subnets-lifecycle.md +++ b/spec/subnets-lifecycle.md @@ -11,7 +11,7 @@ Subnets within a single hierarchy tree have native communication protocols and a The lifecycle of a subnet begins when it’s deployed and ends when the subnet is closed. -Before a subnet is created, one must specify the validator power allocation mode, which is called the `PermissionMode`. There are three kinds of permission mode at the moment: +Before a subnet is created, the subnet creator must specify the validator power allocation mode, which is called the `PermissionMode`. There are three kinds of permission mode at the moment: - `Collateral`: This means the power of the validator comes from the collateral staked. New validators can `join` the subnet, also `stake` more collateral, `unstake` collateral and finally `leave` the subnet - `Federated`: The power of the validator is set by the owner of the subnet From bebe27c85567e4d29c7da46882b4da5853ed8a2b Mon Sep 17 00:00:00 2001 From: cryptoAtwill <108330426+cryptoAtwill@users.noreply.github.com> Date: Mon, 13 May 2024 14:24:09 +0800 Subject: [PATCH 3/5] Update spec/subnets-lifecycle.md Co-authored-by: folex <0xdxdy@gmail.com> --- spec/subnets-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/subnets-lifecycle.md b/spec/subnets-lifecycle.md index 6f3a4b9f4..cbd7d8a02 100644 --- a/spec/subnets-lifecycle.md +++ b/spec/subnets-lifecycle.md @@ -17,7 +17,7 @@ Before a subnet is created, the subnet creator must specify the validator power - `Federated`: The power of the validator is set by the owner of the subnet - `Static`: The power of the validator is set when the subnet is created. This mode is used mainly for debugging and testing -At the time of subnet creation, a minimum validator count requirement is set by the subnet creator. If the subnet’s permission mode is collateral, the creator could also set the minimum collateral requirement for the subnet to be bootstrapped. A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. +At the time of subnet creation, a minimum validator count requirement is set by the subnet creator. If the subnet’s permission mode is `Collateral`, the creator could also set the minimum collateral requirement for the subnet to be bootstrapped. A standard fee for the transaction on the parent network will be paid for the transaction that establishes the subnet. Before the minimal requirements are met, the subnet is in a `preBootstrap` state, once those conditions are met, the subnet is in a `postBootstap` state. Any operations performed on the subnet in `preBootstrap` state is recorded in the subnet `genesis`. From 8e2a5c9cd78d42e1b5ea0699921d9abcd2bec3af Mon Sep 17 00:00:00 2001 From: cryptoAtwill <108330426+cryptoAtwill@users.noreply.github.com> Date: Mon, 13 May 2024 14:42:41 +0800 Subject: [PATCH 4/5] Update spec/subnets-lifecycle.md Co-authored-by: folex <0xdxdy@gmail.com> --- spec/subnets-lifecycle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/subnets-lifecycle.md b/spec/subnets-lifecycle.md index cbd7d8a02..812c96149 100644 --- a/spec/subnets-lifecycle.md +++ b/spec/subnets-lifecycle.md @@ -32,8 +32,8 @@ For validators in `Collateral` permission mode, they can: - Join: Put some stake into the subnet and becomes a validator - State: Add more stake into the subnet -- Unstake: WIthdraw stake from the subnet -- Leave: WIthdraw all stake from the subnet +- Unstake: Withdraw stake from the subnet +- Leave: Withdraw all stake from the subnet For detailed explanation on how `Collateral` and `FederatedPower` affect the validator’s voting power, see `SubnetValidation`. From 8ba48faaf1b004254f782c1405962e2ad1ed1754 Mon Sep 17 00:00:00 2001 From: cryptoAtwill <108330426+cryptoAtwill@users.noreply.github.com> Date: Mon, 13 May 2024 20:03:55 +0800 Subject: [PATCH 5/5] Update subnets-lifecycle.md --- spec/subnets-lifecycle.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/spec/subnets-lifecycle.md b/spec/subnets-lifecycle.md index 812c96149..5223b1c36 100644 --- a/spec/subnets-lifecycle.md +++ b/spec/subnets-lifecycle.md @@ -11,7 +11,7 @@ Subnets within a single hierarchy tree have native communication protocols and a The lifecycle of a subnet begins when it’s deployed and ends when the subnet is closed. -Before a subnet is created, the subnet creator must specify the validator power allocation mode, which is called the `PermissionMode`. There are three kinds of permission mode at the moment: +Before a subnet actor is deployed, the subnet creator must specify the validator power allocation mode, which is called the `PermissionMode`. There are three kinds of permission mode at the moment: - `Collateral`: This means the power of the validator comes from the collateral staked. New validators can `join` the subnet, also `stake` more collateral, `unstake` collateral and finally `leave` the subnet - `Federated`: The power of the validator is set by the owner of the subnet @@ -21,10 +21,10 @@ At the time of subnet creation, a minimum validator count requirement is set by Before the minimal requirements are met, the subnet is in a `preBootstrap` state, once those conditions are met, the subnet is in a `postBootstap` state. Any operations performed on the subnet in `preBootstrap` state is recorded in the subnet `genesis`. -For normal users, they can perform: +Any address can perform: -- Prefund: Provide genesis balance to the subnet -- Fund: Send fund from the parent to an address in the child subnet. The parent will track the total circulating supply of the subnet. +- Prefund: Provide genesis balance to the subnet, i.e. providing some initial balance to certain reward account in the child subnet. +- Fund: Send fund from the parent to an address in the child subnet. The parent will track the total circulating supply of the subnet. For how the mapping of tokens between the parent and the child works, please refer to the `SupplySource` section. - Release: Send fund from the child subnet to an address in the parent subnet - Cross Message Call: Call another contract in another subnet @@ -41,6 +41,11 @@ For detailed explanation on how `Collateral` and `FederatedPower` affect the val For ipc powered subnet, it’s deployed through `SubnetRegistry`. This contract should be deployed together with the gateway. One can simply call [newSubnetActor](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/subnetregistry/RegisterSubnetFacet.sol#L22) method to deploy a new subnet under the gateway contract. But do note that this method requires permission. The creator of this registry could limit the access on who can deploy new subnets or there are no restrictions at all, see [line](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/subnetregistry/RegisterSubnetFacet.sol#L95). +The states of a deployed subnet consists of: +- Prebootstrap: The minimal validator requirements are yet to be met +- Bootstrapped: The validator requirements are met +- Killed: All validators have left the subnet and no more circulation, `kill` method is called + ### Genesis The genesis state of the subnet is tracked in the [SubnetActorStorage](https://github.com/consensus-shipyard/ipc/blob/7af25c4c860f5ab828e8177927a0f8b6b7a7cc74/contracts/src/lib/LibSubnetActorStorage.sol#L10) struct of the subnet, any field that starts with `genesis*`. @@ -65,4 +70,4 @@ The conditions for closing a subnet are as follows: - 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 there 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. \ No newline at end of file +- 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.