Audit and Update Learn section

[Juminstock]

Changelog:

• Added Tokenomics 3.0 section covering inflation model, emission decay, and parameter changes from Referendum 50 and 51
• Added per-network dApp Staking tier threshold table for dApp owners (Astar, Shiden, Shibuya)
• Fixed factual errors: PoW consensus claim, tier reward percentages, V3 migration content archived as historical
• Removed all Astar zkEVM references and deprecated architecture image
• Updated tier threshold language from hardcoded ASTR amounts to percentage-based with approximate values
• Fixed 50+ on-chain/off-chain → onchain/offchain spelling across learn, use, and build sections
• Brand and voice alignment: removed hype language, fixed Astar/Astar Network framing, replaced first-person voice

[ghost]

Visit the preview URL for this PR (updated for commit 079c016):

https://astar-docs--pr788-updates-improve-lear-s2eqa7pp.web.app

_{(expires Fri, 08 May 2026 21:57:27 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: f2f13e9b593d211faae6343d67a88fac3fd7268d}

[Gunit2481]

Thanks for the audit, the direction is right. A few items to address before merge.

Blockers

1. Remove fluctuating inflation figures

Current ASTR inflation fluctuates with staking participation, network usage, and supply growth. Pinning it to "approximately 3%" in published docs will be wrong within weeks and we have no process to update it. Remove both sentences:

• docs/learn/tokenomics3/index.md: "Actual inflation sits at approximately 3% under current staking participation levels, well below the 5.5% ceiling, because the adjustable staker component is only minted proportional to participation."
• docs/learn/tokenomics3/inflation.md: "Under current staking participation levels, actual ASTR inflation is approximately 3%."

Keep the mechanism description (adjustable component scales with participation, ceiling is 5.5%) and let readers infer the rest. If a current figure is useful, link to a live dashboard rather than freezing it in markdown.

2. Drop referendum numbers and approval rate

docs/learn/tokenomics3/index.md cites Referendum #50 and #51 with "100% approval." Documentation is not the right surface for this. Referendum IDs and vote outcomes belong in a forum recap, a blog post, or an onchain link. Documentation should describe the model, not its governance history.

Suggested replacement for the Governance section: a one-liner stating Tokenomics 3.0 was enacted via onchain governance in 2026, with a link to the relevant forum thread or governance record for readers who want the full audit trail.

3. Three visible "link unavailable" placeholders

These will ship to readers as-is:

• docs/learn/interoperability/xcm/building-with-xcm/client-applications.md line 330: "Please refer to the Gas Price API ()". The HTML comment is invisible in rendered output; readers see an empty parenthesis.
• docs/learn/interoperability/xcm/integration/hrmp.md line 73: "Refer to the XCM Tools page (link unavailable, to be updated)..."
• docs/learn/interoperability/xcm/integration/hrmp.md line 109: "Read more about adding XCM assets (link unavailable, to be updated)."

Either point to the correct existing page in /docs/build/ or remove the sentence. Don't surface broken-link disclaimers to readers.

4. Tokenomics 2.0 page reads as if it is still active

docs/learn/tokenomics2/index.md line 6: "Tokenomics 2.0 is Astar Network's economic model..."

This contradicts the new Tokenomics 3.0 page which states 3.0 "is the current economic model." Open Tokenomics 2.0 with a historical note (same pattern as the :::note Historical Reference admonitions added in the dApp Staking FAQ) and switch to past tense. Add a link to /docs/learn/tokenomics3/.

5. Tokenomics 3.0 section has no inbound links

Zero files outside the new directory link to /docs/learn/tokenomics3/. The dApp Staking docs reference "Tokenomics 3.0" in prose seven times but never link the section. Add inbound links from at least:

• docs/learn/dapp-staking/index.md (already has a "Tokenomics 3.0 note:" block)
• docs/learn/dapp-staking/dapp-staking-protocol.md
• docs/learn/tokenomics2/index.md

Marketing language sweep

Docs should describe what the system does, not sell it. Specific rewrites below.

docs/learn/tokenomics3/index.md, "ASTR Token Role" section

Current:

ASTR serves as the economic and governance token for Astar Network. Under Tokenomics 3.0, its value alignment is reinforced by:

• Reduced emission ceiling, limiting new supply growth
• Emission decay converging supply toward a long-term target
• Concentrated dApp rewards driving competitive staking behavior
• Governance control over all parameters through onchain referenda

Proposed:

ASTR is the native token of Astar Network. It is used for transaction fees, dApp Staking, and governance. Under Tokenomics 3.0:

• Maximum yearly emission is capped at 5.5%
• Per-block emission decays toward a long-term supply target of approximately 10B ASTR
• Per-era dApp rewards are concentrated on a capped active set of 16 dApps
• Tokenomics parameters are set through onchain governance

Removes "value alignment is reinforced by" (pitch language), the editorialised "driving competitive staking behavior", and the overreaching "all parameters" (not every parameter is governance-settable).

---

docs/learn/tokenomics3/inflation.md, "Comparison with Tokenomics 2.0" section

Current:

The 13.8% bonus allocation rewarded stakers for participating during the voting subperiod of each cycle, creating timing-dependent behaviour with no direct ecosystem benefit.

Proposed:

The 13.8% bonus allocation rewarded stakers for participating during the voting subperiod of each cycle. Tokenomics 3.0 removes this allocation and redirects it into the base and adjustable staker pools.

Removes the "no direct ecosystem benefit" judgement on the prior model. Description, not critique.

---

docs/learn/dapp-staking/index.md, "Why dApp Staking is Important" section

Current:

Ultimately, the most precious human resource in the Web3 ecosystem are developers. Before dApp staking, there were little to no financial incentives for developers to make dApps or to build infrastructure on public blockchains.

Proposed:

Before dApp Staking, developers building on public blockchains had limited recurring funding options beyond grants and fundraising.

Drops the editorial opener, keeps the substantive point.

---

docs/learn/dapp-staking/index.md, "Benefits of dApp Staking" section opener

Current:

For web3 to flourish, there needs to be a symbiotic relationship between dApp stakers, dApp developers, and dApp users. On Astar and Shiden, dApp staking is the mechanism that enables this mutually beneficial relationship to occur.

Proposed:

dApp Staking aligns incentives between three groups on Astar and Shiden: dApp developers, stakers, and users.

Same point, half the words, zero pitch language.

---

docs/learn/architecture/index.md line 8

Current:

Astar Network supports full EVM compatibility, enabling Solidity developers to deploy contracts without modification.

Proposed:

Astar Network is EVM-compatible and supports standard Solidity contracts.

"Full" and "without modification" overstate reality (account model, fee handling, and precompiles differ from Ethereum mainnet).

---

docs/learn/astar-tokens.md, "dApp Staking" subsection

Current:

Astar Network's core team has developed a unique concept called dApp Staking, which is exclusively available on Astar within the Polkadot ecosystem. The goal of Astar Network is to establish itself as the primary hub for decentralized applications (dApps) on Polkadot. Hence, we prepared incentives for dApp developers who choose to build their smart contracts on Astar Network.

Proposed:

dApp Staking is Astar Network's mechanism for distributing a share of block inflation to dApp developers and the stakers who support them. See dApp Staking Overview for the full protocol description.

"Unique" and "exclusively available" are not strictly accurate (other parachains run developer-reward mechanisms). The positioning sentence belongs on a marketing page, not in the token docs.

---

docs/learn/smart-contracts.md, "Overview" section

Current:

Astar Network supports smart contract deployment. Developers can create and deploy smart contracts on Astar Network using a variety of programming languages, including Solidity, which is compatible with Ethereum smart contracts or ink!, a Rust-based smart contract language for Polkadot ecosystem. This compatibility ensures a seamless transition for developers from other blockchain ecosystems, fostering interoperability and encouraging the adoption of Astar Network.

Proposed:

Astar Network supports smart contract deployment in two environments: Solidity contracts running on the EVM, and ink! contracts (Rust-based) running on pallet-contracts.

Drops the "seamless transition... fostering... encouraging adoption" tail, which is sales copy. The preceding clause already states the technical fact.

Nice-to-haves

• Dedupe the four identical "Historical Reference" admonitions in dapp-staking-faq.md. Once at the top of the migration section is enough.