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.
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.mdxvshome/protocol/celo-token.mdxThe conceptual half is the same content in different prose: what token duality is, native vs ERC20 balances,
balanceOfpassthrough, 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.mdxhas 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-tokenis the destination of three redirects indocs.jsonand is linked fromhome/index.mdxwith a#celo-token-dualityanchor, so it cannot simply be dropped.specs/fee-abstraction.mdxvsbuild-on-celo/fee-abstraction/build-on-celo/fee-abstraction/overviewis the established landing page for this feature — six redirects indocs.jsonpoint at it.The duplicated part is the spec's "For Token Authors" section: the
IFeeCurrencyrequirements, the registration process, and theFeeCurrencyAdapterfor tokens with fewer than 18 decimals.build-on-celo/fee-abstraction/add-fee-currency.mdxandusing-fee-abstraction.mdxcover 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.defaultnode 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/*.mdxare 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-linkscheck run by.github/workflows/docs-validation.ymldoes 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:
home/protocol/celo-token.mdxdown to a short conceptual introduction that links to/specs/token-dualityfor the precompile detail, and drop the stale L1 warning.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:151links to/build-on-celo/fee-abstraction/overview#adapters-for-non-18-decimal-tokens, but that heading is inusing-fee-abstraction.mdx, notoverview.mdx. Pre-existing, unrelated to the migration, and an example of the anchor problem above.