Merge pull request #1 from ChainAgnostic/pr/jdsika/104

Editorial pass for minor style guide issues and clarity

tezos/README.md

@@ -9,22 +9,11 @@ updated: 2024-02-20
 replaces: CAIP-26
 ---
 
-# Namespace for Tezos Blockchains
-
 This document defines the applicability of CAIP schemes to the blockchains of the Tezos ecosystem according to the *Namespace Reference Purpose and Guidelines* of [CAIP-104][].
 
 ## Syntax
 
-The namespace `tezos` refers to the Tezos open-source blockchain protocol in general. The main implementation is called [Octez][]. The [Tezos test network infrastructure][] provides an overview of the different chains maintained by the community. The Tezos Mainnet can be determined through the genesis block hash: `BLockGenesisGenesisGenesisGenesisGenesisf79b5d1CoW2`.
-
-### Chain IDs
-
-*For context, see the [CAIP-2][] specification and in particular the `tezos-caip2` profile thereof.*
-
-| Alias          | Chain ID                         |
-| -------------- | -------------------------------- |
-| tezos:mainnet  | tezos:NetXdQprcVkpaWU            |
-| tezos:ghostnet | tezos:NetXnHfVqm9iesp            |
+The namespace `tezos` refers to the Tezos open-source blockchain protocol in general. The main implementation is called [Octez][]. The [Tezos test network infrastructure][] provides an overview of the different chains maintained by the community. 
 
 ## References
 

tezos/caip10.md

@@ -10,39 +10,40 @@ updated: 2024-02-28
 requires: ["CAIP-2", "CAIP-10"]
 ---
 
-# CAIP-10
-
 *For context, see the [CAIP-10][] specification.*
 
 ## Rationale
 
-Tezos supports the use of multiple public-key signature schemes, so the display address is prefixed with `tz1` ([Ed25519][] curve), `tz2` ([Secp256k1][] curve), `tz3` ([NIST P256][] curve), or `tz4` (BLS12-381 curve from the [BLS family][]) referenced in the [Tezos address types glossary][]. After the prefix, the rest of the account address is a [Base58 Check Encoded Blake2B Hash][] of each key's public key.
+Tezos supports the use of multiple public-key signature schemes; for this reason, a given account can have multiple addresses, each of which is prefixed with `tz1` ([Ed25519][] curve), `tz2` ([Secp256k1][] curve), `tz3` ([NIST P256][] curve), or `tz4` (BLS12-381 curve from the [BLS family][]) referenced in the [Tezos address types glossary][].
+After the prefix, the rest of the account address is a [Base58 Check Encoded Blake2B Hash][] of a public key of the type corresponding to the prefix.
 
 ## Syntax
 
-The syntax of a Tezos address matches the following regular expression (note the 58-character alphabet):
+The syntax of a Tezos address matches the following regular expression (note the [58-character alphabet][base58]):
 
-`(tz1|tz2|tz3|tz4) [1-9A-HJ-NP-Za-km-z]{33}`
+`(tz1|tz2|tz3|tz4)[1-9A-HJ-NP-Za-km-z]{33}`
 
 ## Chain IDs
 
-*For context, see the [CAIP-2][] specification and in particular the `tezos-caip2` profile thereof.*
+For how to compute a valid `chainId` segment or a list of examples, see [the CAIP-2 profile](./caip2.md).
 
 | Alias          | Chain ID                         |
 | -------------- | -------------------------------- |
-| tezos:mainnet  | tezos:NetXdQprcVkpaWU            |
-| tezos:ghostnet | tezos:NetXnHfVqm9iesp            |
+| tezos mainnet  | tezos:NetXdQprcVkpaWU            |
+| tezos ghostnet | tezos:NetXnHfVqm9iesp            |
+
+Tezos addresses are invariable across networks.
 
 ## Test Cases
 
-The Tezos namespace, the chain ID and the [Tezos address types][] allow the construction of the [CAIP-10][] compliant `Account ID`:
+Manually composed examples follow:
 
 ```bash
-# Tezos Mainnet
+# Ed25519-key address on Tezos Mainnet
 # Genesis block hash: BLockGenesisGenesisGenesisGenesisGenesisf79b5d1CoW2
 tezos:NetXdQprcVkpaWU:tz1MJx9vhaNRSimcuXPK2rW4fLccQnDAnVKJ
 
-# Tezos Ghostnet (Long-running test network)
+# NIST p256-key address on Tezos Ghostnet
 # Genesis block hash: BLockGenesisGenesisGenesisGenesisGenesis1db77eJNeJ9
 tezos:NetXnHfVqm9iesp:tz3btDQsDkqq2G7eBdrrLqetaAfLVw6BnPez
 ```

tezos/caip2.md

@@ -38,29 +38,37 @@ tezosB58CheckEncode('Net',
 
 ### Chain ID alias
 
-The Tezos community recognizes the different chains according to human readable names, the so called [Networks][]. The Octez RPC allows you to connect to three predefined networks:
+The Tezos community recognizes the different chains according to human readable names, which are called the "[Networks][]".
+The Octez RPC, for example, allows you to connect to three predefined networks by alias:
 
 ```bash
-# mainnet (this is the default)
+# mainnet (default)
 # sandbox
 # ghostnet
 
 > ./octez-node run --data-dir ~/tezos-ghostnet --network ghostnet
 ```
 
-There is currently no algorithm to connect the `chain ID` to the `network` as it is part of the Octez reference implementation of Tezos. In general it is determined by social consensus what chain ID is considered as `tezos:mainnet`. It is RECOMMENDED to use a separate chain registry to map an alias to the chain ID.
+There is currently no algorithm to connecting `chain ID`s to `network`s in the Octez reference implementation of Tezos.
+In general, social consensus determines which chain ID is considered the "tezos mainnet".
+It is RECOMMENDED to use a separate chain registry to map an alias to the chain ID.
 
 ### Backwards Compatibility
 
 Not applicable.
 
 ## Integrity guarantees for the chain ID
 
-The third chapter of the [Tezos Position Paper][] is dedicated to the analysis of potential threats leading to a user connecting to the Tezos network for the first time and not ending up on the `tezos:mainnet`. One of the main features of the technology is the [On-Chain Governance][] including its consensus mechanism based on [Proof-of-Stake][]. In combination with periodical checkpoints - which are created by institutions like e.g. a [Tezos Block Explorer][] or others based on social consensus - and statistical analysis of the chain using TAPOS "transactions as proof of stake" it is considered safe to assume to be connected to the mainnet regarding most given threat models. The current mainnet is running without a security breach since the `30th of June 2018` with enough incentive to attack its security mechanisms indicating the validity of the statement above.
+The third chapter of the [Tezos Position Paper][] is dedicated to the analysis of potential threats leading to a user connecting to the Tezos network for the first time and not ending up on the `tezos:mainnet`.
+One of the main features of the technology is the [On-Chain Governance][] including its consensus mechanism based on [Proof-of-Stake][]. 
+In combination with social consensus around periodic chain-state "checkpoints" used to bootstrap nodes and anchor shared ground-truth for, e.g. [Tezos Block Explorer][], a statistical analysis of the chain using TAPOS ("transactions as proof of stake") serves as guarantee of the integrity of the mainnet regarding these threat models. 
+The current mainnet has been running without a pertinent protocol-level security breach or consensus attack since the `30th of June 2018`.
 
 ## Test Cases
 
-This is a list of manually composed examples. See [Tezos test network infrastructure][] for available public chains. You can use the [Tezos RPC Interface][] to compute the chain id from a block hash as follows:
+This is a list of manually composed examples.
+See [Tezos test network infrastructure][] for available public chains.
+You can use the [Tezos RPC Interface][] to compute the chain id from a block hash as follows:
 
 ```bash
 # Tezos Ghostnet (Long-running test network)
@@ -84,8 +92,8 @@ The following table includes the chain ID aliases through their human readable n
 
 | Alias          | Chain ID                         |
 | -------------- | -------------------------------- |
-| tezos:mainnet  | tezos:NetXdQprcVkpaWU            |
-| tezos:ghostnet | tezos:NetXnHfVqm9iesp            |
+| tezos mainnet  | tezos:NetXdQprcVkpaWU            |
+| tezos ghostnet | tezos:NetXnHfVqm9iesp            |
 
 ## References