> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phylax.systems/llms.txt
> Use this file to discover all available pages before exploring further.
# Backtesting Reference
> API reference for backtesting configuration and options
This page provides detailed reference documentation for all backtesting configuration options, API methods, and data structures.
New to backtesting? Start with the [Backtesting Guide](/credible/backtesting) to understand the basics before diving into this reference.
## Configuration Parameters
### `targetContract`
The address of the contract ([Assertion Adopter](/credible/glossary#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).
```solidity theme={null}
targetContract: 0x5fd84259d66Cd46123540766Be93DFE6D43130D7
```
### `endBlock`
The last block in the range to test. The tool runs on the block range from `endBlock - blockRange` to `endBlock`.
```solidity theme={null}
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`.
```solidity theme={null}
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](/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit) for a real-world example.
### `assertionCreationCode`
The bytecode of your assertion contract. Use `type(YourAssertion).creationCode` to get this value.
```solidity theme={null}
assertionCreationCode: type(MyAssertion).creationCode
```
### `assertionSelector`
The function selector of the assertion function to trigger. This determines which assertion method runs during validation.
```solidity theme={null}
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.
```solidity theme={null}
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.
```solidity theme={null}
forkByTxHash: true // Default and recommended
```
### `detailedBlocks`
Controls logging verbosity. Currently reserved for future functionality.
```solidity theme={null}
detailedBlocks: false // Standard output
```
## API Reference
### executeBacktest
Executes a backtest with the provided configuration and returns detailed results.
```solidity theme={null}
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:**
```solidity theme={null}
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 staging findings (see [How to Plan Assertion Testing](/credible/testing-strategy) for more on the staging workflow)
* Quickly validating assertion behavior on a problematic transaction without specifying a block range
```solidity theme={null}
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:**
```solidity theme={null}
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.
```solidity theme={null}
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.
```solidity theme={null}
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, review non-zero values to confirm whether they represent expected assertion behavior, logic that needs tuning, or a known exploit window.
```solidity theme={null}
// Check results
if (results.assertionFailures > 0) {
console.log("Assertion failures detected:", results.assertionFailures);
console.log("Review assertion logic, expected behavior, or gas usage");
}
// 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:**
* **Assertion tuning needed:** Assertion logic flags legitimate protocol behavior
* **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](/credible/backtesting#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:
```solidity theme={null}
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](/credible/backtesting#common-configurations) for more configuration examples including debugging and quick test scenarios.**
## Learn More
Autogenerated API documentation for backtesting
Learn how to use backtesting to validate assertions
Basic testing guide for assertions
Automate your testing workflow
Use fuzz testing to test assertions