This web3.js plugin adds utility functions for estimating L1 and L2 gas for OP chains by wrapping the [GasPriceOracle](../contracts-bedrock/contracts/l2/GasPriceOracle.sol) contract
The GasPriceOracle is [deployed to Optimism](https://optimistic.etherscan.io/address/0x420000000000000000000000000000000000000F) 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](https://community.optimism.io/docs/developers/build/transaction-fees/#the-l2-execution-fee)
## Installation
This plugin is intended to be [registered](https://docs.web3js.org/guides/web3_plugin_guide/plugin_users#registering-the-plugin) onto an instance of `Web3`. It has a [peerDependency](https://nodejs.org/es/blog/npm/peer-dependencies) of `web3` version `4.x`, so make sure you have that latest version of `web3` installed for your project before installing the plugin
| [estimateFees](#estimatefees) | The combined estimated L1 and L2 fees for a transaction |
| [getL1Fee](#getl1fee) | The L1 portion of the fee based on the size of the [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) encoded transaction, the current L1 base fee, and other various dynamic parameters |
| [getL2Fee](#getl2fee) | The L2 portion of the fee based on the simulated execution of the provided transaction and current `gasPrice` |
| [getBaseFee](#getbasefee) | The current L2 base fee |
| [getDecimals](#getdecimals) | The decimals used in the scalar |
| [getGasPrice](#getgasprice) | The current L2 gas price |
| [getL1GasUsed](#getl1gasused) | The amount of L1 gas estimated to be used to execute a transaction |
| [getL1BaseFee](#getdegetl1basefeecimals) | The L1 base fee |
| [getOverhead](#getoverhead) | The current overhead |
| [getScalar](#getscalar) | The current fee scalar |
| [getVersion](#getversion) | The current version of `GasPriceOracle` |
---
### `estimateFees`
Computes the total (L1 + L2) fee estimate to execute a transaction
-`transaction: Transaction` - An unsigned web3.js [transaction](https://docs.web3js.org/api/web3-types/interface/Transaction) object
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The estimated total fee as a `BigInt` by default, but `returnFormat` determines type
-`transaction: Transaction` - An unsigned web3.js [transaction](https://docs.web3js.org/api/web3-types/interface/Transaction) object
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The estimated L1 fee as a `BigInt` by default, but `returnFormat` determines type
-`transaction: Transaction` - An unsigned web3.js [transaction](https://docs.web3js.org/api/web3-types/interface/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](https://docs.web3js.org/api/web3-types#Numbers)
- A web3.js [BlockTags](https://docs.web3js.org/api/web3-types/enum/BlockTags)
- If not provided, `BlockTags.LATEST` is used
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The estimated total fee as a `BigInt` by default, but `returnFormat` determines type
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The L2 base fee as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constbaseFee=awaitweb3.op.getBaseFee()
console.log(baseFee)// 68n
```
##### Formatting Response as a Hex String
```typescript
constbaseFee=awaitweb3.op.getBaseFee({
number:FMT_NUMBER.HEX,
bytes:FMT_BYTES.HEX,
})
console.log(baseFee)// 0x44
```
### `getDecimals`
Retrieves the decimals used in the scalar
```typescript
asyncgetDecimals(returnFormat?:ReturnFormat)
```
#### Parameters
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The number of decimals as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constdecimals=awaitweb3.op.getDecimals()
console.log(decimals)// 6n
```
##### Formatting Response as a Hex String
```typescript
constdecimals=awaitweb3.op.getDecimals({
number:FMT_NUMBER.HEX,
bytes:FMT_BYTES.HEX,
})
console.log(decimals)// 0x6
```
### `getGasPrice`
Retrieves the current L2 gas price (base fee)
```typescript
asyncgetGasPrice(returnFormat?:ReturnFormat)
```
#### Parameters
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The current L2 gas price as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constgasPrice=awaitweb3.op.getGasPrice()
console.log(gasPrice)// 77n
```
##### Formatting Response as a Hex String
```typescript
constgasPrice=awaitweb3.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.
-`transaction: Transaction` - An unsigned web3.js [transaction](https://docs.web3js.org/api/web3-types/interface/Transaction) object
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The amount of gas as a `BigInt` by default, but `returnFormat` determines type
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The L1 base fee as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constbaseFee=awaitweb3.op.getL1BaseFee()
console.log(baseFee)// 13752544112n
```
##### Formatting Response as a Hex String
```typescript
constbaseFee=awaitweb3.op.getL1BaseFee({
number:FMT_NUMBER.HEX,
bytes:FMT_BYTES.HEX,
})
console.log(baseFee)// 0x333b72b70
```
### `getOverhead`
Retrieves the current fee overhead
```typescript
asyncgetOverhead(returnFormat?:ReturnFormat)
```
#### Parameters
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The current overhead as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constoverhead=awaitweb3.op.getOverhead()
console.log(overhead)// 188n
```
##### Formatting Response as a Hex String
```typescript
constoverhead=awaitweb3.op.getOverhead({
number:FMT_NUMBER.HEX,
bytes:FMT_BYTES.HEX,
})
console.log(overhead)// 0xbc
```
### `getScalar`
Retrieves the current fee scalar
```typescript
asyncgetScalar(returnFormat?:ReturnFormat)
```
#### Parameters
-`returnFormat?: ReturnFormat` - A web3.js [DataFormat](https://docs.web3js.org/api/web3-types#DataFormat) object that specifies how to format number and bytes values
- If `returnFormat` is not provided, [DEFAULT_RETURN_FORMAT](https://docs.web3js.org/api/web3-types#DEFAULT_RETURN_FORMAT) is used which will format numbers to `BigInt`s
#### Returns
-`Promise<Numbers>` - The current scalar fee as a `BigInt` by default, but `returnFormat` determines type
#### Example
```typescript
constscalarFee=awaitweb3.op.getScalar()
console.log(scalarFee)// 684000n
```
##### Formatting Response as a Hex String
```typescript
constscalarFee=awaitweb3.op.getScalar({
number:FMT_NUMBER.HEX,
bytes:FMT_BYTES.HEX,
})
console.log(scalarFee)// 0xa6fe0
```
### `getVersion`
Retrieves the full semver version of GasPriceOracle
```typescript
asyncgetVersion()
```
#### Returns
-`Promise<string>` - The semver version
#### Example
```typescript
constversion=awaitweb3.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](https://github.com/web3/web3.js/pull/6294) 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
