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

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

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

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

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:

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

## 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="Review Backtesting Results" icon="clock-rotate-left" href="./backtesting">
    Review the automatic backtest attached to a platform release
  </Card>

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