simulation

package
v0.28.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 8, 2018 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package simulation implements a simulation framework for any state machine built on the SDK which utilizes auth.

It is primarily intended for fuzz testing the integration of modules. It will test that the provided operations are interoperable, and that the desired invariants hold. It can additionally be used to detect what the performance benchmarks in the system are, by using benchmarking mode and cpu / mem profiling. If it detects a failure, it provides the entire log of what was ran.

The simulator takes as input: a random seed, the set of operations to run, the invariants to test, and additional parameters to configure how long to run, and misc. parameters that affect simulation speed.

It is intended that every module provides a list of Operations which will randomly create and run a message / tx in a manner that is interesting to fuzz, and verify that the state transition was executed as expected. Each module should additionally provide methods to assert that the desired invariants hold.

Then to perform a randomized simulation, select the set of desired operations, the weightings for each, the invariants you want to test, and how long to run it for. Then run simulation.Simulate! The simulator will handle things like ensuring that validators periodically double signing, or go offline.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeriveRand added in v0.27.0

func DeriveRand(r *rand.Rand) *rand.Rand

Derive a new rand deterministically from a rand. Unlike rand.New(rand.NewSource(seed)), the result is "more random" depending on the source and state of r. NOTE: not crypto safe.

func GetMemberOfInitialState

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 RandStringOfLength

func RandStringOfLength(r *rand.Rand, n int) string

shamelessly copied from https://stackoverflow.com/questions/22892120/how-to-generate-a-random-string-of-a-fixed-length-in-golang#31832326 Generate a random string of a particular length

func RandTimestamp added in v0.27.0

func RandTimestamp(r *rand.Rand) time.Time

RandTimestamp generates a random timestamp

func RandomAmount

func RandomAmount(r *rand.Rand, max sdk.Int) sdk.Int

Generate a random amount

func RandomDecAmount added in v0.26.0

func RandomDecAmount(r *rand.Rand, max sdk.Dec) sdk.Dec

RandomDecAmount generates a random decimal amount

func RandomRequestBeginBlock

func RandomRequestBeginBlock(r *rand.Rand, params Params,
	validators mockValidators, pastTimes []time.Time,
	pastVoteInfos [][]abci.VoteInfo,
	event func(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

func RandomSetGenesis added in v0.25.0

func RandomSetGenesis(r *rand.Rand, app *mock.App, accs []Account, denoms []string)

RandomSetGenesis wraps mock.RandomSetGenesis, but using simulation accounts

func Simulate

func Simulate(t *testing.T, app *baseapp.BaseApp,
	appStateFn AppStateFn, ops WeightedOperations,
	invariants Invariants, numBlocks int, blockSize int, commit bool) (bool, error)

Simulate tests application by sending random messages.

func SimulateFromSeed

func SimulateFromSeed(tb testing.TB, app *baseapp.BaseApp,
	appStateFn AppStateFn, seed int64, ops WeightedOperations,
	invariants Invariants,
	numBlocks int, blockSize int, commit bool) (stopEarly bool, simError error)

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

Types

type Account added in v0.25.0

type Account struct {
	PrivKey crypto.PrivKey
	PubKey  crypto.PubKey
	Address sdk.AccAddress
}

Account contains a privkey, pubkey, address tuple eventually more useful data can be placed in here. (e.g. number of coins)

func RandomAcc added in v0.25.0

func RandomAcc(r *rand.Rand, accs []Account) Account

RandomAcc pick a random account from an array

func RandomAccounts added in v0.25.0

func RandomAccounts(r *rand.Rand, n int) []Account

RandomAccounts generates n random accounts

func (Account) Equals added in v0.25.0

func (acc Account) Equals(acc2 Account) bool

are two accounts equal

type AppStateFn added in v0.27.0

type AppStateFn func(r *rand.Rand, accs []Account) json.RawMessage

AppStateFn returns the app state json bytes

type FutureOperation added in v0.25.0

type FutureOperation struct {
	BlockHeight int
	BlockTime   time.Time
	Op          Operation
}

FutureOperation is an operation which will be ran at the beginning of the provided BlockHeight. If both a BlockHeight and BlockTime are specified, it will use the BlockHeight. In the (likely) event that multiple operations are queued at the same block height, they will execute in a FIFO pattern.

type Invariant

type Invariant func(ctx sdk.Context) error

An Invariant is a function which tests a particular invariant. If the invariant has been broken, it should return an error containing a descriptive message about what happened. The simulator will then halt and print the logs.

func PeriodicInvariant

func PeriodicInvariant(invariant Invariant, period int, offset int) Invariant

PeriodicInvariant returns an Invariant function closure that asserts a given invariant if the mock application's last block modulo the given period is congruent to the given offset.

NOTE this function is intended to be used manually used while running computationally heavy simulations. TODO reference this function in the codebase probably through use of a switch

type Invariants added in v0.27.0

type Invariants []Invariant

group of Invarient

type Operation added in v0.25.0

type Operation func(r *rand.Rand, app *baseapp.BaseApp,
	ctx sdk.Context, accounts []Account, event func(string)) (
	action string, futureOps []FutureOperation, err error)

Operation runs a state machine transition, and ensures the transition happened as expected. The operation could be running and testing a fuzzed transaction, or doing the same for a message.

For ease of debugging, an operation returns a descriptive message "action", which details what this fuzzed state machine transition actually did.

Operations can optionally provide a list of "FutureOperations" to run later These will be ran at the beginning of the corresponding block.

type OperationQueue added in v0.27.0

type OperationQueue map[int][]Operation

queue of operations

type Params added in v0.26.0

type Params struct {
	PastEvidenceFraction      float64
	NumKeys                   int
	EvidenceFraction          float64
	InitialLivenessWeightings []int
	LivenessTransitionMatrix  TransitionMatrix
	BlockSizeTransitionMatrix TransitionMatrix
}

Simulation parameters

func DefaultParams added in v0.26.0

func DefaultParams() Params

Return default simulation parameters

func RandomParams added in v0.26.0

func RandomParams(r *rand.Rand) Params

Return random simulation parameters

type TransitionMatrix

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 CreateTransitionMatrix

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

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

func (TransitionMatrix) NextState

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 added in v0.25.0

type WeightedOperation struct {
	Weight int
	Op     Operation
}

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

type WeightedOperations added in v0.27.0

type WeightedOperations []WeightedOperation

WeightedOperations is the group of all weighted operations to simulate.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL