cometbft · melekes · Nov 23, 2023 · Nov 23, 2023 · Nov 23, 2023
@@ -240,7 +240,7 @@ You could put the commands in a file and run
 
 Note that the `abci-cli` is designed strictly for testing and debugging. In a real
 deployment, the role of sending messages is taken by CometBFT, which
-connects to the app using three separate connections, each with its own
+connects to the app using four separate connections, each with its own
 pattern of messages.
 
 For examples of running an ABCI app with CometBFT, see the

@@ -14,11 +14,7 @@ the block itself is never stored.
 
 Each event contains a type and a list of attributes, which are key-value pairs
 denoting something about what happened during the method's execution. For more
-details on `Events`, see the
-
-[ABCI](../spec/abci/abci++_basic_concepts.md#events)
-
-documentation.
+details on `Events`, see the [ABCI][abci-events] documentation.
 
 An `Event` has a composite key associated with it. A `compositeKey` is
 constructed by its type and key separated by a dot.
@@ -76,6 +72,7 @@ entirely in the future.
 
 The kv indexer stores each attribute of an event individually, by creating a composite key
 with
+
 - event type,
 - attribute key,
 - attribute value,
@@ -121,6 +118,7 @@ transferBalance200FinalizeBlock12          1
 transferNodeNothingFinalizeBlock12         1
 
 ```
+
 The event number is a local variable kept by the indexer and incremented when a new event is processed.
 It is an `int64` variable and has no other semantics besides being used to associate attributes belonging to the same events within a height.
 This variable is not atomically incremented as event indexing is deterministic. **Should this ever change**, the event id generation
@@ -285,3 +283,5 @@ Users can use anything as an event value. However, if the event attribute value
 of the integer it is supposed to represent, so that there is no loss of information due to insufficient precision. This was not present before CometBFT v0.38.x and all float values were ignored.
 - As of CometBFT v0.38.x, queries can contain floating point numbers as well.
 - Note that comparing to floats can be imprecise with a high number of decimals.
+
+[abci-events]: ../spec/abci/abci++_basic_concepts.md#events
@@ -4,13 +4,16 @@ order: 8
 
 # Block Structure
 
-The CometBFT consensus engine records all agreements by a
-supermajority of nodes into a blockchain, which is replicated among all
-nodes. This blockchain is accessible via various RPC endpoints, mainly
-`/block?height=` to get the full block, as well as
-`/blockchain?minHeight=_&maxHeight=_` to get a list of headers. But what
-exactly is stored in these blocks?
+The CometBFT consensus engine records all agreements by a 2/3+ of nodes
+into a blockchain, which is replicated among all nodes. This blockchain is
+accessible via various RPC endpoints, mainly `/block?height=` to get the full
+block, as well as `/blockchain?minHeight=_&maxHeight=_` to get a list of
+headers. But what exactly is stored in these blocks?
 
-The [specification](https://github.com/cometbft/cometbft/blob/v0.38.x/spec/core/data_structures.md) contains a detailed description of each component - that's the best place to get started.
+The [specification][data_structures] contains a detailed description of each
+component - that's the best place to get started.
 
-To dig deeper, check out the [types package documentation](https://godoc.org/github.com/cometbft/cometbft/types).
+To dig deeper, check out the [types package documentation][types].
+
+[data_structures]: https://github.com/cometbft/cometbft/blob/v0.38.x/spec/core/data_structures.md
+[types]: https://pkg.go.dev/github.com/cometbft/cometbft/types
@@ -30,7 +30,7 @@ The next information you will need to acquire it through publicly exposed RPC's
 - `trust_period`: Trust period is the period in which headers can be verified.
   > :warning: This value should be significantly smaller than the unbonding period.
 
-If you are relying on publicly exposed RPC's to get the need information, you can use `curl`.
+If you are relying on publicly exposed RPC's to get the need information, you can use `curl` and [`jq`][jq].
 
 Example:
 
@@ -46,3 +46,5 @@ The response will be:
   "hash": "188F4F36CBCD2C91B57509BBF231C777E79B52EE3E0D90D06B1A25EB16E6E23D"
 }
 ```
+
+[jq]: https://jqlang.github.io/jq/
@@ -130,7 +130,7 @@ cometbft node
 ```
 
 By default, CometBFT will try to connect to an ABCI application on
-`127.0.0.1:26658`. If you have the `kvstore` ABCI app installed, run it in
+`tcp://127.0.0.1:26658`. If you have the `kvstore` ABCI app installed, run it in
 another window. If you don't, kill CometBFT and run an in-process version of
 the `kvstore` app:
 
@@ -139,8 +139,8 @@ cometbft node --proxy_app=kvstore
 ```
 
 After a few seconds, you should see blocks start streaming in. Note that blocks
-are produced regularly, even if there are no transactions. See _No Empty
-Blocks_, below, to modify this setting.
+are produced regularly, even if there are no transactions. See [No Empty
+Blocks](#no-empty-blocks), below, to modify this setting.
 
 CometBFT supports in-process versions of the `counter`, `kvstore`, and `noop`
 apps that ship as examples with `abci-cli`. It's easy to compile your app