docs: update docs to capture Permissionless ICS (#2289)

init commit

Author: insumity

Diff for: docs/docs/adrs/adr-019-permissionless-ics.md

@@ -13,7 +13,7 @@ title: Permissionless ICS
 Accepted
 
 ## Context
-Currently, a consumer chain can join _Interchain Security_ (ICS) only through a [governance proposal](../features/proposals.md).
+Currently, a consumer chain can join _Interchain Security_ (ICS) only through a governance proposal.
 A governance proposal was needed before the introduction of [Partial Set Security](../features/partial-set-security.md) (PSS)
 because validators were required to validate a consumer chain. However, after the introduction of PSS, a consumer chain can
 be either _Top N_ or _Opt In_. If a chain is an Opt In chain, then no validator is required to validate this chain unless they choose to.
@@ -171,7 +171,7 @@ message MsgCreateConsumer {
 }
 ```
 
-Note that `metadata` is a required field, while the `initialization_parameterrs` and `power_shaping_parameters` are optional and can later be set using `MsgUpdateConsumer`.
+Note that `metadata` is a required field, while the `initialization_parameters` and `power_shaping_parameters` are optional and can later be set using `MsgUpdateConsumer`.
 
 `metadata` is of the following type:
 ```protobuf
@@ -341,7 +341,7 @@ The figures below depict some examples of some of the phases a consumer chain re
 
 
 ### Additional Modifications
-We need to perform multiple migrations. All state needs to be reindex based on a `consumerId` instead of the `chainId`.
+We need to perform multiple migrations. All state needs to be reindexed based on a `consumerId` instead of the `chainId`.
 Because we only have two consumer chains (i.e., Neutron and Stride) at the moment, this is not going to be an expensive migration even if we have some live
 consumer chains that are being voted upon. Similarly, all the messages, queries, etc. would need to be changed to operate on a `consumerId` instead of a `chainId`.
 

Diff for: docs/docs/consumer-development/changeover-procedure.md

@@ -14,8 +14,8 @@ The relevant protocol specifications are available below:
 
 Standalone to consumer changeover procedure can roughly be separated into 4 parts:
 
-### 1. ConsumerAddition proposal submitted to the `provider` chain
-The proposal is equivalent to the "normal" ConsumerAddition proposal submitted by new consumer chains.
+### 1. `MsgCreateConsumer` submitted to the `provider` chain
+The `MsgCreateConsumer` is equivalent to the "normal" `MsgCreateConsumer` message submitted by new consumer chains.
 
 However, here are the most important notes and differences between a new consumer chain and a standalone chain performing a changeover:
 
@@ -77,7 +77,7 @@ If the parameter is not set, a new channel will be created.
 The standalone chain creates an upgrade proposal to include the `interchain-security/x/ccv/consumer` module.
 
 :::caution
-The upgrade height in the proposal should correspond to a height that is after the `spawn_time` in the consumer addition proposal submitted to the `provider` chain.
+The upgrade height in the proposal should correspond to a height that is after the `spawn_time` in the `MsgCreateConsumer` submitted to the `provider` chain.
 :::
 
 Otherwise, the upgrade is indistinguishable from a regular on-chain upgrade proposal.
@@ -137,9 +137,9 @@ This should include (at minimum):
 
 Example of such a repository can be found [here](https://github.com/hyphacoop/ics-testnets/tree/main/game-of-chains-2022/sputnik).
 
-## 3. Submit a ConsumerChainAddition Governance Proposal to the provider
+## 3. Submit a `MsgCreateConsumer` to the provider
 
-Before you submit a `ConsumerChainAddition` proposal, please provide a `spawn_time` that is **before** the `upgrade_height` of the upgrade that will introduce the `ccv module` to your chain.
+Before you submit a `MsgCreateConsumer` message, please provide a `spawn_time` that is **before** the `upgrade_height` of the upgrade that will introduce the `ccv module` to your chain.
 :::danger
 If the `spawn_time` happens after your `upgrade_height` the provider will not be able to communicate the new validator set to be used after the changeover.
 :::
@@ -150,22 +150,11 @@ Additionally, reach out to the community via the [forum](https://forum.cosmos.ne
 - [ ] determine consumer chain parameters to be put in the proposal
 - [ ] take note to include a link to your onboarding repository
 
-Example of a consumer chain addition proposal (compare with the [ConsumerAdditionProposal](./onboarding.md#3-submit-a-governance-proposal) in the ICS Provider Proposals section for chains that *launch* as consumers):
+Example of initialization parameters  (compare with the [those](./onboarding.md#3-submit-msgcreateconsumer-and-msgupdateconsumer-messages) for chains that *launch* as consumers):
 
 ```js
-// ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain or add a standalone chain.
-// If it passes, then a subset (i.e., depends on `top_N` and on the power shaping parameters) of validators on the provider chain are expected
-// to validate the consumer chain at spawn time. It is recommended that spawn time occurs after the proposal end time and that it is 
-// scheduled to happen before the standalone chain upgrade that sill introduce the ccv module.
+// ConsumerInitializationParameters provided in MsgCreateConsumer or MsgUpdateConsumer
 {
-    // Title of the proposal
-    "title": "Changeover Standalone chain",
-    // Description of the proposal
-    // format the text as a .md file and include the file in your onboarding repository
-    "description": ".md description of your chain and all other relevant information",
-    // Proposed chain-id of the new consumer chain.
-    // Must be unique from all other consumer chain ids of the executing provider chain.
-    "chain_id": "standalone-1",
     // Initial height of new consumer chain.
     "initial_height" : {
         // must correspond to current revision number of standalone chain
@@ -175,7 +164,7 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio
         // must correspond to a height that is at least 1 block after the upgrade
         // that will add the `consumer` module to the standalone chain
         // e.g. "upgrade_height": 100 => "revision_height": 101
-        "revision_number": 1,
+        "revision_height": 101,
     },
     // Hash of the consumer chain genesis state without the consumer CCV module genesis params.
     // => not relevant for changeover procedure
@@ -212,30 +201,11 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio
     // it is most relevant for chains performing a standalone to consumer changeover
     // in order to maintain the existing ibc transfer channel
     "distribution_transmission_channel": "channel-123"  // NOTE: use existing transfer channel if available
-    // Corresponds to the percentage of validators that have to validate the chain under the Top N case.
-    // For example, 53 corresponds to a Top 53% chain, meaning that the top 53% provider validators by voting power
-    // have to validate the proposed consumer chain. top_N can either be 0 or any value in [50, 100].
-    // A chain can join with top_N == 0 as an Opt In chain, or with top_N ∈ [50, 100] as a Top N chain.
-    "top_N": 95,
-    // Corresponds to the maximum power (percentage-wise) a validator can have on the consumer chain. For instance, if
-    // `validators_power_cap` is set to 32, it means that no validator can have more than 32% of the voting power on the
-    // consumer chain. Note that this might not be feasible. For example, think of a consumer chain with only
-    // 5 validators and with `validators_power_cap` set to 10%. In such a scenario, at least one validator would need
-    // to have more than 20% of the total voting power. Therefore, `validators_power_cap` operates on a best-effort basis.
-    "validators_power_cap": 0,
-    // Corresponds to the maximum number of validators that can validate a consumer chain.
-    // Only applicable to Opt In chains. Setting `validator_set_cap` on a Top N chain is a no-op.
-    "validator_set_cap": 0,
-    // Corresponds to a list of provider consensus addresses of validators that are the ONLY ones that can validate
-    // the consumer chain.
-    "allowlist": [],
-    // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain.
-    "denylist": []
 }
 ```
 
 :::info
-As seen in the `ConsumerAdditionProposal` example above, the changeover procedure can be used together with [Partial Set Security](../adrs/adr-015-partial-set-security.md).
+The changeover procedure can be used together with [Partial Set Security](../adrs/adr-015-partial-set-security.md).
 This means, that a standalone chain can choose to only be validated by some of the validators of the provider chain by setting `top_N` appropriately, or by
 additionally setting a validators-power cap, validator-set cap, etc. by using the [power-shaping parameters](../features/power-shaping.md).
 :::
@@ -244,7 +214,7 @@ additionally setting a validators-power cap, validator-set cap, etc. by using th
 
 This proposal should add the ccv `consumer` module to your chain.
 
-- [ ] proposal `upgrade_height` must happen after `spawn_time` in the `ConsumerAdditionProposal`
+- [ ] proposal `upgrade_height` must happen after `spawn_time` in the `MsgCreateConsumer`
 - [ ] advise validators about the exact procedure for your chain and point them to your onboarding repository
 
 

Diff for: docs/docs/consumer-development/offboarding.md

@@ -4,21 +4,11 @@ title: Offboarding Checklist
 ---
 # Consumer Offboarding
 
-To offboard a consumer chain simply submit a `ConsumerRemovalProposal` governance proposal listing a `stop_time`. After stop time passes, the provider chain will remove the chain from the ICS protocol (it will stop sending validator set updates).
+To offboard a consumer chain, the owner of the chain has to submit a `MsgRemoveConsumer` message with the chain's `consumerId`.
+If the chain is a Top N chain, the `MsgRemoveConsumer` has to be submitted through a governance proposal.
+Otherwise, the message can be submitted simply by the owner of the consumer chain.
 
-```js
-// ConsumerRemovalProposal is a governance proposal on the provider chain to remove (and stop) a consumer chain.
-// If it passes, all the consumer chain's state is removed from the provider chain. The outstanding unbonding
-// operation funds are released.
-{
-    // the title of the proposal
-    "title": "This was a great chain",
-    "description": "Here is a .md formatted string specifying removal details",
-    // the chain-id of the consumer chain to be stopped
-    "chain_id": "consumerchain-1",
-    // the time on the provider chain at which all validators are responsible to stop their consumer chain validator node
-    "stop_time": "2023-03-07T12:40:00.000000Z",
-}
-```
-
-More information will be listed in a future version of this document.
+When the `MsgRemoveConsumer` executes, the provider chain will stop the chain from the ICS protocol (it will stop
+sending validator set updates) and the chain is considered to be in the stopped phase.
+At this phase, validators cannot opt in, change keys, etc. and validators stop receiving rewards.
+After the chain is stopped, and an unbonding period of time passes, part of the state of the chain is deleted and the chain is considered deleted.

Diff for: docs/docs/consumer-development/onboarding.md

@@ -30,36 +30,32 @@ This should include (at minimum):
 
 Example of such a repository can be found [here](https://github.com/hyphacoop/ics-testnets/tree/main/game-of-chains-2022/sputnik).
 
-## 3. Submit a Governance Proposal
+## 3. Submit `MsgCreateConsumer` (and `MsgUpdateConsumer`) messages
 
-Before you submit a `ConsumerChainAddition` proposal, please consider allowing at least a day between your proposal passing and the chain spawn time. This will allow the validators, other node operators and the community to prepare for the chain launch.
-If possible, please set your spawn time so people from different parts of the globe can be available in case of emergencies. Ideally, you should set your spawn time to be between 12:00 UTC and 20:00 UTC so most validator operators are available and ready to respond to any issues.
+Before you start your chain, you need to submit a `MsgCreateConsumer` message that generates and returns back the
+`consumerId` that should be used in any upcoming interactions by the consumer chain or the validators that interact
+with your chain. 
+Additionally, you need to decider whether your chain should be an Opt-In chain or a Top N chain (see [Partial Set Security](../features/partial-set-security.md))
+and act accordingly (see [Permissionless ICS](../features/permissionless.md).
 
-Additionally, reach out to the community via the [forum](https://forum.cosmos.network/) to formalize your intention to become an ICS consumer, gather community support and accept feedback from the community, validators and developers.
+If you create a Top N chain through, please consider allowing at least a day between your proposal passing and the chain spawn time.
+This will allow the validators, other node operators and the community to prepare for the chain launch.
+If possible, please set your spawn time so people from different parts of the globe can be available in case of emergencies.
+Ideally, you should set your spawn time to be between 12:00 UTC and 20:00 UTC so most validator operators are available and ready to respond to any issues.
+
+Additionally, for a Top N chain, reach out to the community via the [forum](https://forum.cosmos.network/) to formalize your intention to become an ICS consumer,
+gather community support and accept feedback from the community, validators and developers.
 
 - [ ] determine your chain's spawn time
-- [ ] determine consumer chain parameters to be put in the proposal
+- [ ] determine consumer chain parameters
 - [ ] take note to include a link to your onboarding repository
 - [ ] describe the purpose and benefits of running your chain
-- [ ] determine whether your chain should be an Opt-In chain or a Top N chain (see [Partial Set Security](../features/partial-set-security.md))
 - [ ] if desired, decide on power-shaping parameters (see [Power Shaping](../features/power-shaping.md))
 
-Example of a consumer chain addition proposal.
-
+Example of initialization parameters:
 ```js
-// ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain.
-// If it passes, if the top_N parameter is not equal to 0, the top N% of validators by voting power on the provider chain are expected to validate the consumer chain at spawn time.
-// Otherwise, only validators that opted in during the proposal period are expected to validate the consumer chain at spawn time.
-// It is recommended that spawn time occurs after the proposal end time.
+// ConsumerInitializationParameters provided in MsgCreateConsumer or MsgUpdateConsumer
 {
-    // Title of the proposal
-    "title": "Add consumer chain",
-    // Description of the proposal
-    // format the text as a .md file and include the file in your onboarding repository
-    "description": ".md description of your chain and all other relevant information",
-    // Proposed chain-id of the new consumer chain.
-    // Must be unique from all other consumer chain ids of the executing provider chain.
-    "chain_id": "newchain-1",
     // Initial height of new consumer chain.
     // For a completely new chain, this will be {0,1}.
     "initial_height" : {
@@ -100,7 +96,14 @@ Example of a consumer chain addition proposal.
 	// Note that transfer_channel_id is the ID of the channel end on the consumer chain.
     // it is most relevant for chains performing a standalone to consumer changeover
     // in order to maintain the existing ibc transfer channel
-    "distribution_transmission_channel": "channel-123",
+    "distribution_transmission_channel": "channel-123"
+}
+```
+
+Example of power-shaping parameters:
+```js
+// PowerShaping parameters provided in MsgCreateConsumer or MsgUpdateConsumer
+{
     // Corresponds to the percentage of validators that have to validate the chain under the Top N case.
     // For example, 53 corresponds to a Top 53% chain, meaning that the top 53% provider validators by voting power
     // have to validate the proposed consumer chain. top_N can either be 0 or any value in [50, 100].

Diff for: docs/docs/features/democracy-modules.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 4
 ---
 
 # Democracy modules

Diff for: docs/docs/features/key-assignment.md

@@ -15,7 +15,7 @@ Note that key assignment is handled only by the provider chain - the consumer ch
 
 ## Rules
 
-- A key can be assigned as soon as the consumer addition proposal is submitted to the provider.
+- A key can be assigned to any active (i.e., in the registered, initialized, or launched phase) chain.
 - Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` (`B!=A`) using `K` on the provider.
 - Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` using `K` on `X`.
 - A new validator on the provider cannot use a consensus key `K` if `K` is already used by any validator on any consumer chain.
@@ -42,35 +42,35 @@ consumerd tendermint show-validator # {"@type":"/cosmos.crypto.ed25519.PubKey","
 Then, make an `assign-consensus-key` transaction on the provider chain in order to inform the provider chain about the consensus key you will be using for a specific consumer chain.
 
 ```bash
-gaiad tx provider assign-consensus-key <consumer-chain-id> '<pubkey>' --from <tx-signer> --home <home_dir> --gas 900000 -b sync -y -o json
+gaiad tx provider assign-consensus-key <consumer-id> '<pubkey>' --from <tx-signer> --home <home_dir> --gas 900000 -b sync -y -o json
 ```
 
-- `consumer-chain-id` is the string identifier of the consumer chain, as assigned on the provider chain
+- `consumer-id` is the string identifier of the consumer chain, as assigned on the provider chain
 - `consumer-pub-key` has the following format `{"@type":"/cosmos.crypto.ed25519.PubKey","key":"<key>"}`
 
 Check that the key was assigned correctly by querying the provider:
 
 ```bash
-gaiad query provider validator-consumer-key <consumer-chain-id> cosmosvalcons1e....3xsj3ayzf4uv6
+gaiad query provider validator-consumer-key <consumer-id> cosmosvalcons1e....3xsj3ayzf4uv6
 ```
 
 You must use a `valcons` address. You can obtain it by querying your node on the provider `gaiad tendermint show-address`
 
 OR
 
 ```bash
-gaiad query provider validator-provider-key <consumer-chain-id> consumervalcons1e....123asdnoaisdao
+gaiad query provider validator-provider-key <consumer-id> consumervalcons1e....123asdnoaisdao
 ```
 
 You must use a `valcons` address. You can obtain it by querying your node on the consumer `consumerd tendermint show-address`
 
 OR
 
 ```bash
-gaiad query provider all-pairs-valconsensus-address <consumer-chain-id>
+gaiad query provider all-pairs-valconsensus-address <consumer-id>
 ```
 
-You just need to use the `chainId` of consumer to query all pairs valconsensus address with `consumer-pub-key` for each of pair
+You just need to use the `consumerId` of consumer to query all pairs valconsensus address with `consumer-pub-key` for each of pair
 
 ## Changing a key
 
@@ -79,13 +79,3 @@ To change your key, simply repeat all of the steps listed above. Take note that
 ## Removing a key
 
 To remove a key, simply switch it back to the consensus key you have assigned on the provider chain by following steps in the `Adding a key` section and using your provider consensus key.
-
-## Querying proposed consumer chains
-
-To query the consumer addition proposals that are in the voting period, you can use the following command on the provider:
-
-```bash
-gaiad query provider list-proposed-consumer-chains
-```
-
-This query is valuable for staying informed about when keys can be assigned to newly proposed consumer chains.