filter

package
v1.16.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 18, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultMessageExpiryWindow = 7 * 24 * time.Hour

DefaultMessageExpiryWindow is 7 days, matching op-supervisor's default

Variables

View Source 
var ErrInvalidLog = errors.New("invalid executing message log")

ErrInvalidLog indicates a malformed executing message log was encountered. This is a sentinel error that can be checked with errors.Is.

Functions

func Main 

func Main(version string) cliapp.LifecycleAction

Main returns the main entrypoint for the service

Types

type AdminFrontend 

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

AdminFrontend handles admin RPC methods

func (*AdminFrontend) GetFailsafeEnabled 

func (a *AdminFrontend) GetFailsafeEnabled(ctx context.Context) (bool, error)

GetFailsafeEnabled returns whether failsafe is enabled

func (*AdminFrontend) Rewind 

func (a *AdminFrontend) Rewind(ctx context.Context, chain eth.ChainID, block eth.BlockID) error

Rewind is not implemented. For cross-chain consistency, rewind would need to coordinate across all chains to the same timestamp, which is complex. Instead, wipe the filter's data directory and restart fresh.

func (*AdminFrontend) SetFailsafeEnabled 

func (a *AdminFrontend) SetFailsafeEnabled(ctx context.Context, enabled bool) error

SetFailsafeEnabled enables or disables failsafe mode

type Backend 

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

Backend coordinates chain ingesters and handles CheckAccessList requests. Failsafe is enabled if manually set OR if any chain ingester has an error.

func NewBackend 

func NewBackend(parentCtx context.Context, params BackendParams) *Backend

NewBackend creates a new Backend instance with the provided components.

func (*Backend) CheckAccessList 

func (b *Backend) CheckAccessList(ctx context.Context, inboxEntries []common.Hash,
	minSafety types.SafetyLevel, execDescriptor types.ExecutingDescriptor) error

CheckAccessList validates the given access list entries.

func (*Backend) FailsafeEnabled 

func (b *Backend) FailsafeEnabled() bool

FailsafeEnabled returns true if failsafe is manually enabled OR any chain has an error OR the cross-validator has an error.

func (*Backend) GetChainErrors added in v1.16.7 

func (b *Backend) GetChainErrors() map[eth.ChainID]*IngesterError

GetChainErrors returns all chains that are in an error state

func (*Backend) Ready added in v1.16.7 

func (b *Backend) Ready() bool

Ready returns true if all chains have completed backfill

func (*Backend) SetFailsafeEnabled added in v1.16.7 

func (b *Backend) SetFailsafeEnabled(enabled bool)

SetFailsafeEnabled sets the manual failsafe override.

func (*Backend) Start 

func (b *Backend) Start(ctx context.Context) error

Start starts all chain ingesters and the cross-validator

func (*Backend) Stop 

func (b *Backend) Stop(ctx context.Context) error

Stop stops all chain ingesters and the cross-validator

type BackendParams added in v1.16.7 

type BackendParams struct {
	Logger         log.Logger
	Metrics        metrics.Metricer
	Chains         map[eth.ChainID]ChainIngester
	CrossValidator CrossValidator
	Passthrough    bool
}

BackendParams contains parameters for creating a Backend.

type ChainIngester added in v1.16.7 

type ChainIngester interface {
	// Start begins the ingester's background processing.
	Start() error

	// Stop halts the ingester's background processing.
	Stop() error

	// Contains checks if a log exists in the chain's database.
	Contains(query types.ContainsQuery) (types.BlockSeal, error)

	// LatestBlock returns the latest ingested block.
	LatestBlock() (eth.BlockID, bool)

	// LatestTimestamp returns the timestamp of the latest ingested block.
	LatestTimestamp() (uint64, bool)

	// GetExecMsgsAtTimestamp returns executing messages with the given inclusion timestamp.
	GetExecMsgsAtTimestamp(timestamp uint64) ([]IncludedMessage, error)

	// Ready returns true if the ingester has completed initial sync.
	Ready() bool

	// Error returns the current error state, if any.
	Error() *IngesterError

	// SetError sets an error state on the ingester.
	SetError(reason IngesterErrorReason, msg string)

	// ClearError clears the error state.
	ClearError()
}

ChainIngester provides access to chain logs and state. Implementations include:

  • mockChainIngester: in-memory for testing
  • LogsDBChainIngester: RPC-backed with logsdb for production

type Config 

type Config struct {
	L2RPCs                      []string
	RollupConfigs               map[eth.ChainID]*rollup.Config // Rollup configs keyed by chain ID
	DataDir                     string
	BackfillDuration            time.Duration
	MessageExpiryWindow         uint64 // Message expiry window in seconds (default: 7 days)
	MessageExpiryWindowExplicit bool   // True if explicitly set via flag
	JWTSecretPath               string
	RPCAddr                     string // Address for public RPC server
	RPCPort                     int    // Port for public RPC server (default: 8545)
	AdminRPCAddr                string // Address for admin RPC server (empty = disabled)
	AdminRPCPort                int    // Port for admin RPC server (default: 8546)
	Version                     string
	PollInterval                time.Duration // Interval for polling new blocks (default: 2s)
	ValidationInterval          time.Duration // Interval for cross-chain validation (default: 500ms)
	Passthrough                 bool          // If true, all transactions pass through without filtering

	LogConfig     oplog.CLIConfig
	MetricsConfig opmetrics.CLIConfig
	PprofConfig   oppprof.CLIConfig
}

func NewConfig 

func NewConfig(ctx *cli.Context, version string) (*Config, error)

func (*Config) Check 

func (c *Config) Check() error

type CrossValidator added in v1.16.7 

type CrossValidator interface {
	// Start begins the validator's background processing.
	Start() error

	// Stop halts the validator's background processing.
	Stop() error

	// ValidateAccessEntry validates a single access list entry.
	ValidateAccessEntry(access types.Access, minSafety types.SafetyLevel, execDescriptor types.ExecutingDescriptor) error

	// CrossValidatedTimestamp returns the global cross-validated timestamp.
	CrossValidatedTimestamp() (uint64, bool)

	// Error returns the current error state, if any.
	// Validation errors (invalid executing messages) are tracked here.
	Error() *ValidatorError
}

CrossValidator validates cross-chain messages. Implementations:

  • LockstepCrossValidator: waits for all chains to align before advancing

type EthClient added in v1.16.7 

type EthClient interface {
	InfoByLabel(ctx context.Context, label eth.BlockLabel) (eth.BlockInfo, error)
	InfoByNumber(ctx context.Context, number uint64) (eth.BlockInfo, error)
	FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, gethTypes.Receipts, error)
	Close()
}

EthClient defines the interface for fetching block and receipt data. This allows for dependency injection in tests.

type IncludedMessage added in v1.16.7 

type IncludedMessage struct {
	*types.ExecutingMessage
	InclusionBlockNum  uint64
	InclusionTimestamp uint64
}

IncludedMessage wraps an executing message with its inclusion context. The ExecutingMessage contains the initiating message's data (source chain), while InclusionBlockNum/Timestamp indicate when it was executed (this chain).

type IngesterError added in v1.16.7 

type IngesterError struct {
	Reason  IngesterErrorReason
	Message string
}

IngesterError represents an error state in a ChainIngester. These are ingestion-level errors tracked per-chain.

func (*IngesterError) Error added in v1.16.7 

func (e *IngesterError) Error() string

type IngesterErrorReason added in v1.16.7 

type IngesterErrorReason int

IngesterErrorReason indicates why an ingester entered an error state. These are ingestion-level errors (reorg, DB conflicts). 

const (
	// ErrorReorg indicates a true chain reorganization was detected
	ErrorReorg IngesterErrorReason = iota
	// ErrorConflict indicates a database conflict (app-level failure)
	ErrorConflict
	// ErrorDataCorruption indicates a database I/O or corruption error
	ErrorDataCorruption
	// ErrorInvalidExecutingMessage indicates a malformed executing message log from the chain
	ErrorInvalidExecutingMessage
)

func (IngesterErrorReason) String added in v1.16.7 

func (r IngesterErrorReason) String() string

String returns a human-readable name for the error reason

type LockstepCrossValidator added in v1.16.7 

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

LockstepCrossValidator validates cross-chain executing messages and tracks the cross-validated timestamp.

"Lockstep" refers to its synchronization model: all chains must reach the same timestamp before validation can advance. This is simpler but means a slow chain holds back validation for all chains.

Simplifications in this implementation:

  • No cycle detection: same-block executing messages are not supported
  • Lockstep advancement: waits for ALL chains to reach timestamp T before validating T, rather than validating each chain independently

Future improvement: per-chain validation that tracks cross-validated timestamp independently for each chain, allowing faster chains to advance without waiting.

func NewLockstepCrossValidator added in v1.16.7 

func NewLockstepCrossValidator(
	parentCtx context.Context,
	logger log.Logger,
	m metrics.Metricer,
	messageExpiryWindow uint64,
	startTimestamp uint64,
	validationInterval time.Duration,
	chains map[eth.ChainID]ChainIngester,
) *LockstepCrossValidator

NewLockstepCrossValidator creates a new LockstepCrossValidator. The startTimestamp is used to initialize the cross-validated timestamp on first run.

func (*LockstepCrossValidator) CrossValidatedTimestamp added in v1.16.7 

func (v *LockstepCrossValidator) CrossValidatedTimestamp() (uint64, bool)

CrossValidatedTimestamp returns the global cross-validated timestamp.

func (*LockstepCrossValidator) Error added in v1.16.7 

func (v *LockstepCrossValidator) Error() *ValidatorError

Error returns the current validation error state, if any.

func (*LockstepCrossValidator) Start added in v1.16.7 

func (v *LockstepCrossValidator) Start() error

Start starts the validation loop

func (*LockstepCrossValidator) Stop added in v1.16.7 

func (v *LockstepCrossValidator) Stop() error

Stop stops the validation loop

func (*LockstepCrossValidator) ValidateAccessEntry added in v1.16.7 

func (v *LockstepCrossValidator) ValidateAccessEntry(
	access types.Access,
	minSafety types.SafetyLevel,
	execDescriptor types.ExecutingDescriptor,
) error

ValidateAccessEntry validates a single access list entry against all message validity rules.

type LogsDBChainIngester added in v1.16.7 

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

LogsDBChainIngester handles block ingestion and log storage for a single chain. It uses an RPC client to fetch blocks and a logsdb database for storage.

func NewLogsDBChainIngester added in v1.16.7 

func NewLogsDBChainIngester(
	parentCtx context.Context,
	logger log.Logger,
	m metrics.Metricer,
	chainID eth.ChainID,
	rpcURL string,
	dataDir string,
	startTimestamp uint64,
	backfillDuration time.Duration,
	pollInterval time.Duration,
	rollupCfg *rollup.Config,
) (*LogsDBChainIngester, error)

NewLogsDBChainIngester creates a new LogsDBChainIngester for the given chain. startTimestamp is when we report Ready() = true (typically now). backfillDuration is how far back from startTimestamp to begin ingestion.

func (*LogsDBChainIngester) BlockHashAt added in v1.16.7 

func (c *LogsDBChainIngester) BlockHashAt(blockNum uint64) (common.Hash, bool)

BlockHashAt returns the hash of the sealed block at the given height.

func (*LogsDBChainIngester) ClearError added in v1.16.7 

func (c *LogsDBChainIngester) ClearError()

ClearError clears the error state.

func (*LogsDBChainIngester) Contains added in v1.16.7 

func (c *LogsDBChainIngester) Contains(query types.ContainsQuery) (types.BlockSeal, error)

Contains checks if a log exists in the database

func (*LogsDBChainIngester) Error added in v1.16.7 

func (c *LogsDBChainIngester) Error() *IngesterError

Error returns the current error state, or nil if no error.

func (*LogsDBChainIngester) GetExecMsgsAtTimestamp added in v1.16.7 

func (c *LogsDBChainIngester) GetExecMsgsAtTimestamp(timestamp uint64) ([]IncludedMessage, error)

GetExecMsgsAtTimestamp returns executing messages with the given inclusion timestamp.

func (*LogsDBChainIngester) LatestBlock added in v1.16.7 

func (c *LogsDBChainIngester) LatestBlock() (eth.BlockID, bool)

LatestBlock returns the latest sealed block

func (*LogsDBChainIngester) LatestTimestamp added in v1.16.7 

func (c *LogsDBChainIngester) LatestTimestamp() (uint64, bool)

LatestTimestamp returns the timestamp of the latest sealed block

func (*LogsDBChainIngester) Ready added in v1.16.7 

func (c *LogsDBChainIngester) Ready() bool

Ready returns true if we've ingested up to at least the start timestamp.

func (*LogsDBChainIngester) SetError added in v1.16.7 

func (c *LogsDBChainIngester) SetError(reason IngesterErrorReason, msg string)

SetError sets the error state, logs the error, and records metrics.

func (*LogsDBChainIngester) Start added in v1.16.7 

func (c *LogsDBChainIngester) Start() error

Start begins block ingestion

func (*LogsDBChainIngester) Stop added in v1.16.7 

func (c *LogsDBChainIngester) Stop() error

Stop gracefully stops the chain ingester

type PublicAdminFrontend added in v1.16.9 

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

PublicAdminFrontend exposes read-only admin methods on the public port.

func (*PublicAdminFrontend) GetFailsafeEnabled added in v1.16.9 

func (p *PublicAdminFrontend) GetFailsafeEnabled(ctx context.Context) (bool, error)

type QueryFrontend 

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

QueryFrontend handles supervisor query RPC methods

func (*QueryFrontend) CheckAccessList 

func (f *QueryFrontend) CheckAccessList(ctx context.Context, inboxEntries []common.Hash,
	minSafety types.SafetyLevel, executingDescriptor types.ExecutingDescriptor) error

CheckAccessList validates interop executing messages

type Service 

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

Service is the main op-interop-filter service

func NewService 

func NewService(ctx context.Context, cfg *Config, logger log.Logger) (*Service, error)

NewService creates a new Service instance

func (*Service) AdminHTTPEndpoint added in v1.16.7 

func (s *Service) AdminHTTPEndpoint() string

AdminHTTPEndpoint returns the HTTP endpoint of the admin RPC server, or empty string if not configured.

func (*Service) HTTPEndpoint added in v1.16.7 

func (s *Service) HTTPEndpoint() string

HTTPEndpoint returns the HTTP endpoint of the RPC server, or empty string if not started.

func (*Service) Start 

func (s *Service) Start(ctx context.Context) error

Start starts the service

func (*Service) Stop 

func (s *Service) Stop(ctx context.Context) error

Stop stops the service

func (*Service) Stopped 

func (s *Service) Stopped() bool

Stopped returns true if the service has been stopped

type ValidatorError added in v1.16.7 

type ValidatorError struct {
	Message string
}

ValidatorError represents an error state in a CrossValidator. These are validation-level errors (invalid executing messages).

func (*ValidatorError) Error added in v1.16.7 

func (e *ValidatorError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.