> For the complete documentation index, see [llms.txt](https://docs.pinto.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pinto.money/pinto-improvements/pi-4.md).

# PI-4: Demand for Soil Adjustments

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

## Summary <a href="#id-9fde4019-aad5-83c1-8bcd-81d575675753" id="id-9fde4019-aad5-83c1-8bcd-81d575675753"></a>

1. **Increasing Demand Window:** Extend the period at the beginning of the [Season](https://docs.pinto.money/resources/glossary#season) during which demand for [Soil](https://docs.pinto.money/resources/glossary#soil) is considered increasing if all but 1 Soil is [Sown](https://docs.pinto.money/resources/glossary#sow) 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 <a href="#id-2e5e4019-aad5-8279-b0fa-819be5e093d3" id="id-2e5e4019-aad5-8279-b0fa-819be5e093d3"></a>

* [Implementation PR](https://github.com/pinto-org/protocol/pull/5)
* Implementation Commit: [a5af7e0f6b1aed7ad64a9413d96ffa0bb35eee3c](https://github.com/pinto-org/protocol/commit/a5af7e0f6b1aed7ad64a9413d96ffa0bb35eee3c)
* [Safe Transaction](https://app.safe.global/transactions/tx?id=multisig_0x2cf82605402912C6a79078a9BBfcCf061CbfD507_0x35bc85e01cce0f40022ddba7e3f15a82fcfd59d0389ed26773b7dda39b20df0b\&safe=base:0x2cf82605402912C6a79078a9BBfcCf061CbfD507)
* [Diamond Cut Transaction](https://basescan.org/tx/0x3568202444211c3177a11bd5abe2a6da2bc0a8cb82497b422d3bf69fd01893dd)

## Problems <a href="#ba9e4019-aad5-82c1-ae40-81114c5c077e" id="ba9e4019-aad5-82c1-ae40-81114c5c077e"></a>

### 1. Increasing Demand Window <a href="#id-65ee4019-aad5-8347-8a95-81b064b0a071" id="id-65ee4019-aad5-8347-8a95-81b064b0a071"></a>

[PI-3](https://pinto.money/pi/4//pi/3/) extended the duration of the [Morning Auction](https://docs.pinto.money/resources/glossary#morning) 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](https://docs.pinto.money/resources/glossary#maximum-temperature) during the period in which this condition could be met.

### 2. Steady Demand Range <a href="#id-175e4019-aad5-8210-9310-815e88bad9b3" id="id-175e4019-aad5-8210-9310-815e88bad9b3"></a>

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](https://docs.pinto.money/resources/glossary#pinto) protocol. Accordingly, only checking the relative time within a 1 minute range was not likely to properly indicate relative demand across Seasons.

## **Solutions** <a href="#id-9cae4019-aad5-823a-8dde-01c240c844d1" id="id-9cae4019-aad5-823a-8dde-01c240c844d1"></a>

### 1. Increasing Demand Window <a href="#fd2e4019-aad5-8352-9821-01f0526b5453" id="fd2e4019-aad5-8352-9821-01f0526b5453"></a>

* 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 <a href="#id-8eee4019-aad5-839b-a9df-01f1f5732347" id="id-8eee4019-aad5-839b-a9df-01f1f5732347"></a>

* 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 <a href="#id-056e4019-aad5-83b9-9681-81b785c6088d" id="id-056e4019-aad5-83b9-9681-81b785c6088d"></a>

### 1. Increasing Demand Window <a href="#id-02ae4019-aad5-82c9-abc8-012b209d806f" id="id-02ae4019-aad5-82c9-abc8-012b209d806f"></a>

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 <a href="#id-245e4019-aad5-833d-9205-0150fd1999c3" id="id-245e4019-aad5-833d-9205-0150fd1999c3"></a>

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 <a href="#id-289e4019-aad5-8212-91a0-819860fc1638" id="id-289e4019-aad5-8212-91a0-819860fc1638"></a>

### Initialization <a href="#aa4e4019-aad5-8354-997c-81d589378bc8" id="aa4e4019-aad5-8354-997c-81d589378bc8"></a>

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

### **Facet** Changes <a href="#id-6a8e4019-aad5-8357-beae-01ee470f82ad" id="id-6a8e4019-aad5-8357-beae-01ee470f82ad"></a>

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`.

| **Facet**            | **Action** | **Previous Implementation**                                                                                                  | **New Implementation**                                                                                                       |
| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `SeasonFacet`        | Replace    | [`0x6Ea855d9473168f4540D4818976Ea814ECBf3456`](https://basescan.org/address/0x6Ea855d9473168f4540D4818976Ea814ECBf3456#code) | [`0x15cBDFaF5715F2a1B6e23b3ef7c4D67843a6C836`](https://basescan.org/address/0x15cBDFaF5715F2a1B6e23b3ef7c4D67843a6C836#code) |
| `GaugeGettersFacet`  | Replace    | [`0xD26a44C9F7C58864c2ea938BE9E2f0Ae25954bc2`](https://basescan.org/address/0xD26a44C9F7C58864c2ea938BE9E2f0Ae25954bc2#code) | [`0x34eaa05624E0B8cFAB251571E429fD88Cec7ec12`](https://basescan.org/address/0x34eaa05624E0B8cFAB251571E429fD88Cec7ec12#code) |
| `SeasonGettersFacet` | Replace    | [`0xD0813e2378A73B7cB49Bd4ff6a4Bf67EdcEa1264`](https://basescan.org/address/0xD0813e2378A73B7cB49Bd4ff6a4Bf67EdcEa1264#code) | [`0x995E1cA9Bd858bff94448dCC0E097bd4d564e74B`](https://basescan.org/address/0x995E1cA9Bd858bff94448dCC0E097bd4d564e74B#code) |

### Other Contract / Parameter Changes <a href="#id-845e4019-aad5-8308-9ac0-81d3b95eb42b" id="id-845e4019-aad5-8308-9ac0-81d3b95eb42b"></a>

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**

| Library          | Previous Implementation                                                                                                      | New Implementation                                                                                                           | Used By                             |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `LibEvaluate`    | [`0x7a7d5a8899f9d68530ef3c551b9cb5610bc9bd02`](https://basescan.org/address/0x7a7d5a8899f9d68530ef3c551b9cb5610bc9bd02#code) | [`0x595eb8aa763325235f988eedc582d74046fd7bca`](https://basescan.org/address/0x595eb8aa763325235f988eedc582d74046fd7bca#code) | `SeasonFacet`                       |
| `LibGauge`       | [`0x6c2736cfc57c1328b7d3db611812297c9754e230`](https://basescan.org/address/0x6c2736cfc57c1328b7d3db611812297c9754e230#code) | [`0xe7e55a27a369bef6d20dd081ff7ddff90d6f7482`](https://basescan.org/address/0xe7e55a27a369bef6d20dd081ff7ddff90d6f7482#code) | `SeasonFacet`                       |
| `LibIncentive`   | [`0xeb9bd84e354e68142e8e996823887edb4dfcf433`](https://basescan.org/address/0xeb9bd84e354e68142e8e996823887edb4dfcf433#code) | [`0xfe1fe5508b33401c20e45fcd10161783de443479`](https://basescan.org/address/0xfe1fe5508b33401c20e45fcd10161783de443479#code) | `SeasonFacet`                       |
| `LibShipping`    | [`0x64d40771f9f6490afe20c135dc07ea48b8addc78`](https://basescan.org/address/0x64d40771f9f6490afe20c135dc07ea48b8addc78#code) | [`0x86c9bdf4b2a7ab22c90048f0d741b81c546895b7`](https://basescan.org/address/0x86c9bdf4b2a7ab22c90048f0d741b81c546895b7#code) | `SeasonFacet`                       |
| `LibWellMinting` | [`0x7124f182847880f4961de89068b249c3299304af`](https://basescan.org/address/0x7124f182847880f4961de89068b249c3299304af#code) | [`0x4e81e73a1ca24ff99a79914a887d13b9c641e2f2`](https://basescan.org/address/0x4e81e73a1ca24ff99a79914a887d13b9c641e2f2#code) | `SeasonFacet`, `SeasonGettersFacet` |
| `LibFlood`       | [`0xed513e167369af0119090d67b8910c02b2b468f6`](https://basescan.org/address/0xed513e167369af0119090d67b8910c02b2b468f6#code) | [`0x249ae0deb8f7ebccaa574c7396c7d099d87e7e3d`](https://basescan.org/address/0x249ae0deb8f7ebccaa574c7396c7d099d87e7e3d#code) | `SeasonFacet`                       |
| `LibGerminate`   | [`0x384374407a64aa24d3335ff12c870debaa04c3e5`](https://basescan.org/address/0x384374407a64aa24d3335ff12c870debaa04c3e5#code) | [`0x7c748262b168e85a5e0973021e44b163fcb578d9`](https://basescan.org/address/0x7c748262b168e85a5e0973021e44b163fcb578d9#code) | `SeasonFacet`                       |

### Function Changes <a href="#id-8cce4019-aad5-82f1-9156-01bc8f644038" id="id-8cce4019-aad5-82f1-9156-01bc8f644038"></a>

* 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 <a href="#id-59be4019-aad5-83f1-8426-0105b19a01ea" id="id-59be4019-aad5-83f1-8426-0105b19a01ea"></a>

* 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.
