CAP 81 draft

[SirTyson]

This CAP outlines a simplified eviction scan logic for Protocol 26. Basically, we just keep a set of live Soroban entries ordered by TTL and key. At the end of each ledger, we check if the front of our set is expired and evict up to maxEntriesToEvict of expired state. Should maintaining this set be too inefficient, we outline future non-protocol breaking optimizations.

Additionally, this separates eviction limits, one for temp entries and one for persistent entries. Temp and persistent entries are fundamentally quite different, so this give us better control over eviction behavior, with little added complexity (we can just maintain two separate sets for each type).

[Copilot]

Pull request overview

This PR introduces CAP-0081, which proposes a simplified eviction mechanism for Soroban entries in Protocol 26. The CAP changes eviction order from bucket-file-position to TTL-order, enabling in-memory eviction scans and improving performance.

Changes:

• Adds CAP-0081 document proposing TTL-ordered eviction with separate limits for temporary and persistent entries
• Introduces new config setting CONFIG_SETTING_MAX_TEMP_ENTRIES_TO_EVICT and renames maxEntriesToArchive to maxPersistentEntriesToArchive
• Updates README.md to include CAP-0081 in the draft proposals list

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
core/cap-0081.md	New CAP document defining TTL-ordered eviction mechanism for Protocol 26
core/README.md	Added CAP-0081 entry to the draft proposals table

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new network config setting maxTempEntriesToEvict is introduced without specifying an initial/default value. According to CAP-0046-09, "Every CAP introducing the new setting must also define its default value to be used during the protocol version upgrade." Consider adding a section in the Semantics that specifies the initial value for maxTempEntriesToEvict and possibly acceptable value ranges, similar to how CAP-0070 defines initial values for CONFIG_SETTING_SCP_TIMING.

Suggested change

	#### Initial value and valid range for `CONFIG_SETTING_MAX_TEMP_ENTRIES_TO_EVICT`
	On upgrade to protocol version 26, the network **MUST** initialize
	`CONFIG_SETTING_MAX_TEMP_ENTRIES_TO_EVICT.maxTempEntriesToEvict` to `1000`.
	The valid range for `maxTempEntriesToEvict` is any non-zero `uint32` value,
	i.e. `1` through `2^32 - 1`. A value of `0` is invalid and **MUST** be
	rejected by implementations.

[dmkozh]

This is indeed missing from the CAP, we should initialize with the same value as persistent setting though.

[Copilot]

The EvictionKey struct includes lastModifiedLedgerSeq but this field is never mentioned in the algorithm description or sorting criteria. The eviction ordering is specified as being by (liveUntilLedgerSeq, LedgerKey), so it's unclear what role lastModifiedLedgerSeq plays. Either this field should be removed from the struct if it's not needed, or the documentation should explain its purpose.

Suggested change

	uint32_t lastModifiedLedgerSeq;
	};
	std::set<EvictionKey> evictionIndex; // Sorted by (liveUntilLedgerSeq, LedgerKey)
	// Ledger sequence when this entry was last modified. This is tracked for
	// diagnostics/metrics and does not participate in the eviction ordering.
	uint32_t lastModifiedLedgerSeq;
	};
	// Ordered by (liveUntilLedgerSeq, LedgerKey), both derived from `entry`.
	// The comparator ignores `lastModifiedLedgerSeq`.
	std::set<EvictionKey> evictionIndex;

[dmkozh]

That's a good find, this seems to be a typo

[anupsdf]

Looks like Copilot spotted this. You meant to have liveUntilLedgerSeq here I think.