Update README.md #774
Update README.md #774
Conversation
Codecov Report
@@ Coverage Diff @@
## develop #774 +/- ##
===========================================
- Coverage 65.18% 59.41% -5.77%
===========================================
Files 65 62 -3
Lines 3550 3282 -268
===========================================
- Hits 2314 1950 -364
- Misses 1049 1187 +138
+ Partials 187 145 -42 |
README.md
Outdated
|
|
||
| - **Composability**: Anyone can create a module for the Cosmos-SDK, and using already-built modules in your blockchain is as simple as importing them into your application. As a developer, you only have to create the modules required by your application that do not already exist. | ||
|
|
||
| - **Capabilities**: Most developers will need to access other modules when building their own modules. Given that the Cosmos-SDK is an open framework, we designed it using object-capabilities (ocaps) based principles. This is because we assume the thread that some modules are malicious. In practice, this means that instead of having each module keep an access control list to give access to other modules, each module implements `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. For example, if an instance of module A's `keepers` is passed to module B, module B will be able to call a restricted set of module A's functions. The capabilities of each `keeper` are defined by the module's developer, and it is the job of the application developer to instanciate and pass a `keeper` from module to module properly. For a deeper look at capabilities, you can read this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). |
There was a problem hiding this comment.
"assume the thread that" -> "assume that"
README.md
Outdated
|
|
||
| - **Capabilities**: Most developers will need to access other modules when building their own modules. Given that the Cosmos-SDK is an open framework, we designed it using object-capabilities (ocaps) based principles. This is because we assume the thread that some modules are malicious. In practice, this means that instead of having each module keep an access control list to give access to other modules, each module implements `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. For example, if an instance of module A's `keepers` is passed to module B, module B will be able to call a restricted set of module A's functions. The capabilities of each `keeper` are defined by the module's developer, and it is the job of the application developer to instanciate and pass a `keeper` from module to module properly. For a deeper look at capabilities, you can read this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). | ||
|
|
||
| _Note: For now the Cosmos-SDK only exists in [Golang](https://golang.org/), which means that module developers can only develop SDK modules in Golang. In the future, we expect that Cosmos-SDK in other programming languages will pop up._ |
There was a problem hiding this comment.
Let's say something more compelling than "we expect ... will pop up". We can suggest we will financially support their development and ask people to reach out about it :)
There was a problem hiding this comment.
What do we mean by Cosmos-SDK in other programming languages - similar module-based frameworks? Compatible encoding / IBC implementations?
Maybe worth making clear that a developer doesn't need to reimplement the entire SDK to write an ABCI application in another language, or to write a second client in another language for an existing SDK application - they just need to implement the subset of SDK functionality required by their application.
README.md
Outdated
|
|
||
| ## Application architecture | ||
|
|
||
| A module is a fundamental unit in the Cosmos-SDK. A module defines its own transaction, handles its own state as well as its own state transition logic. The Cosmos-SDK has all the necessary pre-build modules to add functionality on top of a BaseApp, which is the template to build a blockchain dApp in Cosmos. Some of the most important ones are: |
There was a problem hiding this comment.
Once upon a time I thought we decided to call modules extensions. Did that change ? It's really easy to slide back to "module" but we should be consistent. Note they live under x for eXtension.
There was a problem hiding this comment.
"its own transaction" -> "its own transactions"
There was a problem hiding this comment.
Ok, I thought modules was the final name since Sunny used to call them plugins in the beginning.
There was a problem hiding this comment.
Think we're sticking to modules. We've been using it across all our external comms. We'll want to stick to golang's use of the term "module" and refer to it as a library. A module has keepers, mappers, handlers. Within a module, it has functions to generate said things. Is this consistent throughout?
README.md
Outdated
|
|
||
| A module is a fundamental unit in the Cosmos-SDK. A module defines its own transaction, handles its own state as well as its own state transition logic. The Cosmos-SDK has all the necessary pre-build modules to add functionality on top of a BaseApp, which is the template to build a blockchain dApp in Cosmos. Some of the most important ones are: | ||
| - Auth | ||
| - Token |
There was a problem hiding this comment.
Token ? Are we changing from bank ?
There was a problem hiding this comment.
I do think we should call it something different than bank imo.
README.md
Outdated
| - Token | ||
| - Governance | ||
| - Staking | ||
| - Handlers for messages and transactions |
There was a problem hiding this comment.
How is this distinct from the modules themselves ? Maybe each module should include a brief description here ?
README.md
Outdated
| - Governance | ||
| - Staking | ||
| - Handlers for messages and transactions | ||
| - REST and CLI sor secure user interactions |
README.md
Outdated
| - `client`: Command-Line to interface with the application. | ||
| - `server`: Rest server to communicate with the node. | ||
| - `examples`: Contains example on how to build a working application based on baseapp and modules | ||
| - `store`: Contains code for the multistore (i.e state). Each module can create any number of KVStores from the multistore. Be careful to properly handle access rights to each store with appropriate keepers. |
There was a problem hiding this comment.
shouldnt we mention the capabilities keys somewhere?
README.md
Outdated
| - `examples`: Contains example on how to build a working application based on baseapp and modules | ||
| - `store`: Contains code for the multistore (i.e state). Each module can create any number of KVStores from the multistore. Be careful to properly handle access rights to each store with appropriate keepers. | ||
| - `types`: Common types required in any SDK-based application. | ||
| - `x`: Folder for storing the BaseApp modules. You will find all the already-built modules in this directory. To use any of these modules, you just need to properly import them in your application. |
| interoperable blockchain applications in the Cosmos Network. | ||
|
|
||
| It is inspired by capabilities-based security, and informed by years of | ||
| wrestling with blockchain state machines. |
There was a problem hiding this comment.
I liked this paragraph as a concise overview of the whole thing. Is there someway we can still include it? Or you think not worth it given the new more complete descriptions ?
|
@ebuchman @Chjango @adrianbrink @jaekwon @cwgoes please check the updated file. Thanks ! |
README.md
Outdated
| ## Overview | ||
|
|
||
| The Cosmos SDK is a platform for building multi-asset Proof-of-Stake | ||
| cryptocurrencies, like the [Cosmos Hub](https://cosmos.network). It is both a library for building applications and a set of tools for securely interacting with them. |
There was a problem hiding this comment.
confusing - I'd remove the comma and rephrase - the context is confusing - the Cosmos Hub isn't a cryptocurrency but literally speaking this sentence suggests that
There was a problem hiding this comment.
I'd rephrase second sentence:
... for building and securely interaction with blockchain applications.
There was a problem hiding this comment.
Also I would introduce the PoS acronym the first time Proof-of-Stake is written:
Proof-of-Stake (Pos)
README.md
Outdated
| The Cosmos SDK is a platform for building multi-asset Proof-of-Stake | ||
| cryptocurrencies, like the [Cosmos Hub](https://cosmos.network). It is both a library for building applications and a set of tools for securely interacting with them. | ||
|
|
||
| The goal of the Cosmos-SDK is to allow developers to easily create their custom interoperable blockchain applications within the Cosmos Network without having to code every single functionality of their application, thus abstracting away the complexities of building a Tendermint ABCI application. We envision the SDK as the `npm`-like framework to build secure blockchain applications on top of Tendermint. |
There was a problem hiding this comment.
their -> remove its first use (and it's second based on my next comment)
There was a problem hiding this comment.
without having to code every single functionality
sounds odd, maybe grammatically incorrect, I'd change maybe to:
... without having to recreate common blockchain functionality.
There was a problem hiding this comment.
content comment: eventually we want to make the SDK tendermint independant (so long as the consensus engine fulfilled ABCI I believe) maybe too early to mention here though..
README.md
Outdated
|
|
||
| It is based on two major principles: | ||
|
|
||
| - **Composability**: Anyone can create a module for the Cosmos-SDK, and using the already-built modules in your blockchain is as simple as importing them into your application. As a developer, you only have to create the modules required by your application that do not already exist. |
There was a problem hiding this comment.
first sentence is good but I had to read it twice to understand the content. I'd change and using -> and integrating
There was a problem hiding this comment.
As a developer, you only have to create the modules required by your application that do not already exist
Isn't that obvious? I'd remove that sentence all together
There was a problem hiding this comment.
I don't think that's obvious and is worth mentioning.
README.md
Outdated
|
|
||
| The goal of the Cosmos-SDK is to allow developers to easily create their custom interoperable blockchain applications within the Cosmos Network without having to code every single functionality of their application, thus abstracting away the complexities of building a Tendermint ABCI application. We envision the SDK as the `npm`-like framework to build secure blockchain applications on top of Tendermint. | ||
|
|
||
| In terms of its design, the SDK optimizes flexibility and security. The framework is designed around a modular execution stack which allows applications to mix and match elements as desired. In addition, all modules are sandboxed for greater application security. |
README.md
Outdated
|
|
||
| - **Composability**: Anyone can create a module for the Cosmos-SDK, and using the already-built modules in your blockchain is as simple as importing them into your application. As a developer, you only have to create the modules required by your application that do not already exist. | ||
|
|
||
| - **Capabilities**: The SDK is inspired by capabilities-based security, and informed by years of wrestling with blockchain state machines. Most developers will need to access other modules when building their own modules. Given that the Cosmos-SDK is an open framework, we designed it using object-capabilities (_ocaps_) based principles. This is because we assume that some modules are malicious. In practice, this means that instead of having each module keep an access control list to give access to other modules, each module implements `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. For example, if an instance of module A's `keepers` is passed to module B, the latter will be able to call a restricted set of module A's functions. The capabilities of each `keeper` are defined by the module's developer, and it's the job of the application developer to instantiate and pass a `keeper` from module to module properly. For a deeper look at capabilities, you can read this [article](http://habitatchronicles.com/2017/05/what-are-capabilities/). |
There was a problem hiding this comment.
This is because we assume that some modules are malicious
This is because is a clumsy sentence transition from the previous sentence
There was a problem hiding this comment.
This means that instead of having each module keep an access control list to give access to other modules
->
This means that instead of having each module keep an access control list for other modules
There was a problem hiding this comment.
job of the application developer to instantiate and pass a
keeperfrom module to module properly
It's not their job to do it "properly" - that's a hand-wavey term here. It's their job to understand and audit the safety of foreign code from 3rd party modules based on the capabilities they are passing into each 3rd party module. <- let's change this sentence to reflect this more nuanced idea
README.md
Outdated
| The key directories of the SDK are: | ||
|
|
||
| - `baseapp`: Defines the template for a basic application. It implements the [ABCI protocol](https://cosmos.network/whitepaper#abci) so that your Cosmos-SDK application can communicate with the underlying Tendermint node. | ||
| - `client`: Command-Line to interface with the application. |
There was a problem hiding this comment.
seems incorrect - maybe "CLI and REST server tooling"
README.md
Outdated
|
|
||
| - `baseapp`: Defines the template for a basic application. It implements the [ABCI protocol](https://cosmos.network/whitepaper#abci) so that your Cosmos-SDK application can communicate with the underlying Tendermint node. | ||
| - `client`: Command-Line to interface with the application. | ||
| - `server`: Rest server to communicate with the node. |
There was a problem hiding this comment.
Thought this RPC server not Rest?
README.md
Outdated
| - `baseapp`: Defines the template for a basic application. It implements the [ABCI protocol](https://cosmos.network/whitepaper#abci) so that your Cosmos-SDK application can communicate with the underlying Tendermint node. | ||
| - `client`: Command-Line to interface with the application. | ||
| - `server`: Rest server to communicate with the node. | ||
| - `examples`: Contains example on how to build a working application based on baseapp and module. |
There was a problem hiding this comment.
Contains example on how to build a working application based on baseapp and module -> Contains examples on how to build a working standalone applications
README.md
Outdated
| - `client`: Command-Line to interface with the application. | ||
| - `server`: Rest server to communicate with the node. | ||
| - `examples`: Contains example on how to build a working application based on baseapp and module. | ||
| - `store`: Contains code for the multistore (i.e state). Each module can create any number of KVStores from the multistore. Be careful to properly handle access rights to each store with appropriate keepers. |
There was a problem hiding this comment.
I don't think KVStores has been previously defined, I would just explicitly say key-value stores
There was a problem hiding this comment.
not sure this sentence quite belongs here, it's like a tip on how to program in the SDK not a description of what's in the directory:
Be careful to properly handle access rights to each store with appropriate keepers
README.md
Outdated
| - `examples`: Contains example on how to build a working application based on baseapp and module. | ||
| - `store`: Contains code for the multistore (i.e state). Each module can create any number of KVStores from the multistore. Be careful to properly handle access rights to each store with appropriate keepers. | ||
| - `types`: Common types required in any SDK-based application. | ||
| - `x`(for e**X**tensions): Folder for storing the BaseApp module. You will find all the already-built modules in this directory. To use any of these modules, you just need to properly import them in your application. |
There was a problem hiding this comment.
haha - always wondered about the x
There was a problem hiding this comment.
"properly import" is kinda iffy language (what is proper) - Also I'd remove use of the word you in this bullet
Updated README by compiling & summarizing information from videos, keynotes (Sunny's, Adrian's), previous docs, blog articles and @gamarin2 tutorial's overview.