A Soroban smart contract for recurring paid subscriptions on the Pi Network. Merchants register services with configurable pricing and billing periods; subscribers pay using standard Stellar asset tokens via allowance-based recurring charges.

• Overview
• Architecture
• Data Model
• Contract API
• Payment Flow
• Access Control
• Events
• Error Codes
• Storage Layout & TTL

The contract implements a merchant-initiated pull-payment model:

1. Merchant registers a service (name, price, billing period, optional trial, approval window).
2. Subscriber subscribes to the service, optionally enabling auto-renewal and granting a token allowance to the contract for future charges.
3. Merchant periodically calls process(service_id, offset, limit) to batch-charge due subscribers via transfer_from against their approved allowances.
4. Subscriber can cancel, toggle auto-renewal, or extend their subscription at any time.

Key design properties:

• No charge drift -- next_charge_ts is always computed as old_next_charge_ts + period_secs, not from wall-clock time.
• Paginated batch processing -- process() accepts offset and limit parameters to handle large subscriber sets across multiple transactions.
• Graceful failure isolation -- failed charges and timestamp overflows disable auto-renewal (auto_renew = false) for the individual subscription instead of reverting the entire batch.
• Deduplication -- a subscriber cannot hold two active subscriptions to the same service simultaneously.
• Trial abuse prevention -- a subscriber who already used a free trial cannot re-subscribe without auto_renew=true, preventing infinite free trials.

Subscriber                 Contract                    Token Contract           Merchant
    |                         |                              |                     |
    |-- subscribe() --------->|                              |                     |
    |                         |-- approve(N periods) ------> |                     |
    |                         |-- transfer(price) ---------> |---> merchant         |
    |                         |                              |                     |
    |                         |<-------------- process() ----|                     |
    |                         |-- transfer_from(sub->merch)->|                     |
    |                         |   (for each due subscriber)  |                     |
    |                         |                              |                     |
    |-- cancel() ------------>|  sets auto_renew=false       |                     |

Registered by a merchant. Represents a billable subscription offering.

Represents one subscriber's relationship to one service.

Returned by process() to report batch outcomes.

fn __constructor(env: Env, admin: Address, token: Address)

Initializes the contract. Sets the admin, token address, and zeroes the service/subscription ID counters. Called once at deployment.

fn register_service(
    env: Env,
    merchant: Address,
    name: String,
    price: i128,
    period_secs: u64,
    trial_period_secs: u64,
    approve_periods: u64,
) -> Result<Service, ContractError>

Creates a new subscription service.

Auth: merchant

Validation:

• price > 0 -> InvalidPrice
• period_secs > 0 -> InvalidPeriod
• approve_periods > 0 -> InvalidPeriod
• name non-empty -> InvalidServiceName

Effects:

• Stores Service under DataKey::Service(service_id)
• Appends service_id to DataKey::MerchantServices(merchant)
• Emits srv_reg event

fn subscribe(
    env: Env,
    subscriber: Address,
    service_id: u64,
    auto_renew: bool,
) -> Result<Subscription, ContractError>

Subscribes to a service. Behavior depends on trial period and auto_renew flag:

Auth: subscriber

Deduplication: Rejects with AlreadySubscribed if the subscriber has an active subscription to the same service, unless the previous subscription has expired and auto_renew=false.

Trial abuse prevention: If the subscriber previously used a free trial for this service, re-subscribing with auto_renew=false to a trial service is blocked. The subscriber must set auto_renew=true (committing to paid renewal after the trial).

Effects:

• Stores Subscription under DataKey::Sub(sub_id)
• Updates index keys: SubscriberSubs, ServiceSubs, SubServicePair
• Calls token.approve() before token.transfer() (approval is pre-authorized)
• Emits sub, approve, and optionally low_bal events

fn cancel(env: Env, subscriber: Address, sub_id: u64) -> Result<(), ContractError>

Cancels auto-renewal. The subscription remains active until service_end_ts.

Auth: subscriber (must own the subscription)

Validation:

• AlreadyCancelled if auto_renew is already false

Effects:

• Sets auto_renew = false
• Emits cancel event with remaining seconds

fn toggle_auto_renew(
    env: Env,
    subscriber: Address,
    sub_id: u64,
) -> Result<bool, ContractError>

Toggles the auto_renew flag. When re-enabling (false -> true), refreshes the token approval.

Auth: subscriber (must own the subscription)

Validation:

• SubscriptionExpired if re-enabling on a fully expired subscription

Effects:

• Flips auto_renew
• If re-enabled: calls token.approve() for approve_periods
• Emits renew event

fn extend_subscription(
    env: Env,
    subscriber: Address,
    sub_id: u64,
) -> Result<Subscription, ContractError>

Refreshes the token approval on an active subscription (useful when the original approval is about to expire).

Auth: subscriber (must own the subscription)

Validation:

• SubscriptionExpired if service_end_ts <= now

Effects:

• Sets auto_renew = true
• Calls token.approve() for approve_periods
• Emits extend and approve events

fn process(
    env: Env,
    merchant: Address,
    service_id: u64,
    offset: u32,
    limit: u32,
) -> Result<ProcessResult, ContractError>

Batch-charges due subscriptions for a service. This is the core billing function.

Auth: merchant (must own the service via NotServiceOwner check)

Pagination: Soroban transactions have finite resource limits (read/write ledger entries and bytes per transaction). Large subscriber sets must be processed in batches using offset and limit. The returned ProcessResult.total indicates the total number of subscriptions, allowing the caller to determine how many batches are needed.

Example batch loop:

// Process 20 subscriptions per transaction
batch 1: process(merchant, service_id, 0, 20)   -> total=55
batch 2: process(merchant, service_id, 20, 20)
batch 3: process(merchant, service_id, 40, 20)   -> covers remaining 15

Processing logic for each subscription in the [offset, offset+limit) window:

1. Skip if subscription not found in storage -> increment skipped
2. Skip if auto_renew == false (not auto-renewing) -> increment skipped
3. Skip if now < next_charge_ts (not yet due) -> increment skipped
4. Attempt token.try_transfer_from(subscriber -> merchant, price)
   • Success:
     • next_charge_ts += period_secs (on overflow: sets auto_renew = false, increments failed, continues)
     • service_end_ts = next_charge_ts
     • Emits charge event
     • If was in trial period: emits trl_end event
     • Checks remaining allowance and balance; emits low_alw / low_bal if insufficient for next period
     • Increments charged
   • Failure:
     • Sets auto_renew = false
     • Emits chg_fail event
     • Increments failed

No charge drift guarantee: next_charge_ts and service_end_ts are advanced by exactly period_secs from their previous values, not from wall-clock time.

Failure isolation: Neither payment failures nor timestamp overflows revert the transaction. Each problematic subscription is individually marked as auto_renew = false and the batch continues processing the remaining subscriptions.

All query functions are read-only and are typically called via simulateTransaction (no gas cost). They do not bump storage TTLs -- TTL extension happens only in mutating functions (subscribe, process, cancel, toggle_auto_renew, extend_subscription, register_service).

fn get_service(env: Env, service_id: u64) -> Result<Service, ContractError>

Returns service details. No auth required.

fn get_merchant_services(env: Env, merchant: Address) -> Vec<Service>

Returns all services registered by a merchant. No auth required.

fn get_subscription(
    env: Env,
    caller: Address,
    sub_id: u64,
) -> Result<Subscription, ContractError>

Returns subscription details.

Auth: caller must be the subscriber or the merchant of the service.

fn get_subscriber_subs(env: Env, subscriber: Address) -> Vec<Subscription>

Returns all subscriptions for a subscriber. Gracefully skips subscriptions that have expired from storage.

Auth: subscriber

fn get_merchant_subs(
    env: Env,
    merchant: Address,
    service_id: u64,
) -> Result<Vec<Subscription>, ContractError>

Returns all subscriptions for a service. Gracefully skips subscriptions that have expired from storage.

Auth: merchant (must own the service)

fn is_subscription_active(env: Env, subscriber: Address, service_id: u64) -> bool

Returns true if a subscription exists and current_timestamp < service_end_ts. Returns false if the subscription or index entry is not found. No auth required.

fn upgrade(env: Env, new_wasm_hash: BytesN<32>)

Replaces the contract WASM code.

Auth: admin

fn version(_env: Env) -> u32

Returns the current contract version number (currently 1). No auth required.

The contract uses the Stellar token approve + transfer_from pattern for recurring charges:

1. On subscribe(), toggle_auto_renew(true), or extend_subscription(), the contract calls token.approve() on behalf of the subscriber, granting the contract an allowance of price * approve_periods (using checked multiplication to prevent overflow).
2. The approval expiration ledger is calculated as: current_ledger + ((period_secs * approve_periods + extra_secs) / 5), capped at the network's max TTL. For trial subscriptions, extra_secs includes trial_period_secs to ensure the approval doesn't expire before the trial ends.
3. In the no-trial case, token.approve() is called before token.transfer() so the contract is pre-authorized.
4. On each process() cycle, the contract calls token.try_transfer_from() to pull price from the subscriber to the merchant.
5. When the approval is running low (remaining allowance < price), a low_alw event is emitted to signal that the subscriber should call extend_subscription().

subscribe(auto_renew=true, trial=7d, period=30d)
  |
  |--- Day 0: No payment. Approval granted for N periods.
  |
  |--- Day 7 (trial ends): process() charges first period.
  |                         Emits "trl_end" + "charge".
  |                         service_end_ts = day 7 + 30d = day 37
  |                         next_charge_ts = day 7 + 30d = day 37
  |
  |--- Day 37: process() charges second period.
  |             service_end_ts = day 67
  |             next_charge_ts = day 67
  |
  |--- Day 67: process() charges third period...

All authenticated functions use require_auth() and verify the caller matches the expected role. Mismatches return ContractError::Unauthorized or ContractError::NotServiceOwner.

Persistent storage TTL extend is computed dynamically based on the service's billing period:

ttl_extend = max(period_secs * 2 / SECS_PER_LEDGER, PERSISTENT_TTL_EXTEND_MIN)

This ensures data survives at least 2 full billing periods between process() calls. Without this, a quarterly subscription (90-day period) would lose its data after ~30 days of the fixed TTL, before the next process() call.

TTL bumps (bump_persistent, bump_instance) are performed only in mutating functions (subscribe, process, cancel, toggle_auto_renew, extend_subscription, register_service). Query functions do not bump TTLs because they are typically executed via simulateTransaction, where state changes are discarded.

This means persistent data stays alive as long as the service has active interactions (new subscriptions, recurring charges, cancellations). Data for fully inactive services (no subscribers, no process calls) may eventually expire from storage -- this is by design.