# Module Simulation
This document details how to define each module simulation functions to be
integrated with the application
- Simulation package
- Registering the module simulation functions
- App simulator manager
- Simulation tests
# Simulation package
Every module that implements the Cosmos SDK simulator needs to have a
package which contains the primary functions required by the fuzz tests: store
decoders, randomized genesis state and parameters, weighted operations and proposal
# Store decoders
Registering the store decoders is required for the
AppImportExport. This allows
for the key-value pairs from the stores to be decoded (i.e unmarshalled)
to their corresponding types. In particular, it matches the key to a concrete type
and then unmarshals the value from the
KVPair to the type provided.
You can use the example here (opens new window) from the distribution module to implement your store decoders.
# Randomized genesis
The simulator tests different scenarios and values for genesis parameters
in order to fully test the edge cases of specific modules. The
simulator package from each module must expose a
RandomizedGenState function to generate the initial random
GenesisState from a given seed.
Once the module genesis parameter are generated randomly (or with the key and
values defined in a
params file), they are marshaled to JSON format and added
to the app genesis JSON to use it on the simulations.
You can check an example on how to create the randomized genesis here (opens new window).
# Randomized parameter changes
The simulator is able to test parameter changes at random. The simulator package from each module must contain a
RandomizedParams func that will simulate parameter changes of the module throughout the simulations lifespan.
You can see how an example of what is needed to fully test parameter changes here (opens new window)
# Random weighted operations
Operations are one of the crucial parts of the Cosmos SDK simulation. They are the transactions
Msg) that are simulated with random field values. The sender of the operation
is also assigned randomly.
Operations on the simulation are simulated using the full transaction cycle of a
ABCI application that exposes the
Shown below is how weights are set:
As you can see, the weights are predefined in this case. Options exist to override this behavior with different weights. One option is to use
*rand.Rand to define a random weight for the operation, or you can inject your own predefined weights.
Here is how one can override the above package
For the last test a tool called runsim is used, this is used to parallelize go test instances, provide info to Github and slack integrations to provide information to your team on how the simulations are running.
# Random proposal contents
Randomized governance proposals are also supported on the Cosmos SDK simulator. Each
module must define the governance proposal
Contents that they expose and register
them to be used on the parameters.
# Registering simulation functions
Now that all the required functions are defined, we need to integrate them into the module pattern within the
# App Simulator manager
The following step is setting up the
SimulatorManager at the app level. This
is required for the simulation test files on the next step.
Then at the instantiation of the application, we create the
instance in the same way we create the
ModuleManager but this time we only pass
the modules that implement the simulation functions from the
interface described above.