Token Gate

The RitoSwap Token Gate represents a sophisticated implementation of blockchain-based access control, combining on-chain NFT ownership verification with off-chain content delivery. This system creates an exclusive experience for Colored Key NFT holders, granting them one-time access to submit a message and enjoy crypto-themed music created by Rito Rhymes.

System Overview

The token gate operates as a multi-layered authentication and content delivery system that seamlessly bridges Web3 ownership with Web2 content management. At its core, the system verifies NFT ownership through cryptographic signatures, tracks usage through a hybrid blockchain-database architecture, and delivers exclusive content through secure, time-limited access mechanisms.

Core Architecture Components

The token gate system orchestrates several interconnected services:

User Journey

Understanding the token gate requires following the complete user journey from initial connection to final message submission. Each step involves specific technical components working in concert to create a seamless experience.

if (isSiweEnabled()) {
  // SIWE flow with nonce generation
  const nonceResponse = await fetch('/api/nonce')
  const { nonce } = await nonceResponse.json()
  message = createSiweMessage({ address, nonce, statement })
} else {
  // Legacy flow with timestamp
  const timestamp = Date.now()
  message = `I own key #${tokenId}\nTimestamp: ${timestamp}`
}

if (isMobileDevice() && connector?.id === 'walletConnect') {
  openWallet()
}

UI Feedback Systems

The token gate implements sophisticated user interface feedback mechanisms that guide users through complex blockchain interactions while providing clear recovery paths when issues arise.

Processing Modal

During transaction signing and verification phases, the ProcessingModal component provides essential visual feedback and interaction options. This modal serves multiple critical functions in the user experience. It displays clear instructions about opening wallet applications or extensions, offers a cancel button that allows users to reset the UI state if transactions become stuck, and on mobile devices, presents an “Open Wallet” button that triggers deep-linking to the connected wallet application.

The ProcessingModal appears automatically during both the initial gate unlock signature and the message submission signature, ensuring users always understand the current state of their interaction with the blockchain.

Rate Limiting Feedback

When users exceed API rate limits, the system displays a dedicated modal through the showRateLimitModal function rather than generic error messages. This modal provides specific information about the rate limit including the maximum allowed requests, remaining requests in the current window, and exact time until the rate limit resets. This transparency helps users understand the system’s protective measures while providing clear guidance on when they can retry their action.

Mobile Wallet Deeplinking

The token gate includes specific optimizations for mobile users, particularly those using WalletConnect. When the system detects a mobile device during signature requests, it automatically triggers the wallet deep-linking flow to switch over to the user’s mobile wallet app to complete required actions:

if (isMobileDevice() && connector?.id === 'walletConnect') {
  openWallet()
}

This seamless integration eliminates the confusion mobile users often experience when trying to locate and open their wallet application manually during transaction signing.

Authentication Flows

The token gate implements a sophisticated dual-authentication system that adapts based on infrastructure availability, providing flexibility without compromising security.

I own key #${tokenId}
Timestamp: ${timestamp}

Content Delivery Architecture

The gated content system implements a server-side protection model where exclusive content never exists in client-side code until authentication is verified. This architecture ensures that content remains truly exclusive to authenticated token holders.

Server-Side Content Assembly

The Gated Content Library orchestrates the assembly of multiple content components:

• Gated Content Package
  • welcomeText
  • textSubmissionAreaHtml
  • audioData
  • styles
  • script

Each component serves a specific purpose in creating the complete gated experience:

• Welcome Text: Contextualizes the exclusive area and explains the one-time message submission
• Submission Form: HTML structure for the message input and submission button
• Audio Data: Configuration for the exclusive music player, including R2 signed URLs
• Styles: Custom CSS creating the cyberpunk aesthetic
• Script: Client-side JavaScript handling form submission

Audio Streaming with R2

The exclusive crypto-themed music leverages Cloudflare R2 for secure content delivery:

// Server-side URL generation
const audioUrl = await generateSignedAudioUrl(3600) // 1-hour expiration
 
// Client receives time-limited URL
audioData: {
  audioSrc: "https://account.r2.cloudflarestorage.com/bucket/HitMeBitcoin.mp3?X-Amz-Signature=..."
}

The R2 Storage Library handles:

• S3-compatible signed URL generation
• Configurable expiration times
• Graceful error handling for audio unavailability

Content Injection Security

The GatedContentRenderer component safely injects server-provided content:

useEffect(() => {
  // Inject styles once
  const styleEl = document.createElement("style")
  styleEl.textContent = content.styles
  document.head.appendChild(styleEl)
  
  // Expose submission handler
  window.handleGatedSubmission = onSubmit
  
  // Inject HTML content
  containerRef.current.innerHTML = content.textSubmissionAreaHtml
  
  // Execute script in controlled context
  const runner = new Function(content.script)
  runner()
}, [content, onSubmit])

Usage Tracking System

The token gate implements a sophisticated hybrid tracking system that combines blockchain immutability with database efficiency. This design enables gas-free usage tracking while maintaining the security guarantees of blockchain ownership.

Database Architecture

The Prisma database layer maintains network-isolated tables for each supported blockchain:

State Synchronization

The system maintains consistency between on-chain and off-chain state through multiple touchpoints:

1. Initial Check: Token Status API queries both database and blockchain
2. Usage Recording: Verify Token Gate API marks tokens as used
3. Real-time Updates: Frontend polling ensures UI reflects current state

Usage Flow

Notification System Integration

The token gate leverages RitoSwap’s dual notification system to ensure users remain informed throughout their journey. The system combines ephemeral toast notifications for immediate in-app feedback with persistent browser notifications for critical events.

Notification Triggers

The token gate fires specific notifications at key moments in the user journey. When users successfully unlock the gate, the system triggers NFTNotifications.gateUnlocked(), displaying “Access granted to the token gate” through both toast and browser notifications. After successful message submission, NFTNotifications.messageRecorded() confirms “Your message has been recorded and your key has been used.”

These notifications work in concert with the visual feedback provided by the UI components, creating multiple layers of confirmation that eliminate any ambiguity about action outcomes. The notification system respects user preferences through environment configuration while maintaining toast notifications as essential UI feedback that remains always active.

Browser Notification Management

Browser notifications extend the token gate’s communication beyond the active browser context. The system requests notification permissions at natural interaction points, such as during initial wallet connection, ensuring users understand the value of notifications without feeling pressured. All notifications include the RitoSwap favicon for brand recognition and auto-dismiss after 5 seconds to prevent notification center clutter.

Account Management

The token gate implements sophisticated account switching logic that maintains data consistency when users change wallet accounts while on the gate page.

Account Switching Behavior

When the system detects an account change, it initiates a carefully orchestrated transition process. The current gated content is cleared and all UI states reset to prevent data leakage between accounts. The system then triggers a data refresh to fetch the new account’s NFT ownership status and usage information. During this transition, a loading state prevents user interaction until the new account data is fully loaded.

This process ensures that users always see accurate information for their current account, preventing confusion that could arise from cached data belonging to a previous account. The transition includes a subtle animation that acknowledges the account change without disrupting the user experience.

State Cleanup on Disconnect

When users disconnect their wallet entirely, the token gate performs comprehensive cleanup to ensure security and privacy. All gated content is immediately removed from the DOM, authentication states are reset to their initial values, and any pending transactions or signatures are cancelled. This thorough cleanup prevents any residual data from remaining accessible after disconnection.

API Endpoints Integration

The token gate orchestrates multiple API endpoints to create its complete functionality. Each endpoint serves a specific purpose in the authentication and content delivery pipeline.

Endpoint Orchestration

The endpoints work together in a carefully choreographed sequence:

// 1. Initial state check (automatic polling)
const statusResponse = await fetch(`/api/token-status/${tokenId}`)
 
// 2. Authentication flow (user-initiated)
const nonceResponse = await fetch('/api/nonce')
const gateResponse = await fetch('/api/gate-access', { method: 'POST' })
 
// 3. Message submission (within gated area)
const verifyResponse = await fetch('/api/verify-token-gate', { method: 'POST' })
 
// Note: The token status endpoint only supports GET requests
// Database updates happen server-side during verify-token-gate processing

Notification Pipeline

The token gate system implements a flexible notification architecture that adapts to different deployment scenarios and scale requirements.

USE_CLOUDFLARE_WORKER=false
BREVO_API_KEY=your-api-key
SENDER_EMAIL=noreply@ritoswap.com
RECEIVER_EMAIL=admin@ritoswap.com

USE_CLOUDFLARE_WORKER=true
CLOUDFLARE_WORKER_URL=https://your-worker.workers.dev

Email Content Structure

Regardless of delivery method, notifications maintain consistent formatting:

Subject: Gated Msg by 0x1234...5678
 
<div style="background: #0a0f1b; color: white; padding: 20px;">
  <h2>New Token Gate Submission</h2>
  <p><strong>Token ID:</strong> 42</p>
  <p><strong>Address:</strong> 0x1234567890123456789012345678901234567890</p>
  <p><strong>Timestamp:</strong> March 15, 2024 10:30 AM</p>
  <div style="background: #1a1f2b; padding: 15px; margin-top: 20px;">
    <p><strong>Message:</strong></p>
    <p>User's submitted message content here...</p>
  </div>
</div>

Configuration and Deployment

The token gate system’s modular architecture allows for flexible deployment configurations based on infrastructure availability and scale requirements.

Environment Configuration

Deployment Modes

The system supports several deployment configurations:

1. Minimal Mode: Legacy auth + Direct email + Basic database
2. Standard Mode: SIWE auth + Direct email + Accelerated database
3. Enterprise Mode: SIWE auth + Worker email + Accelerated database with edge caching

Network Configuration

Configure the target network through environment variables:

# For Ethereum Mainnet (default)
# No additional configuration needed
 
# For Sepolia Testnet
NEXT_PUBLIC_SEPOLIA=true
 
# For Local Development
NEXT_PUBLIC_RITONET=true
NEXT_PUBLIC_LOCAL_BLOCKCHAIN_RPC=http://localhost:8545

Security Considerations

The token gate implements multiple layers of security to protect exclusive content and ensure fair access.

Authentication Security

• Signature Verification: All wallet signatures verified using viem’s secure implementation
• Replay Protection: Nonces (SIWE) or timestamps (legacy) prevent signature reuse
• Domain Binding: SIWE messages bound to specific domains
• Rate Limiting: All endpoints protected against abuse

Content Protection

• Server-Side Assembly: Content never exists client-side before authentication
• Signed URLs: Audio URLs expire after 1 hour, preventing long-term sharing
• Single Use Enforcement: Database tracking ensures each token used only once
• Network Isolation: Separate database tables prevent cross-chain confusion

Implementation Best Practices

Performance Optimization

The token gate system implements several optimizations to ensure responsive user experience:

Frontend Optimizations

• Smart Polling: Token status checks pause when users leave the tab
• State Caching: NFT ownership cached to reduce blockchain queries
• Lazy Loading: Audio player components load only after authentication
• Progressive Enhancement: Core functionality works even if auxiliary services fail

Backend Optimizations

• Edge Caching: Prisma Accelerate caches frequently accessed token records
• Connection Pooling: Database connections efficiently managed
• Async Operations: Email sending never blocks user-facing responses
• Graceful Degradation: Audio failures don’t prevent message submission

Monitoring and Metrics

Key metrics to track for optimal performance:

• Authentication success rate
• Average time to content delivery
• Audio streaming performance
• Email delivery success rate
• Database query performance

Troubleshooting Guide

Common issues and their solutions:

“SIWE not enabled” Error

Cause: Redis not properly configured
Solution: Verify Upstash credentials and NEXT_PUBLIC_ACTIVATE_REDIS=true

Audio Not Playing

Cause: R2 configuration or signed URL generation failure
Solution: Check R2 credentials and bucket permissions

Token Already Used

Cause: Database shows token previously used
Solution: User must burn token and mint new one

Email Not Sending

Cause: Incorrect email service configuration
Solution: Verify Brevo API key or Cloudflare Worker URL

Summary

The RitoSwap Token Gate exemplifies sophisticated Web3 access control, seamlessly blending blockchain ownership verification with traditional web services. Through its modular architecture supporting multiple authentication modes, flexible content delivery, and scalable notification systems, it provides a robust foundation for token-gated experiences.

The system’s careful balance of security, performance, and user experience demonstrates how modern dApps can leverage blockchain technology while maintaining the polish expected of enterprise applications. Whether deployed in minimal configuration for testing or full enterprise mode for production, the token gate adapts to infrastructure requirements while maintaining its core security guarantees.

For developers integrating with the token gate, the comprehensive API documentation, clear component boundaries, and extensive configuration options provide the flexibility needed to create unique token-holder experiences while building on a battle-tested foundation.