Skip to content

deployment.mdx

Latest commit

 

History

History
284 lines (231 loc) · 7.37 KB

deployment.mdx

File metadata and controls

284 lines (231 loc) · 7.37 KB
title Deployment Guide
description Step-by-step guide to building, deploying, and initializing the Vowena smart contract on Stellar's Soroban platform - for both mainnet and testnet.

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

```bash git clone https://github.com/vowena/vowena.git cd vowena ``` Compile the Soroban smart contract to WebAssembly: 
```bash
stellar contract build
```

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

<Tip>
  The compiled WASM is approximately **18.5 KB** - well within Soroban's size limits. The contract exports **17 functions**.
</Tip>
```bash stellar contract deploy \ --wasm target/wasm32v1-none/release/vowena.wasm \ --network testnet \ --source $YOUR_SECRET_KEY ``` 
    <Warning>
      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.
    </Warning>
  </Tab>
  <Tab title="Testnet">
    ```bash
    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
    ```
  </Tab>
</Tabs>
After deployment, initialize the contract with an admin address: 
<Tabs>
  <Tab title="Mainnet">
    ```bash
    stellar contract invoke \
      --id $CONTRACT_ID \
      --network testnet \
      --source $YOUR_SECRET_KEY \
      -- initialize \
      --admin $ADMIN_ADDRESS
    ```
  </Tab>
  <Tab title="Testnet">
    ```bash
    stellar contract invoke \
      --id $CONTRACT_ID \
      --network testnet \
      --source $YOUR_SECRET_KEY \
      -- initialize \
      --admin $ADMIN_ADDRESS
    ```
  </Tab>
</Tabs>

<Note>
  The admin address is used only for TTL management (`extend_ttl`). It cannot access funds, modify plans, or interfere with subscriptions. See [Security](/protocol/security) for details.
</Note>
Confirm the contract is live by calling a read-only function: 
<Tabs>
  <Tab title="Mainnet">
    ```bash
    stellar contract invoke \
      --id $CONTRACT_ID \
      --network testnet \
      -- get_plan \
      --plan_id 1
    ```
  </Tab>
  <Tab title="Testnet">
    ```bash
    stellar contract invoke \
      --id $CONTRACT_ID \
      --network testnet \
      -- get_plan \
      --plan_id 1
    ```
  </Tab>
</Tabs>

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.
Test the full flow by creating a plan: 
<Tabs>
  <Tab title="Mainnet">
    ```bash
    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
    ```
  </Tab>
  <Tab title="Testnet">
    ```bash
    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
    ```
  </Tab>
</Tabs>

<Tip>
  On testnet, you can get test USDC from the [Stellar Laboratory](https://laboratory.stellar.org). Use the test token address for the `--token` parameter.
</Tip>

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)
```bash # 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

Install the SDK and start building integrations. Set up a keeper bot to automate billing. Complete reference for every contract function. Review the contract architecture and data models.