Test TTL extension logic in smart contracts

In order to test contracts that extend the contract data TTL via extend_ttl storage operations, you can use the TTL getter operation (get_ttl) in combination with manipulating the ledger sequence number. Note, that get_ttl function is only available for tests and only in Soroban SDK v21+.

Example

Follow along the example 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:

#[contractimpl]
impl TtlContract {
    /// Creates a contract entry in every kind of storage.
    pub fn setup(env: Env) {
        env.storage().persistent().set(&DataKey::MyKey, &0);
        env.storage().instance().set(&DataKey::MyKey, &1);
        env.storage().temporary().set(&DataKey::MyKey, &2);
    }

    /// Extend the persistent entry TTL to 5000 ledgers, when its
    /// TTL is smaller than 1000 ledgers.
    pub fn extend_persistent(env: Env) {
        env.storage()
            .persistent()
            .extend_ttl(&DataKey::MyKey, 1000, 5000);
    }

    /// Extend the instance entry TTL to become at least 10000 ledgers,
    /// when its TTL is smaller than 2000 ledgers.
    pub fn extend_instance(env: Env) {
        env.storage().instance().extend_ttl(2000, 10000);
    }

    /// Extend the temporary entry TTL to become at least 7000 ledgers,
    /// when its TTL is smaller than 3000 ledgers.
    pub fn extend_temporary(env: Env) {
        env.storage()
            .temporary()
            .extend_ttl(&DataKey::MyKey, 3000, 7000);
    }
}

The focus of the example is the tests, so the following code snippets come from test.rs. 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:

/// 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 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 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:

// 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
    // is created the current ledger is counted towards the number of
    // ledgers specified by `min_persistent/temp_entry_ttl`, thus
    // the TTL is 1 ledger less than the respective setting.
    assert_eq!(env.storage().persistent().get_ttl(&DataKey::MyKey), 499);
    assert_eq!(env.storage().instance().get_ttl(), 499);
    assert_eq!(env.storage().temporary().get_ttl(&DataKey::MyKey), 99);
});

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:

// Extend persistent entry TTL to 5000 ledgers - now it is 5000.
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:

// Now bump the ledger sequence by 5000 in order to sanity-check
// the threshold settings of `extend_ttl` operations.
env.ledger().with_mut(|li| {
    li.sequence_number = 100_000 + 5_000;
});
// Now the TTL of every entry has been reduced by 5000 ledgers.
env.as_contract(&contract_id, || {
    assert_eq!(env.storage().persistent().get_ttl(&DataKey::MyKey), 0);
    assert_eq!(env.storage().instance().get_ttl(), 5000);
    assert_eq!(env.storage().temporary().get_ttl(&DataKey::MyKey), 2000);
});

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):

// Extend TTL of all the entries.
client.extend_persistent();
client.extend_instance();
client.extend_temporary();
env.as_contract(&contract_id, || {
    assert_eq!(env.storage().persistent().get_ttl(&DataKey::MyKey), 5000);
    // Instance TTL hasn't been increased because the remaining TTL
    // (5000 ledgers) is larger than the threshold used by
    // `extend_instance` (2000 ledgers)
    assert_eq!(env.storage().instance().get_ttl(), 5000);
    assert_eq!(env.storage().temporary().get_ttl(&DataKey::MyKey), 7000);
});

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 test for the full scenario):

// 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 += 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 entry will be automatically restored. Automatic restoration is mostly transparent, the main side effect is the increased fees. (see test_persistent_entry_auto_restored test for the full scenario):

// 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 functions in the SDK test suite.

​Example

​Testing TTL extension for other contract instances

Example

Testing TTL extension for other contract instances