Backtesting Reference

This page provides detailed reference documentation for all backtesting configuration options, API methods, and data structures.

New to backtesting? Start with the Backtesting Guide to understand the basics before diving into this reference.

Configuration Parameters

`targetContract`

The address of the contract (Assertion Adopter) to test assertions against. The backtesting tool will find all transactions that interact with this contract, including both direct calls and internal calls (e.g., through routers or aggregators).

targetContract: 0x5fd84259d66Cd46123540766Be93DFE6D43130D7

`endBlock`

The last block in the range to test. The tool runs on the block range from endBlock - blockRange to endBlock.

endBlock: 31336940  // Test up to this block

`blockRange`

Number of blocks to test, counting backwards from endBlock. The tool will test blocks from endBlock - blockRange to endBlock.

blockRange: 100  // Tests blocks 31336841 to 31336940 if endBlock is 31336940

To test against a specific transaction, set blockRange: 1 with the block number containing that transaction. This is useful for validating assertions against known exploit transactions. See the Balancer V2 Rate Manipulation Exploit for a real-world example.

`assertionCreationCode`

The bytecode of your assertion contract. Use type(YourAssertion).creationCode to get this value.

assertionCreationCode: type(MyAssertion).creationCode

`assertionSelector`

The function selector of the assertion function to trigger. This determines which assertion method runs during validation.

assertionSelector: MyAssertion.assertionBatchAccountHealth.selector

`rpcUrl`

The RPC endpoint URL to use for fetching blockchain data. Can also be set via the RPC_URL environment variable.

rpcUrl: "https://sepolia.optimism.io"
// or
rpcUrl: vm.envString("MAINNET_RPC_URL")

`forkByTxHash`

Controls how the EVM state is forked for each transaction replay. This parameter is kept for interface compatibility but is effectively always true internally to ensure correct pre-transaction state.

forkByTxHash: true  // Default and recommended

`detailedBlocks`

Controls logging verbosity. Currently reserved for future functionality.

detailedBlocks: false // Standard output

API Reference

executeBacktest

Executes a backtest with the provided configuration and returns detailed results.

function executeBacktest(
    BacktestingTypes.BacktestingConfig memory config
) public returns (BacktestingTypes.BacktestingResults memory results)

Parameters:

config: Configuration struct containing all backtesting parameters

Returns:

results: Results struct containing test execution statistics

Example:

BacktestingTypes.BacktestingResults memory results = executeBacktest(
    BacktestingTypes.BacktestingConfig({
        targetContract: 0x5fd84259d66Cd46123540766Be93DFE6D43130D7,
        endBlock: 31336940,
        blockRange: 20,
        assertionCreationCode: type(MyAssertion).creationCode,
        assertionSelector: MyAssertion.assertionInvariant.selector,
        rpcUrl: "https://sepolia.optimism.io",
        detailedBlocks: false,
        forkByTxHash: true
    })
);

executeBacktestForTransaction

Executes a backtest for a single transaction specified by its hash. This is useful for:

Testing assertions against specific known transactions (such as historical exploits)
Debugging potential false positives reported during staging (see Testing Strategy for more on the staging workflow)
Quickly validating assertion behavior on a problematic transaction without specifying a block range

function executeBacktestForTransaction(
    bytes32 txHash,
    address targetContract,
    bytes memory assertionCreationCode,
    bytes4 assertionSelector,
    string memory rpcUrl
) public returns (BacktestingTypes.BacktestingResults memory results)

Parameters:

txHash: The transaction hash to backtest
targetContract: The target contract address (assertion adopter)
assertionCreationCode: The assertion contract creation code
assertionSelector: The assertion function selector
rpcUrl: The RPC URL to use

Returns:

results: Results struct containing test execution statistics

Example:

bytes32 exploitTxHash = 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef;

BacktestingTypes.BacktestingResults memory results = executeBacktestForTransaction(
    exploitTxHash,
    TARGET_CONTRACT,
    type(MyAssertion).creationCode,
    MyAssertion.assertionInvariant.selector,
    vm.envString("MAINNET_RPC_URL")
);

// Expect the assertion to catch the exploit
assertEq(results.assertionFailures, 1, "Assertion should catch the exploit");

BacktestingConfig

Configuration struct for backtesting parameters.

struct BacktestingConfig {
    address targetContract;             // Contract to test
    uint256 endBlock;                   // Latest block in range
    uint256 blockRange;                 // Number of blocks to test
    bytes assertionCreationCode;        // Assertion contract bytecode
    bytes4 assertionSelector;           // Assertion function selector
    string rpcUrl;                      // RPC endpoint
    bool detailedBlocks;                // Detailed logging (reserved)
    bool forkByTxHash;                  // Fork at exact transaction
}

Field Descriptions:

Field	Type	Description
`targetContract`	`address`	Contract address to test assertions against
`endBlock`	`uint256`	Most recent block in the test range
`blockRange`	`uint256`	Number of blocks to test backwards from `endBlock`
`assertionCreationCode`	`bytes`	Bytecode of the assertion contract
`assertionSelector`	`bytes4`	Function selector of the assertion to execute
`rpcUrl`	`string`	RPC endpoint URL for blockchain data
`detailedBlocks`	`bool`	Enable detailed logging (reserved for future use)
`forkByTxHash`	`bool`	Fork at exact transaction (kept for interface compatibility)

BacktestingResults

Results struct returned after backtesting execution.

struct BacktestingResults {
    uint256 totalTransactions;      // Total transactions found
    uint256 processedTransactions;  // Transactions validated
    uint256 successfulValidations;  // Passing validations
    uint256 skippedTransactions;    // Transactions where assertion wasn't triggered
    uint256 assertionFailures;      // Protocol violations detected
    uint256 replayFailures;         // Transactions that failed to replay
    uint256 unknownErrors;          // Unexpected errors
}

Field Descriptions:

Field	Type	Description
`totalTransactions`	`uint256`	Total number of transactions found in the block range
`processedTransactions`	`uint256`	Number of transactions that were validated
`successfulValidations`	`uint256`	Transactions that passed validation
`skippedTransactions`	`uint256`	Transactions where the assertion wasn’t triggered (function selector didn’t match)
`assertionFailures`	`uint256`	Number of protocol violations detected (assertion reverted)
`replayFailures`	`uint256`	Transactions that failed to replay before assertion could execute
`unknownErrors`	`uint256`	Unexpected errors during execution

Interpreting Results: The assertionFailures field indicates how many transactions triggered assertion reverts. Since backtesting runs against historical transactions, non-zero values most commonly indicate false positives in your assertion logic rather than actual exploits.

// Check results
if (results.assertionFailures > 0) {
    console.log("Assertion failures detected:", results.assertionFailures);
    console.log("Review assertion logic for false positives or gas issues");
}

// Log detailed results
console.log("Total transactions:", results.totalTransactions);
console.log("Successful validations:", results.successfulValidations);
console.log("Skipped transactions:", results.skippedTransactions);
console.log("Assertion failures:", results.assertionFailures);

Common Causes of Assertion Failures:

False positives: Assertion logic incorrectly flags legitimate protocol behavior (most common)
Gas limit exceeded: Assertion ran out of gas (300k limit) during complex operations
Assertion bugs: Logic errors in the assertion code
Known exploits: If testing against historical exploit blocks, failures may be expected

See the Understanding Results section in the Backtesting Guide for detailed information on all result categories.

Example Configurations

Standard Configuration

Basic configuration suitable for most backtesting scenarios:

BacktestingTypes.BacktestingConfig({
    targetContract: TARGET_CONTRACT,
    endBlock: LATEST_BLOCK,
    blockRange: 100,
    assertionCreationCode: type(MyAssertion).creationCode,
    assertionSelector: MyAssertion.assertionInvariant.selector,
    rpcUrl: vm.envString("MAINNET_RPC_URL"),
    detailedBlocks: false,
    forkByTxHash: true
})

See the Backtesting Guide for more configuration examples including debugging and quick test scenarios.

Learn More

Full API Reference

Autogenerated API documentation for backtesting

Backtesting Guide

Learn how to use backtesting to validate assertions

Testing Assertions

Basic testing guide for assertions

CI/CD Integration

Automate your testing workflow

Fuzz Testing

Use fuzz testing to test assertions

Getting Started

Architecture

Assertions

dApp

Guides

Reference

Resources

Configuration Parameters

`targetContract`

`endBlock`

`blockRange`

`assertionCreationCode`

`assertionSelector`

`rpcUrl`

`forkByTxHash`

`detailedBlocks`

API Reference

executeBacktest

executeBacktestForTransaction

BacktestingConfig

BacktestingResults

Example Configurations

Standard Configuration

Learn More

Full API Reference

Backtesting Guide

Testing Assertions

CI/CD Integration

Fuzz Testing

​Configuration Parameters

​targetContract

​endBlock

​blockRange

​assertionCreationCode

​assertionSelector

​rpcUrl

​forkByTxHash

​detailedBlocks

​API Reference

​executeBacktest

​executeBacktestForTransaction

​BacktestingConfig

​BacktestingResults

​Example Configurations

​Standard Configuration

​Learn More

Full API Reference

Backtesting Guide

Testing Assertions

CI/CD Integration

Fuzz Testing

Configuration Parameters

`targetContract`

`endBlock`

`blockRange`

`assertionCreationCode`

`assertionSelector`

`rpcUrl`

`forkByTxHash`

`detailedBlocks`

API Reference

executeBacktest

executeBacktestForTransaction

BacktestingConfig

BacktestingResults

Example Configurations

Standard Configuration

Learn More