@eth-optimism/web3.js-plugin

This web3.js plugin adds utility functions for estimating L1 and L2 gas for OP chains by wrapping the GasPriceOracle contract

The GasPriceOracle is deployed to Optimism and other OP chains at a predeployed address of 0x420000000000000000000000000000000000000F

For more detailed information about gas fees on Optimism's Layer 2, you can visit the official documentation

Installation

This plugin is intended to be registered onto an instance of Web3. It has a peerDependency of web3 version 4.x, so make sure you have that latest version of web3 installed for your project before installing the plugin

Installing the Plugin

pnpm install @eth-optimism/web3.js-plugin

npm install @eth-optimism/web3.js-plugin

yarn add @eth-optimism/web3.js-plugin

Registering the Plugin

import Web3 from 'web3'
import { OptimismPlugin } from '@eth-optimism/web3.js-plugin'

const web3 = new Web3('http://yourProvider.com')
web3.registerPlugin(new OptimismPlugin())

You will now have access to the following functions under the op namespace, i.e. web3.op.someMethod

API

| Function Name | Returns | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | estimateFees | The combined estimated L1 and L2 fees for a transaction | | getL1Fee | The L1 portion of the fee based on the size of the RLP encoded transaction, the current L1 base fee, and other various dynamic parameters | | getL2Fee | The L2 portion of the fee based on the simulated execution of the provided transaction and current gasPrice | | getBaseFee | The current L2 base fee | | getDecimals | The decimals used in the scalar | | getGasPrice | The current L2 gas price | | getL1GasUsed | The amount of L1 gas estimated to be used to execute a transaction | | getL1BaseFee | The L1 base fee | | getOverhead | The current overhead | | getScalar | The current fee scalar | | getVersion | The current version of GasPriceOracle |

estimateFees

Computes the total (L1 + L2) fee estimate to execute a transaction

async estimateFees(transaction: Transaction, returnFormat?: ReturnFormat)

Parameters

• transaction: Transaction - An unsigned web3.js transaction object
• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The estimated total fee as a BigInt by default, but returnFormat determines type

Example

import Web3 from 'web3'
import { OptimismPlugin } from '@eth-optimism/web3.js-plugin'
import {
  l2StandardBridgeABI,
  l2StandardBridgeAddress,
} from '@eth-optimism/contracts-ts'

const web3 = new Web3('https://mainnet.optimism.io')
web3.registerPlugin(new OptimismPlugin())

const l2BridgeContract = new web3.eth.Contract(
  l2StandardBridgeABI,
  optimistAddress[420]
)
const encodedWithdrawMethod = l2BridgeContract.methods
  .withdraw(
    // l2 token address
    '0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000',
    // amount
    Web3.utils.toWei('0.00000001', 'ether'),
    // l1 gas
    0,
    // extra data
    '0x00'
  )
  .encodeABI()

const totalFee = await web3.op.estimateFees({
  chainId: 10,
  data: encodedWithdrawMethod,
  value: Web3.utils.toWei('0.00000001', 'ether'),
  type: 2,
  to: '0x420000000000000000000000000000000000000F',
  from: '0x6387a88a199120aD52Dd9742C7430847d3cB2CD4',
  maxFeePerGas: Web3.utils.toWei('0.2', 'gwei'),
  maxPriorityFeePerGas: Web3.utils.toWei('0.1', 'gwei'),
})

console.log(totalFee) // 26608988767659n

Formatting Response as a Hex String

import Web3 from 'web3'
import { OptimismPlugin } from '@eth-optimism/web3.js-plugin'
import {
  l2StandardBridgeABI,
  l2StandardBridgeAddress,
} from '@eth-optimism/contracts-ts'

const web3 = new Web3('https://mainnet.optimism.io')
web3.registerPlugin(new OptimismPlugin())

const l2BridgeContract = new web3.eth.Contract(
  l2StandardBridgeABI,
  optimistAddress[420]
)
const encodedWithdrawMethod = l2BridgeContract.methods
  .withdraw(
    // l2 token address
    '0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000',
    // amount
    Web3.utils.toWei('0.00000001', 'ether'),
    // l1 gas
    0,
    // extra data
    '0x00'
  )
  .encodeABI()

const totalFee = await web3.op.estimateFees(
  {
    chainId: 10,
    data: encodedWithdrawMethod,
    value: Web3.utils.toWei('0.00000001', 'ether'),
    type: 2,
    to: '0x420000000000000000000000000000000000000F',
    from: '0x6387a88a199120aD52Dd9742C7430847d3cB2CD4',
    maxFeePerGas: Web3.utils.toWei('0.2', 'gwei'),
    maxPriorityFeePerGas: Web3.utils.toWei('0.1', 'gwei'),
  },
  { number: FMT_NUMBER.HEX, bytes: FMT_BYTES.HEX }
)

console.log(totalFee) // 0x18336352c5ab

getL1Fee

Computes the L1 portion of the fee based on the size of the rlp encoded input transaction, the current L1 base fee, and the various dynamic parameters

async getL1Fee(transaction: Transaction, returnFormat?: ReturnFormat)

Parameters

• transaction: Transaction - An unsigned web3.js transaction object
• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The estimated L1 fee as a BigInt by default, but returnFormat determines type

Example

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l1Fee = await web3.op.getL1Fee({
  chainId: 10,
  data: encodedBurnMethod,
  type: 2,
})

console.log(l1Fee) // 18589035222172n

Formatting Response as a Hex String

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l1Fee = await web3.op.getL1Fee(
  {
    chainId: 10,
    data: encodedBurnMethod,
    type: 2,
  },
  { number: FMT_NUMBER.HEX, bytes: FMT_BYTES.HEX }
)

console.log(l1Fee) // 0x10e818d7549c

getL2Fee

Retrieves the amount of L2 gas estimated to execute transaction

async getL2Fee(transaction: Transaction, returnFormat?: ReturnFormat)

Parameters

• transaction: Transaction - An unsigned web3.js transaction object
• options?: { blockNumber?: BlockNumberOrTag, returnFormat?: ReturnFormat } - An optional object with properties:
  • blockNumber?: BlockNumberOrTag - Specifies what block to use for gas estimation. Can be either:
    • Note Specifying a block to estimate L2 gas for is currently not working
    • A web3.js Numbers
    • A web3.js BlockTags
    • If not provided, BlockTags.LATEST is used
  • returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
    • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The estimated total fee as a BigInt by default, but returnFormat determines type

Example

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l2Fee = await web3.op.getL2Fee({
  chainId: '0xa',
  data: encodedBurnMethod,
  type: '0x2',
  to: optimistAddress[420],
  from: '0x77194aa25a06f932c10c0f25090f3046af2c85a6',
})

console.log(l2Fee) // 2659500n

Formatting Response as a Hex String

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l2Fee = await web3.op.getL2Fee(
  {
    chainId: '0xa',
    data: encodedBurnMethod,
    type: '0x2',
    to: optimistAddress[420],
    from: '0x77194aa25a06f932c10c0f25090f3046af2c85a6',
  },
  {
    returnFormat: { number: FMT_NUMBER.HEX, bytes: FMT_BYTES.HEX },
  }
)

console.log(l2Fee) // 0x2894ac

getBaseFee

Retrieves the current L2 base fee

async getBaseFee(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The L2 base fee as a BigInt by default, but returnFormat determines type

Example

const baseFee = await web3.op.getBaseFee()

console.log(baseFee) // 68n

Formatting Response as a Hex String

const baseFee = await web3.op.getBaseFee({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(baseFee) // 0x44

getDecimals

Retrieves the decimals used in the scalar

async getDecimals(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The number of decimals as a BigInt by default, but returnFormat determines type

Example

const decimals = await web3.op.getDecimals()

console.log(decimals) // 6n

Formatting Response as a Hex String

const decimals = await web3.op.getDecimals({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(decimals) // 0x6

getGasPrice

Retrieves the current L2 gas price (base fee)

async getGasPrice(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The current L2 gas price as a BigInt by default, but returnFormat determines type

Example

const gasPrice = await web3.op.getGasPrice()

console.log(gasPrice) // 77n

Formatting Response as a Hex String

const gasPrice = await web3.op.getGasPrice({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(gasPrice) // 0x4d

getL1GasUsed

Computes the amount of L1 gas used for {transaction}. Adds the overhead which represents the per-transaction gas overhead of posting the {transaction} and state roots to L1. Adds 68 bytes of padding to account for the fact that the input does not have a signature.

async getL1GasUsed(transaction: Transaction, returnFormat?: ReturnFormat)

Parameters

• transaction: Transaction - An unsigned web3.js transaction object
• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The amount of gas as a BigInt by default, but returnFormat determines type

Example

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l1GasUsed = await web3.op.getL1GasUsed({
  chainId: 10,
  data: encodedBurnMethod,
  type: 2,
})

console.log(l1GasUsed) // 1884n

Formatting Response as a Hex String

import { Contract } from 'web3'
import { optimistABI, optimistAddress } from '@eth-optimism/contracts-ts'

const optimistContract = new Contract(optimistABI, optimistAddress[420])
const encodedBurnMethod = optimistContract.methods
  .burn('0x77194aa25a06f932c10c0f25090f3046af2c85a6')
  .encodeABI()

const l1GasUsed = await web3.op.getL1GasUsed(
  {
    chainId: 10,
    data: encodedBurnMethod,
    type: 2,
  },
  { number: FMT_NUMBER.HEX, bytes: FMT_BYTES.HEX }
)

console.log(l1GasUsed) // 0x75c

getL1BaseFee

Retrieves the latest known L1 base fee

async getL1BaseFee(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The L1 base fee as a BigInt by default, but returnFormat determines type

Example

const baseFee = await web3.op.getL1BaseFee()

console.log(baseFee) // 13752544112n

Formatting Response as a Hex String

const baseFee = await web3.op.getL1BaseFee({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(baseFee) // 0x333b72b70

getOverhead

Retrieves the current fee overhead

async getOverhead(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The current overhead as a BigInt by default, but returnFormat determines type

Example

const overhead = await web3.op.getOverhead()

console.log(overhead) // 188n

Formatting Response as a Hex String

const overhead = await web3.op.getOverhead({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(overhead) // 0xbc

getScalar

Retrieves the current fee scalar

async getScalar(returnFormat?: ReturnFormat)

Parameters

• returnFormat?: ReturnFormat - A web3.js DataFormat object that specifies how to format number and bytes values
  • If returnFormat is not provided, DEFAULT_RETURN_FORMAT is used which will format numbers to BigInts

Returns

• Promise<Numbers> - The current scalar fee as a BigInt by default, but returnFormat determines type

Example

const scalarFee = await web3.op.getScalar()

console.log(scalarFee) // 684000n

Formatting Response as a Hex String

const scalarFee = await web3.op.getScalar({
  number: FMT_NUMBER.HEX,
  bytes: FMT_BYTES.HEX,
})

console.log(scalarFee) // 0xa6fe0

getVersion

Retrieves the full semver version of GasPriceOracle

async getVersion()

Returns

• Promise<string> - The semver version

Example

const version = await web3.op.getVersion()

console.log(version) // 1.0.0

Known Issues

• As of version 4.0.3 of web3.js, both input and data parameters are automatically added to a transaction objects causing the gas estimations to be inflated. This was corrected in this PR, but has yet to be released
• For the plugin function getL2Fee, you should be able to get the fee estimates using the state of the blockchain at a specified block, however, this doesn't seem to be working with web3.js and requires further investigation