Trustless USDC escrow for freelance digital art commissions on the Stellar Network.
ComiSure replaces informal, trust-based payment channels with a decentralized Soroban smart contract. It protects clients and artists from chargeback scams and ghost deliveries through instant, on-chain settlements.
- GitHub Repo: HitsukiMok/ComiSure
- Contract Factory ID:
CAWAKGBTHWFMTB6O74CDJ5WOVLLFZ5WMKTBKOP2FNB5BUMTQPZYQZN3J - Stellar Expert Factory Log: View Deployment Transaction on Testnet
- Project Demo Video
- Project Description
- Core Features
- Deployed Contract Details
- UI / Screenshots
- True Dynamic Pipeline Structure
- Tech Stack
- Deployment Architecture (Vercel + Render)
- Local Development Quickstart
- Deadline and Auto-Refund
- Smart Contract Development
- Project Structure
- Users Feedback
Click the badge above or navigate to the following link to view the live system walkthrough and features demonstration: Watch the ComiSure Demo Video on YouTube
Freelance digital artists and their clients face rampant fraud. Artists suffer severe income loss from malicious PayPal chargebacks after they deliver unwatermarked artwork. Clients risk sending upfront e-wallet payments to artists who disappear without delivering.
ComiSure is a decentralized web application that acts as a trustless escrow middleman. Clients initiate a commission by depositing USDC into a custom Soroban smart contract. The funds lock on-chain. This proves to the artist that the money is guaranteed. Once the artist delivers the final piece, the client approves the release. The funds then route instantly to the artist wallet. The Stellar network provides 5-second settlement times and sub-cent transaction fees. This makes smart contract escrows economically viable even for small, everyday art commissions.
- Trustless USDC Escrow: Lock commission funds upfront in a stablecoin. This protects both parties from crypto volatility and payment fraud.
- Client-Driven Approval: Funds release to the artist only when the client reviews and approves the final delivered artwork.
- Deadline and Auto-Refund: Each commission has a configurable deadline (1 to 90 days). If the artist does not deliver before the deadline, the client can self-refund directly from the smart contract without admin intervention.
- Admin Dispute Resolution: A built-in fallback mechanism. If a client maliciously withholds approval after delivery, or if an artist fails to deliver, the platform admin can force-release or refund the USDC.
- Dynamic Contract Generation: Every commission gets its own physically isolated Soroban smart contract. The backend generates each contract on the fly. This prevents centralized contract bottlenecks.
- Micro-transaction Optimized: Stellar ensures gas fees do not eat into the artist commission profits.
- Network: Stellar Testnet
- Smart Contract Environment: Soroban
- Deployed Factory Contract ID:
CAWAKGBTHWFMTB6O74CDJ5WOVLLFZ5WMKTBKOP2FNB5BUMTQPZYQZN3J - Supported Asset: USDC (Stellar Asset Contract)
The client confirms the deposit first for the set amount of USDC. The client can then approve the release of funds after the artist delivers the commission. If a dispute happens, the admin with the admin wallet can interfere by refunding or releasing the funds depending on the case.
Unlike traditional DApps that rely on a single monolithic smart contract to track all users, ComiSure creates a unique, physically isolated smart contract for every commission.
- Frontend Request: The UI requests a new escrow.
- Backend Engine: The FastAPI server connects to the Stellar CLI natively.
- On-the-fly Deployment: The backend deploys a pre-compiled
comi_sure.wasmbytecode payload directly onto the Stellar Network. - Initialization: The backend initializes the contract exclusively with the specific client and artist addresses, the deadline timestamp, and maps itself as the irrevocable admin.
- Smart Contract Level: Soroban SDK (Rust),
wasm32v1-none - Backend API Layer: Python 3, FastAPI, SQLModel, Uvicorn, PostgreSQL
- Frontend App: React 19, Vite, Tailwind CSS, Framer Motion
- Stellar SDK:
@stellar/stellar-sdk,@creit-tech/stellar-wallets-kit - Analytics: Vercel Analytics
ComiSure requires a specialized cloud infrastructure split between edge hosting and persistent container engines because of the dynamic compilation pipeline and state persistence.
The React frontend is lightweight, portable, and optimized for static hosting environments like Vercel. Set the Vercel project root directory to frontend/.
Required Vercel Environment Variables:
VITE_SOROBAN_RPC:https://soroban-testnet.stellar.orgVITE_API_URL:<YOUR_RENDER_WEB_SERVICE_URL>(e.g.,https://comisure-backend.onrender.com)
The Stellar CLI requirement, background system processes, and persistent data storage are handled via Render.
- Create a PostgreSQL instance on Supabase (free tier) or Render.
- Copy the connection string (use the pooler URL for Supabase if connecting from Render).
- Create a new web service on Render and link this GitHub repository.
- Set the root directory to
backend/. - Configure the environment to use the custom
Dockerfile. Render builds the container from it and installs the Linux Stellar CLI automatically.
Required Render Environment Variables:
DATABASE_URL: Your PostgreSQL connection string.DEPLOYER_SECRET_KEY: Your deployer identity for signing contract deployments. This can be a raw Stellar secret seed (S...) or a 24-word Stellar seed phrase.
Run both services side-by-side for local development.
- Navigate to the backend directory and set up a virtual environment:
cd backend
python -m venv venv
.\venv\Scripts\activate # Use `source venv/bin/activate` on Mac/Linux
pip install -r requirements.txt-
Run a local Redis server for rate limiting (optional; if not running, the backend falls back to in-memory tracking):
- Docker:
docker run --name comisure-redis -p 6379:6379 -d redis - macOS (Homebrew):
brew install redis && brew services start redis - Ubuntu/Debian:
sudo apt update && sudo apt install redis-server && sudo service redis-server start
- Docker:
-
Encrypt your Stellar deployer secret key for the environment:
python scripts/encrypt_secret.pyCopy the output base64 string to your .env as DEPLOYER_SECRET_KEY_ENCRYPTED_v1 and set DEPLOYER_DECRYPTION_PASSPHRASE.
- Start the backend:
uvicorn main:app --reloadThe API runs at http://127.0.0.1:8000.
cd frontend
npm install
npm run devThe web app runs at http://localhost:5173. You must have the Freighter browser extension installed to connect your wallet.
Each commission includes a configurable deadline. The client sets the deadline (1 to 90 days) when they create a commission. The smart contract stores the deadline as a Unix timestamp.
- The client creates a commission and sets the deadline (default: 14 days).
- The backend computes the deadline as a Unix timestamp and passes it to the smart contract during initialization.
- The smart contract stores the deadline immutably.
- If the artist does not deliver before the deadline, the client calls
client_refund_expireddirectly on-chain. - The contract verifies that the current ledger timestamp exceeds the stored deadline.
- If expired, the contract returns the full locked USDC to the client.
- The deadline does not block
approve_release. The client can still release funds after the deadline passes if the artist delivers late. - Admin actions (
admin_refund,admin_force_release) are not gated by the deadline. The admin can act at any time. - The deadline is immutable after contract initialization. Neither party can change it.
- The frontend displays a circular countdown timer (Orbit Timer) that visually depletes as time passes.
For a comprehensive breakdown of the smart contract internal logic, data structures, and function signatures, refer to the smart contract documentation.
- Rust toolchain with target
wasm32v1-none - Stellar CLI 22.0.0 or later
# Compile the contract to an optimized Wasm binary
stellar contract build
# Run cargo tests (7 tests: 3 core + 4 deadline)
cargo testComiSure/
├── frontend/ # React + Vite application and Wallet SDK integration
├── backend/ # Python FastAPI dynamic deployer and PostgreSQL tracker
├── Cargo.toml # Soroban package dependencies
└── contract/
├── lib.rs # Soroban Escrow Smart Contract code
└── test.rs # Tests for happy path, unauthorized calls, and deadline
We collected feedback from real users who tested the platform. Below are screenshots of user responses.
Submit your feedback via our Google Form
ComiSure received positive user feedback across all metrics. The platform scores above 4.0 in 6 of 7 categories. Visual design and ease of use are the strongest areas (4.7 and 4.6 respectively). The core value proposition — trustless escrow for art commissions — resonates clearly with users, reflected in the 4.5 trust score.
The primary gap is process clarity (3.9/5). Users understand the concept but struggle with the step-by-step execution. This is solvable through better onboarding copy, in-app tooltips, and a guided first-commission flow.
For a testnet MVP, these results demonstrate strong product-market fit with the target audience (Filipino freelance artists and their clients). The platform is technically sound, visually polished, and functionally complete. The recommended next steps are: improve onboarding clarity, differentiate the artist dashboard, and fix the timezone offset in the deadline timer.