🟡 No permissionless TTL keep-alive path or archived-entry recovery procedure

[Ejirowebfi]

Severity: Elevated (downgraded from Critical — see below) · Area: Contract (contracts/token-factory/src/lib.rs), Docs

Description

What has been fixed since this was filed. The critical half of this issue is gone. The argument-ignoring extend_token_ttl(env, _token_address, _index) no longer exists anywhere in the tree. Token bookkeeping moved from a single shared instance entry to persistent storage, and every persistent read and write goes through helpers that extend that specific key's TTL on access — set_persistent (lib.rs:454-455), migrate_addr_keyed (lib.rs:474-475), and the count-key path (lib.rs:496-500). One archival event can therefore no longer take down all token bookkeeping at once; each entry's rent is tracked independently. docs/contract-abi.md:36 documents this, and :38-41 documents the two mechanisms that migrate pre-v3 data out of legacy instance storage.

What remains. The archival risk is now bounded rather than catastrophic, but three pieces of the original scope were never delivered, and they are the pieces that matter for a token nobody has touched in a month:

1. There is no permissionless keep-alive path. A token's entries are extended only when someone calls a factory entrypoint that touches that token. A token created once and never minted, never re-metadata'd, and never transferred gets no extension at all after creation. Its owner has no contract function to call to keep it alive — every extension helper is internal, and no extend_ttls(keys)-style maintenance entrypoint exists (grep for extend_token_ttl, extend_ttls, RestoreFootprint across contracts/, scripts/, docs/, and frontend/src returns nothing).
2. There is no restore procedure. Nothing in docs/ — not incident-response.md, not mainnet-deployment-checklist.md — describes what an operator does once an entry has been archived. docs/contract-abi.md is the only file mentioning TTL at all, and it describes prevention, not recovery.
3. There is no TTL monitoring and no ledger-advancing test. No check surfaces how close any entry is to expiry, and test.rs has no test that advances the ledger past a TTL boundary to prove either that touched entries survive or that archived entries can be recovered. The per-key extension is asserted by construction, not by test.

Severity drops from Critical to Elevated because the blast radius is now one idle token rather than the whole factory, and the state/admin/fee configuration in instance storage is extended by any factory activity at all.

Tasks

• Add a permissionless maintenance entrypoint (extend_token_ttl(token_address) — reusing the name honestly this time, or extend_ttls(keys)) that any address can call to extend a specific token's TokenInfo / TokenIndex / Metadata / owner / supply keys, so an idle token's owner is not dependent on transacting to stay alive.
• Alternatively or additionally, document the ledger-level ExtendFootprintTTL operation as the supported keep-alive route, with a worked example against a real token.
• Write the archived-entry recovery runbook in docs/ — detecting archival, constructing the RestoreFootprint operation, expected rent cost, and who is expected to pay it.
• Add TTL headroom to api/health/indexer.ts or a sibling health endpoint so proximity to expiry is observable rather than discovered by a user report.
• Add tests that advance the ledger past TTL boundaries and assert (a) a touched entry survives, (b) an untouched entry archives as expected, (c) restoration works.

Acceptance Criteria

• A token that receives no factory calls can still be kept alive by an unprivileged caller through a documented, tested mechanism.
• An archived-entry recovery procedure exists in docs/, names its rent cost, and is exercised by a test.
• Ledger-advancing tests prove the per-key extension behavior that docs/contract-abi.md:36 currently asserts by construction.
• No function signature advertises TTL behavior it does not implement (still true today — keep it true).

---

Re-verified and narrowed on 2026-08-19 during the 30-issue codebase audit tracked in ISSUES.md.

[mayborn005]

Hello @maintainer, I’ve gone through the requirements and I’m confident I can implement a proper solution that matches the acceptance criteria. Kindly assign this issue to me. And I will deliver at the shortest possible time.

[Markodiba6399]

Hi, I'd like to work on this issue.

This is a real "the app went dark and nobody knew why" risk. A factory that only extends TTL incidentally, whenever some unrelated state-writing call happens to occur, means archival is basically a matter of time on any contract with irregular usage, and there's currently no recovery path documented anywhere. The misleading extend_token_ttl signature makes it worse, since it looks like the safeguard already exists.

My proposed approach:

Coordinate with (or build on top of) the persistent-storage migration from Issue 3 first, since real per-key TTL extension only makes sense once storage is structured around individual keys rather than one shared instance entry.
Implement per-key TTL extension so that touching a token's TokenInfo, TokenIndex, Metadata, owner, and supply entries extends each of their TTLs on access, rather than relying on the single instance-level TTL as a proxy for all of them.
Delete or rewrite extend_token_ttl so its behavior actually matches its name and arguments, no longer silently ignoring _token_address and _index.
Add a public, permissionless extend_ttls(keys)-style maintenance entrypoint so any caller (a cron job, a concerned user, anyone) can keep entries alive without needing special permissions, and document the alternative of using RestoreFootprint/ExtendFootprintTTL directly if that's preferable for some callers.
Write the operational runbook in docs/: how to monitor entry TTLs approaching expiry, how to restore an archived entry, and what rent budget to expect, plus a cron/CI job doc for scheduled keep-alive on mainnet so this doesn't silently regress after the fix ships.
Write ledger-advancing tests that push past the TTL boundary and verify both that touched entries survive and that archived entries can actually be restored, since the acceptance criteria specifically require this to be proven, not just asserted.

I have experience building Stellar/Soroban contracts including token/wallet-style state that needs to stay durable over time, so I'm comfortable with the storage TTL model and the ledger-advancing test patterns Soroban requires here. Since this issue explicitly depends on Issue 3's storage migration landing first, I'd want to confirm sequencing with maintainers, either picking this up right after Issue 3 merges or coordinating a combined PR if that's a better fit.

[grantfox-oss]

🦊 GrantFox — @Markodiba6399 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.