diff --git a/crates/core/src/taxonomy/data/storage.toml b/crates/core/src/taxonomy/data/storage.toml index 73227acc..d4daf54b 100644 --- a/crates/core/src/taxonomy/data/storage.toml +++ b/crates/core/src/taxonomy/data/storage.toml @@ -1,5 +1,5 @@ -# Storage Error Taxonomy -# Category: Storage — errors related to ledger entry access and contract data operations. +# Storage Error Taxonomy +# Category: Storage — errors related to ledger entry access and contract data operations. [category] name = "Storage" @@ -15,7 +15,7 @@ severity = "Error" since_protocol = 20 summary = "The contract attempted to access a ledger entry not included in the transaction's footprint." detailed_explanation = """ -Every Soroban transaction must declare its read/write footprint — the set of ledger entries it \ +Every Soroban transaction must declare its read/write footprint — the set of ledger entries it \ will access. If the contract tries to read or write an entry not in the declared footprint, \ the host rejects the access. This is a fundamental part of Soroban's parallel execution model. """ @@ -130,6 +130,16 @@ likelihood = "medium" description = "The transaction hit a storage edge case that needs diagnostic events to identify" likelihood = "medium" +[[errors.suggested_fixes]] +description = "Check diagnostic events for the specific ledger key or operation that triggered the internal failure" +difficulty = "medium" +requires_upgrade = false + +[[errors.suggested_fixes]] +description = "If the error is reproducible, report it with the transaction envelope and diagnostic trace" +difficulty = "hard" +requires_upgrade = false + [[errors.suggested_fixes]] description = "Inspect diagnostic events for the ledger key or storage operation that failed" difficulty = "medium" @@ -150,7 +160,7 @@ detailed_explanation = """ Soroban ledger entries have a time-to-live measured in ledgers. This warning indicates that a \ contract read or written an entry that is close to expiring. The operation succeeded, but the \ entry must be extended with extendTTL before it archives or future transactions will fail with \ -EntryNotFound. This is not a blocking error — it is a signal to act before the entry is lost. +EntryNotFound. This is not a blocking error — it is a signal to act before the entry is lost. """ [[errors.common_causes]] @@ -162,5 +172,12 @@ description = "Call extendTTL on the entry to push the expiration ledger further difficulty = "easy" requires_upgrade = false +[[errors.suggested_fixes]] +description = "Set up automated TTL extension for long-lived contract data" +difficulty = "medium" +requires_upgrade = true + related_errors = ["host.storage.entry_not_found"] source_file = "soroban-env-host/src/storage.rs" + +