/kitty-items

Based on CryptoKitties, Kitty Items is an example of a full-stack dapp built on Flow.

Primary LanguageJavaScriptApache License 2.0Apache-2.0

👋 Welcome! This demo app was created to help you learn how to build on Flow.

  • Kitty Items 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.

If you'd like to deploy your own version, see the deploy to Heroku instructions near the bottom to this setup guide.

✨ Getting Started

Note: The following guide demonstrates how to deploy Kitty Items to the Flow Testnet. We think using the live network is the best way to learn about Flow. For your own projects you will likely want to develop and test locally, before you deploy. You can read the local development guide here.

1. Install the Flow CLI

Before you start, install the Flow command-line interface (CLI).

⚠️ This project requires flow-cli v0.15.0 or above.

2. Clone the project

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

3. Create a Flow Testnet account

You'll need a Testnet account to work on this project. Here's how to make one:

Generate a key pair

Generate a new key pair with the Flow CLI:

flow keys generate

⚠️ Make sure to save these keys in a safe place, you'll need them later.

Create your account

Go to the Flow Testnet Faucet to create a new account. Use the public key from the previous step.

Save your keys

After your account has been created, export the following environment variables to your shell:

# Replace these values with the address returned from the faucet and the
# private key you generated in the first step!

export FLOW_ADDRESS=address
export FLOW_PRIVATE_KEY=xxxxxxxxxxxx

Note: It's important that these variables are exported in each shell where you're running any of the commands in this walkthrough.

4. Deploy the contracts

flow project deploy --network=testnet

If you'd like to look at the contracts in your account, to confirm that everything was deploy properly, you can use the following cli command:

flow accounts get $FLOW_ADDRESS --network=testnet

3. Rename .env.example files

Rename .env.example to env.local in the web and api folders. The .env.local files should be in their respective project directories.

kitty-items/
├─ api/
│  ├─ .env.local
├─ web/
│  ├─ .env.local
├─ ... etc

7. Start the project

From the root of the project run: npm install to install lerna.

Once finished run lerna exec npm install to install the project's dependencies.

From the root of the project run npm run start:testnet to start Kitty Items!

(Optional) Heroku Deployment

If you'd like to deploy a version of this app to Heroku for testing, you can use this button!

Deploy

You'll need to supply the following configuration variables when prompted:

# The Flow address and private key you generated above

MINTER_ADDRESS
MINTER_PRIVATE_KEY

# The Flow address where you have deployed your Kitty Items contract.
# (usually the same Flow address as above)

REACT_APP_CONTRACT_KIBBLE
REACT_APP_CONTRACT_KITTY_ITEMS
REACT_APP_CONTRACT_KITTY_ITEMS_MARKET

Project Overview

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 Kibbles (fungible tokens) and 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 (tests written in Golang).

😺 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?

🚀 Happy Hacking!