Deployment Guide

Prerequisites

Before deploying Vowena, ensure you have the following installed:

Rust (latest stable) - rustup.rs
wasm32 target - rustup target add wasm32-unknown-unknown
Stellar CLI - cargo install stellar-cli or via Stellar docs
A funded Stellar account (mainnet XLM for fees, or testnet faucet for testing)

Build and Deploy

Clone the repository

git clone https://github.com/vowena/vowena.git
cd vowena

Build the WASM binary

Compile the Soroban smart contract to WebAssembly:

stellar contract build

This produces the optimized WASM binary at target/wasm32v1-none/release/vowena.wasm.

The compiled WASM is approximately 18.5 KB - well within Soroban’s size limits. The contract exports 17 functions.

Deploy to the network

Mainnet
Testnet

stellar contract deploy \
  --wasm target/wasm32v1-none/release/vowena.wasm \
  --network mainnet \
  --source $YOUR_SECRET_KEY

Mainnet deployment costs real XLM. Ensure your account is funded and double-check the WASM binary before deploying. Contract upgrades are possible but require the admin key.

stellar contract deploy \
  --wasm target/wasm32v1-none/release/vowena.wasm \
  --network testnet \
  --source $YOUR_SECRET_KEY

This returns the contract ID - save it. You will need it for every subsequent interaction.

# Example output:
# CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Initialize the contract

After deployment, initialize the contract with an admin address:

Mainnet
Testnet

stellar contract invoke \
  --id $CONTRACT_ID \
  --network mainnet \
  --source $YOUR_SECRET_KEY \
  -- initialize \
  --admin $ADMIN_ADDRESS

stellar contract invoke \
  --id $CONTRACT_ID \
  --network testnet \
  --source $YOUR_SECRET_KEY \
  -- initialize \
  --admin $ADMIN_ADDRESS

The admin address is used only for TTL management (extend_ttl). It cannot access funds, modify plans, or interfere with subscriptions. See Security for details.

Verify the deployment

Confirm the contract is live by calling a read-only function:

Mainnet
Testnet

stellar contract invoke \
  --id $CONTRACT_ID \
  --network mainnet \
  -- get_plan \
  --plan_id 1

stellar contract invoke \
  --id $CONTRACT_ID \
  --network testnet \
  -- get_plan \
  --plan_id 1

This should return an error like Plan not found - which confirms the contract is deployed and responding. No plans exist yet because none have been created.

Create your first plan

Test the full flow by creating a plan:

Mainnet
Testnet

stellar contract invoke \
  --id $CONTRACT_ID \
  --network mainnet \
  --source $YOUR_SECRET_KEY \
  -- create_plan \
  --merchant $MERCHANT_ADDRESS \
  --token $USDC_TOKEN_ADDRESS \
  --amount 100000000 \
  --period 2592000 \
  --trial_periods 0 \
  --max_periods 12 \
  --grace_period 259200 \
  --price_ceiling 150000000

stellar contract invoke \
  --id $CONTRACT_ID \
  --network testnet \
  --source $YOUR_SECRET_KEY \
  -- create_plan \
  --merchant $MERCHANT_ADDRESS \
  --token $USDC_TOKEN_ADDRESS \
  --amount 100000000 \
  --period 2592000 \
  --trial_periods 0 \
  --max_periods 12 \
  --grace_period 259200 \
  --price_ceiling 150000000

On testnet, you can get test USDC from the Stellar Laboratory. Use the test token address for the --token parameter.

Testing

The Vowena contract includes a comprehensive test suite:

cargo test

Test coverage

The test suite includes 29 tests covering:

Plan creation and validation
Subscription lifecycle (create, cancel, expire)
Billing flow (charge, trial periods, grace periods)
Failed charge handling and pre-check logic
Migration request, accept, and reject flows
Refund processing
TTL extension
Edge cases (double charge, early charge, unauthorized access)

Running specific tests

# Run a specific test
cargo test test_charge_flow

# Run with output
cargo test -- --nocapture

# Run only billing tests
cargo test billing

Contract Specifications

Property	Value
WASM size	~18.5 KB
Exported functions	17
Storage types	Instance + Persistent
Token standard	SEP-41 (SAC)
Soroban SDK	Latest stable

Environment Variables Reference

For convenience, set these in your shell when working with the contract:

# Contract ID (set after deployment)
export CONTRACT_ID="CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"

# Your Stellar secret key
export YOUR_SECRET_KEY="S..."

# Admin address
export ADMIN_ADDRESS="G..."

# Merchant address
export MERCHANT_ADDRESS="G..."

# USDC token contract
export USDC_TOKEN_ADDRESS="CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI"

Never commit secret keys to version control. Use environment variables or a secrets manager. The values above are examples only.

What’s Next

TypeScript SDK

Install the SDK and start building integrations.

Keeper Setup

Set up a keeper bot to automate billing.

API Reference

Complete reference for every contract function.

Architecture

Review the contract architecture and data models.

​Prerequisites

​Build and Deploy

​Testing

​Contract Specifications

​Environment Variables Reference

​What’s Next

TypeScript SDK

Keeper Setup

API Reference

Architecture

Prerequisites

Build and Deploy

Testing

Contract Specifications

Environment Variables Reference

What’s Next