sdk

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 11, 2017 License: Apache-2.0 Imports: 10 Imported by: 0

README

Cosmos SDK

banner

version API Reference Rocket.Chat license LoC Go Report Card

Branch Tests Coverage
develop CircleCI codecov
master CircleCI codecov

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

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

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

View Source 
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

View Source 
var TxMapper = data.NewMapper(Tx{})

Functions

This section is empty.

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 added in v0.8.0 

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 added in v0.8.0 

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 added in v0.8.0 

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

Ticker can be executed every block

type TickerFunc added in v0.8.0 

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

TickerFunc allows a function to implement the interface

func (TickerFunc) Tick added in v0.8.0 

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.

Source Files

View all Source files

Directories

Path Synopsis
Package app contains data structures that provide basic data storage functionality and act as a bridge between the abci interface and the internal sdk representations.
 Package app contains data structures that provide basic data storage functionality and act as a bridge between the abci interface and the internal sdk representations.
commands
Package commands contains any general setup/helpers valid for all subcommands
 Package commands contains any general setup/helpers valid for all subcommands
commands/auto
commands/commits
commands/keys
commands/proxy
commands/query
commands/rpc
commands/search
commands/txs
rest
nolint
 nolint
examples
basecoin/cmd/basecli
basecoin/cmd/basecoin
basecoin/cmd/baseserver
counter/cmd/counter
counter/cmd/countercli
counter/cmd/countercli/commands
counter/plugins/counter
eyes/cmd/eyes
eyes/cmd/eyescli
Package genesis provides some utility functions for parsing a standard genesis file to initialize your abci application.
 Package genesis provides some utility functions for parsing a standard genesis file to initialize your abci application.
modules
auth
nolint
 nolint
auth/commands
base
nolint
 nolint
base/commands
coin
nolint
 nolint
coin/commands
coin/rest
eyes
eyes/commands
fee
nolint
 nolint
fee/commands
ibc
ibc/commands
nonce
nolint
 nolint
nonce/commands
nonce/rest
roles
nolint
 nolint
roles/commands
roles/rest
server
commands
nolint
 nolint
nolint
 nolint
tests
tendermint
nolint
 nolint

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.