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

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

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.

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
nolint
nolint
examples
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 Package auth contains generic Signable implementations that can be used by your application or tests to handle authentication needs.
nolint Package auth contains generic Signable implementations that can be used by your application or tests to handle authentication needs.
base
nolint
nolint
coin
nolint
nolint
fee
nolint
nolint
ibc
nonce
nolint Package nonce - This module allows replay protection to be added to process stack.
nolint Package nonce - This module allows replay protection to be added to process stack.
roles
nolint
nolint
server
nolint nolint
nolint nolint
nolint
nolint
tests
nolint
nolint

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL