> ## 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 Library

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

`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](./cheatcodes-reference). For local assertion tests, see [Testing Assertions](./testing-assertions).

<Warning>
  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.
</Warning>

## Package and Configuration

`credible-std` is distributed as a Foundry library.

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

Backtesting helpers require `ffi = true` in the relevant Foundry profile:

```toml theme={null}
[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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
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.

```solidity theme={null}
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.

## Related Pages

<CardGroup cols={2}>
  <Card title="Cheatcodes API Reference" icon="book" href="./cheatcodes-reference">
    Full PhEVM cheatcode signatures
  </Card>

  <Card title="Testing Assertions" icon="flask" href="./testing-assertions">
    How to test assertions locally
  </Card>

  <Card title="Backtesting Reference" icon="clock-rotate-left" href="./backtesting-reference">
    Backtesting configuration and behavior
  </Card>

  <Card title="Write Your First Assertion" icon="code" href="./write-first-assertion">
    Build a first assertion with credible-std
  </Card>
</CardGroup>