Add backlog to setGasPricingConstraints and improve comments

Author: MishkaRogachev

ArbGasInfo.sol

@@ -49,6 +49,8 @@ interface ArbGasInfo {
     function getPricesInArbGas() external view returns (uint256, uint256, uint256);
 
     /// @notice Get the gas accounting parameters. `gasPoolMax` is always zero, as the exponential pricing model has no such notion.
+    /// @notice Starting from ArbOS version 50, returns `speedLimitPerSecond` as the target from the longest-period constraint.
+    /// @notice For new integrations, prefer `getMaxBlockGasLimit` and `getGasPricingConstraints`.
     /// @return (speedLimitPerSecond, gasPoolMax, maxBlockGasLimit)
     /// @dev Deprecated starting from ArbOS version 50.
     function getGasAccountingParams() external view returns (uint256, uint256, uint256);
@@ -81,14 +83,20 @@ interface ArbGasInfo {
     function getCurrentTxL1GasFees() external view returns (uint256);
 
     /// @notice Get the backlogged amount of gas burnt in excess of the speed limit
+    /// @notice Starting from ArbOS version 50, returns the backlog of the longest-period constraint among all configured constraints.
+    /// @notice For new integrations, prefer `getGasPricingConstraints`.
     /// @dev Deprecated starting from ArbOS version 50.
     function getGasBacklog() external view returns (uint64);
 
     /// @notice Get how slowly ArbOS updates the L2 basefee in response to backlogged gas
+    /// @notice Starting from ArbOS version 50, returns the inertia value derived from the longest-period constraint
+    /// @notice For new integrations, prefer `getGasPricingConstraints`.
     /// @dev Deprecated starting from ArbOS version 50.
     function getPricingInertia() external view returns (uint64);
 
     /// @notice Get the forgivable amount of backlogged gas ArbOS will ignore when raising the basefee
+    /// @notice Starting from ArbOS version 50, this function always returns zero.
+    /// @notice There is no tolerance for backlogged gas in the new pricing model.
     /// @dev Deprecated starting from ArbOS version 50.
     function getGasBacklogTolerance() external view returns (uint64);
 
@@ -130,10 +138,10 @@ interface ArbGasInfo {
     function getMaxBlockGasLimit() external view returns (uint64);
 
     /// @notice Get the current gas pricing constraints used by the Multi-Constraint Pricer.
-    /// @notice Each constraint contains:
-    ///         - uint64 gas_target (in gas/second)
-    ///         - uint64 time_constant (in seconds)
-    ///         - uint64 backlog (in gas units)
+    /// @notice Each constraint contains the following values:
+    ///         - `uint64 gas_target_per_second`: target gas usage per second
+    ///         - `uint64 time_constant_seconds`: time constant in seconds
+    ///         - `uint64 backlog`: current backlog in gas units
     /// @return constraints Array of triples (gas_target_per_second, time_constant_seconds, backlog)
     /// @notice Available in ArbOS version 50 and above.
     function getGasPricingConstraints() external view returns (uint64[3][] memory constraints);

ArbOwner.sol

@@ -77,8 +77,9 @@ interface ArbOwner {
     ) external;
 
     /// @notice Set the computational speed limit for the chain
+    /// @notice Starting from ArbOS version 50, this function always returns an error.
+    /// @notice Use `setGasPricingConstraints` instead, which supports configuring multiple constraints.
     /// @dev Deprecated starting from ArbOS version 50.
-    ///      Replaced by `setGasPricingConstraints`, which supports multiple constraints.
     function setSpeedLimit(
         uint64 limit
     ) external;
@@ -95,15 +96,17 @@ interface ArbOwner {
     ) external;
 
     /// @notice Set the L2 gas pricing inertia
+    /// @notice Starting from ArbOS version 50, this function always returns an error.
+    /// @notice Use `setGasPricingConstraints` instead, which supports configuring multiple constraints.
     /// @dev Deprecated starting from ArbOS version 50.
-    ///      Replaced by `setGasPricingConstraints`, which supports multiple constraints.
     function setL2GasPricingInertia(
         uint64 sec
     ) external;
 
     /// @notice Set the L2 gas backlog tolerance
+    /// @notice Starting from ArbOS version 50, this function always returns an error.
+    /// @notice Use `setGasPricingConstraints` instead, which supports configuring multiple constraints.
     /// @dev Deprecated starting from ArbOS version 50.
-    ///      Ignored by the Multi-Constraint Pricer model.
     function setL2GasBacklogTolerance(
         uint64 sec
     ) external;
@@ -281,11 +284,15 @@ interface ArbOwner {
     ) external;
 
     /// @notice Sets the list of gas pricing constraints for the Multi-Constraint Pricer.
-    /// @notice Replaces existing constraints configuration and resets all backlogs to zero.
+    /// @notice Replaces the existing constraints configuration and sets each constraint's starting backlog value.
+    /// @notice All existing backlogs are replaced by the provided values.
+    /// @notice Any changes to gas targets, periods, or starting backlogs may cause immediate price fluctuations.
+    /// @notice Operators are fully responsible for the resulting behavior and should adjust parameters carefully.
+    /// @notice Use ArbGasInfo.getGasPricingConstraints() to retrieve the current configuration.
     /// @notice Available in ArbOS version 50 and above.
-    /// @param constraints Array of pairs (gas_target_per_second, time_constant_seconds)
+    /// @param constraints Array of triples (gas_target_per_second, period_seconds, starting_backlog_value)
     function setGasPricingConstraints(
-        uint64[2][] calldata constraints
+        uint64[3][] calldata constraints
     ) external;
 
     /// Emitted when a successful call is made to this precompile