docs: Update high level overview and introduction #20535
Conversation
WalkthroughWalkthroughThe changes in the Changes
Possibly related issues
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Files selected for processing (1)
- docs/learn/intro/00-overview.md (2 hunks)
Additional context used
Path-based instructions (1)
docs/learn/intro/00-overview.md (1)
Pattern
**/*.md: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness"
LanguageTool
docs/learn/intro/00-overview.md
[style] ~16-~16: Consider an alternative adjective to strengthen your wording. (DEEP_PROFOUND)
Context: ... of interactions between modules. For a deeper look at capabilities, jump to [Object-C...
[uncategorized] ~18-~18: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE)
Context: ...ld the basic house from the instructions or you can choose to modify your house and...
[style] ~22-~22: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase. (EN_WEAK_ADJECTIVE)
Context: ...contracts. While smart contracts can be very good for some use cases like single-use appl...
[typographical] ~30-~30: Consider adding a comma after ‘Originally’ for more clarity. (RB_LY_COMMA)
Context: ...ussions between monolithic and modular. Originally the Cosmos SDK was built with a vision ...
[typographical] ~30-~30: After the expression ‘for example’ a comma is usually used. (COMMA_FOR_EXAMPLE)
Context: ...rent software for different layers. For example you can choose to build a vanilla chain...
[uncategorized] ~30-~30: Do not mix variants of the same word (‘customise’ and ‘customize’) within a single text. (EN_WORD_COHERENCY)
Context: ...e benefit of modularity is that you can customise your chain to your specific use case. ...
[uncategorized] ~36-~36: Do not mix variants of the same word (‘customise’ and ‘customize’) within a single text. (EN_WORD_COHERENCY)
Context: ...: * It allows you to plug and play and customise your consensus layer. As above you can ...
[uncategorized] ~36-~36: A comma is probably missing here. (MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
Context: ... and customise your consensus layer. As above you can use Rollkit and Celestia as you...
[uncategorized] ~37-~37: Possible missing comma found. (AI_HYDRA_LEO_MISSING_COMMA)
Context: ...ot of flexibility and customisation. * Previously the default consensus engine available ...
[style] ~37-~37: ‘in existence’ might be wordy. Consider a shorter alternative. (EN_WORDINESS_PREMIUM_IN_EXISTENCE)
Context: ... (and only) mature BFT consensus engine in existence. It is widely used across the industry ...
Additional comments not posted (3)
docs/learn/intro/00-overview.md (3)
9-9: Update enhances clarity and scope of the SDK's capabilities.
11-12: Clear and effective expansion on blockchain interoperability and modular consensus engines.
14-14: Excellent detail added to explain the flexibility and customization available to developers.
|
Thanks! lets wait till facu is back for a last review as he always gives me good feedback on my writing! |
docs/learn/intro/00-overview.md
Outdated
| @@ -18,11 +25,16 @@ Application-specific blockchains offer a radically different development paradig | |||
|
|
|||
| Learn more about [application-specific blockchains](./01-why-app-specific.md). | |||
|
|
|||
| ## What is Modularity | |||
|
|
|||
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind. Modularity is dirived from splitting a blockchain into customisable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customisable by using different software for different layers. For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customise your chain to your specific use case. | |||
There was a problem hiding this comment.
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind. Modularity is dirived from splitting a blockchain into customisable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customisable by using different software for different layers. For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customise your chain to your specific use case. | |
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind. Modularity is derived from splitting a blockchain into customizable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customisable by using different software for different layers. For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customize your chain to your specific use case. |
docs/learn/intro/00-overview.md
Outdated
|
|
||
| * The default consensus engine available within the Cosmos SDK is [CometBFT](https://github.com/cometbft/cometbft). CometBFT is the most (and only) mature BFT consensus engine in existence. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems. | ||
| * It allows you to plug and play and customise your consensus layer. As above you can use Rollkit and Celestia as your consensus and data availability layer. This offers a lot of flexibility and customisation. |
There was a problem hiding this comment.
| * It allows you to plug and play and customise your consensus layer. As above you can use Rollkit and Celestia as your consensus and data availability layer. This offers a lot of flexibility and customisation. | |
| * It allows you to plug and play and customise your consensus layer. As above you can use Rollkit and Celestia as your consensus and data availability layer. This offers a lot of flexibility and customization. |
samricotta
added
the
backport/v0.50.x
(cherry picked from commit 78327f4) # Conflicts: # docs/docs/learn/intro/00-overview.md
There was a problem hiding this comment.
Actionable comments posted: 4
Review details
Configuration used: .coderabbit.yml
Review profile: CHILL
Files selected for processing (1)
- docs/learn/intro/00-overview.md (2 hunks)
Additional context used
Path-based instructions (1)
docs/learn/intro/00-overview.md (1)
Pattern
**/*.md: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness"
LanguageTool
docs/learn/intro/00-overview.md
[style] ~16-~16: Consider an alternative adjective to strengthen your wording. (DEEP_PROFOUND)
Context: ... of interactions between modules. For a deeper look at capabilities, jump to [Object-C...
[uncategorized] ~18-~18: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE)
Context: ...ld the basic house from the instructions or you can choose to modify your house and...
[style] ~22-~22: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase. (EN_WEAK_ADJECTIVE)
Context: ...contracts. While smart contracts can be very good for some use cases like single-use appl...
[typographical] ~30-~30: Consider adding a comma after ‘Originally’ for more clarity. (RB_LY_COMMA)
Context: ...ussions between monolithic and modular. Originally the Cosmos SDK was built with a vision ...
[uncategorized] ~30-~30: Do not mix variants of the same word (‘customisable’ and ‘customizable’) within a single text. (EN_WORD_COHERENCY)
Context: ... plug and play, making their blockchain customisable by using different software for differe...
[typographical] ~30-~30: After the expression ‘for example’ a comma is usually used. (COMMA_FOR_EXAMPLE)
Context: ...rent software for different layers. For example you can choose to build a vanilla chain...
[uncategorized] ~36-~36: A comma is probably missing here. (MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
Context: ... and customize your consensus layer. As above you can use Rollkit and Celestia as you...
[style] ~37-~37: ‘in existence’ might be wordy. Consider a shorter alternative. (EN_WORDINESS_PREMIUM_IN_EXISTENCE)
Context: ... (and only) mature BFT consensus engine in existence. It is widely used across the industry ...
Markdownlint
docs/learn/intro/00-overview.md
11-11: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
12-12: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
36-36: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
Additional comments not posted (6)
docs/learn/intro/00-overview.md (6)
9-9: Update the description to reflect the toolkit nature of the Cosmos SDK.
11-12: Ensure the new description of the Cosmos SDK's goals is clear and comprehensive.Tools
Markdownlint
11-11: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
12-12: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
12-12: Clarify the range of consensus engines available.Tools
Markdownlint
12-12: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
14-14: Highlight the flexibility and customization options available to developers.
16-16: Enhance the description of the Cosmos SDK's capabilities-based system.Tools
LanguageTool
[style] ~16-~16: Consider an alternative adjective to strengthen your wording. (DEEP_PROFOUND)
Context: ... of interactions between modules. For a deeper look at capabilities, jump to [Object-C...
36-36: Clarify the flexibility and customization options in the consensus layer.Tools
LanguageTool
[uncategorized] ~36-~36: A comma is probably missing here. (MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
Context: ... and customize your consensus layer. As above you can use Rollkit and Celestia as you...Markdownlint
36-36: Expected: 0 or 2; Actual: 1 (MD009, no-trailing-spaces)
Trailing spaces
|
|
||
| SDK-based blockchains have the choice to use the predefined modules or to build their own modules. What this means is that developers can build a blockchain that is tailored to their specific use case, without having to worry about the low-level details of building a blockchain from scratch. Predefined modules include staking, governance, and token issuance, among others. | ||
|
|
||
| What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../advanced/10-ocap.md). |
There was a problem hiding this comment.
Consider using "comprehensive" instead of "deeper" for stronger impact.
Would you like me to update this in the documentation?
Tools
LanguageTool
[style] ~16-~16: Consider an alternative adjective to strengthen your wording. (DEEP_PROFOUND)
Context: ... of interactions between modules. For a deeper look at capabilities, jump to [Object-C...
|
|
||
| What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../advanced/10-ocap.md). | ||
|
|
||
| How you can look at this is if we imagine that the SDK is like a lego kit. You can choose to build the basic house from the instructions or you can choose to modify your house and add more floors, more doors, more windows. The choice is yours. |
There was a problem hiding this comment.
Add a comma before "or" for grammatical correctness.
- You can choose to build the basic house from the instructions or you can choose to modify your house and add more floors, more doors, more windows.
+ You can choose to build the basic house from the instructions, or you can choose to modify your house and add more floors, more doors, more windows.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| How you can look at this is if we imagine that the SDK is like a lego kit. You can choose to build the basic house from the instructions or you can choose to modify your house and add more floors, more doors, more windows. The choice is yours. | |
| How you can look at this is if we imagine that the SDK is like a lego kit. You can choose to build the basic house from the instructions, or you can choose to modify your house and add more floors, more doors, more windows. The choice is yours. |
Tools
LanguageTool
[uncategorized] ~18-~18: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE)
Context: ...ld the basic house from the instructions or you can choose to modify your house and...
|
|
||
| * The default consensus engine available within the Cosmos SDK is [CometBFT](https://github.com/cometbft/cometbft). CometBFT is the most (and only) mature BFT consensus engine in existence. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems. | ||
| * It allows you to plug and play and customize your consensus layer. As above you can use Rollkit and Celestia as your consensus and data availability layer. This offers a lot of flexibility and customisation. | ||
| * Previously the default consensus engine available within the Cosmos SDK is [CometBFT](https://github.com/cometbft/cometbft). CometBFT is the most (and only) mature BFT consensus engine in existence. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems. |
There was a problem hiding this comment.
Simplify the description of CometBFT's status.
- CometBFT is the most (and only) mature BFT consensus engine in existence.
+ CometBFT is the most (and only) mature BFT consensus engine available.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| * Previously the default consensus engine available within the Cosmos SDK is [CometBFT](https://github.com/cometbft/cometbft). CometBFT is the most (and only) mature BFT consensus engine in existence. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems. | |
| * Previously the default consensus engine available within the Cosmos SDK is [CometBFT](https://github.com/cometbft/cometbft). CometBFT is the most (and only) mature BFT consensus engine available. It is widely used across the industry and is considered the gold standard consensus engine for building Proof-of-Stake systems. |
Tools
LanguageTool
[style] ~37-~37: ‘in existence’ might be wordy. Consider a shorter alternative. (EN_WORDINESS_PREMIUM_IN_EXISTENCE)
Context: ... (and only) mature BFT consensus engine in existence. It is widely used across the industry ...
| @@ -18,11 +25,16 @@ | |||
|
|
|||
| Learn more about [application-specific blockchains](./01-why-app-specific.md). | |||
|
|
|||
| ## What is Modularity | |||
|
|
|||
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind. Modularity is derived from splitting a blockchain into customizable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customisable by using different software for different layers. For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customize your chain to your specific use case. | |||
There was a problem hiding this comment.
Ensure consistency in the use of "customize" and add a comma after "Originally" and "For example".
- Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind.
+ Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally, the Cosmos SDK was built with a vision of modularity in mind.
- For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT.
+ For example, you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT.
- The benefit of modularity is that you can customise your chain to your specific use case.
+ The benefit of modularity is that you can customize your chain to your specific use case.Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally the Cosmos SDK was built with a vision of modularity in mind. Modularity is derived from splitting a blockchain into customizable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customisable by using different software for different layers. For example you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customize your chain to your specific use case. | |
| Today there is a lot of talk around modularity and discussions between monolithic and modular. Originally, the Cosmos SDK was built with a vision of modularity in mind. Modularity is derived from splitting a blockchain into customizable layers of execution, consensus, settlement and data availability, which is what the Cosmos SDK enables. This means that developers can plug and play, making their blockchain customizable by using different software for different layers. For example, you can choose to build a vanilla chain and use the Cosmos SDK with CometBFT. CometBFT will be your consensus layer and the chain itself would be the settlement and execution layer. Another route could be to use the SDK with Rollkit and Celestia as your consensus and data availability layer. The benefit of modularity is that you can customize your chain to your specific use case. |
Tools
LanguageTool
[typographical] ~30-~30: Consider adding a comma after ‘Originally’ for more clarity. (RB_LY_COMMA)
Context: ...ussions between monolithic and modular. Originally the Cosmos SDK was built with a vision ...
[uncategorized] ~30-~30: Do not mix variants of the same word (‘customisable’ and ‘customizable’) within a single text. (EN_WORD_COHERENCY)
Context: ... plug and play, making their blockchain customisable by using different software for differe...
[typographical] ~30-~30: After the expression ‘for example’ a comma is usually used. (COMMA_FOR_EXAMPLE)
Context: ...rent software for different layers. For example you can choose to build a vanilla chain...
* main: refactor(x/auth): Fix system test (#20531) feat(crypto): add blst (#20296) docs: Update high level overview and introduction (#20535) refactor(x/core): remove test (#20624) feat(x/mint)!: Replace InflationCalculationFn with MintFn + simple epoch minting (#20363) docs: remove duplicate words (#20622) feat: prep for errors v2 (#20539) chore: reduce default inflation (#20606) refactor(store): add miss defer (#20602) chore: use comet api pkg instead of comet alias (#20614) chore: write gentx info to cmd.ErrOrStderr (#20616) docs: ADR 073: update to accepted and add to README.md (#20619) chore(proto): change future extracted modules version from v1.0.0 to v0.2.0 (#20600) fix: remove some duplicate words (#20605) feat(stf): port simappv2 changes (#20587) chore: bring patch changelogs to main (#20599)
* build(deps): Bump github.com/cosmos/gogoproto from 1.4.12 to 1.5.0 (cosmos#20567) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> * refactor(x/authz,x/feegrant): provide updated keeper in depinject (cosmos#20590) * docs: Update high level overview and introduction (backport cosmos#20535) (cosmos#20627) Co-authored-by: samricotta <37125168+samricotta@users.noreply.github.com> Co-authored-by: marbar3778 <marbar3778@yahoo.com> * fix: Properly parse json in the wait-tx command. (backport cosmos#20631) (cosmos#20660) Co-authored-by: Daniel Wedul <github@wedul.com> Co-authored-by: marbar3778 <marbar3778@yahoo.com> * docs: remove Ineffective code block (backport cosmos#20703) (cosmos#20711) * feat(client): Add flag & reading mnemonic from file (backport cosmos#20690) (cosmos#20712) Co-authored-by: Hieu Vu <72878483+hieuvubk@users.noreply.github.com> Co-authored-by: marbar3778 <marbar3778@yahoo.com> * fix: nested multisig signatures using CLI (backport cosmos#20438) (cosmos#20692) Co-authored-by: Facundo Medica <14063057+facundomedica@users.noreply.github.com> Co-authored-by: marbar3778 <marbar3778@yahoo.com> Co-authored-by: Facundo <facundomedica@gmail.com> * feat(client/v2): get keyring from context (backport cosmos#19646) (cosmos#20727) Co-authored-by: Julien Robert <julien@rbrt.fr> * docs(x/group): orm codespace comment (backport cosmos#20749) (cosmos#20751) * feat: parse home flag earlier (backport cosmos#20771) (cosmos#20777) Co-authored-by: Julien Robert <julien@rbrt.fr> * build(deps): Bump github.com/cometbft/cometbft from 0.38.7 to 0.38.8 (cosmos#20805) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> * build(deps): Bump github.com/cometbft/cometbft from 0.38.8 to 0.38.9 (cosmos#20836) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> * fix(simulation): fix the problem of `validator set is empty after InitGenesis` in simulation test (backport cosmos#18196) (cosmos#20897) Co-authored-by: Chenqun Lu <luchenqun@qq.com> Co-authored-by: Julien Robert <julien@rbrt.fr> * fix(simulation): Fix all problems `make test-sim-custom-genesis-fast` for simulation test. (backport cosmos#17911) (cosmos#20909) Co-authored-by: Chenqun Lu <luchenqun@qq.com> Co-authored-by: Julien Robert <julien@rbrt.fr> * chore: prepare v0.50.8 (cosmos#20910) --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Julien Robert <julien@rbrt.fr> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> Co-authored-by: samricotta <37125168+samricotta@users.noreply.github.com> Co-authored-by: marbar3778 <marbar3778@yahoo.com> Co-authored-by: Daniel Wedul <github@wedul.com> Co-authored-by: Hieu Vu <72878483+hieuvubk@users.noreply.github.com> Co-authored-by: Facundo Medica <14063057+facundomedica@users.noreply.github.com> Co-authored-by: Facundo <facundomedica@gmail.com> Co-authored-by: Chenqun Lu <luchenqun@qq.com>
Description
Closes Partly: #20174
Author Checklist
All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.
I have...
!in the type prefix if API or client breaking changeCHANGELOG.mdReviewers Checklist
All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.
Please see Pull Request Reviewer section in the contributing guide for more information on how to review a pull request.
I have...
Summary by CodeRabbit