appmanager

README

AppManager Documentation

The AppManager serves as a high-level coordinator, delegating most operations to the STF while managing state access through the Store interface.

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

Table of Contents

• InitGenesis
• ExportGenesis
• DeliverBlock
• ValidateTx
• Simulate
• SimulateWithState
• Query
• QueryWithState

InitGenesis

InitGenesis initializes the genesis state of the application.

sequenceDiagram
participant Caller
participant AppManager
participant InitGenesisImpl
participant STF
participant State
Caller->>AppManager: InitGenesis(ctx, blockRequest, genesisJSON, decoder)
AppManager->>InitGenesisImpl: initGenesis(ctx, genesisJSON, txHandler)
loop For each genesis transaction
InitGenesisImpl->>InitGenesisImpl: Decode and collect transactions
end
InitGenesisImpl-->>AppManager: genesisState, validatorUpdates, error
AppManager->>STF: DeliverBlock(ctx, blockRequest, genesisState)
STF-->>AppManager: blockResponse, blockZeroState, error
AppManager->>State: Apply state changes
AppManager-->>Caller: blockResponse, genesisState, error

Dependencies

• Required Input:
  • Context
  • BlockRequest
  • Genesis JSON
  • Transaction decoder
• Required Components:
  • InitGenesis implementation
  • STF
  • Store interface

ExportGenesis

ExportGenesis exports the current application state as genesis state.

sequenceDiagram
participant Caller
participant AppManager
participant ExportGenesisImpl
Caller->>AppManager: ExportGenesis(ctx, version)
AppManager->>ExportGenesisImpl: exportGenesis(ctx, version)
ExportGenesisImpl-->>Caller: genesisJSON, error

Dependencies

• Required Input:
  • Context
  • Version
• Required Components:
  • ExportGenesis implementation
  • Store interface

DeliverBlock

DeliverBlock processes a block of transactions.

sequenceDiagram
participant Caller
participant AppManager
participant Store
participant STF
Caller->>AppManager: DeliverBlock(ctx, block)
AppManager->>Store: StateLatest()
Store-->>AppManager: version, currentState, error
AppManager->>STF: DeliverBlock(ctx, block, currentState)
STF-->>Caller: blockResponse, newState, error

Dependencies

• Required Input:
  • Context
  • BlockRequest
• Required Components:
  • Store interface
  • STF

ValidateTx

ValidateTx validates a transaction against the latest state.

sequenceDiagram
participant Caller
participant AppManager
participant Store
participant STF
Caller->>AppManager: ValidateTx(ctx, tx)
AppManager->>Store: StateLatest()
Store-->>AppManager: version, latestState, error
AppManager->>STF: ValidateTx(ctx, latestState, gasLimit, tx)
STF-->>Caller: TxResult, error

Dependencies

• Required Input:
  • Context
  • Transaction
• Required Components:
  • Store interface
  • STF
  • Configuration (for gas limits)

Simulate

Simulate executes a transaction simulation using the latest state.

sequenceDiagram
participant Caller
participant AppManager
participant Store
participant STF
Caller->>AppManager: Simulate(ctx, tx)
AppManager->>Store: StateLatest()
Store-->>AppManager: version, state, error
AppManager->>STF: Simulate(ctx, state, gasLimit, tx)
STF-->>Caller: TxResult, WriterMap, error

Dependencies

• Required Input:
  • Context
  • Transaction
• Required Components:
  • Store interface
  • STF
  • Configuration (for gas limits)

SimulateWithState

SimulateWithState executes a transaction simulation using provided state.

sequenceDiagram
participant Caller
participant AppManager
participant STF
Caller->>AppManager: SimulateWithState(ctx, state, tx)
AppManager->>STF: Simulate(ctx, state, gasLimit, tx)
STF-->>Caller: TxResult, WriterMap, error

Dependencies

• Required Input:

  • Context
  • Transaction
  • State

  Query

Query executes a query at a specific version.

sequenceDiagram
participant Caller
participant AppManager
participant Store
participant STF
Caller->>AppManager: Query(ctx, version, request)
alt version == 0
AppManager->>Store: StateLatest()
else version > 0
AppManager->>Store: StateAt(version)
end
Store-->>AppManager: queryState, error
AppManager->>STF: Query(ctx, queryState, gasLimit, request)
STF-->>Caller: response, error

Dependencies

• Required Input:

  • Context
  • Version (or 0 for latest)
  • Query request

• Required Components:

  • Store interface
  • STF
  • Configuration (for gas limits)

  QueryWithState

QueryWithState executes a query using provided state.

sequenceDiagram
participant Caller
participant AppManager
participant STF
Caller->>AppManager: QueryWithState(ctx, state, request)
AppManager->>STF: Query(ctx, state, gasLimit, request)
STF-->>Caller: response, error

Dependencies

• Required Input:
  • Context
  • ReaderMap state
  • Query request
• Required Components:
  • STF
  • Configuration (for gas limits)

Common Dependencies

All operations depend on:

• Context management
• Error handling
• Gas metering
• State management (Store interface)
• STF interface

Documentation

Index

• type AppManager
  • func New[T transaction.Tx](config Config, db Store, stf StateTransitionFunction[T], ...) AppManager[T]
• type Config
• type ExportGenesis
• type InitGenesis
• type StateTransitionFunction
• type Store
• type TransactionFuzzer

Types

type AppManager

type AppManager[T transaction.Tx] interface {
	TransactionFuzzer[T]

	// InitGenesis initializes the genesis state of the application.
	InitGenesis(
		ctx context.Context,
		blockRequest *server.BlockRequest[T],
		initGenesisJSON []byte,
		txDecoder transaction.Codec[T],
	) (*server.BlockResponse, corestore.WriterMap, error)

	// ExportGenesis exports the genesis state of the application.
	ExportGenesis(ctx context.Context, version uint64) ([]byte, error)

	// DeliverBlock executes a block of transactions.
	DeliverBlock(
		ctx context.Context,
		block *server.BlockRequest[T],
	) (*server.BlockResponse, corestore.WriterMap, error)

	// ValidateTx will validate the tx against the latest storage state. This means that
	// only the stateful validation will be run, not the execution portion of the tx.
	// If full execution is needed, Simulate must be used.
	ValidateTx(ctx context.Context, tx T) (server.TxResult, error)

	// Simulate runs validation and execution flow of a Tx.
	Simulate(ctx context.Context, tx T) (server.TxResult, corestore.WriterMap, error)

	// SimulateWithState runs validation and execution flow of a Tx,
	// using the provided state instead of loading the latest state from the underlying database.
	SimulateWithState(ctx context.Context, state corestore.ReaderMap, tx T) (server.TxResult, corestore.WriterMap, error)

	// Query queries the application at the provided version.
	// CONTRACT: Version must always be provided, if 0, get latest
	Query(ctx context.Context, version uint64, request transaction.Msg) (transaction.Msg, error)

	// QueryWithState executes a query with the provided state. This allows to process a query
	// independently of the db state. For example, it can be used to process a query with temporary
	// and uncommitted state
	QueryWithState(ctx context.Context, state corestore.ReaderMap, request transaction.Msg) (transaction.Msg, error)
}

AppManager is a coordinator for all things related to an application It is responsible for interacting with stf and store. Runtime/v2 is an extension of this interface.

func New

func New[T transaction.Tx](
	config Config,
	db Store,
	stf StateTransitionFunction[T],
	initGenesisImpl InitGenesis,
	exportGenesisImpl ExportGenesis,
) AppManager[T]

type Config

type Config struct {
	ValidateTxGasLimit uint64 `mapstructure:"validate-tx-gas-limit"`
	QueryGasLimit      uint64 `mapstructure:"query-gas-limit"`
	SimulationGasLimit uint64 `mapstructure:"simulation-gas-limit"`
}

Config represents the configuration options for the app manager.

type ExportGenesis

type ExportGenesis func(ctx context.Context, version uint64) ([]byte, error)

ExportGenesis is a function type that represents the export of the genesis state.

type InitGenesis

type InitGenesis func(
	ctx context.Context,
	src io.Reader,
	txHandler func(json.RawMessage) error,
) (store.WriterMap, []appmodulev2.ValidatorUpdate, error)

InitGenesis is a function that will run at application genesis, it will be called with the following arguments:

• ctx: the context of the genesis operation
• src: the source containing the raw genesis state
• txHandler: a function capable of decoding a json tx, will be run for each genesis transaction

It must return a map of the dirty state after the genesis operation.

type StateTransitionFunction

type StateTransitionFunction[T transaction.Tx] interface {
	// DeliverBlock executes a block of transactions.
	DeliverBlock(
		ctx context.Context,
		block *server.BlockRequest[T],
		state store.ReaderMap,
	) (blockResult *server.BlockResponse, newState store.WriterMap, err error)

	// ValidateTx validates a transaction.
	ValidateTx(
		ctx context.Context,
		state store.ReaderMap,
		gasLimit uint64,
		tx T,
	) server.TxResult

	// Simulate executes a transaction in simulation mode.
	Simulate(
		ctx context.Context,
		state store.ReaderMap,
		gasLimit uint64,
		tx T,
	) (server.TxResult, store.WriterMap)

	// Query executes a query on the application.
	Query(
		ctx context.Context,
		state store.ReaderMap,
		gasLimit uint64,
		req transaction.Msg,
	) (transaction.Msg, error)

	// DeliverSims provides an interface for state transitions by sims.
	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)
}

StateTransitionFunction is an interface for processing transactions and blocks.

type Store

type Store interface {
	// StateLatest returns a readonly view over the latest
	// committed state of the store. Alongside the version
	// associated with it.
	StateLatest() (uint64, corestore.ReaderMap, error)

	// StateAt returns a readonly view over the provided
	// state. Must error when the version does not exist.
	StateAt(version uint64) (corestore.ReaderMap, error)
}

Store defines the underlying storage behavior needed by AppManager.

type TransactionFuzzer

type TransactionFuzzer[T transaction.Tx] interface {
	// DeliverSims processes simulated transactions for a block and generates a response with potential state changes.
	// The simsBuilder generates simulated transactions.
	DeliverSims(
		ctx context.Context,
		block *server.BlockRequest[T],
		simsBuilder func(ctx context.Context) iter.Seq[T],
	) (*server.BlockResponse, corestore.WriterMap, error)
}

TransactionFuzzer defines an interface for processing simulated transactions and generating responses with state changes.