token_bridge: per-holder WBAL entries never TTL-extended — a dormant wrapped-token balance risks archival and traps on read

[abayomicornelius]

Overview

token_bridge's per-holder wrapped balances are stored exclusively in persistent storage with no TTL-extension call anywhere in the contract:

// token_bridge/src/lib.rs
fn get_wrapped_balance_internal(env: &Env, holder: &Address) -> i128 {
    let bal_key = (KEY_WBAL, holder.clone());
    env.storage().persistent().get(&bal_key).unwrap_or(0i128)
}

fn credit_wrapped(env: &Env, holder: &Address, amount: i128) -> Result<i128, TokenBridgeError> {
    let current = Self::get_wrapped_balance_internal(env, holder);
    let new_bal = current.checked_add(amount).ok_or(TokenBridgeError::ArithmeticOverflow)?;
    let bal_key = (KEY_WBAL, holder.clone());
    env.storage().persistent().set(&bal_key, &new_bal);
    Ok(new_bal)
}

Neither wrap, unwrap, nor get_wrapped_balance ever calls env.storage().persistent().extend_ttl(...). Soroban persistent storage entries have a finite, rent-bounded TTL and are archived once that TTL expires without being bumped — a subsequent read of an archived key does not return the old value, it fails the transaction (or, for get_wrapped_balance's use of .get(...).unwrap_or(0i128), the specific failure mode here is worse: env.storage().persistent().get() on a genuinely archived key traps the whole transaction rather than returning None, so unwrap_or(0i128) never actually gets a chance to run — a long-dormant wrapped-token holder's very first attempted read after archival aborts, not silently zeroes).

This is exactly the same class of problem already reported for the other three contracts — escrow (#34), fee_collector (#39), and stellar_send's Subscription records (#43) — but none of those cover token_bridge, and this contract is the one where the consequence is arguably worst: a wrap() deposit with no further activity (the single most likely usage pattern — a user wraps once and holds) is precisely the "long period of inactivity" pattern that Soroban's TTL/archival design exists to reclaim, and every one of those balances is real, user-owned, previously-transferred-in principal, not just accounting metadata.

Requirements

• Every write to a (KEY_WBAL, holder) entry (in wrap's credit_wrapped and unwrap's debit path) must also extend that entry's TTL to a configured minimum (e.g. via env.storage().persistent().extend_ttl(&bal_key, threshold, extend_to)), following the same pattern that should be applied consistently once escrow: persistent Escrow records are never TTL-extended, risking archival before release/refund #34/fee_collector: persistent per-token totals are never TTL-extended, and get_total_collected silently masks archival as zero #39/stellar_send: persistent Subscription records are never TTL-extended, risking archival for exactly the long-interval payments the feature exists to serve #43 are fixed.
• get_wrapped_balance (a read-only query, potentially called far more often than wrap/unwrap by any UI or integrator) should itself opportunistically extend the TTL on read for entries it successfully retrieves, so simply checking a balance keeps it alive even with zero wrap/unwrap activity — consistent with how a "wallet balance" is conventionally expected to behave (always queryable, never silently expiring from under a passive holder).
• Add a config constant for the extension threshold/amount (ledger counts), matching whatever convention is adopted for the other three contracts' equivalent fix, so all four contracts share one TTL policy rather than four independently-chosen ones.

Acceptance Criteria

• wrap and unwrap extend the TTL of the holder's (KEY_WBAL, holder) entry on every write.
• get_wrapped_balance extends the TTL of the entry on every successful read.
• A test simulates a wrapped balance whose entry's TTL is allowed to expire (via the test harness's ledger-sequence/TTL manipulation, matching whatever pattern is used for the fix to escrow: persistent Escrow records are never TTL-extended, risking archival before release/refund #34/fee_collector: persistent per-token totals are never TTL-extended, and get_total_collected silently masks archival as zero #39/stellar_send: persistent Subscription records are never TTL-extended, risking archival for exactly the long-interval payments the feature exists to serve #43) and confirms a subsequent wrap/unwrap/get_wrapped_balance no longer traps.
• No change to wrap/unwrap's external behavior (amounts, events, error codes) for the non-archival path.

Additional Notes

More precise references

• token_bridge/src/lib.rs — get_wrapped_balance_internal (helper backing both get_wrapped_balance and the balance check inside unwrap) and credit_wrapped (backing wrap): confirmed both interact with (KEY_WBAL, holder) via plain .get()/.set() with no extend_ttl call anywhere in the file — grepped the entire file for extend_ttl/bump with zero matches.
• Compare to the acknowledged-missing pattern in escrow: persistent Escrow records are never TTL-extended, risking archival before release/refund #34 (escrow), fee_collector: persistent per-token totals are never TTL-extended, and get_total_collected silently masks archival as zero #39 (fee_collector), stellar_send: persistent Subscription records are never TTL-extended, risking archival for exactly the long-interval payments the feature exists to serve #43 (stellar_send subscriptions) — this issue is the fourth and last instance of the same gap, specific to token_bridge's KEY_WBAL entries.

Additional edge cases

• unwrap's balance check (if current_bal < amount) calls get_wrapped_balance_internal first — if that read traps due to archival rather than returning a low/zero balance, a holder attempting to unwrap after their entry has archived gets an opaque host trap instead of any of TokenBridgeError's typed variants, which is a poor failure mode on top of the underlying data-loss risk; the TTL fix directly prevents this from being reachable in the first place, but it's worth the implementer confirming (via the reproduction test) that this is in fact the current failure shape, not an already-graceful one.
• wrap's credit_wrapped reads-then-writes the same key; if the entry is already archived at the moment wrap is called (as opposed to unwrap, which is a debit on an existing holder), the very first wrap call for a returning holder after a long gap would itself trap on the read, meaning even topping up an existing wrapped position can't recover from archival without this fix — the TTL extension must happen on every write, not just be checked/lazily-repaired on read.

Implementation sketch

1. Define const WBAL_TTL_THRESHOLD: u32 / const WBAL_TTL_EXTEND_TO: u32 (or reuse whatever names the fix to escrow: persistent Escrow records are never TTL-extended, risking archival before release/refund #34/fee_collector: persistent per-token totals are never TTL-extended, and get_total_collected silently masks archival as zero #39/stellar_send: persistent Subscription records are never TTL-extended, risking archival for exactly the long-interval payments the feature exists to serve #43 introduces).
2. In credit_wrapped, after env.storage().persistent().set(&bal_key, &new_bal), call env.storage().persistent().extend_ttl(&bal_key, WBAL_TTL_THRESHOLD, WBAL_TTL_EXTEND_TO).
3. Same in unwrap's debit path, after its set.
4. In get_wrapped_balance_internal, after a successful .get() that returns Some(_), extend the TTL before returning — only for the existing-entry case (a None/never-wrapped holder has no entry to extend).

Test/reproduction plan

• Using the Soroban test harness's ledger-manipulation helpers (env.ledger().set(...) with a sequence number advanced past the entry's TTL, matching whatever pattern the test suite already uses elsewhere, e.g. farming-pool-style TTL tests in the sibling SmartDropLabs org's contracts repo for a directly comparable example), create a wrapped balance via wrap, advance the ledger past the default persistent-entry TTL without touching the entry, then call get_wrapped_balance and confirm it does not trap and correctly still reflects the balance (proving the fix's read-path extension worked on the previous write, or exercising the intentionally-expired case pre-fix to document the failure mode as a regression test).
• A second case: same setup, but call wrap again (topping up) instead of reading, confirming the write path does not trap either.

Cross-references

• escrow: persistent Escrow records are never TTL-extended, risking archival before release/refund #34, fee_collector: persistent per-token totals are never TTL-extended, and get_total_collected silently masks archival as zero #39, stellar_send: persistent Subscription records are never TTL-extended, risking archival for exactly the long-interval payments the feature exists to serve #43 report the identical gap for escrow, fee_collector, and stellar_send's Subscription records respectively — this issue is the missing fourth instance, specific to token_bridge. Worth sequencing all four together (or at least adopting one shared TTL-policy constant/module) rather than landing four independent, possibly-inconsistent fixes.

[stephenowoh43-collab]

Good day maintainer, i would like to work on this issue. i will add a shared TTL policy for KEY_WBAL entries, extend TTLs on wrap/unwrap writes and balance reads, and add ledger-advance tests to verify dormant balances remain accessible without changing existing behavior.

[grantfox-oss]

🦊 GrantFox — @stephenowoh43-collab has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #55)
2. Your PR will be reviewed by the StellarSend maintainers

Good luck! Track your progress on GrantFox.