QuantX: Decentralized Recurring Payments Infrastructure for Web3

The "Stripe" for Web3 Recurring Payments

Live Demo • Documentation • Contract Explorer • Discord

###UI

🎯 Overview

QuantX is a Recurring Finance Infrastructure (RFI) protocol built on Stellar's Soroban smart contract platform. It solves the critical automation gap in Web3 by enabling trustless, non-custodial recurring payments using stablecoins (USDC/XLM).

Unlike traditional Web3 transactions that require manual signing for each payment, QuantX implements a smart contract vault system allowing users to pre-authorize recurring payments while maintaining full custody of their assets.

🏆 Key Features

✅ Non-Custodial: Users maintain full control of their funds
✅ Trustless Automation: Smart contracts execute payments based on predefined conditions
✅ Multi-Token Support: USDC, XLM, and other Stellar assets
✅ Flexible Scheduling: Daily, weekly, monthly, or custom intervals
✅ Multi-Platform: Web dashboard, SDK integration, and Telegram bot
✅ Gas-Efficient: Optimized Soroban contracts with minimal transaction costs
✅ Decentralized Execution: Open keeper network for payment triggering

💡 Use Cases

For SaaS & Content Creators

Subscription Services: Accept recurring payments for your SaaS, newsletter, or premium content
Membership Platforms: Automate member dues and tiered access
Creator Economy: Enable fans to support creators with automated monthly contributions

For DAOs & Employers

Automated Payroll: Schedule recurring payments to contributors and employees
Vesting Schedules: Implement token vesting with automated distributions
Treasury Management: Automate recurring operational expenses

For DeFi Protocols

Dollar-Cost Averaging: Enable users to automate investment strategies
Loan Repayments: Schedule automated loan installments
Yield Distribution: Automate rewards distribution to stakeholders

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Interfaces                          │
├──────────────────┬──────────────────┬──────────────────────────┤
│  Web Dashboard   │   Telegram Bot   │   Third-party dApps      │
│   (Next.js)      │   (Telegraf)     │   (via SDK)              │
└────────┬─────────┴────────┬─────────┴──────────┬───────────────┘
         │                  │                    │
         └──────────────────┼────────────────────┘
                            │
                   ┌────────▼────────┐
                   │   QuantX SDK    │
                   │  (TypeScript)   │
                   └────────┬────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
    ┌────▼─────┐   ┌───────▼────────┐   ┌────▼─────┐
    │ Freighter│   │ Soroban RPC    │   │ Horizon  │
    │  Wallet  │   │   Indexer      │   │   API    │
    └────┬─────┘   └───────┬────────┘   └────┬─────┘
         │                  │                  │
         └──────────────────┼──────────────────┘
                            │
                ┌───────────▼────────────┐
                │   Stellar Blockchain   │
                ├────────────────────────┤
                │  QuantX Smart Contract │
                │  - Subscription Vault  │
                │  - Payment Executor    │
                │  - Token Allowances    │
                └───────────┬────────────┘
                            │
                ┌───────────▼────────────┐
                │   Keeper Network       │
                │  (Automated Executors) │
                └────────────────────────┘

Architecture Components

1. User Layer

Web Dashboard: Next.js application for creating and managing subscriptions
Telegram Bot: Chat interface for subscription management on-the-go
SDK: TypeScript library for third-party integrations

2. Integration Layer

QuantX SDK: Handles wallet connections, transaction building, and state management
Dual-Layer Polling: Bridges Soroban RPC and Horizon API for reliable transaction indexing

3. Blockchain Layer

Smart Contracts: Rust-based Soroban contracts managing vaults and payment logic
Token Standards: Compatible with SEP-41 (Stellar Asset Contract)

4. Execution Layer

Keeper Network: Decentralized nodes monitoring and triggering due payments
Incentive Mechanism: Executors earn fees for successfully processing payments

📜 Smart Contract Details

Contract Addresses

Testnet Deployment

Network: Stellar Testnet (Soroban)
Contract ID: CDIDTRRDNMK4D6CIWFNLEML5L6FCVLMEVKCXXSAB6PJZ3J5JS74M7GFD
Explorer: https://stellar.expert/explorer/testnet/contract/[CONTRACT_ID]

Mainnet Deployment

Status: Pending Security Audit
Expected Launch: Q2 2025

Core Contract Functions

1. create_subscription

pub fn create_subscription(
    env: Env,
    payer: Address,
    recipient: Address,
    token: Address,
    amount: i128,
    interval: u64,
    start_time: u64,
) -> Result<u64, Error>

Creates a new recurring payment subscription.

Parameters:

payer: Address authorizing the recurring payment
recipient: Address receiving the payments
token: Asset contract address (USDC, XLM, etc.)
amount: Payment amount per interval
interval: Time between payments (in seconds)
start_time: Unix timestamp for first payment

Returns: Subscription ID

2. execute_payment

pub fn execute_payment(
    env: Env,
    subscription_id: u64,
) -> Result<(), Error>

Executes a due payment for an active subscription.

Authorization: Can be called by anyone (keeper network)

Validation:

Checks if payment is due based on timestamp
Verifies payer has sufficient allowance
Ensures payer has adequate balance

3. cancel_subscription

pub fn cancel_subscription(
    env: Env,
    subscription_id: u64,
) -> Result<(), Error>

Cancels an active subscription.

Authorization: Only subscription payer or recipient

4. get_subscription

pub fn get_subscription(
    env: Env,
    subscription_id: u64,
) -> Subscription

Retrieves subscription details.

Returns:

pub struct Subscription {
    pub payer: Address,
    pub recipient: Address,
    pub token: Address,
    pub amount: i128,
    pub interval: u64,
    pub next_payment: u64,
    pub is_active: bool,
}

Security Features

Allowance-Based: Contract uses token allowances, never holding user funds
Time-Locked: Payments can only execute after designated intervals
Atomic Transactions: All operations are atomic, preventing partial states
Reentrancy Protection: Guard mechanisms prevent reentrancy attacks
Access Control: Role-based permissions for sensitive operations

📁 Project Structure

QuantX/
├── contracts/                  # Soroban Smart Contracts
│   ├── src/
│   │   ├── lib.rs             # Main contract logic
│   │   ├── storage.rs         # Storage definitions
│   │   ├── types.rs           # Custom types
│   │   └── test.rs            # Contract tests
│   ├── Cargo.toml
│   └── README.md
│
├── quantx-sdk/                 # TypeScript SDK
│   ├── src/
│   │   ├── contract/          # Contract interaction layer
│   │   ├── wallet/            # Wallet connection handlers
│   │   ├── polling/           # Transaction status polling
│   │   └── types/             # TypeScript definitions
│   ├── package.json
│   └── README.md
│
├── quantx-bot/                 # Telegram Bot
│   ├── src/
│   │   ├── bot.ts             # Bot initialization
│   │   ├── commands/          # Command handlers
│   │   ├── scenes/            # Conversation flows
│   │   └── utils/             # Helper functions
│   ├── package.json
│   └── README.md
│
├── web/                        # Next.js Web Dashboard
│   ├── app/
│   │   ├── (dashboard)/       # Dashboard routes
│   │   ├── api/               # API routes
│   │   └── layout.tsx
│   ├── components/            # React components
│   ├── lib/                   # Utilities
│   ├── public/                # Static assets
│   └── package.json
│
├── keeper/                     # Automated Executor
│   ├── src/
│   │   ├── monitor.ts         # Subscription monitoring
│   │   ├── executor.ts        # Payment execution
│   │   └── config.ts          # Configuration
│   └── package.json
│
├── docs/                       # Documentation
├── scripts/                    # Deployment scripts
├── .github/                    # GitHub workflows
└── README.md                   # This file

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18 or higher)
Rust (v1.70 or higher)
Stellar CLI (Soroban)
Git
Freighter Wallet (Browser extension)

Installation

1. Clone the Repository

git clone https://github.com/iamomm-hack/QuantX.git
cd QuantX

2. Install Stellar CLI

# macOS
brew install stellar-cli

# Linux
cargo install --locked stellar-cli --features opt

# Verify installation
stellar --version

3. Configure Stellar Network

# Add Testnet network
stellar network add \
  --global testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

# Generate a test identity
stellar keys generate alice --network testnet

# Fund the account (get test XLM)
stellar keys fund alice --network testnet

4. Install Dependencies

# Install all workspace dependencies
npm install

# Or install individually
cd web && npm install
cd ../quantx-sdk && npm install
cd ../quantx-bot && npm install
cd ../keeper && npm install

Local Development

1. Build Smart Contracts

cd contracts
stellar contract build

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/quantx_contract.wasm \
  --source alice \
  --network testnet

2. Run Web Dashboard

cd web
cp .env.example .env.local

# Edit .env.local with your contract address
# NEXT_PUBLIC_CONTRACT_ID=CXXXXXXX...

npm run dev

Access at http://localhost:3000

3. Run Telegram Bot

cd quantx-bot
cp .env.example .env

# Edit .env with your bot token
# BOT_TOKEN=your_telegram_bot_token
# CONTRACT_ID=CXXXXXXX...

npm run dev

4. Run Keeper (Executor)

cd keeper
cp .env.example .env

# Configure keeper settings
# PRIVATE_KEY=your_executor_private_key
# CONTRACT_ID=CXXXXXXX...

npm start

📖 Usage Guide

1. Web Dashboard

Creating a Subscription (Merchant/Recipient)

Connect Wallet
- Click "Connect Wallet" and approve Freighter connection
- Ensure you're on Stellar Testnet
Create Subscription Plan
- Navigate to "Create Subscription"
- Fill in details:
  - Amount (e.g., 10 USDC)
  - Interval (e.g., 30 days)
  - Description
- Click "Create Plan"
- Confirm transaction in Freighter
Share Subscription Link
- Copy the generated subscription link
- Share with customers

Subscribing to a Service (Customer/Payer)

Visit Subscription Link
- Open the merchant's subscription link
Review & Approve
- Review subscription details
- Click "Subscribe"
- Approve Token Allowance in Freighter (first time only)
- Confirm subscription creation
Manage Subscriptions
- View active subscriptions in dashboard
- Cancel anytime with one click

2. SDK Integration

Installation

npm install @quantx/sdk

Basic Usage

import { QuantXClient } from '@quantx/sdk';

// Initialize client
const client = new QuantXClient({
  network: 'testnet',
  contractId: 'CXXXXXXX...',
});

// Connect wallet
await client.connectWallet();

// Create subscription
const subscriptionId = await client.createSubscription({
  recipient: 'GXXXXXXX...',
  token: 'USDC_CONTRACT_ADDRESS',
  amount: '10.00',
  interval: 30 * 24 * 60 * 60, // 30 days in seconds
});

// Get subscription details
const subscription = await client.getSubscription(subscriptionId);

// Cancel subscription
await client.cancelSubscription(subscriptionId);

Advanced: Custom Integration

// Listen to subscription events
client.on('payment_executed', (event) => {
  console.log('Payment processed:', event);
});

// Execute payment manually (keeper functionality)
await client.executePayment(subscriptionId);

// Batch operations
const subscriptions = await client.getUserSubscriptions(address);

3. Telegram Bot

Getting Started

Find the Bot
- Search for @QuantXBot on Telegram
- Send /start
Connect Wallet
- Use /connect command
- Scan QR code with Freighter mobile or use deep link
- Approve connection
Commands

/start          - Initialize bot
/connect        - Connect wallet
/subscribe      - Create new subscription
/mysubs         - View your subscriptions
/cancel [id]    - Cancel subscription
/balance        - Check token balances
/help           - Show all commands

Creating a Subscription via Bot

Send /subscribe
Follow the interactive prompts:
- Enter recipient address
- Select token (USDC/XLM)
- Enter amount
- Choose interval (Daily/Weekly/Monthly)
Confirm via deep link
Receive confirmation with subscription ID

🔧 Smart Contract Deployment

Testnet Deployment

# 1. Build the contract
cd contracts
stellar contract build

# 2. Optimize WASM
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/quantx_contract.wasm

# 3. Deploy
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/quantx_contract.optimized.wasm \
  --source alice \
  --network testnet

# 4. Initialize contract (if needed)
stellar contract invoke \
  --id CONTRACT_ID \
  --source alice \
  --network testnet \
  -- initialize \
  --admin GXXXXXXX...

Mainnet Deployment (Future)

# Switch to mainnet network
stellar network add \
  --global mainnet \
  --rpc-url https://soroban-rpc.mainnet.stellar.org:443 \
  --network-passphrase "Public Global Stellar Network ; September 2015"

# Deploy with mainnet source
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/quantx_contract.optimized.wasm \
  --source mainnet-deployer \
  --network mainnet

📚 API Reference

QuantX SDK

Complete SDK documentation available at docs.quantx.fi/sdk

Core Methods

class QuantXClient {
  // Wallet Management
  connectWallet(): Promise<string>
  disconnectWallet(): void
  getAddress(): string
  
  // Subscription Management
  createSubscription(params: CreateSubscriptionParams): Promise<string>
  getSubscription(id: string): Promise<Subscription>
  getUserSubscriptions(address: string): Promise<Subscription[]>
  cancelSubscription(id: string): Promise<void>
  
  // Payment Execution
  executePayment(id: string): Promise<void>
  getPaymentHistory(id: string): Promise<Payment[]>
  
  // Token Operations
  approveToken(token: string, amount: string): Promise<void>
  getAllowance(owner: string, spender: string): Promise<string>
}

REST API (Web Dashboard)

GET    /api/subscriptions/:id          - Get subscription details
POST   /api/subscriptions              - Create subscription
DELETE /api/subscriptions/:id          - Cancel subscription
GET    /api/subscriptions/user/:address - Get user subscriptions
POST   /api/payments/:id/execute       - Execute payment
GET    /api/payments/:id/history       - Get payment history

🔒 Security

Audit Status

✅ Internal security review completed
⏳ Third-party audit: Scheduled Q2 2025
⏳ Bug bounty program: Launching with mainnet

Security Best Practices

Never share your private keys - QuantX never asks for them
Verify contract addresses - Always check official sources
Review allowances - Only approve what you need
Monitor subscriptions - Regularly check active subscriptions
Use hardware wallets - For large-value subscriptions

Reporting Vulnerabilities

If you discover a security vulnerability, please email: security@quantx.fi

We offer rewards for responsible disclosure through our bug bounty program.

🗺️ Roadmap

Phase 1: Foundation (✅ Completed)

Phase 2: Enhancement (🚧 In Progress)

Phase 3: Decentralization (📅 Q2 2025)

Phase 4: Ecosystem (📅 Q3-Q4 2025)

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Development Process

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
Run tests
```
npm test
```

Commit with conventional commits

git commit -m "feat: add amazing feature"

Push and create PR
```
git push origin feature/amazing-feature
```

Contribution Guidelines

Follow the existing code style
Write tests for new features
Update documentation
Use conventional commit messages
Ensure all tests pass

Development Setup

# Install development dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

Stellar Development Foundation for Soroban platform
Freighter Wallet for seamless integration
Community Contributors for feedback and support

Built with ❤️ on Stellar

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
backend		backend
contracts		contracts
executor		executor
my-sdk-test		my-sdk-test
quantx-bot		quantx-bot
quantx-sdk		quantx-sdk
rfi-frontend		rfi-frontend
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

QuantX: Decentralized Recurring Payments Infrastructure for Web3

🎯 Overview

🏆 Key Features

📋 Table of Contents

💡 Use Cases

For SaaS & Content Creators

For DAOs & Employers

For DeFi Protocols

🏗️ System Architecture

Architecture Components

1. User Layer

2. Integration Layer

3. Blockchain Layer

4. Execution Layer

📜 Smart Contract Details

Contract Addresses

Testnet Deployment

Mainnet Deployment

Core Contract Functions

1. create_subscription

2. execute_payment

3. cancel_subscription

4. get_subscription

Security Features

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

1. Clone the Repository

2. Install Stellar CLI

3. Configure Stellar Network

4. Install Dependencies

Local Development

1. Build Smart Contracts

2. Run Web Dashboard

3. Run Telegram Bot

4. Run Keeper (Executor)

📖 Usage Guide

1. Web Dashboard

Creating a Subscription (Merchant/Recipient)

Subscribing to a Service (Customer/Payer)

2. SDK Integration

Installation

Basic Usage

Advanced: Custom Integration

3. Telegram Bot

Getting Started

Creating a Subscription via Bot

🔧 Smart Contract Deployment

Testnet Deployment

Mainnet Deployment (Future)

📚 API Reference

QuantX SDK

Core Methods

REST API (Web Dashboard)

🔒 Security

Audit Status

Security Best Practices

Reporting Vulnerabilities

🗺️ Roadmap

Phase 1: Foundation (✅ Completed)

Phase 2: Enhancement (🚧 In Progress)

Phase 3: Decentralization (📅 Q2 2025)

Phase 4: Ecosystem (📅 Q3-Q4 2025)

🤝 Contributing

Development Process

Contribution Guidelines

Development Setup

📄 License

🌟 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Packages