credible-std Library - Phylax Credible Layer Documentation

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.

Item	Value
Repository	`phylaxsystems/credible-std`
Stable dependency	`phylaxsystems/[email protected]`
Development dependency	`phylaxsystems/credible-std`
Foundry remapping	`credible-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

Contract	Purpose
`Assertion.sol`	Base contract for assertions. Inherits `ForkUtils` and `StateChanges`, exposes trigger helpers, fork ID constructors, call matching helpers, and assertion spec registration.
`Credible.sol`	Provides the inherited `ph` handle for calling the PhEVM precompile.
`PhEvm.sol`	Interface for PhEVM cheatcodes, including logs, call inputs, snapshot reads, mapping tracing, ERC20 transfer data, and protection-suite helpers.
`TriggerRecorder.sol`	Interface used by `Assertion` to register assertion triggers.
`SpecRecorder.sol`	Defines `AssertionSpec` and records whether an assertion uses `Legacy`, `Reshiram`, or `Experimental` precompile access.
`StateChanges.sol`	Typed helpers for legacy state-change arrays.
`ForkUtils.sol`	Helper functions for Reshiram-style snapshot reads and ERC20 balance delta workflows.
`CredibleTest.sol`	Forge test base that exposes `cl.assertion(...)`.
`CredibleTestWithBacktesting.sol`	Test 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

import {AssertionSpec} from "credible-std/SpecRecorder.sol";

constructor() {
    registerAssertionSpec(AssertionSpec.Reshiram);
}

Available specs:

Spec	Meaning
`Legacy`	Standard launch precompile set.
`Reshiram`	Newer precompile set with explicit snapshot access and legacy-only fork-switching selectors disabled.
`Experimental`	Unrestricted 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

​Package and Configuration

​Core Contracts

​Assertion Helpers

​Legacy Trigger Helpers

​Reshiram Trigger Helpers

​Fork and Snapshot Helpers

​ERC20 Delta Helpers

​State Change Helpers

​Call Matching Helpers

​Assertion Spec Helper

​Testing Contracts

​Related Pages

Cheatcodes API Reference

Testing Assertions

Backtesting Reference

Write Your First Assertion

Package and Configuration

Core Contracts

Assertion Helpers

Legacy Trigger Helpers

Reshiram Trigger Helpers

Fork and Snapshot Helpers

ERC20 Delta Helpers

State Change Helpers

Call Matching Helpers

Assertion Spec Helper

Testing Contracts

Related Pages