docs(specs): Subnet Lifecycle #895

cryptoAtwill · 2024-05-07T13:41:30Z

Adding the doc for subnet lifecycle.

folex · 2024-05-09T08:40:33Z

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.


A subnet is a new subsystem that a user can spawn from a parent subnet

Recursive definition. I guess this should mention that subnet is a chain of its own, and one can think of a subnet as an LN+1 connected to a LN chain, eg L2 is connected to L1.

Subnets are firewalled from the parent network.

Is "parent network" different from "parent subnet"?

they are the same

Then I think it's best to name them the same to avoid confusion. As this is the spec, it should be very dry and precise, IMO.

folex · 2024-05-09T08:41:30Z

spec/subnets-lifecycle.md

+# 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.


Subnets begin with a chosen "rootnet".

Parent subnet, parent network, rootnet – are these all the same concept? Maybe it makes sense to have a Glossary? eg take a look at https://fluence.dev/docs/build/glossary.

Good point, I can raise this to the team. But here rootnet simply means the parent of all, like the starting subnet, which for the sake of recurrence.

folex · 2024-05-09T08:44:19Z

spec/subnets-lifecycle.md

+
+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.


have native communication protocols

Between which parties? I guess it's between all the subnets (parents, children, etc), I guess makes sense to point out what exactly these native communication protocols unite.

My understanding is the communication does not really have to be specified in the spec, up to the implementation.

folex · 2024-05-09T08:44:43Z

spec/subnets-lifecycle.md

+
+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:


Is "created" the same as "deployed", or these are different phases of the lifecycle?

yeah, good point. What do you mean by deploy? But what the above means is the subnet actor is deployed.

spec/subnets-lifecycle.md

folex · 2024-05-09T08:48:17Z

spec/subnets-lifecycle.md

+
+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:


What is a normal user? Is it a Validator that's not an Owner, or just a 3rd party who has a wallet in the subnet?

3rd party who has a wallet in the subnet. I will rephrase this a little.

folex · 2024-05-09T08:49:12Z

spec/subnets-lifecycle.md

+
+For normal users, they can perform:
+
+- Prefund: Provide genesis balance to the subnet


Would be nice to elaborate a bit on who usually does that and why

folex · 2024-05-09T08:50:40Z

spec/subnets-lifecycle.md

+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.


So it's about moving some of the child subnet's native token from parent to child? Maybe it makes sense to mention that Parent and Child might have different notion of "fund", ie different native token?

That should be covered in the SupplySource section. I will add a link to that.

spec/subnets-lifecycle.md

folex · 2024-05-09T08:52:58Z

spec/subnets-lifecycle.md

+
+### 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).


For ipc powered subnet

Are there any other options? If yes, maybe mention that subnet abstracts away the implementation?

currently we only have IPC implementation, but as long as the interface is aligned, it should be ok

folex · 2024-05-09T09:19:20Z

spec/subnets-lifecycle.md

+
+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.


So subnet has "blockchain" and something else? Maybe makes sense to elaborate on what constitutes a Subnet then

I mean just the subnet actor and the blockchain.

folex · 2024-05-09T09:35:33Z

spec/subnets-lifecycle.md

+
+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.


The bootstrapped state of the subnet will become true

So there's a preBootstrap state, postBootstrap state and bootstrapped: true? That's 3 or 2 states? Also I guess there should be a Closed state or something like that.

Maybe it makes sense to start this article by enumerating possible state and some transition arrows? i.e. ASCII or Mermaid state diagram.

folex · 2024-05-09T10:09:37Z

spec/subnets-lifecycle.md

+
+### **Closing a Subnet**
+
+The conditions for closing a subnet are as follows:


Who can initiate a subnet closure?

Currently there is no permission required if all validators have left the subnet

folex · 2024-05-09T10:10:00Z

spec/subnets-lifecycle.md

+
+- 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.


Is it related to closing a subnet, or just a general consideration?

general consideration

Co-authored-by: folex <0xdxdy@gmail.com>

cryptoAtwill · 2024-05-13T12:06:10Z

@folex I have updated the doc according to you feedback. Some parts I left as it is and explained as replies to the PR, please help take a look.

add subnet lifecycle

3c23926

cryptoAtwill requested review from raulk, snissn, aakoshh and maciejwitowski May 7, 2024 13:42

maciejwitowski added the specs label May 7, 2024

maciejwitowski changed the title ~~Add subnet lifecycle~~ Spec: Subnet Lifecycle May 7, 2024

folex reviewed May 9, 2024

View reviewed changes

spec/subnets-lifecycle.md Outdated Show resolved Hide resolved

folex reviewed May 9, 2024

View reviewed changes

spec/subnets-lifecycle.md Outdated Show resolved Hide resolved

folex reviewed May 9, 2024

View reviewed changes

spec/subnets-lifecycle.md Outdated Show resolved Hide resolved

folex reviewed May 9, 2024

View reviewed changes

cryptoAtwill and others added 4 commits May 13, 2024 14:23

Update spec/subnets-lifecycle.md

053044a

Co-authored-by: folex <0xdxdy@gmail.com>

Update spec/subnets-lifecycle.md

bebe27c

Co-authored-by: folex <0xdxdy@gmail.com>

Update spec/subnets-lifecycle.md

8e2a5c9

Co-authored-by: folex <0xdxdy@gmail.com>

Update subnets-lifecycle.md

8ba48fa

cryptoAtwill requested a review from folex May 13, 2024 12:04

Merge branch 'main' into spec-subnet-lifecycle

fd634cf

raulk changed the title ~~Spec: Subnet Lifecycle~~ docs(specs): Subnet Lifecycle Jul 22, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(specs): Subnet Lifecycle #895

docs(specs): Subnet Lifecycle #895

cryptoAtwill commented May 7, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 29, 2024

folex May 9, 2024 •

edited

Loading

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

folex May 9, 2024

cryptoAtwill May 13, 2024

cryptoAtwill commented May 13, 2024

		@@ -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.


		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.


		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 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:


		For normal users, they can perform:

		- Prefund: Provide genesis balance to the subnet


		### 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).


		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.


		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.


		### Closing a Subnet

		The conditions for closing a subnet are as follows:

docs(specs): Subnet Lifecycle #895

Are you sure you want to change the base?

docs(specs): Subnet Lifecycle #895

Conversation

cryptoAtwill commented May 7, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

folex May 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cryptoAtwill commented May 13, 2024

folex May 9, 2024 •

edited

Loading