🚀 DeFi Quest

Passkey-Enabled DeFi Protocol Onboarding Platform on Stellar

DeFi Quest is a production-ready onboarding platform that introduces users to the Stellar DeFi ecosystem through interactive quests and passkey-enabled smart contract wallets. Users complete engaging tasks involving XLM airdrops, token swaps, and liquidity provision, ultimately earning completion NFTs that serve as their DeFi community certificates.

✨ Features

🔐 Passkey Smart Wallets - Device biometric authentication with gasless transactions
⚡ Admin-Sponsored Transactions - Seamless user experience with zero gas fees
🎯 Progressive Quest System - XLM Airdrop → Swap → Liquidity → NFT Certificate
🔄 Soroswap Integration - Direct DEX integration on Stellar testnet
📊 Real-time Progress Tracking - Database-backed quest completion monitoring
📱 Mobile-Optimized - Responsive design with passkey support on mobile devices
🛡️ Enterprise Security - Built on Stellar blockchain with Soroban smart contracts
🚀 Production Ready - Vercel-deployable with comprehensive monitoring

🎯 Quest System

Available Quests

Quest	Description	Technology	Status
Quest 1: XLM Airdrop	Claim native XLM to fund your DeFi journey	Smart Contract Airdrop	✅ Live
Quest 2: Token Swap	Execute swaps on Soroswap DEX	DEX Integration	✅ Live
Quest 3: Liquidity Provision	Add liquidity to earn trading fees	Liquidity Pools	✅ Live
Quest 4: Completion NFT	Mint your DeFi onboarding certificate	Dynamic NFTs	✅ Live

Passkey Smart Wallet Authentication

Device Biometrics: Face ID, Touch ID, or Windows Hello authentication
Gasless Transactions: All transactions sponsored by admin accounts
Mobile Native: Optimized for mobile browsers with WebAuthn support
Self-Custody: Users maintain full control with passkey authentication
Cross-Device: Passkeys sync across user's devices via platform providers

User Journey

Create Passkey Wallet: Use device biometrics to create smart contract wallet
Complete Quest 1: Claim XLM airdrop to fund wallet
Execute Swaps: Trade tokens on Soroswap (XLM ↔ USDC, etc.)
Provide Liquidity: Add liquidity to pools and earn fees
Mint NFT: Complete all quests to earn completion certificate

🚀 Quick Start

Prerequisites

Node.js 18+ and Yarn
PostgreSQL Database (Neon, PlanetScale, or local)
Stellar CLI v23.0.0+ (for smart contract deployment)
HTTPS Environment (for passkey authentication)

Installation

Clone and install

git clone https://github.com/your-username/defi-quest.git
cd defi-quest
yarn install

Configure environment

cp .env.local.example .env.local
# Edit .env.local with your configuration

Run setup script

# Complete system setup with smart contract deployment
npx tsx scripts/setup-system.ts

Start development with HTTPS (required for passkeys)
```
yarn dev-https
```
Open app Navigate to https://localhost:3000

🏗️ Architecture

graph TD
    subgraph "Frontend (Next.js 15)"
        A[Quest Navigator] --> B[Passkey Wallet Provider]
        A --> C[Quest Components]
        B --> D[WebAuthn Integration]
        B --> E[Smart Wallet SDK]
    end

    subgraph "Backend API (Next.js)"
        F[API Routes] --> G[Transaction Service]
        F --> H[PostgreSQL Database]
        F --> I[Launchtube Client]
        G --> J[Quest Monitoring]
    end

    subgraph "Stellar Testnet"
        K[XLM Airdrop Contract]
        L[Quest NFT Contract] 
        M[Soroswap DEX]
        N[Passkey Smart Wallets]
    end

    subgraph "External Services"
        O[PostgreSQL/Neon DB]
        P[Launchtube API]
        Q[Mercury Indexer]
        R[Soroswap API]
    end

    A --> F
    G --> K
    G --> L
    G --> M
    I --> P
    H --> O
    J --> Q
    C --> R
    D --> N

🔧 Development

Project Structure

src/
├── app/                    # Next.js 15 App Router
│   ├── api/               # API endpoints
│   │   ├── claim-airdrop/ # XLM airdrop claiming
│   │   ├── execute-swap/  # Token swap execution
│   │   ├── execute-liquidity/ # Liquidity provision
│   │   ├── execute-nft-mint/ # NFT minting
│   │   ├── deploy-passkey-wallet/ # Smart wallet deployment
│   │   └── quest-status/  # Quest progress tracking
│   ├── quest/             # Quest pages  
│   └── page.tsx           # Landing page
├── components/            # React components
│   ├── quest-navigator/   # Quest navigation system
│   ├── ui/               # Reusable UI components
│   ├── AirdropClaim.tsx  # Airdrop quest component
│   ├── SoroswapQuest.tsx # Swap quest component
│   ├── LiquidityQuest.tsx # Liquidity quest component
│   ├── CompletionNFTQuest.tsx # NFT quest component
│   ├── WalletProvider.tsx # Passkey wallet provider
│   └── WalletButton.tsx  # Wallet connection UI
├── hooks/                # Custom React hooks
│   ├── useQuests.ts      # Quest state management
│   ├── useWalletBalances.ts # Balance tracking
│   └── useTransactionExecution.ts # Transaction handling
├── lib/                  # Core utilities
│   ├── config.ts         # Centralized configuration
│   ├── database.ts       # PostgreSQL operations
│   ├── stellar.ts        # Stellar SDK utilities
│   ├── wallet.ts         # Passkey wallet integration
│   ├── soroswap-api.ts   # Soroswap integration
│   ├── launchtube-client.ts # Gasless transactions
│   └── transaction-service.ts # Transaction coordination
├── contracts/            # Soroban smart contracts
│   ├── airdrop/          # XLM airdrop contract
│   └── quest_nft/        # Completion NFT contract
├── scripts/              # System administration scripts
└── types/                # TypeScript type definitions

Available Scripts

# Development
yarn dev          # Start dev server
yarn dev-https    # Start dev server with HTTPS (required for passkeys)
yarn build        # Build for production
yarn start        # Start production server
yarn lint         # Run ESLint

# System Setup
npx tsx scripts/setup-system.ts           # Complete system setup
npx tsx scripts/setup-system.ts --verbose # Detailed setup output

# Testing & Monitoring
npx tsx scripts/test-claim-flow.ts        # Test airdrop claim flow
npx tsx scripts/check-user-claims.ts      # Monitor user claims
npx tsx scripts/verify-airdrop-transfers.ts # Verify contract transfers
npx tsx scripts/airdrop-monitoring-dashboard.ts # Real-time monitoring

Scripts Directory

The /scripts directory contains comprehensive administration and testing tools:

Script	Purpose	Usage
`setup-system.ts`	Complete system deployment	`npx tsx scripts/setup-system.ts`
`test-claim-flow.ts`	Test airdrop claiming	`npx tsx scripts/test-claim-flow.ts`
`check-user-claims.ts`	Monitor user activity	`npx tsx scripts/check-user-claims.ts`
`verify-airdrop-transfers.ts`	Audit contract transfers	`npx tsx scripts/verify-airdrop-transfers.ts`
`airdrop-monitoring-dashboard.ts`	Real-time monitoring	`npx tsx scripts/airdrop-monitoring-dashboard.ts`
`database-blockchain-reconciliation.ts`	Data consistency check	`npx tsx scripts/database-blockchain-reconciliation.ts`
`soroswap-api.js`	Soroswap API testing	`node scripts/soroswap-api.js`
`test-swap-api.js`	Swap functionality test	`node scripts/test-swap-api.js`

📡 API Reference

Quest Status

POST /api/quest-status
Content-Type: application/json

{
  "userAddress": "GDVB7VSXAR2NG5E6QPVDHYJLSJK2T3MTEKVKYCSTMHTD43EW3H2QY6RX"
}

Deploy Passkey Wallet

POST /api/deploy-passkey-wallet
{
  "publicKey": "04a1b2c3...",
  "signerId": "user_passkey_id"
}

Claim XLM Airdrop

POST /api/claim-airdrop
{
  "userAddress": "GDVB7VSXAR2NG5E6QPVDHYJLSJK2T3MTEKVKYCSTMHTD43EW3H2QY6RX",
  "signedXDR": "AAAAAgAAAAC...",
  "isSmartWallet": true
}

Execute Token Swap

POST /api/execute-swap
{
  "userAddress": "GDVB7VSXAR2NG5E6QPVDHYJLSJK2T3MTEKVKYCSTMHTD43EW3H2QY6RX",
  "tokenA": "XLM",
  "tokenB": "USDC",
  "amount": "1000000",
  "isSmartWallet": true
}

Execute Liquidity Provision

POST /api/execute-liquidity
{
  "userAddress": "GDVB7VSXAR2NG5E6QPVDHYJLSJK2T3MTEKVKYCSTMHTD43EW3H2QY6RX",
  "tokenA": "XLM",
  "tokenB": "USDC",
  "amountA": "5000000",
  "amountB": "5000000",
  "isSmartWallet": true
}

Mint Completion NFT

POST /api/execute-nft-mint
{
  "userAddress": "GDVB7VSXAR2NG5E6QPVDHYJLSJK2T3MTEKVKYCSTMHTD43EW3H2QY6RX",
  "isSmartWallet": true
}

🧪 Testing

Setup Test Environment

# Run complete system setup
npx tsx scripts/setup-system.ts --verbose

# Test passkey wallet functionality
npx tsx scripts/test-smart-contract-builder.ts

# Test airdrop claim flow
npx tsx scripts/test-claim-flow.ts

Testing with Passkey Wallets

Use HTTPS development server
```
yarn dev-https
```
Create passkey wallet
- Visit https://localhost:3000
- Use device biometrics to create wallet
- Verify smart contract deployment
Complete quest flow
- Complete Quest 1: Claim XLM airdrop
- Complete Quest 2: Execute token swap
- Complete Quest 3: Add liquidity
- Complete Quest 4: Mint completion NFT

Monitor system health

npx tsx scripts/airdrop-monitoring-dashboard.ts

🚢 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy with environment variables
vercel --prod

Environment Variables

Required for production:

# ==============================================
# DATABASE CONFIGURATION
# ==============================================
POSTGRES_URL=your_postgresql_connection_string

# ==============================================
# STELLAR NETWORK CONFIGURATION
# ==============================================
NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_BASE_URL=https://your-domain.vercel.app

# ==============================================
# TOKEN ADDRESSES
# ==============================================
NEXT_PUBLIC_USDC_TOKEN_ADDRESS=CBBHRKEP5M3NUDRISGLJKGHDHX3DA2CN2AZBQY6WLVUJ7VNLGSKBDUCM
NEXT_PUBLIC_XLM_TOKEN_ADDRESS=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC
NEXT_PUBLIC_XTAR_TOKEN_ADDRESS=CBGXH3YN3O3G75NPL3WNAOA3TXWOQOBVGOOIPZMERO756VOJRCOXUKFE

# ==============================================
# CONTRACT ADDRESSES (Set by setup script)
# ==============================================
NEXT_PUBLIC_AIRDROP_ADDRESS=your_airdrop_contract_address
NEXT_PUBLIC_SAGA_NFT_ADDRESS=your_nft_contract_address
NEXT_PUBLIC_SOROSWAP_ROUTER_ADDRESS=your_soroswap_router_address

# Quest Contract Addresses
NEXT_PUBLIC_QUEST_PROGRESS_CONTRACT_ID=your_quest_progress_contract
NEXT_PUBLIC_AIRDROP_CONTRACT_ID=your_airdrop_contract
NEXT_PUBLIC_SWAP_QUEST_CONTRACT_ID=your_swap_quest_contract
NEXT_PUBLIC_LIQUIDITY_QUEST_CONTRACT_ID=your_liquidity_quest_contract
NEXT_PUBLIC_QUEST_NFT_CONTRACT_ID=your_quest_nft_contract

# ==============================================
# ADMIN CONFIGURATION
# ==============================================
STELLAR_ADMIN_SECRET_KEY=your_admin_secret_key
ADMIN_PRIVATE_KEY=your_admin_private_key
AIRDROP_ADMIN_SECRET_KEY=your_admin_secret_key
STELLAR_ADMIN_PUBLIC_KEY=your_admin_public_key
NEXT_PUBLIC_STELLAR_ADMIN_PUBLIC_KEY=your_admin_public_key

# Setup Script Configuration
STELLAR_ADMIN_IDENTITY=defi-quest-deployer
STELLAR_CLI_PATH=~/.cargo/bin/stellar
DEPLOYMENT_NETWORK=testnet
DEFAULT_XLM_AMOUNT=100000000

# ==============================================
# PASSKEY WALLET CONFIGURATION
# ==============================================
NEXT_PUBLIC_WALLET_WASM_HASH=your_wallet_wasm_hash

# Launchtube Configuration (Gasless Transactions)
NEXT_PUBLIC_LAUNCHTUBE_URL=https://testnet.launchtube.xyz
LAUNCHTUBE_API_URL=https://testnet.launchtube.xyz
LAUNCHTUBE_API_TOKEN=your_launchtube_jwt_token
PRIVATE_LAUNCHTUBE_JWT=your_private_launchtube_jwt
LAUNCHTUBE_CREDITS_THRESHOLD=10000

# Mercury Configuration (Smart Wallet Indexing)
NEXT_PUBLIC_MERCURY_URL=https://testnet.mercurydata.app
PRIVATE_MERCURY_JWT=your_mercury_jwt_token

# ==============================================
# SOROSWAP API CONFIGURATION
# ==============================================
NEXT_PUBLIC_SOROSWAP_API_URL=https://api.soroswap.finance
NEXT_PUBLIC_SOROSWAP_API_KEY=your_soroswap_api_key

🔍 Troubleshooting

Common Issues

Passkey creation fails:

Ensure you're using HTTPS (yarn dev-https)
Check if device supports WebAuthn/passkeys
Try different browser (Chrome/Safari recommended)
Verify certificate is trusted

Quest completion not detected:

Verify all contract addresses in environment variables
Check PostgreSQL database connection
Ensure admin keys are properly configured
Monitor API logs for transaction errors

Smart wallet deployment fails:

Check Launchtube API credits and JWT token
Verify admin secret key has sufficient XLM
Ensure Mercury indexer JWT is valid
Check network connectivity to Stellar RPC

Setup script failures:

Ensure Stellar CLI v23.0.0+ is installed
Verify admin identity is configured: stellar keys generate defi-quest-deployer --network testnet
Check all environment variables are set
Run setup with --verbose flag for detailed logs

Debug Information

Check these resources when troubleshooting:

Browser developer console for WebAuthn errors
Network tab for failed API requests
Stellar Expert Testnet for transaction verification
PostgreSQL logs for database issues
Application logs in terminal where yarn dev-https is running
Launchtube dashboard for gasless transaction credits
Mercury dashboard for smart wallet indexing status

🛡️ Security

Passkey Security: WebAuthn-based authentication with device biometrics
Environment Protection: Sensitive keys never exposed to client-side code
Admin Protection: Admin functions protected by secret keys and API tokens
Input Validation: All API endpoints validate and sanitize inputs
Gasless Security: Admin-sponsored transactions use secure key management
Database Security: PostgreSQL with parameterized queries to prevent injection
Smart Contract Security: Soroban contracts with proper access controls
HTTPS Enforcement: Required for passkey authentication

🔗 Resources

Stellar Documentation
Soroban Smart Contracts
Soroswap DEX | API Docs
Passkey Kit - Smart contract wallet framework
WebAuthn Guide - Passkey authentication
Launchtube - Gasless transaction service
Mercury - Stellar data indexing
Stellar Expert - Blockchain explorer

🤝 Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Development Guidelines

Follow TypeScript best practices
Use ESLint for code quality
Test thoroughly on Stellar testnet
Ensure passkey compatibility across devices
Maintain HTTPS development environment

📄 License

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

🏆 Acknowledgments

Stellar Development Foundation for blockchain infrastructure and Soroban
Soroswap Team for the DEX platform and comprehensive API
Passkey Kit Team for smart contract wallet framework
Launchtube for gasless transaction infrastructure
Next.js Team for the React framework and App Router

Built for the Stellar DeFi ecosystem with passkey-enabled smart wallets

Start onboarding DeFi users today at https://localhost:3000

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
contracts		contracts
docs		docs
public		public
scripts		scripts
src		src
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.vercelignore		.vercelignore
CLAUDE.md		CLAUDE.md
Cargo.toml		Cargo.toml
README.md		README.md
cleanup-localstorage.js		cleanup-localstorage.js
components.json		components.json
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

🚀 DeFi Quest

✨ Features

🎯 Quest System

Available Quests

Passkey Smart Wallet Authentication

User Journey

🚀 Quick Start

Prerequisites

Installation

🏗️ Architecture

🔧 Development

Project Structure

Available Scripts

Scripts Directory

📡 API Reference

Quest Status

Deploy Passkey Wallet

Claim XLM Airdrop

Execute Token Swap

Execute Liquidity Provision

Mint Completion NFT

🧪 Testing

Setup Test Environment

Testing with Passkey Wallets

🚢 Deployment

Vercel (Recommended)

Environment Variables

🔍 Troubleshooting

Common Issues

Debug Information

🛡️ Security

🔗 Resources

🤝 Contributing

Development Guidelines

📄 License

🏆 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages