docs: review polygon basics & gasless lessons

Author: ines-toupeira

src/content/tutorial/5-polygon-basics/1-introduction/content.md

@@ -13,10 +13,43 @@ terminal:
 
 # Introduction to Polygon
 
+Before starting this section, you should have:
+
+- Completed Sections 1–4 of this tutorial
+- Basic understanding of EVM wallets and blockchain transactions
+- MetaMask or similar wallet extension installed
+
+## Learning Objectives
+
+By the end of this section, you will be able to:
+
+- Set up and connect a wallet to the Polygon network (testnet and mainnet)
+- Distinguish between native POL tokens and ERC-20 tokens like USDC
+- Interact with ERC-20 token contracts on Polygon
+- Send USDC transactions on Polygon testnet
+- Verify transactions on Polygonscan block explorer
+
+---
+
 Welcome to Polygon Basics! Over the next three lessons you will assemble a complete transaction workflow on Polygon: create wallets, fund them with test assets, and move both native POL and ERC20 tokens. Each lesson flows step by step so you can focus on the concepts rather than deciphering shorthand.
 
+The Nimiq Wallet supports stablecoins on EVM chains. The concepts you learn here (wallets, providers, POL gas, ERC20) are the foundation for Part 6 where we implement Nimiq‑style gasless transfers with OpenGSN.
+
 ---
 
+> **Prerequisites & Safety**
+>
+> - Use a fresh test wallet. Don't reuse mainnet or exchange keys.
+> - You will add a `PRIVATE_KEY` in a `.env` file in Lesson 2; no setup is needed yet.
+> - Faucets provide the test tokens you will need later; nothing to do in this introduction.
+
+> **Terminology**
+>
+> - **POL**: Polygon's native token (formerly MATIC). Gas is paid in POL.
+> - **EVM**: Ethereum Virtual Machine; the execution environment used by Polygon.
+> - **ERC20**: Token standard for fungible tokens (for example, USDC has 6 decimals).
+> - **Provider**: An RPC endpoint your code connects to (for example, `https://rpc-amoy.polygon.technology`).
+
 ## Why Polygon?
 
 **Polygon** is an Ethereum Layer 2 network designed to feel familiar while solving Ethereum's biggest pain points.
@@ -28,40 +61,50 @@ Welcome to Polygon Basics! Over the next three lessons you will assemble a compl
 
 Think of Polygon as Ethereum's faster, more affordable sibling that still shares the family DNA.
 
+### Note on Polygon's Native Token
+
+Polygon's native token was rebranded from **MATIC** to **POL** in 2024.
+
+- **On Polygon mainnet:** Use POL (contract not applicable; native asset)
+- **On Polygon testnet (Amoy):** Use test POL from the faucet
+- **In code references:** You may see both names in older documentation; they refer to the same asset
+
+This tutorial uses **POL** throughout.
+
 ---
 
 ## Meet Polygon Amoy
 
-For this section we use **Polygon Amoy**, the current Polygon testnet. It mirrors mainnet behavior while using valueless tokens, which makes it ideal for experimentation.
+For this section we use **Polygon Amoy**, the current Polygon testnet. It mirrors mainnet behavior with valueless test tokens, which makes it ideal for experimentation.
 
 - **Network Name**: Polygon Amoy Testnet
 - **Chain ID**: 80002
 - **RPC URL**: https://rpc-amoy.polygon.technology
 - **Block Explorer**: https://amoy.polygonscan.com
 - **Native Token**: POL (pays gas fees)
 
-Because every token on Amoy is free, you can try ideas, make mistakes, and rerun scripts without worrying about real money.
+Because test tokens on Amoy are free, you can try ideas, make mistakes, and rerun scripts without worrying about real money.
 
 ---
 
 ## What You Will Build
 
-By the end of this part you will have a working toolkit for everyday Polygon development:
+By the end of this part, you will have a working toolkit for everyday Polygon development:
 
-### Lesson 2: Polygon Wallet Setup & Faucets
+### Polygon Wallet Setup & Faucets
 
 - Generate an Ethereum-compatible wallet with ethers.js.
 - Connect that wallet to Polygon Amoy.
 - Collect free POL and USDC from public faucets.
 - Read balances programmatically so you can verify funding.
 
-### Lesson 3: Sending POL Transactions
+### Sending POL Transactions
 
 - Craft and broadcast native POL transfers.
 - Inspect gas usage and confirmation receipts.
 - Follow the transaction lifecycle on PolygonScan.
 
-### Lesson 4: ERC20 Tokens & USDC Transfers
+### ERC20 Tokens & USDC Transfers
 
 - Review the ERC20 interface and why it matters.
 - Interact with token contracts through ABIs.
@@ -98,10 +141,17 @@ The script demonstrates how to:
 3. Send POL to another address.
 4. Transfer USDC (an ERC20 token) safely.
 
-> 💡 **Heads-up**: You will still need faucet funds before the demo shows non-zero balances. Lesson 2 covers that process. Until then you will see warnings about missing tokens.
+> 💡 **Heads-up**: You will still need faucet funds before the demo shows non-zero balances. Lesson 2 covers that process. Until then, you will see warnings about missing tokens.
+
+## What the Demo Shows
+
+- The terminal prints a wallet address and environment details.
+- Balances start at zero until you use faucets in Lesson 2.
+- You will see warnings about missing tokens; they are expected.
+- The editor opens `/index.js`. Feel free to skim it; you do not need to change anything in this lesson.
 
 ---
 
 ## Next Up
 
-Continue to **Lesson 2: Polygon Wallet Setup & Faucets** to create your first Polygon wallet and stock it with testnet tokens.
+Continue to **Polygon Wallet Setup & Faucets** to create your first Polygon wallet and stock it with testnet tokens.

src/content/tutorial/5-polygon-basics/2-wallet-and-faucets/content.md

@@ -24,7 +24,7 @@ By the end of this lesson you will:
 - **Generate an Ethereum-compatible wallet** with ethers.js and understand the difference between its private key and public address.
 - **Connect the wallet to Polygon Amoy**, Polygon's public testnet.
 - **Collect free POL** to pay for gas in upcoming lessons.
-- **Collect free USDC** so you can practice ERC20 transfers later on.
+- **Collect free USDC** so you can practice ERC20 transfers later.
 - **Store sensitive credentials safely** using environment variables.
 
 ---
@@ -38,7 +38,7 @@ Wallets sit at the heart of every Web3 interaction. Whether you are experimentin
 - Verify balances before submitting transactions.
 - Reuse credentials across scripts without exposing them.
 
-Master these fundamentals now and everything that follows will feel natural.
+Master these fundamentals now, and everything that follows will feel natural.
 
 ---
 
@@ -51,7 +51,7 @@ We will work on **Polygon Amoy**, a no-stakes environment that mirrors Polygon m
 - **RPC URL**: https://rpc-amoy.polygon.technology
 - **Chain ID**: 80002
 
-Because tokens on Amoy have zero real-world value, you can experiment freely and rerun scripts as often as you like.
+Because test tokens on Amoy have zero real-world value, you can experiment freely and rerun scripts as often as you like.
 
 ---
 
@@ -107,11 +107,15 @@ You should see `0.0 POL`, confirming the wallet has not been funded yet.
 Faucets distribute play tokens for testnets. Follow these steps to fund your wallet with POL:
 
 1. Copy the address printed in your console.
-2. Visit the Polygon faucet at **https://faucet.polygon.technology/**.
+2. Visit the Polygon faucet at https://faucet.polygon.technology/.
 3. Choose "Polygon Amoy" from the dropdown.
 4. Paste your address and submit the request.
 
-Within roughly 30 seconds the faucet should confirm the transfer. Run your script again to verify that the POL balance increased.
+Within roughly 30 seconds, the faucet should confirm the transfer. Run your script again to verify that the POL balance increased. You can also check your address on the explorer: https://amoy.polygonscan.com/address/<your-address>
+
+> Faucet tips
+>
+> If the faucet rate-limits you, wait a few minutes and retry. Make sure “Polygon Amoy” is selected. Some public faucets require sign-in or a CAPTCHA.
 
 ---
 
@@ -121,19 +125,23 @@ Later lessons rely on an ERC20 token, so grab some USDC while you are here. You
 
 **Option 1: Polygon Faucet** (also gives POL)
 
-1. Visit **https://faucet.polygon.technology/**.
+1. Visit https://faucet.polygon.technology/.
 2. Choose "Polygon Amoy" from the dropdown.
 3. Paste your wallet address and submit.
 
 **Option 2: Circle Faucet**
 
-1. Open **https://faucet.circle.com/**.
+1. Open https://faucet.circle.com/.
 2. Select "Polygon Amoy" as the network.
 3. Paste your wallet address.
 4. Complete the CAPTCHA and submit.
 
 To inspect your USDC balance you must query the token contract directly:
 
+> Note on test tokens
+>
+> USDC testnet addresses can change. If the address returns zero unexpectedly, verify the current Amoy USDC address from official sources (faucet/docs) before assuming a code issue.
+
 ```js
 const USDC_ADDRESS = '0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582'
 const USDC_ABI = [
@@ -181,4 +189,4 @@ You now have everything required for real Polygon workflows:
 - ✅ USDC for ERC20 experiments.
 - ✅ Environment variable management for safe credential storage.
 
-In the next lesson you will send your first on-chain POL transfer and watch it confirm in real time.
+In the next lesson, you will send your first on-chain POL transfer and watch it confirm in real time.

src/content/tutorial/5-polygon-basics/3-sending-pol/content.md

@@ -27,7 +27,7 @@ With your wallet funded, it is time to perform a live transaction on Polygon Amo
 
 Keep a small buffer of POL in your wallet; even ERC20 transfers consume it for gas.
 
-> 💡 **Nimiq contrast:** Nimiq blockchain has zero transaction fees. No gas token, no fee calculations—just send. We'll revisit this advantage in Section 6 when we tackle gasless transactions!
+> 💡 **Nimiq contrast:** Nimiq blockchain has zero transaction fees. No gas token, no fee calculations—just send. We will revisit this advantage in Section 6 when we tackle gasless transactions!
 
 ---
 
@@ -149,7 +149,7 @@ Gas Fee = Gas Used × Gas Price
 - **Gas Used** represents the work done (a simple transfer is roughly 21,000 units).
 - **Gas Price** fluctuates with network demand.
 
-On Polygon Amoy these fees are tiny, but cultivating the habit of checking them now will pay off on higher-cost networks.
+On Polygon Amoy, these fees are tiny, but cultivating the habit of checking them now will pay off on higher-cost networks.
 
 ---
 

src/content/tutorial/5-polygon-basics/4-erc20-usdc/content.md

@@ -13,9 +13,7 @@ terminal:
 
 # ERC20 Tokens & USDC Transfers
 
-# ERC20 Tokens & USDC Transfers
-
-Native POL transfers are only half the story on Polygon. The majority of assets you will handle live inside smart contracts that follow the ERC20 standard. In this lesson you will apply everything you learned about wallets and providers to interact with **USDC**, a widely used stablecoin on Polygon Amoy.
+Native POL transfers are only half the story on Polygon. The majority of assets you will handle live inside smart contracts that follow the ERC20 standard. In this lesson, you will apply everything you learned about wallets and providers to interact with **USDC**, a widely used stablecoin on Polygon Amoy.
 
 ---
 
@@ -133,7 +131,7 @@ Key differences from the POL workflow:
 
 ## Step 5: Reconcile Balances
 
-After confirmation, confirm that both your USDC and POL balances changed as expected.
+After confirmation, check that both your USDC and POL balances have changed as expected.
 
 ```js
 const newBalance = await usdc.balanceOf(wallet.address)
@@ -150,8 +148,8 @@ console.log('\n⛽ Gas paid in POL:', ethers.utils.formatEther(polBalance))
 
 You should see:
 
-- Your USDC balance drop by the transfer amount.
-- Your POL balance dip slightly from gas costs.
+- Your USDC balance drops by the transfer amount.
+- Your POL balance dips slightly from gas costs.
 - The recipient's USDC balance increases accordingly.
 
 ---
@@ -163,7 +161,7 @@ ERC20 transfers invoke smart contract logic, so they use more gas than native tr
 - Native POL transfer: about 21,000 gas.
 - ERC20 transfer: typically 50,000 to 65,000 gas.
 
-Polygon's low fees mean the difference is small, but it is important to keep in mind on higher-cost networks.
+Polygon’s low fees mean the difference is small, but it is important to keep in mind on higher-cost networks.
 
 ---
 

src/content/tutorial/6-gasless-transfers/1-wallet-setup/content.md

@@ -13,7 +13,7 @@ terminal:
 
 # Mainnet Wallet Setup
 
-Before working with gasless transactions on Polygon mainnet, you need a wallet with real funds. This lesson generates a fresh wallet and shows you how to secure it properly.
+Before working with gasless transactions on Polygon mainnet, you need a wallet with real funds. This lesson generates a new wallet and shows you how to secure it properly.
 
 ---
 
@@ -67,7 +67,7 @@ console.log('Mnemonic:', wallet.mnemonic.phrase)
 
 For a better UX, import your 24-word mnemonic into the Nimiq Wallet:
 
-1. Visit **https://wallet.nimiq.com**
+1. Visit https://wallet.nimiq.com
 2. Select "Import with Recovery Words"
 3. Paste your 24-word phrase
 4. Access your wallet through a friendly interface
@@ -78,37 +78,55 @@ The Nimiq Wallet supports Polygon and makes managing tokens easier than the comm
 
 ## Get Mainnet Funds
 
-You need two types of tokens:
+### USDT (for core gasless transfers)
 
-### USDC (for transfers)
+You will use USDT for the baseline and OpenGSN lessons (Lessons 3–6). There is no public faucet for USDT on Polygon mainnet, so you must:
 
-Visit **https://faucet.circle.com/** to get testnet USDC that works on mainnet. You will need 2-5 USDC to complete the gasless lessons.
+- Purchase USDT on an exchange and withdraw to Polygon
+- Swap into USDT on Polygon using a DEX such as Uniswap
+- Bridge USDT from Ethereum mainnet
 
-### POL (for gas in Lesson 2)
+Aim for 2–5 USDT to comfortably complete the exercises.
 
-Visit **https://faucet.polygon.technology/** to get a small amount of POL. You only need ~0.1 POL for the baseline gasful transaction in the next lesson.
+### USDC (for the permit lesson)
 
-### USDT (no faucet available)
+USDC is only needed for the EIP-2612 permit lesson (Lesson 7). For Polygon mainnet USDC you must use a real liquidity source. Typical options are:
 
-There is no public faucet for USDT on Polygon mainnet. If you want to follow along with USDT examples instead of USDC, you will need to:
+- Purchase USDC on an exchange and withdraw directly to Polygon
+- Bridge USDC from another chain (for example Ethereum mainnet) using a trusted bridge
+- Swap into USDC on Polygon via a DEX such as Uniswap
 
-- Purchase USDT on an exchange and withdraw to Polygon
-- Swap USDC for USDT using a DEX like Uniswap
-- Bridge USDT from Ethereum mainnet
+If you want to practice on testnets before touching mainnet, you can use https://faucet.circle.com/ to obtain **testnet** USDC on supported networks. That testnet USDC is not usable on Polygon mainnet.
+
+### POL (for gas in gasful baseline lesson)
+
+For Polygon mainnet POL you cannot use the Polygon faucet (it only serves testnets like Amoy). Instead:
 
-> For this tutorial, USDC is recommended since it has faucet access.
+- Acquire POL on an exchange and withdraw to Polygon mainnet, or
+- Bridge POL (or wrapped MATIC) from another network.
+
+You only need ~0.1 POL for the baseline gasful transaction in the next lesson, but it must be real mainnet POL.
 
 ---
 
 ## Save Your Private Key
 
-Copy your **private key** from the terminal output. You will paste it directly into the code files in the following lessons. Each lesson will have a placeholder like:
+Copy your **private key** from the terminal output. In the following lessons, load it from an environment variable instead of hardcoding it in source code. For example:
+
+```bash
+# .env
+SENDER_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_FROM_LESSON_1
+```
 
 ```js
-const PRIVATE_KEY = '0xPASTE_YOUR_PRIVATE_KEY_HERE_FROM_LESSON_1'
+import dotenv from 'dotenv'
+
+dotenv.config()
+
+const wallet = new ethers.Wallet(process.env.SENDER_PRIVATE_KEY, provider)
 ```
 
-Replace that placeholder with your actual private key. Never commit files with your real private key to version control.
+Never commit `.env` files with real private keys to version control.
 
 ---
 
@@ -124,4 +142,4 @@ Before moving forward, confirm:
 
 ## Next Up
 
-In **Lesson 2: Introduction to Gasless Transactions**, you will learn why gasless transactions matter and see the architecture that makes them possible.
+In **Introduction to Gasless Transactions**, you will learn why gasless transactions matter and see the architecture that makes them possible.