EffortToken.sol

This multi-line comment uses NatSpec (Ethereum Natural Language Specification) to document the contract. Tools like Etherscan, Remix, and documentation generators parse these @tags automatically. Think of it as a README that lives inside the code.

• ▸@title — the human-readable name of the contract, displayed prominently on Etherscan
• ▸@dev — technical notes for developers reading or auditing the code
• ▸The bullet list documents the educational concepts this contract demonstrates — good practice for any teaching-oriented codebase

This single line does three powerful things: (1) declares a new contract named EffortToken, (2) inherits ALL of ERC20's functionality (13+ functions), and (3) inherits Ownable's access control. The 'is' keyword is Solidity's inheritance syntax — similar to 'extends' in Java or TypeScript.

• ▸'contract' is like 'class' in other languages — it defines a deployable unit of code with state and functions
• ▸'is ERC20, Ownable' — multiple inheritance, resolved via C3 linearization (rightmost parent wins on conflicts)
• ▸After this line, EffortToken has: balanceOf(), transfer(), approve(), transferFrom(), totalSupply(), allowance(), owner(), transferOwnership(), and more — all inherited
• ▸The opening brace '{' starts the contract body — everything until the matching '}' on line 208 is part of EffortToken

This state variable stores the address of the TaskRegistry contract — the ONLY address allowed to call the mint() function. It acts as a gatekeeper: when mint() is called, the contract checks if msg.sender matches this address. If not, the transaction reverts.

• ▸'address public' — a 20-byte Ethereum address with an auto-generated getter function
• ▸Defaults to address(0) on deployment — meaning minting is disabled until the owner calls setTaskRegistry()
• ▸The @notice comment is rendered by Etherscan, helping users understand the variable's purpose
• ▸This pattern is called 'authorization by address' — a simple but effective access control mechanism

Mirrors taskRegistry but for the spending/burn side. Only the ContentStore contract at this address can call spendForContent() to burn a user's tokens. This creates a separation of concerns: the token contract handles the mechanics, while the ContentStore handles the business logic of content purchases.

• ▸Same pattern as taskRegistry — public address with authorization checks in the spending function
• ▸Also defaults to address(0), disabling content purchases until configured
• ▸Having separate authorized addresses for minting and burning means you can upgrade each system independently

Emitted every time a user earns EFFORT tokens by completing a lesson or quiz. This is the primary reward signal — our frontend watches for this event to show 'You earned X EFFORT!' notifications in real-time. Each parameter tells a piece of the story.

• ▸address indexed to — the wallet that received tokens. 'indexed' makes it searchable: you can query 'show me all mints to 0xABC...' efficiently
• ▸uint256 amount — how many tokens were minted, in wei (10^18 = 1 EFFORT). Always in raw units, never formatted
• ▸string taskType — 'QUIZ' or 'LESSON'. Note: strings can't be indexed (they'd be hashed), so this goes in the event data blob
• ▸uint256 taskId — links this mint back to a specific task, enabling audit trails like 'Quiz #7 rewarded 5 EFFORT to 0xABC'
• ▸uint256 timestamp — block.timestamp at the moment of minting. Note: this is block time, not wall-clock time — miners have slight control over it

The mirror of TokensMinted — emitted when tokens are burned for premium content access. This event creates an on-chain receipt of every purchase. Analytics dashboards can track spending patterns, popular content, and the overall token velocity.

• ▸address indexed user — who spent the tokens. Indexed so you can query a user's full purchase history
• ▸uint256 amount — tokens burned (permanently removed from circulation)
• ▸uint256 contentId — which piece of content was purchased. The ContentStore contract maps IDs to actual content
• ▸uint256 timestamp — when the purchase happened. Useful for time-series analytics of spending patterns

Emitted when the owner changes which contract can mint tokens. This is a critical admin action — if the taskRegistry is changed, a completely different contract controls token creation. The event records BOTH the old and new addresses so anyone can trace the history.

• ▸address indexed oldTaskRegistry — the previous minter address. 'indexed' allows filtering by either old or new address
• ▸address indexed newTaskRegistry — the new minter address. Both being indexed uses 2 of the 3 available topic slots
• ▸This pattern (old, new) is standard for admin events — it answers 'what changed FROM and TO?'

Same pattern as TaskRegistryUpdated but for the content store address. Emitted when the owner changes which contract can burn tokens for content purchases. Together, these two admin events create a complete audit trail of all configuration changes.

• ▸Follows the exact same (old, new) pattern — consistency in event design makes frontend code simpler
• ▸Both parameters are indexed for efficient querying of admin action history
• ▸Monitoring services can alert on these events to detect unauthorized admin activity

Thrown when someone other than the TaskRegistry tries to call mint(). The error includes the caller's address as a parameter — this is incredibly useful for debugging because the frontend can decode the error and show exactly WHO tried to mint and was rejected.

• ▸The parameter (address caller) captures msg.sender at the point of failure
• ▸Used in: mint() function, line 136
• ▸In the frontend, viem's decodeErrorResult can parse this into a human-readable message
• ▸The 4-byte selector for this error is the first 4 bytes of keccak256('UnauthorizedMinter(address)')

The spending equivalent of UnauthorizedMinter. Thrown when any address other than the ContentStore tries to burn tokens via spendForContent(). This prevents malicious actors from destroying other users' tokens.

• ▸Same pattern as UnauthorizedMinter — includes the unauthorized caller's address
• ▸Used in: spendForContent() function, line 162
• ▸Without this check, anyone could call spendForContent and burn your tokens

A guard against accidentally using the zero address (0x0000...0000). Sending tokens to the zero address effectively burns them with no record, and setting the taskRegistry to zero would permanently disable minting. This single error is reused across multiple functions.

• ▸Used in: setTaskRegistry(), setContentStore(), mint(), spendForContent() — reused 4 times
• ▸address(0) is the 'null' of Ethereum — it's a real address but no one controls the private key
• ▸Reusing errors across functions reduces bytecode size compared to having separate error types

Prevents minting or burning zero tokens. While a zero-amount operation wouldn't break anything technically, it would waste gas and pollute the event log with meaningless entries. This check keeps the contract's on-chain history clean and intentional.

• ▸Used in: mint() and spendForContent() — reused 2 times
• ▸A zero-amount mint would still emit events and cost gas — this check saves the user from wasting money
• ▸Some protocols allow zero-amount transfers for UX reasons (e.g., to trigger side effects), but for minting/burning it's always a mistake

Documents the constructor's behavior. Notice it explicitly states the token name, symbol, and decimals — these are the three pieces of metadata every wallet and DEX reads to display your token correctly.

• ▸Token Name: 'Effort Token' — displayed in wallet UIs and on Etherscan
• ▸Token Symbol: ' EFFORT' — the ticker shown in trading interfaces and balances
• ▸Decimals: 18 — the standard. 1 EFFORT in the UI = 1,000,000,000,000,000,000 in the contract

This one line does everything: creates the token, names it, and sets the owner. The empty body {} means no additional initialization is needed — all the work is done by the parent constructors. This is a deliberately minimal constructor.

• ▸ERC20("Effort Token", " EFFORT") — calls the ERC20 parent constructor, which stores the name and symbol internally
• ▸Ownable(msg.sender) — calls the Ownable parent constructor, setting the deployer as the contract owner
• ▸The empty {} body means no initial token supply — totalSupply starts at 0
• ▸msg.sender here is the deployment wallet — this address becomes the permanent owner (until transferred)
• ▸constructor() has no name and no return type — it's a special function that only runs once during deployment

The NatSpec documents what this function does, who can call it, and what the parameter means. The function signature reveals key design choices: 'external' (can't be called internally), 'onlyOwner' (restricted to the contract owner).

• ▸external — saves gas vs public because arguments are read directly from calldata, not copied to memory
• ▸onlyOwner — a modifier from Ownable that adds require(msg.sender == owner()) before the function body runs
• ▸@param _taskRegistry — the underscore prefix is a Solidity naming convention for function parameters to distinguish them from state variables

The function body follows the Check-Effects-Interactions pattern, the golden rule of secure Solidity. Step 1: Check (validate input). Step 2: Effects (update state). Step 3: Interactions (emit event). Each step has a specific security purpose.

• ▸Line 93: CHECK — revert if zero address. This prevents accidentally bricking the mint system
• ▸Line 95: Save old value BEFORE updating — if you saved it after, you'd lose the original for the event
• ▸Line 96: EFFECT — update the state variable. After this line, mint() will accept calls from the new address
• ▸Line 98: INTERACTION — emit the event recording the change. This creates a permanent, immutable audit trail
• ▸If the zero-address check reverts, the state change on line 96 is rolled back — this is atomic transaction behavior

An exact mirror of setTaskRegistry but for the ContentStore address. Identical structure demonstrates code consistency — a hallmark of well-written contracts. Both admin functions use the same validate → update → emit pattern.

• ▸Same zero-address check, same old-value capture, same state update, same event emission
• ▸Code duplication here is acceptable because each function manages a different state variable with its own event
• ▸In more complex contracts, you might abstract this into a single internal function — but here, clarity wins over DRY

The NatSpec fully documents every parameter with its type, purpose, and format. Notice 'string calldata taskType' — the calldata keyword is a gas optimization specific to external functions. The function takes 4 parameters but only 2 (to, amount) affect the actual mint; the other 2 are purely for event logging.

• ▸@param to — the recipient. Could be any address including contracts (tokens sent to a contract without a receive function are stuck forever)
• ▸@param amount — in wei (10^18 = 1 EFFORT). The frontend uses ethers.parseEther() to convert human-readable amounts
• ▸@param taskType — a string like 'QUIZ' or 'LESSON'. Using calldata instead of memory saves gas because the data isn't copied
• ▸@param taskId — links this mint to a specific task for auditability. The TaskRegistry assigns these IDs
• ▸The 'external' keyword means this function CANNOT be called internally — only from other contracts or EOAs

Three consecutive validation checks form a security gauntlet. Each check uses the modern 'if/revert' pattern instead of require() strings. If ANY check fails, the entire transaction reverts — no state changes, no events, minimal gas wasted.

• ▸Line 136: ACCESS CHECK — 'Is the caller the TaskRegistry?' This is THE critical security line. Without it, anyone could mint unlimited tokens
• ▸Line 137: ZERO ADDRESS CHECK — Prevents minting to address(0), which would burn the tokens immediately with no way to recover them
• ▸Line 138: ZERO AMOUNT CHECK — Prevents meaningless mints that waste gas and pollute the event log
• ▸The order matters: check authorization first (cheapest to verify), then validate inputs
• ▸If the access check fails, the custom error UnauthorizedMinter(msg.sender) is returned — the frontend can decode who tried to mint

This single line is where tokens are born. OpenZeppelin's internal _mint function increases totalSupply by 'amount', credits 'to' with the new tokens, and emits a standard Transfer(address(0), to, amount) event. The address(0) as 'from' is how the ERC-20 standard represents creation from nothing.

• ▸_mint is an INTERNAL function — only callable from within this contract (or children), never directly from outside
• ▸It updates two storage slots: totalSupply (global counter) and balances[to] (recipient's balance)
• ▸It automatically emits Transfer(address(0), to, amount) — this is the standard ERC-20 mint event that all block explorers recognize
• ▸If 'to' is a contract, _mint does NOT check if it can handle tokens (unlike ERC-721's safeMint). ERC-20 doesn't have a 'safe' mint pattern

After the mint succeeds, this event broadcasts the full context to the world. While _mint already emitted a standard Transfer event, our custom event adds the taskType and taskId — information that helps frontends show rich notifications and enables analytics on learning activity.

• ▸block.timestamp is the timestamp of the block containing this transaction — set by the validator/miner
• ▸This event is what our frontend's useWatchContractEvent listens for to show 'You earned EFFORT!' notifications
• ▸The event is emitted AFTER _mint() — if _mint reverted (e.g., overflow), this event would never fire
• ▸Indexing services like The Graph subscribe to this event to build queryable databases of all minting activity

Similar structure to mint() but with different parameters and purpose. This function destroys tokens instead of creating them. Notice 'user' instead of 'to' — because the ContentStore is calling this ON BEHALF of the user, we need to explicitly pass whose tokens to burn.

• ▸@param user — whose tokens to burn. The ContentStore passes this — it's NOT msg.sender (which would be the ContentStore's address)
• ▸@param amount — tokens to destroy. The ContentStore must verify the user agreed to this spending before calling
• ▸@param contentId — identifies what was purchased. The ContentStore maps these IDs to actual premium content
• ▸The NatSpec calls out the burn pattern explicitly — educational clarity is part of this contract's design philosophy

Identical triple-guard pattern as mint(). The ContentStore authorization check is critical — without it, any contract or wallet could burn arbitrary users' tokens. The zero checks prevent accidental burns that would confuse the event log.

• ▸Line 162: Only the ContentStore can call this — prevents malicious token burning
• ▸Line 163: Can't burn from the zero address — _burn would fail anyway, but explicit is better than implicit
• ▸Line 164: Can't burn zero tokens — prevents meaningless transactions
• ▸Think of these three lines as a security firewall — each blocks a different class of invalid operation

The opposite of _mint(). OpenZeppelin's internal _burn decreases the user's balance and totalSupply, then emits Transfer(user, address(0), amount). The address(0) as 'to' is how ERC-20 represents permanent destruction.

• ▸_burn checks that user has sufficient balance — if they don't, the entire transaction reverts with an ERC-20 InsufficientBalance error
• ▸After burning, those tokens can NEVER be recovered — they're permanently removed from the total supply
• ▸The automatic Transfer(user, address(0), amount) event is how Etherscan tracks and displays burn transactions

Creates a permanent on-chain receipt of the purchase. While _burn already logged the token destruction, this custom event adds the contentId — telling analytics exactly WHAT was bought, not just that tokens were burned.

• ▸This event + TokensMinted together form the complete economic history of every token
• ▸The contentId parameter enables purchase analytics: which content is most popular? What's the average spending?
• ▸Frontend can listen for this event to show 'Content unlocked!' confirmations

A view function that computes a user's learning tier from their token balance. 'external view' means it can only be called from outside and doesn't modify state — making it completely free to call. The named return 'returns (uint256 tier)' declares the return variable in the signature.

• ▸'view' — reads blockchain state (balanceOf) but doesn't write. Free when called off-chain via eth_call
• ▸'returns (uint256 tier)' — named return. The variable 'tier' is automatically declared in the function scope
• ▸The NatSpec documents every tier level with its range — this documentation shows up on Etherscan
• ▸No access control needed — anyone can check anyone's tier. This is intentional transparency

Simple descending if-chain that maps token balances to tier levels 0-4. The checks go from highest to lowest — this is actually the optimal order because most users will be low-tier, meaning they'll fall through all checks to the default (fast path for common case, but clear intent for readers).

• ▸balanceOf(account) — inherited from ERC20, returns the user's current token balance in wei
• ▸1000 ether = 1000 × 10^18 — the 'ether' keyword is just a multiplier, not related to actual ETH
• ▸Tier 4 (Master): ≥ 1000 EFFORT — the highest achievement. Requires significant learning commitment
• ▸Tier 3 (Expert): ≥ 500 EFFORT — advanced learner
• ▸Tier 2 (Scholar): ≥ 200 EFFORT — intermediate level
• ▸Tier 1 (Learner): ≥ 50 EFFORT — just getting started
• ▸Tier 0 (Newcomer): < 50 EFFORT — the default, returned by the final 'return 0'
• ▸Tiers are computed live from the balance — no separate storage needed. If a user spends tokens and drops below a threshold, their tier automatically decreases

Converts a numeric tier (0-4) to a human-readable string. The 'pure' keyword means this function doesn't read ANY blockchain state — it's a pure computation from input to output. This makes it even cheaper than 'view' and theoretically executable entirely client-side.

• ▸'pure' — stricter than 'view'. No state reads, no balance checks, no storage access. Just input → output
• ▸'string memory name' — returns a string stored in memory (temporary). Strings are dynamically-sized in Solidity
• ▸Returns 'Unknown' for invalid tier values (> 4) — defensive coding against unexpected inputs
• ▸In practice, the frontend could replicate this logic in JavaScript — but having it on-chain ensures consistency and provides a canonical source of truth
• ▸This is the last function before the closing brace — the contract is complete