extend_ttl

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

SDK
Soroban CLI

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

const client = new VowenaClient({
  contractId: NETWORKS.mainnet.contractId,
  rpcUrl: NETWORKS.mainnet.rpcUrl,
  networkPassphrase: NETWORKS.mainnet.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);

soroban contract invoke \
  --id CONTRACT_ID \
  --network mainnet \
  --source ANY_SECRET_KEY \
  -- \
  extend_ttl \
  --plan_id 1 \
  --sub_id 5

Why does TTL matter?

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.

Who should call extend_ttl?

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.

What are the TTL thresholds?

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.

Overview

Core

Management

Migrations

Read-only

Utilities

Parameters

Authorization

Return value

Events emitted

Error cases

Examples

​Parameters

​Authorization

​Return value

​Events emitted

​Error cases

​Examples

Parameters

Authorization

Return value

Events emitted

Error cases

Examples