Deduplicate migrated Specs pages against the Home and Build guides
- Dominant language
- MDX
- Stars
- 90
- Forks
- 382
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 35
Description
Follow-up to #2224, which moved the Celo L2 specification from specs.celo.org into the `specs/` tab. In review, @karlb pointed out that two of the migrated pages overlap content that already lives in the Home and Build tabs. The overlap is real, but deduplicating it was left out of the migration PR to keep that one a pure move.
## The two overlaps
**`specs/token-duality.mdx` vs `home/protocol/celo-token.mdx`**
The conceptual half is the same content in different prose: what token duality is, native vs ERC20 balances, `balanceOf` passthrough, transfers via the precompile.
They are not equal, though. The specs page also documents the precompile itself — address `0xff - 2`, 9000 gas, ABI-encoded parameters, and the address-warming change from the Jovian hardfork. `home/protocol/celo-token.mdx` has none of that, and still carries a "Celo is no longer a standalone Layer 1" warning that has been stale for a while.
`home/protocol/celo-token` is the destination of three redirects in `docs.json` and is linked from `home/index.mdx` with a `#celo-token-duality` anchor, so it cannot simply be dropped.
**`specs/fee-abstraction.mdx` vs `build-on-celo/fee-abstraction/`**
`build-on-celo/fee-abstraction/overview` is the established landing page for this feature — six redirects in `docs.json` point at it.
The duplicated part is the spec's "For Token Authors" section: the `IFeeCurrency` requirements, the registration process, and the `FeeCurrencyAdapter` for tokens with fewer than 18 decimals. `build-on-celo/fee-abstraction/add-fee-currency.mdx` and `using-fee-abstraction.mdx` cover all of it, with more detail and worked examples.
The rest of the spec page has no home anywhere else and should stay in the spec: per-block oracle rate fetching, tx-pool rejection rules for unregistered fee currencies, token-specific intrinsic gas, the EIP-7623 floor, and the `celo.feecurrency.limits` / `celo.feecurrency.default` node flags.
## Constraint: heading fragments
The planned follow-up in celo-org/specs replaces the mdBook site with redirect stubs pointing at these pages, preserving URL fragments. The headings in `specs/*.mdx` are the targets of that mapping.
Deleting sections out of the specs pages therefore breaks incoming deep links from old specs.celo.org URLs, and it breaks them silently: the `mintlify broken-links` check run by `.github/workflows/docs-validation.yml` does not validate anchors.
This work should happen after the stub mapping exists, so the fragment targets are known.
## Suggested direction
Trim the guide pages rather than the specs pages, so no fragment targets disappear:
- Cut `home/protocol/celo-token.mdx` down to a short conceptual introduction that links to `/specs/token-duality` for the precompile detail, and drop the stale L1 warning.
- Point the overlapping sections of `build-on-celo/fee-abstraction/*` at the spec where they restate protocol behaviour, keeping the guides focused on how to use and register a fee currency.
Worth confirming with @karlb before starting.
## Also noticed
`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 is in `using-fee-abstraction.mdx`, not `overview.mdx`. Pre-existing, unrelated to the migration, and an example of the anchor problem above.
Contributor guide
Research direction
First confirm with @karlb and wait for the celo-org/specs stub mapping so the preserved fragment targets are known. Review home/protocol/celo-token.mdx and the build-on-celo/fee-abstraction pages alongside specs/token-duality.mdx and specs/fee-abstraction.mdx. Done means the guides no longer duplicate protocol details, link to the specs where appropriate, retain their useful guidance, and preserve incoming anchors.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100