L1GasPriceOracle

L1GasPriceOracle is TeQoin's contract-level source of truth for L1 data pricing on L2.

It tracks sequencer-updated L1 fee inputs, exposes a gas-optimized fee path for transaction estimation, and provides the operational controls needed to move from calldata pricing toward blob pricing over time.

About the project

This repository is modeled as a focused smart contract implementation repo in the same spirit as contract-specific projects like ERC721A: one core contract, strong documentation, runnable tests, and a clean path for production integration.

The oracle is responsible for:

• storing current L1 calldata and blob fee inputs
• applying TeQoin's scalar and compression parameters
• exposing a hot-path getL1Fee(bytes) function
• providing a front-end friendly fee breakdown view
• giving the owner and sequencer the operational hooks required for live fee updates

Repository layout

contracts/
  L1GasPriceOracle.sol
  interfaces/IL1GasPriceOracle.sol
docs/
  SPECIFICATION.md
scripts/
  deploy.js
test/
  L1GasPriceOracle.test.js

Contract highlights

• Solidity ^0.8.20
• fixed storage layout for future upgrade paths
• sequencer-gated updates for L1 gas data
• owner-gated admin controls
• Yul-optimized fee calculation hot path
• explicit custom errors
• unit tests covering permissions, bounds, and fee math

Fee model

The effective L1 fee is:

L1_Fee = txDataCost(txData) × l1Price × scalar / 1e6

Where:

• txDataCost applies zero-byte and non-zero-byte calldata pricing
• compressionRatio discounts post-compression data weight
• l1Price selects l1BaseFee or l1BlobBaseFee
• scalar is a dynamic sequencer-controlled multiplier

See docs/SPECIFICATION.md for the full operational model.

Quick start

Install

npm ci

Compile

npm run compile

Test

npm test

Coverage

npm run coverage

Deployment

Copy .env.example to .env and set:

• PRIVATE_KEY
• SEQUENCER_ADDRESS
• TEQOIN_RPC_URL

Then run:

npm run deploy -- --network teqoin

Usage

import "./contracts/interfaces/IL1GasPriceOracle.sol";

contract FeeConsumer {
    IL1GasPriceOracle public immutable oracle;

    constructor(address oracle_) {
        oracle = IL1GasPriceOracle(oracle_);
    }

    function quote(bytes calldata txData) external view returns (uint256) {
        return oracle.getL1Fee(txData);
    }
}

Security

• Treat this contract as part of TeQoin's fee-critical infrastructure.
• Do not disclose vulnerabilities publicly before coordinated review.
• Follow SECURITY.md for reporting.

Contributing

Please read CONTRIBUTING.md before opening a pull request.

License

Distributed under the MIT License. See LICENSE.

Disclaimer

This repository is provided for transparency and integration purposes. Teams integrating with the oracle should perform their own review and testing for their specific usage patterns.