Skip to main content

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.

credible-std is the Solidity standard library for writing, testing, and backtesting Credible Layer assertions. It provides the base assertion contract, the ph interface for PhEVM cheatcodes, trigger registration helpers, snapshot-read helpers, typed state-change helpers, and Forge test utilities. For individual cheatcode signatures, see the Cheatcodes API Reference. For local assertion tests, see Testing Assertions.
As of May 6, 2026, the latest credible-std exposes Reshiram helpers, but the v2 Reshiram spec is not live on Linea mainnet. Use Reshiram-only helpers for local or development workflows until Linea mainnet supports the spec.

​
Package and Configuration

credible-std is distributed as a Foundry library.
ItemValue
Repositoryphylaxsystems/credible-std
Stable dependencyphylaxsystems/[email protected]
Development dependencyphylaxsystems/credible-std
Foundry remappingcredible-std/=lib/credible-std/src/
Backtesting helpers require ffi = true in the relevant Foundry profile: 
[profile.backtesting]
src = "src"
out = "out"
libs = ["lib"]
ffi = true
gas_limit = 100000000
test = "test"

​
Core Contracts

ContractPurpose
Assertion.solBase contract for assertions. Inherits ForkUtils and StateChanges, exposes trigger helpers, fork ID constructors, call matching helpers, and assertion spec registration.
Credible.solProvides the inherited ph handle for calling the PhEVM precompile.
PhEvm.solInterface for PhEVM cheatcodes, including logs, call inputs, snapshot reads, mapping tracing, ERC20 transfer data, and protection-suite helpers.
TriggerRecorder.solInterface used by Assertion to register assertion triggers.
SpecRecorder.solDefines AssertionSpec and records whether an assertion uses Legacy, Reshiram, or Experimental precompile access.
StateChanges.solTyped helpers for legacy state-change arrays.
ForkUtils.solHelper functions for Reshiram-style snapshot reads and ERC20 balance delta workflows.
CredibleTest.solForge test base that exposes cl.assertion(...).
CredibleTestWithBacktesting.solTest base for replaying historical transactions against assertions.

​
Assertion Helpers

Assertion.sol provides internal helpers for registering when assertion functions run.

​
Legacy Trigger Helpers

Use these helpers for the launch-era trigger surface: 
function registerCallTrigger(bytes4 fnSelector) internal view;
function registerCallTrigger(bytes4 fnSelector, bytes4 triggerSelector) internal view;
function registerStorageChangeTrigger(bytes4 fnSelector) internal view;
function registerStorageChangeTrigger(bytes4 fnSelector, bytes32 slot) internal view;
function registerBalanceChangeTrigger(bytes4 fnSelector) internal view;

​
Reshiram Trigger Helpers

Use these helpers for newer trigger types: 
function registerFnCallTrigger(bytes4 fnSelector, bytes4 triggerSelector) internal view;
function registerTxEndTrigger(bytes4 fnSelector) internal view;
function registerErc20ChangeTrigger(bytes4 fnSelector, address token) internal view;
function watchCumulativeOutflow(
    address token,
    uint256 thresholdBps,
    uint256 windowDuration,
    bytes4 fnSelector
) internal view;
function watchCumulativeInflow(
    address token,
    uint256 thresholdBps,
    uint256 windowDuration,
    bytes4 fnSelector
) internal view;
registerFnCallTrigger pairs with ph.context() so an assertion can inspect the matched call’s selector and call range.

​
Fork and Snapshot Helpers

Reshiram assertions should prefer explicit snapshot IDs over deprecated fork-switching cheatcodes. Construct ForkId values explicitly: 
PhEvm.ForkId memory preTx = _preTx();
PhEvm.ForkId memory postTx = _postTx();
PhEvm.ForkId memory preCall = PhEvm.ForkId({forkType: 2, callIndex: callId});
PhEvm.ForkId memory postCall = PhEvm.ForkId({forkType: 3, callIndex: callId});
Use ph.loadStateAt to read storage at those snapshots: 
function loadStateAt(bytes32 slot, PhEvm.ForkId calldata fork)
    external view returns (bytes32 value);

function loadStateAt(address target, bytes32 slot, PhEvm.ForkId calldata fork)
    external view returns (bytes32 value);
For packed storage or mappings, calculate the exact slot before calling loadStateAt.

​
ERC20 Delta Helpers

ForkUtils.sol also includes ERC20 transfer-delta helpers: 
function _reducedErc20BalanceDeltasAt(address token, PhEvm.ForkId memory fork)
    internal view returns (PhEvm.Erc20TransferData[] memory deltas);

function _transferredValueAt(address token, address from, address to, PhEvm.ForkId memory fork)
    internal view returns (uint256 value);

function _consumedBetween(uint256 beforeValue, uint256 afterValue)
    internal pure returns (uint256 consumed);
Use these helpers when an assertion needs to reason about ERC20 flows within a selected transaction or call snapshot.

​
State Change Helpers

StateChanges.sol converts ph.getStateChanges(...) from bytes32[] into typed arrays: 
function getStateChangesUint(address contractAddress, bytes32 slot)
    internal view returns (uint256[] memory);

function getStateChangesAddress(address contractAddress, bytes32 slot)
    internal view returns (address[] memory);

function getStateChangesBool(address contractAddress, bytes32 slot)
    internal view returns (bool[] memory);

function getStateChangesBytes32(address contractAddress, bytes32 slot)
    internal view returns (bytes32[] memory);
Each helper also has overloads for mapping keys and mapping keys with slot offsets: 
function getStateChangesUint(address contractAddress, bytes32 slot, uint256 key)
    internal view returns (uint256[] memory);

function getStateChangesUint(address contractAddress, bytes32 slot, uint256 key, uint256 slotOffset)
    internal view returns (uint256[] memory);
The same overload pattern exists for Address, Bool, and Bytes32.

​
Call Matching Helpers

Assertion.sol includes helpers for querying successful calls through the Reshiram call-matching precompile: 
function _successOnlyFilter() internal pure returns (PhEvm.CallFilter memory filter);

function _matchingCalls(address target, bytes4 selector, uint256 limit)
    internal view returns (PhEvm.TriggerCall[] memory);
Use _matchingCalls when an assertion needs a bounded list of successful calls to a target selector.

​
Assertion Spec Helper

Register the desired assertion spec in the constructor: 
import {AssertionSpec} from "credible-std/SpecRecorder.sol";

constructor() {
    registerAssertionSpec(AssertionSpec.Reshiram);
}
Available specs:
SpecMeaning
LegacyStandard launch precompile set.
ReshiramNewer precompile set with explicit snapshot access and legacy-only fork-switching selectors disabled.
ExperimentalUnrestricted access to all available precompiles. May include untested or dangerous behavior.

​
Testing Contracts

CredibleTest is the base contract for local Forge tests. It exposes cl.assertion(...), which registers an assertion against a target contract for the next transaction in a test. 
interface VmEx {
    function assertion(
        address adopter,
        bytes calldata createData,
        bytes4 fnSelector
    ) external;
}
CredibleTestWithBacktesting extends the local test base for historical transaction replay. It looks for credible-std/scripts/backtesting/transaction_fetcher.sh; CREDIBLE_STD_PATH overrides the default dependency lookup path.

Cheatcodes API Reference

Full PhEVM cheatcode signatures

Testing Assertions

How to test assertions locally

Backtesting Reference

Backtesting configuration and behavior

Write Your First Assertion

Build a first assertion with credible-std