Adding faultproof-withdrawals monitoring (#75)

Publishing new monitoring Faultproof Withdrawal

.gitignore

@@ -66,3 +66,7 @@ bin
 op-defender/.air.toml
 op-defender/run.sh
 op-defender/tmp
+
+local
+
+.venv

README.md

@@ -9,6 +9,7 @@
     - [Multisig Monitor](#multisig-monitor)
     - [Drippie Monitor](#drippie-monitor)
     - [Secrets Monitor](#secrets-monitor)
+    - [Faultproof Withdrawals](#secrets-monitor)
   - [Defender Components](#defender-components)
     - [HTTP API PSP Executor Service](#http-api-psp-executor-service)
   - [CLI & Docs](#cli--docs)
@@ -122,6 +123,18 @@ The secrets monitor takes a Drippie contract as a parameter and monitors for any
 | `op-monitorism/secrets` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/secrets/README.md) |
 | ----------------------- | --------------------------------------------------------------------------------------------------- |
 
+### Faultproof Withdrawal
+
+The Faultproof Withdrawal component monitors ProvenWithdrawals events on the [OptimismPortal](https://github.com/ethereum-optimism/superchain-registry/blob/d454618b6cf885417aa8cc8c760bd9ed0429c131/superchain/configs/mainnet/op.toml#L50) contract and performs checks to detect any violations of invariant conditions on the chain. If a violation is detected, it logs the issue and sets a Prometheus metric for the event.
+
+This component is designed to work exclusively with chains that are already utilizing the [Fault Proofs system](https://docs.optimism.io/stack/protocol/fault-proofs/explainer).
+This is a new version of the deprecated [chain-mon faultproof-wd-mon](https://github.com/ethereum-optimism/optimism/tree/chain-mon/v1.2.1/packages/chain-mon/src/faultproof-wd-mon).
+For detailed information on how the component works and the algorithms used, please refer to the component README.
+
+| `op-monitorism/faultproof-withdrawals` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/faultproof-withdrawals/README.md) |
+| ----------------------- | --------------------------------------------------------------------------------------------------- |
+
+
 ## Defender Components
 
 The _defenders_ are active security service allowing to provide automated defense for the OP Stack.
@@ -150,11 +163,17 @@ The cli has the ability to spin up a monitor for varying activities, each emmitt
 
 ```
 COMMANDS:
-   multisig     Monitors OptimismPortal pause status, Safe nonce, and Pre-Signed nonce stored in 1Password
-   fault        Monitors output roots posted on L1 against L2
-   withdrawals  Monitors proven withdrawals on L1 against L2
-   balances     Monitors account balances
-   secrets      Monitors secrets revealed in the CheckSecrets dripcheck
+   multisig                Monitors OptimismPortal pause status, Safe nonce, and Pre-Signed nonce stored in 1Password
+   fault                   Monitors output roots posted on L1 against L2
+   withdrawals             Monitors proven withdrawals on L1 against L2
+   balances                Monitors account balances
+   drippie                 Monitors Drippie contract
+   secrets                 Monitors secrets revealed in the CheckSecrets dripcheck
+   global_events           Monitors global events with YAML configuration
+   liveness_expiration     Monitor the liveness expiration on Gnosis Safe.
+   faultproof_withdrawals  Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.
+   version                 Show version
+   help, h                 Shows a list of commands or help for one command
 ```
 
 Each monitor has some common configuration, configurable both via cli or env with defaults.

op-monitorism/Makefile

@@ -13,6 +13,7 @@ CMD_DIR=./cmd/monitorism
 GOBUILD=go build
 GOCLEAN=go clean
 GORUN=go run
+GOTEST=go test
 
 # Default target
 .PHONY: all
@@ -22,13 +23,13 @@ all: build
 .PHONY: build
 build:
 	@echo "Building..."
-	$(GOBUILD) -o $(BUILD_DIR)/$(BINARY) $(CMD_DIR)
+	$(GOBUILD) -tags all -o $(BUILD_DIR)/$(BINARY) $(CMD_DIR) 
 
 # Run program
 .PHONY: run
 run:
 	@echo "Running..."
-	$(GORUN) $(CMD_DIR)/
+	$(GORUN) $(CMD_DIR) $(ARGS)
 
 # Clean up binaries
 .PHONY: clean
@@ -37,6 +38,19 @@ clean:
 	$(GOCLEAN)
 	rm -f $(BUILD_DIR)/$(BINARY)
 
+# Run tests
+.PHONY: test
+test:
+	@echo "Running tests..."
+	$(GOTEST) ./... -v
+
+#include tests that require live resources
+#these resources are meant to be real and not mocked
+.PHONY: test-live
+test-live:
+	@echo "Running live_tests..."
+	$(GOTEST) ./... -v -tags live
+
 # Run program
 .PHONY: tidy
 tidy:
@@ -50,4 +64,7 @@ help:
 	@echo "  make build"
 	@echo "  make run"
 	@echo "  make clean"
+	@echo "  make test"
+	@echo "  make test-live"
+	@echo "  make tidy"
 	@echo "  make help"

op-monitorism/cmd/monitorism/cli.go

@@ -8,6 +8,7 @@ import (
 	"github.com/ethereum-optimism/monitorism/op-monitorism/balances"
 	"github.com/ethereum-optimism/monitorism/op-monitorism/drippie"
 	"github.com/ethereum-optimism/monitorism/op-monitorism/fault"
+	"github.com/ethereum-optimism/monitorism/op-monitorism/faultproof_withdrawals"
 	"github.com/ethereum-optimism/monitorism/op-monitorism/global_events"
 	"github.com/ethereum-optimism/monitorism/op-monitorism/liveness_expiration"
 	"github.com/ethereum-optimism/monitorism/op-monitorism/multisig"
@@ -91,6 +92,13 @@ func newCli(GitCommit string, GitDate string) *cli.App {
 				Flags:       append(liveness_expiration.CLIFlags("LIVENESS_EXPIRATION_MON"), defaultFlags...),
 				Action:      cliapp.LifecycleCmd(LivenessExpirationMain),
 			},
+			{
+				Name:        "faultproof_withdrawals",
+				Usage:       "Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.",
+				Description: "Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.",
+				Flags:       append(faultproof_withdrawals.CLIFlags("FAULTPROOF_WITHDRAWAL_MON"), defaultFlags...),
+				Action:      cliapp.LifecycleCmd(FaultproofWithdrawalsMain),
+			},
 			{
 				Name:        "version",
 				Usage:       "Show version",
@@ -176,7 +184,23 @@ func WithdrawalsMain(ctx *cli.Context, closeApp context.CancelCauseFunc) (cliapp
 	metricsRegistry := opmetrics.NewRegistry()
 	monitor, err := withdrawals.NewMonitor(ctx.Context, log, opmetrics.With(metricsRegistry), cfg)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create withdrawal monitor: %w", err)
+		return nil, fmt.Errorf("failed to create withdrawals monitor: %w", err)
+	}
+
+	return monitorism.NewCliApp(ctx, log, metricsRegistry, monitor)
+}
+
+func FaultproofWithdrawalsMain(ctx *cli.Context, closeApp context.CancelCauseFunc) (cliapp.Lifecycle, error) {
+	log := oplog.NewLogger(oplog.AppOut(ctx), oplog.ReadCLIConfig(ctx))
+	cfg, err := faultproof_withdrawals.ReadCLIFlags(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse faultproof withdrawals config from flags: %w", err)
+	}
+
+	metricsRegistry := opmetrics.NewRegistry()
+	monitor, err := faultproof_withdrawals.NewMonitor(ctx.Context, log, opmetrics.With(metricsRegistry), cfg)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create faultproof withdrawals monitor: %w", err)
 	}
 
 	return monitorism.NewCliApp(ctx, log, metricsRegistry, monitor)

op-monitorism/fault/binding/BINDING.md

@@ -0,0 +1,5 @@
+## Info
+The bindings in this folder are taken from 
+github.com/ethereum-optimism/optimism/op-bindings/bindings v1.7.3
+
+This tool is compatible with these bindings. Future binding will break compatibility for those files.

op-monitorism/fault/monitor.go

@@ -6,7 +6,7 @@ import (
 	"math/big"
 	"time"
 
-	"github.com/ethereum-optimism/optimism/op-bindings/bindings"
+	"github.com/ethereum-optimism/monitorism/op-monitorism/multisig/bindings"
 	"github.com/ethereum-optimism/optimism/op-bindings/predeploys"
 	"github.com/ethereum-optimism/optimism/op-service/eth"
 	"github.com/ethereum-optimism/optimism/op-service/metrics"

op-monitorism/faultproof_withdrawals/.env.op.sepolia.example

@@ -0,0 +1,9 @@
+FAULTPROOF_WITHDRAWAL_MON_L1_GETH_URL="<geth-url>"
+FAULTPROOF_WITHDRAWAL_MON_L2_OP_NODE_URL="<op-geth-node>"
+FAULTPROOF_WITHDRAWAL_MON_L2_OP_GETH_URL="<op-geth-url>"
+FAULTPROOF_WITHDRAWAL_MON_OPTIMISM_PORTAL="0x16Fc5058F25648194471939df75CF27A2fdC48BC" # This is the address of the Optimism portal contract, this should be for the chain you are monitoring
+FAULTPROOF_WITHDRAWAL_MON_START_BLOCK_HEIGHT=5914813 # This is the block height from which the monitoring will start, decide at which block height you want to start monitoring
+FAULTPROOF_WITHDRAWAL_MON_EVENT_BLOCK_RANGE=1000 # This is the range of blocks to be monitored
+MONITORISM_LOOP_INTERVAL_MSEC=100 # This is the interval in milliseconds for the monitoring loop
+MONITORISM_METRICS_PORT=7300 # This is the port on which the metrics server will run 
+MONITORISM_METRICS_ENABLED=true # This is the flag to enable/disable the metrics server

op-monitorism/faultproof_withdrawals/.gitignore

@@ -0,0 +1,3 @@
+utilities
+testing
+!.env.*.example

op-monitorism/faultproof_withdrawals/README.md

@@ -0,0 +1,81 @@
+# Purpose of the Service
+faultproof_withdrawals has the following purpose:
+- Monitor Withdrawals: The service listens for WithdrawalProven events on the OptimismPortal contract on L1.
+- Validate Withdrawals: It verifies the validity of these withdrawals by checking the corresponding state on L2.
+- Detect Forgeries: The service identifies and reports any invalid withdrawals or potential forgeries.
+
+## Enable Metrics
+This service will optionally expose a [prometeus metrics](https://prometheus.io/docs/concepts/metric_types/).
+
+In order to start the metrics service make sure to either export the variables or setup the right cli args
+
+```bash
+export MONITORISM_METRICS_PORT=7300
+export MONITORISM_METRICS_ENABLED=true
+
+cd ../
+go run ./cmd/monitorism faultproof_withdrawals
+```
+or 
+
+```bash
+cd ../
+go run ./cmd/monitorism faultproof_withdrawals --metrics.enabled --metrics.port 7300
+```
+## Available Metrics and Meaning
+
+
+# Cli options
+
+```bash 
+go run ./cmd/monitorism faultproof_withdrawals --help
+NAME:
+   Monitorism faultproof_withdrawals - Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.
+
+USAGE:
+   Monitorism faultproof_withdrawals [command options]
+
+DESCRIPTION:
+   Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.
+
+OPTIONS:
+   --l1.geth.url value             L1 execution layer node URL [$FAULTPROOF_WITHDRAWAL_MON_L1_GETH_URL]
+   --l2.node.url value             L2 rollup node consensus layer (op-node) URL [$FAULTPROOF_WITHDRAWAL_MON_L2_OP_NODE_URL]
+   --l2.geth.url value             L2 OP Stack execution layer client(op-geth) URL [$FAULTPROOF_WITHDRAWAL_MON_L2_OP_GETH_URL]
+   --event.block.range value       Max block range when scanning for events (default: 1000) [$FAULTPROOF_WITHDRAWAL_MON_EVENT_BLOCK_RANGE]
+   --start.block.height value      Starting height to scan for events. This will take precedence if set. (default: 0) [$FAULTPROOF_WITHDRAWAL_MON_START_BLOCK_HEIGHT]
+   --start.block.hours.ago value   How many hours in the past to start to check for forgery. Default will be 336 (14 days) days if not set. The real block to start from will be found within the hour precision. (default: 0) [$FAULTPROOF_WITHDRAWAL_MON_START_HOURS_IN_THE_PAST]
+   --optimismportal.address value  Address of the OptimismPortal contract [$FAULTPROOF_WITHDRAWAL_MON_OPTIMISM_PORTAL]
+   --log.level value               The lowest log level that will be output (default: INFO) [$MONITORISM_LOG_LEVEL]
+   --log.format value              Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty', (default: text) [$MONITORISM_LOG_FORMAT]
+   --log.color                     Color the log output if in terminal mode (default: false) [$MONITORISM_LOG_COLOR]
+   --log.pid                       Show pid in the log (default: false) [$MONITORISM_LOG_PID]
+   --metrics.enabled               Enable the metrics server (default: false) [$MONITORISM_METRICS_ENABLED]
+   --metrics.addr value            Metrics listening address (default: "0.0.0.0") [$MONITORISM_METRICS_ADDR]
+   --metrics.port value            Metrics listening port (default: 7300) [$MONITORISM_METRICS_PORT]
+   --loop.interval.msec value      Loop interval of the monitor in milliseconds (default: 60000) [$MONITORISM_LOOP_INTERVAL_MSEC]
+   --help, -h                      show help
+   ```
+
+## Example run on sepolia op chain
+
+```bash
+L1_GETH_URL="https://..."
+L2_OP_NODE_URL="https://..."
+L2_OP_GETH_URL="https://..."
+
+export MONITORISM_LOOP_INTERVAL_MSEC=100
+export MONITORISM_METRICS_PORT=7300
+export MONITORISM_METRICS_ENABLED=true
+export FAULTPROOF_WITHDRAWAL_MON_L1_GETH_URL="$L1_GETH_URL"
+export FAULTPROOF_WITHDRAWAL_MON_L2_OP_NODE_URL="$L2_OP_NODE_URL"
+export FAULTPROOF_WITHDRAWAL_MON_L2_OP_GETH_URL="$L2_OP_GETH_URL"
+export FAULTPROOF_WITHDRAWAL_MON_OPTIMISM_PORTAL="0x16Fc5058F25648194471939df75CF27A2fdC48BC"
+export FAULTPROOF_WITHDRAWAL_MON_START_BLOCK_HEIGHT=5914813
+export FAULTPROOF_WITHDRAWAL_MON_EVENT_BLOCK_RANGE=1000
+
+
+go run ./cmd/monitorism faultproof_withdrawals
+```
+
+Metrics will be avialable at [http://localhost:7300](http://localhost:7300)

op-monitorism/faultproof_withdrawals/bindings/BINDING.md

@@ -0,0 +1,3 @@
+Repository https://github.com/ethereum-optimism/optimism.git cloned at commit fe7875e881ce50e75bf4e460bebb8b00bb38c315.
+
+This tool is compatible with these bindings. Future binding may break compatibility for those files.