extend-ttl.mdx

title	extend_ttl
description	Extends the time-to-live of plan and subscription storage entries on the Soroban ledger, preventing them from being archived and ensuring data availability.

fn extend_ttl(env: Env, plan_id: u64, sub_id: u64)

Extends the TTL (time-to-live) of plan and subscription persistent storage entries. This prevents these entries from being archived by the Soroban ledger when their TTL expires.

Soroban persistent storage entries have a finite TTL. When the TTL expires, the entry is **archived** - it still exists but cannot be accessed until restored. Calling `extend_ttl` refreshes the TTL window, keeping the data accessible. This is critical for long-running subscriptions that span months or years.

---

Parameters

Name	Type	Description
plan_id	u64	The plan ID whose TTL to extend.
sub_id	u64	The subscription ID whose TTL to extend.

---

Authorization

None. Anyone can extend the TTL of any entry. This is safe because extending TTL only keeps data accessible longer - it does not modify the data.

---

Return value

None (void).

---

Events emitted

None.

---

Error cases

None. If the plan or subscription does not exist, the function is a no-op.

---

Examples

```typescript import { VowenaClient, NETWORKS } from "@vowena/sdk";

const client = new VowenaClient({
  contractId: NETWORKS.testnet.contractId,
  rpcUrl: NETWORKS.testnet.rpcUrl,
  networkPassphrase: NETWORKS.testnet.networkPassphrase,
});

// Extend TTL for plan 1 and subscription 5
const tx = await client.buildExtendTtl(
  1,   // Plan ID
  5    // Subscription ID
);

const signedXdr = await signTransaction(tx);
await client.submitTransaction(signedXdr);
```

```bash soroban contract invoke \ --id CONTRACT_ID \ --network testnet \ --source ANY_SECRET_KEY \ -- \ extend_ttl \ --plan_id 1 \ --sub_id 5 ``` On Soroban, every piece of persistent data has a TTL measured in ledger sequence numbers. When the current ledger passes the entry's TTL, the entry is archived. Archived entries cannot be read or written until they are restored (which costs additional fees).

For Vowena, this means a subscription that hasn't been touched in several months could become inaccessible. The `extend_ttl` function prevents this by refreshing the TTL window.

Typically, keeper bots or the merchant's backend should periodically call `extend_ttl` for active plans and subscriptions. The Vowena Dashboard keeper service handles this automatically.

Since the function is permissionless, anyone can extend TTL for any entry - there is no access control needed because extending TTL only keeps data alive longer.

Vowena uses these default TTL policies:

- **Instance storage** (admin, counters): ~30 day threshold, ~90 day extend
- **Persistent storage** (plans, subscriptions, indexes): ~30 day threshold, ~120 day extend

The `extend_ttl` function refreshes persistent entries to the ~120 day extend window.