sdk

README

Cosmos SDK

Branch	Tests	Coverage
develop
master

!!!!!!!!!!!!!!!!!!!!!

THIS REPOSITORY IS UNDERGOING RAPID DEVELOPMENT AND NONE OF ITS INTERFACES ARE CONSIDERED STABLE.

USE AT YOUR OWN RISK.

!!!!!!!!!!!!!!!!!!!!!

Note: Requires Go 1.8+

The Cosmos SDK is the middleware platform that the Cosmos Hub 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 designed to be used with the Tendermint consensus engine 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.

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. 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.

Prerequisites

• golang

Installation and Documentation

go get -u github.com/cosmos/cosmos-sdk/cmd/basecoin

See the Cosmos SDK Documentation for complete installation details and usage documentation. To deploy a testnet, see our repository of deployment 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 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.

Documentation

Index

• Constants
• Variables
• type Actor
  • func NewActor(app string, addr []byte) Actor
  • func (a Actor) Bytes() []byte
  • func (a Actor) Empty() bool
  • func (a Actor) Equals(b Actor) bool
  • func (a Actor) String() string
  • func (a Actor) WithChain(chainID string) (b Actor)
• type Actors
  • func (a Actors) AllHaveChain(chainID string) bool
• type ByAll
  • func (a ByAll) Len() int
  • func (a ByAll) Less(i, j int) bool
  • func (a ByAll) Swap(i, j int)
• type CheckResult
  • func NewCheck(gasAllocated int64, log string) CheckResult
  • func (c CheckResult) GetData() data.Bytes
  • func (c CheckResult) ToABCI() abci.ResponseCheckTx
• type Checker
• type CheckerFunc
  • func (c CheckerFunc) CheckTx(ctx Context, store state.SimpleDB, tx Tx) (CheckResult, error)
• type Context
• type Deliver
• type DeliverFunc
  • func (c DeliverFunc) DeliverTx(ctx Context, store state.SimpleDB, tx Tx) (DeliverResult, error)
• type DeliverResult
  • func (d DeliverResult) GetData() data.Bytes
  • func (d DeliverResult) ToABCI() abci.ResponseDeliverTx
• type Handler
• type InitStateFunc
  • func (c InitStateFunc) InitState(l log.Logger, store state.SimpleDB, module, key, value string) (string, error)
• type InitStater
• type InitValidateFunc
  • func (c InitValidateFunc) InitValidate(l log.Logger, store state.SimpleDB, vals []*abci.Validator)
• type InitValidater
• type Named
• type NopCheck
  • func (_ NopCheck) CheckTx(Context, state.SimpleDB, Tx) (r CheckResult, e error)
• type NopDeliver
  • func (_ NopDeliver) DeliverTx(Context, state.SimpleDB, Tx) (r DeliverResult, e error)
• type NopInitState
  • func (_ NopInitState) InitState(log.Logger, state.SimpleDB, string, string, string) (string, error)
• type NopInitValidate
  • func (_ NopInitValidate) InitValidate(log log.Logger, store state.SimpleDB, vals []*abci.Validator)
• type Result
• type Ticker
• type TickerFunc
  • func (t TickerFunc) Tick(ctx Context, store state.SimpleDB) ([]*abci.Validator, error)
• type Tx
  • func LoadTx(bin []byte) (tx Tx, err error)
  • func (h Tx) Empty() bool
  • func (t Tx) GetKind() (string, error)
  • func (t Tx) GetLayer() TxLayer
  • func (t Tx) GetMod() (string, error)
  • func (t Tx) IsLayer() bool
  • func (h Tx) MarshalJSON() ([]byte, error)
  • func (h *Tx) UnmarshalJSON(data []byte) (err error)
  • func (h Tx) Unwrap() TxInner
• type TxInner
• type TxLayer

Constants

const (
	// ModuleNameBase is the module name for internal functionality
	ModuleNameBase = "base"
	// ChainKey is the option key for setting the chain id
	ChainKey = "chain_id"
)

Variables

var TxMapper = data.NewMapper(Tx{})

Types

type Actor

type Actor struct {
	ChainID string     `json:"chain"` // this is empty unless it comes from a different chain
	App     string     `json:"app"`   // the app that the actor belongs to
	Address data.Bytes `json:"addr"`  // arbitrary app-specific unique id
}

Actor abstracts any address that can authorize actions, hold funds, or initiate any sort of transaction.

It doesn't just have to be a pubkey on this chain, it could stem from another app (like multi-sig account), or even another chain (via IBC)

func NewActor

func NewActor(app string, addr []byte) Actor

NewActor - create a new actor

func (Actor) Bytes

func (a Actor) Bytes() []byte

Bytes makes a binary coding, useful for turning this into a key in the store

func (Actor) Empty

func (a Actor) Empty() bool

Empty checks if the actor is not initialized

func (Actor) Equals

func (a Actor) Equals(b Actor) bool

Equals checks if two actors are the same

func (Actor) String

func (a Actor) String() string

String provides a human-readable representation of an actor

func (Actor) WithChain

func (a Actor) WithChain(chainID string) (b Actor)

WithChain creates a copy of the actor with a different chainID

type Actors

type Actors []Actor

func (Actors) AllHaveChain

func (a Actors) AllHaveChain(chainID string) bool

type ByAll

type ByAll []Actor

ByAll implements sort.Interface for []Actor. It sorts be the ChainID, followed by the App, followed by the Address

func (ByAll) Len

func (a ByAll) Len() int

func (ByAll) Less

func (a ByAll) Less(i, j int) bool

func (ByAll) Swap

func (a ByAll) Swap(i, j int)

type CheckResult

type CheckResult struct {
	Data data.Bytes
	Log  string
	// GasAllocated is the maximum units of work we allow this tx to perform
	GasAllocated int64
	// GasPayment is the total fees for this tx (or other source of payment)
	GasPayment int64
}

CheckResult captures any non-error abci result to make sure people use error for error cases

func NewCheck

func NewCheck(gasAllocated int64, log string) CheckResult

NewCheck sets the gas used and the response data but no more info these are the most common info needed to be set by the Handler

func (CheckResult) GetData

func (c CheckResult) GetData() data.Bytes

func (CheckResult) ToABCI

func (c CheckResult) ToABCI() abci.ResponseCheckTx

type Checker

type Checker interface {
	CheckTx(ctx Context, store state.SimpleDB, tx Tx) (CheckResult, error)
}

Checker verifies there are valid fees and estimates work

type CheckerFunc

type CheckerFunc func(Context, state.SimpleDB, Tx) (CheckResult, error)

CheckerFunc (like http.HandlerFunc) is a shortcut for making wrappers

func (CheckerFunc) CheckTx

func (c CheckerFunc) CheckTx(ctx Context, store state.SimpleDB, tx Tx) (CheckResult, error)

type Context

type Context interface {
	// context.Context
	log.Logger
	WithPermissions(perms ...Actor) Context
	HasPermission(perm Actor) bool
	GetPermissions(chain, app string) []Actor
	IsParent(ctx Context) bool
	Reset() Context
	ChainID() string
	BlockHeight() int64
}

Context is an interface, so we can implement "secure" variants that rely on private fields to control the actions

type Deliver

type Deliver interface {
	DeliverTx(ctx Context, store state.SimpleDB, tx Tx) (DeliverResult, error)
}

Deliver performs the tx once it makes it in the block

type DeliverFunc

type DeliverFunc func(Context, state.SimpleDB, Tx) (DeliverResult, error)

DeliverFunc (like http.HandlerFunc) is a shortcut for making wrappers

func (DeliverFunc) DeliverTx

func (c DeliverFunc) DeliverTx(ctx Context, store state.SimpleDB, tx Tx) (DeliverResult, error)

type DeliverResult

type DeliverResult struct {
	Data    data.Bytes
	Log     string
	Diff    []*abci.Validator
	Tags    []*abci.KVPair
	GasUsed int64 // unused
}

DeliverResult captures any non-error abci result to make sure people use error for error cases

func (DeliverResult) GetData

func (d DeliverResult) GetData() data.Bytes

func (DeliverResult) ToABCI

func (d DeliverResult) ToABCI() abci.ResponseDeliverTx

type Handler

type Handler interface {
	// Checker verifies there are valid fees and estimates work
	Checker
	// Deliver performs the tx once it makes it in the block
	Deliver
	// InitStater sets state from the genesis file
	InitStater
	// InitValidater sets the initial validator set
	InitValidater
	// Named ensures there is a name for the item
	Named
}

Handler is anything that processes a transaction

type InitStateFunc

type InitStateFunc func(log.Logger, state.SimpleDB, string, string, string) (string, error)

InitStateFunc (like http.HandlerFunc) is a shortcut for making wrappers

func (InitStateFunc) InitState

func (c InitStateFunc) InitState(l log.Logger, store state.SimpleDB, module, key, value string) (string, error)

type InitStater

type InitStater interface {
	InitState(l log.Logger, store state.SimpleDB, module, key, value string) (string, error)
}

InitStater sets state from the genesis file

type InitValidateFunc

type InitValidateFunc func(log.Logger, state.SimpleDB, []*abci.Validator)

InitValidateFunc (like http.HandlerFunc) is a shortcut for making wrappers

func (InitValidateFunc) InitValidate

func (c InitValidateFunc) InitValidate(l log.Logger, store state.SimpleDB, vals []*abci.Validator)

type InitValidater

type InitValidater interface {
	InitValidate(log log.Logger, store state.SimpleDB, vals []*abci.Validator)
}

InitValidater sets the initial validator set

type Named

type Named interface {
	Name() string
}

Named ensures there is a name for the item

type NopCheck

type NopCheck struct{}

placeholders holders

func (NopCheck) CheckTx

func (_ NopCheck) CheckTx(Context, state.SimpleDB, Tx) (r CheckResult, e error)

type NopDeliver

type NopDeliver struct{}

func (NopDeliver) DeliverTx

func (_ NopDeliver) DeliverTx(Context, state.SimpleDB, Tx) (r DeliverResult, e error)

type NopInitState

type NopInitState struct{}

func (NopInitState) InitState

func (_ NopInitState) InitState(log.Logger, state.SimpleDB, string, string, string) (string, error)

type NopInitValidate

type NopInitValidate struct{}

func (NopInitValidate) InitValidate

func (_ NopInitValidate) InitValidate(log log.Logger, store state.SimpleDB, vals []*abci.Validator)

type Result

type Result interface {
	GetData() data.Bytes
}

type Ticker

type Ticker interface {
	Tick(Context, state.SimpleDB) ([]*abci.Validator, error)
}

Ticker can be executed every block

type TickerFunc

type TickerFunc func(Context, state.SimpleDB) ([]*abci.Validator, error)

TickerFunc allows a function to implement the interface

func (TickerFunc) Tick

func (t TickerFunc) Tick(ctx Context, store state.SimpleDB) ([]*abci.Validator, error)

type Tx

type Tx struct {
	TxInner "json:\"unwrap\""
}

func LoadTx

func LoadTx(bin []byte) (tx Tx, err error)

LoadTx parses a tx from data

func (Tx) Empty

func (h Tx) Empty() bool

func (Tx) GetKind

func (t Tx) GetKind() (string, error)

TODO: put this functionality into go-data in a cleaner and more efficient way

func (Tx) GetLayer

func (t Tx) GetLayer() TxLayer

func (Tx) GetMod

func (t Tx) GetMod() (string, error)

func (Tx) IsLayer

func (t Tx) IsLayer() bool

func (Tx) MarshalJSON

func (h Tx) MarshalJSON() ([]byte, error)

func (*Tx) UnmarshalJSON

func (h *Tx) UnmarshalJSON(data []byte) (err error)

func (Tx) Unwrap

func (h Tx) Unwrap() TxInner

Unwrap recovers the concrete interface safely (regardless of levels of embeds)

type TxInner

type TxInner interface {
	Wrap() Tx

	// ValidateBasic should be a stateless check and just verify that the
	// tx is properly formated (required strings not blank, signatures exist, etc.)
	// this can also be run on the client-side for better debugging before posting a tx
	ValidateBasic() error
}

TxInner is the interface all concrete transactions should implement.

It adds bindings for clean un/marhsaling of the various implementations both as json and binary, as well as some common functionality to move them.

+gen wrapper:"Tx"

type TxLayer

type TxLayer interface {
	TxInner
	Next() Tx
}

TxLayer provides a standard way to deal with "middleware" tx, That add context to an embedded tx.