Ethereum Wingman

// ❌ WRONG: Raw wagmi - resolves after signing, not confirmation
const { writeContractAsync } = useWriteContract();
await writeContractAsync({...}); // Returns immediately after MetaMask signs!

// ✅ CORRECT: Scaffold hooks - waits for tx to be mined
const { writeContractAsync } = useScaffoldWriteContract("MyContract");
await writeContractAsync({...}); // Waits for actual on-chain confirmation

🚨 BEFORE ANY TOKEN/APPROVAL/SECURITY CODE CHANGE

STOP. Re-read the "Critical Gotchas" section below before writing or modifying ANY code that touches:

• Token approvals (approve, allowance, transferFrom)
• Token transfers (transfer, safeTransfer, safeTransferFrom)
• Access control or permissions
• Price calculations or oracle usage
• Vault deposits/withdrawals

This is not optional. The gotchas section exists because these are the exact mistakes that lose real money. Every time you think "I'll just quickly fix this" is exactly when you need to re-read it.

🚨 FRONTEND UX RULES (MANDATORY)

These are HARD RULES, not suggestions. A build is NOT done until all of these are satisfied. These rules have been learned the hard way. Do not skip them.

Rule 1: Every Onchain Button — Loader + Disable

ANY button that triggers a blockchain transaction MUST:

1. Disable immediately on click
2. Show a loader/spinner ("Approving...", "Staking...", etc.)
3. Stay disabled until the state updates confirm the action completed
4. Show success/error feedback when done

// ✅ CORRECT: Separate loading state PER ACTION
const [isApproving, setIsApproving] = useState(false);
const [isStaking, setIsStaking] = useState(false);

<button
  disabled={isApproving}
  onClick={async () => {
    setIsApproving(true);
    try {
      await writeContractAsync({ functionName: "approve", args: [...] });
    } catch (e) {
      console.error(e);
      notification.error("Approval failed");
    } finally {
      setIsApproving(false);
    }
  }}
>
  {isApproving ? "Approving..." : "Approve"}
</button>

❌ NEVER use a single shared isLoading for multiple buttons. Each button gets its own loading state. A shared state causes the WRONG loading text to appear when UI conditionally switches between buttons.

Rule 2: Three-Button Flow — Network → Approve → Action

When a user needs to approve tokens then perform an action (stake, deposit, swap), there are THREE states. Show exactly ONE button at a time:

1. Wrong network?       → "Switch to Base" button
2. Not enough approved? → "Approve" button
3. Enough approved?     → "Stake" / "Deposit" / action button

// ALWAYS read allowance with a hook (auto-updates when tx confirms)
const { data: allowance } = useScaffoldReadContract({
  contractName: "Token",
  functionName: "allowance",
  args: [address, contractAddress],
});

const needsApproval = !allowance || allowance < amount;
const wrongNetwork = chain?.id !== targetChainId;

{wrongNetwork ? (
  <button onClick={switchNetwork} disabled={isSwitching}>
    {isSwitching ? "Switching..." : "Switch to Base"}
  </button>
) : needsApproval ? (
  <button onClick={handleApprove} disabled={isApproving}>
    {isApproving ? "Approving..." : "Approve $TOKEN"}
  </button>
) : (
  <button onClick={handleStake} disabled={isStaking}>
    {isStaking ? "Staking..." : "Stake"}
  </button>
)}

Critical: Always read allowance via a hook so UI updates automatically. Never rely on local state alone. If the user clicks Approve while on the wrong network, EVERYTHING BREAKS — that's why wrong network check comes FIRST.

Rule 3: Address Display — Always <Address/>

EVERY time you display an Ethereum address, use scaffold-eth's <Address/> component.

// ✅ CORRECT
import { Address } from "~~/components/scaffold-eth";
<Address address={userAddress} />

// ❌ WRONG — never render raw hex
<span>{userAddress}</span>
<p>0x1234...5678</p>

<Address/> handles ENS resolution, blockie avatars, copy-to-clipboard, truncation, and block explorer links. Raw hex is unacceptable.

Rule 3b: Address Input — Always <AddressInput/>

EVERY time the user needs to enter an Ethereum address, use scaffold-eth's <AddressInput/> component.

// ✅ CORRECT
import { AddressInput } from "~~/components/scaffold-eth";
<AddressInput value={recipient} onChange={setRecipient} placeholder="Recipient address" />

// ❌ WRONG — never use a raw text input for addresses
<input type="text" value={recipient} onChange={e => setRecipient(e.target.value)} />

<AddressInput/> provides ENS resolution (type "vitalik.eth" → resolves to address), blockie avatar preview, validation, and paste handling. A raw input gives none of this.

The pair: <Address/> for DISPLAY, <AddressInput/> for INPUT. Always.

Rule 3c: USD Values — Show Dollar Amounts Everywhere

EVERY token or ETH amount displayed should include its USD value. EVERY token or ETH input should show a live USD preview.

// ✅ CORRECT — Display with USD
<span>1,000 TOKEN (~$4.20)</span>
<span>0.5 ETH (~$1,250.00)</span>

// ✅ CORRECT — Input with live USD preview
<input value={amount} onChange={...} />
<span className="text-sm text-gray-500">
  ≈ ${(parseFloat(amount || "0") * tokenPrice).toFixed(2)} USD
</span>

// ❌ WRONG — Amount with no USD context
<span>1,000 TOKEN</span>  // User has no idea what this is worth

Where to get prices:

• ETH price: SE2 has a built-in hook — useNativeCurrencyPrice() or check the price display component in the bottom-left footer. It reads from mainnet Uniswap V2 WETH/DAI pool.
• Custom tokens: Use DexScreener API (https://api.dexscreener.com/latest/dex/tokens/TOKEN_ADDRESS), on-chain Uniswap quoter, or Chainlink oracle if available.

This applies to both display AND input:

• Displaying a balance? Show USD next to it.
• User entering an amount to send/stake/swap? Show live USD preview below the input.
• Transaction confirmation? Show USD value of what they're about to do.

Rule 3d: No Duplicate Titles — Header IS the Title

DO NOT put the app name as an <h1> at the top of the page body. The header already displays the app name. Repeating it wastes space and looks amateur.

// ❌ WRONG — AI agents ALWAYS do this
<Header />  {/* Already shows "🦞 $TOKEN Hub" */}
<main>
  <h1>🦞 $TOKEN Hub</h1>  {/* DUPLICATE! Delete this. */}
  <p>Buy, send, and track TOKEN on Base</p>
  ...
</main>

// ✅ CORRECT — Jump straight into content
<Header />  {/* Shows the app name */}
<main>
  <div className="grid grid-cols-2 gap-4">
    {/* Stats, balances, actions — no redundant title */}
  </div>
</main>

The SE2 header component already handles the app title. Your page content should start with the actual UI — stats, forms, data — not repeat what's already visible at the top of the screen.

Rule 4: RPC Configuration — ALWAYS Alchemy

NEVER use public RPCs (mainnet.base.org, etc.) — they rate-limit and cause random failures.

In scaffold.config.ts, ALWAYS set:

rpcOverrides: {
  [chains.base.id]: "https://base-mainnet.g.alchemy.com/v2/YOUR_KEY",
  [chains.mainnet.id]: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
},
pollingInterval: 3000,  // 3 seconds, not the default 30000

Monitor RPC usage: Sensible = 1 request every 3 seconds. If you see 15+ requests/second, you have a bug:

• Hooks re-rendering in loops
• Duplicate hook calls
• Missing dependency arrays
• watch: true on hooks that don't need it

Rule 5: Pre-Publish Checklist

BEFORE deploying frontend to Vercel/production:

Open Graph / Twitter Cards (REQUIRED):

// In app/layout.tsx
export const metadata: Metadata = {
  title: "Your App Name",
  description: "Description of the app",
  openGraph: {
    title: "Your App Name",
    description: "Description of the app",
    images: [{ url: "https://YOUR-LIVE-DOMAIN.com/og-image.png" }],
  },
  twitter: {
    card: "summary_large_image",
    title: "Your App Name",
    description: "Description of the app",
    images: ["https://YOUR-LIVE-DOMAIN.com/og-image.png"],
  },
};

⚠️ The OG image URL MUST be:

• Absolute URL starting with https://
• The LIVE production domain (NOT localhost, NOT relative path)
• NOT an environment variable that could be unset or localhost
• Actually reachable (test by visiting the URL in a browser)

Full checklist — EVERY item must pass:

• OG image URL is absolute, live production domain
• OG title and description set (not default SE2 text)
• Twitter card type set (summary_large_image)
• Favicon updated from SE2 default
• README updated from SE2 default
• Footer "Fork me" link → your actual repo (not SE2)
• Browser tab title is correct
• RPC overrides set to Alchemy
• pollingInterval is 3000
• All contract addresses match what's deployed
• No hardcoded testnet/localhost values in production code
• Every address display uses <Address/>
• Every onchain button has its own loader + disabled state
• Approve flow has network check → approve → action pattern

🧪 BUILD VERIFICATION PROCESS (MANDATORY)

A build is NOT done when the code compiles. A build is done when you've tested it like a real user.

Phase 1: Code QA (Automated)

After writing all code, run the QA check script or spawn a QA sub-agent:

• Scan all .tsx files for raw address strings (should use <Address/>)
• Scan for shared isLoading state across multiple buttons
• Scan for missing disabled props on transaction buttons
• Verify scaffold.config.ts has rpcOverrides and pollingInterval: 3000
• Verify layout.tsx has OG/Twitter meta with absolute URLs
• Verify no mainnet.base.org or other public RPCs in any file

Phase 2: Smart Contract Testing

• Write and run Foundry tests (forge test)
• Test edge cases: zero amounts, max amounts, unauthorized callers
• Test the full user flow in the contract (approve → action → verify state)

Phase 3: Browser Testing (THE REAL TEST)

You have a browser. You have a wallet. You have real money. USE THEM.

After deploying to Base (or fork), open the app and do a FULL walkthrough:

1. Open the app in the browser tool — take a snapshot, verify it loaded
2. Check the page title — is it correct, not "Scaffold-ETH 2"?
3. Connect wallet — does the connect flow work?
4. Wrong network test — connect on wrong network, verify "Switch to Base" appears
5. Switch network — click the switch button, verify it works
6. Approve flow — if the app needs token approval:
   • Verify "Approve" button shows when allowance is insufficient
   • Click Approve — does the button disable? Does it show "Approving..."?
   • Wait for tx — does the button come back? Does the UI update to show the action button?
7. Main action — click the primary action (stake, deposit, mint, etc.):
   • Does the button disable and show a loader?
   • Does the transaction go through?
   • Does the UI update after confirmation?
   • Does the balance/state change reflect correctly?
8. Error handling — reject a transaction in wallet, verify the UI recovers gracefully
9. Address displays — are all addresses showing ENS/blockies, not raw hex?
10. Share the URL — check that the OG unfurl looks correct (image, title, description)

Only after ALL of this passes can you tell the user "it's done."

Phase 4: QA Sub-Agent Review (For Complex Builds)

For bigger projects, spawn a sub-agent with a fresh context:

• Give it the repo path and deployed URL
• It reads all frontend code against the rules above
• It opens the browser and clicks through independently
• It reports issues back before shipping

Default Stack: Scaffold-ETH 2 with Fork Mode

When a user wants to BUILD any Ethereum project, follow these steps:

Step 1: Create Project

npx create-eth@latest
# Select: foundry (recommended), target chain, project name

Step 2: Fix Polling Interval

Edit packages/nextjs/scaffold.config.ts and change:

pollingInterval: 30000,  // Default: 30 seconds (way too slow!)