The Vowena contract exposes 17 functions covering the full subscription lifecycle. This reference documents every function with its parameters, authorization requirements, events, and error codes.
Write functions return assembled XDR via the SDK. You sign the transaction with your wallet and submit it to the network. Read functions query contract state directly and return data without requiring a transaction signature.
Functions by category
Setup
| Function | Description | Auth |
|---|
initialize | One-time contract setup. Sets admin and initializes counters. | None (first call only) |
Plans
| Function | Description | Auth |
|---|
create_plan | Creates a new billing plan with pricing, period, trials, and limits. | Merchant |
update_plan_amount | Updates the billing amount within the price ceiling. | Merchant |
Subscriptions
| Function | Description | Auth |
|---|
subscribe | Subscribes to a plan. Sets token allowance and creates the subscription. | Subscriber |
cancel | Cancels a subscription immediately. Irreversible. | Subscriber or Merchant |
reactivate | Reactivates a paused subscription. Re-approves allowance and attempts charge. | Subscriber |
Billing
| Function | Description | Auth |
|---|
charge | Charges a due subscription. Permissionless - anyone can call. | None |
refund | Refunds a subscriber from the merchant’s wallet. | Merchant |
Migrations
| Function | Description | Auth |
|---|
request_migration | Requests migration of all subscribers from one plan to another. | Merchant |
accept_migration | Accepts a pending migration. Cancels old sub and creates new one. | Subscriber |
reject_migration | Rejects a pending migration. Stays on current plan. | Subscriber |
Read-only
| Function | Description | Auth |
|---|
get_plan | Returns the Plan struct for a given plan ID. | None |
get_subscription | Returns the Subscription struct for a given subscription ID. | None |
get_merchant_plans | Returns all plan IDs belonging to a merchant. | None |
get_subscriber_subscriptions | Returns all subscription IDs for a subscriber. | None |
get_plan_subscribers | Returns all active subscription IDs on a plan. | None |
extend_ttl | Extends TTL of plan and subscription entries to prevent archival. | None |
Authorization model
Vowena uses Soroban’s require_auth() pattern. When a function requires authorization, the caller must sign the transaction with the appropriate keypair:
- Merchant functions - the merchant address stored on the plan must sign.
- Subscriber functions - the subscriber address stored on the subscription must sign.
- Permissionless functions -
charge() is the only write function that requires no authorization. Anyone can call it, and the contract validates all conditions on-chain.
Read-only functions (get_plan, get_subscription, etc.) never require a signature. They query contract state directly via Soroban’s simulation endpoint.
Error codes
Every error returned by the contract maps to a numeric code:
| Code | Name | Description |
|---|
| 1 | AlreadyInitialized | Contract has already been initialized |
| 3 | InvalidAmount | Amount is zero or negative |
| 4 | InvalidPeriod | Period is zero |
| 5 | CeilingBelowAmount | Price ceiling is less than the plan amount |
| 6 | PlanNotFound | No plan exists with the given ID |
| 7 | PlanInactive | Plan is not accepting new subscribers |
| 8 | SubNotFound | No subscription exists with the given ID |
| 9 | Unauthorized | Caller is not authorized for this action |
| 10 | AmountExceedsCeiling | New amount exceeds the plan’s price ceiling |
| 11 | MerchantMismatch | Old and new plans belong to different merchants |
| 12 | NoMigrationPending | No migration has been requested for this subscription |
| 13 | NotPaused | Subscription is not in a paused state |
SDK vs CLI
Every function can be called through the TypeScript SDK or the Soroban CLI. The SDK wraps each function with a typed builder method that returns assembled XDR for signing. The CLI is useful for one-off operations and scripting.
const tx = await client.buildFunctionName({ ...params });
const signed = await signTransaction(tx);
const result = await client.submitTransaction(signed);
soroban contract invoke \
--id CONTRACT_ID \
--network testnet \
--source SIGNER_SECRET \
-- \
function_name \
--param1 value1 \
--param2 value2
