Gas Oracle Integration

Purpose

This integration subtopic addresses the challenge of incorporating dynamic gas fee data into the blockchain API services for Ethereum and EVM-compatible chains. While the parent topic focuses on estimating gas fees based on recent blockchain data, Gas Oracle Integration ensures these estimates are consumable and accessible through the service API layer. It bridges raw gas fee calculations with practical API endpoints that clients use for transaction cost estimation and fee retrieval, enabling accurate and real-time fee information for users submitting transactions.

Functionality

The Gas Oracle Integration is implemented as part of the service layer (`Service` class) within the EVM coinstack API. It leverages a `GasOracle` instance responsible for collecting and estimating gas fees. This integration exposes methods that:

• Start the gas oracle process to continuously update fee estimates.

• Provide API methods to retrieve current gas fee data categorized by speed tiers such as slow, average, and fast.

• Incorporate these gas fees into transaction-related workflows, enabling clients to query gas prices before sending transactions.

Key workflows include:

• Initialization: Upon service instantiation, the gas oracle's start() method is called to begin fetching and updating gas fee data in the background.

• Fee Retrieval: The getGasFees() method queries the gas oracle for the latest base fee and estimates at multiple percentiles (e.g., 1%, 60%, 90%) to represent slow, average, and fast fees.

• Gas Estimation: The service’s estimateGas() method uses a blockchain client to estimate the gas limit for a given transaction payload, complementing the gas price data from the gas oracle.

These workflows provide an API-consumable abstraction over raw gas fee data, enabling client applications to dynamically adjust transaction fees based on network conditions.

Code Snippet Illustrating Gas Fee Retrieval

async getGasFees(): Promise<GasFees> {
  const baseFeePerGas = this.gasOracle.getBaseFeePerGas()
  const estimatedFees = await this.gasOracle.estimateFees([1, 60, 90])

  return {
    baseFeePerGas,
    slow: estimatedFees['1'],
    average: estimatedFees['60'],
    fast: estimatedFees['90'],
  }
}

This method fetches the base fee and estimated fees at different percentiles, packaging them into a structured response for API clients.

Relationship

Gas Oracle Integration complements the parent Gas Fee Estimation subtopic by operationalizing the estimated gas fees into accessible API endpoints. It acts as the bridge that exposes gas fee data to external clients through the unified API layer, thus enabling:

• Upstream Consumption: Clients can retrieve real-time gas fee data when preparing transactions, improving transaction cost accuracy.

• Downstream Coordination: The gas estimation workflow uses blockchain client calls to estimate gas limits, combining fee pricing with gas usage estimation for comprehensive transaction cost prediction.

• Integration with Transaction Workflows: When transactions are sent (sendTx), the gas fee data provided by this integration helps clients set appropriate fees, reducing failed or delayed transactions due to incorrect fee assumptions.

Unlike the parent topic or the Gas Fee Estimation subtopic, which focus on internal fee calculation logic, this integration subtopic focuses on the service layer’s role in managing, updating, and exposing gas fee data seamlessly within the API server.

It also ties into other API functionalities such as transaction history and sending transactions by ensuring fee information stays accurate and up-to-date, thereby enhancing the overall user experience.

Diagram

sequenceDiagram
    participant Service as API Service Layer
    participant GasOracle as Gas Oracle Module
    participant Client as API Consumer

    Note over Service,GasOracle: Initialization
    Service->>GasOracle: start()
    GasOracle-->>Service: Begin periodic fee updates

    Note over Client,Service: Client requests gas fees
    Client->>Service: GET /gas-fees
    Service->>GasOracle: getBaseFeePerGas()
    GasOracle-->>Service: baseFeePerGas
    Service->>GasOracle: estimateFees([1,60,90])
    GasOracle-->>Service: estimatedFees
    Service-->>Client: Return fees {slow, average, fast, baseFeePerGas}

    Note over Client,Service: Client estimates gas limit for tx
    Client->>Service: POST /estimate-gas (tx data)
    Service->>Service.client: estimateGas(tx)
    Service.client-->>Service: gasLimit
    Service-->>Client: Return gasLimit

This sequence diagram highlights the core interaction flows between the API service, the gas oracle module, and the API clients, showing how gas fee data is initialized, updated, and served in response to client requests.