Docs/learn emission mechanism - #88
Open
J0ET0M wants to merge 3 commits into
Open
Conversation
added 2 commits
August 20, 2026 23:00
New page covering Qubic's halving mechanism end-to-end: from gross emission (ISSUANCE_RATE) down to the smart contract that actually removes QU from circulating supply. Grounded in the 2024 approved proposal that created SWATCH and in the current qubic/core source. Structure: - Two different things called 'halving' — Bitcoin's vs Qubic's (avoids confusion — Qubic doesn't cut gross emission, it changes the routing fraction) - Gross vs net emission (ISSUANCE_RATE unchanged; net changes) - Multi-epoch flow: election → work → revenue distribution - The routing table: GQMPROP.revenueDonation structure, quorum vote flow, sequential application (compounding fractions), auto-cleanup at BEGIN_EPOCH - SWATCH — the Emission SC (approved proposal quote as origin document) - What SWATCH does today (BEGIN_EPOCH mechanism, fee-reserve top-ups + qpi.burn() remainder) - Contract fee reserves = burn destinations (the correct mental model — QU sent to a fee reserve are destroyed, not held) - Phase 2 — Supply Watch (adaptive burn control accounting for ecosystem burns; ties SWATCH name to design intent) - How to verify current state (links to inspect-network-state) - Sources: code files + approved proposal + whitepaper §14 Wired into sidebar under Basics category (alongside tokenomics + inspect-network-state). This doc is the detail complement to tokenomics.md — tokenomics gives the overview, this gives the mechanism. No line references in code citations (per project convention that the code evolves).
Each diagram in both light and dark variants, wired via ThemedImage so it matches the reader's current theme (same pattern as upgrading.md). Diagrams (following the docs visual language established by _generate_upgrading_diagrams.py): 1. emission-multi-epoch — 4-step timeline across an epoch boundary: Work (epoch N) → Elect (boundary) → Work (epoch N+1) → Distribute. Illustrates why revenue distribution runs in the epoch after the work that earned it. 2. emission-sequential-deduction — full-width horizontal bar showing how a per-computor revenue is split when the routing table is applied sequentially. Numbered steps below spell out each fraction of the remaining pool. Reader arrives at 'computor keeps ~18%' concretely. 3. emission-swatch-begin-epoch — SWATCH's mechanism: incoming balance flowing to 4 outcome boxes (3 fee-reserve top-ups + qpi.burn() remainder). Bottom callout emphasizes the correct mental model — 'Contract fee reserves are burn destinations: QU sent there are destroyed, not held.' 4. emission-supply-watch-phase2 — the Phase 2 stacked bar showing SWATCH shrinking (68%) as SC IPO, dust, and other burns contribute to the same emission-schedule target. Contrasts explicitly with Phase 1 (SWATCH burns 100% of what it receives). Palette matches _generate_upgrading_diagrams.py exactly (BLUE, GREEN, GOLD, PURPLE, RED accents). Theme colors from theme_colors(mode) function — light bg #FFFFFF, dark bg #1B1B1D (Docusaurus dark default). Generator script committed alongside for regeneration. Doc updates: 4 ThemedImage tags added at natural section breaks, plus the import statements at the top of the file.
✅ Deploy Preview for docs-qubic-org ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Roger: 'the first graphic election, work... has many text overlays.
e.g. text of point 2 is behind point 3.'
Cause: step labels + sub text were positioned to the RIGHT of each
badge (x + 34), so step 2's sub text 'top 676 seat next epoch'
extended horizontally into step 3's badge zone.
Fix: stack each step's text vertically below the badge with
text_center(). Steps are also evenly spaced (200, 450, 750, 1000)
so each has ~250 px of horizontal room — no text collides with
adjacent badges.
Also:
- Moved 'Epoch N' + 'Epoch N+1' column headers slightly inward so
they don't hug the epoch-boundary line.
- Refined column sub-labels to be more compact ('the current 676
computors work' / 'top 676 UPoW scorers of epoch N are seated').
fnordspace
approved these changes
Aug 21, 2026
fnordspace
left a comment
fnordspace
left a comment
Contributor
There was a problem hiding this comment.
Besides that it looks good too me.
| 4. **End of epoch N: distribute.** Whatever is left after the donation-table pass is paid to the computor; the residual of the epoch's ISSUANCE_RATE that wasn't consumed by computors goes to the arbitrator identity. | ||
| 5. **Epoch N+1 begins.** The next epoch's computor set is seated (elected from the highest UPoW-scoring identities of epoch N), and the loop repeats. | ||
|
|
||
| Points 2 and 3 happen inside `endEpoch()` in `qubic/core/src/qubic.cpp`. Point 5 is the boundary transition — see [Upgrading](../computors/upgrading.md) for the tick-continuity mechanics. |
Contributor
There was a problem hiding this comment.
Include 4:
"Points 2, 3 and 4 happen inside "
| <ThemedImage | ||
| alt="Election, work, and revenue span two epochs" | ||
| sources={{ | ||
| light: useBaseUrl('/img/emission-multi-epoch-light.png'), |
Contributor
There was a problem hiding this comment.
Seems this graphic is missleading and/or wrong
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.