From 4f2b5ae06ae4828f1b01c2830e305e4fc83a1fb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Hurlin?= <clement.hurlin@tweag.io>
Date: Wed, 6 Dec 2023 16:46:31 +0100
Subject: [PATCH] create-testnet-data: document generated content (for users..
 and for us)

---
 .../CLI/EraBased/Run/CreateTestnetData.hs     | 54 ++++++++++++++++---
 1 file changed, 46 insertions(+), 8 deletions(-)

diff --git a/cardano-cli/src/Cardano/CLI/EraBased/Run/CreateTestnetData.hs b/cardano-cli/src/Cardano/CLI/EraBased/Run/CreateTestnetData.hs
index 839c7f40d6..f3c9a477d6 100644
--- a/cardano-cli/src/Cardano/CLI/EraBased/Run/CreateTestnetData.hs
+++ b/cardano-cli/src/Cardano/CLI/EraBased/Run/CreateTestnetData.hs
@@ -202,32 +202,38 @@ runGenesisCreateTestNetDataCmd Cmd.GenesisCreateTestNetDataCmdArgs
         pure $ shelleyGenesisDefaults { sgNetworkMagic = unNetworkMagic (toNetworkMagic networkId) }
 
   let -- {0 -> genesis-keys/genesis0/key.vkey, 1 -> genesis-keys/genesis1/key.vkey, ...}
-      genesisVKeysPaths = mkPaths numGenesisKeys (outputDir </> "genesis-keys") "genesis" "key.vkey"
+      genesisVKeysPaths = mkPaths numGenesisKeys genesisDir "genesis" "key.vkey"
       -- {0 -> delegate-keys/delegate0/key.vkey, 1 -> delegate-keys/delegate1/key.vkey, ...}
-      delegateKeys = mkPaths numGenesisKeys (outputDir </> "delegate-keys") "delegate" "key.vkey"
+      delegateKeys = mkPaths numGenesisKeys delegateDir "delegate" "key.vkey"
       -- {0 -> delegate-keys/delegate0/vrf.vkey, 1 -> delegate-keys/delegate1/vrf.vkey, ...}
-      delegateVrfKeys = mkPaths numGenesisKeys (outputDir </> "delegate-keys") "delegate" "vrf.vkey"
+      delegateVrfKeys = mkPaths numGenesisKeys delegateDir "delegate" "vrf.vkey"
 
   forM_ [ 1 .. numGenesisKeys ] $ \index -> do
     createGenesisKeys (genesisDir </> ("genesis" <> show index))
-    createDelegateKeys keyOutputFormat (outputDir </> "delegate-keys" </> ("delegate" <> show index))
+    createDelegateKeys keyOutputFormat (delegateDir </> ("delegate" <> show index))
+
+  writeREADME genesisDir genesisREADME
+  writeREADME delegateDir delegatesREADME
 
   -- UTxO keys
-  let utxoKeys = [outputDir </> "utxo-keys" </> ("utxo" <> show index) </> "utxo.vkey"
+  let utxoKeys = [utxoKeysDir </> ("utxo" <> show index) </> "utxo.vkey"
                   | index <-  [ 1 .. numUtxoKeys ]]
   forM_ [ 1 .. numUtxoKeys ] $ \index ->
-    createUtxoKeys $ outputDir </> "utxo-keys" </> ("utxo" <> show index)
+    createUtxoKeys $ utxoKeysDir </> ("utxo" <> show index)
+
+  writeREADME utxoKeysDir utxoKeysREADME
 
   let mayStakePoolRelays = Nothing -- TODO @smelc temporary?
 
   -- Pools
   poolParams <- forM [ 1 .. numPools ] $ \index -> do
-    let poolsDir = outputDir </> "pools-keys"
-        poolDir = poolsDir </> ("pool" <> show index)
+    let poolDir = poolsDir </> ("pool" <> show index)
 
     createPoolCredentials keyOutputFormat poolDir
     buildPoolParams networkId poolDir Nothing (fromMaybe mempty mayStakePoolRelays)
 
+  writeREADME poolsDir poolsREADME
+
   -- Stake delegators
   let (delegsPerPool, delegsRemaining) = divMod numStakeDelegators numPools
       delegsForPool poolIx = if delegsRemaining /= 0 && poolIx == numPools
@@ -260,10 +266,42 @@ runGenesisCreateTestNetDataCmd Cmd.GenesisCreateTestNetDataCmdArgs
   liftIO $ LBS.writeFile (outputDir </> "genesis.json") $ Aeson.encode shelleyGenesis'
   where
     genesisDir = outputDir </> "genesis-keys"
+    delegateDir = outputDir </> "delegate-keys"
+    utxoKeysDir = outputDir </> "utxo-keys"
+    poolsDir = outputDir </> "pools-keys"
     keyOutputFormat = KeyOutputFormatTextEnvelope
     mkDelegationMapEntry :: Delegation -> (Ledger.KeyHash Ledger.Staking StandardCrypto, Ledger.PoolParams StandardCrypto)
     mkDelegationMapEntry d = (dDelegStaking d, dPoolParams d)
 
+writeREADME :: ()
+  => FilePath
+  -> Text.Text
+  -> ExceptT GenesisCmdError IO ()
+writeREADME dir content = do
+  firstExceptT GenesisCmdFileError . newExceptT $ writeTextFile file content
+  where
+    file :: File Text.Text Out = File $ dir </> "README.md"
+
+genesisREADME :: Text.Text
+genesisREADME = Text.intercalate "\n"
+  ["Keys generated by the --genesis-keys flag. In Byron these keys were used to mint blocks and initiate hard forks."
+   , "Starting with Shelley and decentralization, blocks started being produced by other keys than genesis keys."
+   , "Still, these keys were required to trigger hard forks."
+   , "With the introduction of Conway, these keys should become useless"]
+
+delegatesREADME :: Text.Text
+delegatesREADME = Text.intercalate "\n"
+  ["Keys generated by the --genesis-keys flag. These keys are used to mint blocks when not being completely decentralized",
+   "(e.g. when stake pools are not the sole block producers). These keys are intended to run nodes."]
+
+utxoKeysREADME :: Text.Text
+utxoKeysREADME = Text.intercalate "\n"
+  ["Keys generated by the --utxo-keys flag. These keys receive a portion of the supply."]
+
+poolsREADME :: Text.Text
+poolsREADME = Text.intercalate "\n"
+  ["Keys generated by the --pools flag. These keys are intended to run nodes."]
+
 -- | @mkPaths numKeys dir segment filename@ returns the paths to the keys to generate.
 -- For example @mkPaths 3 dir prefix fn.ext@ returns
 -- [dir/segment1/fn.ext, dir/segment2/fn.ext, dir/segment3/fn.ext]