update ttl extension guide to follow auto-restoration logic (#2189)

ElliotFriend · Copilot · web-flow · commit 13fc2d73ea76 · 2026-01-27T09:31:03.000-06:00
* update ttl extension guide to follow auto-restoration logic Fixes #2075 * Update docs/build/guides/archival/test-ttl-extension.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/build/guides/archival/test-ttl-extension.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
diff --git a/docs/build/guides/archival/test-ttl-extension.mdx b/docs/build/guides/archival/test-ttl-extension.mdx
@@ -8,7 +8,7 @@ In order to test contracts that extend the contract data [TTL](../../../learn/fu
 
 ## Example
 
-Follow along the [example](https://github.com/stellar/soroban-examples/blob/main/ttl/src/lib.rs) that tests TTL extensions. The example has extensive comments, this document just highlights the most important parts.
+Follow along the [example](https://github.com/stellar/soroban-examples/blob/v23.0.0/ttl/src/lib.rs) that tests TTL extensions. The example has extensive comments, this document just highlights the most important parts.
 
 We use a very simple contract that only extends an entry for every Soroban storage type:
 
@@ -51,30 +51,38 @@ The focus of the example is the tests, so the following code snippets come from
 It's a good idea to define the custom values of TTL-related network settings, since the defaults are defined by the SDK and aren't immediately obvious for the reader of the tests:
 
 ```rust
-env.ledger().with_mut(|li| {
-    // Current ledger sequence - the TTL is the number of
-    // ledgers from the `sequence_number` (exclusive) until
-    // the last ledger sequence where entry is still considered
-    // alive.
-    li.sequence_number = 100_000;
-    // Minimum TTL for persistent entries - new persistent (and instance)
-    // entries will have this TTL when created.
-    li.min_persistent_entry_ttl = 500;
-    // Minimum TTL for temporary entries - new temporary
-    // entries will have this TTL when created.
-    li.min_temp_entry_ttl = 100;
-    // Maximum TTL of any entry. Note, that entries can have their TTL
-    // extended indefinitely, but each extension can be at most
-    // `max_entry_ttl` ledger from the current `sequence_number`.
-    li.max_entry_ttl = 15000;
-});
+/// Create an environment with specific values of network settings.
+fn create_env() -> Env {
+    let env = Env::default();
+    env.ledger().with_mut(|li| {
+        // Current ledger sequence - the TTL is the number of
+        // ledgers from the `sequence_number` (exclusive) until
+        // the last ledger sequence where entry is still considered
+        // alive.
+        li.sequence_number = 100_000;
+        // Minimum TTL for persistent entries - new persistent (and instance)
+        // entries will have this TTL when created.
+        li.min_persistent_entry_ttl = 500;
+        // Minimum TTL for temporary entries - new temporary
+        // entries will have this TTL when created.
+        li.min_temp_entry_ttl = 100;
+        // Maximum TTL of any entry. Note, that entries can have their TTL
+        // extended indefinitely, but each extension can be at most
+        // `max_entry_ttl` ledger from the current `sequence_number`.
+        li.max_entry_ttl = 15000;
+    });
+    env
+}
 ```
 
 You could also use the current [network settings](../../../networks/resource-limits-fees.mdx#resource-fees) when setting up the tests, but keep in mind that these are subject to change, and the contract should be able to work with any values of these settings.
 
-Now we run a test scenario that verifies the TTL extension logic (see [`test_extend_ttl_behavior`](https://github.com/stellar/soroban-examples/blob/f595fb5df06058ec0b9b829e9e4d0fe0513e0aa8/ttl/src/test.rs#L38) test for the full scenario). First, we setup the data and ensure that the initial TTL values correspond to the network settings we've defined above:
+Now we run a test scenario that verifies the TTL extension logic (see [`test_extend_ttl_behavior`](https://github.com/stellar/soroban-examples/blob/v23.0.0/ttl/src/test.rs#L38) test for the full scenario). First, we setup the data and ensure that the initial TTL values correspond to the network settings we've defined above:
 
 ```rust
+// Create initial entries and make sure their TTLs correspond to
+// `min_persistent_entry_ttl` and `min_temp_entry_ttl` values set in
+// `create_env()`.
 client.setup();
 env.as_contract(&contract_id, || {
     // Note, that TTL doesn't include the current ledger, but when entry
@@ -87,7 +95,7 @@ env.as_contract(&contract_id, || {
 });
 ```
 
-Notice, that we use `env.as_contract` in order to access the contract's storage.
+Notice, that we use `env.as_contract(...)` in order to access the contract's storage.
 
 Then we call the TTL extension operations and verify that they behave as expected, for example:
 
@@ -97,6 +105,8 @@ client.extend_persistent();
 env.as_contract(&contract_id, || {
     assert_eq!(env.storage().persistent().get_ttl(&DataKey::MyKey), 5000);
 });
+
+// ... repeat with `client.extend_instance` and `client.extend_temporary` ...
 ```
 
 In order to test the extension thresholds (i.e. maximum current TTL that requires extension), we need to increase the ledger sequence number:
@@ -118,6 +128,7 @@ env.as_contract(&contract_id, || {
 Then we can extend the entries again and ensure that only entries that are below threshold have been extended (specifically, persistent and temporary entries in this example):
 
 ```rust
+// Extend TTL of all the entries.
 client.extend_persistent();
 client.extend_instance();
 client.extend_temporary();
@@ -131,42 +142,42 @@ env.as_contract(&contract_id, || {
 });
 ```
 
-Soroban SDK also emulates the behavior for the entries that have their TTL expired. Temporary entries behave 'as if' they were deleted (see [`test_temp_entry_removal`](https://github.com/stellar/soroban-examples/blob/f595fb5df06058ec0b9b829e9e4d0fe0513e0aa8/ttl/src/test.rs#L112) test for the full scenario):
+Soroban SDK also emulates the behavior for the entries that have their TTL expired. Temporary entries behave 'as if' they were deleted (see [`test_temp_entry_removal`](https://github.com/stellar/soroban-examples/blob/v23.0.0/ttl/src/test.rs#L112) test for the full scenario):
 
 ```rust
+// Extend the temporary entry TTL to 7000 ledgers.
 client.extend_temporary();
 // Bump the ledger sequence by 7001 ledgers (one ledger past TTL).
 env.ledger().with_mut(|li| {
-    li.sequence_number = 100_000 + 7001;
+    li.sequence_number += 7001;
 });
 // Now the entry is no longer present in the environment.
 env.as_contract(&contract_id, || {
     assert_eq!(env.storage().temporary().has(&DataKey::MyKey), false);
 });
 ```
 
-Persistent entries are more subtle: when a transaction that is executed on-chain contains a persistent entry that has been archived (i.e. it has its TTL expired) in the footprint, then the Soroban environment will not even be instantiated. Since this behavior is not directly reproducible in test environment, instead an irrecoverable 'internal' error will be produced as soon as an archived entry is accessed, and the test will `panic`:
+Persistent entries are more subtle: when a transaction that is executed on-chain contains a persistent entry that has been archived (i.e., it has its TTL expired) in the footprint, then the entry will be automatically restored. Automatic restoration is mostly transparent, the main side effect is the increased fees. (see [`test_persistent_entry_auto_restored`](https://github.com/stellar/soroban-examples/blob/v23.0.0/ttl/src/test.rs#L136) test for the full scenario):
 
 ```rust
-#[test]
-#[should_panic(expected = "[testing-only] Accessed contract instance key that has been archived.")]
-fn test_persistent_entry_archival() {
-    let env = create_env();
-    let contract_id = env.register(TtlContract, ());
-    let client = TtlContractClient::new(&env, &contract_id);
-    client.setup();
-    // Extend the instance TTL to 10000 ledgers.
-    client.extend_instance();
-    // Bump the ledger sequence by 10001 ledgers (one ledger past TTL).
-    env.ledger().with_mut(|li| {
-        li.sequence_number = 100_000 + 10_001;
-    });
-    // Now any call involving the expired contract (such as `extend_instance`
-    // call here) will panic as soon as that contract is accessed.
-    client.extend_instance();
-}
+// Extend the persistent entry TTL to 5000 ledgers.
+client.extend_persistent();
+// Bump the ledger sequence by 5001 ledgers (one ledger past TTL).
+env.ledger().with_mut(|li| {
+    li.sequence_number += 5001;
+});
+// Now any call involving the expired persistent data will cause automatic
+// restoration.
+client.extend_persistent();
+
+// Notice that disk read bytes and write bytes are increased even though the
+// function itself is read-only.
+let resources = env.cost_estimate().resources();
+assert!(resources.disk_read_bytes > 0);
+assert!(resources.write_bytes > 0);
+assert_eq!(resources.write_entries, 1);
 ```
 
 ## Testing TTL extension for other contract instances
 
-Sometimes a contract may want to extend TTL of another contracts and/or their Wasm entries (usually that would happen in factory contracts). This logic may be covered in a similar fashion to the example above using `env.deployer().get_contract_instance_ttl(&contract)` to get TTL of any contract's instance, and `env.deployer().get_contract_code_ttl(&contract)` to get TTL of any contract's Wasm entry. You can find an example of using these function in the SDK [test suite](https://github.com/stellar/rs-soroban-sdk/blob/ff05c3d4cbed97db50142372e9d7a4fa4a8d1d5d/soroban-sdk/src/tests/storage_testutils.rs#L76).
+Sometimes a contract may want to extend TTL of another contracts and/or their Wasm entries (usually that would happen in factory contracts). This logic may be covered in a similar fashion to the example above using `env.deployer().get_contract_instance_ttl(&contract)` to get TTL of any contract's instance, and `env.deployer().get_contract_code_ttl(&contract)` to get TTL of any contract's Wasm entry. You can find an example of using these functions in the SDK [test suite](https://github.com/stellar/rs-soroban-sdk/blob/v23.4.1/soroban-sdk/src/tests/storage_testutils.rs#L76).
