fix(soroban): implement storage TTL retention policy and archival reliability - #537
Open
akinboyewaSamson wants to merge 2 commits into
Open
fix(soroban): implement storage TTL retention policy and archival reliability#537akinboyewaSamson wants to merge 2 commits into
akinboyewaSamson wants to merge 2 commits into
Conversation
… and archival reliability - Add tiered retention model: permanent instance storage and quarterly persistent rent window - Update MIN_TTL to 120,960 ledgers (~7 days) and BUMP_TTL to 1,555,200 ledgers (~90 days) - Introduce ContractError::PaymentArchived (code 24) to distinguish archival from PaymentNotFound - Add extend_history_ttl admin-gated entrypoint and MAX_TTL_EXTEND_BATCH (20) - Differentiate archived_skipped from gaps_skipped in PaymentHistoryPage - Fix rebuild_payment_history_index and is_index_complete to prevent counter drift upon entry archival - Prevent backend re-anchoring of archived invoices in hasInvoicePayment - Add invoke-extend-history-ttl.sh and invoke-restore-record.sh CLI ops scripts - Document retention policy and restore procedures in retention-and-restore.md and README.md - Add comprehensive contract and client tests
- rebuild_payment_history_index: guard against clobbering V0-era PaymentHistory entries when PaymentLog is empty (payment_count==0 but existing_count>0) - migrate_schema_v1_to_v2: same guard prevents write_history_index wiping pre-log V0 records during full upgrade chain - rebuild now bypasses get_payment() PaymentArchived sentinel by reading PaymentV1/legacy keys directly via new read_payment_value_v1/legacy helpers - test: deadlock loop test tracks archived_skipped instead of gaps_skipped - test: rebuild test correctly calls rebuild before asserting restored state - storage: expose read_payment_value_v1 and read_payment_value_legacy for migration use
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #465
Summary
Fixes a critical reliability gap in the on-chain invoice payment log. The contract claimed records "survive ledger archival" but
BUMP_TTLwas only 518,400 ledgers (~30 days) and entries were only extended on access — meaning untouched audit records would be silently archived after ~30 days.Changes
Storage & TTL Policy
MIN_TTLto120,960ledgers (~7 days) andBUMP_TTLto1,555,200ledgers (~90 days)Archival Differentiation
ContractError::PaymentArchived(code 24) — distinguishes archived records from records that were never createdget_paymentreturnsPaymentArchivedwhen the persistent slot expired but the write log (PaymentLog) confirms the invoice was settledPaymentHistoryPagegainsarchived_skippedfield alongsidegaps_skippedBulk TTL Extension
extend_history_ttlentrypoint — extends up toMAX_TTL_EXTEND_BATCH(20) records per call, exempt from contract pauseinvoke-extend-history-ttl.shandinvoke-restore-record.shIndex & Counter Drift Fix
rebuild_payment_history_indexandis_index_completenow correctly handle archived slots, preventingPaymentHistoryCountdrift and false alarms inhistory_index_statusBackend Protection
hasInvoicePaymentinsoroban.service.tstreatsPaymentArchivedas confirmed on-chain, preventing double-anchoring of settled invoicesTypeScript Client
error-manifest.ts: code 24PaymentArchivedtypes.ts:PaymentHistoryPage.archivedSkipped,ExtendHistoryTtlResultcodec.ts: updateddecodePaymentHistoryPage, exportedMAX_TTL_EXTEND_BATCHsoroban-invoice-client.ts: newextendHistoryTtlmethodDocumentation
soroban/docs/retention-and-restore.md: retention policy and restore runbooksoroban/README.md: updated error codes, retention policy, CLI scriptsTests
test_archived_payment_distinguished_from_not_foundtest_payment_history_distinguishes_archived_from_corrupted_slotstest_extend_history_ttl_admin_auth_and_batchingtest_extend_history_ttl_succeeds_while_pausedtest_history_index_status_remains_consistent_on_archivaltest_rebuild_history_index_with_archived_records_preserves_count_and_mapping