Project Configuration

The project configuration will dictate the compilation and fuzzing parameters for medusa. The fuzzing parameters are determined by the fuzzing configuration and the compilation parameters are determined by the compilation configuration. Thus, a project configuration is a combination of both the fuzzing and compilation configuration.

Note: Here is an example of a project configuration file

Fuzzing Configuration

The fuzzing configuration defines the parameters for the fuzzing campaign:

• workers
  • Type: Integer
  • Description: Defines the number of worker threads to parallelize fuzzing operations on.
• workerResetLimit
  • Type: Integer
  • Description: Defines how many call sequences a worker should process on its underlying chain before being fully reset, freeing memory. After resetting, the worker will be re-created and continue processing of call sequences.

  🚩 This setting, along with workers influence the speed and memory consumption of the fuzzer. Setting this value higher will result in greater memory consumption per worker. Setting it too high will result in the in-memory chain's database growing to a size that is slower to process. Setting it too low may result in frequent worker resets that are computationally expensive for complex contract deployments that need to be replayed during worker reconstruction.

• timeout
  • Type: Integer
  • Description: Refers to the number of seconds before the fuzzing campaign should be terminated. If a zero value is provided, the timeout will not be enforced. The timeout begins counting after compilation succeeds and the fuzzing campaign has started.
• testLimit
  • Type: Unsigned Integer
  • Description: Refers to a threshold of the number of function calls to make before the fuzzing campaign should be terminated. If a zero value is provided, no call limit will be enforced.
• callSequenceLength
  • Type: Integer
  • Description: Defines the maximum number of function calls to generate in a single call sequence in the attempt to violate properties. After every callSequenceLength function calls, the blockchain is reset for the next sequence of transactions.
• coverageEnabled
  • Type: Boolean
  • Description: Refers to whether coverage-increasing call sequences should be saved in the corpus for the fuzzer to mutate / re-use. This aims to help achieve greater coverage across contracts when testing.
• corpusDirectory
  • Type: String
  • Description: Refers to the path where the corpus should be saved. The corpus collects artifacts during a fuzzing campaign that help drive fuzzer features (e.g. a call sequence that increases code coverage is stored in the corpus. This sequence can then be re-used / mutated by the fuzzer).
• deploymentOrder
  • Type: [String] (e.g. [FirstContract, SecondContract, ThirdContract])
  • Description: Refers to the order in which the compiled contracts (contracts resulting from compilation, as specified by the compilation configuration(ADD LINK)) should be deployed to the fuzzer on startup. At least one contract name must be specified here.

  🚩 Changing this order may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.

• deployerAddress
  • Type: Address (e.g 0x10000)
  • Description: Defines the account address used to deploy contracts on startup, represented as a hex string.

  🚩 Changing this address may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.

• senderAddresses
  • Type: [Address] (e.g [0x10000, 0x20000, 0x30000])
  • Description: Defines the account addresses used to send function calls to deployed contracts in the fuzzing campaign.

  🚩 Changing these addresses may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.

• blockNumberDelayMax
  • Type: Unsigned Integer
  • Description: Defines the maximum block number jump the fuzzer should make between test transactions. The fuzzer will use this value to make the next block's block number between [1, blockNumberDelayMax] more than that of the previous block.
• blockTimestampDelayMax
  • Type: Unsigned Integer
  • Description: Defines the maximum block timestamp jump the fuzzer should make between test transactions. The fuzzer will use this value to make the next block's timestamp between [1, blockTimestampDelayMax] more than that of the previous block.
• blockGasLimit
  • Type: Unsigned Integer
  • Description: Defines the maximum amount of gas a block's transactions can use in total (thus defining max transactions per block).

  🚩 It is advised not to change this naively, as a minimum must be set for the chain to operate.

• transactionGasLimit
  • Type: Unsigned Integer
  • Description: Defines the amount of gas sent with each fuzzer-generated transaction.

  🚩 It is advised not to change this naively, as a minimum must be set for the chain to operate.

• testing
  • Type: Struct
  • Description: This struct will define the configuration for the various test-case providers that can be used with the fuzzer.
  • Components:
    • stopOnFailedTest
      • Type: Boolean
      • Description: Defines whether the fuzzer should exit after detecting the first failed test or continue fuzzing to find other results.
    • assertionTesting
      • Type: Struct
      • Description: This struct describes the configuration for assertion-based testing.
      • Components:
        • enabled
          • Type: Boolean
          • Description: Enable or disable assertion-based testing
        • testViewMethods
          • Type: Boolean
          • Description: Describes whether pure / view functions should be tested for assertion failures.
    • propertyTesting
      • Type: Struct
      • Description: This struct describes the configuration for property-based testing.
      • Components:
        • enabled
          • Type: Boolean
          • Description: Enable or disable property-based testing.
        • testPrefixes
          • Type: [String]
          • Description: Defines the list of prefixes that the fuzzer will use to determine whether a given function is a property test or not. For example, if fuzz_ is a test prefix, then any function name in the form fuzz_* may be a property test.

          Note: If you are moving over from Echidna, you can add echidna_ as a test prefix to quickly port over the property tests from it.

Compilation Configuration

The compilation configuration defines the parameters to use while compiling a target file or project:

• platform
  • Type: String
  • Description: Refers to the type of platform to be used to compile the underlying target. Currently, crytic-compile, truffle, or solc can be used as the compilation platform.
• platformConfig
  • Type: Struct
  • Description: This struct is a platform-dependent structure which offers parameters for compiling the underlying project. See below for the structure of platformConfig for each compilation platform

Note: The target parameter in each platformConfig below must be relative paths from the directory containing medusa's project configuration file.

platformConfig for each platform

crytic-compile

• target
  • Type: String
  • Description: Refers to the target that is being compiled. The target can be a single .sol file or a whole project (e.g. hardhat / foundry project).
• solcVersion
  • Type: String
  • Description: Describes the version of solc that will be installed and then used for compilation.
• exportDirectory
  • Type: String
  • Description: Describes the directory where all compilation artifacts will be stored.
• args
  • Type: [String]
  • Description: Refers to any additional args that one may want to provide to crytic-compile.

  🚩 The --export-format and --export-dir are already used during compilation with crytic-compile. Re-using these flags in args will cause the compilation to fail.

solc

• target
  • Type: String
  • Description: Refers to the target that is being compiled. The target must be a single .sol file.

truffle

• target
  • Type: String
  • Description: Refers to the target that is being compiled with truffle.
• useNpx
  • Type: Boolean
  • Description: Describes whether or not to use npx while performing compilation.
• command
  • Type: String
  • Description: Refers to a custom truffle command that can be used for compilation.
• buildDirectory
  • Type: String
  • Description: Describes the directory where all compilation artifacts will be stored.