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 ReplayStatusChecker
• type Route
  • func NewRoute(impl consensus.Route) Route
• type Snapshotter
• type TxApp
  • func NewTxApp(ctx context.Context, db DB, engine common.Engine, signer *auth.Ed25519Signer, ...) (*TxApp, error)
  • func (r *TxApp) AccountInfo(ctx context.Context, acctID []byte, getUnconfirmed bool) (balance *big.Int, nonce int64, err error)
  • func (r *TxApp) Activations(height int64) []*consensus.Hardfork
  • func (r *TxApp) ApplyMempool(ctx context.Context, tx *transactions.Transaction) error
  • func (r *TxApp) Begin(ctx context.Context, height int64) error
  • func (r *TxApp) ChainInfo(ctx context.Context) (int64, []byte, error)
  • func (r *TxApp) Close() error
  • func (r *TxApp) Commit(ctx context.Context) (int64, error)
  • func (r *TxApp) ConsensusAccountInfo(ctx context.Context, acctID []byte) (balance *big.Int, nonce int64, err error)
  • func (r *TxApp) ConsensusValidators(ctx context.Context) ([]*types.Validator, error)
  • func (r *TxApp) Execute(ctx TxContext, tx *transactions.Transaction) *TxResponse
  • func (r *TxApp) Finalize(ctx context.Context, blockHeight int64) (appHash []byte, finalValidators []*types.Validator, err error)
  • func (r *TxApp) GenesisInit(ctx context.Context, validators []*types.Validator, ...) error
  • func (r *TxApp) GetValidators(ctx context.Context) ([]*types.Validator, error)
  • func (r *TxApp) Log() *log.Logger
  • func (r *TxApp) Price(ctx context.Context, tx *transactions.Transaction) (*big.Int, error)
  • func (r *TxApp) ProposerTxs(ctx context.Context, txNonce uint64, maxTxsSize int64, proposerAddr []byte) ([][]byte, error)
  • func (r *TxApp) Reload(ctx context.Context) error
  • func (r *TxApp) SetReplayStatusChecker(fn ReplayStatusChecker)
  • func (r *TxApp) SubscribeValidators() <-chan []*types.Validator
  • func (r *TxApp) UpdateValidator(ctx context.Context, validator []byte, power int64) error
• type TxContext
• 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")
)

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.OuterTxMaker
	sql.ReadTxMaker
	sql.SnapshotTxMaker
	// BeginReservedReadTx creates a read-only transaction on a reserved
	// connection that does not contend with readers in the pool that services
	// RPC requests. NOTE: I think the read tx could use the writer conn given
	// the concurrency guarantees of the consensus connection, but I'm working
	// with a more general assumption in the pg package.
	BeginReservedReadTx(context.Context) (sql.Tx, error)
}

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, 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 ReplayStatusChecker

type ReplayStatusChecker func() bool

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 TxContext, router *TxApp, 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 TxApp

type TxApp struct {
	Database DB            // postgres database
	Engine   common.Engine // tracks deployed schemas

	GasEnabled bool
	// 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 DB, engine common.Engine, signer *auth.Ed25519Signer,
	events Rebroadcaster, snapshotter Snapshotter, chainParams *chain.GenesisConfig,
	extensionConfigs map[string]map[string]string, log log.Logger) (*TxApp, error)

NewTxApp creates a new router.

func (*TxApp) AccountInfo

func (r *TxApp) AccountInfo(ctx context.Context, 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) Activations

func (r *TxApp) Activations(height int64) []*consensus.Hardfork

Activations consults chain config for the names of hard forks that activate *at* the given block height, and retrieves the associated changes from the consensus package that contains the canonical and extended fork definitions.

func (*TxApp) ApplyMempool

func (r *TxApp) ApplyMempool(ctx context.Context, 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.

func (*TxApp) ChainInfo

func (r *TxApp) ChainInfo(ctx context.Context) (int64, []byte, error)

ChainInfo is called be the ABCI application's Info method, which is called once on startup except when the node is at genesis, in which case GenesisInit is called by the application's ChainInit method. At genesis, when there are no blocks yet, the height will be zero, never negative.

func (*TxApp) Close

func (r *TxApp) Close() error

Close is used to end any active database transaction that may exist if the application tries to shut down before closing the transaction with a call to Commit. Neglecting to rollback such a transaction may prevent the DB connection from being closed and released to the connection pool.

func (*TxApp) Commit

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

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

func (*TxApp) ConsensusAccountInfo

func (r *TxApp) ConsensusAccountInfo(ctx context.Context, acctID []byte) (balance *big.Int, nonce int64, err error)

func (*TxApp) ConsensusValidators

func (r *TxApp) ConsensusValidators(ctx context.Context) ([]*types.Validator, error)

ConsensusValidators gets the current validator set from the database. It will use the active write transaction if it exists (meaning it is called from FinalizeBlock, etc. between Commit and Begin), otherwise it uses a reserved reader connection to avoid contention with user requests.

func (*TxApp) Execute

func (r *TxApp) Execute(ctx TxContext, 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, blockHeight int64) (appHash []byte, finalValidators []*types.Validator, 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.

func (*TxApp) GenesisInit

func (r *TxApp) GenesisInit(ctx context.Context, validators []*types.Validator, genesisAccounts []*types.Account,
	initialHeight int64, genesisAppHash []byte) 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) GetValidators

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

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

func (*TxApp) Log

func (r *TxApp) Log() *log.Logger

func (*TxApp) Price

func (r *TxApp) Price(ctx context.Context, tx *transactions.Transaction) (*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, txNonce uint64, maxTxsSize int64, proposerAddr []byte) ([][]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) error

Reload reloads the database state into the engine.

func (*TxApp) SetReplayStatusChecker

func (r *TxApp) SetReplayStatusChecker(fn ReplayStatusChecker)

SetreplayStatusChecker sets the function to check if the node is in replay mode

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, 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 TxContext

type TxContext = common.TxContext

TxContext is the context for transaction execution. It is a type alias for common.TxContext (same type) for convenience.

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.