fix(creator-keys): gate TTL extension event on tracked remaining TTL

Author: Eeboade

PR_DESCRIPTION.md

@@ -13,11 +13,12 @@ The `extend_creator_ttl` function unconditionally emitted a `ttl_ext` event on e
 ### `creator-keys/src/lib.rs`
 
 - **Added `TTL_EXTENSION_THRESHOLD` constant** (`100` ledgers) — the minimum remaining TTL below which a TTL extension event is emitted.
+- **Added `DataKey::CreatorTtlLiveUntil(creator)`** — a per-creator `u32` recording the absolute live-until ledger the contract last set for the creator profile key. The Soroban SDK does not expose TTL reads to contract code, so this tracked value is what `extend_creator_ttl` uses to decide whether to emit the event.
 - **Modified `extend_creator_ttl`** to:
-  1. Read the creator key's remaining TTL **before** calling `extend_ttl` (using `get_ttl`).
-  2. Evaluate `ttl::should_extend(ttl_before, TTL_EXTENSION_THRESHOLD)`.
-  3. Always call `extend_ttl` on all storage keys — the Soroban SDK call is a no-op when TTL is already healthy, preserving the existing on-chain behavior.
-  4. Only publish the `TTL_EXTENDED_EVENT_NAME` event when the check above returns `true`.
+  1. Derive the remaining TTL from `CreatorTtlLiveUntil` and evaluate `ttl::should_extend(remaining, TTL_EXTENSION_THRESHOLD)`.
+  2. Always call `extend_ttl` on all creator-scoped storage keys — the Soroban SDK call is a no-op when TTL is already healthy, preserving the existing on-chain behavior.
+  3. Only publish the `TTL_EXTENDED_EVENT_NAME` event when the check above returns `true`, then update the tracked live-until.
+- **Write-time TTL alignment**: new entries start with the network-default TTL, which can be much shorter than `CREATOR_TTL_LEDGERS` on fresh networks. `register_creator` now forces the full `CREATOR_TTL_LEDGERS` window on the creator profile, curve preset, and tracked live-until; `set_key_price`, the buy path, and dividend settlement grant the same full window to `KeyPrice`, `KeyBalance(creator, holder)`, and the dividend checkpoint/pending keys.
 
 ### `creator-keys/tests/ttl_extension_on_buy.rs`
 
@@ -41,9 +42,9 @@ The `extend_creator_ttl` function unconditionally emitted a `ttl_ext` event on e
 
 ## Testing
 
-- [ ] `cargo fmt --all -- --check`
-- [ ] `cargo clippy --workspace --all-targets -- -D warnings`
-- [ ] `cargo test --workspace`
+- [x] `cargo fmt --all -- --check`
+- [x] `cargo clippy --workspace --all-targets -- -D warnings`
+- [x] `cargo test --workspace`
 
 **Note:** All existing TTL tests (`test_buy_extends_creator_ttl`, `test_ttl_extension_event_topics_and_payload`, `test_ttl_not_extended_when_already_high`, `test_sell_extends_creator_ttl_after_successful_sell`, `test_failed_sell_does_not_extend_creator_ttl`) remain compatible because:
 - They advance the ledger to near expiry before the first buy, so `should_extend` returns `true` and the event is still emitted.

creator-keys/src/lib.rs

@@ -375,6 +375,12 @@ pub mod constants {
         pub fn referral_fee_bps() -> DataKey {
             DataKey::ReferralFeeBps
         }
+
+        /// Absolute live-until ledger the contract last set for `creator`'s
+        /// profile key, used to decide whether to emit the TTL-extension event.
+        pub fn creator_ttl_live_until(creator: &Address) -> DataKey {
+            DataKey::CreatorTtlLiveUntil(creator.clone())
+        }
     }
 
     fn creator_key(creator: &Address) -> DataKey {
@@ -597,6 +603,11 @@ pub enum DataKey {
     StakedBalance(Address, Address), // (creator, holder) -> staked amount
     MaxKeysPerWallet(Address),
     ReferralFeeBps,
+    /// Absolute live-until ledger the contract last set for the creator key
+    /// via `extend_ttl`. Tracks the TTL extension state so the contract can
+    /// decide whether to emit the TTL-extension event without a TTL read
+    /// (the Soroban SDK does not expose TTL reads to contract code).
+    CreatorTtlLiveUntil(Address),
 }
 
 /// Time-locked key allocation for creator self-vesting.
@@ -1328,6 +1339,10 @@ fn settle_holder_dividends(
     env.storage()
         .persistent()
         .set(&checkpoint_key, &accumulator);
+    // Keep dividend settlement state live for the same horizon as the
+    // creator profile between trades.
+    extend_key_ttl_to_full_window(env, &pending_key);
+    extend_key_ttl_to_full_window(env, &checkpoint_key);
     Ok(())
 }
 
@@ -1350,25 +1365,52 @@ fn compute_claimable_dividend(env: &Env, creator: &Address, holder: &Address) ->
     pending.saturating_add(earned)
 }
 
+/// Extends the TTL of a freshly written storage entry to the full
+/// [`CREATOR_TTL_LEDGERS`] window.
+///
+/// Uses `CREATOR_TTL_LEDGERS` as both the threshold and the extension window.
+/// New entries start with the network-default TTL, which is shorter than
+/// `CREATOR_TTL_LEDGERS` on fresh networks; forcing the full window at write
+/// time keeps the entry's real TTL aligned with the live-until the contract
+/// tracks for the TTL-extension event.
+fn extend_key_ttl_to_full_window(env: &Env, key: &DataKey) {
+    env.storage()
+        .persistent()
+        .extend_ttl(key, CREATOR_TTL_LEDGERS, CREATOR_TTL_LEDGERS);
+}
+
 /// Extends TTL for all creator-related storage keys.
 ///
 /// This function extends the TTL of the creator's primary storage entries
 /// to prevent active creator state from expiring. Called after successful
-/// buy and sell operations. Emits a [`events::TTL_EXTENDED_EVENT_NAME`] event
-/// when the creator key's TTL was actually extended (checked via the SDK's
-/// threshold-vs-expiration logic).
+/// buy, sell, and buyback operations. Emits a [`events::TTL_EXTENDED_EVENT_NAME`]
+/// event only when the creator key's remaining TTL was below
+/// [`TTL_EXTENSION_THRESHOLD`] before this call — a healthy TTL silently
+/// skips the event.
 fn extend_creator_ttl(env: &Env, creator: &Address) {
     let current_ledger = env.ledger().sequence();
     let extend_to = current_ledger + CREATOR_TTL_LEDGERS;
     let threshold = current_ledger;
 
     let creator_key = constants::storage::creator(creator);
-
-    // Check remaining TTL before extending to decide whether to emit the event.
-    // The extend_ttl SDK call still happens unconditionally (it is a no-op when
-    // the entry already has a healthy expiration).
-    let ttl_before = env.storage().persistent().get_ttl(&creator_key);
-    let needs_event = ttl::should_extend(ttl_before, TTL_EXTENSION_THRESHOLD);
+    let live_until_key = constants::storage::creator_ttl_live_until(creator);
+
+    // The Soroban SDK does not expose TTL reads to contract code, so the
+    // contract tracks the live-until ledger it last set for the creator key
+    // in persistent storage ([`DataKey::CreatorTtlLiveUntil`]). The remaining
+    // TTL is derived from that value and used only to decide whether to emit
+    // the TTL-extension event. The tracked value is always <= the entry's
+    // real live-until (the network default can exceed `CREATOR_TTL_LEDGERS`),
+    // so the event may fire slightly early on such networks — never too late.
+    // The `extend_ttl` SDK calls below still run unconditionally — the
+    // runtime no-ops when the entry already has a healthy expiration.
+    let live_until: u32 = env
+        .storage()
+        .persistent()
+        .get(&live_until_key)
+        .unwrap_or(current_ledger);
+    let remaining = live_until.saturating_sub(current_ledger);
+    let needs_event = ttl::should_extend(remaining, TTL_EXTENSION_THRESHOLD);
 
     env.storage()
         .persistent()
@@ -1428,6 +1470,11 @@ fn extend_creator_ttl(env: &Env, creator: &Address) {
         }
     }
 
+    // Record the new live-until ledger so future trades can re-evaluate
+    // whether the TTL-extension event should be emitted.
+    env.storage().persistent().set(&live_until_key, &extend_to);
+    extend_key_ttl_to_full_window(env, &live_until_key);
+
     // Only emit the TTL extension event when the remaining TTL was below the
     // extension threshold before this call. A healthy TTL silently skips the event.
     if needs_event {
@@ -1580,27 +1627,28 @@ impl CreatorKeysContract {
         // Persist profile before event publication so indexers reading contract state
         // after this tx observe the same registration payload that was emitted.
         env.storage().persistent().set(&key, &profile);
-        // Set initial TTL for creator storage
+        // Set initial TTL for creator storage. The full window is forced at
+        // write time so the entry's real TTL matches the live-until the
+        // contract tracks for the TTL-extension event.
         let extend_to = current_ledger + CREATOR_TTL_LEDGERS;
-        env.storage()
-            .persistent()
-            .extend_ttl(&key, current_ledger, extend_to);
-        env.storage()
-            .persistent()
-            .extend_ttl(&preset_key, current_ledger, extend_to);
+        extend_key_ttl_to_full_window(&env, &key);
+        extend_key_ttl_to_full_window(&env, &preset_key);
         let co_creator_key = constants::storage::co_creator(&creator);
         if env.storage().persistent().has(&co_creator_key) {
-            env.storage()
-                .persistent()
-                .extend_ttl(&co_creator_key, current_ledger, extend_to);
+            extend_key_ttl_to_full_window(&env, &co_creator_key);
         }
         let whitelist_key = constants::storage::whitelist(&creator);
         if env.storage().persistent().has(&whitelist_key) {
-            env.storage()
-                .persistent()
-                .extend_ttl(&whitelist_key, current_ledger, extend_to);
+            extend_key_ttl_to_full_window(&env, &whitelist_key);
         }
 
+        // Record the live-until the contract set for the creator key so
+        // `extend_creator_ttl` can later decide whether to emit the
+        // TTL-extension event.
+        let live_until_key = constants::storage::creator_ttl_live_until(&creator);
+        env.storage().persistent().set(&live_until_key, &extend_to);
+        extend_key_ttl_to_full_window(&env, &live_until_key);
+
         env.events().publish(
             events::register_event_topics(&profile.creator),
             events::CreatorRegisteredEvent {
@@ -1719,6 +1767,9 @@ impl CreatorKeysContract {
             .ok_or(ContractError::Overflow)?;
         // Balance key is scoped by (creator, holder) so creator positions cannot collide.
         env.storage().persistent().set(&balance_key, &new_balance);
+        // Grant the balance entry the full TTL window so long-held positions
+        // survive the same horizon as creator state between trades.
+        extend_key_ttl_to_full_window(&env, &balance_key);
 
         if let Some(config) = read_protocol_fee_config(&env) {
             let (creator_fee, protocol_fee) =
@@ -2553,6 +2604,9 @@ impl CreatorKeysContract {
         env.storage()
             .persistent()
             .set(&constants::storage::KEY_PRICE, &price);
+        // Grant the price entry the full TTL window so buy/sell reads stay
+        // live for the same horizon as creator state.
+        extend_key_ttl_to_full_window(&env, &constants::storage::KEY_PRICE);
         Ok(())
     }
 

creator-keys/tests/ttl_extension_on_buy.rs

@@ -29,6 +29,15 @@ fn setup(
     soroban_sdk::Address,
 ) {
     let (client, contract_id) = register_creator_keys(env);
+    // The test env archives the contract instance and code after ~4095
+    // ledgers by default. Bump them to the full extension window so tests
+    // that advance the ledger far into the future (to drain creator TTL)
+    // can still invoke the contract.
+    env.deployer().extend_ttl(
+        contract_id.clone(),
+        CREATOR_TTL_LEDGERS,
+        CREATOR_TTL_LEDGERS,
+    );
     set_key_price_for_tests(env, &client, KEY_PRICE);
     let creator = register_test_creator(env, &client, "alice");
     (client, contract_id, creator)
@@ -155,8 +164,6 @@ fn test_ttl_not_extended_when_already_high() {
 /// succeeds and emits its own event.
 #[test]
 fn test_no_ttl_extension_event_when_ttl_healthy() {
-#[test]
-fn buy_extends_instance_ttl() {
     let env = soroban_sdk::Env::default();
     env.mock_all_auths();
     let (client, contract_id, creator) = setup(&env);
@@ -205,6 +212,16 @@ fn buy_extends_instance_ttl() {
     assert_eq!(
         ttl_before, ttl_after,
         "TTL should remain unchanged after buy when TTL is healthy: before={ttl_before} after={ttl_after}"
+    );
+}
+
+#[test]
+fn buy_extends_instance_ttl() {
+    let env = soroban_sdk::Env::default();
+    env.mock_all_auths();
+    let (client, contract_id, creator) = setup(&env);
+    let holder = Address::generate(&env);
+
     let ttl_before = creator_ttl_remaining(&env, &contract_id, &creator);
 
     let mut ledger = env.ledger().get();

docs/storage-layout.md

@@ -73,6 +73,7 @@ distinguishable from other key types.
 | `ReferralFeeBps` | Global | `u32` | `set_referral_fee_bps` (admin) | `buy_key_with_referrer` (referral split), `get_referral_fee_bps` |
 | `DiscountTiers` | Global | `Vec<DiscountTier>` | `update_discount_tiers` (admin) | `get_discount_tiers` (volume-based fee discount evaluation) |
 | `CreatorVolume(Address)` | Per-creator | `i128` | *(not currently written by any entrypoint)* | `get_creator_volume` |
+| `CreatorTtlLiveUntil(Address)` | Per-creator | `u32` | `register_creator` (initial write), `extend_creator_ttl` (updated after every trade) | `extend_creator_ttl` (TTL-extension event gate) |
 
 > **Note:** `CreatorVolume(Address)` is read by `get_creator_volume` but has no
 > writer in the current implementation, so it always resolves to its `0`
@@ -81,16 +82,10 @@ distinguishable from other key types.
 
 ## TTL extension behavior
 
-The contract does **not** use the `ttl::should_extend(current_ttl, threshold)`
-pure helper (`creator-keys/src/lib.rs`) to decide *whether* to bump TTL on the
-hot buy/sell path — that helper is an isolated, unit-testable decision
-function (see its tests in `lib.rs`) but is not currently wired into
-`extend_creator_ttl`.
-
-Instead, `extend_creator_ttl(env, creator)` runs **unconditionally** after
-every successful `register_creator`, `buy_key`/`buy_key_with_referrer`, and
-`sell_key` call, and extends the TTL of every creator-scoped key that is
-currently present in storage:
+`extend_creator_ttl(env, creator)` runs **unconditionally** after every
+successful `buy_key`/`buy_key_with_referrer`, `sell_key`, and `buyback` call,
+and extends the TTL of every creator-scoped key that is currently present in
+storage:
 
 - `Creator(creator)` — always extended (the key that must exist for the call to have succeeded)
 - `CreatorFeeBalance(creator)` — extended only if present
@@ -114,15 +109,32 @@ effectively always satisfied for any contract that has been live longer than
 successful buy/sell/register call re-bumps creator-scoped TTLs by the full
 `CREATOR_TTL_LEDGERS` window.
 
-A successful `extend_creator_ttl` call emits a TTL-extension event (see
-`events::ttl_extended_topics`) once per invocation, regardless of how many
-individual keys were extended underneath it.
-
-Entries **not** covered by `extend_creator_ttl` (global config keys such as
-`FeeConfig`, `KeyPrice`, `AdminAddress`, `TreasuryAddress`,
+The Soroban SDK does not expose TTL reads to contract code, so the contract
+tracks the live-until ledger it last set for the creator profile key under
+`CreatorTtlLiveUntil(creator)` (initialised in `register_creator`, updated by
+every `extend_creator_ttl` call). The `ttl::should_extend(current_ttl,
+threshold)` pure helper is used on that tracked value to decide whether to
+emit the TTL-extension event:
+
+- The `extend_ttl` SDK calls still run **unconditionally** on every trade
+  (the runtime no-ops when an entry's TTL is already healthy).
+- A `TTL_EXTENDED_EVENT_NAME` event (see `events::ttl_extended_topics`) is
+  emitted **only when the tracked remaining TTL was below
+  `TTL_EXTENSION_THRESHOLD`** before the call — a healthy TTL silently skips
+  the event.
+
+New entries get the network-default TTL, which can be much shorter than
+`CREATOR_TTL_LEDGERS` on fresh networks. To keep an entry's real TTL aligned
+with the value the contract tracks, the contract forces the full
+`CREATOR_TTL_LEDGERS` window at write time (via `extend_key_ttl_to_full_window`)
+for: the creator profile and curve preset at `register_creator`, `KeyPrice` at
+`set_key_price`, holder `KeyBalance(creator, holder)` on buy, the dividend
+checkpoint/pending pair on settlement, and `CreatorTtlLiveUntil` itself.
+
+Entries **not** covered by `extend_creator_ttl` or a write-time extension
+(global config keys such as `FeeConfig`, `AdminAddress`, `TreasuryAddress`,
 `ProtocolFeeRecipient`, `CurveSlope`, `ReferralFeeBps`, `DiscountTiers`, and
-per-holder keys like `KeyBalance(creator, holder)` and the dividend
-checkpoint/pending pair) do not receive automatic TTL bumps from trade
+any other per-holder keys) do not receive automatic TTL bumps from trade
 activity and should be covered by an operational maintenance job if long-term
 persistence is required — see
 [creator-state-storage-ttl.md](./creator-state-storage-ttl.md) for the