Tapkarnival

Problem Statement

TapKarnival is a skill‑based, on‑chain mini‑games platform built for fast, transparent competitions with real stakes, live leaderboards, compliance‑aware asset flows, and verifiable result snapshots on Kadena EVM testnet. It brings three pillars together: fair gameplay with on‑chain prize pools, a pragmatic RWA compliance proof‑of‑concept, and decentralized storage for portable, judge‑friendly verification artifacts.What it doesGames and bettingHosts short, skill‑based mini‑games (Tap, Reflex, Aim, Memory) as 30‑second rounds with a visible entry fee and prize pool. Players choose a stake, start a round, and submit once; a single wallet prompt and clear revert guards ensure reliable UX during live demos. Winners can claim the prize immediately, while a small protocol fee (e.g., 4%) sustains the platform. The round’s result emits an event that updates the leaderboard in real time.Rooms and sharingCreates shareable “war room” lobbies where participants can copy a link or entry code and jump into specific games. This keeps multiplayer sessions or judge walkthroughs coordinated with minimal setup.LeaderboardsAggregates on‑chain GamePlayed events client‑side to compute best‑ever scores per wallet for each game, plus an overall ranking. This provides instant, auditable standings without central databases or off‑chain scoring.Compliance PoC (RWA‑style)Demonstrates KYC‑gated asset transfers using two simple contracts: a ComplianceRegistry that records isKYCd flags and a RestrictedToken (ERC‑20) that checks the registry before allowing transfers. A Real Estate Mode UI gives an admin panel to approve/revoke KYC, shows KYC badges for “From” and “To,” indicates whether a transfer is allowed, and performs a transfer only when both parties are approved. This mirrors ERC‑1404‑style behavior and turns an abstract compliance requirement into a tangible, testable flow.Decentralized storage (CID snapshots)Provides a Storage Mode where the top‑10 leaderboard is captured as JSON and uploaded to return a CID. Anyone can load that CID back to reproduce the snapshot table. This makes results portable and tamper‑evident for judges, partners, or communities reviewing tournament outcomes.How it’s builtFrontendNext.js (App Router) with wallet connection, debounced reads, and guarded writes for a single‑prompt experience. Pages include /play (hub), /rooms (lobbies), /leaderboard (ranks by wallet and game), /real‑estate (compliance UI), and /storage (snapshots).Smart contracts (Kadena EVM, chainId 5920)TapKarnival: holds entry fee logic, emits GamePlayed events, and supports prize/fee flows.ComplianceRegistry: owner‑controlled KYC list and a checkTransfer method used by gated assets.RestrictedToken (RTK): minimal ERC‑20 whose transfers revert if either party isn’t KYC‑approved per the registry.Storage helperA lightweight uploadJSON/fetchJSON abstraction that demonstrates “write JSON → get CID → read by CID,” so snapshots are easy to verify and share.Why it mattersTrust and transparencyPrize pools and results are verifiable on‑chain, leaderboards derive directly from events, and snapshots are recoverable by CID. This removes the usual skepticism around casual “betting” games by making the money and outcomes visible and traceable.Compliance‑awareReal‑world asset narratives require more than marketing; the KYC‑gated token and clear UI states (approved vs restricted) turn compliance from a slide into a working demo component.Judge‑friendlyA tight demo flow (play round → leaderboard → claim → snapshot → load CID → KYC allow/transfer → revoke/block) shows complete, interoperable features in minutes, with addresses, tx links, and CIDs ready to click.Business modelRevenueProtocol fee on each round, sponsored tournaments, branded “Pro Rooms” with custom stakes and prize boosts, and licensing of the compliance widget (registry + passport UI) to RWA pilots.GrowthSeasonal leaderboards, jackpots, referral mechanics, creator‑hosted events, and expansion to additional EVM networks with a simple address map and optional network switcher.CostsMinimal infra for gateways/storage and indexing; decentralized storage reduces vendor lock‑in while keeping artifacts portable.What’s included for reviewersDeployed contracts on Kadena EVM Chain 20:TapKarnival at 0xd9462c9066749CB7579Ed88087Ef5dB0634F5Ec4 (tx: 0x5ea164f16d75a068593d4f98faf1316ef12dbed2fb12a0cfa8ce41ea35ee202c)ComplianceRegistry at 0x0e1EC1B969675Bb1d7bD6500203A05b05Fe5d385 (tx: 0x74c9c5b4bf9c143973c03ba6796fbe81d147041c0a8faaddf4b6b80a9490d54c)RestrictedToken (RTK) at 0xCe694F96838a6904f60bF5eE57f55532c82e6399 (tx: 0xf595b0875e00efbd099030d5b866571d7ea2793d6e22c7c766dbfd4e88f56ccd)A leaderboard snapshot flow that produces and reloads a CID.A Real Estate Mode UI showing KYC status, allowed/not‑allowed gating, and an actual gated transfer.

Solution

Built with Next.js + Scaffold‑ETH hooks on Kadena EVM Chain 20, three contracts (TapKarnival, ComplianceRegistry, RestrictedToken), and a gateway-style JSON snapshot helper that returns CIDs; the frontend uses debounced reads and guarded writes to avoid wallet spam while aggregating on-chain events into leaderboards and verifiable snapshots.Stack and structure Frontend: Next.js App Router with RainbowKit, Wagmi/Viem, Tailwind + daisyUI, plus Scaffold‑ETH hooks for typed reads/writes/events to deployed contracts, keeping the UI reactive to chain state without custom RPC glue code.Contracts: Hardhat + hardhat-deploy with OpenZeppelin; three main contracts—TapKarnival (gameplay, events, pool/fees), ComplianceRegistry (isKYCd + setKYC + checkTransfer), and RestrictedToken (ERC‑20 with registry-gated transfers) deployed to Kadena EVM Chain 20 (chainId 5920).How pieces connect Game loop: The /play pages start a 30s round with a stake ≥ entryFee; on submit, the contract emits GamePlayed(player, game, score), which the frontend subscribes to via event history/watch hooks to update the leaderboard without a centralized database.Leaderboard: Client-side aggregation maps each wallet’s best score per game and computes overall ranks, so judges can see standings update live and snapshot them on demand.Compliance PoC: The Real Estate Mode calls setKYC from an owner wallet to flip isKYCd flags, reads the flags to render green/red badges and an Allowed? indicator, and only enables ERC‑20 transfer if both From and To are approved, mirroring ERC‑1404-style enforcement.Storage snapshots: A minimal lib/storage.ts implements uploadJSON(obj) → CID and fetchJSON(cid) → data using a gateway pattern, enabling “Snapshot Top‑10” and “Load by CID” to produce portable, verifiable artifacts during judging.Partner tech benefits Scaffold‑ETH: The hooks eliminated boilerplate for contract IO, sped up prototyping, and made the /debug page useful for quickly verifying new deploys and function signatures.Kadena EVM Chain 20: One chain for all modules (games, compliance, snapshots integration) reduced multi-network UX complexity and kept explorer links consistent for judges.Notable hacks and optimizations Wallet prompt hygiene: Debounced address inputs and enabled guards for reads prevent excessive provider calls, while gating writes (Transfer disabled unless Allowed?) avoids revert popups like TRANSFER_RESTRICTED during live demos.Rapid storage demo: A stubbed upload API initially returned a fake CID to validate the full UX loop fast, then the helper was abstracted to point at a real gateway so “upload → get CID → fetch by CID” remained unchanged in the UI.Single-network reliability: By deploying the new compliance/token contracts to the same chain as TapKarnival and restarting the frontend to reload ABIs, the app avoided stale bindings and multi-chain edge cases under time constraints.Deployment details TapKarnival: 0xd9462c9066749CB7579Ed88087Ef5dB0634F5Ec4 (tx: 0x5ea164f16d75a068593d4f98faf1316ef12dbed2fb12a0cfa8ce41ea35ee202c), used for rounds, events, claims, and fee withdrawal.ComplianceRegistry: 0x0e1EC1B969675Bb1d7bD6500203A05b05Fe5d385 (tx: 0x74c9c5b4bf9c143973c03ba6796fbe81d147041c0a8faaddf4b6b80a9490d54c), owner-controlled KYC list and transfer checks.RestrictedToken (RTK): 0xCe694F96838a6904f60bF5eE57f55532c82e6399 (tx: 0xf595b0875e00efbd099030d5b866571d7ea2793d6e22c7c766dbfd4e88f56ccd), ERC‑20 that reuses the registry to block non-compliant transfers.