docs: add USDN section#23
Conversation
WalkthroughAdds a new USDN documentation section (category, overview, architecture, integration, references), enables KaTeX and Mermaid in Docusaurus configuration and dependencies, and introduces a Root theme component that injects Mermaid dark-mode CSS. No runtime application logic changed. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Author as Content Author
participant CI as Build / Site Generator
participant Remark as remark-math
participant Rehype as rehype-katex
participant Mermaid as Mermaid Renderer
participant Root as Root Theme Component
participant Browser as User Browser
Author->>CI: Commit docs + config changes
CI->>Remark: Parse math blocks
Remark-->>CI: Math AST
CI->>Rehype: Render KaTeX HTML
Rehype-->>CI: KaTeX markup
CI->>Mermaid: Render diagrams to SVG
Mermaid-->>CI: SVG output
CI-->>Browser: Serve built site
Browser->>Root: Load theme component
Root-->>Browser: Inject Mermaid dark-mode CSS
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (4)
🚧 Files skipped from review as they are similar to previous changes (4)
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
🧹 Nitpick comments (12)
docs/usdn/references.mdx (4)
10-12: Use descriptive link text instead of bare URLsImproves accessibility/SEO and readability.
- - https://docs.m0.org: Foundation for USDN's rebasing mechanism - - https://docs.wormhole.com: USDN's cross-chain messaging protocol + - [M0 Docs](https://docs.m0.org) — foundation for USDN’s rebasing mechanism + - [Wormhole Docs](https://docs.wormhole.com) — cross-chain messaging protocol
15-19: Add gRPC/REST endpoints and ICS-20 channel referencesDevelopers often need more than RPC/explorer. Consider adding gRPC, REST, and a link to channel registry or a note on where to find channels.
Noble Mainnet: - Chain ID: noble-1 - - RPC: https://rpc.noble.io + - RPC: https://rpc.noble.io + - gRPC: <add if available> + - REST: <add if available> + - IBC Channels: see chain registries/explorer for live channels (subject to change)
22-24: Clarify repo purposeIf “dollar” is the USDN module and “noble” is the chain, note that explicitly.
- - https://github.com/noble-assets/dollar: USDN repo - - https://github.com/noble-assets/noble: Noble blockchain repo + - https://github.com/noble-assets/dollar — USDN (x/dollar) module + - https://github.com/noble-assets/noble — Noble blockchain
27-29: Add community guidelines linkIf you have a forum or docs contribution guide, link it here.
docs/usdn/integration.mdx (2)
12-18: Clarify operational ownership and timing for rewards registrationWho submits the on-chain transaction and typical SLA/epoch when accrual starts? Add a brief note to set expectations.
-3. The rewards distribution is registered by Noble validators to accrue to the address of choice. +3. Noble governance/operators register the rewards distribution on-chain. Accrual typically begins after confirmation in the next index update window (timing subject to network conditions).
19-23: Link to integration specs and failure modesAdd links or bullets for: message formats, retries/timeouts, idempotency, and monitoring hooks for IBC/Hyperlane deliveries.
#### Supported Network Types: - Cosmos SDK chains (via IBC) - Ethereum and EVM-compatible chains (via Hyperlane) - - Custom integrations available for other networks. [Contact our team](https://www.noble.xyz/#contact) for a custom solution based on your blockchain's state machine and canonical bridge. + - Custom integrations available for other networks. [Contact our team](https://www.noble.xyz/#contact). + +> Note: Implement delivery retries, idempotency keys, and observability for cross-chain messages. See IBC and Hyperlane ops guides.docs/usdn/overview.mdx (4)
25-31: Feature bullets: add caveat for cross-chain rewards latencySet expectation that rewards delivery depends on index updates and bridge finality.
-- **Composable Rewards for Integrators**: Stream cross-chain rewards from Noble to your network via [IBC](https://ibcprotocol.dev/) or [Hyperlane](https://hyperlane.xyz/). +- **Composable Rewards for Integrators**: Stream cross-chain rewards via [IBC](https://ibcprotocol.dev/) or [Hyperlane](https://hyperlane.xyz/); delivery subject to update cadence and bridge finality.
32-37: Collateral section: add source link and remove absolute phrasingYou already link to M0 dashboard; mark the ratio as dynamic and timestamped.
-**As of writing, USDN has a collateralization ratio of 102%.** +Collateralization ratio is dynamic; see the [M0 dashboard](https://dashboard.m0.org/) for current figures (snapshot as of September 2025 was ~102%).
46-50: Forward-looking statements: add “subject to change” notePoints Vault and Managed Vault are future-facing—add a brief disclaimer.
-- Deposit USDN into the Hyperliquid Managed Vault [Coming Soon!] +- Deposit USDN into the Hyperliquid Managed Vault (coming soon; subject to change)
8-9: Heading level: avoid duplicate H1Docusaurus renders title as H1. Change “# Overview” to “## Overview”.
-# Overview +## Overviewdocs/usdn/architecture.mdx (2)
54-61: Portal paragraph: clarify burn/mint and nomenclatureMinor wording to avoid implying USDN mints unconditionally without bridge finality.
-When $M is transferred from Ethereum [...] it gets minted on Noble as USDN. +When $M is bridged from Ethereum, USDN is minted on Noble per Portal/NTT finalization and configuration.
270-285: Rounding mode and precisionYou mention “rounded” but not how. Specify rounding mode (bankers, floor) to avoid accounting discrepancies.
-Principal Amount = Present Amount × 1e12 ÷ Index (rounded) +Principal Amount = Present Amount × 1e12 ÷ Index (rounded to nearest integer; ties = <mode>)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (4)
docs/usdn/architecture.pngis excluded by!**/*.pngdocs/usdn/flow.pngis excluded by!**/*.pngpackage-lock.jsonis excluded by!**/package-lock.jsonyarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (5)
docs/usdn/_category_.json(1 hunks)docs/usdn/architecture.mdx(1 hunks)docs/usdn/integration.mdx(1 hunks)docs/usdn/overview.mdx(1 hunks)docs/usdn/references.mdx(1 hunks)
🔇 Additional comments (7)
docs/usdn/_category_.json (1)
1-5: Category config looks goodLabel, position, and collapsed are correctly set for Docusaurus.
docs/usdn/integration.mdx (1)
25-26: Institutional onboarding: add KYC/compliance note (if applicable)If institutions must complete due diligence before configuration, call it out here.
docs/usdn/overview.mdx (1)
20-24: Tighten wording on Portal/NTT minting semanticsClarify lock/burn vs mint mechanics to prevent misconceptions; note that exact flows are per M0 Portal/NTT config.
-By locking $M on Ethereum [...] Noble can mint USDN on‐chain +Via M0’s Portal (powered by Wormhole NTT), $M is locked/burned on the source and minted on Noble as USDN per bridge configuration.docs/usdn/architecture.mdx (4)
30-34: Index update source and cadenceSpecify how often index updates occur and who is authorized to submit them; link to spec.
70-97: Cosmos TX JSON structure and types are non-canonicalExamples use bare numbers and simplified fields. Cosmos SDK JSON typically encodes coins with denom/amount as strings. Fix types or label examples as pseudo-code to prevent copy/paste errors.
- "@type": "/noble.dollar.v1.MsgClaimRewards", - "signer": "noble1user" + "@type": "/noble.dollar.v1.MsgClaimRewards", + "signer": "noble1user"Also consider annotating: “Example payload (abbreviated; field names/types subject to change).”
127-158: MsgTransfer fields likely mismatch protos
destination_chain_idas number and base64 fields may not match actual proto. Replace with accurate fields (e.g., bech32 recipient, chain identifiers) or clearly mark as illustrative.- "destination_chain_id": 2, - "destination_token": "base64_encoded_destination_token", - "recipient": "base64_encoded_recipient_address" + "destination_chain_id": "<chain identifier>", + "recipient": "<recipient address>", + "...": "see proto definitions"
250-265: CLI commands: verify subcommand names and argsDouble-check module/command paths (e.g.,
tx dollar portal deliver) and vaults enum spelling. Provide--gas-prices/--gas-adjustmentexamples.-nobled tx dollar portal deliver <vaa_payload> --from <signer> +nobled tx dollar portal deliver <vaa_payload> --from <signer> --gas-prices 0.025unoble --gas-adjustment 1.3
0xstepit
left a comment
0xstepit
left a comment
There was a problem hiding this comment.
Amazing job here @adiraviraj! Thanks for this very detailed USDN section. I've added a couple of suggestions to the files
Co-authored-by: stepit <48993133+0xstepit@users.noreply.github.com>
Co-authored-by: stepit <48993133+0xstepit@users.noreply.github.com>
Co-authored-by: stepit <48993133+0xstepit@users.noreply.github.com>
Co-authored-by: stepit <48993133+0xstepit@users.noreply.github.com>
MalteHerrmann
left a comment
MalteHerrmann
left a comment
There was a problem hiding this comment.
Thanks for this contribution to our docs @adiraviraj -- I also left a bunch of comments with suggestions for improvements but it's a great addition to the existing knowledge base 🙌 let me know if I should help you address the open comments!
|
|
||
| ## Use Cases | ||
|
|
||
| ### For Integrators |
There was a problem hiding this comment.
also I would remove the "for" in both of these headlines
| ### For Integrators | |
| ### Integrators |
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
Co-authored-by: MalteHerrmann <42640438+MalteHerrmann@users.noreply.github.com>
- remove sidebar position - fix broken images issue - added mermaid support - added LaTeX support - updated wording for clarity on index, yield distribution, claims process - standardize punctuation - corrected NOBLE ticker - removed message types, CLI commands, and collateral section - added integration use cases
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
src/theme/Root.js (2)
7-68: Consider safer alternatives to dangerouslySetInnerHTML for CSS injection.While the CSS content appears safe (no executable JavaScript), using
dangerouslySetInnerHTMLcreates potential security risks and triggers static analysis warnings. Consider these safer alternatives:
- Move styles to a CSS file and import it
- Use a CSS-in-JS solution like styled-components
- Create individual style objects for each CSS rule
Here's a safer approach using a separate CSS file:
Create
src/css/mermaid-dark.css:/* Shared tweaks */ .mermaid svg .node rect, .mermaid svg .node path, .mermaid svg .node polygon, .mermaid svg .cluster rect { stroke-width: 2px; } .mermaid svg .cluster rect { rx: 12px; ry: 12px; } /* Dark mode overrides (scoped to site toggle) */ html[data-theme="dark"] .mermaid svg { background: transparent !important; } /* ... rest of your styles ... */Then update
Root.js:import React from 'react'; +import '../css/mermaid-dark.css'; export default function Root({children}) { return ( - <> - {children} - <style - data-mermaid-darkfix - dangerouslySetInnerHTML={{ - __html: `/* ... CSS content ... */`, - }} - /> - </> + <>{children}</> ); }
3-3: Add PropTypes or TypeScript for better type safety.Consider adding prop validation to ensure
childrenis properly typed, especially since this is a root-level component that wraps the entire application.Add PropTypes:
import React from 'react'; +import PropTypes from 'prop-types'; export default function Root({children}) { // ... component logic } +Root.propTypes = { + children: PropTypes.node.isRequired, +};Or convert to TypeScript:
import React, { ReactNode } from 'react'; interface RootProps { children: ReactNode; } export default function Root({ children }: RootProps) { // ... component logic }docusaurus.config.js (1)
33-41: Consider updating to the latest KaTeX version for security and features.You're using KaTeX 0.13.24 in the CDN link, but your
package.jsonspecifieskatex@^0.16.22. Consider updating the CDN link to match the installed version for consistency.- href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css', + href: 'https://cdn.jsdelivr.net/npm/katex@0.16.22/dist/katex.min.css', type: 'text/css', integrity: - 'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM', + 'sha384-<update-with-correct-integrity-hash>', crossorigin: 'anonymous',You'll need to update the integrity hash for the new version. You can get the correct hash from the CDN or generate it using tools like SRI Hash Generator.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
package-lock.jsonis excluded by!**/package-lock.jsonyarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (9)
docs/usdn/_category_.json(1 hunks)docs/usdn/architecture.mdx(1 hunks)docs/usdn/integration.mdx(1 hunks)docs/usdn/overview.mdx(1 hunks)docs/usdn/references.mdx(1 hunks)docusaurus.config.js(5 hunks)package.json(2 hunks)src/css/custom.css(1 hunks)src/theme/Root.js(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- src/css/custom.css
- docs/usdn/architecture.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/usdn/references.mdx
- docs/usdn/overview.mdx
- docs/usdn/category.json
- docs/usdn/integration.mdx
🧰 Additional context used
🪛 Biome (2.1.2)
src/theme/Root.js
[error] 9-9: Avoid passing content using the dangerouslySetInnerHTML prop.
Setting content using code can expose users to cross-site scripting (XSS) attacks
(lint/security/noDangerouslySetInnerHtml)
🔇 Additional comments (5)
package.json (1)
20-20: Verify dependency versions for compatibility and security.The added dependencies support Mermaid diagrams and math rendering. Ensure these versions are compatible with your Docusaurus version (3.7.0) and check for any security advisories.
Perfect! The search results confirm that the dependency versions you're using are correct for Docusaurus 3.7.0. Docusaurus v3 requires remark-math 6 and rehype-katex 7, which matches your configuration exactly.
The packages look properly configured:
@docusaurus/theme-mermaid@^3.7.0matches your Docusaurus versionremark-math@^6.0.0andrehype-katex@^7.0.1are the recommended versionskatex@^0.16.22is a recent stable versionAlso applies to: 29-32
docusaurus.config.js (4)
8-9: LGTM! Imports correctly match the package versions.The imports for
remarkMathandrehypeKatexare properly configured for Docusaurus v3 compatibility.
64-65: LGTM! Math plugins properly configured.The
remarkMathandrehypeKatexplugins are correctly configured in the docs preset, matching the recommended setup for Docusaurus v3.
75-78: LGTM! Mermaid integration properly configured.The Mermaid theme and markdown configuration follow the standard Docusaurus pattern for enabling Mermaid diagrams globally.
195-216: Excellent Mermaid theme configuration with comprehensive styling.The configuration includes proper light/dark theme support with detailed theme variables. The styling choices (colors, fonts, borders) create a cohesive visual experience that should integrate well with your site's design system.
0xstepit
left a comment
0xstepit
left a comment
There was a problem hiding this comment.
We're almost there, amazing job @adiraviraj! I left just a couple of comments but looking forward to have the section live!!!!
Co-authored-by: stepit <48993133+0xstepit@users.noreply.github.com>
- update M to $M - add info on collateralization ratio - removed community links - updated comments on custom.css - standardize letter case - update cross-chain diagram - removed vaults section
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
docusaurus.config.js (2)
64-66: Docs preset: remark/rehype plugin order is correct.remarkMath before rehypeKatex is the right sequencing.
If you ever render untrusted content, insert rehype-sanitize before rehype-katex. Based on learnings.
195-216: Mermaid theming: consider dark-mode specificity for background/text.You set background '#ffffff' and text '#111827' globally; this can clash in dark mode unless your custom Root CSS overrides every diagram. Either:
- Provide separate light/dark themeVariables, or
- Drop hard background to let Mermaid/Docusaurus dark theme handle it.
Example (split vars):
mermaid: { - theme: { light: 'base', dark: 'base' }, - options: { themeVariables: { background: '#ffffff', textColor: '#111827', ... } } + theme: { light: 'base', dark: 'base' }, + options: { + themeVariables: { /* light */ background: '#ffffff', textColor: '#111827', ... }, + darkThemeVariables: { /* custom */ background: '#0b1220', textColor: '#e5e7eb' } + } }Or keep a single set but remove background to respect dark theme defaults.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
docs/usdn/architecture.mdx(1 hunks)docs/usdn/overview.mdx(1 hunks)docs/usdn/references.mdx(1 hunks)docusaurus.config.js(5 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/usdn/references.mdx
- docs/usdn/architecture.mdx
🧰 Additional context used
🪛 GitHub Actions: Spell Check
docs/usdn/overview.mdx
[error] 13-13: codespell: misspelling detected. 'extention' should be 'extension'.
🔇 Additional comments (2)
docusaurus.config.js (2)
75-79: Approve –@docusaurus/theme-mermaiddependency verified
Listed in package.json at version ^3.7.0.
8-9: ESM support verified package.json engines.node is set to ≥18.0 and CI uses Node 18, so remark-math and rehype-katex integration will work as expected.
3 participants
Summary by CodeRabbit
New Features
Documentation
Style
Chores