From 0868daa0595389d3c55afa53ea49e1eb31bd9239 Mon Sep 17 00:00:00 2001
From: Julien Robert <julien@rbrt.fr>
Date: Thu, 31 Aug 2023 15:40:15 +0200
Subject: [PATCH] docs: add genesis changes in upgrading.md (#17596)

---
 UPGRADING.md        | 24 +++++++++++++++++++++---
 x/genutil/README.md | 22 +++++++++++++++++++++-
 2 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index 8145397b5d..1faeac4597 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -53,7 +53,7 @@ Following an exhaustive list:
 * Package `client/grpc/tmservice` -> `client/grpc/cmtservice`
 
 Additionally, the commands and flags mentioning `tendermint` have been renamed to `comet`.
-However, these commands and flags are still supported for backward compatibility.
+These commands and flags are still supported for backward compatibility.
 
 For backward compatibility, the `**/tendermint/**` gRPC services are still supported.
 
@@ -61,6 +61,7 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug
 
 * The usage of the CometBFT logger has been replaced by the Cosmos SDK logger interface (`cosmossdk.io/log.Logger`).
 * The usage of `github.com/cometbft/cometbft/libs/bytes.HexByte` has been replaced by `[]byte`.
+* Usage of an application genesis (see [genutil](#xgenutil)).
 
 #### Enable Vote Extensions
 
@@ -101,7 +102,6 @@ allows an application to define handlers for these methods via `ExtendVoteHandle
 and `VerifyVoteExtensionHandler` respectively. Please see [here](https://docs.cosmos.network/v0.50/building-apps/vote-extensions)
 for more info.
 
-
 #### Upgrade
 
 **Users using `depinject` / app v2 do not need any changes, this is abstracted for them.**
@@ -343,7 +343,25 @@ For ante handler construction via `ante.NewAnteHandler`, the field `ante.Handler
 
 #### `x/capability`
 
-Capability has been moved to [IBC-GO](https://github.com/cosmos/ibc-go). IBC v8 will contain the necessary changes to incorporate the new module location.
+Capability has been moved to [IBC Go](https://github.com/cosmos/ibc-go). IBC v8 will contain the necessary changes to incorporate the new module location.
+
+#### `x/genutil`
+
+The Cosmos SDK has migrated from a CometBFT genesis to a application managed genesis file.
+The genesis is now fully handled by `x/genutil`. This has no consequences for running chains:
+
+* Importing a CometBFT genesis is still supported.
+* Exporting a genesis now exports the genesis as an application genesis.
+
+When needing to read an application genesis, use the following helpers from the `x/genutil/types` package:
+
+```go
+// AppGenesisFromReader reads the AppGenesis from the reader.
+func AppGenesisFromReader(reader io.Reader) (*AppGenesis, error)
+
+// AppGenesisFromFile reads the AppGenesis from the provided file.
+func AppGenesisFromFile(genFile string) (*AppGenesis, error)
+```
 
 #### `x/gov`
 
diff --git a/x/genutil/README.md b/x/genutil/README.md
index c534b8b0d7..45cb45355b 100644
--- a/x/genutil/README.md
+++ b/x/genutil/README.md
@@ -2,16 +2,36 @@
 
 ## Concepts
 
-The `genutil` package contains a variaety of genesis utility functionalities for usage within a blockchain application. Namely:
+The `genutil` package contains a variety of genesis utility functionalities for usage within a blockchain application. Namely:
 
 * Genesis transactions related (gentx)
 * Commands for collection and creation of gentxs
 * `InitChain` processing of gentxs
+* Genesis file creation
 * Genesis file validation
 * Genesis file migration
 * CometBFT related initialization
     * Translation of an app genesis to a CometBFT genesis
 
+## Genesis
+
+Genutil contains the data structure that defines an application genesis.
+An application genesis consist of a consensus genesis (g.e. CometBFT genesis) and application related genesis data.
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L24-L34
+```
+
+The application genesis can then be translated to the consensus engine to the right format:
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L126-L136
+```
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/server/start.go#L397-L407
+```
+
 ## Client
 
 ### CLI