docs: add a book for platform development with design philosophy#3080
docs: add a book for platform development with design philosophy#3080QuantumExplorer merged 5 commits intov3.1-devfrom
Conversation
📝 WalkthroughWalkthroughIntroduces a new mdBook documentation build pipeline with configuration, GitHub Actions CI/CD workflow, table-of-contents structure, and documentation content on shielded transaction fees. Includes build artifact deployment to GitHub Pages triggered by version branch pushes or manual dispatch. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Fix all issues with AI agents
In `@book/book/architecture/component-pipeline.html`:
- Around line 553-567: The HTML contains a dev-only LiveReload WebSocket snippet
(wsProtocol, wsAddress, new WebSocket, socket.onmessage, window.onbeforeunload)
that comes from running mdbook serve; regenerate the site using mdbook build (or
add a CI step to run mdbook build) so the produced files no longer include this
script before committing/deploying.
In `@book/book/architecture/overview.html`:
- Around line 390-408: The "Other" category contains an incorrect crate name:
replace the <code>rs-platform-wallet</code> entry with
<code>platform-wallet</code> in the HTML table row that lists Other crates (look
for the table cell containing "Other" and the sibling cell listing
<code>dash-platform-macros</code>, <code>rs-dash-event-bus</code>,
<code>rs-platform-wallet</code>, ...). Update that cell text to
"platform-wallet" so the displayed crate name matches the workspace.
In `@book/book/css/chrome-ae938929.css`:
- Around line 657-659: The media query currently uses the obsolete Firefox-only
feature `-moz-touch-enabled`; remove that unsupported media feature and use only
the standard `(pointer: coarse)` media query so the rule applies to coarse
pointers; update the rule containing `.chapter li a` and `.spacer` (the media
block that currently reads `@media (-moz-touch-enabled: 1), (pointer: coarse) {
... }`) to rely solely on `(pointer: coarse)`.
In `@book/book/css/print-9e4910d8.css`:
- Around line 9-46: Update the CSS to use modern break properties alongside the
legacy ones and remove unit from zero values: add break-inside: avoid and
break-after: avoid to the h1, h2, h3, h4, h5, h6 rule (while keeping
page-break-* for compatibility), add break-inside: avoid to the pre, code and
.page selectors (in addition to existing page-break-inside), and change
margin-inline-start: 0px in `#mdbook-page-wrapper.page-wrapper` to
margin-inline-start: 0 (and any other 0px occurrences to 0) so it conforms to
length-zero-no-unit; leave existing properties otherwise unchanged.
In `@book/book/drive/cost-tracking.html`:
- Around line 331-344: The snippet in consume_to_fees_v0 references an undefined
variable system_amount inside the SectionedStorageRemoval arm; fix by deriving
or exposing the correct value and passing it into
FeeRefunds::from_storage_removal (or clarify with an inline comment). Locate the
match on cost.storage_cost.removed_bytes and either (a) compute system_amount
from removal_per_epoch_by_identifier (or other available data such as total
system-removed bytes or a field on the SectionedStorageRemoval) before the
return tuple, or (b) replace system_amount with the appropriate existing
variable name; ensure the SectionedStorageRemoval arm calls
FeeRefunds::from_storage_removal(removal_per_epoch_by_identifier, epoch.index,
epochs_per_era, previous_fee_versions)? and returns the computed system_amount
alongside the FeeRefunds value so the tuple types match.
In `@book/book/error-handling/consensus-errors.html`:
- Line 226: Update or remove the ambiguous sentence "There are five things worth
understanding here." so it matches the actual sections; either change the count
to the correct number of topics covered (or to a dynamic phrasing like "a few
things" or "several things") or remove the sentence entirely to avoid future
mismatches — locate the exact sentence in the document (the paragraph containing
"There are five things worth understanding here.") and edit it to accurately
reflect the list that follows (four categories, ordering rule, derive stack,
platform_serialize attribute, nesting, leaf error anatomy, test-only variant).
In `@book/book/serialization/platform-serialization.html`:
- Around line 395-408: The example for fn platform_versioned_decode has a
mismatched parameter name: the function signature uses platform_versioned while
the body calls platform_version; update the body to use platform_versioned
(e.g., change the call to T::platform_versioned_decode(decoder,
platform_versioned)? ) so the parameter name is consistent with the signature
and references to platform_versioned throughout the example (look for
platform_versioned_decode, platform_versioned, and the
T::platform_versioned_decode call).
- Around line 472-486: The committed HTML contains an injected LiveReload
WebSocket block (symbols: wsProtocol, wsAddress, new WebSocket(...), socket,
window.onbeforeunload) that should not be in production output; regenerate the
book output using mdbook build (not mdbook serve) so the livereload script is
excluded from all generated files, then replace the committed HTML files in the
book/ directory with the freshly built files.
🧹 Nitpick comments (4)
book/book/book-a0b12cfe.js (1)
1-843: Consider excluding generated mdBook build artifacts from version control.This file is auto-generated by mdBook (note the content-hash suffix
book-a0b12cfe.js). Committing build output increases repo size, creates noisy diffs on regeneration, and risks the committed version drifting from the actual build. Consider addingbook/book/to.gitignoreand generating the site in CI instead.Because this is generated code, the 4-space indentation and
snake_casenaming that conflict with the project's JS coding guidelines are not worth changing manually—they'd be overwritten on the next build.book/book/serialization/platform-serialization.html (1)
1-507: Consider not committing generated HTML output to the repository.These HTML files are build artifacts produced by mdBook from Markdown sources. Committing them creates maintenance overhead (merge conflicts, large diffs of generated code) and risk of staleness if someone edits Markdown but forgets to rebuild. A common pattern is to build and deploy the book in CI (e.g., GitHub Pages via GitHub Actions) and keep only the Markdown sources in the repo.
If there's a specific reason to vendor the built book (e.g., offline access without tooling), consider adding a CI check that verifies the committed HTML matches a fresh
mdbook build.book/book.toml (1)
8-9: Consider not committing thebook/book/build output directory.With
build-dir = "book", runningmdbook buildin thebook/directory generates all output intobook/book/. The entirebook/book/tree (HTML, CSS, JS, fonts) in this PR appears to be generated build artifacts — analogous to committing adist/folder.Committing generated output causes:
- Large, hard-to-review diffs on every documentation edit
- Potential merge conflicts on auto-generated files
- Risk of stale output if source is edited but not rebuilt
- Development-only code shipped in committed files (e.g., the livereload WebSocket script present in every HTML page)
The standard approach is to commit only the source (
book/src/) and config (book/book.toml), then build in CI (e.g., a GitHub Actions workflow that runsmdbook buildand deploys to GitHub Pages). Addbook/book/to.gitignore.book/book/sdk/put-operations.html (1)
567-581: Livereload script included — files appear built withmdbook serveinstead ofmdbook build.All five HTML files contain the livereload WebSocket script. This script is injected only by
mdbook servefor local development and is not present inmdbook buildoutput. When these pages are deployed, every visitor's browser will attempt a WebSocket connection to a non-existent/__livereloadendpoint, producing console errors.Regenerate these files with
mdbook buildbefore committing, or add a CI step that runsmdbook buildto produce the final artifacts.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
.github/workflows/book.yml (1)
13-16: Scope write permissions to the deploy job only.
pages: writeandid-token: writeare only needed for deployment. Keeping them workflow-wide gives the build job unnecessary privileges.🔧 Suggested least-privilege layout
-permissions: - contents: read - pages: write - id-token: write +permissions: + contents: read jobs: build: name: Build book runs-on: ubuntu-24.04 + permissions: + contents: read @@ deploy: name: Deploy to GitHub Pages needs: build runs-on: ubuntu-24.04 + permissions: + pages: write + id-token: writeAlso applies to: 23-25, 45-51
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/book.yml around lines 13 - 16, Top-level permissions currently grant pages: write and id-token: write workflow-wide; restrict them to the deploy job by leaving top-level permissions as minimal (e.g., contents: read) and moving pages: write and id-token: write into the deploy job's permissions block (add or update the deploy job's permissions to include pages: write and id-token: write). Also find the other permissions blocks in the file with the same scopes (the ones mentioned in the comment) and apply the same change: remove write scopes from global/work-level permissions and add them only to the deploy job's permissions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/book.yml:
- Around line 30-35: In the "Install mdBook" CI step, stop streaming the tarball
directly into tar; instead download the mdBook tarball and its official checksum
(or .sha256) to disk, verify the tarball's SHA256 against the downloaded
checksum (e.g., via sha256sum --check or equivalent), and only extract into
"$HOME/.local/bin" after the checksum verification succeeds; update the step
that currently runs under the "Install mdBook" name to use curl -fSL to save
both files, perform the checksum comparison, and fail the job if the
verification does not match.
In `@book/src/state-transitions/shielded-fees.md`:
- Around line 52-54: The Markdown fences in the shielded-fees document lack
language tags; update the opening triple backticks for the blocks containing the
min_fee formula, the storage_fee_per_action calculation, the flow snippet "... →
Basic Structure → Minimum Fee Check → ZK Proof Verification → ...", the
pool_balance adjustments (ShieldedTransfer / Unshield / ShieldedWithdrawal), and
the sighash formula to include a language (use "text") so each fence becomes
```text; ensure all other similar fences in the same file (those around
storage_fee_per_action, the flow line, the Shielded... lines, and the sighash
line) are changed the same way to satisfy markdownlint MD040.
---
Nitpick comments:
In @.github/workflows/book.yml:
- Around line 13-16: Top-level permissions currently grant pages: write and
id-token: write workflow-wide; restrict them to the deploy job by leaving
top-level permissions as minimal (e.g., contents: read) and moving pages: write
and id-token: write into the deploy job's permissions block (add or update the
deploy job's permissions to include pages: write and id-token: write). Also find
the other permissions blocks in the file with the same scopes (the ones
mentioned in the comment) and apply the same change: remove write scopes from
global/work-level permissions and add them only to the deploy job's permissions.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.github/workflows/book.yml.gitignorebook/src/SUMMARY.mdbook/src/state-transitions/shielded-fees.md
✅ Files skipped from review due to trivial changes (1)
- book/src/SUMMARY.md
QuantumExplorer
changed the title
QuantumExplorer
changed the title
2 participants
What was done?
Added comprehensive documentation covering architecture, versioning, state transitions, error handling, serialization, data models, drive operations, testing, SDK patterns, and WASM bindings.
Checklist
For repository code-owners and collaborators only