Documentation ¶
Overview ¶
Package weave defines all common interfaces to weave together the various subpackages, as well as implementations of some of the simpler components (when interfaces would be too much overhead).
We pass context through context.Context between app, middleware, and handlers. To do so, weave defines some common keys to store info, such as block height and chain id. Each extension, such as auth, may add its own keys to enrich the context with specific data.
There should exist two functions for every XYZ of type T that we want to support in Context:
WithXYZ(Context, T) Context GetXYZ(Context) (val T, ok bool)
WithXYZ may error/panic if the value was previously set to avoid lower-level modules overwriting the value (eg. height, header)
Index ¶
- Constants
- Variables
- func CheckOrError(result CheckResult, err error) abci.ResponseCheckTx
- func CheckTxError(err error) abci.ResponseCheckTx
- func DeliverOrError(result DeliverResult, err error) abci.ResponseDeliverTx
- func DeliverTxError(err error) abci.ResponseDeliverTx
- func GetChainID(ctx Context) string
- func GetHeader(ctx Context) (abci.Header, bool)
- func GetHeight(ctx Context) (int64, bool)
- func GetLogger(ctx Context) log.Logger
- func GetPath(tx Tx) string
- func Version() string
- type Address
- type Batch
- type CacheableKVStore
- type CheckResult
- type Checker
- type CommitID
- type CommitKVStore
- type Context
- type Decorator
- type DeliverResult
- type Deliverer
- type Handler
- type Initializer
- type Iterator
- type KVCacheWrap
- type KVStore
- type Marshaller
- type Model
- type Msg
- type Options
- type Persistent
- type QueryHandler
- type QueryRegister
- type QueryRouter
- type ReadOnlyKVStore
- type Registry
- type SetDeleter
- type TickResult
- type Ticker
- type Tx
- type TxDecoder
Constants ¶
const ( // KeyQueryMod means to query for exact match (key) KeyQueryMod = "" // PrefixQueryMod means to query for anything with this prefix PrefixQueryMod = "prefix" // RangeQueryMod means to expect complex range query // TODO: implement RangeQueryMod = "range" )
const Fix = 0
Fix is the patch number (updated on bugfix releases)
const Maj = 0
Maj is the major version number (updated on breaking release)
const Min = 2
Min is the minor version number (updated on minor releases)
const Suffix = ""
Suffix used when not a tagged release (eg. -dev, -alpha, -beta, etc)
Variables ¶
var ( // DefaultLogger is used for all context that have not // set anything themselves DefaultLogger = log.NewNopLogger() // IsValidChainID is the RegExp to ensure valid chain IDs IsValidChainID = regexp.MustCompile(`^[a-zA-Z0-9_\-]{6,20}$`).MatchString )
var ( // AddressLength is the length of all addresses // You can modify it in init() before any addresses are calculated, // but it must not change during the lifetime of the kvstore AddressLength = 20 )
var GitCommit = ""
GitCommit set by build flags
Functions ¶
func CheckOrError ¶
func CheckOrError(result CheckResult, err error) abci.ResponseCheckTx
CheckOrError returns an abci response for CheckTx, converting the error message if present, or using the successful CheckResult
func CheckTxError ¶
func CheckTxError(err error) abci.ResponseCheckTx
CheckTxError converts any error into a abci.ResponseCheckTx, preserving as much info as possible if it was already a TMError
func DeliverOrError ¶
func DeliverOrError(result DeliverResult, err error) abci.ResponseDeliverTx
DeliverOrError returns an abci response for DeliverTx, converting the error message if present, or using the successful DeliverResult
func DeliverTxError ¶
func DeliverTxError(err error) abci.ResponseDeliverTx
DeliverTxError converts any error into a abci.ResponseDeliverTx, preserving as much info as possible if it was already a TMError
func GetChainID ¶
GetChainID returns the current chain id panics if chain id not already set (should never happen)
func GetHeader ¶
GetHeader returns the current block header ok is false if no header set in this Context
func GetHeight ¶
GetHeight returns the current block height ok is false if no height set in this Context
Types ¶
type Address ¶
type Address []byte
Address represents a collision-free, one-way digest of data (usually a public key) that can be used to identify a signer
It will be of size AddressLength
func MustObjAddress ¶
func MustObjAddress(obj Marshaller) Address
MustObjAddress is like ObjAddress, but panics instead of returning errors. Only use when you control the obj being passed in.
func NewAddress ¶
NewAddress hashes and truncates into the proper size
func ObjAddress ¶
func ObjAddress(obj Marshaller) (Address, error)
ObjAddress takes the address of an object
func (Address) MarshalJSON ¶
MarshalJSON provides a hex representation for JSON, to override the standard base64 []byte encoding
func (Address) ToString ¶ added in v0.2.0
ToString returns a human readable string. Currently hex, may move to bech32
func (*Address) UnmarshalJSON ¶
UnmarshalJSON parses JSON in hex representation, to override the standard base64 []byte encoding
type Batch ¶
type Batch interface { SetDeleter Write() }
Batch can write multiple ops atomically to an underlying KVStore
type CacheableKVStore ¶
type CacheableKVStore interface { KVStore CacheWrap() KVCacheWrap }
CacheableKVStore is a KVStore that supports CacheWrapping
CacheWrap() should not return a Committer, since Commit() on cache-wraps make no sense.
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) ToABCI ¶
func (c CheckResult) ToABCI() abci.ResponseCheckTx
ToABCI converts our internal type into an abci response
type Checker ¶
type Checker interface {
Check(ctx Context, store KVStore, tx Tx) (CheckResult, error)
}
Checker is a subset of Handler to verify the validity of a transaction. It is its own interface to allow better type controls in the next arguments in Decorator
type CommitKVStore ¶
type CommitKVStore interface { // Get returns the value at last committed state // returns nil iff key doesn't exist. Panics on nil key. Get(key []byte) []byte // Get a CacheWrap to perform actions // TODO: add Batch to atomic writes and efficiency // invisibly inside this CacheWrap??? CacheWrap() KVCacheWrap // Commit the next version to disk, and returns info Commit() CommitID // LoadLatestVersion loads the latest persisted version. // If there was a crash during the last commit, it is guaranteed // to return a stable state, even if older. LoadLatestVersion() error // LatestVersion returns info on the latest version saved to disk LatestVersion() CommitID }
CommitKVStore is a root store that can make atomic commits to disk. We modify it in batch by getting a CacheWrap() and then Write(). Commit() will persist all changes to disk
This store should also be able to return merkle proofs for any committed state.
type Context ¶
Context is just an alias for the standard implementation. We use functions to extend it to our domain
func WithChainID ¶
WithChainID sets the chain id for the Context. panics if called with chain id already set
func WithHeader ¶
WithHeader sets the block header for the Context. panics if called with header already set
func WithHeight ¶
WithHeight sets the block height for the Context. panics if called with height already set
func WithLogInfo ¶
WithLogInfo accepts keyvalue pairs, and returns another context like this, after passing all the keyvals to the Logger
type Decorator ¶
type Decorator interface { Check(ctx Context, store KVStore, tx Tx, next Checker) (CheckResult, error) Deliver(ctx Context, store KVStore, tx Tx, next Deliverer) (DeliverResult, error) }
Decorator wraps a Handler to provide common functionality like authentication, or fee-handling, to many Handlers
type DeliverResult ¶
type DeliverResult struct { Data data.Bytes Log string Diff []abci.Validator Tags []common.KVPair GasUsed int64 // unused }
DeliverResult captures any non-error abci result to make sure people use error for error cases
func (DeliverResult) ToABCI ¶
func (d DeliverResult) ToABCI() abci.ResponseDeliverTx
ToABCI converts our internal type into an abci response
type Deliverer ¶
type Deliverer interface {
Deliver(ctx Context, store KVStore, tx Tx) (DeliverResult, error)
}
Deliverer is a subset of Handler to execute a transaction. It is its own interface to allow better type controls in the next arguments in Decorator
type Handler ¶
Handler is a core engine that can process a few specific messages This could represent "coin transfer", or "bonding stake to a validator"
type Initializer ¶
Initializer implementations are used to initialize extensions from genesis file contents
type Iterator ¶
type Iterator interface { // Valid returns whether the current position is valid. // Once invalid, an Iterator is forever invalid. Valid() bool // Next moves the iterator to the next sequential key in the database, as // defined by order of iteration. // // If Valid returns false, this method will panic. Next() // Key returns the key of the cursor. // If Valid returns false, this method will panic. // CONTRACT: key readonly []byte Key() (key []byte) // Value returns the value of the cursor. // If Valid returns false, this method will panic. // CONTRACT: value readonly []byte Value() (value []byte) // Close releases the Iterator. Close() }
Iterator allows us to access a set of items within a range of keys. These may all be preloaded, or loaded on demand.
Usage: var itr Iterator = ... defer itr.Close() for ; itr.Valid(); itr.Next() { k, v := itr.Key(); itr.Value() // ... }
type KVCacheWrap ¶
type KVCacheWrap interface { // CacheableKVStore allows us to use this Cache recursively CacheableKVStore // Write syncs with the underlying store. Write() // Discard invalidates this CacheWrap and releases all data Discard() }
KVCacheWrap allows us to maintain a scratch-pad of uncommitted data that we can view with all queries.
At the end, call Write to use the cached data, or Discard to drop it.
type KVStore ¶
type KVStore interface { ReadOnlyKVStore SetDeleter // NewBatch returns a batch that can write multiple ops atomically NewBatch() Batch }
KVStore is a simple interface to get/set data
For simplicity, we require all backing stores to implement this interface. They *may* implement other methods as well, but at least these are required.
type Marshaller ¶
Marshaller is anything that can be represented in binary
Marshall may validate the data before serializing it and unless you previously validated the struct, errors should be expected.
type Msg ¶
type Msg interface { Persistent // Return the message path. // This is used by the Router to locate the proper Handler. // Msg should be created alongside the Handler that corresponds to them. // // Multiple types may have the same value, and will end up at the // same Handler. // // Must be alphanumeric [0-9A-Za-z_\-]+ Path() string }
Msg is message for the blockchain to take an action (Make a state transition). It is just the request, and must be validated by the Handlers. All authentication information is in the wrapping Tx.
type Options ¶
type Options map[string]json.RawMessage
Options are the app options Each extension can look up it's key and parse the json as desired
func (Options) ReadOptions ¶
ReadOptions reads the values stored under a given key, and parses the json into the given obj. Returns an error if it cannot parse. Noop and no error if key is missing
type Persistent ¶
type Persistent interface { Marshaller Unmarshal([]byte) error }
Persistent supports Marshal and Unmarshal
This is separated from Marshal, as this almost always requires a pointer, and functions that only need to marshal bytes can use the Marshaller interface to access non-pointers.
As with Marshaller, this may do internal validation on the data and errors should be expected.
type QueryHandler ¶ added in v0.2.0
type QueryHandler interface {
Query(db ReadOnlyKVStore, mod string, data []byte) ([]Model, error)
}
QueryHandler is anything that can process ABCI queries
type QueryRegister ¶ added in v0.2.0
type QueryRegister func(QueryRouter)
QueryRegister is a function that adds some handlers to this router
type QueryRouter ¶ added in v0.2.0
type QueryRouter struct {
// contains filtered or unexported fields
}
QueryRouter allows us to register many query handlers to different paths and then direct each query to the proper handler.
Minimal interface modeled after net/http.ServeMux
func NewQueryRouter ¶ added in v0.2.0
func NewQueryRouter() QueryRouter
NewQueryRouter initializes a QueryRouter with no routes
func (QueryRouter) Handler ¶ added in v0.2.0
func (r QueryRouter) Handler(path string) QueryHandler
Handler returns the registered Handler for this path. If no path is found, returns a noSuchPath Handler Always returns a non-nil Handler
func (QueryRouter) Register ¶ added in v0.2.0
func (r QueryRouter) Register(path string, h QueryHandler)
Register adds a new Handler for the given path. panics if another Handler was already registered
func (QueryRouter) RegisterAll ¶ added in v0.2.0
func (r QueryRouter) RegisterAll(qr ...QueryRegister)
RegisterAll registers a number of QueryRegister at once
type ReadOnlyKVStore ¶
type ReadOnlyKVStore interface { // Get returns nil iff key doesn't exist. Panics on nil key. Get(key []byte) []byte // Has checks if a key exists. Panics on nil key. Has(key []byte) bool // Iterator over a domain of keys in ascending order. End is exclusive. // Start must be less than end, or the Iterator is invalid. // CONTRACT: No writes may happen within a domain while an iterator exists over it. Iterator(start, end []byte) Iterator // ReverseIterator over a domain of keys in descending order. End is exclusive. // Start must be greater than end, or the Iterator is invalid. // CONTRACT: No writes may happen within a domain while an iterator exists over it. ReverseIterator(start, end []byte) Iterator }
ReadOnlyKVStore is a simple interface to query data.
type SetDeleter ¶
type SetDeleter interface { Set(key, value []byte) // CONTRACT: key, value readonly []byte Delete(key []byte) // CONTRACT: key readonly []byte }
SetDeleter is a minimal interface for writing, Unifying KVStore and Batch
type TickResult ¶
TickResult allows the Ticker to modify the validator set
type Ticker ¶
type Ticker interface {
Tick(ctx Context, store KVStore) (TickResult, error)
}
Ticker is a method that is called the beginning of every block, which can be used to perform periodic or delayed tasks
type Tx ¶
type Tx interface { Persistent // GetMsg returns the action we wish to communicate GetMsg() (Msg, error) }
Tx represent the data sent from the user to the chain. It includes the actual message, along with information needed to authenticate the sender (cryptographic signatures), and anything else needed to pass through middleware.
Each Application must define their own tx type, which embeds all the middlewares that we wish to use. auth.SignedTx and token.FeeTx are common interfaces that many apps will wish to support.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package app is a generated protocol buffer package.
|
Package app is a generated protocol buffer package. |
Package crypto is a generated protocol buffer package.
|
Package crypto is a generated protocol buffer package. |
examples
|
|
errors
package main demonstrates how we can print out our TMErrors meant for `go run .../demo.go`
|
package main demonstrates how we can print out our TMErrors meant for `go run .../demo.go` |
mycoind/app
Package app contains standard implementations of a number of components.
|
Package app contains standard implementations of a number of components. |
mycoind/commands
Package commands has integration tests of the mycoind application.
|
Package commands has integration tests of the mycoind application. |
Package orm provides an easy to use db wrapper Break state space into prefixed sections called Buckets.
|
Package orm provides an easy to use db wrapper Break state space into prefixed sections called Buckets. |
Package x is a generated protocol buffer package.
|
Package x is a generated protocol buffer package. |
cash
Package cash is a generated protocol buffer package.
|
Package cash is a generated protocol buffer package. |
sigs
Package sigs is a generated protocol buffer package.
|
Package sigs is a generated protocol buffer package. |