txapp

Documentation

Overview

package tx_router routes transactions to the appropriate module(s)

Index

• Variables
• func RegisterRoute(payloadType transactions.PayloadType, route Route) error
• func RegisterRouteImpl(payloadType transactions.PayloadType, route consensus.Route) error
• type ConsensusParams
• type CreditPayload
  • func (p *CreditPayload) MarshalBinary() ([]byte, error)
  • func (p *CreditPayload) UnmarshalBinary(data []byte) error
• type DB
• type Pricer
• type Rebroadcaster
• type Route
  • func NewRoute(impl consensus.Route) Route
• type Snapshotter
• type Spend
  • func (s *Spend) ApplySpend(ctx context.Context, db sql.DB) error
• type TxApp
  • func NewTxApp(ctx context.Context, db sql.Executor, engine common.Engine, ...) (*TxApp, error)
  • func (r *TxApp) AccountInfo(ctx context.Context, db sql.DB, acctID []byte, getUnconfirmed bool) (balance *big.Int, nonce int64, err error)
  • func (r *TxApp) ApplyMempool(ctx *common.TxContext, db sql.DB, tx *transactions.Transaction) error
  • func (r *TxApp) Begin(ctx context.Context, height int64) error
  • func (r *TxApp) CachedValidators() ([]*types.Validator, bool)
  • func (r *TxApp) Commit(ctx context.Context)
  • func (r *TxApp) Execute(ctx *common.TxContext, db sql.DB, tx *transactions.Transaction) *TxResponse
  • func (r *TxApp) Finalize(ctx context.Context, db sql.DB, block *common.BlockContext) (finalValidators []*types.Validator, approvedJoins, expiredJoins [][]byte, ...)
  • func (r *TxApp) GenesisInit(ctx context.Context, db sql.DB, validators []*types.Validator, ...) error
  • func (r *TxApp) GetBlockSpends() []*Spend
  • func (r *TxApp) GetValidators(ctx context.Context, db sql.DB) ([]*types.Validator, error)
  • func (r *TxApp) Price(ctx context.Context, dbTx sql.DB, tx *transactions.Transaction, ...) (*big.Int, error)
  • func (r *TxApp) ProposerTxs(ctx context.Context, db sql.DB, txNonce uint64, maxTxsSize int64, ...) ([][]byte, error)
  • func (r *TxApp) Reload(ctx context.Context, db sql.DB) error
  • func (r *TxApp) SubscribeValidators() <-chan []*types.Validator
  • func (r *TxApp) UpdateValidator(ctx context.Context, db sql.DB, validator []byte, power int64) error
• type TxResponse

Variables

var (
	ErrCallerNotValidator = errors.New("caller is not a validator")
	ErrCallerIsValidator  = errors.New("caller is already a validator")
	ErrCallerNotProposer  = errors.New("caller is not the block proposer")
	ErrTargetNotValidator = errors.New("target is not a validator")
)

var (
	ValidatorVoteBodyBytePrice int64 = 1000                  // Per byte cost
	ValidatorVoteIDPrice             = big.NewInt(1000 * 16) // 16 bytes for the UUID
)

Functions

func RegisterRoute

func RegisterRoute(payloadType transactions.PayloadType, route Route) error

RegisterRoute associates a Route with a payload type. See also RegisterRouteImpl to register a consensus.Route.

func RegisterRouteImpl

func RegisterRouteImpl(payloadType transactions.PayloadType, route consensus.Route) error

RegisterRouteImpl associates a consensus.Route with a payload type. This is shorthand for RegisterRoute(payloadType, NewRoute(route)).

Types

type ConsensusParams

type ConsensusParams struct {
	// VotingPeriod is the maximum length of a voting period.
	// It is measured in blocks, and is applied additively.
	// e.g. if the current block is 50, and VotingPeriod is 100,
	// then the current voting period ends at block 150.
	VotingPeriod int64
	// JoinVoteExpiration is the voting period for any validator
	// join or removal vote. It is measured in blocks, and is applied additively.
	// e.g. if the current block is 50, and JoinVoteExpiration is 100,
	// then the current voting period ends at block 150.
	JoinVoteExpiration int64
}

ConsensusParams holds network level parameters that may evolve over time.

type CreditPayload

type CreditPayload struct {
	DepositID string   // the transaction ID from the source chain that created the deposit
	Account   []byte   // the account to be credited
	Amount    *big.Int // the amount of tokens to be credited
}

func (*CreditPayload) MarshalBinary

func (p *CreditPayload) MarshalBinary() ([]byte, error)

func (*CreditPayload) UnmarshalBinary

func (p *CreditPayload) UnmarshalBinary(data []byte) error

type DB

type DB interface {
	sql.PreparedTxMaker
	sql.ReadTxMaker
	sql.SnapshotTxMaker
}

DB is the interface for the main SQL database. All queries must be executed from within a transaction. A DB can create read transactions or the special two-phase outer write transaction.

type Pricer

type Pricer interface {
	Price(ctx context.Context, router *TxApp, db sql.DB, tx *transactions.Transaction) (*big.Int, error)
}

type Rebroadcaster

type Rebroadcaster interface {
	// MarkRebroadcast marks events for rebroadcasting.
	MarkRebroadcast(ctx context.Context, ids []*types.UUID) error
}

Rebroadcaster is a service that marks events for rebroadcasting.

type Route

type Route interface {
	Pricer
	// Execute is responsible for committing or rolling back transactions.
	// All transactions should spend, regardless of success or failure.
	// Therefore, a nested transaction should be used for all database
	// operations after the initial checkAndSpend.
	Execute(ctx *common.TxContext, router *TxApp, db sql.DB, tx *transactions.Transaction) *TxResponse
}

Route is a type that the router uses to handle a certain payload type.

func NewRoute

func NewRoute(impl consensus.Route) Route

NewRoute creates a complete Route for the TxApp from a consensus.Route.

type Snapshotter

type Snapshotter interface {
	// CreateSnapshot creates a snapshot of the current state.
	CreateSnapshot(ctx context.Context, height uint64, snapshotID string) error

	// IsSnapshotDue returns true if a snapshot is due at the given height.
	IsSnapshotDue(height uint64) bool
}

type Spend

type Spend struct {
	Account []byte
	Amount  *big.Int
	Nonce   uint64
}

func (*Spend) ApplySpend

func (s *Spend) ApplySpend(ctx context.Context, db sql.DB) error

ApplySpend applies a spend to the accounts database.

type TxApp

type TxApp struct {
	Engine common.Engine // tracks deployed schemas
	// contains filtered or unexported fields
}

TxApp maintains the state for Kwil's ABCI application. It is responsible for interpreting payload bodies and routing them properly, maintaining a mempool for uncommitted accounts, pricing transactions, managing atomicity of the database, and managing the validator set.

func NewTxApp

func NewTxApp(ctx context.Context, db sql.Executor, engine common.Engine, signer *auth.Ed25519Signer,
	events Rebroadcaster, service *common.Service) (*TxApp, error)

NewTxApp creates a new router.

func (*TxApp) AccountInfo

func (r *TxApp) AccountInfo(ctx context.Context, db sql.DB, acctID []byte, getUnconfirmed bool) (balance *big.Int, nonce int64, err error)

AccountInfo gets account info from either the mempool or the account store. It takes a flag to indicate whether it should check the mempool first.

func (*TxApp) ApplyMempool

func (r *TxApp) ApplyMempool(ctx *common.TxContext, db sql.DB, tx *transactions.Transaction) error

ApplyMempool applies the transactions in the mempool. If it returns an error, then the transaction is invalid.

func (*TxApp) Begin

func (r *TxApp) Begin(ctx context.Context, height int64) error

Begin signals that a new block has begun. This creates an outer database transaction that may be committed, or rolled back on error or crash. It is given the starting networkParams, and is expected to use them to use them to store any changes to the network parameters in the database during Finalize.

func (*TxApp) CachedValidators

func (r *TxApp) CachedValidators() ([]*types.Validator, bool)

CachedValidators returns the current validator set that is cached, and whether or not it is valid. This can be used by TxApp consumers to try to get a validator set without hitting the database.

func (*TxApp) Commit

func (r *TxApp) Commit(ctx context.Context)

Commit signals that a block's state changes should be committed.

func (*TxApp) Execute

func (r *TxApp) Execute(ctx *common.TxContext, db sql.DB, tx *transactions.Transaction) *TxResponse

Execute executes a transaction. It will route the transaction to the appropriate module(s) and return the response. This method must only be called from the consensus engine, sequentially, when executing transactions in a block.

func (*TxApp) Finalize

func (r *TxApp) Finalize(ctx context.Context, db sql.DB, block *common.BlockContext) (finalValidators []*types.Validator, approvedJoins, expiredJoins [][]byte, err error)

Finalize signals that a block has been finalized. No more changes can be applied to the database. It returns the apphash and the validator set. And state modifications specified by hardforks activating at this height are applied. It is given the old and new network parameters, and is expected to use them to store any changes to the network parameters in the database.

func (*TxApp) GenesisInit

func (r *TxApp) GenesisInit(ctx context.Context, db sql.DB, validators []*types.Validator, genesisAccounts []*types.Account,
	initialHeight int64, chain *common.ChainContext) error

GenesisInit initializes the TxApp. It must be called outside of a session, and before any session is started. It can assign the initial validator set and initial account balances. It is only called once for a new chain.

func (*TxApp) GetBlockSpends

func (r *TxApp) GetBlockSpends() []*Spend

GetBlockSpends returns the spends that occurred during the block.

func (*TxApp) GetValidators

func (r *TxApp) GetValidators(ctx context.Context, db sql.DB) ([]*types.Validator, error)

GetValidators returns a shallow copy of the current validator set. It will return ONLY committed changes.

func (*TxApp) Price

func (r *TxApp) Price(ctx context.Context, dbTx sql.DB, tx *transactions.Transaction, chainContext *common.ChainContext) (*big.Int, error)

Price estimates the price of a transaction. It returns the estimated price in tokens.

func (*TxApp) ProposerTxs

func (r *TxApp) ProposerTxs(ctx context.Context, db sql.DB, txNonce uint64, maxTxsSize int64, block *common.BlockContext) ([][]byte, error)

ProposerTxs returns the transactions that the proposer should include in the next block. It takes txNonce as an argument because, the proposer may have its own transactions in the mempool that are included in the current block. Therefore, we need to know the largest nonce of the transactions included in the block that are authored by the proposer. This transaction only includes voteBodies for events whose bodies have not been received by the network. Therefore, there won't be more than 1 VoteBody transaction per event.

func (*TxApp) Reload

func (r *TxApp) Reload(ctx context.Context, db sql.DB) error

Reload reloads the database state into the engine.

func (*TxApp) SubscribeValidators

func (r *TxApp) SubscribeValidators() <-chan []*types.Validator

SubscribeValidators creates and returns a new channel on which the current validator set will be sent for each block Commit. The receiver will miss updates if they are unable to receive fast enough. This should generally be used after catch-up is complete, and only called once by the receiving goroutine rather than repeatedly in a loop, for instance. The slice should not be modified by the receiver.

func (*TxApp) UpdateValidator

func (r *TxApp) UpdateValidator(ctx context.Context, db sql.DB, validator []byte, power int64) error

UpdateValidator updates a validator's power. It can only be called in between Begin and Finalize. The value passed as power will simply replace the current power.

type TxResponse

type TxResponse struct {
	// ResponseCode is the response code from the transaction
	ResponseCode transactions.TxCode

	// Spend is the amount of tokens spent by the transaction
	Spend int64

	// Error is the error returned by the transaction, if any
	Error error
}

TxResponse is the response from a transaction. It contains information about the transaction, such as the amount spent.