charge

fn charge(env: Env, sub_id: u64) -> bool

Attempts to charge a subscription that is due for billing. This is the only write function in Vowena that requires no authorization. Anyone can call it. The contract validates all conditions on-chain and either transfers funds or handles the failure gracefully. Returns true if the charge succeeded, false if it did not.

charge() is permissionless by design. There is no require_auth() call. This enables keeper bots, third-party services, or anyone to trigger billing without the merchant’s private key. The contract enforces all safety checks (timing, balance, allowance, and subscription status), so permissionless calling is safe.

Parameters

Name	Type	Description
`sub_id`	`u64`	The subscription ID to charge.

Authorization

None. This function has no require_auth(). Anyone can call it.

Return value

bool - true if the charge was processed successfully, false if it was not charged (e.g., not yet due, insufficient funds).

Pre-charge validation

Before attempting the transfer_from, the contract checks the subscriber’s balance and allowance. This is a deliberate design decision:

The contract pre-checks the subscriber’s token balance and allowance before calling transfer_from(). If either is insufficient, the charge fails gracefully (emitting charge_fail) instead of reverting the transaction. This means the caller still pays the transaction fee, but the subscription enters the grace period flow instead of causing an on-chain error.

The contract checks, in order:

Does the subscription exist and is it Active?
Has the next_billing_time passed?
Is this a trial period? (If so, advance the period counter without transferring funds.)
Has max_periods been reached? (If so, expire the subscription.)
Does the subscriber have sufficient balance?
Does the subscriber have sufficient allowance?
Execute transfer_from() to move funds from subscriber to merchant.

Events emitted

Event	Topics	Data	Condition
`charge_ok`	`subscriber`, `sub_id`, `amount`	Period number	Charge succeeded
`charge_fail`	`subscriber`, `sub_id`	Failure reason	Balance or allowance insufficient
`sub_paused`	`subscriber`, `sub_id`	`failed_at` timestamp	Grace period expired on a previously failed charge
`sub_expired`	`subscriber`, `sub_id`	`periods_billed`	Max periods reached
`sub_cancel`	`subscriber`, `sub_id`	`cancelled_at` timestamp	Subscription cancelled due to expiry

Error cases

charge() is designed to fail gracefully rather than revert. It returns false for most failure conditions rather than throwing an error. However, the following will cause a revert:

Code	Name	Description
8	`SubNotFound`	No subscription exists with the given `sub_id`.

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,
});

// Anyone can build and submit this. No specific signer required
const tx = await client.buildCharge(
  "GCALLER...ADDR",   // Any address (pays the tx fee)
  subscriptionId       // Subscription ID to charge
);

const signedXdr = await signTransaction(tx);
const result = await client.submitTransaction(signedXdr);
console.log("Charged:", result.charged); // true or false

soroban contract invoke \
  --id CONTRACT_ID \
  --network mainnet \
  --source ANY_SECRET_KEY \
  -- \
  charge \
  --sub_id 1

Who should call charge()?

Since charge() is permissionless, there are several options:

Keeper bots - automated services that monitor next_billing_time and call charge() on schedule.
The merchant - can call charge() directly from their backend.
The Vowena Dashboard - includes a built-in keeper service.
Third-party networks - any service can integrate charge calling.

The caller pays the Stellar transaction fee (~0.00001 XLM), but needs no special authorization.

What happens when a charge fails?

If the subscriber has insufficient balance or allowance:

The charge_fail event is emitted.
failed_at is set to the current timestamp.
On the next charge() call, if now > failed_at + grace_period, the subscription is paused.
A paused subscription can be reactivated by the subscriber via reactivate().

Overview

Core

Management

Migrations

Read-only

Utilities

Parameters

Authorization

Return value

Pre-charge validation

Events emitted

Error cases

Examples

​Parameters

​Authorization

​Return value

​Pre-charge validation

​Events emitted

​Error cases

​Examples

Parameters

Authorization

Return value

Pre-charge validation

Events emitted

Error cases

Examples