github.com/ethereum-optimism/optimism@v1.7.2/packages/contracts-bedrock/invariant-docs/README.md (about)

     1  # Invariant Docs
     2  
     3  This directory contains documentation for all defined invariant tests within `contracts-bedrock`.
     4  
     5  <!-- Do not modify the following section manually. It will be automatically generated on running `pnpm autogen:invariant-docs` -->
     6  <!-- START autoTOC -->
     7  
     8  ## Table of Contents
     9  - [AddressAliasHelper](./AddressAliasHelper.md)
    10  - [Burn.Eth](./Burn.Eth.md)
    11  - [Burn.Gas](./Burn.Gas.md)
    12  - [CrossDomainMessenger](./CrossDomainMessenger.md)
    13  - [Encoding](./Encoding.md)
    14  - [FaultDisputeGame](./FaultDisputeGame.md)
    15  - [Hashing](./Hashing.md)
    16  - [InvariantTest.sol](./InvariantTest.sol.md)
    17  - [L2OutputOracle](./L2OutputOracle.md)
    18  - [OptimismPortal](./OptimismPortal.md)
    19  - [OptimismPortal2](./OptimismPortal2.md)
    20  - [ResourceMetering](./ResourceMetering.md)
    21  - [SafeCall](./SafeCall.md)
    22  - [SystemConfig](./SystemConfig.md)
    23  <!-- END autoTOC -->
    24  
    25  ## Usage
    26  
    27  To auto-generate documentation for invariant tests, run `pnpm autogen:invariant-docs`.
    28  
    29  ## Documentation Standard
    30  
    31  In order for an invariant test file to be picked up by the [docgen script](../scripts/autogen/generate-invariant-docs.ts), it must
    32  adhere to the following conventions:
    33  
    34  ### Forge Invariants
    35  
    36  All `forge` invariant tests must exist within the `contracts/test/invariants` folder, and the file name should be
    37  `<ContractName>.t.sol`, where `<ContractName>` is the name of the contract that is being tested.
    38  
    39  All tests within `forge` invariant files should follow the convention:
    40  
    41  ```solidity
    42  /**
    43   * @custom:invariant <title>
    44   *
    45   * <longDescription>
    46   */
    47  function invariant_<shortDescription>() external {
    48      // ...
    49  }
    50  ```