DApp Overview

Version: 0.2.0

This overview provides entry points for configuring and understanding the RitoSwap decentralized application workspace. Each section includes links to detailed documentation where deeper technical implementation is required. External service documentation may be necessary for third-party integrations.

Pages Architecture

The dApp consists of six core pages, each serving distinct functions within its ecosystem:

Requirements Walkthrough

This section provides a comprehensive overview of the infrastructure and service requirements necessary to operate the RitoSwap dApp with its complete feature set. The following steps outline categories of dependencies that must be configured for full functionality, presenting a roadmap for understanding the scope of requirements before beginning the actual setup process.

Each requirement represents a configuration task involving external service providers, API key generation, database setup, or infrastructure deployment. The steps below organize these requirements into logical groups, with hyperlinks to detailed implementation documentation for each component.

Running the dApp

Once all services are configured and environment variables are set, you can run the dApp on your chosen network:

Development Mode

For Sepolia testnet development:

pnpm dev:sepolia

For Ethereum mainnet development:

pnpm dev:ethereum

These commands automatically set the correct network configuration and start the development server on all network interfaces (0.0.0.0).

Production Build

Generate production build for Sepolia:

pnpm build:sepolia

Generate production build for Ethereum mainnet:

pnpm build:ethereum

The build commands run Prisma generation before creating the optimized production bundle. Ensure your DATABASE_URL is configured before building.

Core Infrastructure

Smart Contract Integration

The dApp requires deployment of the Colored Keys ERC-721 contract. Configure one network at a time through environment variables. Note that “Ritonet” refers to the local blockchain environment with custom branding.

NEXT_PUBLIC_RITONET=false  # Local blockchain (branded alias)
NEXT_PUBLIC_SEPOLIA=true    # Active network
NEXT_PUBLIC_ETHEREUM=false

Wallet Infrastructure

Configure wallet connections with Alchemy API and WalletConnect. The system includes fallback mechanisms when keys are unavailable.

NEXT_PUBLIC_ALCHEMY_API_KEY=your_key_here
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=d506c8083e0c05aa9c9f80b310b9bd4f
NEXT_PUBLIC_APP_NAME=RitoSwap
NEXT_PUBLIC_APP_DESCRIPTION=RitoSwap DEX

Database & State Management

PostgreSQL database with Prisma ORM manages off-chain state for token usage tracking, rate limiting, and session management. The database synchronizes with on-chain data to provide a unified view of token states.

DATABASE_URL=postgresql://user:password@host:5432/dbname

The Prisma schema defines models for token usage, SIWE sessions, and rate limit tracking. Database migrations ensure schema consistency across environments. The system maintains separate tables for each blockchain network (Ethereum mainnet, Sepolia, and local Ritonet) to prevent cross-chain data conflicts.

Token-Gated Access System

The token-gating system combines blockchain verification, database state management, SIWE authentication, and email notifications to provide secure exclusive content access based on NFT ownership.

Email Infrastructure

The system provides flexible email delivery for administrative notifications when token gates are accessed.

Brevo SMTP Provider

Brevo (formerly SendinBlue) serves as the SMTP provider for automated email notifications. Setting up Brevo requires several configuration steps to ensure reliable email delivery.

Create an account with Brevo  and configure the following:

1. API Key Generation: Generate an API key from the Brevo dashboard and add it to your environment configuration under BREVO_API_KEY

2. IP Whitelisting: Whitelist the IP addresses of your email-sending sources in the Brevo dashboard. This includes both your Vercel deployment IPs and any Cloudflare Worker IPs if using the worker configuration

3. Sender Configuration: Configure a sender email address that Brevo will use to send automated emails, adding it as SENDER_EMAIL in your environment

4. Receiver Setup: Set up a receiver email address where form submissions and notifications should be sent, configured as RECEIVER_EMAIL

If you prefer using an alternative SMTP provider, you will need to refactor the API endpoint implementations in verify-token.ts and gatedContent.tsx to accommodate your provider’s API structure.

Primary: Vercel Serverless Function

The default email handling mechanism operates through Vercel’s serverless functions. This configuration provides direct integration with your deployment environment and requires minimal setup beyond the Brevo SMTP configuration.

BREVO_API_KEY=xkeysib-your-api-key-here
SENDER_EMAIL=noreply@yourdomain.com
RECEIVER_EMAIL=admin@yourdomain.com
USE_CLOUDFLARE_WORKER=false  # Keep false for Vercel

When using the Vercel serverless function approach, ensure that USE_CLOUDFLARE_WORKER remains false or is omitted entirely from your environment configuration. The serverless function handles all email composition and delivery within the same API request cycle.

Alternative: Cloudflare Worker

For high-performance email processing at scale, you can delegate email sending to a Cloudflare Worker. This approach leverages Cloudflare’s global edge network for faster response times and better scalability.

Enable Cloudflare Worker delegation by setting:

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

To implement the Cloudflare Worker:

1. Copy the worker.js file from dapp/cloudflare/worker.js to your Cloudflare Worker
2. Configure the Brevo API credentials either as environment variables or secrets in your Worker settings
3. Add your Cloudflare Worker’s IP addresses to the Brevo whitelist
4. Update the Worker URL in your environment configuration

The Worker configuration allows customization of email metadata:

const emailPayload = {
  sender: {
    name: 'RitoSwap Gate',
    email: SENDER_EMAIL,
  },
  to: [{
    email: RECEIVER_EMAIL,
    name: 'RitoSwap Admin',
  }]
}

Security & Authentication

The security infrastructure implements multiple layers of protection including rate limiting, SIWE (Sign-In with Ethereum) authentication, and cryptographic nonce management.

SIWE Authentication

SIWE (Sign-In with Ethereum) provides secure, standardized authentication using Ethereum wallets. When enabled, it offers domain-bound authentication with replay protection through cryptographic nonces. The SIWE implementation follows the EIP-4361 specification, ensuring compatibility with all major wallets while providing robust security against replay attacks and domain spoofing.

NEXT_PUBLIC_ACTIVATE_REDIS=true

Redis Configuration

Redis powers both rate limiting and nonce storage for SIWE sessions. The Redis integration uses Upstash’s REST API for serverless compatibility:

KV_REST_API_TOKEN=your_redis_token
KV_REST_API_URL=your_redis_url

Content Delivery & Storage

Cloudflare R2 Storage

Cloudflare R2 provides secure object storage with signed URL generation for protected content delivery. The R2 integration enables time-limited access to exclusive audio content for token holders, ensuring that premium content remains protected while providing seamless streaming experiences.

Additional API Endpoints

The token gate system includes several specialized API endpoints for different aspects of the authentication and verification flow:

User Interface Components

Navigation System

The navigation infrastructure provides responsive, context-aware navigation throughout the dApp.

Portfolio Viewer

The multi-chain NFT portfolio viewer leverages the Alchemy API to display NFTs across supported EVM chains. Configuration details and implementation specifics are available in the Portfolio page documentation.

Cross-Chain Trading

Integration with the Rango DEX widget enables cross-chain token trading directly within the dApp. Note that the Rango widget requires Next.js 13 compatibility.

NEXT_PUBLIC_RANGO_API_KEY=your_rango_api_key

Application Features

Progressive Web App

Enable Progressive Web App functionality for installable experiences and offline capabilities:

NEXT_PUBLIC_SW=true  # Set to false to disable

Notifications System

The notification system provides both toast notifications for immediate feedback and optional browser notifications for important events:

NEXT_PUBLIC_LOCAL_NOTIFICATIONS=on  # Set to 'off' to disable browser notifications

Music Integration

The dApp features an embedded music player with crypto-themed tracks that enhance the user experience.

Styling Architecture

The styling system uses CSS modules with scoped classes to maintain component isolation and prevent style conflicts.

Footer Components

The footer system provides modular components for comprehensive site information and navigation.