faultproof_withdrawals

README

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.

In order to start the metrics service make sure to either export the variables or setup the right cli args

export MONITORISM_METRICS_PORT=7300
export MONITORISM_METRICS_ENABLED=true

cd ../
go run ./cmd/monitorism faultproof_withdrawals

or

cd ../
go run ./cmd/monitorism faultproof_withdrawals --metrics.enabled --metrics.port 7300

Available Metrics and Meaning

Cli options

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

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

Documentation

Index

• Constants
• func CLIFlags(envVar string) []cli.Flag
• type CLIConfig
  • func ReadCLIFlags(ctx *cli.Context) (CLIConfig, error)
• type Metrics
  • func NewMetrics(m metrics.Factory) *Metrics
  • func (m *Metrics) UpdateMetricsFromState(state *State)
• type Monitor
  • func NewMonitor(ctx context.Context, log log.Logger, m metrics.Factory, cfg CLIConfig) (*Monitor, error)
  • func (m *Monitor) Close(_ context.Context) error
  • func (m *Monitor) ConsumeEvent(enrichedWithdrawalEvent validator.EnrichedProvenWithdrawalEvent) (bool, error)
  • func (m *Monitor) ConsumeEvents(enrichedWithdrawalEvent []validator.EnrichedProvenWithdrawalEvent) (*[]validator.EnrichedProvenWithdrawalEvent, error)
  • func (m *Monitor) GetLatestBlock() (uint64, error)
  • func (m *Monitor) GetMaxBlock() (uint64, error)
  • func (m *Monitor) Run(ctx context.Context)
• type State
  • func NewState(log log.Logger, nextL1Height uint64, latestL1Height uint64) (*State, error)
  • func (s *State) GetPercentages() (uint64, uint64)
  • func (s *State) LogState(log log.Logger)

Constants

const (
	L1GethURLFlagName = "l1.geth.url"
	L2NodeURLFlagName = "l2.node.url"
	L2GethURLFlagName = "l2.geth.url"

	EventBlockRangeFlagName           = "event.block.range"
	StartingL1BlockHeightFlagName     = "start.block.height"
	HoursInThePastToStartFromFlagName = "start.block.hours.ago"

	OptimismPortalAddressFlagName = "optimismportal.address"
)

const (
	MetricsNamespace                 = "faultproof_withdrawals"
	DefaultHoursInThePastToStartFrom = 14 * 24 //14 days
)

Functions

func CLIFlags

func CLIFlags(envVar string) []cli.Flag

Types

type CLIConfig

type CLIConfig struct {
	L1GethURL   string
	L2OpGethURL string
	L2OpNodeURL string

	EventBlockRange           uint64
	StartingL1BlockHeight     int64
	HoursInThePastToStartFrom uint64

	OptimismPortalAddress common.Address
}

func ReadCLIFlags

func ReadCLIFlags(ctx *cli.Context) (CLIConfig, error)

type Metrics

type Metrics struct {
	InitialL1HeightGauge                               prometheus.Gauge
	NextL1HeightGauge                                  prometheus.Gauge
	LatestL1HeightGauge                                prometheus.Gauge
	ProcessedProvenWithdrawalsEventsExtensions1Counter prometheus.Counter
	NumberOfDetectedForgeryGauge                       prometheus.Gauge
	NumberOfInvalidWithdrawalsGauge                    prometheus.Gauge
	WithdrawalsValidatedCounter                        prometheus.Counter
	NodeConnectionFailuresCounter                      prometheus.Counter
	ForgeriesWithdrawalsEventsGauge                    prometheus.Gauge
	InvalidProposalWithdrawalsEventsGauge              prometheus.Gauge
	ForgeriesWithdrawalsEventsGaugeVec                 *prometheus.GaugeVec
	InvalidProposalWithdrawalsEventsGaugeVec           *prometheus.GaugeVec
	// contains filtered or unexported fields
}

func NewMetrics

func NewMetrics(m metrics.Factory) *Metrics

func (*Metrics) UpdateMetricsFromState

func (m *Metrics) UpdateMetricsFromState(state *State)

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor monitors the state and events related to withdrawal forgery.

func NewMonitor

func NewMonitor(ctx context.Context, log log.Logger, m metrics.Factory, cfg CLIConfig) (*Monitor, error)

NewMonitor creates a new Monitor instance with the provided configuration. It establishes connections to the specified L1 and L2 Geth clients, initializes the withdrawal validator, and sets up the initial state and metrics.

func (*Monitor) Close

func (m *Monitor) Close(_ context.Context) error

Close gracefully shuts down the Monitor by closing the Geth clients.

func (*Monitor) ConsumeEvent

func (m *Monitor) ConsumeEvent(enrichedWithdrawalEvent validator.EnrichedProvenWithdrawalEvent) (bool, error)

ConsumeEvent processes a single enriched withdrawal event. It logs the event details and checks for any forgery detection.

func (*Monitor) ConsumeEvents

func (m *Monitor) ConsumeEvents(enrichedWithdrawalEvent []validator.EnrichedProvenWithdrawalEvent) (*[]validator.EnrichedProvenWithdrawalEvent, error)

ConsumeEvents processes a slice of enriched withdrawal events and updates their states. It returns any events detected during the consumption that requires to be re-analysed again at a later stage (when the event referenced DisputeGame completes).

func (*Monitor) GetLatestBlock

func (m *Monitor) GetLatestBlock() (uint64, error)

GetLatestBlock retrieves the latest block number from the L1 Geth client. It updates the state with the latest L1 height.

func (*Monitor) GetMaxBlock

func (m *Monitor) GetMaxBlock() (uint64, error)

GetMaxBlock calculates the maximum block number to be processed. It considers the next L1 height and the defined max block range.

func (*Monitor) Run

func (m *Monitor) Run(ctx context.Context)

Run executes the main monitoring loop. It retrieves new events, processes them, and updates the state accordingly.

type State

type State struct {
	// contains filtered or unexported fields
}

func NewState

func NewState(log log.Logger, nextL1Height uint64, latestL1Height uint64) (*State, error)

func (*State) GetPercentages

func (s *State) GetPercentages() (uint64, uint64)

func (*State) LogState

func (s *State) LogState(log log.Logger)