Update CAP-78

core/cap-0078.md

@@ -140,18 +140,18 @@ index d72886e3..3f2d0d48 100644
 - `liveUntilLedgerSeq` is the last ledger sequence number for which the entry is still considered to be alive, after that it is considered expired.
 - TTL is defined as `TTL = liveUntilLedgerSeq - currentLedgerSeq`, where `currentLedgerSeq` is the sequence number of the ledger where transaction is executed.
 - TTL extension is defined as `TTL_ext = TTL_new - TTL_curr = liveUntilLedgerSeq_new - liveUntilLedgerSeq_curr`, where `_curr/_new` are the values before and after executing the function respectively.
+- `maxEntryTTL` is a State Archival network setting.
 
 With these definitions, the extension algorithm is defined as follows:
 
 - If  `t` is `StorageType::Instance`, the function traps
-- If `min_extension > extend_to`, or `max_extension < min_extension`, the function traps
+- If `max_extension < min_extension`, the function traps
 - If `extend_to <= TTL_curr` the function returns without performing any changes
-- Otherwise, compute the initial TTL extension `TTL_ext_init = extend_to - TTL_curr`
-- If `TTL_ext_init < min_extension`, the function returns without performing any changes
-- Otherwise, compute the final extension `TTL_ext_final = min(TTL_ext_init, max_extension)`
-- If `TTL_ext_final` exceeds `maxEntryTTL` State Archival network setting value:
-     - If storage type `t` is `Persistent`, then `TTL_ext_final` is assigned to be `maxEntryTTL`
-     - If storage type `t` is `Temporary`, then function traps
+- Compute the initial TTL extension `TTL_ext_init = extend_to - TTL_curr`
+- Compute maximum extension allowed by the network `max_network_extension = maxEntryTTL - TTL_curr`
+- If storage type `t` is `Temporary`, and `TTL_ext_init > max_network_extension`, the function traps
+- Clamp the initial extension to not exceed network/argument limits: `TTL_ext_final = min(TTL_ext_init, max_extension, max_network_extension)`
+- If `TTL_ext_final < min_extension`, the function returns without performing any changes
 - `liveUntilLedgerSeq` of the entry is set to be `liveUntilLedgerSeq + TTL_ext_final`
 
 #### `extend_contract_instance_and_code_ttl_v2` host function
@@ -165,7 +165,7 @@ If a built-in contract instance is being extended (currently, only Stellar Asset
 
 ### Minimum and maximum extension arguments
 
-Minimum extension argument is preserved from the old TTL extension functions and is just renamed from `threshold` for consistency. Its role is still to reduce the extension frequency, which reduces the user fees (as every TTL update incurs the write fee) and the ledger write load.
+Minimum extension argument replaces `threshold` argument from the old TTL extension functions. Its role is still to reduce the extension frequency, which reduces the user fees (as every TTL update incurs the write fee) and the ledger write load. However, unlike `threshold`, `min_extension` specifies the minimum number of ledgers to *extend* the entry TTL (i.e. add to its TTL), and not the absolute TTL threshold that must be crossed. This is done for the sake of consistency with maximum extension, and provides arguably more clear way of managing the TTL extension policy. For example, a typical way to use the `threshold` is to prevent extensions that are shorter than e.g. one day. With `threshold` parameters developers needed to compute the `threshold` as `extend_to - 1 day in ledgers`. With `min_extension` parameter `1 day in ledgers` is passed explicitly as `min_extension`, and there is no dependency on the extension target.
 
 Maximum extension argument addresses the extension strategy mentioned in the 'Motivation' section. Developers may set extension strategies like 'extend TTL to 30 days with min extension of 1 day and max extension of 1 day', which would result in any user extending the entry TTL by just 1 day as long as its current TTL is anywhere between 0 and 29 days.
 
@@ -175,7 +175,11 @@ Extension strategies that rely on `max_extension` may result in relatively more
 
 ### `max_extension` for temporary entries
 
-For most of the use cases setting `max_extension` less than `extend_to` for temporary entry would be a mistake, as typically lifetime of temporary entries is very sensitive and must be set precisely (for example, temporary nonce entries must not be archived until the respective signature has expired). Protocol could make setting `max_extension` lower than `extend_to` an error, but there may be a small fraction of use cases where the ability to use lower `max_extension` is actually desired. Additional harness for reducing the error probability can be added at the SDK layer.
+For most of the use cases setting `max_extension` less than `extend_to` for temporary entry would be a mistake, as typically lifetime of temporary entries is very sensitive and must be set precisely (for example, temporary nonce entries must not be archived until the respective signature has expired). Protocol could make setting `max_extension` lower than necessary to reach `extend_to` an error, but there may be a small fraction of use cases where the ability to use lower `max_extension` is actually desired. This is consistent with how `threshold` is treated for the old TTL extension functions: an extension may be skipped for certain `threshold` values.
+
+The justification for failing when the *network* limit is exceeded is that the network limit might change and contract generally can't know about that, which is why it conservatively aborts execution. However, in case of the user-provided arguments there is less motivation for the protocol to make assumptions on behalf of the users.
+
+SDK harness may be provided to reduce possibility of an error when using extension for the temporary entries.
 
 ### `extend_contract_instance_and_code_ttl_v2` using enum to identify extension