LayerX Forge Std Integration, Fixtures, and Solidity Test Support

Overview

This section captures the vendored Forge Standard Library surface that LayerX uses to write Solidity tests, plus the local test doubles and fixture files that exercise token behavior, wrapped native flows, router quoting, and reentrancy handling. The most important integration point is the root layerx/contracts/foundry.toml, which explicitly vendors forge-std under lib/ for tests only and keeps production src/ free of external imports.

The vendored copy under layerx/contracts/lib/forge-std/ provides the default Test harness, the standard IERC20 and IERC165 interfaces, helper documentation for storage inspection and cheatcodes, and the configuration files that support Forge’s own validation. The layerx/contracts/test/mocks/ directory then supplies the concrete mock contracts LayerX uses to simulate standard ERC-20 behavior, USDT-style approval rules, wrapped native token minting and withdrawal, router execution, and deliberate reentrancy attempts.

Forge Std Package and Repository Configuration

Package Metadata

The root layerx/contracts/foundry.toml explicitly treats forge-std as a vendored test-only dependency, which is the integration contract that keeps the test harness separate from production imports.

layerx/contracts/lib/forge-std/package.json identifies the vendored library as forge-std version 1.16.1 and publishes only src/**/*. The metadata points to the Forge Std guide for documentation, the Foundry issue tracker for bugs, and the upstream git repository for source history.

Contributor Workflow

layerx/contracts/lib/forge-std/CONTRIBUTING.md is a support file rather than runtime code, but it is part of the test-support surface because it explains how the vendored library is maintained.

1. Format check | Run `forge fmt --check`.
2. Test suite | Run `forge test -vvv`.
3. Compiler matrix | Run `forge build --skip test --use solc:0.6.2`, `forge build --skip test --use solc:0.6.12`, `forge build --skip test --use solc:0.7.0`, `forge build --skip test --use solc:0.7.6`, and `forge build --skip test --use solc:0.8.0`.
4. Cheatcode regeneration | Run `./scripts/vm.py` when the native cheatcode surface changes.

Forge Std Helper Surfaces Documented in the README

layerx/contracts/lib/forge-std/README.md is the main usage guide for the vendored library. It describes the helper surfaces LayerX relies on in tests and scripts:

• stdError supplies compiler built-in error selectors for expectRevert.
• stdStorage wraps the record and accesses cheatcodes, can locate storage slots without knowing the full layout, supports mapping keys and struct field depth, and can write back through find() and checked_write().
• stdCheats wraps prank, deal, hoax, startHoax, time manipulation, deployment helpers, and fuzzing helpers.
• StdAssertions provides equality, inequality, comparison, approximate equality, and boolean assertions across primitive values and arrays.
• StdConfig loads TOML data by chain identifier or alias and casts values into typed subtables.
• console2.sol is the recommended logging surface because Forge traces decode it cleanly.
• console.sol remains available for Hardhat compatibility, with a README note that uint256 and int256 logs are not decoded correctly in Forge traces.

UnpackedStruct

The README recommends console2.sol for decoded Forge traces and reserves console.sol for Hardhat compatibility.

layerx/contracts/lib/forge-std/README.md

This example struct appears in the storage walkthrough used to explain stdStorage. It is paired with the testFindStruct example, which resolves a and b by field depth and then validates the stored values with vm.load.

Test Harness Contract

Test

layerx/contracts/lib/forge-std/src/Test.sol

Test is the default Forge Std testing base. It is declared as an abstract contract and combines TestBase, StdAssertions, StdChains, StdCheats, StdInvariant, and StdUtils into a single test harness. The contract also imports logging, storage, JSON, math, TOML, and cheatcode modules so test files can use the standard Forge tooling surface from one import.

The contract declares no public methods of its own. Its role is to expose the inherited assertion, cheatcode, chain, invariant, and utility behavior through a single test entrypoint.

Helper Interfaces

IERC20

layerx/contracts/lib/forge-std/src/interfaces/IERC20.sol

IERC20 is the standard ERC-20 interface used by the test mocks and router adapter. The interface includes the standard token metadata, transfer, allowance, and approval methods, plus the standard Transfer and Approval events.

IERC165

layerx/contracts/lib/forge-std/src/interfaces/IERC165.sol

IERC165 is the minimal ERC-165 surface used to query interface support.

Test Mocks

layerx/contracts/test/mocks/ contains the Solidity doubles that the LayerX contract tests use to exercise token transfers, wrapped native value movement, router behavior, and reentrancy protection.

MockERC20

layerx/contracts/test/mocks/MockERC20.sol

MockERC20 is the standard, well-behaved ERC-20 test token. It implements IERC20, tracks balances and allowances in storage, emits the standard token events, and returns true from token-moving methods.

Mock PECOR Router

layerx/contracts/test/mocks/MockPECORRouter.sol

MockPECORRouter is a test DEX router. It pulls tokenIn from the caller, pays out USDL at a configured rate, and requires USDL liquidity to be pre-funded. It uses IPECORRouter and IERC20, with usdl stored as an immutable ERC-20 reference and rateE18 holding the per-token conversion rate.

The internal _out helper implements the conversion formula:

• out(USDL base) = amountIn * rateE18[tokenIn] / 1e18

MockUSDT

layerx/contracts/test/mocks/MockUSDT.sol

MockUSDT models the non-standard USDT approval and transfer behavior used by the test suite to exercise SafeERC20 and force-approval paths. It intentionally does not implement IERC20 because the signatures differ from the standard interface.

Mock Wrapped Native

layerx/contracts/test/mocks/MockWrappedNative.sol

MockWrappedNative is a minimal WETH-style wrapper used in tests. It inherits MockERC20 with the name Wrapped PAX, symbol WPAX9, and 18 decimals, and then adds native-value deposit and withdrawal behavior.

The contract reuses the MockERC20 storage layout and adds no new storage variables.

Reentrant Token

layerx/contracts/test/mocks/ReentrantToken.sol

ReentrantToken is the malicious token used to prove that value-moving entrypoints are protected by nonReentrant. It inherits MockERC20, stores a target payload, and attempts to call back into the target during transferFrom when armed.

Fixture Files

The fixture set under layerx/contracts/lib/forge-std/test/fixtures/ provides the sample inputs and outputs used by the vendored Forge Std tests.

config.toml

The fixture config uses two example environments, mainnet and optimism, and assigns values by type-specific subtables. It includes boolean arrays, address arrays, signed and unsigned integers, bytes32 arrays, raw bytes arrays, string arrays, and RPC URL placeholders driven by environment variables.

broadcast.log.json

The broadcast log fixture stores a complete run record with call transactions, deployment receipts, linked library addresses, a pending list, the broadcast path, return values, and a timestamp. The transaction samples include calls against Test contract functions such as multiple_arguments, inc, and t, which makes the file useful for broadcast parsing and trace validation.

Test Execution Flow

This flow mirrors the way the README examples and the mock contracts are meant to be used together: a Solidity test inherits Test, sets up token state with mocks, and then verifies results with Forge cheatcode-backed assertions and storage reads.