docs(fd): minor readme update (#3466)

Minor README update after questions from a third party.
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

packages/fault-detector/README.md

@@ -20,3 +20,47 @@ Once your environment variables have been set, run the service via:
 ```
 yarn start
 ```
+
+## Ports
+
+- API is exposed at `$FAULT_DETECTOR__HOSTNAME:$FAULT_DETECTOR__PORT/api`
+- Metrics are exposed at `$FAULT_DETECTOR__HOSTNAME:$FAULT_DETECTOR__PORT/metrics`
+- `$FAULT_DETECTOR__HOSTNAME` defaults to `0.0.0.0`
+- `$FAULT_DETECTOR__PORT` defaults to `7300`
+
+## What this service does
+
+The `fault-detector` detects differences between the transaction results generated by your local Optimism node and the transaction results actually published to Ethereum.
+Currently, transaction results take the form of [the root of the Optimism state trie](https://medium.com/@eiki1212/ethereum-state-trie-architecture-explained-a30237009d4e).
+For every Optimism block, the state root of the block is published to the [`StateCommitmentChain`](https://github.com/ethereum-optimism/optimism/blob/39b7262cc3ffd78cd314341b8512b2683c1d9af7/packages/contracts/contracts/L1/rollup/StateCommitmentChain.sol) contract on Ethereum.
+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.
+
+We export a series of Prometheus metrics that you can use to trigger alerting when issues are detected.
+Check the list of available metrics via `yarn start --help`:
+
+```sh
+> yarn start --help
+yarn run v1.22.19
+$ ts-node ./src/service.ts --help
+Usage: service [options]
+
+Options:
+  --l1rpcprovider    Provider for interacting with L1 (env: FAULT_DETECTOR__L1_RPC_PROVIDER)
+  --l2rpcprovider    Provider for interacting with L2 (env: FAULT_DETECTOR__L2_RPC_PROVIDER)
+  --startbatchindex  Batch index to start checking from (env: FAULT_DETECTOR__START_BATCH_INDEX)
+  --loopintervalms   Loop interval in milliseconds (env: FAULT_DETECTOR__LOOP_INTERVAL_MS)
+  --port             Port for the app server (env: FAULT_DETECTOR__PORT)
+  --hostname         Hostname for the app server (env: FAULT_DETECTOR__HOSTNAME)
+  -h, --help         display help for command
+
+Metrics:
+  highest_checked_batch_index   Highest good batch index (type: Gauge)
+  highest_known_batch_index     Highest known batch index (type: Gauge)
+  is_currently_mismatched       0 if state is ok, 1 if state is mismatched (type: Gauge)
+  l1_node_connection_failures   Number of times L1 node connection has failed (type: Gauge)
+  l2_node_connection_failures   Number of times L2 node connection has failed (type: Gauge)
+  metadata                      Service metadata (type: Gauge)
+  unhandled_errors              Unhandled errors (type: Counter)
+
+Done in 2.19s.
+```