Corpus (crytic#11)

* Added corpus with support for storing coverage-increasing call sequences, computing coverage on startup for those sequences, etc.
* Update to only commit coverage in call frames which succeeded (did not revert) in the CoverageTracer.
* Updated serialization format for coverage maps and call message to use hex strings rather than base64.
* Fix for TxContext during TestChain block production
* Changed coverage to be collected per deployment address/code hash
* Added support for init bytecode coverage in CoverageMaps
* Added DeploymentOrder configuration variable which explicitly dictates the order for contracts to be deployed in (for corpus determinism).
* Refactoring of Fuzzer unit test API
* Improved bytecode matching
* Added validation for DeploymentOrder
* Added events throughout Fuzzer/FuzzerWorker, moved TestCaseProvider to be event/hook driven.
* Made EventEmitter's accepted event handlers always return an error type (so errors can be passed around). Refactored all usages of it.


Co-authored-by: David Pokora <[email protected]>

Author: anishnaik

README.md

@@ -25,6 +25,9 @@ An example project configuration can be observed below:
 		"timeout": 0,
 		"testLimit": 10000000,
 		"maxTxSequenceLength": 100,
+		"corpusDirectory": "corpus",
+		"coverageEnabled": true,
+		"deploymentOrder": ["TestXY", "TestContract2"],
 		"deployerAddress": "0x1111111111111111111111111111111111111111",
 		"senderAddresses": [
 			"0x1111111111111111111111111111111111111111",
@@ -63,8 +66,14 @@ The structure is described below:
   - `timeout` 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 is starting.
   - `testLimit` refers to a threshold of the number of function calls to make before the fuzzing campaign should be terminated. Must be a non-negative number. If a zero value is provided, no call limit will be enforced.
   - `maxTxSequenceLength` defines the maximum number of function calls to generate in a single sequence that tries to violate property tests. For property tests which require many calls to violate, this number should be set sufficiently high.
+  - `corpusDirectory` 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. coverage-increasing call sequences which the fuzzer collects to be mutates).
+  - `coverageEnabled` refers to whether coverage-increasing call sequences should be saved in the corpus for the fuzzer to mutate. This aims to help achieve greater coverage across contracts when testing.
+  - `deploymentOrder` refers to the order in which compiled contracts (contracts resulting from compilation, as specified by the `compilation` config) should be deployed to the fuzzer on startup. At least one contract name must be specified here. 
+    - **Note**: Changing this order may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.
   - `deployerAddress` defines the account address used to deploy contracts on startup, represented as a hex string.
+      - **Note**: Changing this address may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.
   - `senderAddresses` defines the account addresses used to send function calls to deployed contracts in the fuzzing campaign.
+      - **Note**: Removing previously existing addresses may render entries in the corpus invalid. It is recommended to clear your corpus when doing so.
   - `testing` defines the configuration for built-in test case providers which can be leveraged for fuzzing campaign.
     - `stopOnFailedTest` defines whether the fuzzer should exit after detecting the first failed test, or continue fuzzing to find other results.
     - `assertionTesting` describes configuration for assertion-based testing.

chain/test_chain.go

@@ -64,14 +64,16 @@ type TestChain struct {
 	// such as whether certain fees should be charged and which execution tracer should be used (if any).
 	vmConfig *vm.Config
 
-	// BlockAddedEventEmitter serves events indicating a block was added to the chain.
-	BlockAddedEventEmitter events.EventEmitter[BlockAddedEvent]
-	// BlockRemovedEventEmitter serves events indicating a block was removed from the chain.
+	// BlockMiningEventEmitter emits events indicating a block was added to the chain.
+	BlockMiningEventEmitter events.EventEmitter[BlockMiningEvent]
+	// BlockMinedEventEmitter emits events indicating a block was added to the chain.
+	BlockMinedEventEmitter events.EventEmitter[BlockMinedEvent]
+	// BlockRemovedEventEmitter emits events indicating a block was removed from the chain.
 	BlockRemovedEventEmitter events.EventEmitter[BlockRemovedEvent]
 
-	// ContractDeploymentAddedEventEmitter serves events indicating a new contract was deployed to the chain.
+	// ContractDeploymentAddedEventEmitter emits events indicating a new contract was deployed to the chain.
 	ContractDeploymentAddedEventEmitter events.EventEmitter[ContractDeploymentsAddedEvent]
-	// ContractDeploymentAddedEventEmitter serves events indicating a previously deployed contract was removed
+	// ContractDeploymentAddedEventEmitter emits events indicating a previously deployed contract was removed
 	// from the chain.
 	ContractDeploymentRemovedEventEmitter events.EventEmitter[ContractDeploymentsRemovedEvent]
 }
@@ -204,7 +206,7 @@ func (t *TestChain) CopyTo(targetChain *TestChain) error {
 	for i := 1; i < len(t.blocks); i++ {
 		blockHeader := t.blocks[i].Header()
 		blockNumber := blockHeader.Number.Uint64()
-		_, err := targetChain.CreateNewBlockWithParameters(blockNumber, blockHeader.Time, t.blocks[i].Messages()...)
+		_, err := targetChain.MineBlockWithParameters(blockNumber, blockHeader.Time, t.blocks[i].Messages()...)
 		if err != nil {
 			return err
 		}
@@ -227,6 +229,12 @@ func (t *TestChain) MemoryDatabaseEntryCount() int {
 	return t.keyValueStore.Len()
 }
 
+// CommittedBlocks returns the real blocks which were committed to the chain, where methods such as BlockFromNumber
+// return the simulated chain state with intermediate blocks injected for block number jumps, etc.
+func (t *TestChain) CommittedBlocks() []*chainTypes.Block {
+	return t.blocks
+}
+
 // Head returns the head of the chain (the latest block).
 func (t *TestChain) Head() *chainTypes.Block {
 	return t.blocks[len(t.blocks)-1]
@@ -418,19 +426,25 @@ func (t *TestChain) RevertToBlockNumber(blockNumber uint64) error {
 	// Emit our events for newly deployed contracts
 	for i := len(removedBlocks) - 1; i >= 0; i-- {
 		// Emit our event for removing a block
-		t.BlockRemovedEventEmitter.Publish(BlockRemovedEvent{
+		err := t.BlockRemovedEventEmitter.Publish(BlockRemovedEvent{
 			Chain: t,
 			Block: removedBlocks[i],
 		})
+		if err != nil {
+			return err
+		}
 
 		// For each call message in our block, if we had any resulting deployed smart contracts, signal that they have
 		// now been removed.
 		for _, messageResult := range removedBlocks[i].MessageResults() {
 			if len(messageResult.DeployedContractBytecodes) > 0 {
-				t.ContractDeploymentRemovedEventEmitter.Publish(ContractDeploymentsRemovedEvent{
+				err = t.ContractDeploymentRemovedEventEmitter.Publish(ContractDeploymentsRemovedEvent{
 					Chain:                     t,
 					DeployedContractBytecodes: messageResult.DeployedContractBytecodes,
 				})
+				if err != nil {
+					return err
+				}
 			}
 		}
 	}
@@ -450,6 +464,7 @@ func (t *TestChain) CreateMessage(from common.Address, to *common.Address, value
 	gasPrice := big.NewInt(1)
 
 	// Setting fee and tip cap to zero alongside the NoBaseFee for the vm.Config will bypass base fee validation.
+	// TODO: Set this appropriately for newer transaction types.
 	gasFeeCap := big.NewInt(0)
 	gasTipCap := big.NewInt(0)
 
@@ -471,7 +486,7 @@ func (t *TestChain) CallContract(msg *chainTypes.CallMessage) (*core.ExecutionRe
 	txContext := core.NewEVMTxContext(msg)
 	blockContext := newTestChainBlockContext(t, t.Head().Header())
 
-	// Create our EVM instance
+	// Create our EVM instance.
 	evm := vm.NewEVM(blockContext, txContext, t.state, t.chainConfig, vm.Config{NoBaseFee: true})
 
 	// Fund the gas pool, so it can execute endlessly (no block gas limit).
@@ -486,21 +501,31 @@ func (t *TestChain) CallContract(msg *chainTypes.CallMessage) (*core.ExecutionRe
 	return res, err
 }
 
-// CreateNewBlock takes messages (internal txs) and constructs a block with them, similar to a real chain using
-// transactions to construct a block. Returns the constructed block, or an error if one occurred.
-func (t *TestChain) CreateNewBlock(messages ...*chainTypes.CallMessage) (*chainTypes.Block, error) {
+// MineBlock takes messages (internal txs), constructs a block with them, and updates the chain head, similar to a
+// real chain using  transactions to construct a block.
+// Returns the constructed block, or an error if one occurred.
+func (t *TestChain) MineBlock(messages ...*chainTypes.CallMessage) (*chainTypes.Block, error) {
 	// Create a block with default parameters
 	blockNumber := t.HeadBlockNumber() + 1
 	timestamp := t.Head().Header().Time + 1 // TODO: Find a sensible default step for timestamp.
-	return t.CreateNewBlockWithParameters(blockNumber, timestamp, messages...)
+	return t.MineBlockWithParameters(blockNumber, timestamp, messages...)
 }
 
-// CreateNewBlockWithParameters takes messages (internal txs) and constructs a block with them, similar to a real chain
-// using transactions to construct a block. It accepts block header parameters used to produce the block. Values
-// should be sensibly chosen (e.g., block number and timestamps should be greater than the previous block).
-// Providing a block number that is greater than the previous block number plus one will simulate empty blocks between.
+// MineBlockWithParameters takes messages (internal txs), constructs a block with them, and updates the chain head,
+// similar to a real chain using transactions to construct a block. It accepts block header parameters used to produce
+// the block. Values should be sensibly chosen (e.g., block number and timestamps should be greater than the previous
+// block). Providing a block number that is greater than the previous block number plus one will simulate empty blocks
+// between.
 // Returns the constructed block, or an error if one occurred.
-func (t *TestChain) CreateNewBlockWithParameters(blockNumber uint64, blockTime uint64, messages ...*chainTypes.CallMessage) (*chainTypes.Block, error) {
+func (t *TestChain) MineBlockWithParameters(blockNumber uint64, blockTime uint64, messages ...*chainTypes.CallMessage) (*chainTypes.Block, error) {
+	// Emit our event for mining a new block
+	err := t.BlockMiningEventEmitter.Publish(BlockMiningEvent{
+		Chain: t,
+	})
+	if err != nil {
+		return nil, err
+	}
+
 	// Validate our block number exceeds our previous head
 	currentHeadBlockNumber := t.Head().Header().Number.Uint64()
 	if blockNumber <= currentHeadBlockNumber {
@@ -546,7 +571,7 @@ func (t *TestChain) CreateNewBlockWithParameters(blockNumber uint64, blockTime u
 		Bloom:       types.Bloom{},
 		Difficulty:  common.Big0,
 		Number:      big.NewInt(int64(blockNumber)),
-		GasLimit:    t.GasLimit(), // re-used from previous block
+		GasLimit:    t.GasLimit(),
 		GasUsed:     0,
 		Time:        blockTime,
 		Extra:       []byte{},
@@ -572,7 +597,7 @@ func (t *TestChain) CreateNewBlockWithParameters(blockNumber uint64, blockTime u
 		blockContext := newTestChainBlockContext(t, header)
 
 		// Create our EVM instance.
-		evm := vm.NewEVM(blockContext, vm.TxContext{}, t.state, t.chainConfig, *t.vmConfig)
+		evm := vm.NewEVM(blockContext, core.NewEVMTxContext(messages[i]), t.state, t.chainConfig, *t.vmConfig)
 
 		// Apply our transaction
 		var usedGas uint64
@@ -617,19 +642,25 @@ func (t *TestChain) CreateNewBlockWithParameters(blockNumber uint64, blockTime u
 	// Append our new block to our chain.
 	t.blocks = append(t.blocks, block)
 
-	// Emit our event for adding a new block
-	t.BlockAddedEventEmitter.Publish(BlockAddedEvent{
+	// Emit our event for mining a new block
+	err = t.BlockMinedEventEmitter.Publish(BlockMinedEvent{
 		Chain: t,
 		Block: block,
 	})
+	if err != nil {
+		return nil, err
+	}
 
 	// Emit our events for newly deployed contracts
 	for _, messageResult := range messageResults {
 		if len(messageResult.DeployedContractBytecodes) > 0 {
-			t.ContractDeploymentAddedEventEmitter.Publish(ContractDeploymentsAddedEvent{
+			err = t.ContractDeploymentAddedEventEmitter.Publish(ContractDeploymentsAddedEvent{
 				Chain:                     t,
 				DeployedContractBytecodes: messageResult.DeployedContractBytecodes,
 			})
+			if err != nil {
+				return nil, err
+			}
 		}
 	}
 
@@ -655,7 +686,7 @@ func (t *TestChain) DeployContract(contract *compilationTypes.CompiledContract,
 	msg := t.CreateMessage(deployer, nil, value, b)
 
 	// Create a new block with our deployment message/tx.
-	block, err := t.CreateNewBlock(msg)
+	block, err := t.MineBlock(msg)
 	if err != nil {
 		return common.Address{}, nil, err
 	}

chain/test_chain_events.go

@@ -2,9 +2,15 @@ package chain
 
 import "github.com/trailofbits/medusa/chain/types"
 
-// BlockAddedEvent describes an event where a new block is added to the TestChain. This only considers internally
-// committed blocks, not ones spoofed in between block number jumps.
-type BlockAddedEvent struct {
+// BlockMiningEvent describes an event where a new block has been requested to be mined in the TestChain. This only
+// considers committed blocks.
+type BlockMiningEvent struct {
+	// Chain refers to the TestChain which emitted the event.
+	Chain *TestChain
+}
+
+// BlockMinedEvent describes an event where a new block is added to the TestChain. This only considers committed blocks.
+type BlockMinedEvent struct {
 	// Chain refers to the TestChain which emitted the event.
 	Chain *TestChain
 

chain/test_chain_test.go

@@ -98,7 +98,7 @@ func TestChainReverting(t *testing.T) {
 		// Determine if this will jump a certain number of blocks.
 		if rand.Float32() >= blockNumberJumpProbability {
 			// We decided not to jump, so we commit a block with a normal consecutive block number.
-			_, err := chain.CreateNewBlock()
+			_, err := chain.MineBlock()
 			assert.NoError(t, err)
 		} else {
 			// We decided to jump, so we commit a block with a random jump amount.
@@ -110,7 +110,7 @@ func TestChainReverting(t *testing.T) {
 			// the diff.
 
 			// Create a block with our parameters
-			_, err := chain.CreateNewBlockWithParameters(newBlockNumber, chain.Head().Header().Time+jumpDistance)
+			_, err := chain.MineBlockWithParameters(newBlockNumber, chain.Head().Header().Time+jumpDistance)
 			assert.NoError(t, err)
 		}
 
@@ -158,7 +158,7 @@ func TestChainBlockNumberJumping(t *testing.T) {
 		// Determine if this will jump a certain number of blocks.
 		if rand.Float32() >= blockNumberJumpProbability {
 			// We decided not to jump, so we commit a block with a normal consecutive block number.
-			_, err := chain.CreateNewBlock()
+			_, err := chain.MineBlock()
 			assert.NoError(t, err)
 		} else {
 			// We decided to jump, so we commit a block with a random jump amount.
@@ -170,7 +170,7 @@ func TestChainBlockNumberJumping(t *testing.T) {
 			// the diff.
 
 			// Create a block with our parameters
-			_, err := chain.CreateNewBlockWithParameters(newBlockNumber, chain.Head().Header().Time+jumpDistance)
+			_, err := chain.MineBlockWithParameters(newBlockNumber, chain.Head().Header().Time+jumpDistance)
 			assert.NoError(t, err)
 		}
 	}
@@ -233,7 +233,7 @@ func TestChainDynamicDeployments(t *testing.T) {
 
 						// Create some empty blocks and ensure we can get our state for this block number.
 						for x := 0; x < 5; x++ {
-							block, err = chain.CreateNewBlock()
+							block, err = chain.MineBlock()
 							assert.NoError(t, err)
 
 							// Empty blocks should not record message results or dynamic deployments.
@@ -298,7 +298,7 @@ func TestChainCloning(t *testing.T) {
 
 							// Create some empty blocks and ensure we can get our state for this block number.
 							for x := 0; x < i; x++ {
-								_, err = chain.CreateNewBlock()
+								_, err = chain.MineBlock()
 								assert.NoError(t, err)
 
 								_, err = chain.StateAfterBlockNumber(chain.HeadBlockNumber())
@@ -364,7 +364,7 @@ func TestChainCallSequenceReplayMatchSimple(t *testing.T) {
 
 							// Create some empty blocks and ensure we can get our state for this block number.
 							for x := 0; x < i; x++ {
-								_, err = chain.CreateNewBlock()
+								_, err = chain.MineBlock()
 								assert.NoError(t, err)
 
 								_, err = chain.StateAfterBlockNumber(chain.HeadBlockNumber())
@@ -382,7 +382,7 @@ func TestChainCallSequenceReplayMatchSimple(t *testing.T) {
 
 		// Replay all messages after genesis
 		for i := 1; i < len(chain.blocks); i++ {
-			_, err := recreatedChain.CreateNewBlock(chain.blocks[i].Messages()...)
+			_, err := recreatedChain.MineBlock(chain.blocks[i].Messages()...)
 			assert.NoError(t, err)
 		}
 

chain/test_chain_tracer.go

@@ -14,6 +14,9 @@ type testChainTracer struct {
 	// callDepth refers to the current EVM depth during tracing.
 	callDepth uint64
 
+	// evm refers to the EVM instance last captured.
+	evm *vm.EVM
+
 	// deployedContractBytecode is a list of all bytecode deployments found from the current/last transaction
 	// executed.
 	deployedContractBytecode []*types.DeployedContractBytecode
@@ -44,6 +47,9 @@ func (t *testChainTracer) CaptureTxEnd(restGas uint64) {
 
 // CaptureStart initializes the tracing operation for the top of a call frame, as defined by vm.EVMLogger.
 func (t *testChainTracer) CaptureStart(env *vm.EVM, from common.Address, to common.Address, create bool, input []byte, gas uint64, value *big.Int) {
+	// Store our evm reference
+	t.evm = env
+
 	// Create our stack item for pending deployments discovered at this call frame depth.
 	t.pendingDeployedContractBytecode = append(t.pendingDeployedContractBytecode, make([]*types.DeployedContractBytecode, 0))
 
@@ -64,6 +70,11 @@ func (t *testChainTracer) CaptureEnd(output []byte, gasUsed uint64, d time.Durat
 	// If we encountered an error, we reverted, so we don't consider the deployments.
 	if err == nil {
 		t.deployedContractBytecode = append(t.deployedContractBytecode, t.pendingDeployedContractBytecode[t.callDepth]...)
+
+		// Fetch runtime bytecode for all verified deployments.
+		for _, singleDeployment := range t.deployedContractBytecode {
+			singleDeployment.RuntimeBytecode = t.evm.StateDB.GetCode(singleDeployment.Address)
+		}
 	}
 
 	// Pop the pending contracts for this frame off the stack.