docs(readme): Token Vendor overview, contracts, usage & submission notes

0x4543 · 0x4543 · commit bbb9685590ba · 2025-11-03T00:14:50.000-05:00
diff --git a/README.md b/README.md
@@ -1,294 +1,142 @@
-# 🏗 Scaffold-ETH 2
+# 🏵️ Token Vendor — SpeedRunEthereum Challenge
 
-<h4 align="center">
-  <a href="https://docs.scaffoldeth.io">Documentation</a> |
-  <a href="https://scaffoldeth.io">Website</a>
-</h4>
+A minimal ERC‑20 + vending machine dApp built with **Scaffold‑ETH 2** (Next.js + Viem + Wagmi + Hardhat). The app lets users **buy** your ERC‑20, **transfer** it, and **sell it back** to the Vendor using the standard **approve → transferFrom** pattern.
 
-🧪 An open-source, up-to-date toolkit for building decentralized applications (dapps) on the Ethereum blockchain. It's designed to make it easier for developers to create and deploy smart contracts and build user interfaces that interact with those contracts.
-
-⚙️ Built using NextJS, RainbowKit, Hardhat, Wagmi, Viem, and Typescript.
-
-- ✅ **Contract Hot Reload**: Your frontend auto-adapts to your smart contract as you edit it.
-- 🪝 **[Custom hooks](https://docs.scaffoldeth.io/hooks/)**: Collection of React hooks wrapper around [wagmi](https://wagmi.sh/) to simplify interactions with smart contracts with typescript autocompletion.
-- 🧱 [**Components**](https://docs.scaffoldeth.io/components/): Collection of common web3 components to quickly build your frontend.
-- 🔥 **Burner Wallet & Local Faucet**: Quickly test your application with a burner wallet and local faucet.
-- 🔐 **Integration with Wallet Providers**: Connect to different wallet providers and interact with the Ethereum network.
-
-![Debug Contracts tab](https://github.com/scaffold-eth/scaffold-eth-2/assets/55535804/b237af0c-5027-4849-a5c1-2e31495cccb1)
-
-## Requirements
-
-Before you begin, you need to install the following tools:
-
-- [Node (>= v20.18.3)](https://nodejs.org/en/download/)
-- Yarn ([v1](https://classic.yarnpkg.com/en/docs/install/) or [v2+](https://yarnpkg.com/getting-started/install))
-- [Git](https://git-scm.com/downloads)
-
-# 🚩 Challenge: 🏵 Token Vendor 🤖
-
-![readme-2](https://raw.githubusercontent.com/scaffold-eth/se-2-challenges/challenge-token-vendor/extension/packages/nextjs/public/hero.png)
-
-🤖 Smart contracts are kind of like "always on" _vending machines_ that **anyone** can access. Let's make a decentralized, digital currency. Then, let's build an unstoppable vending machine that will buy and sell the currency. We'll learn about the "approve" pattern for ERC20s and how contract to contract interactions work.
-
-🏵 Create `YourToken.sol` smart contract that inherits the **ERC20** token standard from OpenZeppelin. Set your token to `_mint()` **1000** (* 10 ** 18) tokens to the `msg.sender`. Then create a `Vendor.sol` contract that sells your token using a payable `buyTokens()` function.
-
-🎛 Edit the frontend that invites the user to input an amount of tokens they want to buy. We'll display a preview of the amount of ETH it will cost with a confirm button.
-
-🔍 It will be important to verify your token's source code in the block explorer after you deploy. Supporters will want to be sure that it has a fixed supply and you can't just mint more.
-
-🌟 The final deliverable is an app that lets users purchase your ERC20 token, transfer it, and sell it back to the vendor. Deploy your contracts on your public chain of choice and then `yarn vercel` your app to a public web server. Submit the url on [SpeedRunEthereum.com](https://speedrunethereum.com)!
-
-> 💬 Meet other builders working on this challenge and get help in the [Challenge Telegram](https://t.me/joinchat/IfARhZFc5bfPwpjq)!
+> This repository is a completed submission for the **Token Vendor** challenge on [speedrunethereum.com](https://speedrunethereum.com/challenge/token-vendor).
 
 ---
 
-## Checkpoint 0: 📦 Environment 📚
-
-> Start your local network (a blockchain emulator in your computer):
-
-```
-yarn chain
-```
-
-> in a second terminal window, 🛰 deploy your contract (locally):
-
-```sh
-yarn deploy
-```
-
-> in a third terminal window, start your 📱 frontend:
-
-```sh
-yarn start
-```
+## 🚀 Live
 
-📱 Open http://localhost:3000 to see the app.
+- **App**: [https://nextjs-llt7ljkl8-dormins-projects.vercel.app/](https://nextjs-llt7ljkl8-dormins-projects.vercel.app/)
+- **Network**: Sepolia (chain id **11155111**)
+- **Contracts**
+  - `Vendor` — **0x98219Dc8ECAFDe3B5ed9dAd5DD8bc14963Dd0F87**
+  - `YourToken` — **0x35f5CB22E33E7063514a26b3D8680B3Bc86F8176**
 
-> 👩‍💻 Rerun `yarn deploy --reset` whenever you want to deploy new contracts to the frontend, update your current contracts with changes, or re-deploy it to get a fresh contract address.
+Paste any address above into a block explorer to view code/txs.
 
 ---
 
-⚠️ We have disabled AI in Cursor and VSCode and highly suggest that you do not enable it so you can focus on the challenge, do everything by yourself, and hence better understand and remember things. If you are using another IDE, please disable AI yourself.
+## ✨ What’s inside
 
-🔧 If you are a vibe-coder and don't care about understanding the syntax of the code used and just want to understand the general takeaways, you can re-enable AI by:
-- Cursor: remove `*` from `.cursorignore` file
-- VSCode: set `chat.disableAIFeatures` to `false` in `.vscode/settings.json` file
+- **YourToken.sol** — ERC‑20 (OpenZeppelin). Fixed supply, minted in the constructor to deployer.
+- **Vendor.sol** — Vending machine contract:
+  - `tokensPerEth = 100`
+  - `buyTokens()` payable — swaps ETH → tokens
+  - `sellTokens(uint256)` — requires prior `approve`, swaps tokens → ETH
+  - `withdraw()` — owner‑only, withdraws all ETH
+  - Events: `BuyTokens`, `SellTokens`, `Withdraw`
+- **Deploy script** transfers `1000 * 10**18` tokens to the Vendor and transfers Vendor ownership to the **frontend/owner** address.
 
 ---
 
-## Checkpoint 1: 🏵Your Token 💵
+## 🛠 Quickstart (local)
 
-> 👩‍💻 Edit `YourToken.sol` to inherit the **ERC20** token standard from OpenZeppelin
+> Recommended Node: **v20.18.x** (Hardhat does not officially support Node 21).
 
-> Mint **1000** (* 10 ** 18) to your frontend address using the `constructor()`.
+```bash
+# 1) Install deps (root)
+yarn
 
-(Your frontend address is the address in the top right of http://localhost:3000)
-
-> You can `yarn deploy --reset` to deploy your contract until you get it right.
-
-### 🥅 Goals
-
-- [ ] Can you check the `balanceOf()` your frontend address in the `Debug Contracts` tab? (`YourToken` contract)
-- [ ] Can you `transfer()` your token to another account and check _that_ account's `balanceOf`?
-
-![debugContractsYourToken](https://github.com/scaffold-eth/se-2-challenges/assets/55535804/5fb4daeb-5d05-4522-96b3-76f052a68418)
-
-> 💬 Hint: Use an incognito window to create a new address and try sending to that new address. Can use the `transfer()` function in the `Debug Contracts` tab.
-
----
-
-## Checkpoint 2: ⚖️ Vendor 🤖
-
-> 👩‍💻 Edit the `Vendor.sol` contract with a **payable** `buyTokens()` function
+# 2) Start local chain
+cd packages/hardhat
+yarn chain
 
-Use a price variable named `tokensPerEth` set to **100**:
+# 3) In a new terminal: deploy locally
+cd packages/hardhat
+yarn deploy --reset
 
-```solidity
-uint256 public constant tokensPerEth = 100;
+# 4) In a third terminal: start the dapp
+cd packages/nextjs
+yarn start
+# open http://localhost:3000
 ```
 
-> 📝 The `buyTokens()` function in `Vendor.sol` should use `msg.value` and `tokensPerEth` to calculate an amount of tokens to `yourToken.transfer()` to `msg.sender`.
-
-> 📟 Emit **event** `BuyTokens(address buyer, uint256 amountOfETH, uint256 amountOfTokens)` when tokens are purchased.
-
-Edit `packages/hardhat/deploy/01_deploy_vendor.ts` to deploy the `Vendor` (uncomment Vendor deploy lines).
+### Environment
 
-Uncomment the `Buy Tokens` sections in `packages/nextjs/app/token-vendor/page.tsx` to show the UI to buy tokens on the Token Vendor tab.
-
-### 🥅 Goals
-
-- [ ] When you try to buy tokens from the vendor, you should get an error: **'ERC20InsufficientBalance'**
-
-⚠️ This is because the Vendor contract doesn't have any YourTokens yet!
-
-⚔️ Side Quest: send tokens from your frontend address to the Vendor contract address and _then_ try to buy them.
-
-> ✏️ We can't hard code the vendor address like we did above when deploying to the network because we won't know the vendor address at the time we create the token contract.
-
-> ✏️ So instead, edit `YourToken.sol` to mint the tokens to the `msg.sender` (deployer) in the **constructor()**.
-
-> ✏️ Then, edit `deploy/01_deploy_vendor.ts` to transfer 1000 tokens to vendor address.
-
-```js
-await yourToken.transfer(vendorAddress, hre.ethers.parseEther("1000"));
+`packages/hardhat/.env`
 ```
-
-> 🔎 Look in `packages/nextjs/app/token-vendor/page.tsx` for code to uncomment to display the Vendor ETH and Token balances.
-
-> You can `yarn deploy --reset` to deploy your contract until you get it right.
-
-![TokenVendorBuy](https://github.com/scaffold-eth/se-2-challenges/assets/55535804/7669cc68-e942-4630-95c8-91cd21af5ba0)
-
-### 🥅 Goals
-
-- [ ] Does the `Vendor` address start with a `balanceOf` **1000** in `YourToken` on the `Debug Contracts` tab?
-- [ ] Can you buy **10** tokens for **0.1** ETH?
-- [ ] Can you transfer tokens to a different account?
-
-⚠️ Uncomment the import of Ownable.sol contract!
-
-> 📝 Edit `Vendor.sol` to inherit _Ownable_.
-
-`contract Vendor is Ownable {`
-
-> 📝 Change constructor of `Vendor.sol` to:
-
-`constructor(address tokenAddress) Ownable(msg.sender) {`
-
-In `deploy/01_deploy_vendor.ts` you will need to call `transferOwnership()` on the `Vendor` to make _your frontend address_ the `owner`:
-
-```js
-await vendor.transferOwnership("**YOUR FRONTEND ADDRESS**");
+ALCHEMY_API_KEY=
+ETHERSCAN_V2_API_KEY=
+DEPLOYER_PRIVATE_KEY_ENCRYPTED={...}
+FRONTEND_ADDRESS=0xyourOwnerWallet
 ```
 
-### 🥅 Goals
-
-- [ ] Is your frontend address the `owner` of the `Vendor`?
-
-> 📝 Finally, add a `withdraw()` function in `Vendor.sol` that lets the owner withdraw all the ETH from the vendor contract.
-
-### 🥅 Goals
-
-- [ ] Can **only** the `owner` withdraw the ETH from the `Vendor`?
-
-### ⚔️ Side Quests
+`packages/nextjs/.env.local` (optional; defaults are provided)
+```
+NEXT_PUBLIC_ALCHEMY_API_KEY=
+NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=
+```
 
-- [ ] What if you minted **2000** and only sent **1000** to the `Vendor`?
+> Ensure `.env*` files are **gitignored**. Do **not** commit private keys or encrypted key blobs.
 
 ---
 
-## Checkpoint 3: 🤔 Vendor Buyback 🤯
-
-👩‍🏫 The hardest part of this challenge is to build your `Vendor` to buy the tokens back.
-
-🧐 The reason why this is hard is the `approve()` pattern in ERC20s.
-
-😕 First, the user has to call `approve()` on the `YourToken` contract, approving the `Vendor` contract address to take some amount of tokens.
-
-🤨 Then, the user makes a _second transaction_ to the `Vendor` contract to `sellTokens(uint256 amount)`.
-
-🤓 The `Vendor` should call `yourToken.transferFrom(msg.sender, address(this), theAmount)` and if the user has approved the `Vendor` correctly, tokens should transfer to the `Vendor` and ETH should be sent to the user.
-
-> 📝 Edit `Vendor.sol` and add a `sellTokens(uint256 amount)` function!
-
-⚠️ You will need extra UI for calling `approve()` before calling `sellTokens(uint256 amount)`.
-
-🔨 Use the `Debug Contracts` tab to call the approve and sellTokens() at first but then...
-
-🔍 Look in the `packages/nextjs/app/token-vendor/page.tsx` for the extra approve/sell UI to uncomment!
-
-![VendorBuyBack](https://github.com/scaffold-eth/se-2-challenges/assets/55535804/99063aaa-368d-4156-997d-08dff99af11b)
-
-### 🥅 Goal
+## 🔍 Verify (optional)
 
-- [ ] Can you sell tokens back to the vendor?
-- [ ] Do you receive the right amount of ETH for the tokens?
+From `packages/hardhat`:
 
-### ⚔️ Side Quests
-
-- [ ] Should we disable the `owner` withdraw to keep liquidity in the `Vendor`?
-- [ ] It would be a good idea to display Sell Token Events. Create an **event** `SellTokens(address seller, uint256  amountOfTokens, uint256 amountOfETH)` and `emit` it in your `Vendor.sol` and uncomment `SellTokens Events` section in your `packages/nextjs/app/events/page.tsx` to update your frontend.
-
-  ![Events](https://github.com/scaffold-eth/se-2-challenges/assets/55535804/662c96b5-d53f-4efa-af4a-d3106bfd47f0)
-
-### ⚠️ Test it!
-
-- Now is a good time to run `yarn test` to run the automated testing function. It will test that you hit the core checkpoints. You are looking for all green checkmarks and passing tests!
+```bash
+yarn verify --network sepolia 0x35f5CB22E33E7063514a26b3D8680B3Bc86F8176   # YourToken (no args)
+yarn verify --network sepolia 0x98219Dc8ECAFDe3B5ed9dAd5DD8bc14963Dd0F87  "0x35f5CB22E33E7063514a26b3D8680B3Bc86F8176"  # Vendor(tokenAddress)
+```
 
 ---
 
-## Checkpoint 4: 💾 Deploy your contracts! 🛰
-
-📡 Edit the `defaultNetwork` to [your choice of public EVM networks](https://ethereum.org/en/developers/docs/networks/) in `packages/hardhat/hardhat.config.ts`
-
-🔐 You will need to generate a **deployer address** using `yarn generate` This creates a mnemonic and saves it locally.
+## 📋 How to use (on Sepolia)
 
-👩‍🚀 Use `yarn account` to view your deployer account balances.
-
-⛽️ You will need to send ETH to your deployer address with your wallet, or get it from a public faucet of your chosen network.
-
-🚀 Run `yarn deploy` to deploy your smart contract to a public network (selected in `hardhat.config.ts`)
-
-> 💬 Hint: You can set the `defaultNetwork` in `hardhat.config.ts` to `sepolia` or `optimismSepolia` **OR** you can `yarn deploy --network sepolia` or `yarn deploy --network optimismSepolia`.
+1. Connect wallet (burner or MetaMask) on Sepolia.
+2. **Buy**: enter tokens to buy → wallet pays `amount / tokensPerEth` ETH.
+3. **Transfer**: send tokens to any address via `transfer`.
+4. **Sell**: `approve(Vendor, amount)` then `sellTokens(amount)` to receive ETH back.
 
 ---
 
-## Checkpoint 5: 🚢 Ship your frontend! 🚁
-
-✏️ Edit your frontend config in `packages/nextjs/scaffold.config.ts` to change the `targetNetwork` to `chains.sepolia` (or `chains.optimismSepolia` if you deployed to OP Sepolia)
-
-💻 View your frontend at http://localhost:3000 and verify you see the correct network.
-
-📡 When you are ready to ship the frontend app...
+## 🧩 Tech stack
 
-📦 Run `yarn vercel` to package up your frontend and deploy.
+- Solidity, Hardhat, hardhat‑deploy
+- OpenZeppelin ERC20, Ownable
+- Next.js (app router), Viem, Wagmi, RainbowKit
+- Tailwind + daisyUI
 
-> You might need to log in to Vercel first by running `yarn vercel:login`. Once you log in (email, GitHub, etc), the default options should work.
-
-> If you want to redeploy to the same production URL you can run `yarn vercel --prod`. If you omit the `--prod` flag it will deploy it to a preview/test URL.
-
-> Follow the steps to deploy to Vercel. It'll give you a public URL.
-
-> 🦊 Since we have deployed to a public testnet, you will now need to connect using a wallet you own or use a burner wallet. By default 🔥 `burner wallets` are only available on `hardhat` . You can enable them on every chain by setting `onlyLocalBurnerWallet: false` in your frontend config (`scaffold.config.ts` in `packages/nextjs/`)
-
-#### Configuration of Third-Party Services for Production-Grade Apps.
-
-By default, 🏗 Scaffold-ETH 2 provides predefined API keys for popular services such as Alchemy and Etherscan. This allows you to begin developing and testing your applications more easily, avoiding the need to register for these services.
-This is great to complete your **SpeedRunEthereum**.
-
-For production-grade applications, it's recommended to obtain your own API keys (to prevent rate limiting issues). You can configure these at:
-
-- 🔷`ALCHEMY_API_KEY` variable in `packages/hardhat/.env` and `packages/nextjs/.env.local`. You can create API keys from the [Alchemy dashboard](https://dashboard.alchemy.com/).
+---
 
-- 📃`ETHERSCAN_API_KEY` variable in `packages/hardhat/.env` with your generated API key. You can get your key [here](https://etherscan.io/myapikey).
+## ✅ Submission notes
 
-> 💬 Hint: It's recommended to store env's for nextjs in Vercel/system env config for live apps and use .env.local for local testing.
+- `tokensPerEth` hard‑coded to **100**.
+- Vendor preloaded with **1000 YTK** in the deploy script.
+- Vendor ownership transferred to `FRONTEND_ADDRESS` from `.env`.
+- Frontend route: `/token-vendor` includes **Buy / Transfer / Approve+Sell** UX and shows balances.
 
 ---
 
-## Checkpoint 6: 📜 Contract Verification
-
-Run the `yarn verify --network your_network` command to verify your contracts on etherscan 🛰
+## 🔐 Security
 
-👀 You may see an address for both YourToken and Vendor. You will want the Vendor address.
-
-👉 Search this address on [Sepolia Etherscan](https://sepolia.etherscan.io/) (or [Optimism Sepolia Etherscan](https://sepolia-optimism.etherscan.io/) if you deployed to OP Sepolia) to get the URL you submit to 🏃‍♀️[SpeedRunEthereum.com](https://speedrunethereum.com).
+- Addresses are public by design. **Never** commit private keys, mnemonics or the encrypted key JSON.
+- Keep owner funds in a non‑burner wallet.
 
 ---
 
-> 🏃 Head to your next challenge [here](https://speedrunethereum.com).
+## 📦 Scripts
 
-> 💬 Problems, questions, comments on the stack? Post them to the [🏗 scaffold-eth developers chat](https://t.me/joinchat/F7nCRK3kI93PoCOk)
+```bash
+# Deploy to Sepolia
+cd packages/hardhat
+yarn deploy --network sepolia --reset
 
-## Documentation
+# Verify on Sepolia (see Verify above)
 
-Visit our [docs](https://docs.scaffoldeth.io) to learn how to start building with Scaffold-ETH 2.
+# Build frontend
+cd packages/nextjs
+yarn build
 
-To know more about its features, check out our [website](https://scaffoldeth.io).
+# Deploy frontend to Vercel (once linked)
+vercel --prod
+```
 
-## Contributing to Scaffold-ETH 2
+---
 
-We welcome contributions to Scaffold-ETH 2!
+## 📄 License
 
-Please see [CONTRIBUTING.MD](https://github.com/scaffold-eth/scaffold-eth-2/blob/main/CONTRIBUTING.md) for more information and guidelines for contributing to Scaffold-ETH 2.
+MIT
