From c9a620d10746006f61fe4a73db0cfafbe3fb742e Mon Sep 17 00:00:00 2001 From: Zach Ramsay Date: Thu, 31 Aug 2017 13:33:46 -0400 Subject: [PATCH] docs: address moar comments & re-add (modified) inspiration --- README.md | 28 ++++++++++++++++++++++- docs/glossary.md | 8 +++---- docs/guide/counter/cmd/countercli/main.go | 16 +++++++------ docs/overview.md | 6 ++--- 4 files changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 1cf56c64ac..f47ab92a7a 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Branch | Tests | Coverage | Report Card 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) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/develop)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/develop) 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) | [![Go Report Card](https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk/tree/master)](https://goreportcard.com/report/github.com/cosmos/cosmos-sdk/tree/master) -The Cosmos SDK is the middleware platform which the [Cosmos](https://cosmos.network) HUB is constructed from. The HUB is a blockchain (or, internet of blockchains) in which the atom supply resides. The atos supply is defined at genesis and can change based on the rules of the HUB. +The Cosmos SDK is the middleware platform which the [Cosmos Hub](https://cosmos.network) is constructed from. The Hub is a blockchain (or, internet of blockchains) in which the Atom supply resides. The Atoms supply is defined at genesis and can change based on the rules of the Hub. Under the hood, the Cosmos SDK is an [ABCI application](https://github.com/tendermint/abci) designed to be used with the [Tendermint consensus engine](https://tendermint.com/) to form a Proof-of-Stake cryptocurrency. It also provides a general purpose framework for extending the feature-set of the cryptocurrency by implementing plugins. @@ -49,3 +49,29 @@ See the [install guide](/docs/guide/install.md) for more details. * See [more examples](https://github.com/cosmos/cosmos-academy) To deploy a testnet, see our [repository of deployment tools](https://github.com/tendermint/tools). + +# Inspiration + +The basic concept for this SDK comes from years of web development. A number of +patterns have arisen in that realm of software which enable people to build remote +servers with APIs remarkably quickly and with high stability. The +[ABCI](https://github.com/tendermint/abci) application interface is similar to +a web API (`DeliverTx` is like POST and `Query` is like GET while `SetOption` is like +the admin playing with the config file). Here are some patterns that might be +useful: + +* MVC - separate data model (storage) from business logic (controllers) +* Routers - easily direct each request to the appropriate controller +* Middleware - a series of wrappers that provide global functionality (like + authentication) to all controllers +* Modules (gems, package, etc) - developers can write a self-contained package + with a given set of functionality, which can be imported and reused in other + apps + +Also at play is the concept of different tables/schemas in databases, thus you can +keep the different modules safely separated and avoid any accidental (or malicious) +overwriting of data. + +Not all of these can be compare one-to-one in the blockchain world, but they do +provide inspiration for building orthogonal pieces that can easily be combined +into various applications. diff --git a/docs/glossary.md b/docs/glossary.md index dc6e641d3b..ba6bb72ec0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -21,9 +21,9 @@ Here, encoding and decoding operations are designed to operate with interfaces nested any amount times (like an onion!). There is one public `TxMapper` in the basecoin root package, and all modules can register their own transaction types there. This allows us to deserialize the entire transaction in one location -(even with types defined in other repos), to easily embed an arbitrary tx inside -another without specifying the type, and provide an automatic json representation -to provide to users (or apps) to inspect the chain. +(even with types defined in other repos), to easily embed an arbitrary transaction +inside another without specifying the type, and provide an automatic json +representation allowing for users (or apps) to inspect the chain. Note how we can wrap any other transaction, add a fee level, and not worry about the encoding in our module any more? @@ -163,7 +163,7 @@ then each transaction is handled by the appropriate module. ## Dispatcher We usually will want to have multiple modules working together, and need to -make sure the correct transactions get to the correct module. So we have the +make sure the correct transactions get to the correct module. So we have `coin` sending money, `roles` to create multi-sig accounts, and `ibc` for following other chains all working together without interference. diff --git a/docs/guide/counter/cmd/countercli/main.go b/docs/guide/counter/cmd/countercli/main.go index 184b222aa6..4bd49b99d7 100644 --- a/docs/guide/counter/cmd/countercli/main.go +++ b/docs/guide/counter/cmd/countercli/main.go @@ -12,6 +12,7 @@ import ( "github.com/cosmos/cosmos-sdk/client/commands/proxy" "github.com/cosmos/cosmos-sdk/client/commands/query" "github.com/cosmos/cosmos-sdk/client/commands/seeds" + txcmd "github.com/cosmos/cosmos-sdk/client/commands/txs" bcount "github.com/cosmos/cosmos-sdk/docs/guide/counter/cmd/countercli/commands" authcmd "github.com/cosmos/cosmos-sdk/modules/auth/commands" @@ -21,15 +22,16 @@ import ( noncecmd "github.com/cosmos/cosmos-sdk/modules/nonce/commands" ) -// BaseCli represents the base command when called without any subcommands -var BaseCli = &cobra.Command{ +// CounterCli represents the base command when called without any subcommands +var CounterCli = &cobra.Command{ Use: "countercli", - Short: "Light client for tendermint", - Long: `Basecli is an version of tmcli including custom logic to -present a nice (not raw hex) interface to the basecoin blockchain structure. + Short: "Example app built using the Cosmos SDK", + Long: `Countercli is a demo app that includes custom logic to +present a formatted interface to a custom blockchain structure. + +This is a useful tool and also serves to demonstrate how to configure +the Cosmos SDK to work for any custom ABCI app, see: -This is a useful tool, but also serves to demonstrate how one can configure -tmcli to work for any custom abci app. `, } diff --git a/docs/overview.md b/docs/overview.md index 96c6d68525..b773073797 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -34,7 +34,7 @@ the stack. Middleware components allow for code reusability and integrability. A standard set of middleware are provided and can be mix-and-matched with custom -middleware. Some of the [standardlibrary](stdlib.md) +middleware. Some of the [standard library](stdlib.md) middlewares provided in this package include: - Logging - Recovery @@ -47,7 +47,7 @@ middlewares provided in this package include: As a part of stack execution the state space provided to each middleware is isolated (see [Data Store](overview.md#data-store)). When executing the stack, -state-recovery check-points can be assigned for stack execution of `CheckTx` +state-recovery checkpoints can be assigned for stack execution of `CheckTx` or `DeliverTx`. This means, that all state changes will be reverted to the checkpoint state on failure when either being run as a part of `CheckTx` or `DeliverTx`. Example usage of the checkpoints is when we may want to deduct @@ -75,7 +75,7 @@ Store](overview.md#data-store)). ### Permission Each application is run in a sandbox to isolate security risks. When -interfacing between applications, if a one of those applications is compromised +interfacing between applications, if one of those applications is compromised the entire network should still be secure. This is achieved through actor permissioning whereby each chain, account, or application can provided a designated permission for the transaction context to perform a specific action.