Stellar contract data pays rent to stay live and gets archived when it stops

Stellar's Soroban smart contract platform takes a notably different approach to on-chain storage compared with most blockchain environments. Rather than allowing ledger state to grow indefinitely, every contract entry is required to pay rent to remain live, with the clock measured in ledgers rather than wall time.

Three tiers, three outcomes

Every piece of contract data must pay rent to remain alive on the ledger for a specific time-to-live (TTL), which refers to the number of ledgers between the current ledger and the final ledger where the data can still be accessed. Soroban organises this across three distinct storage tiers: temporary, persistent, and instance.

The tiers behave very differently when their TTL expires. All contract data is automatically archived when TTL reaches zero, except for temporary entries, which are deleted permanently from the ledger. Persistent and instance data is moved to an archive and can be brought back, but temporary data is gone for good. Storing long-term critical data such as user balances in temporary storage causes irreversible state loss when the entry's TTL reaches zero.

The rationale behind the model is straightforward. State bloat is the continuous, unbounded growth of on-chain state. Left unchecked, as contract data accumulates on the ledger, it degrades state-sync and transaction-execution performance and pushes the network towards centralisation as nodes require more RAM and faster storage to keep up.

The rent rate is based on how long the entry should live on the ledger and how large the entry is. Like transaction fees, rent goes into the fee pool, which is currently locked and can only be unlocked by a validator-approved change to the protocol.

Protocol 23 makes restoration automatic

Protocol 23 introduced automatic restoration of archived Soroban entries via the InvokeHostFunctionOp. Prior to Protocol 23, developers had to explicitly call a restore operation to bring archived state back into use. Now, whenever InvokeHostFunctionOp is executed, the network automatically checks the footprint and restores any archived entries it needs before contract execution.

In most cases, running simulation or preflight will detect expired entries and include them in the footprint. Archived entries being restored are still treated like disk-based data, with rent, write, and read fees still applying.

The manual RestoreFootprintOp can still be used in edge cases, such as when auto-restoration would make a transaction too large to fit within network limits, or when contract developers want to ensure they pay restoration fees rather than their users.

The design reflects @StellarOrg's broader push to keep Soroban scalable without sacrificing developer flexibility, giving builders precise control over how long data lives on-chain and what happens when it does not.

Sources:
Stellar: Announcing Protocol 23
Stellar Docs: State Archival
CertiK: Soroban Contract State Management