Skip to main content

​
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 (testnet faucet or mainnet XLM for fees)

​
Build and Deploy

1

Clone the repository

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

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.
3

Deploy to the network

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
4

Initialize the contract

After deployment, initialize the contract with an 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.
5

Verify the deployment

Confirm the contract is live by calling a read-only function:
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.
6

Create your first plan

Test the full flow by creating a plan:
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 testnet faucet. Use the test token address for the --token parameter.

​
Testing

The Vowena contract includes a comprehensive test suite: 
cargo test
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)
# Run a specific test
cargo test test_charge_flow

# Run with output
cargo test -- --nocapture

# Run only billing tests
cargo test billing

​
Contract Specifications

PropertyValue
WASM size~18.5 KB
Exported functions17
Storage typesInstance + Persistent
Token standardSEP-41 (SAC)
Soroban SDKLatest 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 (testnet)
export USDC_TOKEN_ADDRESS="CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA"
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.