feat: introduces the new BaseServiceV2 class

Introduces the new BaseServiceV2 class to eventually replace the older
BaseService class. BaseServiceV2 includes many convenience features like
automatic environment variable and argv parsing.

.changeset/twenty-walls-turn.md

+---
+'@eth-optimism/common-ts': patch
+---
+
+Introduces the new BaseServiceV2 class.

packages/common-ts/package.json

@@ -31,14 +31,23 @@
     "url": "https://github.com/ethereum-optimism/optimism.git"
   },
   "dependencies": {
+    "@eth-optimism/core-utils": "^0.7.7",
     "@sentry/node": "^6.3.1",
+    "bcfg": "^0.1.7",
+    "commander": "^9.0.0",
+    "dotenv": "^16.0.0",
+    "envalid": "^7.2.2",
+    "ethers": "^5.5.4",
     "express": "^4.17.1",
+    "lodash": "^4.17.21",
     "pino": "^6.11.3",
     "pino-multi-stream": "^5.3.0",
     "pino-sentry": "^0.7.0",
     "prom-client": "^13.1.0"
   },
   "devDependencies": {
+    "@ethersproject/abstract-provider": "^5.5.1",
+    "@ethersproject/abstract-signer": "^5.5.0",
     "@types/chai": "^4.2.18",
     "@types/express": "^4.17.12",
     "@types/mocha": "^8.2.2",

packages/common-ts/src/base-service/base-service-v2.ts

+/* Imports: External */
+import Config from 'bcfg'
+import * as dotenv from 'dotenv'
+import { Command, Option } from 'commander'
+import { ValidatorSpec, Spec, cleanEnv } from 'envalid'
+import { sleep } from '@eth-optimism/core-utils'
+import snakeCase from 'lodash/snakeCase'
+
+/* Imports: Internal */
+import { Logger } from '../common/logger'
+import { Metric } from './metrics'
+
+export type Options = {
+  [key: string]: any
+}
+
+export type OptionsSpec<TOptions extends Options> = {
+  [P in keyof Required<TOptions>]: {
+    validator: (spec?: Spec<TOptions[P]>) => ValidatorSpec<TOptions[P]>
+    desc: string
+    default?: TOptions[P]
+  }
+}
+
+export type MetricsV2 = {
+  [key: string]: Metric
+}
+
+export type MetricsSpec<TMetrics extends MetricsV2> = {
+  [P in keyof Required<TMetrics>]: {
+    type: new (configuration: any) => TMetrics[P]
+    desc: string
+    labels?: string[]
+  }
+}
+
+/**
+ * BaseServiceV2 is an advanced but simple base class for long-running TypeScript services.
+ */
+export abstract class BaseServiceV2<
+  TOptions extends Options,
+  TMetrics extends MetricsV2,
+  TServiceState
+> {
+  /**
+   * Whether or not the service will loop.
+   */
+  protected loop: boolean
+
+  /**
+   * Waiting period in ms between loops, if the service will loop.
+   */
+  protected loopIntervalMs: number
+
+  /**
+   * Logger class for this service.
+   */
+  protected logger: Logger
+
+  /**
+   * Service state, persisted between loops.
+   */
+  protected state: TServiceState
+
+  /**
+   * Service options.
+   */
+  protected readonly options: TOptions
+
+  /**
+   * Metrics.
+   */
+  protected readonly metrics: TMetrics
+
+  /**
+   * @param params Options for the construction of the service.
+   * @param params.name Name for the service. This name will determine the prefix used for logging,
+   * metrics, and loading environment variables.
+   * @param params.optionsSpec Settings for input options. You must specify at least a
+   * description for each option.
+   * @param params.metricsSpec Settings that define which metrics are collected. All metrics that
+   * you plan to collect must be defined within this object.
+   * @param params.options Options to pass to the service.
+   * @param params.loops Whether or not the service should loop. Defaults to true.
+   * @param params.loopIntervalMs Loop interval in milliseconds. Defaults to zero.
+   */
+  constructor(params: {
+    name: string
+    optionsSpec: OptionsSpec<TOptions>
+    metricsSpec: MetricsSpec<TMetrics>
+    options?: Partial<TOptions>
+    loop?: boolean
+    loopIntervalMs?: number
+  }) {
+    this.loop = params.loop !== undefined ? params.loop : true
+    this.loopIntervalMs =
+      params.loopIntervalMs !== undefined ? params.loopIntervalMs : 0
+    this.state = {} as TServiceState
+
+    // Use commander as a way to communicate info about the service. We don't actually *use*
+    // commander for anything besides the ability to run `ts-node ./service.ts --help`.
+    const program = new Command()
+    for (const [optionName, optionSpec] of Object.entries(params.optionsSpec)) {
+      program.addOption(
+        new Option(`--${optionName.toLowerCase()}`, `${optionSpec.desc}`).env(
+          `${params.name
+            .replace(/-/g, '_')
+            .toUpperCase()}__${optionName.toUpperCase()}`
+        )
+      )
+    }
+
+    const longestMetricNameLength = Object.keys(params.metricsSpec).reduce(
+      (acc, key) => {
+        const nameLength = snakeCase(key).length
+        if (nameLength > acc) {
+          return nameLength
+        } else {
+          return acc
+        }
+      },
+      0
+    )
+
+    program.addHelpText(
+      'after',
+      `\nMetrics:\n${Object.entries(params.metricsSpec)
+        .map(([metricName, metricSpec]) => {
+          const parsedName = snakeCase(metricName)
+          return `  ${parsedName}${' '.repeat(
+            longestMetricNameLength - parsedName.length + 2
+          )}${metricSpec.desc} (type: ${metricSpec.type.name})`
+        })
+        .join('\n')}
+      `
+    )
+
+    // Load all configuration values from the environment and argv.
+    program.parse()
+    dotenv.config()
+    const config = new Config(params.name)
+    config.load({
+      env: true,
+      argv: true,
+    })
+
+    // Clean configuration values using the options spec.
+    // Since BCFG turns everything into lower case, we're required to turn all of the input option
+    // names into lower case for the validation step. We'll turn the names back into their original
+    // names when we're done.
+    const cleaned = cleanEnv<TOptions>(
+      { ...config.env, ...config.args },
+      Object.entries(params.optionsSpec || {}).reduce((acc, [key, val]) => {
+        acc[key.toLowerCase()] = val.validator({
+          desc: val.desc,
+          default: val.default,
+        })
+        return acc
+      }, {}) as any,
+      Object.entries(params.options || {}).reduce((acc, [key, val]) => {
+        acc[key.toLowerCase()] = val
+        return acc
+      }, {}) as any
+    )
+
+    // Turn the lowercased option names back into camelCase.
+    this.options = Object.keys(params.optionsSpec || {}).reduce((acc, key) => {
+      acc[key] = cleaned[key.toLowerCase()]
+      return acc
+    }, {}) as TOptions
+
+    // Create the metrics objects.
+    this.metrics = Object.keys(params.metricsSpec || {}).reduce((acc, key) => {
+      const spec = params.metricsSpec[key]
+      acc[key] = new spec.type({
+        name: `${snakeCase(params.name)}_${snakeCase(key)}`,
+        help: spec.desc,
+        labelNames: spec.labels || [],
+      })
+      return acc
+    }, {}) as TMetrics
+
+    this.logger = new Logger({ name: params.name })
+  }
+
+  /**
+   * Runs the main function. If this service is set up to loop, will repeatedly loop around the
+   * main function. Will also catch unhandled errors.
+   */
+  public run(): void {
+    const _run = async () => {
+      if (this.init) {
+        this.logger.info('initializing service')
+        await this.init()
+        this.logger.info('service initialized')
+      }
+
+      if (this.loop) {
+        this.logger.info('starting main loop')
+        while (true) {
+          try {
+            await this.main()
+          } catch (err) {
+            this.logger.error('caught an unhandled exception', {
+              message: err.message,
+              stack: err.stack,
+              code: err.code,
+            })
+          }
+
+          // Always sleep between loops
+          await sleep(this.loopIntervalMs)
+        }
+      } else {
+        this.logger.info('running main function')
+        await this.main()
+      }
+    }
+
+    _run()
+  }
+
+  /**
+   * Initialization function. Runs once before the main function.
+   */
+  protected init?(): Promise<void>
+
+  /**
+   * Main function. Runs repeatedly when run() is called.
+   */
+  protected abstract main(): Promise<void>
+}

packages/common-ts/src/base-service.ts → packages/common-ts/src/base-service/base-service.ts

 /* Imports: Internal */
-import { Logger } from './common/logger'
-import { Metrics } from './common/metrics'
+import { Logger } from '../common/logger'
+import { Metrics } from '../common/metrics'
 
 type OptionSettings<TOptions> = {
   [P in keyof TOptions]?: {

packages/common-ts/src/base-service/index.ts

+export * from './base-service'
+export * from './base-service-v2'
+export * from './validators'
+export * from './metrics'

packages/common-ts/src/base-service/metrics.ts

+import {
+  Gauge as PGauge,
+  Counter as PCounter,
+  Histogram as PHistogram,
+  Summary as PSummary,
+} from 'prom-client'
+
+export class Gauge extends PGauge<string> {}
+export class Counter extends PCounter<string> {}
+export class Histogram extends PHistogram<string> {}
+export class Summary extends PSummary<string> {}
+export type Metric = Gauge | Counter | Histogram | Summary

packages/common-ts/src/base-service/validators.ts

+import {
+  str,
+  bool,
+  num,
+  email,
+  host,
+  port,
+  url,
+  json,
+  makeValidator,
+} from 'envalid'
+import { Provider } from '@ethersproject/abstract-provider'
+import { Signer } from '@ethersproject/abstract-signer'
+import { ethers } from 'ethers'
+
+const provider = makeValidator<Provider>((input) => {
+  const parsed = url()._parse(input)
+  return new ethers.providers.JsonRpcProvider(parsed)
+})
+
+const wallet = makeValidator<Signer>((input) => {
+  if (!ethers.utils.isHexString(input)) {
+    throw new Error(`expected wallet to be a hex string`)
+  } else {
+    return new ethers.Wallet(input)
+  }
+})
+
+export const validators = {
+  str,
+  bool,
+  num,
+  email,
+  host,
+  port,
+  url,
+  json,
+  wallet,
+  provider,
+}

packages/contracts/docs/Initializable.md

@@ -6,7 +6,7 @@
 
 
 
-*This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed behind a proxy. Since a proxied contract can't have a constructor, it's common to move constructor logic to an external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer function so it can only be called once. The {initializer} modifier provided by this contract will have this effect. TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}. CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure that all initializers are idempotent. This is not verified automatically as constructors are by Solidity. [CAUTION] ==== Avoid leaving a contract uninitialized. An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation contract, which may impact the proxy. To initialize the implementation contract, you can either invoke the initializer manually, or you can include a constructor to automatically mark it as initialized when it is deployed: [.hljs-theme-light.nopadding] ```*
+*This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed behind a proxy. Since a proxied contract can't have a constructor, it's common to move constructor logic to an external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer function so it can only be called once. The {initializer} modifier provided by this contract will have this effect. TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}. CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.*
 
 
 

packages/message-relayer/src/service.ts

 /* Imports: External */
 import { Wallet } from 'ethers'
 import { sleep } from '@eth-optimism/core-utils'
-import { Logger, BaseService, Metrics } from '@eth-optimism/common-ts'
 import {
-  CrossChainMessenger,
-  MessageStatus,
-  ProviderLike,
-} from '@eth-optimism/sdk'
-
-interface MessageRelayerOptions {
-  /**
-   * Provider for interacting with L2.
-   */
-  l2RpcProvider: ProviderLike
-
-  /**
-   * Wallet used to interact with L1.
-   */
-  l1Wallet: Wallet
-
-  /**
-   * Gas to relay transactions with. If not provided, will use the estimated gas for the relay
-   * transaction.
-   */
-  relayGasLimit?: number
-
-  /**
-   * Index of the first L2 transaction to start processing from.
-   */
+  BaseServiceV2,
+  validators,
+  Gauge,
+  Counter,
+} from '@eth-optimism/common-ts'
+import { CrossChainMessenger, MessageStatus } from '@eth-optimism/sdk'
+import { Provider } from '@ethersproject/abstract-provider'
+
+type MessageRelayerOptions = {
+  l1RpcProvider: Provider
+  l2RpcProvider: Provider
+  l1Wallet: Signer
   fromL2TransactionIndex?: number
 
-  /**
-   * Waiting interval between loops when the service is at the tip.
-   */
-  pollingInterval?: number
-
-  /**
-   * Size of the block range to query when looking for new SentMessage events.
-   */
-  getLogsInterval?: number
-
-  /**
-   * Logger to transport logs. Defaults to STDOUT.
-   */
-  logger?: Logger
-
-  /**
-   * Metrics object to use. Defaults to no metrics.
-   */
-  metrics?: Metrics
+type MessageRelayerMetrics = {
+  highestCheckedL2Tx: Gauge
+  highestKnownL2Tx: Gauge
+  numRelayedMessages: Counter
 }
 
-export class MessageRelayerService extends BaseService<MessageRelayerOptions> {
-  constructor(options: MessageRelayerOptions) {
-    super('Message_Relayer', options, {
-      relayGasLimit: {
-        default: 4_000_000,
+type MessageRelayerState = {
+  wallet: Signer
+  messenger: CrossChainMessenger
+  highestCheckedL2Tx: number
+  highestKnownL2Tx: number
+}
+
+export class MessageRelayerService extends BaseServiceV2<
+  MessageRelayerOptions,
+  MessageRelayerMetrics,
+  MessageRelayerState
+> {
+  constructor(options?: Partial<MessageRelayerOptions>) {
+    super({
+      name: 'Message_Relayer',
+      options,
+      optionsSpec: {
+        l1RpcProvider: {
+          validator: validators.provider,
+          desc: 'Provider for interacting with L1.',
+        },
+        l2RpcProvider: {
+          validator: validators.provider,
+          desc: 'Provider for interacting with L2.',
+        },
+        l1Wallet: {
+          validator: validators.wallet,
+          desc: 'Wallet used to interact with L1.',
         },
         fromL2TransactionIndex: {
+          validator: validators.num,
+          desc: 'Index of the first L2 transaction to start processing from.',
           default: 0,
         },
-      pollingInterval: {
-        default: 5000,
       },
-      getLogsInterval: {
-        default: 2000,
+      metricsSpec: {
+        highestCheckedL2Tx: {
+          type: Gauge,
+          desc: 'Highest L2 tx that has been scanned for messages',
+        },
+        highestKnownL2Tx: {
+          type: Gauge,
+          desc: 'Highest known L2 transaction',
+        },
+        numRelayedMessages: {
+          type: Counter,
+          desc: 'Number of messages relayed by the service',
+        },
       },
     })
   }
@@ -93,22 +98,22 @@ export class MessageRelayerService extends BaseService<MessageRelayerOptions> {
     this.state.highestCheckedL2Tx = this.options.fromL2TransactionIndex || 1
   }
 
-  protected async _start(): Promise<void> {
-    while (this.running) {
-      await sleep(this.options.pollingInterval)
+  protected async main(): Promise<void> {
+    // Update metrics
+    this.metrics.highestCheckedL2Tx.set(this.state.highestCheckedL2Tx)
+    this.metrics.highestKnownL2Tx.set(this.state.highestKnownL2Tx)
 
-      try {
-        // Loop strategy is as follows:
-        // 1. Get the current L2 tip
-        // 2. While we're not at the tip:
-        //    2.1. Get the transaction for the next L2 block to parse.
-        //    2.2. Find any messages sent in the L2 block.
-        //    2.3. Make sure all messages are ready to be relayed.
-        //    3.4. Relay the messages.
-        const l2BlockNumber =
+    // If we're already at the tip, then update the latest tip and loop again.
+    if (this.state.highestCheckedL2Tx > this.state.highestKnownL2Tx) {
+      this.state.highestKnownL2Tx =
         await this.state.messenger.l2Provider.getBlockNumber()
 
-        while (this.state.highestCheckedL2Tx <= l2BlockNumber) {
+      // Sleeping for 1000ms is good enough since this is meant for development and not for live
+      // networks where we might want to restrict the number of requests per second.
+      await sleep(1000)
+      return
+    }
+
     this.logger.info(`checking L2 block ${this.state.highestCheckedL2Tx}`)
 
     const block =
@@ -127,56 +132,16 @@ export class MessageRelayerService extends BaseService<MessageRelayerOptions> {
       block.transactions[0].hash
     )
 
-          // No messages in this transaction so we can move on to the next one.
-          if (messages.length === 0) {
-            this.state.highestCheckedL2Tx++
-            continue
-          }
-
-          // Make sure that all messages sent within the transaction are finalized. If any messages
-          // are not finalized, then we're going to break the loop which will trigger the sleep and
-          // wait for a few seconds before we check again to see if this transaction is finalized.
-          let isFinalized = true
-          for (const message of messages) {
-            const status = await this.state.messenger.getMessageStatus(message)
-            if (
-              status === MessageStatus.IN_CHALLENGE_PERIOD ||
-              status === MessageStatus.STATE_ROOT_NOT_PUBLISHED
-            ) {
-              isFinalized = false
-            }
-          }
-
-          if (!isFinalized) {
-            this.logger.info(
-              `tx not yet finalized, waiting: ${this.state.highestCheckedL2Tx}`
-            )
-            break
-          } else {
-            this.logger.info(
-              `tx is finalized, relaying: ${this.state.highestCheckedL2Tx}`
-            )
-          }
-
-          // If we got here then all messages in the transaction are finalized. Now we can relay
-          // each message to L1.
-          for (const message of messages) {
       try {
         const tx = await this.state.messenger.finalizeMessage(message)
         this.logger.info(`relayer sent tx: ${tx.hash}`)
+        this.metrics.numRelayedMessages.inc()
       } catch (err) {
         if (err.message.includes('message has already been received')) {
           // It's fine, the message was relayed by someone else
         } else {
           throw err
         }
-            }
-            await this.state.messenger.waitForMessageReceipt(message)
-          }
-
-          // All messages have been relayed so we can move on to the next block.
-          this.state.highestCheckedL2Tx++
-        }
       } catch (err) {
         this.logger.error('Caught an unhandled error', {
           message: err.toString(),

yarn.lock

@@ -4407,6 +4407,13 @@ bcfg@^0.1.6:
   dependencies:
     bsert "~0.0.10"
 
+bcfg@^0.1.7:
+  version "0.1.7"
+  resolved "https://registry.yarnpkg.com/bcfg/-/bcfg-0.1.7.tgz#610198a67a56160305fdc1f54b5b5c90b52530d7"
+  integrity sha512-+4beq5bXwfmxdcEoHYQsaXawh1qFzjLcRvPe5k5ww/NEWzZTm56Jk8LuPmfeGB7X584jZ8xGq6UgMaZnNDa5Ww==
+  dependencies:
+    bsert "~0.0.10"
+
 bcrypt-pbkdf@^1.0.0:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz#a4301d389b6a43f9b67ff3ca11a3f6637e360e9e"
@@ -5383,6 +5390,11 @@ commander@^8.3.0:
   resolved "https://registry.yarnpkg.com/commander/-/commander-8.3.0.tgz#4837ea1b2da67b9c616a67afbb0fafee567bca66"
   integrity sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==
 
+commander@^9.0.0:
+  version "9.0.0"
+  resolved "https://registry.yarnpkg.com/commander/-/commander-9.0.0.tgz#86d58f24ee98126568936bd1d3574e0308a99a40"
+  integrity sha512-JJfP2saEKbQqvW+FI93OYUB4ByV5cizMpFMiiJI8xDbBvQvSkIk0VvQdn1CZ8mqAO8Loq2h0gYTYtDFUZUeERw==
+
 comment-parser@1.1.6-beta.0:
   version "1.1.6-beta.0"
   resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.1.6-beta.0.tgz#57e503b18d0a5bd008632dcc54b1f95c2fffe8f6"
@@ -6142,6 +6154,11 @@ dotenv@^10.0.0:
   resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-10.0.0.tgz#3d4227b8fb95f81096cdd2b66653fb2c7085ba81"
   integrity sha512-rlBi9d8jpv9Sf1klPjNfFAuWDjKLwTIJJ/VxtoTwIR6hnZxcEOQCZg2oIL3MWBYw5GpUDKOEnND7LXTbIpQ03Q==
 
+dotenv@^16.0.0:
+  version "16.0.0"
+  resolved "https://registry.yarnpkg.com/dotenv/-/dotenv-16.0.0.tgz#c619001253be89ebb638d027b609c75c26e47411"
+  integrity sha512-qD9WU0MPM4SWLPJy/r2Be+2WgQj8plChsyrCNQzW/0WjvcJQiKQJ9mH3ZgB3fxbUUxgc/11ZJ0Fi5KiimWGz2Q==
+
 dotignore@~0.1.2:
   version "0.1.2"
   resolved "https://registry.yarnpkg.com/dotignore/-/dotignore-0.1.2.tgz#f942f2200d28c3a76fbdd6f0ee9f3257c8a2e905"
@@ -6288,6 +6305,13 @@ envalid@^7.1.0:
   dependencies:
     tslib "2.3.1"
 
+envalid@^7.2.2:
+  version "7.2.2"
+  resolved "https://registry.yarnpkg.com/envalid/-/envalid-7.2.2.tgz#f3219f85e692002dca0f28076740227d30c817e3"
+  integrity sha512-bl/3VF5PhoF26HlDWiE0NRRHUbKT/+UDP/+0JtOFmhUwK3cUPS7JgWYGbE8ArvA61T+SyNquxscLCS6y4Wnpdw==
+  dependencies:
+    tslib "2.3.1"
+
 envinfo@^7.7.4:
   version "7.8.1"
   resolved "https://registry.yarnpkg.com/envinfo/-/envinfo-7.8.1.tgz#06377e3e5f4d379fea7ac592d5ad8927e0c4d475"