refactor: move contracts under Build > API, merge manuals into guides#121
refactor: move contracts under Build > API, merge manuals into guides#121
Conversation
- Move docs/contracts/ to docs/build/api/contracts/ with Deployed
Addresses as the section index (skip vendor README)
- Merge docs/manuals/ into docs/guides/manuals/
- Remove Contracts and Manuals navbar links
- Remove contractsSidebar and manualsSidebar
- Update sync-contracts-docs.js output path and sidebar references
- Update homepage and supported-chains links
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR restructures the documentation layout by relocating contract documentation from Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
Suggested reviewers
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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/build/api/contracts/sdk/_category_.json (1)
1-10:⚠️ Potential issue | 🟡 MinorThis file will be overwritten by the sync script.
The sync script calls
cleanDir(DEST)which wipesdocs/build/api/contracts/before regenerating. Since the script'swriteCategorycall for CATEGORIES doesn't pass thekeyparameter (bug flagged insync-contracts-docs.js), the"key": "contracts-sdk"field will be lost on the next sync run.Either fix the script to pass
cat.key(as suggested), or this manual addition will need to be re-added after every sync.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/api/contracts/sdk/_category_.json` around lines 1 - 10, The generated category JSON is losing its "key" because the sync script's writeCategory call in sync-contracts-docs.js does not pass the category key; update the call that writes CATEGORIES (the writeCategory invocation) to include cat.key (or the equivalent property) so the generated object includes "key": "contracts-sdk" on regen, ensuring the writeCategory function receives and writes the key field for each category.scripts/sync-contracts-docs.js (1)
383-388:⚠️ Potential issue | 🟡 MinorThe
keyparameter is not passed when writing sub-category files.The
writeCategoryfunction was updated to accept an optionalkeyparameter (line 120), and the SDK category defineskey: 'contracts-sdk'(line 341). However, the loop writing sub-categories doesn't passcat.keytowriteCategory, so the key will never be written tosdk/_category_.jsonby this script.🔧 Proposed fix
for (const cat of CATEGORIES) { writeCategory(path.join(DEST, cat.dir), { label: cat.label, position: cat.position, + key: cat.key, }); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/sync-contracts-docs.js` around lines 383 - 388, The loop that writes sub-category files calls writeCategory without forwarding the optional key, so CATEGORIES entries like the SDK item (key 'contracts-sdk') never get written; update the loop to pass cat.key into writeCategory (e.g., writeCategory(path.join(DEST, cat.dir), { label: cat.label, position: cat.position }, cat.key)) so the key is persisted into sdk/_category_.json and other sub-category files; keep using the existing writeCategory signature and handle undefined keys as before.docs/build/api/contracts/sdk/api-reference.md (1)
89-89:⚠️ Potential issue | 🟠 MajorBroken link: the referenced path does not exist.
The link
../operations/addresses.mdpoints to a non-existent path. Based on the PR restructure, the "Deployed Addresses" page is now atdocs/build/api/contracts/index.md. From this file's location (sdk/api-reference.md), the correct relative path should be../index.mdor use the doc ID directly.🔗 Proposed fix
-See [Deployed Addresses](../operations/addresses.md) for the full list. +See [Deployed Addresses](../index.md) for the full list.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/api/contracts/sdk/api-reference.md` at line 89, The Markdown link labeled "Deployed Addresses" currently points to a non-existent relative path "../operations/addresses.md"; update that link target in the sdk/api-reference.md file so it references the correct document (either change the target to "../index.md" relative to this file or replace it with the appropriate doc ID for the contracts index) so the "Deployed Addresses" link resolves correctly.
🧹 Nitpick comments (1)
scripts/sync-contracts-docs.js (1)
369-380: API category may conflict with manually committed file.The script writes
docs/build/api/_category_.jsonat runtime (lines 369-373), but there's also a manually committeddocs/build/api/_category_.jsonfile in this PR. Running the script will overwrite the manual file, though currently both have the same content. Consider either:
- Removing the manual file and relying solely on script generation, or
- Removing these lines from the script if manual control is preferred.
Having both creates a potential maintenance inconsistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/sync-contracts-docs.js` around lines 369 - 380, The script currently generates docs/build/api/_category_.json by calling writeCategory(API_CATEGORY.dir, ...) and also writes a Contracts category at DEST using writeCategory(DEST, ...), which will overwrite the manually committed docs/build/api/_category_.json in the repo; either remove the manual file from the repo and keep these writeCategory calls (recommended) or remove the two writeCategory calls (the write to API_CATEGORY.dir and the Contracts write to DEST) so the manual _category_.json remains authoritative—update whichever you choose and ensure API_CATEGORY and DEST usages are consistent with the chosen approach.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docusaurus.config.ts`:
- Line 95: Remove the orphaned client module file named hideContractsOn05x.js
from the repository since it is no longer referenced in clientModules; delete
the file from version control (git rm) and commit the removal so it no longer
appears in the codebase.
In `@src/pages/whitepaper.md`:
- Around line 302-310: In src/pages/whitepaper.md update the document link for
the table row referencing "[YELLOW MiCA White Paper v1.2 (PDF)]" so the href
points to the actual file location
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" instead of
"/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; modify the table cell containing
the document link accordingly so the rendered link uses the /static/assets path.
---
Outside diff comments:
In `@docs/build/api/contracts/sdk/_category_.json`:
- Around line 1-10: The generated category JSON is losing its "key" because the
sync script's writeCategory call in sync-contracts-docs.js does not pass the
category key; update the call that writes CATEGORIES (the writeCategory
invocation) to include cat.key (or the equivalent property) so the generated
object includes "key": "contracts-sdk" on regen, ensuring the writeCategory
function receives and writes the key field for each category.
In `@docs/build/api/contracts/sdk/api-reference.md`:
- Line 89: The Markdown link labeled "Deployed Addresses" currently points to a
non-existent relative path "../operations/addresses.md"; update that link target
in the sdk/api-reference.md file so it references the correct document (either
change the target to "../index.md" relative to this file or replace it with the
appropriate doc ID for the contracts index) so the "Deployed Addresses" link
resolves correctly.
In `@scripts/sync-contracts-docs.js`:
- Around line 383-388: The loop that writes sub-category files calls
writeCategory without forwarding the optional key, so CATEGORIES entries like
the SDK item (key 'contracts-sdk') never get written; update the loop to pass
cat.key into writeCategory (e.g., writeCategory(path.join(DEST, cat.dir), {
label: cat.label, position: cat.position }, cat.key)) so the key is persisted
into sdk/_category_.json and other sub-category files; keep using the existing
writeCategory signature and handle undefined keys as before.
---
Nitpick comments:
In `@scripts/sync-contracts-docs.js`:
- Around line 369-380: The script currently generates
docs/build/api/_category_.json by calling writeCategory(API_CATEGORY.dir, ...)
and also writes a Contracts category at DEST using writeCategory(DEST, ...),
which will overwrite the manually committed docs/build/api/_category_.json in
the repo; either remove the manual file from the repo and keep these
writeCategory calls (recommended) or remove the two writeCategory calls (the
write to API_CATEGORY.dir and the Contracts write to DEST) so the manual
_category_.json remains authoritative—update whichever you choose and ensure
API_CATEGORY and DEST usages are consistent with the chosen approach.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: adf65378-9f40-48ea-8dfb-b4f8bafeace4
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (43)
docs/build/api/_category_.jsondocs/build/api/contracts/_category_.jsondocs/build/api/contracts/api-reference/_category_.jsondocs/build/api/contracts/api-reference/app-registry.mddocs/build/api/contracts/api-reference/faucet.mddocs/build/api/contracts/api-reference/interfaces/_category_.jsondocs/build/api/contracts/api-reference/interfaces/ilock.mddocs/build/api/contracts/api-reference/interfaces/islash.mddocs/build/api/contracts/api-reference/locker.mddocs/build/api/contracts/api-reference/node-registry.mddocs/build/api/contracts/api-reference/treasury.mddocs/build/api/contracts/api-reference/yellow-governor.mddocs/build/api/contracts/api-reference/yellow-token.mddocs/build/api/contracts/faq.mddocs/build/api/contracts/index.mddocs/build/api/contracts/integration/_category_.jsondocs/build/api/contracts/integration/deployment.mddocs/build/api/contracts/integration/events.mddocs/build/api/contracts/integration/ui-spec.mddocs/build/api/contracts/protocol/_category_.jsondocs/build/api/contracts/protocol/governance.mddocs/build/api/contracts/protocol/overview.mddocs/build/api/contracts/protocol/slashing.mddocs/build/api/contracts/protocol/staking.mddocs/build/api/contracts/protocol/treasury.mddocs/build/api/contracts/sdk/_category_.jsondocs/build/api/contracts/sdk/api-reference.mddocs/build/api/contracts/sdk/examples.mddocs/build/api/contracts/sdk/getting-started.mddocs/contracts/index.mddocs/guides/index.mddocs/guides/manuals/_category_.jsondocs/guides/manuals/request-asset-support.mddocs/guides/manuals/request-blockchain-support.mddocs/guides/manuals/running-clearnode-locally.mddocs/learn/introduction/supported-chains.mdxdocs/manuals/_category_.jsondocs/manuals/index.mddocusaurus.config.tsscripts/sync-contracts-docs.jssidebars.tssrc/components/HomepageFeatures/index.tsxsrc/pages/whitepaper.md
💤 Files with no reviewable changes (4)
- sidebars.ts
- docs/contracts/index.md
- docs/manuals/index.md
- docs/manuals/category.json
src/pages/whitepaper.md
Outdated
| --- | ||
|
|
||
| ## MiCA White Paper Filing History | ||
|
|
||
| The following versions of the YELLOW crypto-asset white paper have been filed under the Markets in Crypto-Assets Regulation (EU) 2023/1114: | ||
|
|
||
| | Version | Date of Notification | Status | Document | | ||
| |---|---|---|---| | ||
| | v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if the referenced PDF file exists
# Check for the PDF file in the assets directory
if [ -f "assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" ]; then
echo "✓ PDF file exists at assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
ls -lh "assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
else
echo "✗ PDF file not found at assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"
echo "Searching for similar files..."
fd -e pdf -i mica . 2>/dev/null || echo "No similar PDF files found"
fiRepository: layer-3/docs
Length of output: 201
Update the PDF reference path to match the actual file location.
The PDF file exists at /static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf, not at the referenced path /assets/YELLOW_MiCA_White_Paper_v.1.2.pdf. Update the link on line 307 to the correct location.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/pages/whitepaper.md` around lines 302 - 310, In src/pages/whitepaper.md
update the document link for the table row referencing "[YELLOW MiCA White Paper
v1.2 (PDF)]" so the href points to the actual file location
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" instead of
"/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; modify the table cell containing
the document link accordingly so the rendered link uses the /static/assets path.
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
There was a problem hiding this comment.
@coderabbitai this seems like a false positive, this file is downloadable when I tested it with the build
There was a problem hiding this comment.
@ihsraham, you're right — this is a false positive. In Docusaurus, files placed in the static/ directory are served from the root path at build time, so a file at static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf is correctly referenced as /assets/YELLOW_MiCA_White_Paper_v.1.2.pdf. My script checked for the file without accounting for this, and incorrectly flagged the path. Apologies for the noise!
(´• ω •`) 🐰💭
✏️ Learnings added
Learnt from: ihsraham
Repo: layer-3/docs PR: 121
File: src/pages/whitepaper.md:0-0
Timestamp: 2026-03-07T13:34:05.091Z
Learning: In this Docusaurus (layer-3/docs) repository, static files placed under the `static/` directory are served from the root path at build time. For example, a file at `static/assets/foo.pdf` is correctly referenced in Markdown/MDX as `/assets/foo.pdf`, not `/static/assets/foo.pdf`. Do not flag such paths as incorrect.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
src/pages/whitepaper.md (1)
303-303:⚠️ Potential issue | 🟡 MinorFix the PDF link path to match the actual file location.
The PDF link still references
/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf, but according to previous verification, the file exists at/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf. This broken link will result in a 404 error for users attempting to access the whitepaper.🔗 Proposed fix for the PDF path
-| v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) | +| v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/pages/whitepaper.md` at line 303, Update the PDF link in the markdown table row that contains "[YELLOW MiCA White Paper v1.2 (PDF)]" so it points to the actual file location by changing the href from "/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" to "/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; ensure the table row text for version v1.2 (the line shown in src/pages/whitepaper.md) is updated accordingly so the link resolves without a 404.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@src/pages/whitepaper.md`:
- Line 303: Update the PDF link in the markdown table row that contains "[YELLOW
MiCA White Paper v1.2 (PDF)]" so it points to the actual file location by
changing the href from "/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf" to
"/static/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf"; ensure the table row text
for version v1.2 (the line shown in src/pages/whitepaper.md) is updated
accordingly so the link resolves without a 404.
alessio
left a comment
alessio
left a comment
There was a problem hiding this comment.
Minor comment to address. Other than that, looks good to me
…checker Made-with: Cursor
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/build/sdk/typescript/api-reference.mdx (1)
153-155: Use the concrete method names in the lifecycle sentence.The shorthand terms (
approve,lock,unlock,relock,withdraw) are not actualClientAPI names and reduce searchability in an API reference. Replace them with the exact method names:approveSecurityToken()→escrowSecurityTokens()→initiateSecurityTokensWithdrawal()→withdrawSecurityTokens(), withcancelSecurityTokensWithdrawal()called out as the relock step.📝 Suggested wording
-The locking lifecycle is: **approve** → **lock** → *(optionally)* **unlock** → *(wait for unlock period)* → **withdraw**. At any point during the unlock period, you can **relock** to cancel the withdrawal. +The locking lifecycle is: **approveSecurityToken** → **escrowSecurityTokens** → *(optionally)* **initiateSecurityTokensWithdrawal** → *(wait for unlock period)* → **withdrawSecurityTokens**. During the unlock period, call **cancelSecurityTokensWithdrawal** to relock and cancel the withdrawal.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/sdk/typescript/api-reference.mdx` around lines 153 - 155, Replace the shorthand lifecycle terms with the concrete Client API names: change the sentence to read the lifecycle as approveSecurityToken() → escrowSecurityTokens() → (optionally) initiateSecurityTokensWithdrawal() → (wait for unlock period) → withdrawSecurityTokens(), and mention cancelSecurityTokensWithdrawal() as the relock step that can be called during the unlock period; update any occurrences of the short names (`approve`, `lock`, `unlock`, `relock`, `withdraw`) in this paragraph to these exact method names to improve API searchability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/build/sdk/typescript-compat/overview.mdx`:
- Around line 115-127: Update the docs for getLockedBalance to state that the
optional wallet parameter defaults to the connected user's address when omitted
(in addition to chainId defaulting to the client-configured chain), and add a
brief example demonstrating calling client.getLockedBalance(undefined,
nonDefaultChainId) (or calling it with no args) to query the connected user on a
non-default chain; reference the method name getLockedBalance and the client
invocation client.getLockedBalance in the prose and example so readers can
locate and verify the behavior.
In `@scripts/check-links.mjs`:
- Around line 521-543: The current routing collapses docs, versioned_docs and
site routes by using relativeFile/stripDocsBasePath and storing routes without
the mounted /docs and version prefix; update the logic (functions and variables
around stripDocsBasePath, resolveDocsRoute, isBareInternalPath and the
routeToRecord creation) so records are keyed by absoluteFile (or a composite key
{root, relativeFile}) instead of relativeFile, and ensure index routes are
generated with the full mounted path (include docsRouteBasePath and any version
prefix like versioned_docs/version-0.5.x mapped to /docs/0.5.x) when calling
normalizeRoute/resolveDocsRoute; stop collapsing leading '/' removal for files
under versioned_docs and preserve the full sourceBaseRoute (including /docs and
version) when joining with normalizedPath.
- Around line 30-31: The regex stored in jsxAttributePattern currently matches
only href|src|url and should include to to capture Docusaurus <Link to="...">
props; update the pattern (jsxAttributePattern) to include to (e.g.
href|src|url|to) and make the same change for the duplicate/related regex
elsewhere in the file where the same attribute-matching pattern is used so all
link checks capture Link navigation props.
In `@versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx`:
- Around line 256-257: The two CTA links use "../../../manuals/..." which climbs
one level too high and omits the new "guides/" segment; update the links in
supported-chains.mdx (the lines with "**[Request Blockchain Support]..." and
"**[Request Asset Support]...") to include the guides path and the corrected
relative depth, e.g. change "../../../manuals/request-blockchain-support" to
"../../guides/manuals/request-blockchain-support" and
"../../../manuals/request-asset-support" to
"../../guides/manuals/request-asset-support".
---
Nitpick comments:
In `@docs/build/sdk/typescript/api-reference.mdx`:
- Around line 153-155: Replace the shorthand lifecycle terms with the concrete
Client API names: change the sentence to read the lifecycle as
approveSecurityToken() → escrowSecurityTokens() → (optionally)
initiateSecurityTokensWithdrawal() → (wait for unlock period) →
withdrawSecurityTokens(), and mention cancelSecurityTokensWithdrawal() as the
relock step that can be called during the unlock period; update any occurrences
of the short names (`approve`, `lock`, `unlock`, `relock`, `withdraw`) in this
paragraph to these exact method names to improve API searchability.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 19f25f23-5af8-4c60-8558-1c959e1e51e9
📒 Files selected for processing (11)
docs/build/quick-start/index.mddocs/build/sdk/typescript-compat/overview.mdxdocs/build/sdk/typescript/api-reference.mdxdocs/build/sdk/typescript/examples.mdxdocusaurus.config.tsi18n/en/docusaurus-theme-classic/footer.jsonpackage.jsonscripts/check-links.mjssrc/clientModules/hideContractsOn05x.jsversioned_docs/version-0.5.x/build/quick-start/index.mdversioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx
💤 Files with no reviewable changes (3)
- i18n/en/docusaurus-theme-classic/footer.json
- src/clientModules/hideContractsOn05x.js
- docusaurus.config.ts
✅ Files skipped from review due to trivial changes (2)
- docs/build/quick-start/index.md
- docs/build/sdk/typescript/examples.mdx
versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx
Outdated
Show resolved
Hide resolved
These docs belong with the feat/integrate-locking SDK changes, not this docs branch. Made-with: Cursor
3 participants
Summary by CodeRabbit