From 5b9ae43b766746e7ce7c4e3a2ae989feb1d7de3d Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Mon, 2 Apr 2018 14:21:34 -0300 Subject: [PATCH 1/3] Update SDK readme --- README.md | 119 +++++++++++++++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index d0cd45ee4..cfce6b931 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,63 @@ -# Cosmos SDK - -![banner](docs/graphics/cosmos-sdk-image.png) - -[![version](https://img.shields.io/github/tag/cosmos/cosmos-sdk.svg)](https://github.com/cosmos/cosmos-sdk/releases/latest) -[![API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk?status.svg -)](https://godoc.org/github.com/cosmos/cosmos-sdk) -[![Rocket.Chat](https://demo.rocket.chat/images/join-chat.svg)](https://cosmos.rocket.chat/) -[![license](https://img.shields.io/github/license/cosmos/cosmos-sdk.svg)](https://github.com/cosmos/cosmos-sdk/blob/master/LICENSE) -[![LoC](https://tokei.rs/b1/github/cosmos/cosmos-sdk)](https://github.com/cosmos/cosmos-sdk) -[![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk) - -Branch | Tests | Coverage -----------|-------|--------- -develop | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/develop/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) -master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) - - -WARNING: the libraries are still undergoing breaking changes as we get better ideas and start building out the Apps. - -**Note: Requires Go 1.9+** - -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 goals of the SDK are to abstract away the complexities of building a -Tendermint ABCI application in Golang and to provide a framework for building -interoperable blockchain applications in the Cosmos Network. - -It is inspired by capabilities-based security, and informed by years of -wrestling with blockchain state machines. - -The SDK is fast, safe, and easy-to-use. It is generic enough to be used to -implement the state machines of other existing blockchains, like Bitcoin and -Ethereum, allowing seamless integration with them and their data structures. -It comes with batteries included, is easily extensible, and does not require -developers to fork it to access any of its current or extended functionality. -It provides both REST and command line interfaces for secure user interactions. - -Applications in the Cosmos-SDK are defined in terms of handlers that process -messages and read and write to a store. Handlers are given restricted -capabilities that determine which parts of the store they can access. The SDK -provides common data structures for Accounts, multi-asset Coins, checking -signatures, preventing replay, and so on. - -For more details on the design goals, see the [SDK Guide](docs/guide.md) - -## Prerequisites - -* [golang](https://golang.org/doc/install) - -## Getting Started - -- See the [SDK Guide](docs/guide.md) +# Cosmos SDK +![banner](docs/graphics/cosmos-sdk-image.png) + +[![version](https://img.shields.io/github/tag/cosmos/cosmos-sdk.svg)](https://github.com/cosmos/cosmos-sdk/releases/latest) +[![API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk?status.svg +)](https://godoc.org/github.com/cosmos/cosmos-sdk) +[![Rocket.Chat](https://demo.rocket.chat/images/join-chat.svg)](https://cosmos.rocket.chat/) +[![license](https://img.shields.io/github/license/cosmos/cosmos-sdk.svg)](https://github.com/cosmos/cosmos-sdk/blob/master/LICENSE) +[![LoC](https://tokei.rs/b1/github/cosmos/cosmos-sdk)](https://github.com/cosmos/cosmos-sdk) +[![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk) + +Branch | Tests | Coverage +----------|-------|--------- +develop | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/develop) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/develop/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) +master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.svg?style=shield)](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master) | [![codecov](https://codecov.io/gh/cosmos/cosmos-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/cosmos/cosmos-sdk) + +**WARNING**: the libraries are still undergoing breaking changes as we get better ideas and start building out the Apps. + +**Note**: Requires [Go 1.9+](https://golang.org/dl/) + +## Overview + +The Cosmos-SDK is a developer toolkit which allows developers to easily create their custom blockchain applications within the Cosmos ecosystem without having to code every single functionality of their application. The SDK will be the `npm`-like framework to build secure blockchain applications on top of Tendermint. + +The SDK design 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. + +It is based on two major principles: + +- **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/). + +_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._ + +## 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: +- Auth +- Token +- Governance +- Staking +- Handlers for messages and transactions +- REST and CLI sor secure user interactions + +Key directories of the SDK: + +- `baseapp`: Defines the template for a basic application. Basically it implements the ABCI protocol 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 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. + +## Prerequisites + +- [Golang](https://golang.org/doc/install) + +## Getting Started + +See the [documentation](https://cosmos-sdk.readthedocs.io). + + From de11b3f6103b21bc9d200230e8d10d7d4f3fe49c Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Fri, 6 Apr 2018 10:55:49 -0300 Subject: [PATCH 2/3] defined modules and added suggestions from previous PR --- README.md | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index cfce6b931..218c4f920 100644 --- a/README.md +++ b/README.md @@ -18,39 +18,49 @@ master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.s **Note**: Requires [Go 1.9+](https://golang.org/dl/) + ## Overview -The Cosmos-SDK is a developer toolkit which allows developers to easily create their custom blockchain applications within the Cosmos ecosystem without having to code every single functionality of their application. The SDK will be the `npm`-like framework to build secure blockchain applications on top of Tendermint. +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 SDK design 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. +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. It is based on two major principles: -- **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. +- **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**: 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/). +- **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/). -_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._ +_Note: For now the Cosmos-SDK only exists in [Golang](https://golang.org/), which means that developers can only develop SDK modules in Golang. In the future, we expect that the SDK will be implemented in other programming languages. The Cosmos team will also financially support their development._ ## 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: -- Auth -- Token -- Governance -- Staking +#### Modules + +A `module` is a fundamental unit in the Cosmos-SDK. Each module is an extension to the BaseApp functionalities that defines its own transactions, handles its own state as well as the state transition logic. The Cosmos-SDK has all the necessary pre-built 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` - Defines a `BaseAccount` structure and how transaction signers are authenticated. +- `Bank` - Defines how coins (i.e cryptocurrencies) are transferred. +- `Governance` - Governance related specifications including proposals and voting. +- `Staking` - Proof of Stake related specifications including bonding and delegation transactions, inflation, fees, unbonding, etc. +- `IBC` - Defines the intereoperability of blockchain zones according to the specifications of the [IBC Protocol](https://cosmos.network/whitepaper#inter-blockchain-communication-ibc). - Handlers for messages and transactions -- REST and CLI sor secure user interactions +- REST and CLI for secure user interactions -Key directories of the SDK: +#### Directories -- `baseapp`: Defines the template for a basic application. Basically it implements the ABCI protocol so that your Cosmos-SDK application can communicate with the underlying Tendermint node. +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. - `server`: Rest server to communicate with the node. -- `examples`: Contains example on how to build a working application based on baseapp and modules +- `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`: 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. +- `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. ## Prerequisites @@ -59,5 +69,3 @@ Key directories of the SDK: ## Getting Started See the [documentation](https://cosmos-sdk.readthedocs.io). - - From c155a8212e4e921809b6d8a273564a73f2ef1d68 Mon Sep 17 00:00:00 2001 From: Federico Kunze Date: Sun, 8 Apr 2018 12:23:17 -0300 Subject: [PATCH 3/3] addressed Rige's comments --- README.md | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 218c4f920..ecafd1e28 100644 --- a/README.md +++ b/README.md @@ -21,46 +21,48 @@ master | [![CircleCI](https://circleci.com/gh/cosmos/cosmos-sdk/tree/master.s ## 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. +The Cosmos-SDK is a platform for building multi-asset Proof-of-Stake (PoS) blockchains, like the [Cosmos Hub](https://cosmos.network). It is both a library for building and securely interacting with blockchain applications. -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. +The goal of the Cosmos-SDK is to allow developers to easily create custom interoperable blockchain applications within the Cosmos Network without having to recreate common blockchain functionality, 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. 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. +- **Composability**: Anyone can create a module for the Cosmos-SDK and integrating the already-built modules is as simple as importing them into your blockchain application. -- **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/). +- **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 3rd party modules when building their own modules. Given that the Cosmos-SDK is an open framework and that we assume that some those modules may be malicious, we designed the SDK using object-capabilities (_ocaps_) based principles. In practice, this means that instead of having each module keep an access control list for 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. -_Note: For now the Cosmos-SDK only exists in [Golang](https://golang.org/), which means that developers can only develop SDK modules in Golang. In the future, we expect that the SDK will be implemented in other programming languages. The Cosmos team will also financially support their development._ + The capabilities of each `keeper` are defined by the module's developer, and 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. 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 developers can only develop SDK modules in Golang. In the future, we expect that the SDK will be implemented in other programming languages. Funding opportunities supported by the Tendermint team may be available eventually._ ## Application architecture #### Modules -A `module` is a fundamental unit in the Cosmos-SDK. Each module is an extension to the BaseApp functionalities that defines its own transactions, handles its own state as well as the state transition logic. The Cosmos-SDK has all the necessary pre-built 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: +The Cosmos-SDK has all the necessary pre-built modules to add functionality on top of a `BaseApp`, which is the template to build a blockchain dApp in Cosmos. In this context, a `module` is a fundamental unit in the Cosmos-SDK. Each module is an extension of the `BaseApp` functionalities that defines transactions, handles application state and the state transition logic. Each module also contains handlers for messages and transactions, as well as REST and CLI for secure user interactions. + +Some of the most important modules already integrated in the SDK are: + +- `Auth`: Defines a standard account structure (`BaseAccount`) and how transaction signers are authenticated. +- `Bank`: Defines how coins (i.e cryptocurrencies) are transferred. +- `Governance`: Governance related implementation including proposals and voting. +- `Staking`: Proof of Stake related implementation including bonding and delegation transactions, inflation, fees, unbonding, etc. +- `IBC`: Defines the intereoperability of blockchain zones according to the specifications of the [IBC Protocol](https://cosmos.network/whitepaper#inter-blockchain-communication-ibc). -- `Auth` - Defines a `BaseAccount` structure and how transaction signers are authenticated. -- `Bank` - Defines how coins (i.e cryptocurrencies) are transferred. -- `Governance` - Governance related specifications including proposals and voting. -- `Staking` - Proof of Stake related specifications including bonding and delegation transactions, inflation, fees, unbonding, etc. -- `IBC` - Defines the intereoperability of blockchain zones according to the specifications of the [IBC Protocol](https://cosmos.network/whitepaper#inter-blockchain-communication-ibc). -- Handlers for messages and transactions -- REST and CLI for secure user interactions #### Directories 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. -- `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. +- `baseapp`: Defines the template for a basic [ABCI ](https://cosmos.network/whitepaper#abci) application so that your Cosmos-SDK application can communicate with the underlying Tendermint node. +- `client`: CLI and REST server tooling. +- `server`: RPC server to communicate with the node. +- `examples`: Contains examples on how to build working standalone applications. +- `store`: Contains code for the multistore (_i.e._ state). Each module can create any number of `KVStores` (key-value stores) from the multistore. - `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. +- `x`(for e**X**tensions): Folder for storing the `BaseApp` module and all the already-built modules described in the previous section. ## Prerequisites