@eth-optimism/web3js-plugin
v0.1.0
Published
A Web3.js plugin for doing OP-Chain gas estimation
Downloads
8
Readme
@eth-optimism/web3js-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/web3js-plugin
npm install @eth-optimism/web3js-plugin
yarn add @eth-optimism/web3js-plugin
Registering the Plugin
import Web3 from 'web3'
import OptimismFeeEstimationPlugin from '@eth-optimism/web3js-plugin'
const web3 = new Web3('http://yourProvider.com')
web3.registerPlugin(new OptimismFeeEstimationPlugin())
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 objectreturnFormat?: 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 toBigInt
s
- If
Returns
Promise<Numbers>
- The estimated total fee as aBigInt
by default, butreturnFormat
determines type
Example
import Web3 from 'web3'
import {
l2StandardBridgeABI,
l2StandardBridgeAddress,
} from '@eth-optimism/contracts-ts'
const web3 = new Web3('https://mainnet.optimism.io')
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 {
l2StandardBridgeABI,
l2StandardBridgeAddress,
} from '@eth-optimism/contracts-ts'
const web3 = new Web3('https://mainnet.optimism.io')
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 objectreturnFormat?: 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 toBigInt
s
- If
Returns
Promise<Numbers>
- The estimated L1 fee as aBigInt
by default, butreturnFormat
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 objectoptions?: { blockNumber?: BlockNumberOrTag, returnFormat?: ReturnFormat }
- An optional object with properties:blockNumber?: BlockNumberOrTag
- Specifies what block to use for gas estimation. Can be either: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 toBigInt
s
- If
Returns
Promise<Numbers>
- The estimated total fee as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The L2 base fee as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The number of decimals as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The current L2 gas price as aBigInt
by default, butreturnFormat
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 objectreturnFormat?: 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 toBigInt
s
- If
Returns
Promise<Numbers>
- The amount of gas as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The L1 base fee as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The current overhead as aBigInt
by default, butreturnFormat
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 toBigInt
s
- If
Returns
Promise<Numbers>
- The current scalar fee as aBigInt
by default, butreturnFormat
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, bothinput
anddata
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