Version: v0.2201.11 Latest Latest

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

Go to latest
Published: Aug 29, 2022 License: Apache-2.0 Imports: 42 Imported by: 3



Package api implements the API between Oasis ABCI application and Oasis core.



View Source
const BackendName = "tendermint"

BackendName is the consensus backend name.

View Source
const (
	// LogEventPeerExchangeDisable is a log event that indicates that
	// Tendermint's peer exchange has been disabled.
	LogEventPeerExchangeDisabled = "tendermint/peer_exchange_disabled"


View Source
var (
	// ErrGasOverflow is the error returned if the gas counter would
	// overflow.
	ErrGasOverflow = errors.New("gas overflow")
	// ErrOutOfGas is the error returned if the caller is out of gas.
	ErrOutOfGas = errors.New("out of gas")
View Source
var ErrNoState = errors.New("tendermint: no state available (app not registered?)")

ErrNoState is the error returned when state is nil.

View Source
var ErrNoSubscribers = errors.New("no subscribers to given message kind")

ErrNoSubscribers is the error returned when publishing a message that noone is subscribed to.

View Source
var MessageStateSyncCompleted = messageKind(0)

MessageStateSyncCompleted is the message kind for when the node successfully performs a state sync. The message itself is nil.


func EventTypeForApp

func EventTypeForApp(eventApp string) string

EventTypeForApp generates the ABCI event type for events belonging to the specified App.

func GetTendermintGenesisDocument

func GetTendermintGenesisDocument(provider genesis.Provider) (*tmtypes.GenesisDoc, error)

GetTendermintGenesisDocument returns the Tendermint genesis document corresponding to the Oasis genesis document specified by the given genesis provider.

func IsUnavailableStateError

func IsUnavailableStateError(err error) bool

IsUnavailableStateError returns true if any error in err's chain is an unavailable state error.

func NewBlock

func NewBlock(blk *tmtypes.Block) *consensus.Block

NewBlock creates a new consensus.Block from a Tendermint block.

func NodeToP2PAddr

func NodeToP2PAddr(n *node.Node) (*tmp2p.NetAddress, error)

NodeToP2PAddr converts an Oasis node descriptor to a tendermint p2p address book entry.

func PublicKeyToValidatorUpdate

func PublicKeyToValidatorUpdate(id signature.PublicKey, power int64) types.ValidatorUpdate

PublicKeyToValidatorUpdate converts an Oasis node public key to a tendermint validator update.

func QueryForApp

func QueryForApp(eventApp string) tmpubsub.Query

QueryForApp generates a tmquery.Query for events belonging to the specified App.

func UnavailableStateError

func UnavailableStateError(err error) error

UnavailableStateError wraps an error in an unavailable state error.


type Application

type Application interface {

	// Name returns the name of the Application.
	Name() string

	// ID returns the unique identifier of the application.
	ID() uint8

	// Methods returns the list of supported methods.
	Methods() []transaction.MethodName

	// Blessed returns true iff the Application should be considered
	// "blessed", and able to alter the validation set and handle the
	// access control related standard ABCI queries.
	// Only one Application instance may be Blessed per multiplexer
	// instance.
	Blessed() bool

	// Dependencies returns the names of applications that the application
	// depends on.
	Dependencies() []string

	// QueryFactory returns an application-specific query factory that
	// can be used to construct new queries at specific block heights.
	QueryFactory() interface{}

	// OnRegister is the function that is called when the Application
	// is registered with the multiplexer instance.
	OnRegister(ApplicationState, MessageDispatcher)

	// OnCleanup is the function that is called when the ApplicationServer
	// has been halted.

	// ExecuteTx executes a transaction.
	ExecuteTx(*Context, *transaction.Transaction) error

	// InitChain initializes the blockchain with validators and other
	// info from TendermintCore.
	// Note: Errors are irrecoverable and will result in a panic.
	InitChain(*Context, tmabcitypes.RequestInitChain, *genesis.Document) error

	// BeginBlock signals the beginning of a block.
	// Returned tags will be added to the current block.
	// Note: Errors are irrecoverable and will result in a panic.
	BeginBlock(*Context, tmabcitypes.RequestBeginBlock) error

	// EndBlock signals the end of a block, returning changes to the
	// validator set.
	// Note: Errors are irrecoverable and will result in a panic.
	EndBlock(*Context, tmabcitypes.RequestEndBlock) (tmabcitypes.ResponseEndBlock, error)

Application is the interface implemented by multiplexed Oasis-specific ABCI applications.

type ApplicationQueryState

type ApplicationQueryState interface {
	// Storage returns the storage backend.
	Storage() storage.LocalBackend

	// Checkpointer returns the checkpointer associated with the application state.
	// This may be nil in case checkpoints are disabled.
	Checkpointer() checkpoint.Checkpointer

	// BlockHeight returns the last committed block height.
	BlockHeight() int64

	// GetEpoch returns epoch at block height.
	GetEpoch(ctx context.Context, blockHeight int64) (beacon.EpochTime, error)

	// LastRetainedVersion returns the earliest retained version the ABCI
	// state.
	LastRetainedVersion() (int64, error)

ApplicationQueryState is minimum methods required to service ApplicationState queries.

type ApplicationState

type ApplicationState interface {

	// InitialHeight returns the initial height.
	InitialHeight() int64

	// BlockHash returns the last committed block hash.
	BlockHash() []byte

	// ConsensusParameters returns the consensus parameters for the consensus backend itself.
	// These always reflect the active parameters for the current block.
	ConsensusParameters() *consensusGenesis.Parameters

	// BlockContext returns the current block context which can be used
	// to store intermediate per-block results.
	// This method must only be called from BeginBlock/DeliverTx/EndBlock
	// and calls from anywhere else will cause races.
	BlockContext() *BlockContext

	// GetBaseEpoch returns the base epoch.
	GetBaseEpoch() (beacon.EpochTime, error)

	// GetCurrentEpoch returns the epoch at the current block height.
	GetCurrentEpoch(ctx context.Context) (beacon.EpochTime, error)

	// EpochChanged returns true iff the current epoch has changed since the
	// last block.  As a matter of convenience, the current epoch is returned.
	EpochChanged(ctx *Context) (bool, beacon.EpochTime)

	// MinGasPrice returns the configured minimum gas price.
	MinGasPrice() *quantity.Quantity

	// OwnTxSigner returns the transaction signer identity of the local node.
	OwnTxSigner() signature.PublicKey

	// OwnTxSignerAddress returns the transaction signer's staking address of the local node.
	OwnTxSignerAddress() staking.Address

	// Upgrader returns the upgrade backend if available.
	Upgrader() upgrade.Backend

	// NewContext creates a new application processing context.
	NewContext(mode ContextMode, now time.Time) *Context

ApplicationState is the overall past, present and future state of all multiplexed applications.

type Backend

type Backend interface {

	// RegisterApplication registers an ABCI multiplexer application
	// with this service instance and check that its dependencies are
	// registered.
	RegisterApplication(Application) error

	// SetTransactionAuthHandler configures the transaction fee handler for the
	// ABCI multiplexer.
	SetTransactionAuthHandler(TransactionAuthHandler) error

	// GetBlock returns the Tendermint block at the specified height.
	GetTendermintBlock(ctx context.Context, height int64) (*tmtypes.Block, error)

	// GetBlockResults returns the ABCI results from processing a block
	// at a specific height.
	GetBlockResults(ctx context.Context, height int64) (*tmrpctypes.ResultBlockResults, error)

	// WatchTendermintBlocks returns a stream of Tendermint blocks as they are
	// returned via the `EventDataNewBlock` query.
	WatchTendermintBlocks() (<-chan *tmtypes.Block, *pubsub.Subscription)

	// GetLastRetainedVersion returns the earliest retained version the ABCI
	// state.
	GetLastRetainedVersion(ctx context.Context) (int64, error)

	// Pruner returns the state pruner.
	Pruner() StatePruner

Backend is a Tendermint consensus backend.

type BaseServiceClient

type BaseServiceClient struct{}

BaseServiceClient is a default ServiceClient implementation that provides noop implementations of all the delivery methods. Implementations should override them as needed.

func (*BaseServiceClient) DeliverBlock

func (bsc *BaseServiceClient) DeliverBlock(ctx context.Context, height int64) error

Implements ServiceClient.

func (*BaseServiceClient) DeliverCommand

func (bsc *BaseServiceClient) DeliverCommand(ctx context.Context, height int64, cmd interface{}) error

Implements ServiceClient.

func (*BaseServiceClient) DeliverEvent

func (bsc *BaseServiceClient) DeliverEvent(ctx context.Context, height int64, tx tmtypes.Tx, ev *types.Event) error

Implements ServiceClient.

type BlockContext

type BlockContext struct {
	// contains filtered or unexported fields

BlockContext can be used to store arbitrary key/value pairs for state that is needed while processing a block.

When a block is committed, this context is automatically reset.

func NewBlockContext

func NewBlockContext() *BlockContext

NewBlockContext creates an empty block context.

func (*BlockContext) Get

func (bc *BlockContext) Get(key BlockContextKey) interface{}

Get returns the value stored under the given key (if any). If no value currently exists, the NewDefault method is called on the key to produce a default value and that value is stored.

func (*BlockContext) Set

func (bc *BlockContext) Set(key BlockContextKey, value interface{})

Set overwrites the value stored under the given key.

type BlockContextKey

type BlockContextKey interface {
	// NewDefault returns a new default value for the given key.
	NewDefault() interface{}

BlockContextKey is an interface for a block context key.

type BlockMeta

type BlockMeta struct {
	// Header is the Tendermint block header.
	Header *tmtypes.Header `json:"header"`
	// LastCommit is the Tendermint last commit info.
	LastCommit *tmtypes.Commit `json:"last_commit"`

BlockMeta is the Tendermint-specific per-block metadata that is exposed via the consensus API.

type BlockProposerKey added in v0.2100.0

type BlockProposerKey struct{}

BlockProposerKey is the block context key for storing the block proposer address.

func (BlockProposerKey) NewDefault added in v0.2100.0

func (bpk BlockProposerKey) NewDefault() interface{}

NewDefault returns a new default value for the given key.

type Context

type Context struct {
	// contains filtered or unexported fields

Context is the context of processing a transaction/block.

func FromCtx

func FromCtx(ctx context.Context) *Context

FromCtx extracts an ABCI context from a context.Context if one has been set. Otherwise it returns nil.

func NewContext

func NewContext(
	ctx context.Context,
	mode ContextMode,
	currentTime time.Time,
	gasAccountant GasAccountant,
	appState ApplicationState,
	state mkvs.Tree,
	blockHeight int64,
	blockCtx *BlockContext,
	initialHeight int64,
) *Context

NewContext creates a new context.

func (*Context) AppState

func (c *Context) AppState() ApplicationState

AppState returns the application state.

Accessing application state in simulation mode is not allowed and will result in a panic.

func (*Context) BlockContext

func (c *Context) BlockContext() *BlockContext

BlockContext returns the current block context.

In case there is no current block (e.g., because the current context is not an execution context), this will return nil.

func (*Context) BlockHeight

func (c *Context) BlockHeight() int64

BlockHeight returns the current block height.

func (*Context) CallerAddress added in v0.2100.0

func (c *Context) CallerAddress() staking.Address

CallerAddress returns the authenticated address representing the caller.

func (*Context) Close

func (c *Context) Close()

Close releases all resources associated with this context.

After calling this method, the context should no longer be used.

func (*Context) Commit added in v0.2200.0

func (c *Context) Commit() *Context

Commit commits state updates and emitted events in this transaction child context previously created via NewTransaction. Returns the parent context.

If this is not a transaction child context, the method has no effect.

func (*Context) Data

func (c *Context) Data() interface{}

Data returns the data to be serialized with this output.

func (*Context) DecodeEvent added in v0.2200.0

func (c *Context) DecodeEvent(index int, ev events.TypedAttribute) error

DecodeEvent decodes the given raw event as a specific typed event.

func (*Context) EmitData

func (c *Context) EmitData(data interface{})

EmitData emits data to be serialized as transaction output.

Note: The use of this has mostly been replaced with EmitEvent, please think really carefully if you want to use this.

func (*Context) EmitEvent

func (c *Context) EmitEvent(bld *EventBuilder)

EmitEvent emits an ABCI event for the current transaction/block. Note: If the event has no attributes, this routine will do nothing.

func (*Context) Gas

func (c *Context) Gas() GasAccountant

Gas returns the gas accountant.

func (*Context) GetEvents

func (c *Context) GetEvents() []types.Event

GetEvents returns the ABCI event vector corresponding to the tags.

func (*Context) HasEvent

func (c *Context) HasEvent(app string, kind events.TypedAttribute) bool

HasEvent checks if a specific event has been emitted.

func (*Context) InitialHeight added in v0.2010.0

func (c *Context) InitialHeight() int64

InitialHeight returns the initial height.

func (*Context) IsCheckOnly

func (c *Context) IsCheckOnly() bool

IsCheckOnly returns true if this is a CheckTx context.

func (*Context) IsInitChain

func (c *Context) IsInitChain() bool

IsInitChain returns true if this ia an init chain context.

func (*Context) IsMessageExecution added in v0.2100.0

func (c *Context) IsMessageExecution() bool

IsMessageExecution returns true if this is a message execution context.

func (*Context) IsSimulation

func (c *Context) IsSimulation() bool

IsSimulation returns true if this is a simulation-only context.

func (*Context) Logger

func (c *Context) Logger() *logging.Logger

Logger returns the logger associated with this context.

func (*Context) Mode

func (c *Context) Mode() ContextMode

Mode returns the context mode.

func (*Context) NewChild added in v0.2100.0

func (c *Context) NewChild() *Context

NewChild creates a new child context that shares state with the current context.

If you want isolated state and events use NewTransaction instad.

func (*Context) NewTransaction added in v0.2200.0

func (c *Context) NewTransaction() *Context

NewTransaction creates a new transaction child context.

This automatically starts a new state checkpoint and the context must be explicitly committed by calling Commit otherwise both state and events will be reverted.

NOTE: This does NOT isolate anything other than state and events.

func (*Context) Now

func (c *Context) Now() time.Time

Now returns the current tendermint time.

func (*Context) SetGasAccountant

func (c *Context) SetGasAccountant(ga GasAccountant)

SetGasAccountant configures the gas accountant on the context.

func (*Context) SetTxSigner

func (c *Context) SetTxSigner(txSigner signature.PublicKey)

SetTxSigner sets the authenticated transaction signer.

This must only be done after verifying the transaction signature.

In case the method is called on a non-transaction context, this method will panic.

func (*Context) State

func (c *Context) State() mkvs.KeyValueTree

State returns the state tree associated with this context.

func (*Context) TxSigner

func (c *Context) TxSigner() signature.PublicKey

TxSigner returns the authenticated transaction signer.

In case the method is called on a non-transaction context, this method will panic.

func (*Context) WithCallerAddress added in v0.2100.0

func (c *Context) WithCallerAddress(callerAddress staking.Address) *Context

WithCallerAddress creates a child context and sets a specific tx address.

func (*Context) WithMessageExecution added in v0.2100.0

func (c *Context) WithMessageExecution() *Context

WithMessageExecution creates a child context and sets the message execution flag.

func (*Context) WithSimulation added in v0.2100.0

func (c *Context) WithSimulation() *Context

WithSimulation creates a child context in simulation mode.

Note that state is unchanged -- if you want to prevent propagation of state updates, start a checkpoint manually.

type ContextMode

type ContextMode uint

ContextMode is a context mode.

const (
	// ContextInvalid is invalid context and should never be used.
	ContextInvalid ContextMode = iota
	// ContextInitChain is InitChain context.
	// ContextCheckTx is CheckTx context.
	// ContextDeliverTx is DeliverTx context.
	// ContextSimulateTx is SimulateTx context.
	// ContextBeginBlock is BeginBlock context.
	// ContextEndBlock is EndBlock context.

func (ContextMode) String

func (m ContextMode) String() string

String returns a string representation of the context mode.

type EventBuilder

type EventBuilder struct {
	// contains filtered or unexported fields

EventBuilder is a helper for constructing ABCI events.

func NewEventBuilder

func NewEventBuilder(app string) *EventBuilder

NewEventBuilder returns a new EventBuilder for the given ABCI app.

func (*EventBuilder) Dirty

func (bld *EventBuilder) Dirty() bool

Dirty returns true iff the EventBuilder has attributes.

func (*EventBuilder) Event

func (bld *EventBuilder) Event() types.Event

Event returns the event from the EventBuilder.

func (*EventBuilder) TypedAttribute added in v0.2102.2

func (bld *EventBuilder) TypedAttribute(value events.TypedAttribute) *EventBuilder

TypedAttribute appends a typed attribute to the event.

type GasAccountant

type GasAccountant interface {
	// UseGas attempts the use the given amount of gas. If the limit is
	// reached this method will return ErrOutOfGas.
	// The actual amount defined by the costs map will be multiplied by
	// the given multiplier which must be a positive value.
	UseGas(multiplier int, op transaction.Op, costs transaction.Costs) error

	// GasWanted returns the amount of gas wanted.
	GasWanted() transaction.Gas

	// GasUsed returns the amount of gas used so far.
	GasUsed() transaction.Gas

GasAccountant is a gas accountant interface.

func NewCompositeGasAccountant

func NewCompositeGasAccountant(accts ...GasAccountant) GasAccountant

NewCompositeGasAccountant creates a gas accountant that is composed of multiple gas accountants. Any gas used is dispatched to all accountants and if any returns an error, the error is propagated.

The first accountant is used for GasWanted reporting.

func NewGasAccountant

func NewGasAccountant(maxUsedGas transaction.Gas) GasAccountant

NewGasAccountant creates a basic gas accountant.

The gas accountant is not safe for concurrent use.

func NewNopGasAccountant

func NewNopGasAccountant() GasAccountant

NewNopGasAccountant creates a no-op gas accountant that doesn't do any accounting.

type GasAccountantKey

type GasAccountantKey struct{}

GasAccountantKey is the gas accountant block context key.

func (GasAccountantKey) NewDefault

func (gak GasAccountantKey) NewDefault() interface{}

NewDefault returns a new default value for the given key.

type GenesisProvider

type GenesisProvider interface {
	GetTendermintGenesisDocument() (*tmtypes.GenesisDoc, error)

GenesisProvider is a tendermint specific genesis document provider.

type ImmutableState

type ImmutableState struct {

ImmutableState is an immutable state wrapper.

func NewImmutableState

func NewImmutableState(ctx context.Context, state ApplicationQueryState, version int64) (*ImmutableState, error)

NewImmutableState creates a new immutable state wrapper.

func (*ImmutableState) CheckContextMode

func (s *ImmutableState) CheckContextMode(ctx context.Context, allowedModes []ContextMode) error

CheckContextMode checks if the passed context is an ABCI context and is using one of the explicitly allowed modes.

func (*ImmutableState) Close

func (s *ImmutableState) Close()

Close releases the resources associated with the immutable state wrapper.

After calling this method, the immutable state wrapper should not be used anymore.

type MessageDispatcher added in v0.2100.0

type MessageDispatcher interface {
	// Subscribe subscribes a given message subscriber to messages of a specific kind.
	Subscribe(kind interface{}, ms MessageSubscriber)

	// Publish publishes a message of a given kind by dispatching to all subscribers.
	// Subscribers can return a result, but at most one subscriber should return a
	// non-nil result to any published message. Panics in case more than one subscriber
	// returns a non-nil result.
	// In case there are no subscribers ErrNoSubscribers is returned.
	Publish(ctx *Context, kind, msg interface{}) (interface{}, error)

MessageDispatcher is a message dispatcher interface.

type MessageSubscriber added in v0.2100.0

type MessageSubscriber interface {
	// ExecuteMessage executes a given message.
	ExecuteMessage(ctx *Context, kind, msg interface{}) (interface{}, error)

MessageSubscriber is a message subscriber interface.

type MockApplicationState added in v0.2100.0

type MockApplicationState interface {

	// UpdateMockApplicationStateConfig updates the mock application config.
	UpdateMockApplicationStateConfig(cfg *MockApplicationStateConfig)

MockApplicationState is the mock application state interface.

func NewMockApplicationState

func NewMockApplicationState(cfg *MockApplicationStateConfig) MockApplicationState

NewMockApplicationState creates a new mock application state for testing.

type MockApplicationStateConfig

type MockApplicationStateConfig struct {
	BlockHeight int64
	BlockHash   []byte

	BaseEpoch    beacon.EpochTime
	CurrentEpoch beacon.EpochTime
	EpochChanged bool

	MaxBlockGas transaction.Gas
	MinGasPrice *quantity.Quantity

	OwnTxSigner signature.PublicKey

	Genesis *genesis.Document

MockApplicationStateConfig is the configuration for the mock application state.

type NoopMessageDispatcher added in v0.2100.0

type NoopMessageDispatcher struct{}

NoopMessageDispatcher is a no-op message dispatcher that performs no dispatch.

func (*NoopMessageDispatcher) Publish added in v0.2100.0

func (nd *NoopMessageDispatcher) Publish(*Context, interface{}, interface{}) (interface{}, error)

Implements MessageDispatcher.

func (*NoopMessageDispatcher) Subscribe added in v0.2100.0

func (nd *NoopMessageDispatcher) Subscribe(interface{}, MessageSubscriber)

Implements MessageDispatcher.

type ServiceClient

type ServiceClient interface {
	// ServiceDescriptor returns the consensus service descriptor.
	ServiceDescriptor() ServiceDescriptor

	// DeliverBlock delivers a new block.
	// Execution of this method will block delivery of further events.
	DeliverBlock(ctx context.Context, height int64) error

	// DeliverEvent delivers an event emitted by the consensus service.
	DeliverEvent(ctx context.Context, height int64, tx tmtypes.Tx, ev *types.Event) error

	// DeliverCommand delivers a command emitted via the command channel.
	DeliverCommand(ctx context.Context, height int64, cmd interface{}) error

ServiceClient is a consensus service client.

type ServiceDescriptor

type ServiceDescriptor interface {
	// Name returns the name of this service.
	Name() string

	// EventType returns the event type associated with the consensus service.
	EventType() string

	// Queries returns a channel that emits queries that need to be subscribed to.
	Queries() <-chan tmpubsub.Query

	// Commands returns a channel that emits commands for the service client.
	Commands() <-chan interface{}

ServiceDescriptor is a Tendermint consensus service descriptor.

func NewServiceDescriptor

func NewServiceDescriptor(name, eventType string, queryCh <-chan tmpubsub.Query, cmdCh <-chan interface{}) ServiceDescriptor

NewServiceDescriptor creates a new consensus service descriptor.

func NewStaticServiceDescriptor

func NewStaticServiceDescriptor(name, eventType string, queries []tmpubsub.Query) ServiceDescriptor

NewStaticServiceDescriptor creates a new static consensus service descriptor.

type ServiceEvent

type ServiceEvent struct {
	Block *tmtypes.EventDataNewBlockHeader `json:"block,omitempty"`
	Tx    *tmtypes.EventDataTx             `json:"tx,omitempty"`

ServiceEvent is a Tendermint-specific consensus.ServiceEvent.

type StatePruneHandler added in v0.2200.0

type StatePruneHandler interface {
	// Prune is called before the specified version is pruned.
	// If an error is returned, pruning is aborted and the version is
	// not pruned from history.
	// Note that this can be called for the same version multiple
	// times (e.g., if one of the handlers fails but others succeed
	// and pruning is later retried).
	Prune(ctx context.Context, version uint64) error

StatePruneHandler is a handler that is called when versions are pruned from history.

type StatePruner added in v0.2200.0

type StatePruner interface {
	// RegisterHandler registers a prune handler.
	RegisterHandler(handler StatePruneHandler)

StatePruner is a concrete ABCI mux state pruner implementation.

type TransactionAuthHandler

type TransactionAuthHandler interface {

	// AuthenticateTx authenticates the given transaction by making sure
	// that the nonce is correct and deducts any fees as specified.
	// It may reject the transaction in case of incorrect nonces, insufficient
	// balance to pay fees or (only during CheckTx) if the gas price is too
	// low.
	// The context may be modified to configure a gas accountant.
	AuthenticateTx(ctx *Context, tx *transaction.Transaction) error

	// PostExecuteTx is called after the transaction has been executed. It is
	// only called in case the execution did not produce an error.
	PostExecuteTx(ctx *Context, tx *transaction.Transaction) error

TransactionAuthHandler is the interface for ABCI applications that handle authenticating transactions (checking nonces and fees).

Jump to

Keyboard shortcuts

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