PI-4: Demand for Soil Adjustments

Executed on December 8, 2024 at 06:46 UTC.

Summary

1. Increasing Demand Window: Extend the period at the beginning of the Season during which demand for Soil is considered increasing if all but 1 Soil is Sown into, from 10 to 20 minutes.

2. Steady Demand Range: Extend the range during which demand for Soil is considered steady if all but 1 Soil is Sown into across the previous 2 Seasons, from ±1 to ±5 minutes, subject to the increasing-demand conditions.

Links

• Implementation PR

• Implementation Commit: a5af7e0f6b1aed7ad64a9413d96ffa0bb35eee3c

• Safe Transaction

• Diamond Cut Transaction

Problems

1. Increasing Demand Window

PI-3 extended the duration of the Morning Auction from 5 to 10 minutes. Demand for Soil was considered increasing when all but 1 Soil is Sown into in the first 10 minutes of the Season. As a result of the increase in the duration of the Morning Auction, Soil was never offered at the Maximum Temperature during the period in which this condition could be met.

2. Steady Demand Range

Measuring the relative time it takes for Soil to be Sown into across Seasons in order to measure demand for Soil was not particularly reliable at this early stage of the Pinto protocol. Accordingly, only checking the relative time within a 1 minute range was not likely to properly indicate relative demand across Seasons.

Solutions

1. Increasing Demand Window

• Increase SOW_TIME_DEMAND_INCR from 600 (10 minutes) to 1200 (20 minutes). Demand is considered increasing when all but 1 Soil is Sown into before minute 20 of the Season, allowing this condition to be met after the Morning Auction ends.

2. Steady Demand Range

• Increase SOW_TIME_STEADY from 60 (1 minute) to 300 (5 minutes). If all but 1 Soil is Sown into in both consecutive Seasons, demand is considered steady when the sellout times differ by no more than 5 minutes, unless an increasing-demand condition applies.

Rationale

1. Increasing Demand Window

By extending the duration within a Season in which demand will always be measured as increasing in the instance where all but 1 Soil is Sown into from 10 to 20 minutes, it allows for a period in which the protocol is offering Soil at the Maximum Temperature where this condition can be met. This remedies the removal of this opportunity that was created by doubling the duration of the Morning Auction from 5 to 10 minutes in PI-3.

2. Steady Demand Range

By expanding the range in which a steady demand for Soil measurement can occur in the instance where all but 1 Soil is Sown into across the previous 2 Seasons, the protocol can more accurately understand Soil demand across Seasons and respond with the appropriate Maximum Temperature change.

Contract Changes

Initialization

No initializer was called. The Diamond Cut used the zero address, so this upgrade performed no one-time state reset.

Facet Changes

All three facet source files were unchanged. The replacements incorporated the updated demand calculation in SeasonFacet and GaugeGettersFacet and the new LibWellMinting deployment linked by SeasonGettersFacet.

Other Contract / Parameter Changes

Updated LibEvaluate.SOW_TIME_DEMAND_INCR from 600 to 1200 seconds (10 to 20 minutes) and LibEvaluate.SOW_TIME_STEADY from 60 to 300 seconds (1 to 5 minutes).

Updated the linked library implementations below (previous → new). SeasonFacet linked all seven libraries, and SeasonGettersFacet linked LibWellMinting. Only LibEvaluate had a production source change in this upgrade. The other six libraries were redeployed with unchanged own source files. GaugeGettersFacet had no externally linked libraries.

Externally Linked Libraries

Function Changes

• Updated the internal LibEvaluate.calcDeltaPodDemand logic to classify demand as increasing when Soil sells out in less than 1200 seconds. The existing rule also classifies demand as increasing if Soil sold out this Season but not in the preceding Season. The same helper supplies GaugeGettersFacet.getDeltaPodDemand() and the demand component of the weather case used by SeasonFacet. Soil is treated as sold out when at most 1 Soil remains.

• Widened the sellout-time comparison in LibEvaluate.calcDeltaPodDemand from 60 to 300 seconds. Subject to the earlier increasing-demand conditions, demand is increasing if Soil sells out more than 300 seconds faster than in the preceding Season, steady within the inclusive ±300-second window, and decreasing if more than 300 seconds slower. No public function or event signature changed.

Event Changes

• Changed the demand component of the weather case through the longer increasing-demand window and wider steady-demand tolerance. This can change the caseId emitted by TemperatureChange and BeanToMaxLpGpPerBdvRatioChange. It can also change the absChange emitted by TemperatureChange. With other inputs fixed, the demand classification does not change the absChange emitted by BeanToMaxLpGpPerBdvRatioChange because each set of three demand cases uses the same ratio adjustment. Event signatures, emission timing, existing clamps, and the oracle-failure guard on the latter event were unchanged.