Trivela is a Stellar Soroban–based campaign and rewards platform. It lets campaign operators create on-chain campaigns, register participants, award points via smart contracts, and let users claim rewards—all on the Stellar network. The project is built for the Stellar Wave on Drips and is designed for open-source contributors.
- Campaigns – Create and manage reward campaigns with on-chain configuration (Soroban).
- Rewards contract – Tracks user points, credits (by admin/campaign), and claims.
- Campaign contract – Stores campaign active flag and participant registration.
- Backend API – REST API for campaign metadata, health checks, and integration.
- Frontend – React app to list campaigns and (when wired) connect wallets and interact with contracts.
Use cases: loyalty points, drip campaigns, bounties, and any flow where you need on-chain rewards + off-chain campaign metadata.
Trivela/
├── contracts/ # Soroban (Rust) smart contracts
│ ├── rewards/ # Points balance, credit, claim
│ └── campaign/ # Campaign active flag, participant list
├── backend/ # Node.js Express API
├── frontend/ # React + Vite + Stellar SDK
├── Cargo.toml # Rust workspace
├── package.json # npm workspaces (backend + frontend)
└── README.md
For a quick system map (diagram, trust boundaries, and end-to-end data flows), see docs/ARCHITECTURE_OVERVIEW.md.
For the supported Stellar testnet/mainnet presets and runtime config flow, see docs/STELLAR_NETWORKS.md.
- Rust (for Soroban): rustup
- Stellar CLI (optional but recommended): Install Stellar CLI
- Node.js 18+
If you cloned or created this repo without git:
./scripts/setup-git.sh
git add . && git commit -m "chore: initial Trivela scaffold"
git branch -M main && git push -u origin mainUse a Personal Access Token (PAT) with repo scope when pushing over HTTPS, or switch to SSH: git remote set-url origin git@github.com:FinesseStudioLab/Trivela.git.
git clone https://github.com/FinesseStudioLab/Trivela.git
cd Trivela
npm installTo build the smart contracts, ensure you have the Stellar CLI installed.
# Build both contracts using Stellar CLI
stellar contract build
# Alternatively, build specific packages with cargo
cargo build --target wasm32-unknown-unknown --release -p trivela-rewards-contract
cargo build --target wasm32-unknown-unknown --release -p trivela-campaign-contract-
Configure an Identity:
stellar keys generate alice --network testnet
-
Deploy the WASM:
# Deploy Rewards Contract stellar contract deploy \ --wasm target/wasm32-unknown-unknown/release/trivela_rewards_contract.wasm \ --source alice --network testnet # Deploy Campaign Contract stellar contract deploy \ --wasm target/wasm32-unknown-unknown/release/trivela_campaign_contract.wasm \ --source alice --network testnet
-
Initialize the Contracts: After deployment, you will receive a Contract ID. Use it to call the
initializefunction:stellar contract invoke --id <CONTRACT_ID> --source alice --network testnet -- \ initialize --admin alice --name "Trivela Rewards" --symbol "TVL"
You can also build and deploy both contracts with the helper script:
STELLAR_SOURCE=alice npm run deploy:testnetOptional environment variables:
STELLAR_NETWORK: Stellar CLI network alias to deploy against (defaults totestnet)STELLAR_SOURCE: Stellar CLI identity used for the deployTRIVELA_ENV_OUT: output env file for the deployed contract IDs (defaults to.env.testnet)
The script writes:
VITE_REWARDS_CONTRACT_ID=...
VITE_CAMPAIGN_CONTRACT_ID=...cp backend/.env.example backend/.env
npm run dev:backendAPI: http://localhost:3001 (health: http://localhost:3001/health, v1: http://localhost:3001/api/v1).
Campaign endpoints are available under the versioned prefix:
GET /api/v1/campaigns
GET /api/v1/campaigns/:id
POST /api/v1/campaigns
PUT /api/v1/campaigns/:id
DELETE /api/v1/campaigns/:idMigration note:
Legacy /api/* campaign routes are still available for backward compatibility, but new integrations should target /api/v1/*.
npm run dev:frontendApp: http://localhost:5173 (proxies /api and /api/v1 to the backend).
docker compose up --buildThis starts the backend on http://localhost:3001 and the frontend on http://localhost:5173.
The backend container uses CORS_ALLOWED_ORIGINS=http://localhost:5173 and the frontend container
uses VITE_API_URL=http://backend:3001 so the two services can talk to each other on the Compose
network.
To add the optional Redis service for local experimentation, include the redis profile:
docker compose --profile redis up --build# All tests (Contracts + Backend + Frontend E2E)
npm run test
# Rust contracts
cargo test --workspace
# Backend tests
npm run test:backend
# Frontend E2E tests (Playwright)
# 1. Build the frontend first (required for `npm run preview`)
npm run build:frontend
# 2. Run the tests
npm run test:frontendThe frontend E2E tests use Playwright. They run against a local preview server (npm run preview). Ensure the backend is running if you want the tests to hit real API endpoints, otherwise they will show the "empty state" as expected in a isolated environment.
| Layer | Stack |
|---|---|
| Smart contracts | Rust, Soroban SDK |
| Backend | Node.js, Express |
| Frontend | React, Vite, @stellar/stellar-sdk |
| Network | Stellar (testnet/mainnet), Soroban RPC |
Sync the shared label taxonomy with GitHub CLI:
gh auth login
npm run labels:sync -- --repo FinesseStudioLab/TrivelaThe taxonomy lives in scripts/github-labels.json and the sync script is idempotent, so re-running it updates colors/descriptions instead of failing.
After the repo is pushed, create labels and open all 50 issues in GitHub in one go:
node scripts/create-github-issues.jsThis reads PAT from .env.local, creates issues from docs/issues-data.json, and can still be used for bulk issue creation. For labels, prefer npm run labels:sync so maintainers can rely on gh auth instead of PAT-based automation.
We welcome contributions, especially from the Stellar and Drip community. Please read CONTRIBUTING.md and check the open issues for labeled tasks (backend, frontend, smart-contract, good first issue, etc.).
Apache-2.0. See LICENSE for details.