Welcome to RitoSwap Docs

Two Products in One: Multi-chain dApp + Musical AI Game

RitoSwap pairs a Blade Runner‑inspired multichain dApp with a musical AI game experience powered by RapBotRito, an agentic, multi‑modal, chain‑aware voice‑clone extension of Rito Rhymes that you can rap‑battle against to earn rewards. It’s a full‑stack showcase spanning smart contracts, cross‑chain Web3 infrastructure, frontend UX, and a modern AI runtime with custom MCP tooling, on-chain interactions and text-to-speech voice-clone generation.

Storybook UI playground: https://ui.ritoswap.com 

Here is a faucet for free testnet Ether: https://cloud.google.com/application/web3/faucet/ethereum/sepolia 

GitHub Repository: https://github.com/ritovision/ritoswap-mirror 

Core Features

Multichain dApp

• Custom ERC-721 smart contract for Colored Keys, only hold 1 NFT at a time per address with a randomized set of colors for an on-chain SVG image.
• On-chain NFT mint and burn for Colored Keys, burn-to-reset identity.
• Token gate with SIWE and JWT access tokens for fast re-entry.
• Cross-chain swaps via the LiFi widget.
• Multichain balance and portfolio view powered by Alchemy.
• Custom wallet UI on Wagmi and WalletConnect, with mobile deeplinking.
• Music-first experience with integrated players, original Rito Rhymes catalog, and PWA features across the experience.

AI System - RapBotRito

• An extension of the likeness of Rito Rhymes, an infotaining rapper in the crypto space with a voice clone used to generate spoken word audio.
• Token-gated AI experience embedded inside the gate.
• Mode-driven behavior for rap battle games with strict MCP tool allowlists.
• MCP server, LangChain orchestration, and Vercel AI SDK streaming.
• Chat JWT enforcement is env-toggleable; selected tools require JWT when enabled.
• Pinecone semantic database for lore, rhymes, and image search.
• Inline tools for GIFs, images, chain logos, and music playback.
• ElevenLabs voice clone for spoken-word raps, cached locally and routed through the Music Bar.
• Image generation streams base64 payloads directly to the client (no server storage).
• On-chain balance tools and (testnet only) limited crypto transfers.
• Token and crypto quota systems for controlled usage.
• Provider switching for OpenAI or LM Studio, plus multiple image providers.

Quality and Observability

• Playwright flows execute real Sepolia transactions for end-to-end validation.
• Supertest API suites cover the token gate and MCP surfaces, and contract tests lock the token gate schema.
• Sentry error boundaries and monitoring across client, server, and edge.

Documentation Entry Points

Pick a path depending on what you want to explore first:

Docs Tooling

The docs site embeds live UI and API playgrounds:

Technology Stack

This TypeScript-first codebase uses modern tooling across the stack.

Frontend Technologies

The frontend is built with Next.js, Wagmi, Tanstack Query, Zustand, Framer Motion, and Howler. The dApp ships a custom wallet UI, portfolio viewer, and mobile deeplinking, while the docs run on Nextra.

Backend and State

The backend uses PostgreSQL with Prisma and Prisma Accelerate, Cloudflare R2, Brevo SMTP, Vercel serverless functions, and a Cloudflare Worker plus Durable Object for nonces, rate limits, quotas, and email relay. SIWE and JWT access tokens secure the token gate and AI services.

AI Backend

The AI system runs on the Vercel AI SDK with LangChain orchestration, an MCP server and tool registry, Pinecone semantic search, and provider switching between OpenAI and LM Studio. Tool access is JWT-gated and quota-controlled.

Blockchain Components

Local development uses Hyperledger Besu QBFT with Blockscout. Production and testnet use Alchemy and public RPC endpoints. The ERC-721 contract is developed with Hardhat and validated with Slither, Mythril, and Echidna.

Workspace Architecture

• ritoswap
  • local-blockchain
  • colored-keys
  • dapp
  • docs
  • package.json
  • pnpm-workspace.yaml
  • .changeset/

The monorepo contains five workspaces, including the root workspace that serves as the entry point for pnpm, changesets scripts, CI workflows, and shared configuration.

Workspace Descriptions

Local Blockchain and Block Explorer (/local-blockchain): Single-validator Hyperledger Besu QBFT network with Blockscout for local development.

Smart Contract and Security Tests (/colored-keys): ERC-721 contract code plus deployment scripts and security testing.

Decentralized Application (/dapp): The main dApp, API routes, AI system, wallet UX, and token gate infrastructure.

Cloudflare Worker and Durable State (/dapp/cloudflare): Durable Object state engine for nonces, rate limits, and quotas, plus the email relay used by the token gate.

Documentation (/docs): Nextra documentation site with Storybook and OpenAPI playground embeds.

Current Versions

The following table displays the current version of each workspace in the monorepo:

System Requirements

To build and run this project locally, your development environment requires Node.js version 20.18.1 or higher (recommended minimum) and Docker Engine through Docker Desktop on macOS/Windows or Docker Engine on Linux with the latest stable release.

Getting Started

Each workspace provides specific functionality that can be explored independently or integrated as part of the complete RitoSwap ecosystem. The documentation for each workspace includes detailed setup instructions, configuration guides, and implementation details.

About the Project

Creator and Vision

Creator and Vision

RitoSwap is conceived and built end-to-end by Rito, also known by his music alias Rito Rhymes , with assistance from AI models including Claude and ChatGPT. The project serves as a comprehensive showcase of multi-disciplinary expertise across product development, brand management, UX design, and technology integration.

Rito serves as a multi-hyphenate Chief Product Officer, UX & Design Leader, and Full-Stack Engineer through RitoVision , his hybrid studio and consultancy. This project demonstrates the harmonious integration of multiple roles that would often take a full team of specialists to execute including full-stack engineering, UX design, product strategy, brand management, music production, and creative direction.

With a Master’s in Human-Computer Interaction and over a decade of experience leading startups and building digital products, Rito brings deep expertise in connecting disciplines to solve complex business challenges. His work has garnered significant media attention, with features in The New York Times, ScreenRant, and U.Today, along with profile interviews on NYC’s flagship 77 WABC radio and Stockhead magazine. His portfolio includes co-authoring blockchain standards with William Entriken, designing wearable technology showcased by celebrity fashion designers, leveraging global press coverage to drive patches in the multi-billion-dollar Call of Duty franchise, and spearheading end-to-end platform development for high-profile clients.

License and Usage

The source code is licensed under the MIT License. However, trademarks including Rito Rhymes, RitoVision, and all associated branding, images, logos, voice clone assets, and music remain privately owned. The production voice clone and its outputs or derivatives are not open sourced. You are granted a personal, non-commercial license to consume the audio inside the app for personal entertainment purposes only. No commercial rights or redistribution are granted. Use of these brand assets is not granted under the open source license.

Support and Resources

For technical questions and implementation details, consult the comprehensive documentation for each workspace. For questions about the project, its architecture, or potential collaboration opportunities with Rito including fractional services, visit https://ritovision.com .

Explore the Documentation

Ready to dive deeper into the technical implementation? Start with the dApp and AI Systems sections to see how the core experiences are built end to end.