controller.ts

Overview

The [controller.ts](/projects/291/68853) file implements a REST API controller for the Base blockchain network, built atop an Ethereum Virtual Machine (EVM) compatible architecture. It extends a generic `EVM` controller to provide Base-specific endpoints focused on gas estimation and gas fee retrieval. The controller integrates with various services, such as a Blockbook indexer, a Gas Oracle, and an RPC client, to calculate accurate gas costs and fees for transactions on Base.

Key functionalities provided by this controller include:

• Estimating gas costs (both Layer 2 and Layer 1 gas limits) for arbitrary transactions.

• Retrieving current recommended gas fees, including advanced calculations for Base's Layer 1 gas price based on the Gas Price Oracle smart contract.

This controller serves as a critical interface between clients and the underlying blockchain data/services, exposing Base-specific gas-related information via RESTful HTTP endpoints under the `/api/v1` route.

Classes and Methods

class Base

The `Base` class is a REST API controller decorated with [tsoa](/projects/291/68848) annotations to automatically generate OpenAPI specifications and route handlers. It extends the generic `EVM` controller class and implements both [BaseAPI](/projects/291/69264) and `API` interfaces.

It exposes two primary endpoints:

1. estimateGas(body: EstimateGasBody): Promise<BaseGasEstimate>

Estimate the gas cost for a transaction on the Base network.

• Route: POST /api/v1/gas/estimate

• Request Body: EstimateGasBody object containing:

  • data: string — The calldata or transaction data in hex string format.

  • from: string — The sender's address.

  • to: string — The recipient's address.

  • value: string — The amount of Base token (in smallest units) transferred.

• Returns: Promise<BaseGasEstimate> containing:

  • gasLimit: string — Estimated gas limit for the Layer 2 transaction.

  • l1GasLimit: string — Estimated Layer 1 gas limit used for this transaction.

• Errors: Returns HTTP 422 on validation errors and 500 on internal server errors.

**Implementation Details:**

• Calls the service.estimateGas method to get the Layer 2 gas limit.

• Serializes the unsigned transaction using viem utilities.

• Uses the Gas Price Oracle contract's getL1GasUsed method to fetch the Layer 1 gas limit for the serialized transaction.

• Returns both gas limits as strings.

**Usage Example:**

POST /api/v1/gas/estimate
{
  "data": "0x",
  "from": "0x0000000000000000000000000000000000000000",
  "to": "0x15E03a18349cA885482F59935Af48C5fFbAb8DE1",
  "value": "1337"
}

Response:

{
  "gasLimit": "21000",
  "l1GasLimit": "1664"
}

2. getGasFees(): Promise<BaseGasFees>

Retrieve the current recommended gas fees for transactions on Base.

• Route: GET /api/v1/gas/fees

• Returns: Promise<BaseGasFees> object containing:

  • l1GasPrice: string — Layer 1 gas price in wei.

  • baseFeePerGas: string — Base fee per gas unit.

  • slow, average, fast: Objects containing gas price details for different speeds:

    • gasPrice: string

    • maxFeePerGas: string

    • maxPriorityFeePerGas: string

• Errors: Returns HTTP 500 on internal server errors.

**Implementation Details:**

• Calls service.getGasFees() to obtain current Layer 2 gas fees.

• Queries the Gas Price Oracle contract to check if the Base network is in "ecotone" mode.

• If ecotone is enabled:

  • Calculates Layer 1 gas price using a specific formula that combines base fee and blob base fee scalars.

• Otherwise:

  • Uses a legacy calculation for Layer 1 gas price as l1BaseFee * scalar.

• Returns the Layer 1 gas price combined with Layer 2 gas fee estimates.

**Usage Example:**

GET /api/v1/gas/fees

Response:

{
  "l1GasPrice": "5349789102",
  "baseFeePerGas": "51497198",
  "slow": {
    "gasPrice": "51815704",
    "maxFeePerGas": "51947082",
    "maxPriorityFeePerGas": "428650"
  },
  "average": {
    "gasPrice": "53149928",
    "maxFeePerGas": "52728076",
    "maxPriorityFeePerGas": "1209644"
  },
  "fast": {
    "gasPrice": "105353129",
    "maxFeePerGas": "145357641",
    "maxPriorityFeePerGas": "93839209"
  }
}

Important Implementation Details

Environment Variables and Configuration

The file requires several environment variables to be set for operation:

• ETHERSCAN_API_KEY - API key for Etherscan to access explorer APIs.

• INDEXER_URL and INDEXER_WS_URL - URLs for the Blockbook indexer HTTP and WebSocket endpoints.

• INDEXER_API_KEY - API key for the indexer.

• NETWORK - Target blockchain network identifier.

• RPC_URL and RPC_API_KEY - RPC endpoint for direct blockchain JSON-RPC calls.

The controller throws errors at startup if any required environment variables are missing.

Service and Client Initialization

• A PublicClient from viem is created with HTTP transport pointing to the configured RPC URL.

• A Blockbook instance is created for indexer-based blockchain data access.

• A GasOracle instance is created to provide gas price recommendations.

• A Service instance aggregates these components and provides utility methods for gas estimation and fee retrieval.

• The EVM controller's static service property is assigned to this Service instance, enabling inherited methods from the base EVM class to use it.

Gas Price Oracle Contract

• Uses viem's getContract to instantiate a contract interface for the Gas Price Oracle smart contract deployed on Base.

• This contract exposes methods to get Layer 1 gas used by transactions and other fee-related parameters.

Gas Limit Serialization

• The method estimateGas serializes the unsigned transaction with correct parameters using viem utilities before querying the Gas Price Oracle contract.

• The nonce for the transaction is fetched live from the RPC client.

Layer 1 Gas Price Calculation

• Contains specialized logic for "ecotone" mode — a network upgrade or feature.

• The gas price is computed by combining multiple parameters from the Gas Price Oracle contract and scaling factors.

• Uses bignumber.js for arbitrary precision arithmetic to avoid floating-point inaccuracies.

Interaction with Other Parts of the System

• Extends the generic EVM controller, inheriting common Ethereum-compatible blockchain logic.

• Uses shared models such as EstimateGasBody, BaseGasEstimate, and BaseGasFees defined locally and in common API modules.

• Relies heavily on external services:

  • Blockbook: For transaction indexing and blockchain data.

  • GasOracle: For Layer 2 gas fee recommendations.

  • RPC Client (viem): For direct blockchain queries.

  • Gas Price Oracle Contract: For Layer 1 gas fee calculations.

• The controller exposes REST endpoints used by clients and other backend services to fetch gas-related blockchain data specific to the Base network.

Visual Diagram

classDiagram
    class Base {
        +estimateGas(body: EstimateGasBody): Promise<BaseGasEstimate>
        +getGasFees(): Promise<BaseGasFees>
    }
    class EVM {
        <<abstract>>
        +service: Service
    }
    class Service {
        +estimateGas(body: EstimateGasBody): Promise<string>
        +getGasFees(): Promise<object>
    }
    class GasOracle {
        +constructor(logger, client, coinstack)
    }
    class Blockbook {
        +constructor({httpURL, wsURL, logger})
    }
    class PublicClient {
        +getTransactionCount(params): Promise<number>
    }
    class Contract {
        +read.getL1GasUsed(params): Promise<BigNumber>
        +read.isEcotone(): Promise<boolean>
        +read.l1BaseFee(): Promise<BigNumber>
        +read.baseFeeScalar(): Promise<BigNumber>
        +read.blobBaseFeeScalar(): Promise<BigNumber>
        +read.decimals(): Promise<BigNumber>
        +read.scalar(): Promise<BigNumber>
    }

    Base --|> EVM
    Base --> Service : uses
    Service --> GasOracle : uses
    Service --> Blockbook : uses
    Service --> PublicClient : uses
    Base --> Contract : uses (Gas Price Oracle)

Summary

The [controller.ts](/projects/291/68853) file provides the Base blockchain-specific REST API controller extending a generic EVM controller. It exposes endpoints to estimate transaction gas costs and fetch current gas fee recommendations, integrating tightly with blockchain RPC, indexers, and smart contracts. Its design leverages modular services and contracts to deliver accurate Layer 1 and Layer 2 gas metrics, crucial for clients building on the Base network.

The file plays a vital role in bridging blockchain infrastructure components and client applications, encapsulating complex gas fee logic behind simple HTTP endpoints.