Skip to content

feat: add missing fix suggestions for Tier 1 storage errors #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
codeZe-us merged 1 commit into from
Jun 28, 2026
+21 −4
Merged

feat: add missing fix suggestions for Tier 1 storage errors #280

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions crates/core/src/taxonomy/data/storage.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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.
"""
Expand Down Expand Up @@ -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"
Expand All @@ -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]]
Expand All @@ -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"