celo-org / celo-org/docs

task: Fee abstraction — differentiate the guide, contract-reference and spec pages and make their relationship explicit

Open
#2,257 0 comments 0 reactions 1 assignee Claimed by @GigaHierz View on GitHub
chore documentation priority:medium size:M status: triage
Dominant language
MDX
Stars
90
Forks
382
Avg merge
3d 9h
Merged PRs (30d)
35

Description

Part of #2266.

### What needs to be done?

Fee abstraction has three in-nav homes that partly restate each other (verified at `bdf40b37`):

| Page | Job |
|---|---|
| `build-on-celo/fee-abstraction/{overview,using-fee-abstraction,add-fee-currency}.mdx` | **Guide** — how to pay gas in a stablecoin, how to register a fee currency (6 redirects point at the overview) |
| `tooling/contracts/fee-currencies.mdx` (13.8 KB) | **Contract reference** — addresses, registry, adapters, per-network tables |
| `specs/fee-abstraction.mdx` | **Protocol spec** — oracle rates, tx-pool rules, intrinsic gas, node flags |

Plus two orphaned copies (`tooling/overview/migrate/from-ethereum.mdx`, `tooling/overview/setup/development-chain.mdx` — #2253) and mentions across 46 other pages (`grep -ril "fee abstraction|fee-abstraction|fee currencies|feeCurrency" --include=*.mdx` → 51 files).

Decided: **all three pages stay.** Each gets one clear job, says so in its first line, and links to the other two instead of restating them.

### Definition of done

- [ ] Each of the three pages opens with a one-line "This page is the X. For Y see …" and cross-links the other two
- [ ] Content that belongs to another page's job is replaced by a link, not copied: the guide loses its address tables (→ reference); the reference loses its how-to prose (→ guide)
- [ ] Titles / sidebar titles differ clearly (e.g. "Fee abstraction guide" / "Fee currency contracts" / "Fee abstraction spec"; OPEN: exact wording)
- [ ] The two orphaned copies reduced to a link to the guide (after #2253 decides whether they survive)
- [ ] Anchor bug fixed: `build-on-celo/fee-abstraction/add-fee-currency.mdx:151` links to `/build-on-celo/fee-abstraction/overview#adapters-for-non-18-decimal-tokens`, but that heading lives in `using-fee-abstraction.mdx` (`mintlify broken-links` does not validate anchors)
- [ ] A troubleshooting section added to the guide per the code-example policy in `AGENTS.md` (#2251): gas in USDC — adapter address vs token address, 6 vs 18 decimals, the `feeCurrency` parameter per SDK
- [ ] Done in place — no directory moves
- [ ] `npx mintlify broken-links` green

### Non-goals

Deleting or merging any of the three pages. Editing the spec page's content — #2227 owns the guide-vs-spec trim and must wait for the specs.celo.org fragment mapping; do not duplicate that work.

### Depends on / blocks

Depends on #2253. Related: #2227. Blocks #2259.

**Measured at:** `bdf40b37`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.