ExtendFootprintTTLOperation class

Extends the time-to-live (TTL) of Soroban contract state entries.

This operation extends the TTL of active contract data entries, preventing them from being archived. Soroban uses TTL-based state archival to manage ledger size. Entries with expired TTLs are moved to cheaper archived storage. This operation extends TTLs to keep entries in active, immediately accessible storage.

Soroban TTL Management:

• TTL: Number of ledgers until entry is archived
• Minimum TTL: Protocol-defined minimum value (varies by entry type)
• Maximum TTL: Upper bound on TTL extension
• Cost: Fees based on entry size and extension duration

TTL Extension Strategy:

• Extend frequently accessed data to avoid restoration costs
• Balance extension costs vs restoration costs
• Consider access patterns and data importance
• Monitor TTLs and extend before expiration

Parameters:

• extendTo: Number of ledgers to extend the TTL to (not by)

Use Cases:

• Prevent important contract data from archival
• Maintain active state for frequently used contracts
• Extend TTL after restoring archived entries
• Ensure contract availability during critical periods

Example - Extend Contract Data TTL:

// Extend TTL to 100,000 ledgers (approximately 6 days)
var extendOp = ExtendFootprintTTLOperationBuilder(100000)
  .setSourceAccount(accountId)
  .build();

// Include footprint specifying which entries to extend
var footprint = SorobanTransactionData(
  resources: SorobanResources(
    footprint: LedgerFootprint(
      readOnly: ledgerKeysToExtend
    )
  )
);

var transaction = TransactionBuilder(account)
  .addOperation(extendOp)
  .setSorobanData(footprint)
  .build();

Important Considerations:

• Extension cost increases with duration and entry size
• Cannot extend beyond maximum TTL
• Footprint must specify entries to extend
• Consider periodic extensions for critical data
• Batch extensions when possible to save fees

See also:

• RestoreFootprintOperation to restore archived entries
• InvokeHostFunctionOperation for contract invocation
• Soroban State Archival Documentation