credible-std Library

Reference for credible-std contracts, helpers, specs, and testing utilities

credible-std is the Solidity standard library for writing and testing 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.

The current Phylax app and Linea deployment support the V1 assertion specification. pcl warns when an assertion uses the V2 Reshiram specification. Use Reshiram-only helpers for local or development workflows until the target deployment supports V2.

Package and Configuration

credible-std is distributed as a Foundry library.

Item	Value
Repository	phylaxsystems/credible-std
Stable dependency	phylaxsystems/credible-std@0.7.0
Development dependency	phylaxsystems/credible-std
Foundry remapping	credible-std/=lib/credible-std/src/

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(...).

Assertion Helpers

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

Legacy Trigger Helpers

Use these helpers for the pre-Reshiram trigger APIs:

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;

The cumulative flow helpers collect inflow or outflow into one bucket per block and evaluate those per-block buckets over the configured rolling window.

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:

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;
}

Related Pages

Cheatcodes API Reference

Full PhEVM cheatcode signatures

Testing Assertions

How to test assertions locally

Review Backtesting Results

Review the automatic backtest attached to a platform release

Write Your First Assertion

Build a first assertion with credible-std