Potion Master's Guild

Brew legendary potions and build your reputation in the on-chain alchemy game.

Comment

Potion Master's Guild

Inspiration

I wanted to build a game that actually feels good to play on blockchain. Too many Web3 games feel clunky with constant wallet popups and slow transactions. I thought - what if we made something that's truly on-chain but doesn't sacrifice user experience? An alchemy game seemed perfect because the crafting loop (gather ingredients → craft items → sell/use) maps naturally to blockchain transactions.

What it does

Potion Master's Guild is an on-chain alchemy RPG where you:

  • Buy magical ingredients from the market using gold
  • Brew potions by combining ingredients in your laboratory
  • Complete customer orders before time runs out
  • Earn gold and reputation to rank up from Novice to Master Alchemist
  • Discover mysterious recipes by spending gold in the Discovery Lab

Everything - your gold, reputation, ingredients, recipes, and orders - lives entirely on-chain on Starknet. No centralized servers, no off-chain databases.

How we built it

Smart Contracts:

  • Built with Cairo and the Dojo engine for provable game state
  • Deployed to Starknet Sepolia testnet
  • Created systems for player registration, ingredient purchases, potion brewing, recipe discovery, and order fulfillment

Frontend:

  • React + TypeScript with Vite
  • Integrated Cartridge Controller for seamless wallet onboarding
  • Used Framer Motion for smooth animations (brewing cauldron, confetti, particle effects)
  • Implemented localStorage for caching to avoid constant RPC calls while keeping the source of truth on-chain
  • Added support for Argent and Braavos wallets alongside Cartridge

Game Design:

  • Designed a tutorial system to onboard new players
  • Created a progression system with 5 ranks and multiple recipe tiers
  • Implemented time-based orders with urgency indicators

Challenges we ran into

Real-time updates without Torii: Getting the frontend to reflect on-chain state changes immediately was tricky. I solved this by optimistically updating the UI after transactions while using localStorage to persist state per wallet address.

Type safety across Cairo and TypeScript: Mapping Cairo types (felt252, u64, ContractAddress) to TypeScript interfaces required careful planning. I created helper types like IngredientWithQuantity and RecipeWithDetails to bridge contract models and UI needs.

Animation performance: The brewing cauldron has bubbles, steam, flames, and rotating sparkles. Keeping 60fps with all these animations running required optimizing the number of animated elements and using CSS transforms over layout changes.

Wallet UX: Making the game work seamlessly across three different wallet providers (Cartridge, Argent, Braavos) while handling connection states, transaction signing, and error cases properly.

Accomplishments that we're proud of

  • It actually feels like a game! The animations, sounds, and visual feedback make it engaging, not just a blockchain demo.
  • Zero friction onboarding with Cartridge Controller - new players can start playing in seconds without seed phrases.
  • Real-time stat updates - gold and reputation change instantly when you complete actions, no page refresh needed.
  • Complete game loop - you can actually play from start to finish: buy ingredients, brew potions, complete orders, rank up, and unlock new content.
  • Fully on-chain - every game action is a real Starknet transaction that updates the contract state.

What we learned

  • Dojo is powerful for game state management - the ECS pattern makes it easy to model complex game entities and their relationships.
  • UX matters more than tech - having beautiful animations and instant feedback is what makes players want to keep playing, not just "it's on blockchain."
  • Optimistic UI updates are crucial - showing immediate feedback while transactions confirm makes blockchain games feel responsive.
  • Cartridge Controller is a game-changer - removing the wallet complexity barrier makes Web3 games accessible to everyone.
  • LocalStorage + on-chain is a good hybrid - cache for speed, blockchain for truth and persistence.

What's next for Potion Master's Guild

  • Multiplayer market dynamics - let players trade ingredients and potions with each other
  • Leaderboard system - global rankings showing top alchemists by reputation
  • Player-named potions - let players discover and name their own unique recipes (stored on-chain)
  • Lab explosions - add a risk/reward mechanic where failed brews can damage your lab
  • Seasonal events - limited-time ingredients and special customer orders
  • Mobile responsive design - make it playable on phones and tablets
  • Achievement NFTs - mint commemorative NFTs for reaching Master rank or discovering all recipes
  • Integration with Torii - use Dojo's indexer for real-time data queries instead of localStorage caching

Built With

Share this project:

Updates