Add onchain gas cost to trades and orders APIs by jmg-duarte · Pull Request #4540 · cowprotocol/services

jmg-duarte · 2026-06-19T14:11:26Z

Description

The removal of UCP means that we no longer have fees and gas costs info in a single place, meaning the FE must calculate them; the issue comes when one notices that we don't keep track of gas costs for settlements (meaning trades and orders don't either).

This PR adds gas cost tracking, when settlements get indexed, they will now be indexed with the gas cost.
The PR does not do backfills on purpose, that must be done as a separate process.

Changes

DB migrations
OpenAPI updates
DB queries for trades and orders to include gas costs
Update indexing to include gas costs

How to test

Sepolia staging is currently suspended with this code there, please do a trade and review the UI using this link
https://jmgd-ucp.explorer-dev-dxz.pages.dev/

Under costs and fees you should see this:

Persist the actual settlement gas (gas_used, effective_gas_price) read from the transaction receipt — previously computed by the autopilot but only logged since the settlement_observations table was dropped in V090 — and expose a per-trade `gasCost` (native token wei). Attribution: each trade gets its share of the settlement transaction's gas cost (gas_used * effective_gas_price), split equally across all trades settled in the same transaction. - V111 migration: nullable gas_used + effective_gas_price on settlements - autopilot save_settlement writes them (going-forward only, no backfill) - trades query computes per-trade gas_cost in SQL - model + openapi documentation for the new gasCost field on trades Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Expose a per-order `gasCost` (native token wei): the sum, across the order's fills, of each trade's share of its settlement transaction's gas cost (gas_used * effective_gas_price), split equally across all trades settled in the same transaction. Builds on the settlement gas now persisted for trades. - order_gas_costs aggregates the per-trade gas attribution per order_uid - orders wired on the single_order / many_orders read paths - model + openapi documentation for the new gasCost field on orders Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-19T14:11:42Z

Reminder: Please update the DB Readme and comment whether migrations are reversible (include rollback scripts if applicable).

If creating new tables, update the tables list.
When adding a new index, consider using CREATE INDEX CONCURRENTLY for tables involved in the critical execution path.
For breaking changes, remember that during rollout k8s starts the new autopilot, runs the Flyway migration, and only then shuts down the old pod. That overlap means the previous version can still be processing requests on the migrated schema, so make it compatible first and ship the breaking DB change in the following release.

Caused by:

database/sql/V111__add_gas_to_settlements.sql

github-actions · 2026-06-19T14:11:43Z

Reminder: Please consider backward compatibility when modifying the API specification.
If breaking changes are unavoidable, ensure:

You explicitly pointed out breaking changes.
You communicate the changes to affected teams (at least Frontend team and SAFE team).
You provide proper versioning and migration mechanisms.

Caused by:

crates/orderbook/openapi.yml

claude · 2026-06-19T14:11:52Z

Claude finished @jmg-duarte's task in 4m 13s —— View job

PR Review: Add on-chain gas cost to trades and orders APIs

I reviewed the diff against origin/main. The overall approach is solid — sharing the GAS_COST_EXPR between trades and order_gas_costs so they can't drift, and moving the settlement/gas join onto the paginated page CTE (instead of every UNION branch) is a nice performance win. I verified the autopilot stores genuine receipt values (receipt.gas_used, receipt.effective_gas_price), so the "actual on-chain" framing in the OpenAPI is accurate.

I left 3 inline comments:

crates/model/src/order.rs:715 — incorrect doc comment. Says the value is "derived from its quote (gas_amount * gas_price)", but it's actually the on-chain settlement gas cost. The None condition is wrong too.
crates/model/src/trade.rs:34 — same incorrect doc comment, plus the "(e.g. JIT orders)" note is misleading (JIT orders do get a gas cost).
database/sql/V111 — deploy-ordering caveat. The orderbook queries reference the new columns unconditionally; confirm V111 is applied before the new orderbook serves traffic.

The doc-comment mismatches (1 & 2) read like leftovers from an earlier quote-based design — worth fixing since they directly contradict the OpenAPI and the implementation.

Minor (non-blocking)

gas_cost uses skip_serializing_if = "Option::is_none", so the field is omitted when absent, while the OpenAPI marks it nullable: true (implying an explicit null). Consistent with other optional fields here, so likely fine — just flagging the spec/impl nuance for the FE.
DB tests for the rewritten trades query (cargo nextest run postgres ...) aren't runnable in this environment — worth confirming they pass, since the query restructure is substantial.

gemini-code-assist

Code Review

This pull request implements tracking and persistence of actual on-chain gas costs for settlements, trades, and orders, including database migrations, query updates, and OpenAPI documentation. The reviewer feedback highlights that the docstrings for the gas_cost fields in both the OrderMetadata and Trade models are incorrect and misleading, as they describe the value as an estimated cost derived from quotes rather than the actual on-chain gas cost.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-19T14:13:54Z

+    /// Estimated network gas cost (in native token wei) of executing this
+    /// order, derived from its quote (`gas_amount * gas_price`). `None` when
+    /// the order has no stored quote.
+    #[serde_as(as = "Option<HexOrDecimalU256>")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gas_cost: Option<U256>,


The docstring for gas_cost is incorrect and misleading. It states that the gas cost is an "Estimated network gas cost... derived from its quote", but the PR actually implements and exposes the actual on-chain gas cost attributed to the order (as documented in the OpenAPI spec and implemented in the database queries). Please update the docstring to accurately reflect that this is the actual on-chain gas cost.

Suggested change

/// Estimated network gas cost (in native token wei) of executing this

/// order, derived from its quote (`gas_amount * gas_price`). `None` when

/// the order has no stored quote.

#[serde_as(as = "Option<HexOrDecimalU256>")]

#[serde(default, skip_serializing_if = "Option::is_none")]

pub gas_cost: Option<U256>,

/// Actual on-chain gas cost (in native token wei) attributed to this

/// order. Computed as the order's share of the gas cost

/// (gas_used * effective_gas_price) of the settlement transaction(s)

/// that executed it, split equally across all trades settled in the same

/// transaction, and summed across the order's fills. None for orders

/// settled before this data started being recorded, or not yet settled.

#[serde_as(as = "Option<HexOrDecimalU256>")]

#[serde(default, skip_serializing_if = "Option::is_none")]

pub gas_cost: Option<U256>,

gemini-code-assist · 2026-06-19T14:13:54Z

+    /// Estimated network gas cost (in native token wei) of executing this
+    /// trade, derived from the order's quote (`gas_amount * gas_price`).
+    /// `None` when the order has no stored quote (e.g. JIT orders).
+    #[serde_as(as = "Option<HexOrDecimalU256>")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gas_cost: Option<U256>,


The docstring for gas_cost is incorrect and misleading. It states that the gas cost is an "Estimated network gas cost... derived from the order's quote", but the PR actually implements and exposes the actual on-chain gas cost attributed to the trade. Please update the docstring to accurately reflect that this is the actual on-chain gas cost.

/// Actual on-chain gas cost (in native token wei) attributed to this /// trade. Computed as this trade's share of the settlement transaction's /// gas cost (gas_used * effective_gas_price), split equally across all /// trades settled in the same transaction. None for trades settled /// before this data started being recorded. #[serde_as(as = "Option<HexOrDecimalU256>")] #[serde(default, skip_serializing_if = "Option::is_none")] pub gas_cost: Option<U256>,

claude · 2026-06-19T14:15:57Z

+    /// Estimated network gas cost (in native token wei) of executing this
+    /// order, derived from its quote (`gas_amount * gas_price`). `None` when
+    /// the order has no stored quote.


This doc comment is incorrect and contradicts both the implementation and the OpenAPI spec. The value populated into gas_cost comes from database::trades::order_gas_costs, i.e. the actual on-chain settlement gas cost (gas_used * effective_gas_price from the receipt, split across trades) — not the quote (gas_amount * gas_price). The None condition is also wrong: it's None for orders settled before V111 or not yet settled, not "the order has no stored quote".

Suggested change

/// Estimated network gas cost (in native token wei) of executing this

/// order, derived from its quote (`gas_amount * gas_price`). `None` when

/// the order has no stored quote.

/// Actual on-chain gas cost (in native token wei) attributed to this order:

/// its share of the settlement transaction(s)' gas cost

/// (`gas_used * effective_gas_price`), split equally across all trades in

/// each settlement and summed across the order's fills. `None` for orders

/// settled before this data was recorded (see V111), or not yet settled.

claude · 2026-06-19T14:16:01Z

+    /// Estimated network gas cost (in native token wei) of executing this
+    /// trade, derived from the order's quote (`gas_amount * gas_price`).
+    /// `None` when the order has no stored quote (e.g. JIT orders).


Same issue as the OrderMetadata::gas_cost comment: this is the actual on-chain gas cost (this trade's share of the settlement's gas_used * effective_gas_price), not a quote-derived estimate. The "None ... (e.g. JIT orders)" claim is also misleading — JIT orders have trades and settlements, so they do get a gas cost here; the value is None only for trades settled before V111.

Suggested change

/// Estimated network gas cost (in native token wei) of executing this

/// trade, derived from the order's quote (`gas_amount * gas_price`).

/// `None` when the order has no stored quote (e.g. JIT orders).

/// Actual on-chain gas cost (in native token wei) attributed to this trade:

/// its share of the settlement transaction's gas cost

/// (`gas_used * effective_gas_price`), split equally across all trades

/// settled in the same transaction. `None` for trades settled before this

/// data was recorded (see V111).

claude · 2026-06-19T14:16:09Z

+ALTER TABLE settlements
+    ADD COLUMN gas_used numeric(78, 0),
+    ADD COLUMN effective_gas_price numeric(78, 0);


Deploy-ordering caveat worth confirming: the orderbook trades / order_gas_costs queries now reference s.gas_used and s.effective_gas_price unconditionally. If a new orderbook pod starts serving before this migration has been applied (the migration is run by autopilot's Flyway, a separate deployment), every trades/orders query will fail with column "gas_used" does not exist. Please make sure V111 is applied before (or atomically with) the new orderbook rollout — see the bot's backward-compatibility reminder above.

MartinquaXD

Main concern is the error prone settlement <> trade association via log indices and the fact that this estimate can be very much off. Was that discussed with the solver / frontend team?

MartinquaXD · 2026-06-22T08:16:21Z


+/// SQL expression computing a single trade's share of its settlement's on-chain
+/// gas cost: the settlement's total cost (`gas_used * effective_gas_price`)
+/// divided equally across all trades settled in the same transaction. Expects


This can be wildly inaccurate because a super complicated order can be batched together with a simple order. I don't think there is a way to make this more accurate with reasonable effort - just wanted to flag this in case you weren't aware.

I knew all this could be innacurate, the idea is to give an estimate (slightly better than "solver reported" as they can simply write a different value)

MartinquaXD · 2026-06-22T08:20:06Z

+    WHERE s.block_number = page.block_number
+    AND   s.log_index > page.log_index


I think deciding to not store the tx_hash in the trades table was a blunder back in the day which leads to this ugly code again and again. Also unless I'm missing something this code does not handle trades from multiple settlements in the same block correctly.
WDYT about introducing the tx_hash column on the trades table to simply join on that? Since we can already get the association using the log index this data can even be fully backfilled using a DB migration alone.

MartinquaXD · 2026-06-22T08:24:42Z

+            .transpose()?;
+
+        if let Some(order) = order.as_mut() {
+            order.metadata.gas_cost = attributed_gas_cost(&mut ex, uid).await?;


Feels like this logic should already be handled in single_full_order_with_quote(), no?

MartinquaXD · 2026-06-22T08:29:58Z


+/// Total on-chain gas cost (native token wei) attributed to a single order
+/// across all of its trades. See [`database::trades::order_gas_costs`].
+async fn attributed_gas_cost(


maybe accumulative_gas_cost expresses the concept of the function better?

MartinquaXD · 2026-06-22T08:33:34Z

+            Actual on-chain gas cost attributed to this order, in native token
+            wei. Computed as the order's share of the gas cost


This exposes a ton of implementation details the user doesn't care about, no?
Key pieces of info appear to be:

it's an estimate (no need to explain how we estimate IMO)

it's an ETH value (instead of gas units)

may not be populated for old orders (unsettled orders could just get a 0 here, no?)

Same applies to the other openapi field

squadgazzz · 2026-06-22T09:03:57Z

            database::jit_orders::get_many_by_uid(&mut ex_jit_orders, &uids)
        )?;
+
+        let gas_costs = database::trades::order_gas_costs(&mut ex_orders, &uids)


single_order and many_orders set gas_cost, but user_orders (/account/{owner}/orders) and orders_for_tx (/transactions/{tx}/orders) return None, since they build the order through full_order_into_model_order and skip this step. A client fetching the same order then sees gasCost over /orders/{uid} and null over /account/{owner}/orders. Is it intentional? If the FE lists costs on the account orders page, it reads null there.

squadgazzz · 2026-06-22T09:17:31Z

+pub async fn order_gas_costs(
+    ex: &mut PgConnection,
+    order_uids: &[OrderUid],
+) -> Result<Vec<(OrderUid, BigDecimal)>, sqlx::Error> {


Should it be covered with a small DB test to pin it down: one block, two settlements in different txs, a few trades each, then assert each trade's share and the per-order sum.

jmg-duarte and others added 2 commits June 18, 2026 11:13

jmg-duarte requested a review from a team as a code owner June 19, 2026 14:11

gemini-code-assist Bot reviewed Jun 19, 2026

View reviewed changes

claude Bot reviewed Jun 19, 2026

View reviewed changes

MartinquaXD reviewed Jun 22, 2026

View reviewed changes

squadgazzz reviewed Jun 22, 2026

View reviewed changes

-    /// Estimated network gas cost (in native token wei) of executing this
-    /// order, derived from its quote (`gas_amount * gas_price`). `None` when
-    /// the order has no stored quote.
+    /// Actual on-chain gas cost (in native token wei) attributed to this order:
+    /// its share of the settlement transaction(s)' gas cost
+    /// (`gas_used * effective_gas_price`), split equally across all trades in
+    /// each settlement and summed across the order's fills. `None` for orders
+    /// settled before this data was recorded (see V111), or not yet settled.

		WHERE s.block_number = page.block_number
		AND s.log_index > page.log_index

		Actual on-chain gas cost attributed to this order, in native token
		wei. Computed as the order's share of the gas cost

Conversation

jmg-duarte commented Jun 19, 2026

Description

Changes

How to test

Uh oh!

github-actions Bot commented Jun 19, 2026

Uh oh!

github-actions Bot commented Jun 19, 2026

Uh oh!

claude Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Add on-chain gas cost to trades and orders APIs

Minor (non-blocking)

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

MartinquaXD left a comment

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

squadgazzz Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

squadgazzz Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

claude Bot commented Jun 19, 2026 •

edited

Loading

jmg-duarte Jun 22, 2026 •

edited

Loading