Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Kitty Items: CryptoKitties Sample App
https://github.com/onflow/kitty-items

blockchain cryptokitties dapp flow sample

Last synced: 2 days ago
JSON representation

Kitty Items: CryptoKitties Sample App

Awesome Lists containing this project

README 

        


  

    

  




# Important Message



This repo is deprecated and archived. If you want to learn how

to build on Flow with a demo app,

please see the [Flow App Quickstart guide](https://developers.flow.com/build/guides/flow-app-quickstart).



If you want an example of an NFT project on Flow,

see the [Flow NFT Guide](https://developers.flow.com/build/guides/nft)

or the [Flow NonFungibleToken repo](https://github.com/onflow/flow-nft).



# Archived Content



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](https://docs.onflow.org/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](https://kitty-items.onflow.org/),

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**](https://docs.onflow.org/kitty-items/install/).



### 1. Install Dependencies



_🛠 This project requires `NodeJS v16.x` or above._ See: [Node installation instructions](https://nodejs.org/en/) 


_🛠 This project requires `flow-cli v0.39.1` or above._ See: [Flow CLI installation instructions](https://docs.onflow.org/flow-cli) 


_🛠 This project requires `Python v3.6` or above._ See: [Python installation instructions](https://www.python.org/downloads)



### 2. Clone the project



```sh

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](https://docs.onflow.org/emulator/) and [FCL Development Wallet](https://github.com/onflow/fcl-dev-wallet) to simulate the blockchain and an FCL-compatible wallet using the [initialization code in this repository](/.ki-scripts/README.md)



## 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



![Project Overview](/assets/kitty-items-diagram.png)



## 🔎 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](https://github.com/onflow/kitty-items/tree/master/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](https://docs.onflow.org/concepts/accounts-and-keys/), [signing transactions](https://docs.onflow.org/concepts/transaction-signing/), and querying data using using Cadence scripts.



### 2. Look Ma, a Web Server! | [kitty-items/api](https://github.com/onflow/kitty-items/tree/master/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](https://github.com/onflow/flow-js-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](https://github.com/onflow/kitty-items/blob/master/cadence/contracts/KittyItems.cdc) (non-fungible tokens).



### 3. Cadence Code | [kitty-items/cadence](https://github.com/onflow/kitty-items/tree/master/cadence)



[Cadence](https://docs.onflow.org/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](https://github.com/onflow/flow-ft) and [non-fungible token (NFT)](https://github.com/onflow/flow-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)](https://github.com/onflow/flow-nft) 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](https://www.cryptokitties.co/) with ownership validated by an oracle.



## ❓ More Questions?



- Chat with the team on the [Flow Discord server](https://discord.gg/xUdZxs82Rz)

- Ask questions on the [Flow community forum](https://forum.onflow.org/t/kitty-items-marketplace-demo-dapp/759/5)



## 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: [https://github.com/vercel/next.js/discussions/30468](https://github.com/vercel/next.js/discussions/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!