State Management
forkPreTx
Updates the active fork to the state prior to the assertion triggering transaction. Useful for:
- Checking chain state before a transaction
- Comparing values between pre and post states
function forkPreTx() external
forkPostTx
Updates the active fork to the state after the assertion triggering transaction. Useful for:
- Verifying chain state after a transaction
- Comparing values between pre and post states
function forkPostTx() external
forkPreCall
Updates the active fork to the state at the start of call execution for the specified id. getCallInputs(..) can be used to get ids to fork to.
function forkPreCall(uint256 id) external
forkPostCall
Updates the active fork to the state after the call execution for the specified id. getCallInputs(..) can be used to get ids to fork to.
function forkPostCall(uint256 id) external
Storage Operations
load
Loads a storage slot from an address.
Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.
function load(
address target,
bytes32 slot
) external view returns (bytes32 data)
Transaction Data
getLogs
Retrieves logs from the assertion triggering transaction.
struct Log {
bytes32[] topics; // Log topics, including signature
bytes data; // Raw log data
address emitter; // Log emitter address
}
function getLogs() external returns (Log[] memory logs)
struct CallInputs {
bytes input; // Call data
uint64 gas_limit; // Gas limit
address bytecode_address; // Code execution address
address target_address; // Storage modification target
address caller; // Transaction caller
uint256 value; // Call value
uint256 id; // Call id (used for forkPreCall and forkPostCall)
}
function getAllCallInputs(
address target,
bytes4 selector
) external view returns (CallInputs[] memory calls);
function getCallInputs(
address target,
bytes4 selector
) external view returns (CallInputs[] memory calls);
function getStaticCallInputs(
address target,
bytes4 selector
) external view returns (CallInputs[] memory calls);
function getDelegateCallInputs(
address target,
bytes4 selector
) external view returns (CallInputs[] memory calls);
function getCallCodeInputs(
address target,
bytes4 selector
) external view returns (CallInputs[] memory calls);
getCallInputs, getStaticCallInputs, getDelegateCallInputs, getCallCodeInputs) eliminate double-counting issues by allowing you to target only the specific call type you need. Use these instead of getAllCallInputs() when you want to avoid duplicate entries from proxy contracts.
For example, if you’re monitoring a proxy contract and only want the actual delegate calls (not the proxy calls), use getDelegateCallInputs() instead of getAllCallInputs().
// GOOD: Only get delegate calls, no duplicates
CallInputs[] memory delegateCalls = ph.getDelegateCallInputs(target, selector);
// AVOID: May include both proxy and delegate calls for the same operation
CallInputs[] memory allCalls = ph.getAllCallInputs(target, selector);
getAllCallInputs(), you may still need to filter out proxy calls:
// Filter proxy calls when using getAllCallInputs
for (uint256 i = 0; i < callInputs.length; i++) {
if (callInputs[i].bytecode_address == callInputs[i].target_address) {
continue; // Skip proxy calls, only process delegate calls
}
// Process the actual call
}
Internal calls are not actual EVM calls but rather a Solidity language feature. They are not traced by the CallTracer and will not result in CallInputs or trigger call-based assertions. However, using the this keyword (e.g., this.functionName()) creates an external call that will be traced and can trigger assertions.Example:function foo() external {
// Internal call - not traced, no CallInputs generated
bar();
// External call via 'this' - traced, generates CallInputs
this.bar();
}
function bar() public {
// Function implementation
}
State Change Tracking
getStateChanges
Returns state changes for a contract’s storage slot within the current call stack.
Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.
function getStateChanges(
address contractAddress,
bytes32 slot
) external view returns (bytes32[] memory stateChanges);
The array returned includes the initial value of the slot as the first element, so the length of the array is either 0 or >= 2.
Helper Functions
The following helpers convert state changes to specific types. Each has three variants:
- Basic: Get changes for a single slot
- Mapping: Get changes using a mapping key
- Mapping with Offset: Get changes using a key and offset for complex storage
getStateChangesUint
Gets state changes for a storage slot as uint256 values.
// Basic
function getStateChangesUint(
address target,
bytes32 slot
) internal view returns (uint256[] memory)
// With mapping
function getStateChangesUint(
address target,
bytes32 slot,
uint256 key
) internal view returns (uint256[] memory)
// With mapping and offset
function getStateChangesUint(
address target,
bytes32 slot,
uint256 key,
uint256 offset
) internal view returns (uint256[] memory)
getStateChangesAddress: Convert to address valuesgetStateChangesBool: Convert to boolean valuesgetStateChangesBytes32: Get raw bytes32 values
Each of these functions follows the same pattern with basic, mapping, and mapping-with-offset variants.
Triggers
Triggers determine when your assertion functions will be executed. You can register different types of triggers in your assertion’s triggers() function.
Use triggers to ensure that assertions are only called when they are needed in order to save gas and resources. For example, instead of triggering an assertion on every call to a contract, you can trigger it only on specific function calls that are able to change the state of the specific value you are asserting on.
Call Triggers
Call triggers execute your assertion when specific contract calls occur.
// Trigger on any call to the contract
// Note: It is not recommended to use this trigger as it will trigger the assertion on every call to the contract
// This can be expensive and inefficient
function registerCallTrigger(
bytes4 assertionFnSelector
) internal view
// Trigger on specific function calls
function registerCallTrigger(
bytes4 assertionFnSelector,
bytes4 triggerSelector
) internal view
function triggers() external view override {
// Run assertion on ALL calls to the contract
registerCallTrigger(this.checkAllCalls.selector);
// Run assertion only on transfer calls
registerCallTrigger(
this.checkTransfer.selector,
IERC20.transfer.selector
);
}
Storage Triggers
Storage triggers execute your assertion when contract storage changes.
Using forge inspect <ContractName> storage-layout is an easy way to get the storage layout of a contract. This can be used to determine the storage slot of a specific variable to use in the cheatcode.
// Trigger on ANY storage slot change
// Note: It is not recommended to use this trigger as it will trigger the assertion on every storage slot change
// This can be expensive and inefficient
function registerStorageChangeTrigger(
bytes4 assertionFnSelector
) internal view
// Trigger on changes to a specific storage slot
function registerStorageChangeTrigger(
bytes4 assertionFnSelector,
bytes32 slot
) internal view
function triggers() external view override {
// Run assertion on ANY storage change
registerStorageChangeTrigger(this.checkAllStorage.selector);
// Run assertion when totalSupply slot changes
registerStorageChangeTrigger(
this.checkSupply.selector,
TOTAL_SUPPLY_SLOT
);
}
Balance Triggers
Executes assertion on ETH balance changes.
function registerBalanceChangeTrigger(
bytes4 assertionFnSelector
) internal view
Combining Triggers
Triggers can be combined for comprehensive coverage:
function triggers() external view override {
// Multiple triggers for one assertion
registerStorageChangeTrigger(this.mainInvariant.selector);
registerCallTrigger(this.mainInvariant.selector);
// Different assertions for different events
registerBalanceChangeTrigger(this.checkBalances.selector);
registerCallTrigger(
this.checkCalls.selector,
IERC20.transfer.selector
);
}
Helpers
getAssertionAdopter
Get assertion adopter contract address associated with the assertion triggering transaction.
function getAssertionAdopter() external view returns (address);
triggers() function and the assertion functions. It cannot be used in the constructor since assertion contracts have no state during deployment.
console.log
Prints debug information to the console during testing with pcl test. Useful for debugging assertion logic and understanding transaction flow.
function console.log(string memory message) external;
import { console } from "credible-std/console.sol";
function assertionExample() external {
ph.forkPreTx();
uint256 preBalance = token.balanceOf(user);
ph.forkPostTx();
uint256 postBalance = token.balanceOf(user);
console.log("Checking user balance assertion");
require(postBalance >= preBalance, "Balance should not decrease");
}
Next Steps
