Merge pull request #3583 from input-output-hk/co-354-network-magic-doc

[CO-354] docs: add configuration info for "protocolMagic"

Author: rvl

CHANGELOG.md

@@ -14,7 +14,7 @@
 
 - Fix a case where the error reporting system can cause the node to stop syncing. ([#3294](https://github.com/input-output-hk/cardano-sl/pull/3294), CDEC-469, CDEC-439)
 
-- Adjust the address format to distinguish testnet and mainnet addresses. ([#3540](https://github.com/input-output-hk/cardano-sl/pull/3540), [#3556](https://github.com/input-output-hk/cardano-sl/pull/3556), [#3558](https://github.com/input-output-hk/cardano-sl/pull/3558), [#3561](https://github.com/input-output-hk/cardano-sl/pull/3561), [#3578](https://github.com/input-output-hk/cardano-sl/pull/3578), [#3618](https://github.com/input-output-hk/cardano-sl/pull/3618), [#3659](https://github.com/input-output-hk/cardano-sl/pull/3659), CO-353, CO-354)
+- Adjust the address format to distinguish testnet and mainnet addresses. ([#3540](https://github.com/input-output-hk/cardano-sl/pull/3540), [#3556](https://github.com/input-output-hk/cardano-sl/pull/3556), [#3558](https://github.com/input-output-hk/cardano-sl/pull/3558), [#3561](https://github.com/input-output-hk/cardano-sl/pull/3561), [#3578](https://github.com/input-output-hk/cardano-sl/pull/3578), [#3583](https://github.com/input-output-hk/cardano-sl/pull/3583), [#3618](https://github.com/input-output-hk/cardano-sl/pull/3618), [#3659](https://github.com/input-output-hk/cardano-sl/pull/3659), [#3685](https://github.com/input-output-hk/cardano-sl/pull/3685), CO-353, CO-354)
 
 - Add a workaround for the RocksDB issue which prevented Daedalus Windows users with non-ASCII usernames from starting the wallet. ([#3465](https://github.com/input-output-hk/cardano-sl/pull/3465), CBR-391)
 

docs/configuration.md

@@ -264,13 +264,31 @@ mechanism (hex-encoded).
 Section `"protocolConsts"` contains basic protocol constants:
 
 *  `"k"` - security parameter from the paper,
-*  `"protocolMagic"` - protocol magic value (it's included into a
-   serialized block and header and it's part of signed data, so when protocol
-   magic is changed, all signatures become invalid) used to
-   distinguish different networks,
+*  `"protocolMagic"` - protocol magic section, described fully below:
+   * `"pm"` - protocol magic number,
+   * `"requiresNetworkMagic"` - either `"NMMustBeNothing"` or `"NMMustBeJust"`,
 *  `"vssMaxTTL"` - VSS certificates maximum timeout to live (number of epochs),
 *  `"vssMinTTL"` - VSS certificates minimum timeout to live (number of epochs).
 
+Section `"protocolMagic"` defines the protocol magic number. When the
+protocol magic is changed, all signatures become invalid. This is used
+to distinguish different networks.
+
+*  `"pm"` - is the protocol magic number, is included in serialized
+   blocks and headers, and is part of signed data.
+*  `"requiresNetworkMagic"` - will be either
+   `"NMMustBeNothing"` or `"NMMustBeJust"`
+
+The `"protocolMagic"` value can either be an object with the two
+fields described above, or just a plain integer. In the latter case,
+`"requiresNetworkMagic"` will take the default value of
+`"NMMustBeJust"`.
+
+The `"requiresNetworkMagic"` setting forms part of the genesis
+data. However it is configured in the
+[core section](#core-configuration-besides-genesis).
+
+
 Section `"heavyDelegation"` contains an information about heavyweight delegation:
 
 *  `"cert"` - delegation certificate,
@@ -574,7 +592,16 @@ to this file already.
 
 ### Core configuration besides genesis
 
-**TODO**
+* `requiresNetworkMagic` — influences both the genesis data and the
+  address format that the node uses. It can be either:
+   * `"NMMustBeNothing"` (mainnet setting) — means that the protocol
+     magic value will *not* be included in the address format or
+     transactions.
+   * `"NMMustBeJust"` (public testnet setting, the default) — means
+     that the protocol magic value will be included in the address
+     format and hence transactions.
+
+* `dbSerializeVersion` — **TODO**
 
 ### Infra configuration