Merge pull request cosmos#333 from cosmos/docs

README makeover

Makefile

@@ -1,7 +1,7 @@
 PACKAGES=$(shell go list ./... | grep -v '/vendor/' | grep -v '_attic')
 BUILD_FLAGS = -ldflags "-X github.com/cosmos/cosmos-sdk/version.GitCommit=`git rev-parse --short HEAD`"
 
-all: check_tools get_vendor_deps build test install
+all: check_tools get_vendor_deps build test 
 
 ########################################
 ### Build
@@ -13,7 +13,6 @@ dist:
 	@bash publish/dist.sh
 	@bash publish/publish.sh
 
-
 ########################################
 ### Tools & dependencies
 

README.md

@@ -16,75 +16,41 @@ develop   | [![CircleCI](https://circleci.com/gh/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)
 
 
-!!!!!!!!!!!!!!!!!!!!!
+WARNING: the libraries are still undergoing breaking changes as we get better ideas and start building out the Apps.
 
-*THIS REPOSITORY IS UNDERGOING RAPID DEVELOPMENT AND NONE OF ITS INTERFACES ARE CONSIDERED STABLE.*
+**Note: Requires Go 1.9+**
 
-*USE AT YOUR OWN RISK.*
+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.
 
-**Note: Requires Go 1.8+**
+It is inspired by the routing and middleware model of many web application frameworks, and informed by years
+of wrestling with blockchain state machines. 
 
-The Cosmos SDK is the middleware platform that 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.
+The SDK is fast, safe, easy-to-use, and easy-to-reason-about.
+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.
 
-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.
+Applications in the Cosmos-SDK are defined in terms of a chain 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.
 
-This SDK affords you all the tools you need to rapidly develop
-robust blockchains and blockchain applications which are interoperable with The
-Cosmos Hub. It is a blockchain development 'starter-pack' of common blockchain
-modules while not enforcing their use thus giving maximum flexibility for
-application customization. For example, does your app require fees, how do you
-want to log messages, do you enable IBC, do you even have a cryptocurrency? In
-this way, the Cosmos SDK is the **Rails of cryptocurrencies**.
-
-Within this repository, the `basecoin` app serves as a reference implementation for how we build ABCI applications in Go, and is the framework in which we implement the [Cosmos Hub](https://cosmos.network). **It's easy to use, and doesn't require any forking** - just implement your plugin, import the libraries, and away you go with a full-stack blockchain and command line tool for transacting.
+For more details on the design goals, see the [Design Document]()
 
 ## Prerequisites
 
 * [golang](https://golang.org/doc/install)
 
-## Installation
-
-```
-go get -u github.com/cosmos/cosmos-sdk/cmd/basecoin
-```
-
-See the [install guide](/docs/guide/install.md) for more details.
-
-## Guides
-
-* Getting started with the [Basecoin basics](/docs/guide/basecoin-basics.md)
-* Learn to [use the plugin system](/docs/guide/basecoin-plugins.md)
-* More features of the [Basecoin tool](/docs/guide/basecoin-tool.md)
-* Learn how to use [Inter-Blockchain Communication (IBC)](/docs/guide/ibc.md)
-* 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.
+## Getting Started
 
-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.
+The main application built with the Cosmos-SDK is the Cosmos Hub.
+Setup a local Cosmos Hub blockchain by following [this guide]().
+Connect to a testnet by following [this guide]().
+Learn how to build your own SDK application [here]().

circle.yml

@@ -17,5 +17,5 @@ dependencies:
 
 test:
   override:
-    - "cd $REPO && make all"
+    - "cd $REPO && make get_tools && make all"
     - ls $GOPATH/bin

docs/design.md

@@ -0,0 +1,38 @@
+## Design Goals
+
+More details about the design goals of particular components follows.
+
+### Store
+
+- Fast balanced dynamic Merkle tree for storing application state
+- Support multiple Merkle tree backends in a single store 
+    - allows using Ethereum Patricia Trie and Tendermint IAVL in same app
+- Support iteration
+- Provide caching for intermediate state during execution of blocks and transactions (including for iteration)
+- Retain some amount of recent historical state
+- Allow many kinds of proofs (exists, absent, range, etc.) on current and retained historical state
+
+### ABCI Application
+
+- Simple connector between developer's application logic and the ABCI protocol
+- Simplify discrepancy between DeliverTx and CheckTx
+- Handles ABCI handshake logic and historical state
+- Provide simple hooks to BeginBlock and EndBlock 
+
+### Transaction Processing
+
+- Transactions consist of composeable messages 
+- Processing via series of handlers that handle authenticate, deduct fees, transfer coins, etc.
+- Developers control tx encoding
+    - Default go-wire
+    - Must be able to write eg. Ethermint using the SDK with Ethereum-native transaction encoding
+- Handler access to the store is restricted via capabilities and interfaces
+- Context object holds
+
+### Data Types
+
+- Default Ethereum-style Account 
+- Default multi-asset Coins
+
+
+

docs/web-inspriation.md

@@ -0,0 +1,29 @@
+
+
+TODO: write a blog post ...
+
+# 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.

x/auth/account_test.go

@@ -18,6 +18,10 @@ func TestBaseAccount(t *testing.T) {
 
 	acc := NewBaseAccountWithAddress(addr)
 
+	// need a codec for marshaling
+	codec := wire.NewCodec()
+	crypto.RegisterWire(codec)
+
 	err := acc.SetPubKey(pub)
 	assert.Nil(t, err)
 	assert.Equal(t, pub, acc.GetPubKey())
@@ -32,15 +36,15 @@ func TestBaseAccount(t *testing.T) {
 	assert.Nil(t, err)
 	assert.Equal(t, seq, acc.GetSequence())
 
-	b, err := wire.MarshalBinary(acc)
+	b, err := codec.MarshalBinary(acc)
 	assert.Nil(t, err)
 
 	var acc2 BaseAccount
-	err = wire.UnmarshalBinary(b, &acc2)
+	err = codec.UnmarshalBinary(b, &acc2)
 	assert.Nil(t, err)
 	assert.Equal(t, acc, acc2)
 
 	acc2 = BaseAccount{}
-	err = wire.UnmarshalBinary(b[:len(b)/2], &acc2)
+	err = codec.UnmarshalBinary(b[:len(b)/2], &acc2)
 	assert.NotNil(t, err)
 }