docs(chain): Move B20 spec to References, Create B20 and Native AA in Core Concepts, change Chain landing page by youssefea · Pull Request #1829 · base/docs

youssefea · 2026-08-18T17:48:59Z

What changed? Why?

The Chain tab opened on the Beryl upgrade page, because a Beryl Upgrade group sat above Introduction in the nav. It now lands on Chain Overview.

Two new pages at the top of Core Concepts:

B20 Token Standard — a conceptual, deliberately non-technical introduction: what B20 is, why it exists, what it gives you, the Asset vs Stablecoin variants, who it's for, and a comparison against a custom ERC-20. The B20 demo is embedded in the page (with an open-in-new-tab fallback), and every section links out to the relevant part of the specification.
Native Account Abstraction — the conceptual half of the old EIP-8130 page: why native AA beats ERC-4337/EIP-7702, the five concepts (account, signer/actor, scope/policy, authenticators, payer), and what it unlocks.

Upgrades collapses to one page per upgrade for the two newest forks, via sidebarTitle:

Before	After
Cobalt › EIP-8130	Cobalt
Beryl › Overview, B20 Demos, B20 Specification › …	Beryl

Azul and Optimism are untouched.

Both specs move into Reference:

Reference › B20 — un-nested and renamed from "B20 Specification": Overview, Constants & addresses, Errors & events, Interfaces/, plus a new B20 changelog.
Reference › Native Account Abstraction — eip-8130.mdx, rewritten as a technical reference (network details, client setup, transaction structure, account configuration, authenticators, payers) now that the conceptual material lives in Core Concepts.

Also adds a Cobalt upgrade overview shaped like Beryl's, and a B20 card to Chain Overview since that's the new landing page.

Second commit — unrelated bug, found while testing: mintlify dev currently fails to start on master. #1812 added a Chain anchor with a site-relative href, and the CLI rejects it (#.navigation.tabs[1].global.anchors[0].href: Must be a valid url), failing the prebuild step. cc8ee918 makes it an absolute docs.base.org URL, matching the Get Started tab's Faucet and Bridge anchors. Happy to split this out if you'd rather land it separately.

Notes to reviewers

No URLs move. Spec files stay at their current paths; only the nav position changes. That keeps the diff at 30 insertions / 40 deletions in docs.json instead of ~120 redirects, and no external link to a spec page breaks.
Two things need real data before this is fully accurate:
- specs/upgrades/cobalt/overview.mdx has TBD activation timestamps and no required-software table, since Cobalt isn't scheduled. Please fill in if those numbers exist.
- b20/changelog.mdx has one entry (the Beryl initial release, reconstructed from the specification). Worth a check that nothing is missing or mischaracterised.
The upgrade pages are listed flat as "Cobalt" and "Beryl" using sidebarTitle; their on-page titles stay "Overview", consistent with Azul and the Optimism forks.
b20/demos.mdx (an external-link stub) is deleted and redirected to the new core concept, which embeds the same demo.
Fixed an inconsistency in the Beryl overview along the way: it described the AA phase as Cobalt in the summary and Beryl in the body.
beryl/b20-playground.mdx is left as-is. It was already orphaned from the nav before this PR; worth a follow-up decision on whether to surface or delete it.

How has it been tested?

mintlify dev runs locally (after the anchor fix above). All affected pages return 200: Chain Overview, both new core concepts, Cobalt overview, the EIP-8130 reference, Beryl overview, the B20 changelog, the B20 specification, and the Reference glossary. The only nav warning is get-started/build-app, already missing on master.
Verified https://chain.base.org/demos/b20 sends no X-Frame-Options and no CSP frame-ancestors, so the iframe embed renders rather than falling back.
node scripts/lint-mdx.js on each new and changed file: 0 errors, 0 warnings on the new pages. The 3 "code block missing language" hits on eip-8130.mdx and specification/index.mdx are a pre-existing linter quirk that flags closing fences (297 of them repo-wide on master), not new issues.
Scripted check that every pages entry in docs.json resolves to a file: the only unresolved entry is get-started/build-app, already broken on master.
Scripted check that every internal link in the new and changed pages resolves: 0 broken.
node scripts/agents.js re-run; docs/AGENTS.md index updated.

…oncepts The Chain tab opened on the Beryl upgrade page because a "Beryl Upgrade" group sat above Introduction. Remove that group so the tab lands on Chain Overview. Core Concepts gains two pages at the top: - B20 Token Standard: a conceptual, non-technical introduction to B20 with the chain.base.org/demos/b20 demo embedded, covering why it exists, what it provides, the Asset and Stablecoin variants, who it is for, and how it compares to a custom ERC-20. - Native Account Abstraction: the conceptual half of the EIP-8130 page — why native AA, the five concepts, and what it unlocks. Upgrades collapses Cobalt and Beryl to one page each (via sidebarTitle); Azul and Optimism are untouched. Both specs move into Reference: - Reference > B20 (un-nested from "B20 Specification"): overview, constants and addresses, errors and events, interfaces, plus a new B20 changelog. - Reference > Native Account Abstraction: eip-8130.mdx, rewritten as the technical reference now that the concepts live in Core Concepts. Adds a Cobalt upgrade overview shaped like Beryl's, with activation timestamps marked TBD pending scheduling. Spec file paths are unchanged, so no existing URLs move. The b20/demos stub is removed and redirected to the new core concept, which embeds the same demo. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mintlify · 2026-08-18T17:49:02Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
base	🟢 Ready	View Preview	Aug 18, 2026, 5:50 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

cb-heimdall · 2026-08-18T17:49:03Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

The Chain tab's "B20 Specification" anchor used a site-relative href, which the Mintlify CLI rejects with "must be a valid url", failing the prebuild step so `mintlify dev` could not start at all. Use an absolute docs.base.org URL, matching the Get Started tab's Faucet and Bridge anchors. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Two sentences was longer than the neighbouring cards. Drop the audience framing, which the B20 page itself opens with. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

ericbrown99 · 2026-08-18T18:11:19Z

@@ -0,0 +1,87 @@
+---
+title: "Native Account Abstraction"


Can we have a "coming soon" tag on the side nav for this one given its not mainnet live yet?

Done — added in 3ae34aa8, before this reply. The page now carries tag: "Coming Soon" in its frontmatter, so the pill renders in the side nav next to "Native Account Abstraction" (the B20 page alongside it uses tag: "New").

Ended up pulling this back out. In the side nav the pill sits awkwardly: "Native Account Abstraction" is already a long label, and the tag pushes onto a second line, which makes the entry look overlong next to the rest of Core Concepts.

The signal is still on the page itself — there is a callout at the top stating that EIP-8130 is experimental and currently runs only on the vibenet devnet, and the Cobalt overview lists mainnet and Sepolia activation as TBD. So a reader learns it is not mainnet-live in the first screen, just not from a nav pill.

Added "Soon" instead of "Coming Soon" that was too long

The page opened with prose I wrote rather than sourced material, including a "why B20 exists" narrative and a comparison table whose rows were not backed by anything in the repo. Replace it with technical content drawn from existing pages: - Intro and the ERC-20 build-audit-maintain framing from launch-b20-token - ERC-20 parity list, roles, policy registry and scopes, seize, pause, memos, supply cap, permit, contract URI, factory, address derivation, admin renunciation, variants, and precompile addresses from the B20 specification - The decimals caveat and integration notes from accept-b20-payments - Activation gating and the base-forge note from launch-b20-token - "When to use B20" verbatim from b20-playground - Activation dates from the Beryl overview Drops the invented "why B20 exists" section and the B20-vs-ERC-20 table. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

rayyan224 · 2026-08-18T18:13:16Z

+
+## Why B20 exists
+
+Ask an issuer what their token contract has to do beyond moving balances, and the list is long: freeze an account when a court order lands, seize a balance, pause one operation without halting the rest, tag a transfer with an invoice number, cap total supply, run a stock split, publish a dividend. Every team builds that logic again, in a custom contract, and then pays to audit it.


Is this the normal voice of our text ?

The comparison of native account abstraction against ERC-4337 and EIP-7702 applies across EVM networks, not Ethereum L1 specifically. Also updates the secp256k1 descriptor on both halves of the page so the two stay consistent. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

ericbrown99 · 2026-08-18T18:20:14Z

          {
            "group": "Core Concepts",
            "pages": [
+              "base-chain/network-information/b20-token-standard",


Can we move the new ones below "Network Fees" and above bridging?

Generally ordering based on most commonly asked plus logical building up from the foundation.

ericbrown99 · 2026-08-18T18:23:27Z

+                  {
+                    "group": "B20",
+                    "pages": [
+                      "base-chain/specs/upgrades/beryl/b20/specification/index",


Think we should update these urls so that they match they IA here, which is now much cleaner

Some of these b20 urls have gotten a bit wild: /specs/upgrades/beryl/b20/specification/reference/**

moved files so the paths match the nav. /specs/upgrades/beryl/b20/specification/reference/** is now /specs/reference/b20/**, and upgrades/cobalt/eip-8130 is now specs/reference/native-account-abstraction. All old urls redirect, and every internal link is updated.

cb-heimdall · 2026-08-18T18:24:56Z

Review Error for ericbrown99 @ 2026-08-18 18:24:56 UTC
User failed mfa authentication, see go/mfa-help

EIP-8130 is experimental and runs only on the vibenet devnet, so the nav should signal that it is not yet available on mainnet or Sepolia. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Addresses review feedback that the B20 urls had gotten unwieldy: /specs/upgrades/beryl/b20/specification/reference/** did not reflect that these pages now live under Protocol Specifications > Reference. Moves 113 files so paths match the nav: specs/upgrades/beryl/b20/specification -> specs/reference/b20 .../specification/reference/constants-and-addresses -> specs/reference/b20/constants-and-addresses .../specification/reference/errors-and-events-index -> specs/reference/b20/errors-and-events .../specification/reference/interfaces/** -> specs/reference/b20/interfaces/** specs/upgrades/beryl/b20/changelog -> specs/reference/b20/changelog specs/upgrades/cobalt/eip-8130 -> specs/reference/native-account-abstraction Rewrites 390 internal urls across 117 content files, and adds redirects covering every old path, using :slug* wildcards for the interface tree in keeping with the existing redirects. Ordered most-specific-first so the errors-and-events rename is not shadowed by the wildcard. Also reorders Core Concepts per review: the two new pages now sit after Network Fees and before Bridging and Withdrawals, rather than at the top. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Reverts 3ae34aa at the author's request. The page's own warning still states that EIP-8130 is experimental and vibenet-only, and the Cobalt overview lists mainnet and Sepolia activation as TBD. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

Restores a nav tag on the page, shortened from "Coming Soon" so it fits alongside the label without pushing onto a second line. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging - docs August 18, 2026 17:50 View deployment

mintlify Bot deployed to staging - docs August 18, 2026 17:51 View deployment

docs: tighten B20 card description on Chain Overview

b2194f5

Two sentences was longer than the neighbouring cards. Drop the audience framing, which the B20 page itself opens with. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging - docs August 18, 2026 17:58 View deployment

youssefea requested review from ericbrown99, roethke and soheimam and a lite review from Copilot and removed request for Copilot August 18, 2026 18:07

Copilot started reviewing on behalf of youssefea August 18, 2026 18:07 View session

youssefea changed the title ~~docs(chain): land tab on Chain Overview, add B20 and native AA core concepts~~ docs(chain): Move B20 spec to References, Create B20 and Native AA in Core Concepts, change Chain landing page Aug 18, 2026

ericbrown99 reviewed Aug 18, 2026

View reviewed changes

rayyan224 reviewed Aug 18, 2026

View reviewed changes

mintlify Bot deployed to staging - docs August 18, 2026 18:14 View deployment

mintlify Bot deployed to staging - docs August 18, 2026 18:19 View deployment

ericbrown99 reviewed Aug 18, 2026

View reviewed changes

ericbrown99 requested changes Aug 18, 2026

View reviewed changes

docs: tag the native account abstraction core concept as Coming Soon

3ae34aa

EIP-8130 is experimental and runs only on the vibenet devnet, so the nav should signal that it is not yet available on mainnet or Sepolia. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging - docs August 18, 2026 18:58 View deployment

mintlify Bot deployed to staging - docs August 18, 2026 19:13 View deployment

mintlify Bot deployed to staging - docs August 18, 2026 19:17 View deployment

base deleted a comment from luis200412 Aug 18, 2026

docs: tag native account abstraction as Soon

d29cc39

Restores a nav tag on the page, shortened from "Coming Soon" so it fits alongside the label without pushing onto a second line. Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging - docs August 18, 2026 19:27 View deployment

soheimam added 2 commits August 18, 2026 22:04

updated b20 token standard page

a6d88ba

docs: streamline B20 reference navigation

4ff5c14

mintlify Bot deployed to staging - docs August 18, 2026 20:08 View deployment

Navigation Menu

Uh oh!

docs(chain): Move B20 spec to References, Create B20 and Native AA in Core Concepts, change Chain landing page - #1829

docs(chain): Move B20 spec to References, Create B20 and Native AA in Core Concepts, change Chain landing page#1829
youssefea wants to merge 11 commits into
masterfrom
mux/docs-claude-6

youssefea commented Aug 18, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

cb-heimdall commented Aug 18, 2026

Uh oh!

ericbrown99 Aug 18, 2026

Uh oh!

youssefea Aug 18, 2026 •

edited

Loading

Uh oh!

youssefea Aug 18, 2026 •

edited

Loading

Uh oh!

youssefea Aug 18, 2026

Uh oh!

rayyan224 Aug 18, 2026 •

edited

Loading

Uh oh!

youssefea Aug 18, 2026

Uh oh!

ericbrown99 Aug 18, 2026

Uh oh!

youssefea Aug 18, 2026

Uh oh!

ericbrown99 Aug 18, 2026

Uh oh!

youssefea Aug 18, 2026 •

edited

Loading

Uh oh!

cb-heimdall commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Why B20 exists

		Ask an issuer what their token contract has to do beyond moving balances, and the list is long: freeze an account when a court order lands, seize a balance, pause one operation without halting the rest, tag a transfer with an invoice number, cap total supply, run a stock split, publish a dividend. Every team builds that logic again, in a custom contract, and then pays to audit it.

Uh oh!

Conversation

youssefea commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cb-heimdall commented Aug 18, 2026

🟡 Heimdall Review Status

Uh oh!

ericbrown99 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

rayyan224 Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

ericbrown99 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

ericbrown99 Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

youssefea Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cb-heimdall commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

youssefea commented Aug 18, 2026 •

edited

Loading

mintlify Bot commented Aug 18, 2026 •

edited

Loading

youssefea Aug 18, 2026 •

edited

Loading

youssefea Aug 18, 2026 •

edited

Loading

rayyan224 Aug 18, 2026 •

edited

Loading

youssefea Aug 18, 2026 •

edited

Loading