Skip to content

docs(terminology): expand into a comprehensive, sourced glossary (206 terms)#1193

Open
lamentierschweinchen wants to merge 1 commit into
multiversx:developmentfrom
lamentierschweinchen:glossary-expansion
Open

docs(terminology): expand into a comprehensive, sourced glossary (206 terms)#1193
lamentierschweinchen wants to merge 1 commit into
multiversx:developmentfrom
lamentierschweinchen:glossary-expansion

Conversation

@lamentierschweinchen

Copy link
Copy Markdown

What this does

Replaces the current docs/welcome/terminology.md page (about 17 staking-focused terms) with a comprehensive, sourced glossary of 206 terms spanning the whole docs surface: blockchain foundations, protocol and architecture, consensus and security, tokens, network / nodes / staking, wallets and accounts, ecosystem applications, upgrades, framework and SDK, the agent stack, economics, governance, and day-to-day staking operations.

The page keeps its id: terminology and slug, so the existing sidebar entry (Terminology: ["welcome/terminology"]) resolves unchanged. Only this one file is touched.

Format

Every entry follows a single, consistent shape:

  • a short mechanical definition;
  • a Context: line with the MultiversX specifics;
  • a See also: line cross-linking related terms;
  • a Source: line citing the exact page the definition is drawn from.

The original staking terms (Validate, Stake, Delegate, Stake rewards, Delegate rewards, Unstake, Staking provider, Staking pool, Delegation cap, plus APR/Service Fee/Metachain/Node/Validator/Observer) are retained and brought up to the same enriched format. Foundational terms (block, transaction, account, testnet, faucet, endpoint, gas limit, and so on) are included on purpose: what is obvious to readers fluent in the docs is not obvious to first-timers, and this page is meant to be the thing a newcomer or a search engine lands on for "what is X in MultiversX."

Sourcing

Every entry is grounded in the docs and cites the specific page it came from (for example docs.multiversx.com/validators/staking-v4, .../tokens/fungible-tokens, .../governance/overview, .../learn/consensus), rather than a single generic link. Where a term is framework behavior or an upgrade/economic decision, it cites the source repository or the governing post. Features in phased rollout (for example Supernova) are labeled as such rather than stated as live.

New terms added in this pass, by area:

  • Foundations: Miniblock, Metablock, Genesis Round, Intra-Shard Transaction, Cross-Shard Transaction, Verifiable Unpredictable Function, Mainnet, Testnet, Devnet, Faucet.
  • Protocol / architecture, sovereign, bridge: SpaceVM, Stateless Execution, Restaking (Sovereign), Dual Staking (Sovereign), Header Verifier, ESDT-Safe, Ad-Astra Bridge, Axelar bridge, Bridged Tokens.
  • Tokens: Token Properties (canFreeze / canWipe / canPause / ...), Freeze and Wipe, Pause, Local Mint and Burn.
  • Nodes and staking: Unbond, Top-up, Auction List, Waiting List, Eligible Nodes, Soft Auction, Slashing, BLS Key (Validator Key), Node Redundancy, Multikey Nodes, Merge Validator, Delegation Manager, Delegation Contract, Import DB.
  • Wallets: Web Wallet, Wallet Extension (DeFi Wallet), Ledger, xAlias, WalletConnect.
  • Framework and SDK: Official SDKs, sdk-py, sdk-nestjs, Endpoint, View, Init and Upgrade, Payable Endpoint, only_owner, Contract Calls (sync / async / transfer-execute), Callback, Code Metadata, Serialization (TopEncode / NestedEncode), Managed Decimal, Gas Limit, Gas Price, Code Hash, Reproducible Build, Contract Address, Blackbox and Whitebox Testing, Gateway, Elastic Indexer, Events Notifier, Deep-History Squad, Snapshotless Observer.
  • Governance: Governance Proposal, Quorum, Veto, Voting Power.

For docs-team review

This is submitted for your review as the terminology owners. A couple of points I want to flag explicitly rather than paper over:

  1. learn/economics.md is stale on supply, and I did not want the glossary to contradict it silently. That page still states a fixed maximum theoretical supply of 31,415,926 EGLD and a 10-year inflation schedule. That predates the October 2025 Economic Evolution proposal, which removed the fixed cap and moved EGLD to tail inflation. To avoid asserting the superseded model as current, I did not add a standalone "Inflation (fixed cap)" entry; the current model is carried by the EGLD, Economic Evolution, Tail Inflation, and Staking V5 entries. It would be worth reconciling learn/economics.md with the Economic Evolution changes in a separate pass.

  2. Slashing framing. validators/overview.md defines stake slashing (a fine that loses EGLD, for serious offences), while validators/redundancy.md notes that slashing for double-signing is a near-future enforcement. The Slashing entry states that nuance rather than implying routine principal slashing; day-to-day unreliability is handled by rating and jailing. Please confirm that framing matches protocol intent.

  3. A few forward-looking / lightly-documented terms (Dual Staking on sovereign chains; parts of the agent stack) are labeled as directions or previews, in line with how the docs describe them. Corrections welcome.

Checks

  • Builds as MDX: all <, {, } occurrences are inside inline code spans; no bare tag-like tokens.
  • codespell docs/welcome/terminology.md --config .codespell passes clean (the same check as the Spell Check workflow).
  • US English, no em dashes, "onchain" as one word.
  • No sidebar or other file changes; the diff is limited to docs/welcome/terminology.md.

Replace the ~17-term terminology page with a sourced glossary of 206
terms across blockchain foundations, protocol and architecture,
consensus and security, tokens, network/nodes/staking, wallets,
ecosystem applications, upgrades, framework and SDK, the agent stack,
economics, governance, and day-to-day staking operations.

Every entry follows one format: a mechanical definition, a Context line
of MultiversX specifics, a See also line of cross-links, and a Source
line citing the specific docs page (or repo/post) it is drawn from.
The existing staking-operations terms are retained and enriched to the
same format. Foundational terms are included on purpose: what is
obvious to readers fluent in the docs is not obvious to first-timers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lamentierschweinchen lamentierschweinchen changed the base branch from main to development July 2, 2026 13:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants