onflow/kitty-items

👋 Welcome! This demo app is designed to help you learn to build on Flow.

• Kitty Items: CryptoKitties Sample App is a complete NFT marketplace built with Cadence, Flow's resource-oriented smart contract programming language.
• Learn how to deploy contracts, mint NFTs, and integrate user wallets with the Flow Client Library (FCL).

🎬 Live Demo

Check out the live demo of Kitty Items, deployed on the Flow Testnet. The demo features 4 main views: homepage, marketplace, profile page, & admin view to mint your very own Kitty Items.

✨ Getting Started

Looking for a step by step guide? Follow the Kitty Items tutorial in the Flow documentation.

1. Install Dependencies

🛠 This project requires NodeJS v16.x or above. See: Node installation instructions
🛠 This project requires flow-cli v0.39.1 or above. See: Flow CLI installation instructions
🛠 This project requires Python v3.6 or above. See: Python installation instructions

2. Clone the project

git clone --depth=1 https://github.com/onflow/kitty-items.git

3. Install packages

• Run npm install in the root of the project.

⚠️ NOTE for Mac M1 users:
You'll need to run the following command in the web project:
From the ./web directory run npm install -D @next/swc-darwin-arm64

Local development

Run this command to start Kitty Items with the Flow local development suite:

npm run dev:emulator

Note: This script launches the Flow Emulator and FCL Development Wallet to simulate the blockchain and an FCL-compatible wallet using the initialization code in this repository

Testnet development

Run npm run dev:testnet and follow the prompt to begin developing on testnet.

If this is your first time interacting with KI or Flow, you will need to create a wallet account (Blocto) using an email. If you created a wallet (Blocto) account before July 7th, the user should create a new account with Blocto. This is because the account storage paths have changed, and the older accounts may result in conflicting paths during minting/purchasing.

Cypress tests

There are 3 ways tests can be run:

1. dev environment - start the server with npm run dev:emulator and run cypress npx cypress run --headed --browser chrome
2. Github actions locally - requires the use of https://github.com/nektos/act
   • On Apple M1 - act -j cypress --container-architecture linux/arm64
   • On Intel/AMD - act -j cypress --container-architecture linux/amd64
3. Github actions - executed automatically when merged to master. Add your branch name to integration-local.yml after line 10 to trigger workflows for every push into your remote branch.

Project Overview

🔎 Legend

Above is a basic diagram of the parts of this project contained in each folder, and how each part interacts with the others.

1. Web App (Static website) | kitty-items/web

A true dapp, client-only web app. This is a complete web application built with React that demonstrates how to build a static website that can be deployed to an environment like IPFS and connects directly to the Flow blockchain using @onflow/fcl. No servers required. @onflow/fcl handles authentication and authorization of Flow accounts, signing transactions, and querying data using using Cadence scripts.

2. Look Ma, a Web Server! | kitty-items/api

We love decentralization, but servers are still very useful, and this one's no exception. The code in this project demonstrates how to connect to Flow using Flow JavaScript SDK from a Node JS backend. It's also chalk-full of handy patterns you'll probably want to use for more complex and feature-rich blockchain applications, like storing and querying events using a SQL database (Postgres). The API demonstrates how to send transactions to the Flow blockchain, specifically for minting Kitty Items (non-fungible tokens).

3. Cadence Code | kitty-items/cadence

Cadence smart contracts, scripts & transactions for your viewing pleasure. This folder contains all of the blockchain logic for the marketplace application. Here you will find examples of fungible token and non-fungible token (NFT) smart contract implementations, as well as the scripts and transactions that interact with them. It also contains examples of how to test your Cadence code.

😺 What are Kitty Items?

Items are hats for your cats, but under the hood they're non-fungible tokens (NFTs) stored on the Flow blockchain.

Items can be purchased from the marketplace with fungible tokens. In the future you'll be able to add them to Ethereum CryptoKitties with ownership validated by an oracle.

❓ More Questions?

• Chat with the team on the Flow Discord server
• Ask questions on the Flow community forum

Troubleshooting

Non-Intel issues

You'll need to run the following command in the web project:
From the ./web directory run npm install -D @next/swc-darwin-arm64
If you're running on another non-intel based system, the issue and troubleshooting steps are detailed here: vercel/next.js#30468

Rebuild dependencies

• The api and web projects depend on sqlite3. If you change node versions on your system, you'll need to cd into the web and api directory and run npm rebuild to rebuild you dependencies for the new version.

Finding the logs

• You can see what processes have been started, and if they are online using pm2 list
• You can tail logs for individual processes using pm2 logs [process name]. eg., pm2 logs api or pm2 logs web
• You can tail all logs in the same terminal using pm2 logs

Starting over

• In the event of problems, you may want to start over. To reset the project, perform these steps:
  • Run pm2 delete all to stop and delete all processes
  • Delete database files in ./api. (kitty-items-db-*.sqlite)

Unblock ports

• Kitty Items uses the following ports. Make sure they are not in use by another process
  • 8080 : Flow emulator
  • 3569 : Flow emulator
  • 3000 : Kitty Items API
  • 3001 : Kitty Items web app
  • 8701 : FCL dev-wallet

Understanding the Marketplace

• The Kitty Items Marketplace on testnet is universal. Every instance of Kitty Items deployed on Testnet points to the same marketplace (NFTStorefrontV2) contract. So, you may see other listing s showing up in your Kitty items instance, but you will not see items in your marketplace page that were added before you deployed your instance of Kitty Items.

🚀 Happy Hacking!