Skip to main content

Architecture Overview

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

System Architecture​

System Architecture

Event Tracking Flow​

Event Tracking Flow

Gasless Transaction Flow​

Gasless Transaction Flow

Perk Claiming Flow​

Perk Claiming Flow

Payment & RSNC Minting Flow​

Payment and RSNC Minting Flow

OAuth Pregeneration Flow (Idempotent)​

OAuth Pregeneration Flow

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.rsnc.network/sdk.js"></script>
<script>
  Resonance.init('YOUR_BRAND_ID');
</script>

2. Event Handler Worker​

Purpose: Process events and distribute RSNC rewards

Endpoints:

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

Key Functions:

  • Event validation
  • User wallet creation (via Privy)
  • RSNC 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​

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

Domain: register.rsnc.network

Endpoints:

  • POST /resonance-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 RSNC tokens. To send rewards, you need to either:

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

5. Stripe Mint Worker​

Purpose: Convert fiat payments to RSNC credits

Key Functions:

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

6. Reward Agent​

Purpose: AI-powered loyalty agent for program management and agentic commerce

Domain: agent.rsnc.network

Access Points:

  • POST /mcp — MCP Streamable HTTP tool calls
  • GET/POST/PATCH /api/v1/* — REST API (45 endpoints)
  • POST /converse — Natural language queries
  • POST /tasks/send — A2A protocol
  • CLI: npm install -g @resonance/cli

Key Features:

  • 45 tools across 17 modules (discovery, brand, user, reward, perks, leaderboard, growth, onboarding, analytics, management, agent rewards, comparison, commerce routing, recommendations, intelligence, network intelligence, suggestions)
  • Four access points: MCP, REST API, CLI, A2A
  • HMAC-SHA256 + RFC 9421 Ed25519 + OAuth 2.0 authentication
  • Cloudflare KV rate limiting
  • Workers AI for intelligence, suggestions, and converse
  • ERC-8004, A2A, and UCP protocol support

Learn More: Reward Agent Documentation

7. Shopify App​

Purpose: Embedded Shopify app for merchant loyalty programs

Domain: rsnc-shopify-app.rsnc.network

Key Features:

  • Earning rules (credits per dollar, product filters, time windows)
  • Webhook processing (orders/create, customers/create)
  • Storefront widget via App Proxy
  • Discount code generation for perk redemptions
  • D1 database for merchant data

Learn More: Shopify App Documentation

Security Model​

Security Model

Data Flow​

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.rsnc.network/sdk.jsEvent tracking
Event Handlerapi.rsnc.network/resonance-api/*Backend API
Gas Relayerrelayer.rsnc.network/relayGasless transactions
Pregenerationregister.rsnc.network/resonance-api/pregenerate-userOAuth wallet creation
Partner Portalpartners.rsnc.networkBrand dashboard
Perks Marketplaceperks.rsnc.networkConsumer perk discovery & claiming
Reward Agent (MCP)agent.rsnc.network/mcpAI agent (MCP over HTTP)
Reward Agent (REST)agent.rsnc.network/api/v1/*REST API (45 endpoints)
Shared Servicesservices.rsnc.networkStreaks, leaderboards, achievements, perks
Shopify Apprsnc-shopify-app.rsnc.networkShopify embedded app

Testnet (Testing)​

ServiceURLPurpose
SDKapi.resonance.xyz/sdk.jsEvent tracking (testnet)
Event Handlerapi.resonance.xyz/resonance-api/*Backend API (testnet)
Gas Relayerrelayer.resonance.xyz/relayGasless transactions (testnet)
Pregenerationregister.resonance.xyz/resonance-api/pregenerate-userOAuth wallet creation (testnet)
Partner Portalpartners.resonance.xyzBrand dashboard (testnet)
Perks Marketplaceperks.resonance.xyzConsumer perk discovery (testnet)

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

Contract Addresses​

Soneium Mainnet (Production)​

ContractAddress
Resonance Token0x4183CD8fE04bA0f10Ca83cf9E76e58ef8dB7cb33
PerkNFT0x997f05E7447Fdde75d47eBb12D4D6C65013AA0Da
PointsSale0x02939031C36637a4c46d86832D7015a2F350cc7D

Soneium Minato Testnet (Testing)​

ContractAddress
Resonance 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
  • RSNC 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