api

package
v0.2100.0 Latest Latest
Warning

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

 Go to latest Published: Mar 18, 2021 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

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

Index

Constants

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"
)

Variables

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.

Functions

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.

Types

type Application 

type Application interface {
	MessageSubscriber

	// 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.
	OnCleanup()

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

	// 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 {
	ApplicationQueryState

	// 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 {
	consensus.Backend

	// 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)
}

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 {
	context.Context
	// 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) Data 

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

Data returns the data to be serialized with this output.

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(evType string, key []byte) 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.

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) StartCheckpoint 

func (c *Context) StartCheckpoint() *StateCheckpoint

StartCheckpoint starts a new state checkpoint. Any further updates to the context's state will be performed against the checkpoint and will only be committed in case of an explicit Commit.

Any existing references to State() returned prior to calling this method should not be mutated while the checkpoint is open. Doing so may cause updates to leak to into the checkpoint as isolation is only one-way.

The caller must make sure to call either Close or Commit on the checkpoint, otherwise this will leak resources.

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.
	ContextInitChain
	// ContextCheckTx is CheckTx context.
	ContextCheckTx
	// ContextDeliverTx is DeliverTx context.
	ContextDeliverTx
	// ContextSimulateTx is SimulateTx context.
	ContextSimulateTx
	// ContextBeginBlock is BeginBlock context.
	ContextBeginBlock
	// ContextEndBlock is EndBlock context.
	ContextEndBlock
)

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) Attribute 

func (bld *EventBuilder) Attribute(key, value []byte) *EventBuilder

Attribute appends a key/value pair to the event.

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.

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 {
	mkvs.ImmutableKeyValueTree
}

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.
	//
	// In case there are no subscribers ErrNoSubscribers is returned.
	Publish(ctx *Context, kind, msg 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{}) error
}

MessageSubscriber is a message subscriber interface.

type MockApplicationState added in v0.2100.0 

type MockApplicationState interface {
	ApplicationState

	// 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{}) 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 StateCheckpoint 

type StateCheckpoint struct {
	// contains filtered or unexported fields
}

StateCheckpoint is a state checkpoint that can be used to rollback state.

func (*StateCheckpoint) Close 

func (sc *StateCheckpoint) Close()

Close releases resources associated with the checkpoint without committing it.

func (*StateCheckpoint) Commit 

func (sc *StateCheckpoint) Commit()

Commit commits any changes performed since the checkpoint was created.

type TransactionAuthHandler 

type TransactionAuthHandler interface {
	consensus.TransactionAuthHandler

	// 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
}

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

Source Files

View all Source files

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.