Skip to main content

Architecture Overview

Loyalteez uses a distributed Cloudflare Worker architecture to provide seamless, gasless blockchain rewards.

System Architecture​

Event Tracking Flow​

Gasless Transaction Flow​

Perk Claiming Flow​

Payment & LTZ Minting Flow​

OAuth Pregeneration Flow (Idempotent)​

Component Breakdown​

1. JavaScript SDK​

Purpose: Capture user events and send to Event Handler

Key Features:

  • Auto-detection of form submissions
  • Email extraction
  • Event deduplication
  • Configurable event rules

Integration:

<script src="https://api.loyalteez.app/sdk.js"></script>
<script>
  Loyalteez.init('YOUR_BRAND_ID');
</script>

2. Event Handler Worker​

Purpose: Process events and distribute LTZ rewards

Endpoints:

  • POST /loyalteez-api/manual-event - Track events
  • POST /loyalteez-api/checkout - Stripe checkout
  • GET /loyalteez-api/debug - Health check

Key Functions:

  • Event validation
  • User wallet creation (via Privy)
  • LTZ distribution
  • Event logging

3. Gas Relayer Worker​

Purpose: Enable gasless transactions for users

Endpoints:

  • POST /relay - Execute gasless transaction

Key Features:

  • Privy authentication
  • Contract whitelisting
  • Rate limiting (35 tx/hour/user)
  • EIP-2612 permit support
  • Gas budget protection

4. Pregeneration Worker ✨ Production Ready​

Purpose: Create wallets for users before they log in (OAuth pregeneration)

Domain: register.loyalteez.app

Endpoints:

  • POST /loyalteez-api/pregenerate-user - Pregenerate OAuth wallet

Key Features:

  • Idempotent - Safe to call multiple times (returns existing wallet)
  • Server-side Privy integration - No credentials needed from developers
  • 8 OAuth providers supported - Discord, Twitter, GitHub, Google, Telegram, Spotify, Instagram, TikTok
  • Real OAuth validation - Rejects test/fake credentials for security
  • Deterministic - Same OAuth ID = same wallet (always)
  • Supabase event logging - Full audit trail
  • created_new flag - Track new vs. existing users

Use Cases:

  • Discord bots rewarding users before they log in
  • Twitter engagement campaigns
  • GitHub contribution rewards
  • Multi-platform user onboarding
  • Reward failsafe systems (idempotent by design)

Security:

  • Requires valid brand_id (controlled access)
  • Validates credentials with actual OAuth providers
  • Rate limited (100 requests/min per brand)
  • Server-side only (no frontend exposure)

Learn More: OAuth Pregeneration Guide | API Reference

Note: The Pregeneration Worker only creates/retrieves wallets - it does NOT send LTZ tokens. To send rewards, you need to either:

  1. Use the Event Handler API to create reward distributions
  2. Use your own LTZ transfer mechanism
  3. Use the Reward Processor (scheduled worker that processes pending rewards)

5. Stripe Mint Worker​

Purpose: Convert fiat payments to LTZ credits

Key Functions:

  • Stripe webhook handling
  • Payment verification
  • LTZ minting
  • Balance updates

Security Model​

Data Flow​

Network Architecture​

All Workers are deployed on Cloudflare's global edge network, providing:

  • 🌍 Global Distribution - Low latency worldwide
  • ⚡ Auto-scaling - Handles traffic spikes automatically
  • 🔒 DDoS Protection - Built-in protection
  • 📊 Analytics - Real-time metrics

Blockchain: Soneium Mainnet (Chain ID: 1868)

Database: Supabase (PostgreSQL with RLS)

Auth: Privy (Smart Account Wallets)

Key URLs​

Mainnet (Production)​

ServiceURLPurpose
SDKapi.loyalteez.app/sdk.jsEvent tracking
Event Handlerapi.loyalteez.app/loyalteez-api/*Backend API
Gas Relayerrelayer.loyalteez.app/relayGasless transactions
Pregenerationregister.loyalteez.app/loyalteez-api/pregenerate-userOAuth wallet creation
Partner Portalpartners.loyalteez.appDashboard

Testnet (Testing)​

ServiceURLPurpose
SDKapi.loyalteez.xyz/sdk.jsEvent tracking (testnet)
Event Handlerapi.loyalteez.xyz/loyalteez-api/*Backend API (testnet)
Gas Relayerrelayer.loyalteez.xyz/relayGasless transactions (testnet)
Pregenerationregister.loyalteez.xyz/loyalteez-api/pregenerate-userOAuth wallet creation (testnet)
Partner Portalpartners.loyalteez.xyzDashboard (testnet)

📚 Learn More: See the Testnet Guide for complete testnet documentation.

Contract Addresses​

Soneium Mainnet (Production)​

ContractAddress
Loyalteez Token0x5242b6DB88A72752ac5a54cFe6A7DB8244d743c9
PerkNFT0x6ae30d6Dcf3e75456B6582b057f1Bf98A90F2CA0
PointsSale0x5269B83F6A4E31bEdFDf5329DC052FBb661e3c72

Soneium Minato Testnet (Testing)​

ContractAddress
Loyalteez Token0x8C894048a1313Df870f293a6Db6E744B244F6cf0
PerkNFT0x4204EDEa4A7bE70f544bfe8BEFA8C43F3C198B1b
PointsSale0x5121F2f9D59E558a2aE83EE31111DEF781923de2
USDC0xE9A198d38483aD727ABC8b0B1e16B2d338CF0391

⚠️ Important: Testnet contracts are separate from mainnet. Testnet tokens have no real value. See Testnet Guide for details.

Performance Characteristics​

  • Event Processing: < 200ms average
  • LTZ Distribution: < 3 seconds
  • Gasless Transactions: < 5 seconds
  • SDK Load Time: < 50ms
  • Global Availability: 99.9% uptime

Scalability​

The Worker architecture provides:

  • Infinite horizontal scaling via Cloudflare edge
  • No infrastructure management required
  • Pay-per-request pricing model
  • Zero cold starts (Workers are always warm)

Next Steps​

Last updated on