Update migration guide with the information on archived persistent entry behavior change (#1560)

### What

Update migration guide with the information on archived persistent entry
behavior change.

Fixes #1545

Also bump the SDK dependencies.

### Why

Improving documentation on breaking changes.

### Known limitations

N/A

Author: dmkozh

Cargo.lock

@@ -28,25 +28,25 @@ soroban-token-spec = { version = "23.0.0-rc.3", path = "soroban-token-spec" }
 stellar-asset-spec = { version = "23.0.0-rc.3", path = "stellar-asset-spec" }
 
 [workspace.dependencies.soroban-env-common]
-version = "=23.0.0-rc.2"
+version = "=23.0.1"
 #git = "https://github.com/stellar/rs-soroban-env"
 #rev = "bd0c80a1fe171e75f8d745f17975a73927d44ecd"
 
 [workspace.dependencies.soroban-env-guest]
-version = "=23.0.0-rc.2"
+version = "=23.0.1"
 #git = "https://github.com/stellar/rs-soroban-env"
 #rev = "bd0c80a1fe171e75f8d745f17975a73927d44ecd"
 
 [workspace.dependencies.soroban-env-host]
-version = "=23.0.0-rc.2"
+version = "=23.0.1"
 #git = "https://github.com/stellar/rs-soroban-env"
 #rev = "bd0c80a1fe171e75f8d745f17975a73927d44ecd"
 
 [workspace.dependencies.stellar-strkey]
 version = "=0.0.13"
 
 [workspace.dependencies.stellar-xdr]
-version = "=23.0.0-rc.2"
+version = "=23.0.0"
 default-features = false
 features = ["curr"]
 #git = "https://github.com/stellar/rs-stellar-xdr"

Cargo.toml

@@ -6,6 +6,10 @@
 //!    This change concerns `soroban-token-sdk` and is documented in detail in
 //!    `soroban-token-sdk` crate migration guide.
 //!
+//! 3. [Accessing archived persistent entries in tests no longer results in a panic][v23_archived_testing],
+//!    automatic restoration is emulated instead. Note, that instance storage is a
+//!    persistent entry as well.
+//!
 //! # Migrating from v21 to v22
 //!
 //! 1. [`Env::register`] and [`Env::register_at`] replace [`Env::register_contract`] and [`Env::register_contract_wasm`].
@@ -243,4 +247,5 @@
 //! [`Hash<32>`]: crate::crypto::Hash
 //! [`Hash<32>::to_bytes`]: crate::crypto::Hash::to_bytes
 
+pub mod v23_archived_testing;
 pub mod v23_contractevent;

soroban-sdk/src/_migrating.rs

@@ -0,0 +1,176 @@
+//! Accessing archived persistent entries in tests no longer results in an error.
+//!
+//! Prior to protocol 23 the SDK used to emulate the failure when an archived
+//! ledger entry was accessed in tests. This behavior has never represented the
+//! actual behavior of the network, just one possible scenario when an archived
+//! entry is present in the transaction footprint.
+//!
+//! In protocol 23 automatic entry restoration has been introduced, which makes
+//! it possible for a transaction to restore an archived entry before accessing
+//! it. As this behavior will become the most common case on the network, the
+//! SDK has been changed to emulate automatic restoration in tests as well.
+//!
+//! Note, that instance storage is a persistent entry as well, so it is subject
+//! to the same change.
+//!
+//! ## Example
+//!
+//! Consider the following simple contract that extends entry TTL
+//! along with the test that relies on the error on archived entry access in
+//! SDK 22:
+//!
+//! ```
+//! #![no_std]
+//! use soroban_sdk::{contract, contractimpl, contracttype, Env};
+//!
+//! #[contract]
+//! struct Contract;
+//!
+//! #[contracttype]
+//! enum DataKey {
+//!     Key,
+//! }
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn create_and_extend_entry(env: Env) {
+//!         env.storage().persistent().set(&DataKey::Key, &123_u32);
+//!         // Extend the entry to live for at least 1_000_000 ledgers.
+//!         env.storage()
+//!             .persistent()
+//!             .extend_ttl(&DataKey::Key, 1_000_000, 1_000_000);
+//!     }
+//!
+//!     pub fn read_entry(env: Env) -> u32 {
+//!         env.storage().persistent().get(&DataKey::Key).unwrap()
+//!     }
+//! }
+//!
+//! mod test {
+//!     extern crate std;
+//!     use soroban_sdk::testutils::{storage::Persistent, Ledger};
+//!
+//!     use super::*;
+//!
+//!     #[test]
+//!     fn test_entry_archived() {
+//!         let env = Env::default();
+//!         let contract = env.register(Contract, ());
+//!         let client = ContractClient::new(&env, &contract);
+//!         client.create_and_extend_entry();
+//!         let current_ledger = env.ledger().sequence();
+//!         assert_eq!(client.read_entry(), 123);
+//!
+//!         // Bump ledger sequence past entry TTL.
+//!         env.ledger()
+//!             .set_sequence_number(current_ledger + 1_000_000 + 1);
+//!         let res = client.try_read_entry();
+//!         // 👀 In SDK 22 `res` would be an error because the entry is archived.
+//!         // 👀 In SDK 23 `res` is Ok(123) because the entry is automatically restored.
+//!         assert!(res.is_err());
+//!     }
+//! }
+//!
+//! # fn main() { }
+//! ```
+//!
+//! The best way to address this change is to update the tests to explicitly
+//! verify the expected entry TTL after the extension. This way there is no need
+//! to rely on the storage behavior, and also the test becomes more robust as
+//! it enforces the exact expected TTL value, so there is no risk of bumping
+//! the ledger sequence further than the expected TTL and still having the test
+//! pass.
+//!
+//! The example test above can be re-written as follows:
+//!
+//! ```
+//! #![no_std]
+//! use soroban_sdk::{contract, contractimpl, contracttype, Env};
+//!
+//! #[contract]
+//! struct Contract;
+//!
+//! #[contracttype]
+//! enum DataKey {
+//!     Key,
+//! }
+//!
+//! #[contractimpl]
+//! impl Contract {
+//!     pub fn create_and_extend_entry(env: Env) {
+//!         env.storage().persistent().set(&DataKey::Key, &123_u32);
+//!         // Extend the entry to live for at least 1_000_000 ledgers.
+//!         env.storage()
+//!             .persistent()
+//!             .extend_ttl(&DataKey::Key, 1_000_000, 1_000_000);
+//!     }
+//!
+//!     pub fn read_entry(env: Env) -> u32 {
+//!         env.storage().persistent().get(&DataKey::Key).unwrap()
+//!     }
+//! }
+//!
+//! #[cfg(test)]
+//! mod test {
+//!     extern crate std;
+//!     use soroban_sdk::testutils::{storage::Persistent, Ledger};
+//!
+//!     use super::*;
+//!
+//!     #[test]
+//!     fn test_entry_ttl_extended() {
+//!         let env = Env::default();
+//!         let contract = env.register(Contract, ());
+//!         let client = ContractClient::new(&env, &contract);
+//!         client.create_and_extend_entry();
+//!         assert_eq!(client.read_entry(), 123);
+//!
+//!         // 👀 Verify that the entry TTL was extended correctly by 1000000 ledgers.
+//!         env.as_contract(&contract, || {
+//!             assert_eq!(env.storage().persistent().get_ttl(&DataKey::Key), 1_000_000);
+//!         });
+//!     }
+//!     
+//!     // 👀 This test is not really necessary, but it demonstrates the
+//!     // auto-restoration behavior in tests.
+//!     #[test]
+//!     fn test_auto_restore() {
+//!         let env = Env::default();
+//!         let contract = env.register(Contract, ());
+//!         let client = ContractClient::new(&env, &contract);
+//!         client.create_and_extend_entry();
+//!         let current_ledger = env.ledger().sequence();
+//!
+//!         // Bump ledger sequence past entry TTL.
+//!         env.ledger()
+//!             .set_sequence_number(current_ledger + 1_000_000 + 1);
+//!         // 👀 Entry can still be accessed because automatic restoration is emulated
+//!         // in tests.
+//!         assert_eq!(client.read_entry(), 123);
+//!
+//!         // 👀 Automatic restoration is also accounted for in cost_estimate():
+//!         let resources = env.cost_estimate().resources();
+//!         // Even though `read_entry` call is normally read-only, auto-restoration
+//!         // will cause 2 entry writes here: 1 for the contract instance, another
+//!         // one for the restored entry.
+//!         assert_eq!(resources.write_entries, 2);
+//!         // 2 rent bumps will happen as well for the respective entries.
+//!         assert_eq!(resources.persistent_entry_rent_bumps, 2);
+//!
+//!         // 👀 Entry TTL after auto-restoration can be observed via get_ttl().
+//!         env.as_contract(&contract, || {
+//!             // Auto-restored entries have their TTL extended by the minimum
+//!             // possible TTL worth of ledgers (`min_persistent_entry_ttl`),
+//!             // including the ledger in which they were restored (that's why
+//!             // we subtract 1 here).
+//!             assert_eq!(
+//!                 env.storage().persistent().get_ttl(&DataKey::Key),
+//!                 env.ledger().get().min_persistent_entry_ttl - 1
+//!             );
+//!         });
+//!     }
+//! }
+//!
+//! # fn main() { }
+//! ```
+//!