github.com/ethereum-optimism/optimism@v1.7.2/packages/chain-mon/src/fault-mon/README.md (about)

     1  # @eth-optimism/fault-mon
     2  
     3  [![codecov](https://codecov.io/gh/ethereum-optimism/optimism/branch/develop/graph/badge.svg?token=0VTG7PG7YR&flag=fault-detector-tests)](https://codecov.io/gh/ethereum-optimism/optimism)
     4  
     5  The `fault-mon` is a simple service for detecting discrepancies between your local view of the Optimism network and the L2 output proposals published to Ethereum.
     6  
     7  ## Installation
     8  
     9  Clone, install, and build the Optimism monorepo:
    10  
    11  ```
    12  git clone https://github.com/ethereum-optimism/optimism.git
    13  pnpm install
    14  pnpm build
    15  ```
    16  
    17  ## Running the service
    18  
    19  Copy `.env.example` into a new file named `.env`, then set the environment variables listed there. Additional env settings are listed on `--help`. If running the fault detector against
    20  a custom op chain, the `OptimismPortal` contract addresses must also be set associated with the op-chain.
    21  
    22  Once your environment variables or flags have been set, run the service via:
    23  
    24  ```
    25  pnpm start
    26  ```
    27  
    28  ## Ports
    29  
    30  - API is exposed at `$FAULT_DETECTOR__HOSTNAME:$FAULT_DETECTOR__PORT/api`
    31  - Metrics are exposed at `$FAULT_DETECTOR__HOSTNAME:$FAULT_DETECTOR__PORT/metrics`
    32  - `$FAULT_DETECTOR__HOSTNAME` defaults to `0.0.0.0`
    33  - `$FAULT_DETECTOR__PORT` defaults to `7300`
    34  
    35  ## What this service does
    36  
    37  The `fault-mon` detects differences between the transaction results generated by your local Optimism node and the transaction results actually published to Ethereum.
    38  Currently, transaction results take the form of [the root of the Optimism state trie](https://medium.com/@eiki1212/ethereum-state-trie-architecture-explained-a30237009d4e).
    39  
    40  The state root of the block is published to the [`L2OutputOracle`](https://github.com/ethereum-optimism/optimism/blob/39b7262cc3ffd78cd314341b8512b2683c1d9af7/packages/contracts-bedrock/contracts/L1/L2OutputOracle.sol) contract on Ethereum.
    41      - ***Note***: The service accepts the `OptimismPortal` as a flag instead of the `L2OutputOracle` for backwards compatibility with early versions of these contracts. The `L2OutputOracle`
    42      is inferred from the portal contract.
    43  
    44  We can therefore detect differences by, for each block, checking the state root of the given block as reported by an Optimism node and the state root as published to Ethereum.
    45  
    46  We export a series of Prometheus metrics that you can use to trigger alerting when issues are detected.
    47  Check the list of available metrics via `pnpm start --help`:
    48  
    49  ```sh
    50  > pnpm start --help
    51  $ tsx ./src/service.ts --help
    52  Usage: service [options]
    53  
    54  Options:
    55    --l1rpcprovider    Provider for interacting with L1 (env: FAULT_DETECTOR__L1_RPC_PROVIDER)
    56    --l2rpcprovider    Provider for interacting with L2 (env: FAULT_DETECTOR__L2_RPC_PROVIDER)
    57    --startbatchindex  Batch index to start checking from. Setting it to -1 will cause the fault detector to find the first state batch index that has not yet passed the fault proof window (env: FAULT_DETECTOR__START_BATCH_INDEX, default value: -1)
    58    --loopintervalms   Loop interval in milliseconds (env: FAULT_DETECTOR__LOOP_INTERVAL_MS)
    59    --optimismportaladdress        [Custom OP Chains] Deployed OptimismPortal contract address. Used to retrieve necessary info for output verification  (env: FAULT_DETECTOR__OPTIMISM_PORTAL_ADDRESS, default 0x0)
    60  
    61    --port             Port for the app server (env: FAULT_DETECTOR__PORT)
    62    --hostname         Hostname for the app server (env: FAULT_DETECTOR__HOSTNAME)
    63    -h, --help         display help for command
    64  
    65  Metrics:
    66    highest_checked_batch_index   Highest good batch index (type: Gauge)
    67    highest_known_batch_index     Highest known batch index (type: Gauge)
    68    is_currently_mismatched       0 if state is ok, 1 if state is mismatched (type: Gauge)
    69    l1_node_connection_failures   Number of times L1 node connection has failed (type: Gauge)
    70    l2_node_connection_failures   Number of times L2 node connection has failed (type: Gauge)
    71    metadata                      Service metadata (type: Gauge)
    72    unhandled_errors              Unhandled errors (type: Counter)
    73  ```