cosmos-sdk: Index | Files

package simulation

import ""

Package simulation implements a full fledged Cosmos SDK application used for executing simulation test suites.

Simulation App

The SimApp type defines an application used for running extensive simulation testing suites. It contains all core modules, including governance, staking, slashing, and distribution.

Simulation is executed with various inputs including the number of blocks to simulate, the block size, whether the app should commit or not, the invariant checking period, and a seed which is used as a source of pseudo-randomness.

In addition to the various inputs, simulation runs mainly in three modes:

1. Completely random where the initial state, module parameters and simulation parameters are pseudo-randomly generated.

2. From a genesis file where the initial state and the module parameters are defined. This mode is helpful for running simulations on a known state such as a live network export where a new (mostly likely breaking) version of the application needs to be tested.

3. From a params file where the initial state is pseudo-randomly generated but the module and simulation parameters can be provided manually. This allows for a more controlled and deterministic simulation setup while allowing the state space to still be pseudo-randomly simulated.

The simulation test suite also supports testing determinism and import/export functionality.


Currently, simulation uses a single seed (integer) as a source for a PRNG by which all random operations are executed from. Any call to the PRNG changes all future operations as the internal state of the PRNG is modified. For example, if a new message type is created and needs to be simulated, the new introduced PRNG call will change all subsequent operations.

This may can often be problematic when testing fixes to simulation faults. One current solution to this is to use a params file as mentioned above. In the future the simulation suite is expected to support a series of PRNGs that can be used uniquely per module and simulation component so that they will not effect each others state execution outcome.


To execute a completely pseudo-random simulation:

 $ go test -mod=readonly \
	-run=TestFullAppSimulation \
	-Enabled=true \
	-NumBlocks=100 \
	-BlockSize=200 \
	-Commit=true \
	-Seed=99 \
	-Period=5 \
	-v -timeout 24h

To execute simulation from a genesis file:

 $ go test -mod=readonly \
 	-run=TestFullAppSimulation \
 	-Enabled=true \
 	-NumBlocks=100 \
 	-BlockSize=200 \
 	-Commit=true \
 	-Seed=99 \
 	-Period=5 \
	-Genesis=/path/to/genesis.json \
 	-v -timeout 24h

To execute simulation from a simulation params file:

 $ go test -mod=readonly \
	-run=TestFullAppSimulation \
	-Enabled=true \
	-NumBlocks=100 \
	-BlockSize=200 \
	-Commit=true \
	-Seed=99 \
	-Period=5 \
	-Params=/path/to/params.json \
	-v -timeout 24h

To export the simulation params to a file at a given block height:

 $ go test -mod=readonly \
 	-run=TestFullAppSimulation \
 	-Enabled=true \
 	-NumBlocks=100 \
 	-BlockSize=200 \
 	-Commit=true \
 	-Seed=99 \
 	-Period=5 \
	-ExportParamsPath=/path/to/params.json \
	-ExportParamsHeight=50 \
	 -v -timeout 24h

To export the simulation app state (i.e genesis) to a file:

 $ go test -mod=readonly \
 	-run=TestFullAppSimulation \
 	-Enabled=true \
 	-NumBlocks=100 \
 	-BlockSize=200 \
 	-Commit=true \
 	-Seed=99 \
 	-Period=5 \
	-ExportStatePath=/path/to/genesis.json \
	 v -timeout 24h


Params that are provided to simulation from a JSON file are used to used to set both module parameters and simulation parameters. See sim_test.go for the full set of parameters that can be provided.


Package Files

doc.go event_stats.go log.go mock_tendermint.go operation.go params.go simulate.go transition_matrix.go util.go


const (
    BeginBlockEntryKind = "begin_block"
    EndBlockEntryKind   = "end_block"
    MsgEntryKind        = "msg"
    QueuedMsgEntryKind  = "queued_msg"

entry kinds for use within OperationEntry

const AverageBlockTime = 6 * time.Second

func CreateTransitionMatrix Uses

func CreateTransitionMatrix(weights [][]int) (simulation.TransitionMatrix, error)

CreateTransitionMatrix creates a transition matrix from the provided weights. TODO: Provide example usage

func GetMemberOfInitialState Uses

func GetMemberOfInitialState(r *rand.Rand, weights []int) int

GetMemberOfInitialState takes an initial array of weights, of size n. It returns a weighted random number in [0,n).

func NewSimParamChange Uses

func NewSimParamChange(subspace, key string, simVal simulation.SimValFn) simulation.ParamChange

NewSimParamChange creates a new ParamChange instance

func NewWeightedProposalContent Uses

func NewWeightedProposalContent(appParamsKey string, defaultWeight int, contentSimulatorFn simulation.ContentSimulatorFn) simulation.WeightedProposalContent

func RandomConsensusParams Uses

func RandomConsensusParams(r *rand.Rand, appState json.RawMessage) *abci.ConsensusParams

RandomParams returns random simulation consensus parameters, it extracts the Evidence from the Staking genesis state.

func RandomRequestBeginBlock Uses

func RandomRequestBeginBlock(r *rand.Rand, params Params,
    validators mockValidators, pastTimes []time.Time,
    pastVoteInfos [][]abci.VoteInfo,
    event func(route, op, evResult string), header abci.Header) abci.RequestBeginBlock

RandomRequestBeginBlock generates a list of signing validators according to the provided list of validators, signing fraction, and evidence fraction

type DummyLogWriter Uses

type DummyLogWriter struct{}

_____________________ dummy log writter

func (*DummyLogWriter) AddEntry Uses

func (lw *DummyLogWriter) AddEntry(_ OperationEntry)

do nothing

func (*DummyLogWriter) PrintLogs Uses

func (lw *DummyLogWriter) PrintLogs()

do nothing

type EventStats Uses

type EventStats map[string]map[string]map[string]int

EventStats defines an object that keeps a tally of each event that has occurred during a simulation.

func NewEventStats Uses

func NewEventStats() EventStats

NewEventStats creates a new empty EventStats object

func (EventStats) ExportJSON Uses

func (es EventStats) ExportJSON(path string)

ExportJSON saves the event stats as a JSON file on a given path

func (EventStats) Print Uses

func (es EventStats) Print(w io.Writer)

Print the event stats in JSON format.

func (EventStats) Tally Uses

func (es EventStats) Tally(route, op, evResult string)

Tally increases the count of a simulation event.

type LogWriter Uses

type LogWriter interface {

log writter

func NewLogWriter Uses

func NewLogWriter(testingmode bool) LogWriter

LogWriter - return a dummy or standard log writer given the testingmode

type OperationEntry Uses

type OperationEntry struct {
    EntryKind string          `json:"entry_kind" yaml:"entry_kind"`
    Height    int64           `json:"height" yaml:"height"`
    Order     int64           `json:"order" yaml:"order"`
    Operation json.RawMessage `json:"operation" yaml:"operation"`

OperationEntry - an operation entry for logging (ex. BeginBlock, EndBlock, XxxMsg, etc)

func BeginBlockEntry Uses

func BeginBlockEntry(height int64) OperationEntry

BeginBlockEntry - operation entry for begin block

func EndBlockEntry Uses

func EndBlockEntry(height int64) OperationEntry

EndBlockEntry - operation entry for end block

func MsgEntry Uses

func MsgEntry(height, order int64, opMsg simulation.OperationMsg) OperationEntry

MsgEntry - operation entry for standard msg

func NewOperationEntry Uses

func NewOperationEntry(entry string, height, order int64, op json.RawMessage) OperationEntry

NewOperationEntry creates a new OperationEntry instance

func QueuedMsgEntry Uses

func QueuedMsgEntry(height int64, opMsg simulation.OperationMsg) OperationEntry

QueuedMsgEntry creates an operation entry for a given queued message.

func (OperationEntry) MustMarshal Uses

func (oe OperationEntry) MustMarshal() json.RawMessage

MustMarshal marshals the operation entry, panic on error.

type OperationQueue Uses

type OperationQueue map[int][]simulation.Operation

OperationQueue defines an object for a queue of operations

func NewOperationQueue Uses

func NewOperationQueue() OperationQueue

NewOperationQueue creates a new OperationQueue instance.

type ParamChange Uses

type ParamChange struct {
    // contains filtered or unexported fields

ParamChange defines the object used for simulating parameter change proposals

func (ParamChange) ComposedKey Uses

func (spc ParamChange) ComposedKey() string

ComposedKey creates a new composed key for the param change proposal

func (ParamChange) Key Uses

func (spc ParamChange) Key() string

func (ParamChange) SimValue Uses

func (spc ParamChange) SimValue() simulation.SimValFn

func (ParamChange) Subspace Uses

func (spc ParamChange) Subspace() string

type Params Uses

type Params struct {
    // contains filtered or unexported fields

Params define the parameters necessary for running the simulations

func RandomParams Uses

func RandomParams(r *rand.Rand) Params

RandomParams returns random simulation parameters

func SimulateFromSeed Uses

func SimulateFromSeed(
    tb testing.TB, w io.Writer, app *baseapp.BaseApp,
    appStateFn simulation.AppStateFn, ops WeightedOperations,
    blackListedAccs map[string]bool, config simulation.Config,
) (stopEarly bool, exportedParams Params, err error)

SimulateFromSeed tests an application by running the provided operations, testing the provided invariants, but using the provided config.Seed. TODO: split this monster function up

func (Params) BlockSizeTransitionMatrix Uses

func (p Params) BlockSizeTransitionMatrix() simulation.TransitionMatrix

func (Params) EvidenceFraction Uses

func (p Params) EvidenceFraction() float64

func (Params) InitialLivenessWeightings Uses

func (p Params) InitialLivenessWeightings() []int

func (Params) LivenessTransitionMatrix Uses

func (p Params) LivenessTransitionMatrix() simulation.TransitionMatrix

func (Params) NumKeys Uses

func (p Params) NumKeys() int

func (Params) PastEvidenceFraction Uses

func (p Params) PastEvidenceFraction() float64

type StandardLogWriter Uses

type StandardLogWriter struct {
    OpEntries []OperationEntry `json:"op_entries" yaml:"op_entries"`

log writter

func (*StandardLogWriter) AddEntry Uses

func (lw *StandardLogWriter) AddEntry(opEntry OperationEntry)

add an entry to the log writter

func (*StandardLogWriter) PrintLogs Uses

func (lw *StandardLogWriter) PrintLogs()

PrintLogs - print the logs to a simulation file

type TransitionMatrix Uses

type TransitionMatrix struct {
    // contains filtered or unexported fields

TransitionMatrix is _almost_ a left stochastic matrix. It is technically not one due to not normalizing the column values. In the future, if we want to find the steady state distribution, it will be quite easy to normalize these values to get a stochastic matrix. Floats aren't currently used as the default due to non-determinism across architectures

func (TransitionMatrix) NextState Uses

func (t TransitionMatrix) NextState(r *rand.Rand, i int) int

NextState returns the next state randomly chosen using r, and the weightings provided in the transition matrix.

type WeightedOperation Uses

type WeightedOperation struct {
    // contains filtered or unexported fields

WeightedOperation is an operation with associated weight. This is used to bias the selection operation within the simulator.

func NewWeightedOperation Uses

func NewWeightedOperation(weight int, op simulation.Operation) WeightedOperation

NewWeightedOperation creates a new WeightedOperation instance

func (WeightedOperation) Op Uses

func (w WeightedOperation) Op() simulation.Operation

func (WeightedOperation) Weight Uses

func (w WeightedOperation) Weight() int

type WeightedOperations Uses

type WeightedOperations []simulation.WeightedOperation

WeightedOperations is the group of all weighted operations to simulate.

type WeightedProposalContent Uses

type WeightedProposalContent struct {
    // contains filtered or unexported fields

WeightedProposalContent defines a common struct for proposal contents defined by external modules (i.e outside gov)

func (WeightedProposalContent) AppParamsKey Uses

func (w WeightedProposalContent) AppParamsKey() string

func (WeightedProposalContent) ContentSimulatorFn Uses

func (w WeightedProposalContent) ContentSimulatorFn() simulation.ContentSimulatorFn

func (WeightedProposalContent) DefaultWeight Uses

func (w WeightedProposalContent) DefaultWeight() int

Package simulation imports 20 packages (graph) and is imported by 42 packages. Updated 2020-05-24. Refresh now. Tools for package owners.