add docs

.github/workflows/e2e.yaml

@@ -92,7 +92,7 @@ jobs:
          go-version: ${{ env.GO_VERSION }}
 
      - name: Download Host Artifact
-       uses: actions/download-artifact@v3
+       uses: actions/download-artifact@v4.1.8
        with:
          name: ${{ env.IMAGE_NAME }}
          path: /tmp

INTEGRATION.md

@@ -5,6 +5,7 @@
 * [Example integration of the PoA Module](#example-integration-of-the-poa-module)
     * [Ante Handler Setup](#ante-handler-integration)
 * [Network Considerations](#network-considerations)
+* [PoA to PoS Migration](#migrating-to-pos-from-poa)
 
 # Introduction
 
@@ -133,7 +134,7 @@ func NewAnteHandler(options HandlerOptions) (sdk.AnteHandler, error) {
 
 ### [Disable Withdraw Delegation Rewards](./ante/disable_withdraw_delegator_rewards.go)
 
-This decorator blocks the `MsgWithdrawDelegatorReward` message from the CosmosSDK `x/distribution` module. The decorator acts as a preventive measure against a crash caused by an interaction between the POA module and the CosmosSDK `x/distribution` module. 
+This decorator blocks the `MsgWithdrawDelegatorReward` message from the CosmosSDK `x/distribution` module. The decorator acts as a preventive measure against a crash caused by an interaction between the POA module and the CosmosSDK `x/distribution` module.
 
 While the crash has a low probability of occurring in the wild, it is a critical issue that can cause the chain to halt.
 
@@ -253,8 +254,29 @@ If you want a module's control not to be based on governance (e.g. x/upgrade for
 
 ## Migrating to PoS from PoA
 
-A future optional upgrade will grant PoA networks the ability to migrate to PoS (Proof-of-Stake).
+You can perform an upgrade to transition from this PoA module on your network, to the Cosmos SDK's native staking module with delegators. [poa_to_pos_test e2e](./e2e/poa_to_pos_test.go).
 
-Reasons this may be desired:
+### Desired Reasons
 - The chain product has been successful and the network is ready to be decentralized.
 - There is a new token use case that requires a PoS network for user delegations (ex: sharing platform rewards with stakers).
+
+### Risk
+
+Networks using IBC (07-tendermint light client) may break if too many new validators enter the set within the trusting period. This would require IBC clients be updated on counterparty chains with the 'new' validator set.
+
+PoA safe guards this risk within the module itself by not allowing >33% of the validator set to be changed within a block *(technically you could still bypass this with the unsafe message flag on SetPower)*. This is a security limitation of IBC and how the 07-tendermint light client works, NOT a limit of proof of authority in any way. This could technically happen on any PoS network in the Cosmos ecosystem, but is more likely to happen on a PoA network with a small validator set and low stake.
+
+We recommend you coordinate with either foundation delegations or a phased approach
+- validators get tokens
+- PoA is removed but a staking ante block is set so only validators can delegate
+- validators self delegate
+- then the ante staking whitelist is removed and open for all
+
+This is up to your team to implement and is more operations than technical. It may not be an issue for teams but we do want to call out so you are aware.
+
+### How to Upgrade
+- Remove all references to the poa module in your application
+- Any modules using the poa.ModuleName as the authority should be changed to something like govtypes.ModuleName (app.go)
+- Create a NoOp upgrade handler that does a Store removal of the "poa" key namespace. ([example, PR #240](https://github.com/strangelove-ventures/poa/pull/240))
+
+

README.md

@@ -9,7 +9,7 @@
 
 
 
-The Proof of Authority (PoA) module allows for permissioned networks to be controlled by a predefined set of validators to verify transactions. This implementation extends the Cosmos-SDK's x/staking module to a set of administrators over the chain. These administrators gate keep the chain by whitelisting validators, updating consensus power, and removing validators from the network.
+The Proof of Authority (PoA) module allows for permissioned networks to be controlled by a predefined set of validators to verify transactions. This implementation extends the Cosmos-SDK's x/staking module to a set of administrators over the chain. These administrators gate keep the chain by whitelisting validators, updating consensus power, and removing validators from the network. Networks can then easily transition to a standard Proof of Stake (PoS) module [with a simple upgrade](./INTEGRATION.md#migrating-to-pos-from-poa).
 
 ## Security
 
@@ -28,13 +28,17 @@ The default POA administrator is set to the `x/gov` module address. One can chan
 ```bash
 # Override the default PoA admin address
 POA_ADMIN_ADDRESS="cosmos1hj5fveer5cjtn4wd6wstzugjfdxzl0xpxvjjvr" poad start
-````
+```
+
+## Migration
+
+You can migrate from the PoA module to the standard x/staking module by following the [migration guide](./INTEGRATION.md#migrating-to-pos-from-poa). **READ** the risk that are involved with this migration if your network has live IBC (07-tendermint) connections.
 
 ## Configuration
 
 After integrating the PoA module into your chain, read the [network considerations](./INTEGRATION.md#network-considerations) before launching the network.
 
-This includes: parameters, full module control, migrating from PoA->PoS, and other useful information.
+This includes: parameters, full module control, and other useful information.
 
 ## Concepts
 
@@ -68,9 +72,9 @@ For better UX, this is accomplished by wrapping the x/staking module's `create-v
 
 **Flow**:
 - Validator previous block set power is 9 (3 validators @ 3 power)
-- The admin increases validator[0] to 4 power (+11%)
-- The admin increases validator[1] to 4 power (+22%)
-- The admin increases validator[2] to 4 power (+33%, error)
+- The admin increases `validator[0]` to 4 power (+11%)
+- The admin increases `validator[1]` to 4 power (+22%)
+- The admin increases `validator[2]` to 4 power (+33%, error)
 
 The `AbsoluteChangedPower` of +1 to each validator is 3, which is 33% of the previous block power (3/9). It can be bypassed with the use of the `--unsafe` flag in the CLI command.