--- name: flare-dapp-pitfalls description: > Hard-won, cross-project lessons from building, deploying, and operating Flare-family (Flare / Songbird / Coston2) dApps. Use this skill whenever the user is: deploying or interacting with a Flare/Songbird/Coston2 contract, building a frontend with RainbowKit + Wagmi for Flare chains, writing Foundry fork tests against Flare-family state, claiming or rotating FTSO reward redistributors, debugging a stuck or silently-failing transaction, choosing RPC endpoints for browser vs server use, or troubleshooting MetaMask / wallet connection on Flare. Trigger on any mention of: Flare RPC, Songbird canary, Coston2 testnet, FTSO reward claim, WNAT vote-power, FlareDrops, FtsoRewardRedistributor, FlaresRewardsRedistributorForNft, Enosys redistributor, RainbowKit MetaMask hang, Ankr origin locked, Multicall3 on Flare, EIP-150 63/64 gas, eth_getLogs 30-block cap, "why is my Flare contract test failing in CI", "why did my claim transaction return zero", "Wrap SGB to WSGB", or any question about gotchas specific to Flare-family chains. --- # Flare dApp Pitfalls — Cross-Project Lessons This skill captures **gotchas that are NOT in `enosys-contracts`, `enosys-integrations`, `enosys-dex-v3`, or `solidity`** but cost real time on Flare-family work. Most are counterintuitive, RPC-/wallet-/gas-shaped, or specific to Flare's FTSO reward infrastructure. If something contradicts the existing Enosys skills, the override is documented inline with the reason — Enosys skills describe what their own private frontends use; this skill describes what works for **third-party builders** with no privileged RPC access. --- ## 1. Wallet & RainbowKit setup ### Do NOT use RainbowKit's `metaMaskWallet` SDK connector on desktop This is a **direct correction** to the `enosys-integrations` skill, which lists `metaMaskWallet` from `@rainbow-me/rainbowkit/wallets` in its recommended set. `metaMaskWallet` uses the MetaMask SDK, which races a mobile deep-link flow against extension detection on desktop. It frequently hangs on "Opening MetaMask…" — a ~15-30s blocking dead state where the user can't tell if anything's happening. **Use `injectedWallet` instead** — RainbowKit renders it as **"Browser Wallet"** in the picker. It works seamlessly with the MetaMask extension, Rabby, and Brave Wallet (any EIP-1193 injected provider). For mobile MetaMask users, `walletConnectWallet` covers them via QR pairing — no SDK connector needed. ```typescript import { injectedWallet, // ← use this, not metaMaskWallet rainbowWallet, coinbaseWallet, walletConnectWallet, } from "@rainbow-me/rainbowkit/wallets"; const connectors = connectorsForWallets( [ { groupName: "Recommended", wallets: [injectedWallet, rainbowWallet, coinbaseWallet, walletConnectWallet], }, ], { appName: "Your dApp", projectId: WALLETCONNECT_PROJECT_ID } ); ``` Enosys's own frontends can use `metaMaskWallet` because they're served from a curated domain set with their own RPC infrastructure; outside that, the MetaMask SDK is the reason "MetaMask doesn't open" support tickets pile up. ### Wagmi button "dead zone" — track BOTH `isPending` AND `isLoading` `useWriteContract().isPending` = waiting for wallet to sign (0.5–2s). `useWaitForTransactionReceipt().isLoading` = tx is in mempool / mining. Most tutorials only check `isLoading`, which means there's a 0.5–2s dead zone where the user has clicked the button but MetaMask hasn't opened yet, and the button still says "Place order". Three-state pattern: ```tsx const { writeContract, isPending, data: txHash } = useWriteContract(); const { isLoading: isMining, isSuccess } = useWaitForTransactionReceipt({ hash: txHash }); const label = isPending ? "Confirm in wallet…" : isMining ? "Placing order…" : "Place order"; ``` Apply this to every write-action button. --- ## 2. RPC endpoints — browser vs server ### Public Flare RPCs cap `eth_getLogs` at 30 blocks | Chain | Public RPC | `eth_getLogs` cap | |---|---|---| | Flare | `https://flare-api.flare.network/ext/C/rpc` | **30 blocks** | | Songbird | `https://songbird-api.flare.network/ext/C/rpc` | **30 blocks** | | Coston2 | `https://coston2-api.flare.network/ext/C/rpc` | **30 blocks** | If your frontend depends on historical log scans (e.g. "find all my orders"), the public RPC will throw `block range too wide`. Either: - Use **Multicall3 + per-id pairwise reads** instead of log scans (e.g. `factory.getPool(t0, t1, fee)` over a curated token list). - Use **Ankr** (paid tier) — lifts to ~5,000 blocks per request. - Run a **self-hosted node**. Plan for the public-RPC `eth_getLogs` cap from day one — assume 30 blocks is your default and design history-dependent features around that. ### Ankr's API key is origin-locked for browser safety The Ankr key in `NEXT_PUBLIC_ANKR_KEY` is **domain-locked** to the production hostname (plus `localhost:3000` for dev). This is correct browser hygiene — anyone can read the key from your build output, so origin lock prevents abuse. Side effect: server-side calls (curl, `forge script`, indexers, executor bots) will hit `Origin not allowed (-32079)`. **Generate a separate IP-locked Ankr key** for server use; don't try to share the browser key. ### Multicall3 canonical address — same on all three Flare chains ``` 0xcA11bde05977b3631167028862bE2a173976CA11 ``` Live on Flare (14), Songbird (19), and Coston2 (114). Any dApp doing batched reads should use it instead of N parallel `eth_call`s. `aggregate3(allowFailure=true)` is the workhorse — lets one call fail without killing the batch. **Use it for permissionless writes too**, but only when the target function doesn't gate on `msg.sender`. Functions that credit `msg.sender` (executor shares, etc.) cannot be multicalled because Multicall3 becomes the apparent caller. ### EIP-3855 (PUSH0) warning on Coston2 is cosmetic Forge will print: ``` Warning: EIP-3855 is not supported in one or more of the RPCs used. Unsupported Chain IDs: 114. ``` Deployments still succeed. **Don't downgrade `solc` to 0.8.19** to silence it — 0.8.20+ targets PUSH0 and Coston2 handles it fine in practice; the RPC just doesn't advertise the EIP. --- ## 3. Gas: EIP-150 63/64 rule + `try/catch` The single biggest source of "looks-successful but did nothing" bugs on Flare. **The rule**: when contract A calls contract B, EVM forwards `min(gasleft, callerLimit)` where `callerLimit = floor(63/64 × gasleft)`. The remaining 1/64 stays with A. **Why it bites with `try/catch`**: many Flare contracts wrap external calls in `try/catch` with a **reserved inner gas budget** (e.g. `B.foo{gas: 10_000_000}()`). The `gas:` clause is a *ceiling*; the actual forwarded amount is `min(10_000_000, 63/64 × gasleft)`. If the OUTER tx didn't have enough gas to forward 10M, the inner call gets less, OOGs silently, the `try/catch` swallows the revert, and the outer tx succeeds with no observable effect. **MetaMask and `eth_estimateGas` cannot trace through `try/catch`** — the estimator sees the outer revert path of "did anything", not the inner OOG, so wallets routinely under-estimate. Your transactions confirm but pay zero out. **Fix**: pin outer gas explicitly when wrapping a call with a reserved inner budget. Rule of thumb: `outer ≥ ceil(inner × 64/63) + outer_overhead_estimate`. For a 10M inner cap, pin **at least 12M** outer — use 14M to be safe. ```typescript // Wagmi pattern: pin gas on the write to escape estimateGas under-budgeting writeContract({ address: lom, abi, functionName: "claimDelegationRewards", args: [orderId], gas: 12_000_000n, // ← outer pin; protects the 10M REWARD_CLAIM_GAS_CAP forward }); ``` Anywhere you see a contract pattern like: ```solidity try IExternal(target).foo{gas: INNER_CAP}() returns (...) { ... } catch { /* swallow */ } ``` assume estimateGas will under-budget the outer call. Always pin gas on the frontend. ### WNAT's transfer hooks are invisible to `eth_estimateGas` A related variant that doesn't need any `try/catch` to bite you. WNAT (`WFLR`, `WSGB`, `WC2FLR`) fires per-transfer vote-power hooks: every `transfer` and `transferFrom` calls `updateAtTokenTransfer` on each registered delegate / governance contract to refresh checkpoints. Those hooks consume real gas — often 75k-200k per hook — and their cost depends on the recipient's delegation graph, which `eth_estimateGas` can't see through. Symptom: a contract whose execution path ends with `WNAT.transfer(user, amount)` runs cleanly through all its accounting and external calls, then OOGs inside the final WNAT transfer. The 63/64 rule kicks in at the tail: by the time the outer call has spent most of the budget on the upstream work, only a sliver is forwarded into WNAT's hooks. The first hook clears, the second OOGs, the whole tx reverts with no useful reason. Wallets under-estimate because the hook gas isn't reachable from a standard simulation. This matters anywhere your contract pays the user in wrapped-native at the end of a multi-step flow — vault redemptions, claim-and-forward patterns, batch exits that ultimately settle in WNAT. The fix is the same as the `try/catch` case: **pin outer gas on the frontend**. Default to 10M-12M on Flare/Songbird. ```typescript writeContract({ address: vault, abi, functionName: "withdraw", args: [assets, receiver, owner], gas: 12_000_000n, // ← absorbs WNAT vote-power hooks at the tail }); ``` General rule: when pinning gas for any contract write, lean high. The downside of pinning too high is "wallet shows a slightly scary number"; the downside of pinning too low is "tx silently OOGs, user pays gas anyway, you ship a hotfix." ### `block.basefee` is essentially zero on cheap Flare-family chains Coston2 basefee = 1 wei. Songbird basefee = 2 wei. Flare basefee ≈ 25 gwei. If you're building anti-spam economics that gate on `required = basefee × gasEstimate × multiplier`, the gate **collapses to zero on the cheap chains** unless you floor `basefee` at something like 25 gwei. Treat `max(block.basefee, MIN_BASEFEE)` as the effective basefee, with `MIN_BASEFEE` configurable but capped (don't let owner set it to 1000 ETH and brick the system). --- ## 4. WNAT, FTSO, and Enosys's redistributor naming churn WNAT (wrapped FLR / SGB / C2FLR) holders earn **FTSO delegation rewards** and historically **FlareDrops**. Pools, vaults, and limit-order contracts that hold WNAT need to harvest these on behalf of users. ### `vm.deal()` corrupts WNAT vote-power state in fork tests WNAT is not a vanilla ERC-20 — it has FTSO vote-power checkpoints. `vm.deal(addr, X)` sets the balance directly without updating the checkpoint. The next time *any* address tries to `safeTransfer` WNAT (even one unrelated to your test), the call reverts with **`STF`** (SafeTransferFrom) or similar, because the checkpoint is internally inconsistent. **Fix**: in fork tests, fund accounts via the deposit path: ```solidity vm.deal(alice, 10_000 ether); // give alice native FLR/SGB vm.prank(alice); (bool ok,) = WNAT.call{value: 10_000 ether}(abi.encodeWithSignature("deposit()")); require(ok, "WNAT deposit failed"); // alice now has WNAT, checkpoint correct ``` `deal(token, addr, amount)` (the `forge-std` helper, lowercase) works fine for **non-WNAT** ERC-20s like USDT0, USDC, FXRP — just not for WNAT itself. **WNAT recipient-side reverts CANNOT block transfers**. The hook only updates internal state on the WNAT contract; it does not call into the recipient. A contract whose `receive()` and `fallback()` both `revert("blocked")` still receives WNAT successfully. Empirically confirmed against live Flare WFLR 2026-05-08 — useful to know when an audit tries to flag a `safeTransfer(WFLR, ...)` to an unknown recipient as a DoS vector. ### FTSO reward-claim gas blows past naive estimates A long-held NFT position with many accrued FTSO epochs can require **7M+ gas** just to claim its rewards. One real Enosys V3 NFT on Flare was observed consuming **7.67M gas** on a single `claim` call — and that was an active mid-life NFT, not the worst case. When designing an `executeBatch` or `cancelOrder` path that auto-claims rewards before burn, reserve **at least 10M inner gas** for the claim and pin outer gas accordingly. Provide a recovery path (e.g. `claimDelegationRewardsFull(orderId)`) that forwards all caller gas with no inner cap, so users with overflowing NFTs have an out. ### Enosys redistributor rotation — naming chaos, same ABI As of 2026-04, three different redistributor contracts have existed on Flare. **They share the same ABI shape but are not interchangeable.** | Contract | Address | Status | Handles | |---|---|---|---| | `FlaresRewardsRedistributorForNft` | `0x4410B821Fa1041D242f2C199C0EA78E4A5f15F19` | **Legacy** | FTSO + FlareDrops (NFT-aware) | | `FtsoRewardRedistributorForNft` | `0x5a0BfF8Ff1AF1DF28619Fce57d07E3bBb7BAF3d7` | **Current Flare** | FTSO delegation only | | `FtsoRewardRedistributorForAddress` | `0x45aAa2e37B89f7514DF69FA084f381C67891C381` | Different ABI! | FTSO for naked WNAT delegations | On Songbird, `FtsoRewardRedistributorForNft` lives at `0x421294D3eb38c87390fc7f1442623f5b7DBc5b86`. **Critical**: `FtsoRewardRedistributorForAddress` takes `address[]` not `uint256[]` in its `claim` function. **Never register it on a contract that expects an NFT-aware redistributor** — the selector mismatch will revert every claim call. FlareDrops are no longer routed through any of the LOM-claimable redistributors; that path moved to a separate Enosys-handled flow in the 2026-04 rotation. ### How to identify the live redistributor for a given DEX 1. Check if it's a proxy (EIP-1967 implementation slot `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc`). 2. Call `getUnclaimed([])`. The active redistributor returns non-zero for active NFTs; legacy or wrong ones return 0 even for active NFTs. 3. NFT id `1` is usually a safe probe — if it returns 0 from one redistributor and non-zero from another, the non-zero one is current. ### `RewardManager` ≠ Redistributor Enosys's `RewardManager` (e.g. Songbird `0xa997E5FD…` for DEX-level pool incentives) has a **different signature** from the NFT redistributors: `claim(uint256[] ids, uint256 epochsToClaimCnt, address recipient)` — note the extra `epochsToClaimCnt` parameter. A contract expecting the redistributor ABI will revert on selector mismatch if you wire `RewardManager` in by accident. ### Coston2's redistributor returns 0 even for live NFTs Coston2 has the FTSO contracts deployed but rewards aren't flowing — `getUnclaimed` always returns 0. Order/fill flow works for development; reward-path testing has to happen on Songbird or Flare. Don't waste time debugging "no rewards" on Coston2. --- ## 5. Foundry / fork-test patterns ### Fork tests must self-skip when CI runs without `--fork-url` `forge test` runs every test by default. Tests that bake real mainnet addresses into `setUp()` will fail with `call to non-contract address 0x…` when CI runs without fork. Cleanest fix: gate on `block.chainid`. ```solidity function setUp() public { // Fork-only test: skip in default (non-forked) CI runs. // Run locally with: forge test --fork-url flare --match-contract MyTest -vvv if (block.chainid == 31337) { vm.skip(true); return; } // …rest of setUp using real Flare addresses } ``` `31337` is Anvil's default chain ID (also Foundry's default test chain). On a real fork (`14`/`19`/`114`) the guard is a no-op. `vm.skip(true)` requires a recent forge-std (post-1.8); use `return;` alone if that's unavailable but you'll see a "setUp succeeded but no tests ran" warning. ### Stack-too-deep in deploy scripts → extract to internal helpers Foundry scripts often accumulate locals in `run()`: env-var reads, factory references, address parsing. Yul codegen hits "variable too deep in stack." Fix by extracting groups of locals to internal helpers: ```solidity function run() external { address deployed = _deployCore(); _applyTreasuryAndFeeSplit(deployed); _applyPricingConfig(deployed); // ... } function _applyTreasuryAndFeeSplit(address mgr) internal { /* scoped locals */ } function _applyPricingConfig(address mgr) internal { /* scoped locals */ } ``` Each helper gets its own stack window, so depth resets at every call boundary. ### `forge fmt --check` is strictly enforced in CI — pre-format before pushing If your repo's CI runs `forge fmt --check`, every column-alignment difference fails the run. The formatter has strong opinions about: - Single-space between type and identifier (`uint24 fee` not `uint24 fee`) - Single-space inside `require(cond, "msg")` (no double-space alignment) - Multi-line return tuples in interface definitions - Brace placement on multi-modifier function declarations **Before opening a PR, run `forge fmt`** and commit. The formatter is deterministic; its output is the only formatting CI accepts. ### Scope contract CI to contract-relevant paths Don't run the full `forge build + test` pipeline on doc-only or frontend-only commits. Path-filter the workflow: ```yaml on: push: paths: - 'src/**' - 'test/**' - 'script/**' - 'lib/**' - 'foundry.toml' - 'remappings.txt' - '.github/workflows/test.yml' pull_request: paths: [ … same … ] workflow_dispatch: ``` Frontend-only / docs-only PRs no longer trigger contract CI. --- ## 6. Frontend UX — Flare-specific patterns ### Native ↔ wrapped-native shortcut paths in swap UIs The DEX has no `native ↔ wrapped` pool — and shouldn't. When a user picks native on one side and wrapped native on the other (FLR↔WFLR, SGB↔WSGB, C2FLR↔WC2FLR), **bypass the router entirely** and call the WNAT contract: - `WNAT.deposit{value: amount}()` — wraps native → WNAT, 1:1, no slippage, no fee - `WNAT.withdraw(amount)` — unwraps WNAT → native, 1:1 No approval needed for either direction. Show a dedicated info panel ("This is a 1:1 wrap, no slippage applies") instead of the usual route/fee/min-received display because there's nothing to slip. ### Auto-wrap before token operations that need WNAT When the user holds bare native but the contract needs wrapped (e.g. a limit order selling `WSGB` when the user only has `SGB`), don't make them go to the swap tab and back. Detect the deficit and offer a one-click wrap inline: ```tsx {nativeBalance >= shortfall && wrappedBalance < requiredAmount && ( Wrap needed: you have {nativeBalance} {native}, need {shortfall} more {wrapped}. )} ``` Refresh the wrapped-balance read after `WNAT.deposit` confirms; the order flow proceeds to Approve and Create automatically. ### Favicon cache is famously sticky After changing your site's favicon, browsers cache it independently from the page. Hard-refresh (Ctrl+Shift+R) usually misses the favicon. Tell users (and yourself): - DevTools → Application → "Clear site data" → reload, OR - Open in incognito to verify the new icon ships In Next.js App Router, `app/icon.png` replaces `app/favicon.ico`. **`git rm` the old `favicon.ico`** when migrating, otherwise CI re-checks it out and serves both; browsers then pick whichever they cached first. --- ## 7. Deployment, CREATE addresses, and Ledger handoff ### CREATE determinism: same EOA + same nonce ⇒ same address on every chain If you deploy with the same EOA and the same nonce on Flare and Songbird, you'll get **the same contract address on both chains**. This is normal, not a bug. They are entirely separate contracts with separate state and separate storage. Useful pattern: pre-image the deploy address (offline `keccak256(rlp([sender, nonce]))`), share it in advance for indexer config, and deploy to each chain when ready. ### Ownable2Step + Ledger pattern Don't deploy directly from a Ledger — `forge script --ledger` is supported but the sequence of `registerDex`, `setFeeSplit`, `setTreasury2`, etc. that follow the constructor is annoying with hardware-wallet confirms. **Pattern**: deploy from a fresh hot EOA, do all post-deploy configuration, then hand off via OpenZeppelin's `Ownable2Step`: 1. Hot EOA: `forge script Deploy.s.sol --broadcast` — deploys + registers DEXes + sets fees. 2. Hot EOA: `cast send 'transferOwnership(address)' ` — stages the Ledger as `pendingOwner`. 3. Ledger: `cast send 'acceptOwnership()' --ledger` — completes the handoff. After step 3 the hot EOA loses all admin power. Use `Ownable2Step` (not `Ownable`) so a typo in the Ledger address can't permanently brick admin access — the new owner has to actively accept. ### GitHub Pages + branch protection rules If you're deploying a frontend via `peaceiris/actions-gh-pages@v4`, the workflow **force-pushes** to the `gh-pages` branch (`force_orphan: true` or otherwise). If you have a branch ruleset blocking force-push, the workflow fails with: ``` remote: error: GH013: Repository rule violations found ``` Two ways to fix: 1. Edit the ruleset to **exclude `gh-pages`** from force-push protection. 2. Add the GitHub Actions bot to the ruleset's bypass list. ### Personal Access Tokens + workflow files A PAT without `workflow` scope cannot push changes to `.github/workflows/*`: ``` remote: error: refusing to allow a Personal Access Token to create or update workflow `.github/workflows/test.yml` without `workflow` scope ``` Fix: add `workflow` scope to the PAT, OR make workflow file edits via the GitHub web editor, OR push from a token/key that has the scope. For automation (Claude Code, CI bots, etc.) this is a gotcha worth flagging early. ### GitBook ↔ GitHub sync GitBook's **green "Connected" button is OAuth only** — that proves identity, not repo access. If after connecting, GitBook's Account dropdown shows "No items" when you try to add a repo, you also need to install the **GitBook GitHub App**: 1. From GitBook's repo-picker page, click "Install the GitHub app". 2. Choose `Only select repositories` and pick the doc repo. 3. Refresh GitBook — the dropdown now lists the repo. Both OAuth and the App install are required. --- ## 8. Quick reference card | Question | Answer | |---|---| | RainbowKit MetaMask hangs | Use `injectedWallet`, not `metaMaskWallet` | | Server-side Ankr fails with -32079 | Browser key is origin-locked; generate IP-locked key for servers | | `eth_getLogs` block range too wide | Public Flare RPCs cap at 30 blocks; switch to Multicall3 + pairwise reads or Ankr | | Multicall3 address | `0xcA11bde05977b3631167028862bE2a173976CA11` on Flare/Songbird/Coston2 | | Tx confirmed but did nothing | EIP-150 63/64 + `try/catch` + missing outer gas pin | | Wallet under-estimates a `try/catch` call | Pin `gas:` on the write; `eth_estimateGas` can't trace through | | Tx OOGs inside `WNAT.transfer` at the tail | Pin outer gas (10M-12M); vote-power hooks aren't traced by estimateGas | | `cancelOrder` reverts with `STF` | `vm.deal` corrupted WNAT checkpoint; use `WNAT.deposit()` | | FTSO claim returns 0 unexpectedly | Outer gas under-pinned, OR rewards stranded on rotated-away redistributor | | Anti-spam gate too lenient on cheap chain | Floor `block.basefee` at e.g. 25 gwei before sizing the gate | | CI fails with `call to non-contract address 0x…` | Fork test running without `--fork-url`; gate setUp on `block.chainid == 31337` | | `forge fmt --check` in CI fails | Run `forge fmt` and commit | | Ledger handoff bricked admin? | Use `Ownable2Step`, not `Ownable` | --- ## When this skill applies Trigger this skill on Flare-family work that involves any of: - Frontend wallet integration (especially RainbowKit + Wagmi) - RPC choice between public, Ankr, or self-hosted - Foundry fork tests against Flare/Songbird/Coston2 - FTSO reward claims, redistributor rotation, or "why does my claim return 0" - Ledger or multisig deploy handoff - CI failures on contract-touching repos - Any "transaction confirmed but nothing happened" debugging session - Dollar-cost decisions about gas estimation when `try/catch` is in the call path For Enosys-specific contract addresses and DEX V3 patterns, use `enosys-contracts` and `enosys-dex-v3`. For frontend integration boilerplate, use `enosys-integrations` (but with the wallet-list correction noted above). This skill is the **third-party builder's pitfall list** — what you can't learn from looking at someone else's working code, only by hitting the bug yourself.