From 96abadac106f2c0c4d8f42170f9fa5cf16f6d6e3 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 23 Nov 2023 20:17:02 +0400 Subject: [PATCH] docs: various small improvements (part 2) (#1683) * docs: fix the number of connections CometBFT opens to the ABCI app * docs: fix link formatting * docs: make it explicit that default is TCP for ABCI * docs: replace 'supermajority' with 2/3+ 2/3+ is easier to understand. also this is the first time the reader is seeing the word 'supermajority', which might be confusing without the defition. The defition for supermajority is absent (maybe it's in the spec though) * add a link to jq * suggestions from Lasaro --- docs/app-dev/abci-cli.md | 2 +- docs/app-dev/indexing-transactions.md | 10 ++++------ docs/core/block-structure.md | 19 +++++++++++-------- docs/core/state-sync.md | 4 +++- docs/core/using-cometbft.md | 6 +++--- 5 files changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/app-dev/abci-cli.md b/docs/app-dev/abci-cli.md index 17aa4f2bf2e..ba944b7a86a 100644 --- a/docs/app-dev/abci-cli.md +++ b/docs/app-dev/abci-cli.md @@ -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 diff --git a/docs/app-dev/indexing-transactions.md b/docs/app-dev/indexing-transactions.md index a2ca5a5b18a..f0916cb16d4 100644 --- a/docs/app-dev/indexing-transactions.md +++ b/docs/app-dev/indexing-transactions.md @@ -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](https://github.com/cometbft/cometbft/blob/main/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. @@ -284,4 +280,6 @@ Users can use anything as an event value. However, if the event attribute value - Event values are converted to big floats (from the `big/math` package). The precision of the floating point number is set to the bit length 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. \ No newline at end of file +- Note that comparing to floats can be imprecise with a high number of decimals. + +[abci-events]: https://github.com/cometbft/cometbft/blob/main/spec/abci/abci++_basic_concepts.md#events diff --git a/docs/core/block-structure.md b/docs/core/block-structure.md index a422aa9cd9a..dc6819be20a 100644 --- a/docs/core/block-structure.md +++ b/docs/core/block-structure.md @@ -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/main/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/main/spec/core/data_structures.md +[types]: https://pkg.go.dev/github.com/cometbft/cometbft/types diff --git a/docs/core/state-sync.md b/docs/core/state-sync.md index 0f477302e29..7f5c5433d2e 100644 --- a/docs/core/state-sync.md +++ b/docs/core/state-sync.md @@ -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/ diff --git a/docs/core/using-cometbft.md b/docs/core/using-cometbft.md index 546387c8321..82ec9a30422 100644 --- a/docs/core/using-cometbft.md +++ b/docs/core/using-cometbft.md @@ -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