Proposal: Native Contract for Time-Limited (TTL) Temporary Storage with PostPersist Cleanup

[erikzhang]

Background

One of the long-standing concerns discussed in this repository (e.g. #1187) is state growth and long-term storage bloat.
At the same time, many use cases only require short-lived, temporary data, such as:

• off-chain coordination / handshakes
• temporary commitments or proofs
• message passing, caches, or relay data
• intermediate results in multi-step workflows

Currently, all contract storage is effectively permanent unless explicitly deleted by users, which makes these use cases inefficient and increases long-term state pressure.

---

Proposal

Introduce a native contract that provides time-limited (TTL) temporary storage, where each entry is written together with an explicit expiration period.
Expired entries are automatically removed by the system during PostPersist, without requiring any user transaction.

This creates a first-class, protocol-level mechanism for ephemeral storage, instead of overloading permanent contract storage.

---

High-Level Design

1. Native Contract: TemporaryStorage (name illustrative)

The contract manages temporary key-value entries with an expiration height.

Core methods:

• Put(byte[] key, byte[] value, uint ttlBlocks)
• Get(byte[] key) -> byte[] (returns empty / null if expired)
• Delete(byte[] key) (early removal)
• (optional) Renew(byte[] key, uint ttlBlocks)

TTL is defined in block height, not wall-clock time.

---

2. Storage Layout

To enable efficient cleanup in PostPersist, the contract maintains:

• Data storage

  • D | keyId -> value

• Metadata

  • E | expireHeight | keyId -> (empty)

This allows the system to directly locate all entries expiring at a given height.

---

3. PostPersist Cleanup

During PostPersist(currentHeight):

1. Iterate over keys with prefix E | currentHeight

2. For each keyId:

   • Remove data entry
   • Remove expiration index entry

To ensure consensus safety:

• A maximum cleanup limit per block should be enforced.
• If the limit is reached, cleanup can continue in subsequent blocks using a cursor.

This guarantees bounded execution cost per block.

---

Advantages

• Prevents permanent state bloat for short-lived data
• Enables new classes of applications requiring ephemeral storage
• System-enforced expiration (no reliance on user cleanup)
• Aligns with storage-rent and sustainability discussions

---

Optional Extensions

• Storage rent based on bytes × ttlBlocks
• Maximum TTL / size limits enforced by policy
• Cross-contract data sharing

---

Summary

This proposal introduces a clean, explicit, and protocol-level solution for temporary storage, reducing long-term state growth while enabling practical real-world use cases.

[roman-khimov]

Not sure why it's a new issue when we already have one in #1187, but anyway.

1. Native Contract: TemporaryStorage (name illustrative)

If it's a contract then I don't exactly understand

Cross-contract data sharing

extension since API is the same for everyone and TemporaryStorage stores the same thing for everyone. But all of the other text implies that each contract has its own temporary storage, so either we need to make it an interop (much like regular storage) or (preferably to me) change its getter and storage format. Specifically, it should add contract hash into storage:

• D | contract hash | keyId -> value
• E | expiration | contract hash | keyId

and then allow Get(uint160 hash, byte[] key) -> byte[] as well as all the others with automatically derived hash from the caller. This way cross-contract sharing would be available from day one as well.

TTL is defined in block height, not wall-clock time.

I'd make it real time (we do have a timestamp in header anyway). Block time can be changed already, we do have dynamic block time in FS chains already and we can have it in other networks as well. Also, people are really more used to thinking in terms of real time instead of blocks/epochs/whatever.

If the limit is reached, cleanup can continue in subsequent blocks using a cursor.

Cursor isn't required, it'd be kinda like GC running every block, but picking no more than X records per run. Any record with time less than current can be removed.

A nice and pretty easy to implement thing overall, we can leverage it in https://github.com/nspcc-dev/neofs-contract/blob/f228d5018923fa9d6d14bf363670e9159c0e79c7/contracts/balance/contract.go#L203 for example.

[vncoelho]

many use cases only require short-lived, temporary data

That is a crucial point.

Introduce a native contract that provides time-limited (TTL) temporary storage, where each entry is written together with an explicit expiration period.
Expired entries are automatically removed by the system during PostPersist, without requiring any user transaction.

So, theoretically, we could write, use and delete in the same block? Or we will need at least 1 extra block for that?

A maximum cleanup limit per block should be enforced. If the limit is reached, cleanup can continue in subsequent blocks using a cursor.

This is indeed a good protection and not hard to implement. This is useful for peak times.

Storage rent based on bytes × ttlBlocks (optional)

I agree that this is optional because it will all depends on the limit of "ttlBlocks"
Let's say, if the limit is 1 week, 1 month, maybe we will not need to charge based on period.

Maximum TTL / size limits enforced by policy (optional)

This is not optional in my opnion, this is a must.

Cross-contract data sharing (optional)

This is a must in my opnion.
This is the heart of L2 operations efficiently.

[shargon]

Maybe we can avoid a new native contract and just add a parameter during write

[roman-khimov]

Maybe we can avoid a new native contract and just add a parameter during write

That'd require a new interop set and some additional logic to drop old data while native contracts already have onPersist/postPersist and are easier to maintain.

[vncoelho]

I prefer the organization of these features as Native Contracts.

More flexible to adjustments and makes our Neo Core Framework more powerful