{"id":13410269,"url":"https://github.com/starknet-edu/starknet-erc20","last_synced_at":"2025-03-14T15:32:15.701Z","repository":{"id":52311260,"uuid":"510788334","full_name":"starknet-edu/starknet-erc20","owner":"starknet-edu","description":"Learn how to deploy and customize an ERC20 token on StarkNet","archived":false,"fork":false,"pushed_at":"2023-09-12T12:38:47.000Z","size":205,"stargazers_count":69,"open_issues_count":5,"forks_count":33,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-31T20:41:26.996Z","etag":null,"topics":["cairo","erc20"],"latest_commit_sha":null,"homepage":"","language":"Cairo","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/starknet-edu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-05T15:13:41.000Z","updated_at":"2024-06-17T00:59:13.000Z","dependencies_parsed_at":"2024-10-26T05:50:50.432Z","dependency_job_id":"542bcf8e-9169-4d85-9677-a2f7cce4c9ec","html_url":"https://github.com/starknet-edu/starknet-erc20","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starknet-edu%2Fstarknet-erc20","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starknet-edu%2Fstarknet-erc20/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starknet-edu%2Fstarknet-erc20/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starknet-edu%2Fstarknet-erc20/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starknet-edu","download_url":"https://codeload.github.com/starknet-edu/starknet-erc20/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243600734,"owners_count":20317324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cairo","erc20"],"created_at":"2024-07-30T20:01:05.909Z","updated_at":"2025-03-14T15:32:15.240Z","avatar_url":"https://github.com/starknet-edu.png","language":"Cairo","funding_links":[],"categories":["Templates"],"sub_categories":[],"readme":"# DISCLAIMER\nHello Starknet community, this repository is not updated with the latest Cairo syntax and hence, we do not recommend to attempt this tutorial as of today. If you are interested in contributing to the repository to update the tutorial, please create a PR and tag me @gyan0890 on it and we will be happy to support you with the process.\n\nA great resource to get you up to speed with the new Cairo syntax in a Starknet context is [Chapter 2 of the Starknet Book](https://book.starknet.io/chapter_2/index.html).\n\nYou can also ping me(@gyanlakshmi) on Telegram to help you assign the right tasks.\n\n# ERC20 on Starknet\n\nWelcome! This is an automated workshop that will explain how to deploy an ERC20 token on Starknet and customize it to perform specific functions. The ERC20 standard is described [here](https://docs.openzeppelin.com/contracts/3.x/api/token/erc20)\nIt is aimed at developers that:\n\n- Understand Cairo syntax\n- Understand the ERC20 token standard\n\nThis tutorial was written by Florian Charlier ([@trevis_dev](https://twitter.com/trevis_dev)) in collaboration with Henri Lieutaud and Lucas Levy, based on Henri's original [ERC20 101](https://github.com/l-henri/erc20-101) and [ERC20 102](https://github.com/l-henri/erc20-102) tutorials for Solidity.\n\n​\n​\n\n## Introduction\n\n### Disclaimer\n\nDon'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.\n​\nStarknet 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!\n​\n\n### How it works\n\nThe goal of this tutorial is for you to customize and deploy an ERC20 contract on Starknet. Your progress will be check by an [evaluator contract](contracts/Evaluator.cairo), deployed on Starknet, which will grant you points in the form of [ERC20 tokens](contracts/token/ERC20/TUTOERC20.cairo).\n\nEach exercise will require you to add functionality to your ERC20 token.\n\nFor each exercise, you will have to write a new version on your contract, deploy it, and submit it to the evaluator for correction.\n\n### Where am I?\n\nThis workshop is the third in a series aimed at teaching how to build on Starknet. Checkout out the following:\n\n| Topic                                              | GitHub repo                                                                            |\n| -------------------------------------------------- | -------------------------------------------------------------------------------------- |\n| Learn how to read Cairo code                       | [Cairo 101](https://github.com/starknet-edu/starknet-cairo-101)                        |\n| Deploy and customize an ERC721 NFT                 | [Starknet ERC721](https://github.com/starknet-edu/starknet-erc721)                     |\n| Deploy and customize an ERC20 token (you are here) | [Starknet ERC20](https://github.com/starknet-edu/starknet-erc20)                       |\n| Build a cross layer application                    | [Starknet messaging bridge](https://github.com/starknet-edu/starknet-messaging-bridge) |\n| Debug your Cairo contracts easily                  | [Starknet debug](https://github.com/starknet-edu/starknet-debug)                       |\n| Design your own account contract                   | [Starknet account abstraction](https://github.com/starknet-edu/starknet-accounts)      |\n\n### Providing feedback \u0026 getting help\n\nOnce you are done working on this tutorial, your feedback would be greatly appreciated!\n\n**Please fill out [this form](https://forms.reform.app/starkware/untitled-form-4/kaes2e) to let us know what we can do to make it better.**\n\n​\nAnd 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.\n\n​\nDo you have a question? Join our [Discord server](https://starknet.io/discord), register, and join channel #tutorials-support\n​\nAre you interested in following online workshops about learning how to dev on Starknet? [Subscribe here](http://eepurl.com/hFnpQ5)\n\n### Contributing\n\nThis project can be made better and will evolve as Starknet matures. Your contributions are welcome! Here are things that you can do to help:\n\n- Create a branch with a translation to your language\n- Correct bugs if you find some\n- Add an explanation in the comments of the exercise if you feel it needs more explanation\n- Add exercises showcasing your favorite Cairo feature\n\n​\n\n## Getting ready to work\n\n### Step 1 - Clone the repo\n\n```bash\ngit clone https://github.com/starknet-edu/starknet-erc20\ncd starknet-erc20\n```\n\n### Step 2 - Set up your environment\n\nThere are two ways to set up your environment on Starknet: a local installation, or using a docker container\n\n- For Mac and Linux users, we recommend either\n- For windows users we recommand docker\n\nFor a production setup instructions we wrote [this article](https://medium.com/starknet-edu/the-ultimate-starknet-dev-environment-716724aef4a7).\n\n#### Option A - Set up a local python environment\n\n- Set up the environment following [these instructions](https://starknet.io/docs/quickstart.html#quickstart)\n- Install [OpenZeppelin's cairo contracts](https://github.com/OpenZeppelin/cairo-contracts).\n\n```bash\npip install openzeppelin-cairo-contracts\n```\n\n#### Option B - Use a dockerized environment\n\n- Linux and macos\n\nfor mac m1:\n\n```bash\nalias cairo='docker run --rm -v \"$PWD\":\"$PWD\" -w \"$PWD\" shardlabs/cairo-cli:latest-arm'\n```\n\nfor amd processors\n\n```bash\nalias cairo='docker run --rm -v \"$PWD\":\"$PWD\" -w \"$PWD\" shardlabs/cairo-cli:latest'\n```\n\n- Windows\n\n```bash\ndocker run --rm -it -v ${pwd}:/work --workdir /work shardlabs/cairo-cli:latest\n```\n\n### Step 3 -Test that you are able to compile the project\n\n```bash\nstarknet-compile contracts/Evaluator.cairo\n```\n\n### Step 4 - Define your environment variables to set up your account\n\n```bash\nexport STARKNET_NETWORK=alpha-goerli\nexport STARKNET_WALLET=starkware.starknet.wallets.open_zeppelin.OpenZeppelinAccount\n```\n\n### Step 5 - Create and deploy your account\nBefore deploying your account, send a few Goerli ETH to it.\n```bash\nstarknet new_account\nstarknet deploy_account\n```\n\n## Working on the tutorial\n\n### Workflow\n\nTo do this tutorial you will have to interact with the [`Evaluator.cairo`](contracts/Evaluator.cairo) contract. To validate an exercise you will have to\n\n- Read the evaluator code to figure out what is expected of your contract\n- Customize your contract's code\n- Deploy it to Starknet's testnet. This is done using the CLI.\n- Register your exercise for correction, using the `submit_exercise` function on the evaluator. This is done using Voyager.\n- Call the relevant function on the evaluator contract to get your exercise corrected and receive your points. This is done using Voyager.\n\nFor example to solve the first exercise the workflow would be the following:\n\n`deploy a smart contract that answers ex1` \u0026rarr; `call submit_exercise on the evaluator providing your smart contract address` \u0026rarr; `call ex2_test_erc20 on the evaluator contract`\n\nNotes:\nTo deploy a smart contract, follow these instructions:\n\n```bash\nstarknet-compile my_contrats/erc20.cairo --output artifacts/erc20.json\nstarknet declare --contract artifacts/erc20.json\n```\n\nUse the contract class from the output of the previous command\n\n```bash\nstarknet deploy --class_hash \u003ccompile_contract_class_hash\u003e --network alpha-goerli\n```\n\n***Your objective is to gather as many ERC20-101 points as possible.*** Please note :\n\n- The 'transfer' function of ERC20-101 has been disabled to encourage you to finish the tutorial with only one address\n- In order to receive points, you will have to reach the calls to the  `validate_and_distribute_points_once` function.\n- This repo contains two interfaces ([`IERC20Solution.cairo`](contracts/IERC20Solution.cairo) and [`IExerciseSolution.cairo`](contracts/IERC20Solution.cairo)). For example, for the first part, your ERC20 contract will have to conform to the first interface in order to validate the exercises; that is, your contract needs to implement all the functions described in `IERC20Solution.cairo`.\n- **We really recommend that your read the [`Evaluator.cairo`](contracts/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.\n- 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.\n\n### Contracts code and addresses\n\n| Contract code                                                     | Contract on voyager                                                                                                                                                           |\n| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Points counter ERC20](contracts/token/ERC20/TUTOERC20.cairo)     | [0x228c0e6db14052a66901df14a9e8493c0711fa571860d9c62b6952997aae58b](https://goerli.voyager.online/contract/0x228c0e6db14052a66901df14a9e8493c0711fa571860d9c62b6952997aae58b) |\n| [Evaluator](contracts/Evaluator.cairo)                            | [0x14ece8a1dcdcc5a56f01a987046f2bd8ddfb56bc358da050864ae6da5f71394](https://goerli.voyager.online/contract/0x14ece8a1dcdcc5a56f01a987046f2bd8ddfb56bc358da050864ae6da5f71394) |\n| [Dummy ERC20 token (DTK20)](contracts/token/ERC20/DTKERC20.cairo) | [0x66aa72ce2916bbfc654fd18f9c9aaed29a4a678274639a010468a948a5e2a96](https://goerli.voyager.online/contract/0x66aa72ce2916bbfc654fd18f9c9aaed29a4a678274639a010468a948a5e2a96) |\n\n​\n​\n\n## Tasks list\n\nToday you will deploy your own ERC20 token on Starknet!\n\nThe tutorial is structured in two parts\n\n- In the first part (exercises 1 to 9), you will have to deploy an ERC-20 contract.\n- In the second part (exercises 10 to 18), you will deploy another contract that will itself have to interact with ERC20 tokens.\n\n### Exercise 1 - Deploy an ERC20\n\n- Call [`ex1_assign_rank()`](contracts/Evaluator.cairo#L134) in the evaluator contract to receive a random ticker for your ERC20 token, as well as an initial token supply (1 pt). You can read your assigned ticker and supply through the [evaluator page in voyager](https://goerli.voyager.online/contract/0x14ece8a1dcdcc5a56f01a987046f2bd8ddfb56bc358da050864ae6da5f71394) by calling getters [`read_ticker()`](contracts/Evaluator.cairo#L93) and [`read_supply()`](contracts/Evaluator.cairo#L102)\n- Create an ERC20 token contract with the proper ticker and supply. You can use [this implementation](https://github.com/OpenZeppelin/cairo-contracts/blob/main/src/openzeppelin/token/erc20/ERC20.cairo) as a base (2 pts)\n- Deploy it to the testnet (check the constructor for the needed arguments. Also note that the arguments should be decimals.) (1pt)\n\n```bash\nstarknet-compile contracts/token/ERC20/ERC20.cairo --output artifacts/ERC20.json\nstarknet deploy --contract ERC20 --inputs arg1 arg2 arg3 --network alpha-goerli \n```\n\n- Call [`submit_erc20_solution()`](contracts/Evaluator.cairo#L733) in the Evaluator to set the contract you want evaluated (2pts) (Previous 3 points for the ERC20 and the deployment are also attributed at that step)\n\n### Exercise 2 - Verifying your ERC20\n\n- Call [`ex2_test_erc20()`](contracts/Evaluator.cairo#L150) in the evaluator for it to check ticker and supply and attribute your points (2 pts)\n\n### Exercise 3 - Creating a faucet\n\n- Create a `get_tokens()` function in your contract. It should mint some of your token for the caller. It should return the exact amount it mints so that the Evaluator can check that the increase of balance and the amount sent corresponds.\n- Deploy your contract and call [`submit_erc20_solution()`](contracts/Evaluator.cairo#L733) in the Evaluator to register it\n- Call the [`ex3_test_get_token()`](contracts/Evaluator.cairo#L209)  function that distributes tokens to the caller (2 pts).\n\n### Exercises 4, 5 and 6 - Creating an allow list\n\n- Create a customer allow listing function. Only allow listed users should be able to call `get_tokens()`.\n- Create a function `request_allowlist()` that the evaluator will call during the exercise check to be allowed to get tokens.\n- Create a function `allowlist_level()` that can be called by anyone to know whether an account is allowed to get tokens.\n- Deploy your contract and call [`submit_erc20_solution()`](contracts/Evaluator.cairo#L733) in the Evaluator to register it\n- Call [`ex4_5_6_test_fencing()`](contracts/Evaluator.cairo#L231) in the evaluator to show\n  - It can't get tokens using `get_tokens()` (1 pt)\n  - It can call `request_allowlist()` and have confirmation that it went through (1 pt)\n  - It can then get tokens using the same `get_tokens()` (2 pt)\n\n### Exercises 7, 8 and 9 - Creating a multi tier allow list\n\n- Create a customer multi tier listing function. Only allow listed users should be able to call `get_token()`; and customers should receive a different amount of tokens based on their level\n- Create a function `request_allowlist_level()` that the evaluator will call during the exercise check to be allowed to get tokens at a certain tier level\n- Modify the function `allowlist_level()` so that it returns the allowed level of accounts.\n- Deploy your contract and call [`submit_erc20_solution()`](contracts/Evaluator.cairo#L733) in the Evaluator to register it\n- Call [`ex7_8_9_test_fencing_levels()`](contracts/Evaluator.cairo#L291) in the evaluator to show\n  - It can't get tokens using `get_tokens()` (1 pt)\n  - It can call `request_allowlist_level(1)` , then call `get_tokens()` and get N tokens (2 pt)\n  - It can call `request_allowlist_level(2)` , then call `get_tokens()` and get \u003e N tokens (2 pt)\n\n### Exercise 10 - Claiming dummy tokens\n\n- Manually claim tokens on the predeployed claimable [ERC20](https://goerli.voyager.online/contract/0x66aa72ce2916bbfc654fd18f9c9aaed29a4a678274639a010468a948a5e2a96) ([DTK tokens](contracts/token/ERC20/DTKERC20.cairo)) (1 pts)\n- Claim your points by calling [`ex10_claimed_tokens()`](contracts/Evaluator.cairo#L364) in the evaluator (1 pts)\n\n### Exercise 11 - Calling the faucet from your contract\n\n- Create a contract `ExerciseSolution` that:\n  - Can claim and hold DTK tokens on behalf of the calling address\n  - Keeps track of addresses who claimed tokens, and how much\n  - Implements a `tokens_in_custody` function to show these claimed amounts\n- Deploy your contract and call [`submit_exercise_solution()`](contracts/Evaluator.cairo#L754) in the Evaluator to register it\n- Call [`ex11_claimed_from_contract()`](contracts/Evaluator.cairo#L383) in the evaluator to prove your code works (3 pts)\n\n### Exercise 12 - Using transferFrom on an ERC20\n\n- Create a function `withdraw_all_tokens()` in `ExerciseSolution` to withdraw the claimed tokens from the `ExerciseSolution` to the address that initially claimed them\n- Deploy your contract and call [`submit_exercise_solution()`](contracts/Evaluator.cairo#L754) in the Evaluator to register it\n- Call [`ex12_withdraw_from_contract()`](contracts/Evaluator.cairo#L431) in the evaluator to prove your code works (2 pts)\n\n### Exercise 13 - Approve\n\n- Mint some DTK tokens and use voyager to authorize the evaluator to manipulate them\n- Call [`ex13_approved_exercise_solution()`](contracts/Evaluator.cairo#L491)  to claim points (1 pts)\n\n### Exercise 14 - Revoking approval\n\n- Use voyager to revoke the previous authorization.\n- Call [`ex14_revoked_exercise_solution()`](contracts/Evaluator.cairo#L512)  to claim points (1 pts)\n\n### Exercise 15 - Using transferFrom\n\n- Create a function `deposit_tokens()` in your contract through which a user can deposit DTKs in `ExerciseSolution`, by using the `transferFrom` of DTK\n- Deploy your contract and call [`submit_exercise_solution()`](contracts/Evaluator.cairo#L754) in the Evaluator to register it\n- Call [`ex15_deposit_tokens`](contracts/Evaluator.cairo#L533) in the evaluator to prove your code works (2 pts)\n\n### Exercise 16 and 17 - Tracking deposits with a wrapping ERC20\n\n- Create and deploy a new ERC20 `ExerciseSolutionToken` to track user deposit. This ERC20 should be mintable and mint authorization given to `ExerciseSolution`\n- Deploy `ExerciseSolutionToken` and make sure that `ExerciseSolution` knows its address\n- Update the deposit function on `ExerciseSolution` so that user balances are tokenized: when a deposit is made in `ExerciseSolution`, tokens are minted in `ExerciseSolutionToken` and transferred to the address depositing\n- Deploy your contract and call [`submit_exercise_solution()`](contracts/Evaluator.cairo#L754) in the Evaluator to register it\n- Call [`ex16_17_deposit_and_mint`](contracts/Evaluator.cairo#L591) in the evaluator to prove your code works (4 pts)\n\n### Exercise 18 - Withdrawing tokens and burning wrapped tokens\n\n- Update the `ExerciseSolution` withdraw function so that it uses `transferFrom()` in `ExerciseSolutionToken`, burns these tokens, and returns the DTKs\n- Deploy your contract and call [`submit_exercise_solution()`](contracts/Evaluator.cairo#L754) in the Evaluator to register it\n- Call [`ex18_withdraw_and_burn`](contracts/Evaluator.cairo#L659) in the evaluator to prove your code works (2 pts)\n\n​\n​\n\n## Annex - Useful tools\n\n### Converting data to and from decimal\n\nTo convert data to felt use the [`utils.py`](utils.py) script\nTo open Python in interactive mode after running script\n\n  ```bash\n  python -i utils.py\n  ```\n\n  ```python\n  \u003e\u003e\u003e str_to_felt('ERC20-101')\n  1278752977803006783537\n  ```\n\n### Checking your progress \u0026 counting your points\n\n​\nYour 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!\n​\n\n- Go to the  [ERC20 counter](https://goerli.voyager.online/contract/0x228c0e6db14052a66901df14a9e8493c0711fa571860d9c62b6952997aae58b#readContract)  in voyager, in the \"read contract\" tab\n- Enter your address in decimal in the \"balanceOf\" function\n\nYou can also check your overall progress [here](https://starknet-tutorials.vercel.app)\n​\n\n### Transaction status\n\n​\nYou sent a transaction, and it is shown as \"undetected\" in voyager? This can mean two things:\n​\n\n- Your transaction is pending, and will be included in a block shortly. It will then be visible in voyager.\n- Your transaction was invalid, and will NOT be included in a block (there is no such thing as a failed transaction in Starknet).\n​\nYou can (and should) check the status of your transaction with the following URL  [https://alpha4.starknet.io/feeder_gateway/get_transaction_receipt?transactionHash=](https://alpha4.starknet.io/feeder_gateway/get_transaction_receipt?transactionHash=)  , where you can append your transaction hash.\n​\n\n​\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarknet-edu%2Fstarknet-erc20","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarknet-edu%2Fstarknet-erc20","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarknet-edu%2Fstarknet-erc20/lists"}