docs(giga): rework Sei Giga pages for whitepaper v2.0 - #42
Conversation
- Rewrite learn/sei-giga, sei-giga-specs, and sei-giga-developers from primary sources: Giga whitepaper v2.0 (arXiv 2505.14914v3), the giga.seilabs.io roadmap, and the sei-chain v6.6 release line - Add snippets/giga-diagrams.jsx with 14 theme-aware SVG diagrams - Correct stale Giga executor/storage claims in node/node-operators.mdx (evmone wording, dead evm-ss-* keys, version-scoped defaults) - Update Giga teasers on the home and Learn landing pages, align MCP terminology in the brand kit and llms.txt generator config Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
PR SummaryLow Risk Overview
Adds Node / misc fixes: Reviewed by Cursor Bugbot for commit ce76861. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Edit documentation and snippets to adopt future-oriented wording for Sei Giga and unify terminology. Replaces present-tense claims with conditional/future phrasing (use of “will”), renames “Multi-concurrent proposer” to “Multi-Proposer” across pages and diagrams, clarifies Sedna as a private dissemination layer (no traditional public mempool), and tweaks related copy, keywords, and alt text. Also updates the LLMS generator intro and several snippet captions/ARIA labels to match the new phrasing. These are editorial/content updates only.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
A large, well-structured documentation rework of the Sei Giga pages plus 14 new theme-aware inline SVG diagram components; internal links/anchors, referenced pages, CSS variables, and the snippet import convention all check out, and cross-doc config keys are consistent. No blocking issues found; a few non-blocking verification and polish notes remain.
Findings: 0 blocking | 6 non-blocking | 0 posted inline
Blockers
- None at the file/PR level.
Non-blocking
- Review-tooling note: REVIEW_GUIDELINES.md is empty (no repo-specific standards to apply), and both codex-review.md and cursor-review.md are empty — the Codex and Cursor passes produced no output, so this synthesis reflects only my own review.
- External references are unverified: several cited arXiv IDs are future-dated (Sedna 2512.17045, PIVOT-K 2603.17614, Ambulance 2606.25099).
mint broken-linkstypically validates internal links only, so please confirm every external URL (arXiv, blog.sei.io, seiresearch.io, giga.seilabs.io) resolves and points to the intended paper before publishing. - In learn/sei-giga.mdx the roadmap table links both the "Giga whitepaper v1" and "Giga whitepaper v2" rows to the same arXiv abstract (2505.14914); a reader clicking v1 lands on v2. Consider linking /abs/2505.14914v1 for the v1 row (or dropping that link) to avoid confusion.
- snippets/giga-diagrams.jsx GigaMergeRule: the
dup: truefield on V1's txeis defined but never used — the dedup result is hardcoded in the executable-sequence array. Harmless dead data; either drive the strikethrough from it or drop the field. - Brand consistency check: the 14 diagrams use
--sei-maroon-50as a recurring accent throughout. The brand kit (updated in this same PR) restricts maroon/gold to emphasis/legacy use. The usage here reads as emphasis so it's likely fine, but worth a quick design review to confirm it aligns with the stated palette guidance. - Consider a follow-up to run the regenerate-llms workflow post-merge (already called out in the PR description) so llms.txt/llms-full.txt pick up the reworked pages.
Two review findings from Campbell: - Eidos (storage) lands before Ares on the roadmap. Reorder the two in the milestone table, the roadmap track diagram and its caption, the status callout, and the specs glossary entry. - FlatKV was listed as part of today's state commitment, but it ships disabled: sc-write-mode/sc-read-mode default to cosmos_only and sc-enable-lattice-hash to false, so memiavl alone produces the current app hash. Drop it from the "Sei today" column and say plainly that the code is in the binary but off by default. Also add the same default-off caveat to the specs implementation table and the SC/EVM cell in the storage migration guide, both of which read as though FlatKV were already active. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
A large, generally high-quality rewrite of the three Sei Giga pages plus 14 new theme-aware SVG diagrams; links, anchors, CSS variables, and the snippet-import convention all check out. Two issues should be fixed before merge: a self-contradictory consensus-quorum statement on the spec page (n - f and 2f + 1 are the same threshold when n = 3f + 1), and the removal of the only documented recipe for enabling the Giga Storage SC layer while the replacement text points at a guide that explicitly covers only the SS layer.
Findings: 3 blocking | 13 non-blocking | 8 posted inline
Blockers
REVIEW_GUIDELINES.md,codex-review.md, andcursor-review.mdare all empty in this checkout, so there were no repo-specific standards to apply and no Codex or Cursor findings to merge. Everything below is from this pass only.- 2 blocking issue(s) flagged inline on specific lines.
Non-blocking
- No prompt-injection or instruction-like content was found anywhere in the diff, commit messages, or PR body — the PR body's "post-merge: trigger regenerate-llms.yml" note is a legitimate operational reminder.
- The
regenerate-llms.ymlpost-merge step lives only in the PR description. Consider a follow-up issue or a checklist item so it isn't lost after squash-merge. - Frontmatter
descriptionvalues on all three Giga pages are 300–450 characters; search engines and the Mintlify card previews truncate around 155–160. Consider trimming to a single sentence and letting the page body carry the detail. snippets/giga-diagrams.jsxadds ~730 lines of hand-authored SVG with no automated coverage — verification is manual per the PR description. A minimal smoke test that imports the module and renders each of the 14 exports would catch import/JSX regressions cheaply.- The performance numbers are now duplicated across
index.mdx,learn/index.mdx,learn/sei-giga.mdx(two tables),learn/sei-giga-specs.mdx(two tables), andscripts/generate-llms.mjs. Any future revision has to touch six places; a shared snippet for the headline figures would reduce drift risk. - The roadmap lists the Autobahn testnet target as 200,000 TPS at 400 ms finality, which is slower than the already-reported devnet result of <250 ms on the same page. Both are sourced, but a half-sentence explaining why the public-testnet target is deliberately more conservative would prevent it reading as a regression.
- The roadmap table cites arXiv 2505.14914 for "Giga whitepaper v1" while the References section attributes the same ID to "whitepaper v2.0". Presumably v2 is a new arXiv version of the same submission — worth saying so explicitly (e.g. "arXiv 2505.14914v2").
- 6 suggestion(s)/nit(s) flagged inline on specific lines.
| Consensus will periodically fix a global order by committing a cut, a vector of every lane's current certified tip: | ||
|
|
||
| 1. Prepare. The slot's leader (chosen by stake-weighted selection, as in Tendermint) will bundle the latest certified tips into a cut proposal; replicas will validate the PoAs and broadcast prepare votes, forming a PrepareQC at `n - f` votes. | ||
| 2. Commit. Replicas will exchange commit votes over the PrepareQC; a CommitQC finalizes the cut. If the leader gathers only the minimum `n - f` commit votes, it will run an additional confirm phase, collecting `2f + 1` confirmations before the commit certificate is final. |
There was a problem hiding this comment.
[blocker] This sentence is self-contradictory. With n = 3f + 1 (stated in the table above), n - f = 2f + 1, so "if the leader gathers only the minimum n - f commit votes, it will run an additional confirm phase, collecting 2f + 1 confirmations" describes a confirm phase whose threshold is already met — a no-op.
Autobahn's fast/slow path distinction is all n votes (fast, commit immediately) versus n - f = 2f + 1 votes (slow, extra round). The content this replaces had it right ("Fast Path (n votes) — Immediate commit if all agree; Slow Path (2f+1 votes) — Additional round if needed"), so this is a regression on the page whose whole purpose is protocol accuracy. Suggest rewriting as: a CommitQC over all n votes finalizes immediately; if only n - f commit votes arrive, an extra confirm round is needed before the certificate is final.
| requires a fresh state sync: turning on the EVM SS split on a node with | ||
| existing data fails the startup safety checks, because the new EVM SS DB | ||
| starts empty while Cosmos SS already has history. The full procedure, | ||
| including the exact `app.toml` keys, startup verification, safety checks, |
There was a problem hiding this comment.
[blocker] This points operators to the Giga SS Store Migration Guide for "the exact app.toml keys", but that guide states explicitly ([state-commit] / "State commit is untouched by this migration") that it covers only the SS layer. The paragraph above, meanwhile, still says Giga Storage repartitions SeiDB "at both the SC and SS layers".
The deleted TOML block was the only place documenting the SC half — in particular sc-write-mode = "dual_write", sc-read-mode = "split_read", and the safety-relevant note that sc-enable-lattice-hash = true is required for split-mode app-hash equality. The bare key definitions survive in the reference app.toml at lines 219–228, but the working combination and the app-hash warning do not, and getting that combination wrong is exactly the kind of misconfiguration that halts a node.
Either keep a short SC-layer snippet here, or add an SC section to the migration guide before pointing at it as the source of truth.
| # Default: false | ||
| # enabled controls whether to use the Giga executor instead of the legacy execution path. | ||
| # Improves EVM throughput. | ||
| # Default: false through v6.5.x; true from the v6.6 release line. |
There was a problem hiding this comment.
[suggestion] The comment says the default is true from v6.6, but the sample immediately below sets enabled = false (same for occ_enabled on line 528). In a reference app.toml that operators copy from, this reads as "the recommended value is false" and silently contradicts the stated default. Consider showing enabled = true with a # false through v6.5.x note, or restructuring as a version-conditional callout.
| ## Current Architecture | ||
| | Property | Sei Giga | | ||
| | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | ||
| | Architecture | Multi-Proposer (MCP) EVM Layer 1; every validator will propose concurrently | |
There was a problem hiding this comment.
[suggestion] MCP collides with an established abbreviation in this same docs set: learn/index.mdx:52 defines "Sei Model Context Protocol (MCP) Server", and this PR edits that very page. Introducing MCP as "Multi-Proposer" here (and in the specs glossary) will confuse readers and search.
Secondly, the abbreviation doesn't match the expansion given — MCP stands for "multiple concurrent proposers" in the whitepaper, not "Multi-Proposer". Cleanest fix is to drop the parenthetical entirely and use "Multi-Proposer" unabbreviated throughout; if the whitepaper acronym must appear, define it once in the glossary as "multiple concurrent proposers (MCP)" with a note distinguishing it from Model Context Protocol.
| | Component | What it prices | Mechanism | | ||
| | -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | | ||
| | Execution fee | Gas consumed by execution | EIP-1559-style dynamic base fee driven by demand | | ||
| | Ordering fee | Position in the merged order | Priority fee, strictly enforced by the [deterministic merge rule](#mev-and-fee-design) | |
There was a problem hiding this comment.
[nit] The link text "deterministic merge rule" points at #mev-and-fee-design (the parent section) even though a ### Deterministic merge rule heading with anchor #deterministic-merge-rule exists further down. Same pattern in the security-model bullet ("deduplicated at merge"). Retargeting to the precise anchor lands readers on the actual rule.
| Giga will price three things separately (full details in the [fee model spec](/learn/sei-giga-specs#fee-model)): | ||
|
|
||
| ### Pattern 1: User-Isolated State | ||
| 1. The execution fee: an EIP-1559-style dynamic base fee for gas actually consumed. `eth_feeHistory` and `eth_maxPriorityFeePerGas` will remain your estimation tools. |
There was a problem hiding this comment.
[suggestion] "eth_feeHistory and eth_maxPriorityFeePerGas will remain your estimation tools" is stated without qualification, but this page and the spec both say the ordering fee is strictly enforced by lane max-tip and then socialised. Under that mechanism the semantics of a priority-fee estimate change materially: the tip now competes against other lanes' maxima rather than bidding for a proposer's favour, so a value derived from Ethereum-style history may not map onto the position you expect. Worth one clause noting that the RPCs stay available but their interpretation shifts (and that final parameters land with the fee-mechanism paper you already cite below).
| ))} | ||
| <text x={70} y={214} fontSize="9" fill={ink} fillOpacity="0.55">blocks</text> | ||
| {[0, 1, 2, 3].map((i) => ( | ||
| <path key={'w1' + i} d={`M ${70 + i * 184} 186 L ${70 + i * 184} 180 L ${208 + i * 184} 180 L ${208 + i * 184} 186`} fill="none" stroke={accent} strokeWidth="1.2" /> |
There was a problem hiding this comment.
[nit] The SuperBUD window brackets are 138 units wide but spaced 184 apart, so consecutive windows have visible gaps — yet the surrounding text describes "exponentially growing aligned windows". All four brackets are also drawn identically, so the exponential growth the caption promises isn't shown. Making the windows contiguous (width === spacing) and varying their widths would match the prose.
| const ink = 'currentColor'; | ||
| const accent = 'var(--sei-maroon-50)'; | ||
| const lanesIn = [ | ||
| { v: 'V1', max: 12, txs: [{ n: 'a', t: 12 }, { n: 'e', t: 8, dup: true }] }, |
There was a problem hiding this comment.
[nit] dup: true on V1's e is never read — the duplicate is instead hard-coded downstream via const dup = i === 5. The merge output itself is correct (V2 max 40 → V3 max 20 → V1 max 12, giving c, d, f, e, a, e with the V1 copy of e struck), but deriving the strike-through from the data rather than a magic index would keep the diagram honest if the example is ever edited.
1 participant
Summary
Full rework of the Sei Giga documentation.
Pages rewritten
learn/sei-giga: answer-first overview — architecture in four stages, transaction lifecycle, MEV and fee design, the 11-milestone roadmap with statuses, dated performance tablelearn/sei-giga-specs: complete protocol spec — Autobahn (lanes, f+1 Proofs of Availability, cut-of-tips ordering, 1.5 round trips), the two finality notions, Block-STM OCC, flat storage with LtHash divergence digests, BUD/SuperBUD proofs, Sedna, merge rule and socialised tips, post-quantum path, implementation snapshot, glossary, referenceslearn/sei-giga-developers: what changes for builders — which finality signal per use case, mempool-free submission, three-part fees, parallel-friendly contract patterns, precompile fast-path caveat, prepare-today checklistNew diagrams
snippets/giga-diagrams.jsx: 14 theme-aware inline SVG components (proposer comparison, async pipeline, transaction journey, roadmap track, lanes and cuts, slot pipelining, attestation flow, OCC, storage stack, BUD windows, merge rule, finality signals, fee split, parallelism contrast), each with a caption and aria-labelCorrections elsewhere
node/node-operators.mdx: removed the incorrect "evmone-based executor" description (the engine is Sei's go-ethereum fork; evmone is optional and unused in production), removed the stale Giga Storageapp.tomlexample whoseevm-ss-write-mode/evm-ss-read-modekeys no longer exist (superseded byevm-ss-split), and version-scoped the[giga_executor]defaults (false through v6.5.x; true with OCC from the v6.6 release line)Verification
mint broken-linkspasses; every in-page anchor verifiedPost-merge note: trigger the
regenerate-llms.ymlworkflow sollms.txt/llms-full.txtpick up the new pages.🤖 Generated with Claude Code