[palango]

The viem examples in the fee abstraction how-to didn't run. Step 3 treated USDC as an 18-decimal token, so it sent the wrong amount, and it used functions and imports that only existed in step 1. This rewrites steps 1 and 3 as standalone scripts that use USDC's 6 decimals, labels every address with its network and decimals as AGENTS.md section 5 asks, corrects the explanation of why the sender needs a little more than 1 USDC, and sentence-cases the headings.

Refs #2362. Two boxes stay open: nobody has run the CLI transfer, and the step 3 script has not sent a transaction on Celo Sepolia. Both need a funded key, which I don't have. #2366 fixed the CLI addresses.

Changes

• Step 1 shows all its imports, builds the transfer with viem's erc20Abi, and no longer calls hexToBigInt on estimateGas, which already returns a bigint. The hexToBigInt on the raw eth_gasPrice result stays, since that call returns hex. The fee is printed without a unit, so the line stays correct when a reader swaps in USDT.
• Step 3 is one script. It estimates the fee, converts it from 18 to 6 decimals rounding up, and transfers 1 USDC minus the fee. Before, it subtracted the 18-decimal fee from parseEther("1") and used encodeFunctionData and parseEther without importing them. The key comes from PRIVATE_KEY, and @celo/abis is no longer needed.
• The prose under step 3 now matches op-geth. buyGas() in core/state_transition.go (celo-org/op-geth, celo-rebase-17) checks the fee-currency balance against gas limit times max fee per gas, without the transfer amount (canPayFee in core/celo_state_transition.go). It then debits gas limit times the effective gas price before the transfer runs. So the balance must cover the transfer plus the fee at inclusion, with a margin in case the base fee rises.
• A Warning above step 3 points out that the script sends real USDC on mainnet, covers key handling, and shows how to try it on Celo Sepolia first. A line under the CLI blocks says --privateKey ends up in shell history and the process list.
• A setup line covers npm install viem, .mjs files and node, and says how to switch the scripts to USDT or USA₮.
• Labels: adapters now say gas math is in 18 decimals. The USDC adapter has no decimals() function (the call reverts on both networks), so its label says so. The USDT adapter's label says 18 decimals. Example sender and recipient addresses name the network.
• Headings are in sentence case and no longer numbered. Nothing in the repo links to the old #1-estimate-the-gas-fee, #2-prepare-the-transaction or #3-send-the-transaction anchors. The other slugs don't change.

Verification

Setup, in a scratch directory outside the repo (viem 2.55.10, Node 24.21.0):

npm init -y && npm i viem
# step1.mjs, step2.mjs and step3.mjs are the three js blocks, extracted verbatim from the page

Step 1 and step 2 on Celo mainnet, unchanged:

$ node step1.mjs
Estimated fee: 0.00335641401
$ node step2.mjs   # exits 0, no output

Step 1 on Celo Sepolia. step1-sepolia.mjs is step 1 with celoSepolia imported as celo, the Sepolia USDC token 0x01C5C0122039549AD1493B8220cABEdD739BC44E and adapter 0xbf1441Ea57f43f35f713431001f35742c88071c7, and sender 0x75b9B758DcE00616969ad584894CeBc07E66e830, which held 8.897780 USDC:

$ node step1-sepolia.mjs
Estimated fee: 0.00891347625

Step 3, read-only. step3-harness.mjs changes three lines of the page's script: the account comes from a SENDER address instead of privateKeyToAccount(process.env.PRIVATE_KEY), sendTransaction becomes prepareTransactionRequest, and it logs the prepared values instead of the hash:

$ SENDER=0xccc9576F841de93Cd32bEe7B98fE8B9BD3070e3D node step3-harness.mjs   # Celo mainnet
{ gasPrice: 19113975000n, gas: 175600n, feeInUsdc: 3357n, transfer: 996643n,
  type: 'cip64', maxFeePerGas: 45590370000n, serializedTypeByte: '0x7b' }
$ SENDER=0x75b9B758DcE00616969ad584894CeBc07E66e830 node step3-harness-sepolia.mjs   # Celo Sepolia
{ gasPrice: 78750000000n, gas: 113187n, feeInUsdc: 8914n, transfer: 991086n,
  type: 'eip1559', maxFeePerGas: 93750000000n, serializedTypeByte: '0x7b' }

serializedTypeByte is the first byte of chain.serializers.transaction(prepared), so both requests serialize as CIP-64.

Adapter decimals:

$ cast call --rpc-url https://forno.celo.org 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B 'decimals()(uint8)'
Error: server returned an error response: error code 3: execution reverted
$ cast call --rpc-url https://forno.celo-sepolia.celo-testnet.org 0xbf1441Ea57f43f35f713431001f35742c88071c7 'decimals()(uint8)'
Error: server returned an error response: error code 3: execution reverted
$ cast call --rpc-url https://forno.celo.org 0x0E2A3e05bc9A16F5292A6170456A710cb89C6f72 'decimals()(uint8)'
18

Docs checks, with mint 4.2.746:

$ mint broken-links --check-redirects
success no broken links found
$ mint validate
success build validation passed
$ scripts/check-orphans.sh
No orphan pages found.

Not run: the CLI transfer (celocli transfer:erc20) on either network, and the step 3 script's sendTransaction. Nothing was signed or sent. Closing #2362 needs a funded Celo Sepolia run of both, with the command and output added here.

Step 2 keeps type: "0x7b". viem serializes "0x7b", "cip64" and an omitted type the same way when feeCurrency is set.

[GigaHierz]

head 5402077 · headRefOid == fetched refs/pull/2384/head (re-fetched, equal); 0 commits behind origin/main, 1 ahead; git merge-tree --write-tree clean (tree 57015d2e); one file changed; step 1 mainnet run printed Estimated fee: 0.00334671600393 USDC; CI: broken-links, GitGuardian, StepSecurity pass (Mintlify Deployment skipping)

Verdict: REQUEST-CHANGES

Status of the #2362 boxes

• CLI USDC example uses token for --erc20Address and adapter for --gasCurrency, and the command is run once with output noted in the PR. The code half is done on main (build/fee-abstraction/using-fee-abstraction.mdx lines 48-57 carry token 0xcebA...118C and adapter 0x2F25...602B, both checksum-correct, from #2366). The run half is NOT done: #2366's body says "I did not run the transfers ... the 'run once with output' box is still open", and #2384 contains no CLI run, only "#2366 already fixed the CLI example, so this closes out #2362". No CLI output has been recorded in either PR.
• [~] viem examples self-contained, token decimals, run against Sepolia with command and output in PR. Decimals fixed and imports shown. The PR records fee outputs and prepareTransactionRequest serialization on Sepolia (I reproduced them), but not the commands, and the send in step 3 was not run (PR admits). "Self-contained" is not met in full, see finding 2.
• [~] Every address labelled with network and decimals. Tokens are labelled. Adapters are labelled with network and role but not decimals (lines 48, 64, 105, 146, 169), and the sender/recipient addresses (108-110, 172-173) carry no network. See finding 4.
• mint broken-links --check-redirects: "no broken links found". mint validate: passed. scripts/check-orphans.sh: "No orphan pages found." CI "Check for broken links": pass.

Closes #2362 is not justified: box 1's run is open, box 2 is partly open, box 3 is partly open. Use Refs #2362, or run the missing items and record them.

Findings

1. MEDIUM · PR body (Closes #2362) · The PR auto-closes an issue whose definition of done has an unmet run requirement. Scenario: merge closes #2362, the "CLI command run once with output" requirement and the Sepolia send are silently dropped, and AGENTS.md section 5 ("every example that stays must run; the PR notes the command and output") is not met for the CLI block or step 3's send. Fix: change to Refs #2362 until a funded Celo Sepolia run (celocli transfer:erc20 --node celo-sepolia with Sepolia token 0x01C5C0122039549AD1493B8220cABEdD739BC44E and adapter 0xbf1441Ea57f43f35f713431001f35742c88071c7, plus step 3 sent from a throwaway funded key) is recorded in the PR with command and output, or have the author or a maintainer with a funded test key run it. Add the commands, not only outputs, to the PR body.

2. MEDIUM · build/fee-abstraction/using-fee-abstraction.mdx:153 · The stated reason the sender needs "slightly more than 1 USDC" is wrong. The sentence says the network checks the balance against gas limit times max fee per gas, implying 1 USDC plus that. In celo-org/op-geth (default branch celo-rebase-17), core/state_transition.go buyGas() computes balanceCheck = GasLimit * GasFeeCap and calls canPayFee(balanceCheck) (in core/celo_state_transition.go): for a fee-currency tx it compares the fee-currency balance with that amount alone; the token-transfer amount is not part of it (only msg.Value, which is 0 here, is added, and only to the CELO check). Separately, subFees(mgval) debits GasLimit * GasPrice (effective price, not the cap) from the fee-currency balance before the transfer executes. So the practical requirement is transfer amount plus the upfront fee, which is about 1 USDC when the price has not moved, and a few units more if base fee rises between estimate and inclusion. I confirmed with eth_call on Sepolia with a state override of the sender's USDC balance: with transfer = 991086, gas = 113187, maxFeePerGas = 93.75 gwei and feeCurrency set, balances up to 990000 revert with "transfer amount exceeds balance" and 999999 and above succeed (eth_call skips the pre-check, so this shows the debit-then-transfer ordering, not the max-fee check). Failure scenario: a reader who holds exactly 1 USDC reads "needs slightly more because of the max-fee check", assumes 1.0017 is the exact rule, and cannot predict why a send with 1.000001 fails after a base-fee bump. Fix shape: rewrite as "The fee is taken from the sender's USDC balance before the transfer runs, so the balance must cover the transferred amount plus the fee at the time of inclusion; keep a small margin because the fee can rise after the estimate. The network also requires the balance to cover gas limit times max fee per gas, which is higher than the estimate." Keep the op-geth reference only if the sentence stays accurate.

3. MEDIUM · build/fee-abstraction/using-fee-abstraction.mdx:91-138, 155-209 · The blocks are not copy-and-run self-contained: the page never says to npm install viem, that both blocks use top-level await and import so they must be run as ES modules (.mjs or "type": "module"), or what PRIVATE_KEY must look like (viem needs a 0x-prefixed 32-byte hex string; an unprefixed or malformed value dies inside privateKeyToAccount with "invalid private key, expected hex or 32 bytes, got string"). I extracted the three js blocks verbatim and they run only as .mjs with viem installed (2.57.2, Node 20.19.4). Failure scenario: a reader pastes into index.js in a CommonJS project and gets Cannot use import statement outside a module or await is only valid in async functions. AGENTS.md section 5 asks for imports shown and env vars named. Fix shape: one line above step 1 ("Install viem with npm install viem and save each script as an .mjs file; step 3 reads the sender key from PRIVATE_KEY, a 0x-prefixed hex string"), and a CodeGroup for the install command if wanted.

4. LOW · lines 48, 64, 105-110, 146, 169-173 · Labels are incomplete against AGENTS.md section 5 and #2362 box 3. Adapters say "USDC adapter, the fee currency for USDC" with no decimals; sender and recipient lines say "Example addresses; use your own" with no network. Note the USDC adapter has no decimals() (it reverts; verified on mainnet and Sepolia), while the USDT adapter returns 18, so the label must say what is meant. Failure scenario: a reader checks the adapter's decimals, finds a revert, and cannot tell whether the label is wrong. Fix shape: // Celo mainnet (42220), USDC adapter, fee currency (gas math in 18 decimals; no decimals() on this adapter) and // Celo mainnet (42220), example sender for sender/recipient. Same for the two CLI comment lines.

5. LOW · line 153 and lines 91-209 · Key handling and mainnet default. The step 3 prose only says "Set PRIVATE_KEY to the sender's key." There is no warning to use a dedicated low-balance key, never hardcode or commit it, and never log it (the script itself does not print it, which is good). The CLI blocks (57, 73) still pass --privateKey [PRIVATE_KEY] on the command line, which lands in shell history and ps. Both scripts target mainnet, so copying step 3 sends real USDC with no dry-run suggestion even though the PR verified on Sepolia. Fix shape: a <Warning> above step 3 (key from a secret store or env var, never committed, use a throwaway funded account, try Celo Sepolia first by switching celo to celoSepolia and using the Sepolia token 0x01C5...C44E and adapter 0xbf14...71c7 from Fee currency contracts) and, for the CLI, note that --privateKey is visible in shell history.

6. LOW · lines 91-209 · USDC-only examples under a page that claims USDC, USDT and USA₮. Swapping in the USDT token and adapter works (I ran step 1 on mainnet with USDT, fee 0.002475635964296625, using a USDT holder as sender), but the output line is hardcoded ... USDC, so a USDT reader prints a wrong unit, and nothing says that USDT and USA₮ adapters expose getAdaptedToken() rather than adaptedToken() inside the script path (line 34 does say it in prose). I did not run USA₮. If the maintainers prefer USDT as the example token, the change is the two constants, the labels and the unit string; the math is identical (6 decimals, 18-decimal adapter). Fix shape: either keep USDC and add a one-line note "for USDT or USA₮ replace both addresses with the pair from Fee currency contracts and the unit label", or switch the example to USDT.

7. LOW · headings, lines 11, 26, 38, 44, 78, 82, 140, 151 · AGENTS.md section 3: a page you are editing should get sentence-case headings and no numbered headings ("Allowlisted Fee Currencies", "Adapters for Non-18-Decimal Tokens", "1. Estimate the Gas Fee", ...). The PR rewrote steps 1 and 3 but left their numbered title-case headings. Fix shape: ## Estimate the gas fee, ## Prepare the transaction, ## Send the transaction, etc. Slugs: sentence-casing keeps #adapters-for-non-18-decimal-tokens unchanged (inbound links in fee-currencies.mdx:16, add-fee-currency.mdx:162, overview.mdx:52,56 stay valid; check by hand that nothing links to #1-estimate-the-gas-fee before dropping the numbers; I found none).

Verified good

• Head and merge state as above; diff touches only the one page.
• Step 1 on Celo mainnet (https://forno.celo.org), verbatim from the page as .mjs: prints a plausible fee. Independent recomputation by raw JSON-RPC: eth_gasPrice with the adapter parameter = 19058747175, eth_estimateGas with feeCurrency = adapter = 175600, product 3.34671600393e15, which formatted in 18 decimals is exactly the printed 0.00334671600393; in 6 decimals floor 3346, ceil 3347. Step 1 on Celo Sepolia with Sepolia token/adapter and a USDC holder as sender: 0.00891347625 (gasPrice 78750000000 times gas 113187), matching the PR.
• Step 3 math on Sepolia (harness: holder as keyless sender, sendTransaction replaced by prepareTransactionRequest): feeInUsdc = 8914, transfer 991086 = 1000000 - 8914, matching the PR. Mainnet harness: fee 3347, transfer 996653. Rounding is up (ceil of 18 to 6 decimals), so the fee is never under-withheld; the transferred amount is 1 USDC minus the fee in 6-decimal base units; no double conversion (the fee is converted once from gasPrice * gas; the transfer amount is built with parseUnits("1", 6)); the only underflow would be a fee above 1 USDC, which encodeFunctionData would reject as a negative uint256, not a realistic case.
• CIP-64: celoSepolia.serializers.transaction on the prepared request (feeCurrency set) serializes with type byte 0x7b; type: "0x7b", "cip64", omitted and even "eip1559" all serialize to 0x7b when feeCurrency is set (so step 2's type: "0x7b" is accepted, as the PR says). The prepared Sepolia request reports maxFeePerGas 93750000000 against gasPrice 78750000000; on mainnet the max fee is about 2.4 times the gas price (45458641410 vs 19058747175), so the worst-case reserve gas times maxFee (7983 units) is well above the 3347-unit fee.
• Step 1's comment "estimateGas reverts if the sender holds less than 1 USDC": with a zero-balance sender the call reverts with ERC20: transfer amount exceeds balance.
• hexToBigInt is now only applied to the hex eth_gasPrice result and not to estimateGas; imports in both scripts cover everything used (encodeFunctionData, erc20Abi, formatEther, hexToBigInt, http, parseUnits, privateKeyToAccount, chain). Step 2 runs as written.
• Chain roles (viem reads against both networks): mainnet USDC token 0xcebA...118C symbol() USDC, decimals() 6, not in FeeCurrencyDirectory.getCurrencies(); adapter 0x2F25...602B in getCurrencies() (directory 0x15F344b9E6c3Cb6F0376A36A64928b13F62C6276), adaptedToken() returns the token, getAdaptedToken() reverts; USDT mainnet token 0x4806...3D5e (USD₮, 6) and adapter 0x0E2A...6f72 (18, getAdaptedToken()) correct. Sepolia (chain id 11142220) USDC token 0x01C5...C44E (6) and adapter 0xbf14...71c7 (in directory 0x9212Fb72ae65367A7c887eC4Ad9bE310BAC611BF), USD₮ pair also correct. Roles in all examples are right: token for transfer and to, adapter for feeCurrency and eth_gasPrice.
• EIP-55: cast to-check-sum-address returns the input unchanged for every address on the page that I checked (USDC token and adapter, USDT token and adapter, 0x22ae...4966, 0xDF7d...c4d7, 0xccc9...0e3D). The sender 0xccc9...0e3D held 2.244022 USDC on mainnet at the time, so step 1 runs as printed.
• Private key is read from PRIVATE_KEY and never printed or logged in either script.
• AGENTS.md: root-relative links, bare js language tag, Note component, no promotional wording, no emoji, no Alfajores, Celo Sepolia only.
• Render: mint dev --port 3911 served /build/fee-abstraction/using-fee-abstraction with HTTP 200 and the PR's content (feeInUsdc present, "slightly more than 1 USDC" present, 6 code blocks); my own Playwright tab on port 3911 showed 0 console errors.

What the PR got right

• Fixes all three viem defects named in the issue: 6-decimal math, imports shown, no hexToBigInt on the bigint.
• The rounding-up conversion and total - fee design is arithmetically sound and reproducible; the scripts are short and self-consistent.
• Honest about what was not run (the send), reports real numbers that reproduce, and keeps PRIVATE_KEY out of the source.
• Step 2 type: "0x7b" retained with an accurate justification.
• It is one page, no conflicts, no stale base. The remaining work is one round of targeted edits (PR body, one sentence, one install line, labels, headings), not a rethink.

Merge-order hazards

• Single file, mergeable now; the PR touches only build/fee-abstraction/using-fee-abstraction.mdx (I did not scan other open PRs for overlap). Any other PR editing that page (headings, CLI blocks, troubleshooting) will conflict on the same hunks, especially if the heading cleanup in finding 7 lands in a separate PR.
• Merging with Closes #2362 closes the issue; if findings 1-3 are resolved as a follow-up issue, link it from the PR, otherwise the CLI run requirement vanishes.

[GigaHierz]

head d94e360 · API headRefOid matches the fetched refs/pull/2384/head; one file changed, git merge-tree --write-tree against current main is clean; CI: Check for broken links, GitGuardian and StepSecurity pass.

Verdict: APPROVE

Thank you for the two follow-up commits. Every finding from the last round is resolved on this head, and the remaining open items are honestly disclosed in the description and tracked with Refs #2362.

Status of earlier findings

1. Closes #2362 with unmet run boxes: fixed. The description now says Refs #2362, lists the CLI transfer and the step 3 send as not run, and records commands as well as outputs for step 1, step 2, the read-only step 3 harness and the adapter decimals() calls.
2. Wrong reason for needing "slightly more than 1 USDC": fixed. Line 162 now says the fee is taken from the sender's USDC balance before the transfer runs, so the balance must cover the amount plus the fee at inclusion, and separately that the network checks the balance against gas limit times max fee per gas. That matches buyGas() / canPayFee in op-geth.
3. Scripts not copy-and-run: fixed. Line 84 covers npm install viem, .mjs, node, and how to swap in USDT or USA₮; line 162 names PRIVATE_KEY and says it is a 0x-prefixed hex string.
4. Incomplete labels: fixed. Adapters carry network, role and "gas math in 18 decimals", and the USDC adapter says it has no decimals() function. Sender and recipient lines carry the network. The two CLI comment blocks match.
5. Key handling and mainnet default: fixed. A <Warning> sits above step 3 (dedicated account, env var or secret store, never commit or log, try Celo Sepolia first with the exact edit), and line 76 notes that --privateKey lands in shell history and the process list.
6. USDC-only output unit: fixed. The USDC suffix is gone from the output line, and line 84 says what to replace for USDT or USA₮.
7. Numbered title-case headings: fixed. All headings are sentence case and unnumbered. I grepped the repo for the old slugs (#1-estimate-the-gas-fee, #2-prepare-the-transaction, #3-send-the-transaction): nothing links to them. The inbound anchors that do exist (#adapters-for-non-18-decimal-tokens from add-fee-currency.mdx, overview.mdx and fee-currencies.mdx, and #using-fee-abstraction-with-viem from overview.mdx) still resolve.

Verified

• The executable code in all three js blocks is identical to the head I ran last round: the diff since then touches only comments, the dropped unit string, prose and headings. That run reproduced the step 1 fee on mainnet and Celo Sepolia, the step 3 amounts (feeInUsdc 3347 and 8914, transfer total - fee, rounding up, no double conversion), and CIP-64 serialization (type byte 0x7b).
• On this head I did not re-run the scripts, because the environment's secret guard blocks running any block that handles a key. The check above rests on the unchanged code.
• Addresses on the page are EIP-55 checksummed, roles are right everywhere (token for transfer and to, adapter for feeCurrency and eth_gasPrice), no Alfajores, Celo Sepolia only, bare js language tags, Warning component rather than a blockquote, frontmatter unchanged and valid.

Non-blocking notes

• The example sender in step 1 (line 114) is a third-party mainnet address that holds USDC today. The comment already says estimateGas reverts below 1 USDC; if that address is ever emptied the example fails for readers who copy it unchanged. A note to use their own funded address would make that explicit, but it is not worth holding the PR.
• The step 3 sendTransaction and the celocli transfer:erc20 example have still not been executed on-chain. Step 3's prepared request, math and serialization are verified, and the CLI block is unchanged apart from comments, so I'm comfortable merging, but #2362's "run once with output" requirement stays open and should be closed by someone with a funded Celo Sepolia key, with the command and output recorded on the issue.

Merge

Single file, no conflicts with open PRs that I could find, mergeable now. Squash-merging with the PR title as the commit.