/starknet-erc721

Learn how to deploy and customize an ERC721 token on StarkNet

Primary LanguageCairo

ERC721 on StarkNet

Introduction

Welcome! This is an automated workshop that will explain how to deploy an ERC721 token on StarkNet and customize it to perform specific functions. The ERC721 standard is described here. It is aimed at developers that:

  • Understand Cairo syntax
  • Understand the ERC721 token standard

​ This workshop is the second in a series that will cover broad smart contract concepts (writing and deploying ERC20/ERC721, bridging assets, L1 <-> L2 messaging...). You can find the first tutorial here Interested in helping writing those? Reach out!

Table of contents

Disclaimer

​ Don't expect any kind of benefit from using this, other than learning a bunch of cool stuff about StarkNet, the first general purpose validity rollup on the Ethereum Mainnnet. ​ StarkNet is still in Alpha. This means that development is ongoing, and the paint is not dry everywhere. Things will get better, and in the meanwhile, we make things work with a bit of duct tape here and there! ​

Providing feedback

Once you are done working on this tutorial, your feedback would be greatly appreciated! Please fill this form to let us know what we can do to make it better. ​ And if you struggle to move forward, do let us know! This workshop is meant to be as accessible as possible; we want to know if it's not the case. ​ Do you have a question? Join our Discord server, register and join channel #tutorials-support ​

How to work on this tutorial

Before you start

The TD has three components:

  • An ERC20 token, ticker ERC721-101, that is used to keep track of points
  • An evaluator contract, that is able to mint and distribute ERC721-101 points
  • A second ERC20 token, ticker DTK, that is used to make fake payments

Workflow

To do this tutorial you will have to interact with the Evaluator.cairo contract. To do an exercise you will have to use the submit_exercise function to tell the evaluator the address of the evaluated contract. Once it's done you can call the evaluator for it to correct the desired exericse. For example to solve the first exercise the workflow would be the following:

deploy a smart contract that answers ex1 → call submit_exercise on the evaluator providing your smart contract address → call ex1_test_erc721 on the evaluator contract

Your objective is to gather as many ERC721-101 points as possible. Please note :

  • The 'transfer' function of ERC721-101 has been disabled to encourage you to finish the tutorial with only one address
  • In order to receive points, you will have to reach the calls to the distribute_point function.
  • This repo contains an interface IExerciceSolution.cairo. Your ERC721 contract will have to conform to this interface in order to validate the exercise; that is, your contract needs to implement all the functions described in IExerciceSolution.cairo.
  • We really recommend that your read the Evaluator.cairo contract in order to fully understand what's expected for each exercise. A high level description of what is expected for each exercise is provided in this readme.
  • The Evaluator contract sometimes needs to make payments to buy your tokens. Make sure he has enough dummy tokens to do so! If not, you should get dummy tokens from the dummy tokens contract and send them to the evaluator

Checking your progress

Counting your points

​ Your points will get credited in your wallet; though this may take some time. If you want to monitor your points count in real time, you can also see your balance in voyager! ​

  • Go to the ERC20 counter in voyager, in the "read contract" tab
  • Enter your address in decimal in the "balanceOf" function

You can also check your overall progress here ​

Transaction status

​ You sent a transaction, and it is shown as "undetected" in voyager? This can mean two things: ​

  • Your transaction is pending, and will be included in a block shortly. It will then be visible in voyager.
  • Your transaction was invalid, and will NOT be included in a block (there is no such thing as a failed transaction in StarkNet). ​ You can (and should) check the status of your transaction with the following URL https://alpha4.starknet.io/feeder_gateway/get_transaction_receipt?transactionHash= , where you can append your transaction hash. ​

Install nile

With pip
With docker
  • Linux and macos

for mac m1:

alias nile='docker run --rm -v "$PWD":"$PWD" -w "$PWD" lucaslvy/nile:0.8.0-arm'

for amd processors

alias nile='docker run --rm -v "$PWD":"$PWD" -w "$PWD" lucaslvy/nile:0.8.0-x86'
  • Windows
docker run --rm -it -v ${pwd}:/work --workdir /work lucaslvy/0.8.0-x86

Getting to work

  • Clone the repo on your machine
  • Test that you are able to compile the project
nile compile
  • To convert data to felt use the utils.py script

Contract addresses

Contract code Contract on voyager
Points counter ERC20 0x0272abeb08a98ce2024b96dc522fdcf71e91bd333b228ad62ca664920881bc52
Evaluator 0x03b56add608787daa56932f92c6afbeb50efdd78d63610d9a904aae351b6de73
Dummy ERC20 token 0x07ff0a898530b169c5fe6fed9b397a7bbd402973ce2f543965f99d6d4a4c17b8
Dummy ERC721 token 0x02e24bd7683c01cb2e4e48148e254f2a0d44ee526cff3c703d6031a685f1700d

Points list

Today we are creating an animal registry! Animals are bred by breeders. They can be born, die, reproduce, be sold. You will implement these features little by little.

ERC721 basics

Exercise 1

  • Create an ERC721 token contract. You can use this implementation as a base
  • Deploy it to the testnet (check the constructor for the needed arguments. Also note that the arguments should be decimals.)
nile compile contracts/token/ERC721/ERC721.cairo
nile deploy ERC721 arg1 arg2 arg3 --network goerli
  • Give token #1 to Evaluator contract
  • Call submit_exercise() in the Evaluator to configure the contract you want evaluated (2 pts)
  • Call ex1_test_erc721() in the evaluator to receive your points (2 pts)

Exercise 2

  • Call ex2a_get_animal_rank() to get assigned a random creature to create.
  • Read the expected characteristics of your animal from the Evaluator
  • Create the tools necessary to record animals characteristics in your contract and enable the evaluator contract to retrieve them trough get_animal_characteristics function on your contract (check this)
  • Mint the animal with the desired characteristics and give it to the evaluator
  • Call ex2b_test_declare_animal() to receive points (2 pts)

Minting and burning NFTs

Exercise 3

  • Create a function to allow breeders to mint new animals with the specified characteristics
  • Call ex3_declare_new_animal() to get points (2 pts)

Exercicse 4

  • Create a function to allow breeders to declare dead animals (burn the NFT)
  • Call ex4_declare_dead_animal() to get points (2 pts)

Adding permissions and payments

Exercise 5

  • Use dummy token faucet to get dummy tokens
  • Use ex5a_i_have_dtk() to show you managed to use the faucet (2 pts)
  • Create a function to allow breeder registration.
  • This function should charge the registrant for a fee, paid in dummy tokens (check registration_price)
  • Add permissions. Only allow listed breeders should be able to create animals
  • Call ex5b_register_breeder() to prove your function works. If needed, send dummy tokens first to the evaluator (2pts)

Minting NFTs with Metadata

Exercise 6

Exercise 7

  • Create a new ERC721 contract that supports metadata. You can use this contract as a base
  • The base token URI is the chosen IPFS gateway
  • You can upload your NFTs directly on this website
  • Your tokens should be visible on Oasis once minted!
  • Claim points on ex7_add_metadata (2 pts)

​ ​