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 ¶
- func DisplayEvents(events map[string]uint)
- func GetMemberOfInitialState(r *rand.Rand, weights []int) int
- func RandStringOfLength(r *rand.Rand, n int) string
- func RandomAmount(r *rand.Rand, max int64) int64
- func RandomRequestBeginBlock(r *rand.Rand, validators map[string]mockValidator, ...) abci.RequestBeginBlock
- func RandomSetGenesis(r *rand.Rand, app *mock.App, accs []Account, denoms []string)
- func Simulate(t *testing.T, app *baseapp.BaseApp, ...) error
- func SimulateFromSeed(tb testing.TB, app *baseapp.BaseApp, ...) (simError error)
- type Account
- type FutureOperation
- type Invariant
- type Operation
- type RandSetup
- type TransitionMatrix
- type WeightedOperation
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetMemberOfInitialState ¶
GetMemberOfInitialState takes an initial array of weights, of size n. It returns a weighted random number in [0,n).
func RandStringOfLength ¶
Generate a random string of a particular length
func RandomRequestBeginBlock ¶
func RandomRequestBeginBlock(r *rand.Rand, validators map[string]mockValidator, livenessTransitions TransitionMatrix, evidenceFraction float64, 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 nolint: unparam
func RandomSetGenesis ¶
RandomSetGenesis wraps mock.RandomSetGenesis, but using simulation accounts
func Simulate ¶
func Simulate(t *testing.T, app *baseapp.BaseApp, appStateFn func(r *rand.Rand, accs []Account) json.RawMessage, ops []WeightedOperation, setups []RandSetup, invariants []Invariant, numBlocks int, blockSize int, commit bool) error
Simulate tests application by sending random messages.
func SimulateFromSeed ¶
func SimulateFromSeed(tb testing.TB, app *baseapp.BaseApp, appStateFn func(r *rand.Rand, accs []Account) json.RawMessage, seed int64, ops []WeightedOperation, setups []RandSetup, invariants []Invariant, numBlocks int, blockSize int, commit bool) (simError error)
SimulateFromSeed tests an application by running the provided operations, testing the provided invariants, but using the provided seed.
Types ¶
type Account ¶
Account contains a privkey, pubkey, address tuple eventually more useful data can be placed in here. (e.g. number of coins)
func RandomAccounts ¶
RandomAccounts generates n random accounts
type FutureOperation ¶
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 ¶
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.
type Operation ¶
type Operation func(r *rand.Rand, app *baseapp.BaseApp, ctx sdk.Context, accounts []Account, event func(string), ) (action string, futureOperations []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 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
type WeightedOperation ¶
WeightedOperation is an operation with associated weight. This is used to bias the selection operation within the simulator.
Source Files