stf

README

STF (State Transition Function) Documentation

This document outlines the main external calls in the STF package, their execution flows, and dependencies.

Table of Contents

• DeliverBlock
• Simulate
• ValidateTx
• Query

DeliverBlock

DeliverBlock is the main state transition function that processes an entire block of transactions.

sequenceDiagram
participant Caller
participant STF
participant State
participant PreBlock
participant BeginBlock
participant TxProcessor
participant EndBlock
Caller->>STF: DeliverBlock(ctx, block, state)
STF->>State: Branch(state)
STF->>State: SetHeaderInfo
STF->>PreBlock: doPreBlock(ctx, txs)
STF->>BeginBlock: doBeginBlock(ctx)
loop For each transaction
STF->>TxProcessor: deliverTx(ctx, state, tx)
TxProcessor->>TxProcessor: validateTx()
TxProcessor->>TxProcessor: execTx()
TxProcessor-->>STF: TxResult
end
STF->>EndBlock: doEndBlock(ctx)
STF->>EndBlock: validatorUpdates(ctx)
STF-->>Caller: BlockResponse, newState, error

Dependencies

• Required Input:
  • Context
  • BlockRequest containing transactions
  • ReadOnly state
• Required Components:
  • PreBlock handler
  • BeginBlock handler
  • EndBlock handler
  • Transaction validator
  • Message router
  • Gas meter

Simulate

Simulate executes a transaction without committing changes to the actual state.

sequenceDiagram
participant Caller
participant STF
participant State
participant TxProcessor
Caller->>STF: Simulate(ctx, state, gasLimit, tx)
STF->>State: Branch(state)
STF->>State: GetHeaderInfo()
STF->>TxProcessor: deliverTx(ctx, state, tx, SimulateMode)
TxProcessor-->>Caller: TxResult, simulationState

Dependencies

• Required Input:
  • Context
  • ReadOnly state
  • Gas limit
  • Transaction
• Required Components:
  • Transaction processor
  • Gas meter
  • Message router

ValidateTx

ValidateTx performs transaction validation without execution.

sequenceDiagram
participant Caller
participant STF
participant State
participant Validator
Caller->>STF: ValidateTx(ctx, state, gasLimit, tx)
STF->>State: Branch(state)
STF->>Validator: validateTx(ctx, state, gasLimit, tx)
Validator-->>Caller: TxResult

Dependencies

• Required Input:
  • Context
  • ReadOnly state
  • Gas limit
  • Transaction
• Required Components:
  • Transaction validator
  • Gas meter

Query

Query executes a read-only query against the application state.

sequenceDiagram
participant Caller
participant STF
participant State
participant QueryRouter
Caller->>STF: Query(ctx, state, gasLimit, req)
STF->>State: Branch(state)
STF->>State: GetHeaderInfo()
STF->>QueryRouter: Invoke(ctx, req)
QueryRouter-->>Caller: Response, error

Dependencies

• Required Input:
  • Context
  • ReadOnly state
  • Gas limit
  • Query request message
• Required Components:
  • Query router
  • Gas meter
  • Message handlers

Error Handling

All operations include error handling for:

• Context cancellation
• Gas limit exceeded
• Invalid transactions
• State operation failures
• Panic recovery (in transaction execution)

Gas Management

Gas is tracked and limited for:

• Transaction validation
• Message execution
• State operations
• Query execution

Each operation that consumes gas uses a gas meter to track usage and ensure limits are not exceeded.

Documentation

Index

• Variables
• func NewEventService() event.Service
• func NewGasMeterService() gas.Service
• func NewKVStoreService(address []byte) store.KVStoreService
• func NewMemoryStoreService(address []byte) store.MemoryStoreService
• func NewMsgRouterService(identity transaction.Identity) router.Service
• func NewQueryRouterService() router.Service
• func TypedEventToEvent(tev transaction.Msg) (event.Event, error)
• type BranchService
  • func (bs BranchService) Execute(ctx context.Context, f func(ctx context.Context) error) error
  • func (bs BranchService) ExecuteWithGasLimit(ctx context.Context, gasLimit uint64, f func(ctx context.Context) error) (gasUsed uint64, err error)
• type HeaderService
  • func (h HeaderService) HeaderInfo(ctx context.Context) header.Info
• type MsgRouterBuilder
  • func NewMsgRouterBuilder() *MsgRouterBuilder
  • func (b *MsgRouterBuilder) HandlerExists(msgType string) bool
  • func (b *MsgRouterBuilder) RegisterGlobalPostMsgHandler(handler appmodulev2.PostMsgHandler)
  • func (b *MsgRouterBuilder) RegisterGlobalPreMsgHandler(handler appmodulev2.PreMsgHandler)
  • func (b *MsgRouterBuilder) RegisterHandler(msgType string, handler appmodulev2.HandlerFunc) error
  • func (b *MsgRouterBuilder) RegisterPostMsgHandler(msgType string, handler appmodulev2.PostMsgHandler)
  • func (b *MsgRouterBuilder) RegisterPreMsgHandler(msgType string, handler appmodulev2.PreMsgHandler)
• type STF
  • func New[T transaction.Tx](logger log.Logger, msgRouterBuilder *MsgRouterBuilder, ...) (*STF[T], error)
  • func (s STF[T]) DeliverBlock(ctx context.Context, block *server.BlockRequest[T], state store.ReaderMap) (blockResult *server.BlockResponse, newState store.WriterMap, err error)
  • func (s STF[T]) DeliverSims(ctx context.Context, block *server.BlockRequest[T], state store.ReaderMap, ...) (blockResult *server.BlockResponse, newState store.WriterMap, err error)
  • func (s STF[T]) Query(ctx context.Context, state store.ReaderMap, gasLimit uint64, ...) (transaction.Msg, error)
  • func (s STF[T]) Simulate(ctx context.Context, state store.ReaderMap, gasLimit uint64, tx T) (server.TxResult, store.WriterMap)
  • func (s STF[T]) ValidateTx(ctx context.Context, state store.ReaderMap, gasLimit uint64, tx T) server.TxResult

Variables

var (
	// Identity defines STF's bytes identity and it's used by STF to store things in its own state.
	Identity = []byte("stf")
	// RuntimeIdentity defines the bytes identity of the runtime.
	RuntimeIdentity = []byte("runtime")
	// ConsensusIdentity defines the bytes identity of the consensus.
	ConsensusIdentity = []byte("consensus")
)

var ErrNoHandler = errors.New("no handler")

Functions

func NewEventService

func NewEventService() event.Service

func NewGasMeterService

func NewGasMeterService() gas.Service

NewGasMeterService creates a new instance of the gas meter service.

func NewKVStoreService

func NewKVStoreService(address []byte) store.KVStoreService

func NewMemoryStoreService

func NewMemoryStoreService(address []byte) store.MemoryStoreService

func NewMsgRouterService

func NewMsgRouterService(identity transaction.Identity) router.Service

NewMsgRouterService implements router.Service.

func NewQueryRouterService

func NewQueryRouterService() router.Service

NewQueryRouterService implements router.Service.

func TypedEventToEvent

func TypedEventToEvent(tev transaction.Msg) (event.Event, error)

TypedEventToEvent takes typed event and converts to Event object

Types

type BranchService

type BranchService struct{}

func (BranchService) Execute

func (bs BranchService) Execute(ctx context.Context, f func(ctx context.Context) error) error

func (BranchService) ExecuteWithGasLimit

func (bs BranchService) ExecuteWithGasLimit(
	ctx context.Context,
	gasLimit uint64,
	f func(ctx context.Context) error,
) (gasUsed uint64, err error)

type HeaderService

type HeaderService struct{}

func (HeaderService) HeaderInfo

func (h HeaderService) HeaderInfo(ctx context.Context) header.Info

type MsgRouterBuilder

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

func NewMsgRouterBuilder

func NewMsgRouterBuilder() *MsgRouterBuilder

NewMsgRouterBuilder is a router that routes messages to their respective handlers.

func (*MsgRouterBuilder) HandlerExists

func (b *MsgRouterBuilder) HandlerExists(msgType string) bool

func (*MsgRouterBuilder) RegisterGlobalPostMsgHandler

func (b *MsgRouterBuilder) RegisterGlobalPostMsgHandler(handler appmodulev2.PostMsgHandler)

func (*MsgRouterBuilder) RegisterGlobalPreMsgHandler

func (b *MsgRouterBuilder) RegisterGlobalPreMsgHandler(handler appmodulev2.PreMsgHandler)

func (*MsgRouterBuilder) RegisterHandler

func (b *MsgRouterBuilder) RegisterHandler(msgType string, handler appmodulev2.HandlerFunc) error

func (*MsgRouterBuilder) RegisterPostMsgHandler

func (b *MsgRouterBuilder) RegisterPostMsgHandler(msgType string, handler appmodulev2.PostMsgHandler)

func (*MsgRouterBuilder) RegisterPreMsgHandler

func (b *MsgRouterBuilder) RegisterPreMsgHandler(msgType string, handler appmodulev2.PreMsgHandler)

type STF

type STF[T transaction.Tx] struct {
	// contains filtered or unexported fields
}

STF is a struct that manages the state transition component of the app.

func New

func New[T transaction.Tx](
	logger log.Logger,
	msgRouterBuilder *MsgRouterBuilder,
	queryRouterBuilder *MsgRouterBuilder,
	doPreBlock func(ctx context.Context, txs []T) error,
	doBeginBlock func(ctx context.Context) error,
	doEndBlock func(ctx context.Context) error,
	doTxValidation func(ctx context.Context, tx T) error,
	doValidatorUpdate func(ctx context.Context) ([]appmodulev2.ValidatorUpdate, error),
	postTxExec func(ctx context.Context, tx T, success bool) error,
	branch func(store store.ReaderMap) store.WriterMap,
) (*STF[T], error)

New returns a new STF instance.

func (STF[T]) DeliverBlock

func (s STF[T]) DeliverBlock(
	ctx context.Context,
	block *server.BlockRequest[T],
	state store.ReaderMap,
) (blockResult *server.BlockResponse, newState store.WriterMap, err error)

DeliverBlock is our state transition function. It takes a read only view of the state to apply the block to, executes the block and returns the block results and the new state.

func (STF[T]) DeliverSims

func (s STF[T]) DeliverSims(
	ctx context.Context,
	block *server.BlockRequest[T],
	state store.ReaderMap,
	simsBuilder func(ctx context.Context) iter.Seq[T],
) (blockResult *server.BlockResponse, newState store.WriterMap, err error)

DeliverSims entrypoint to processes sims transactions similar to DeliverBlock.

func (STF[T]) Query

func (s STF[T]) Query(
	ctx context.Context,
	state store.ReaderMap,
	gasLimit uint64,
	req transaction.Msg,
) (transaction.Msg, error)

Query executes the query on the provided state with the provided gas limits.

func (STF[T]) Simulate

func (s STF[T]) Simulate(
	ctx context.Context,
	state store.ReaderMap,
	gasLimit uint64,
	tx T,
) (server.TxResult, store.WriterMap)

Simulate simulates the execution of a tx on the provided state.

func (STF[T]) ValidateTx

func (s STF[T]) ValidateTx(
	ctx context.Context,
	state store.ReaderMap,
	gasLimit uint64,
	tx T,
) server.TxResult

ValidateTx will run only the validation steps required for a transaction. Validations are run over the provided state, with the provided gas limit.