feat: v1.x docs version setup with SDK documentation and protocol flows#120
feat: v1.x docs version setup with SDK documentation and protocol flows#120
Conversation
- Freeze 0.5.x docs into versioned_docs/version-0.5.x/ - Remove contracts/ and protocol/decentralized-layer/ from 0.5.x (v1-only content) - Clean contractsSidebar from frozen 0.5.x sidebar - Bump package.json to 1.x, update docusaurus.config.ts version entries - Fix i18n version label override (was stuck on 0.5.x) SDK Documentation (15 new pages under build/sdk/): - @yellow-org/sdk: getting-started, api-reference, configuration, examples - @yellow-org/sdk-compat: overview, migration-overview, migration-onchain, migration-offchain - Go SDK: getting-started, api-reference - SDK overview with architecture diagram Protocol Flows (9 new pages under learn/protocol-flows/): - Architecture (Petal Diagram), Transfer Flow, App Session Deposit - Home Channel: creation, deposit, withdrawal, withdraw-on-create - Escrow: deposit, withdrawal (with cross-chain coming-soon notes) Other: - Move Yellow Token content to learn/core-concepts/yellow-token.mdx - Remove Contracts from navbar/footer (sidebar-only in v1.x) - Add protocol-flows category and yellow-token to learnSidebar Made-with: Cursor
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughAdds extensive v1.x documentation (SDKs for TypeScript and Go, migration/compat docs), a large set of protocol and learn pages, snapshots of legacy v0.5.x docs (versioned_docs), site configuration/versioning updates, and a small client-side module plus minor UI/CSS and gitignore tweaks. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 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 |
alessio
left a comment
alessio
left a comment
There was a problem hiding this comment.
Good step forward. We can merge this.
Adds Contracts back to the navbar using a path-based link (to avoid build failures when contracts don't exist in frozen 0.5.x). A tiny client module (hideContractsOn05x.js) hides the link when the user is browsing 0.5.x docs via onRouteDidUpdate. Made-with: Cursor
Adds a warning admonition to pages carried over from 0.5.x that still contain outdated terminology, code examples, or API references. The banner reads: "This page was carried over from the v0.5.x documentation and has not yet been fully updated for v1.x." Heavy rewrites: quickstart, prerequisites, key-terms, message-envelope, managing-session-keys Moderate updates: what-yellow-solves, architecture-at-a-glance, app-sessions, session-keys, challenge-response Minor updates: supported-chains, state-channels-vs-l1-l2 Pages already correct for v1 (no banner): yellow-token, index, all protocol-flows/* Made-with: Cursor
https://yellow-docs-v1.vercel.app/docs/learn/core-concepts/message-envelope 
|
|
Press ahead @ihsraham |
Makes sense. Please press ahead. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🟠 Major comments (33)
versioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdx-1-155 (1)
1-155:⚠️ Potential issue | 🟠 MajorKeep the frozen
0.5.xtree archive-only.This adds net-new dispute documentation under
versioned_docs/version-0.5.x, which conflicts with the PR goal of freezing0.5.xas a historical snapshot. If this content is intended for v1 terminology/flows, it should live only in the1.xdocs; otherwise the archived version stops reflecting what0.5.xusers actually had.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdx` around lines 1 - 155, The new document "Challenge-Response & Disputes" (frontmatter title: "Challenge-Response & Disputes", sidebar_position: 4) was added to the frozen 0.5.x tree; remove this file from the versioned_docs/version-0.5.x archive and instead add it to the active 1.x docs (or appropriate 1.x location) so historical 0.5.x remains unchanged; ensure the relocated file keeps the same content and frontmatter, and update any internal links that previously pointed to the 0.5.x path to reference the new 1.x location.versioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdx-153-155 (1)
153-155:⚠️ Potential issue | 🟠 MajorUse version-relative doc links in versioned pages.
These three links use absolute
/docs/...paths, which can cause version navigation to break for archived documentation. Links inversion-0.5.xshould be relative to keep readers within the same version. The target files exist in the versioned tree and are reachable via relative paths.Suggested fix
-- **[Channel Lifecycle](/docs/protocol/app-layer/on-chain/channel-lifecycle.mdx)** — Full state machine -- **[Security Considerations](/docs/protocol/app-layer/on-chain/security.mdx)** — Threat model and best practices -- **[Communication Flows](/docs/protocol/communication-flows.mdx#challenge-response-closure-flow)** — Sequence diagrams +- **[Channel Lifecycle](../../protocol/app-layer/on-chain/channel-lifecycle.mdx)** — Full state machine +- **[Security Considerations](../../protocol/app-layer/on-chain/security.mdx)** — Threat model and best practices +- **[Communication Flows](../../protocol/communication-flows.mdx#challenge-response-closure-flow)** — Sequence diagrams🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdx` around lines 153 - 155, The three absolute links ("Channel Lifecycle", "Security Considerations", "Communication Flows") should use version-relative paths so they keep readers in version-0.5.x; locate those link nodes in challenge-response.mdx and replace "/docs/protocol/app-layer/on-chain/channel-lifecycle.mdx" with the relative path to the versioned file (e.g. "../app-layer/on-chain/channel-lifecycle.mdx"), "/docs/protocol/app-layer/on-chain/security.mdx" with "../app-layer/on-chain/security.mdx", and "/docs/protocol/communication-flows.mdx#challenge-response-closure-flow" with the appropriate relative path (e.g. "../communication-flows.mdx#challenge-response-closure-flow") so all three links point to the versioned docs tree.versioned_docs/version-0.5.x/manuals/request-blockchain-support.md-77-77 (1)
77-77:⚠️ Potential issue | 🟠 MajorUnify the config flag name (
disabledvsenabled).Line 77 defines
disabled, but Lines 130-133 and 146-153 switch toenabled. Copy-pasting this will produce inconsistent config.Suggested fix
blockchains: - name: polygon id: 137 - enabled: true + disabled: false - name: base id: 8453 - enabled: true + disabled: falseblockchains: - name: polygon id: 137 - enabled: true + disabled: false contract_addresses: custody: "0xPolygonCustodyAddress..." adjudicator: "0xPolygonAdjudicatorAddress..." balance_checker: "0xPolygonBalanceCheckerAddress..." - name: base id: 8453 - enabled: true + disabled: false contract_addresses: custody: "0xBaseCustodyAddress..." adjudicator: "0xBaseAdjudicatorAddress..." balance_checker: "0xBaseBalanceCheckerAddress..."Also applies to: 130-133, 146-153
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/manuals/request-blockchain-support.md` at line 77, The config uses two inconsistent flag names—`disabled` and `enabled`—which will break copy-paste; choose and use a single flag name everywhere (e.g., rename all `disabled:` entries to `enabled:` or vice versa) and update all occurrences and examples in this document so they match (search for the tokens `disabled` and `enabled` and make them uniform in the request-blockchain-support examples and schema). Ensure any default comments (like “default: false”) remain correct for the chosen polarity and update surrounding explanatory text to reflect the unified flag name.versioned_docs/version-0.5.x/protocol/glossary.mdx-410-410 (1)
410-410:⚠️ Potential issue | 🟠 MajorUse a version-local link for the Quick Start reference and fix duplicate wording in the Nitro RPC section.
Line 410 uses an absolute link
/docs/build/quick-startfrom aversion-0.5.xpage, which routes readers to the current version docs instead of frozen version-specific content.Additionally, line 230 contains redundant wording: "RPC-based RPC protocol" should be "RPC-based protocol" or "RPC protocol".
Suggested fixes
Fix 1 (Line 410):
- - **Implementation**: [Quick Start Guide](/docs/build/quick-start), [Implementation Checklist](./implementation-checklist) + - **Implementation**: [Quick Start Guide](../build/quick-start), [Implementation Checklist](./implementation-checklist)Fix 2 (Line 230):
- A lightweight, RPC-based RPC protocol with compact message format and signature-based authentication. + A lightweight RPC protocol with compact message format and signature-based authentication.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/glossary.mdx` at line 410, Update the "Implementation" link in glossary.mdx that currently uses the absolute path "/docs/build/quick-start" to a version-local link so readers stay on the frozen v0.5.x docs (replace with a versioned path or a relative path to the v0.5.x quick start, e.g., ./build/quick-start or /version-0.5.x/docs/build/quick-start), and in the Nitro RPC section replace the redundant phrase "RPC-based RPC protocol" with "RPC-based protocol" (or simply "RPC protocol") to remove duplicated wording.versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx-13-13 (1)
13-13:⚠️ Potential issue | 🟠 MajorAvoid live “latest/current” phrasing in frozen versioned docs.
This introduces drift in 0.5.x docs and can desync historical accuracy over time.
Snapshot wording fix
-This page lists all blockchains and assets currently supported on Yellow Network. +This page lists blockchains and assets in the v0.5.x documentation snapshot. -Contract addresses vary by blockchain. See the [deployment repository](https://github.com/erc7824/nitrolite/tree/main/contract/deployments) for the latest addresses. +Contract addresses below are the v0.5.x snapshot for this documentation version.Also applies to: 176-176
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx` at line 13, The sentence "This page lists all blockchains and assets currently supported on Yellow Network." uses live phrasing; replace it with a frozen snapshot phrasing such as "This page lists the blockchains and assets supported on Yellow Network at the time of the 0.5.x release." Update any other occurrences of "currently", "latest" or "current" in this document (notably the similar line later) to equivalent release- or snapshot-scoped wording so the versioned docs remain historically accurate.versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx-256-257 (1)
256-257:⚠️ Potential issue | 🟠 MajorReplace absolute links with version-local links in 0.5.x docs.
Current links can route to a different docs version and break version isolation.
Version-safe link fix
-- **[Request Blockchain Support](/docs/manuals/request-blockchain-support)** — Guide for adding new blockchain networks -- **[Request Asset Support](/docs/manuals/request-asset-support)** — Guide for adding new tokens/assets +- **[Request Blockchain Support](../../manuals/request-blockchain-support)** — Guide for adding new blockchain networks +- **[Request Asset Support](../../manuals/request-asset-support)** — Guide for adding new tokens/assets -- [Quick Start Guide](/docs/build/quick-start) — Get started building with Yellow SDK -- [Multi-Party App Sessions](/docs/guides/multi-party-app-sessions) — Create multi-party application sessions -- [API Reference](/docs/api-reference) — Complete SDK documentation +- [Quick Start Guide](../../build/quick-start) — Get started building with Yellow SDK +- [Multi-Party App Sessions](../../guides/multi-party-app-sessions) — Create multi-party application sessions +- [API Reference](../../api-reference) — Complete SDK documentationAlso applies to: 299-301
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx` around lines 256 - 257, Replace the absolute links for "Request Blockchain Support" and "Request Asset Support" with version-local relative links in supported-chains.mdx so the 0.5.x docs remain isolated; locate the two link occurrences (and the similar links around lines referenced 299-301) and change "/docs/manuals/request-blockchain-support" and "/docs/manuals/request-asset-support" to their corresponding relative paths within the versioned docs tree (use relative MDX links that point to the local manuals pages for the 0.5.x docs).versioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdx-351-351 (1)
351-351:⚠️ Potential issue | 🟠 Major
Running the Examplecommand uses the wrong script path.Line 351 drops the
app_sessions/directory and won’t match the earlier referenced file.Command fix
-npx tsx scripts/app_session_two_signers.ts +npx tsx scripts/app_sessions/app_session_two_signers.ts🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdx` at line 351, The run command shown ("npx tsx scripts/app_session_two_signers.ts") is missing the app_sessions/ directory; update the command to the correct path "npx tsx scripts/app_sessions/app_session_two_signers.ts" so it matches the earlier referenced file and will execute the intended script.versioned_docs/version-0.5.x/protocol/terminology.mdx-57-76 (1)
57-76:⚠️ Potential issue | 🟠 MajorRemove v1-only decentralized-layer terms from frozen 0.5.x docs.
This section introduces YNP/BLS-cluster concepts that are outside the 0.5.x frozen scope and can mislead readers about version capabilities.
Suggested scope fix
-## Decentralized Layer Terms - -**NodeID**: A 256-bit identity derived from on-chain randomness at registration. Each NodeID requires collateral. - -**Signing Cluster (C_sign)**: The set of *k* nodes closest to an account's key in the DHT, responsible for BLS threshold signing. - -**Replication Set (C_watch)**: A larger ring of *r* nodes that independently verify signing cluster state. Always a superset of the signing cluster. - -**Certificate**: The protocol's universal primitive for state change — a cluster-attested operation carrying a BLS threshold signature. - -**Escrow Certificate**: A certificate authorizing a withdrawal from the network to L1. - -**Dispute Certificate**: A certificate produced by the replication set to override a fraudulent withdrawal. +<!-- Moved to v1.x docs to keep version-0.5.x historically accurate and frozen -->🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/terminology.mdx` around lines 57 - 76, Remove the v1-only decentralized-layer terminology block from the frozen 0.5.x docs: delete or comment out the "Decentralized Layer (YNP)" heading and the definitions for "Signing Cluster (C_sign)", "Replication Set (C_watch)", "Certificate", "Escrow Certificate", and "Dispute Certificate" in protocol/terminology.mdx, and if needed replace with a brief 0.5.x‑scoped note that those YNP/BLS-cluster concepts are introduced in v1 and not part of 0.5.x; ensure references to "Nitro RPC" and "App Layer (VirtualApp)" remain unchanged.versioned_docs/version-0.5.x/learn/core-concepts/message-envelope.mdx-141-143 (1)
141-143:⚠️ Potential issue | 🟠 MajorDeep-dive links should be version-local and extensionless.
Absolute
/docs/...links with.mdxare brittle in versioned docs and can 404.Link fix
-- **[Message Format](/docs/protocol/app-layer/off-chain/message-format.mdx)** — Full format specification -- **[Off-Chain Overview](/docs/protocol/app-layer/off-chain/overview.mdx)** — Protocol architecture -- **[Implementation Checklist](/docs/protocol/implementation-checklist.mdx#off-chain-rpc)** — Building RPC support +- **[Message Format](../../protocol/app-layer/off-chain/message-format)** — Full format specification +- **[Off-Chain Overview](../../protocol/app-layer/off-chain/overview)** — Protocol architecture +- **[Implementation Checklist](../../protocol/implementation-checklist#off-chain-rpc)** — Building RPC support🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/core-concepts/message-envelope.mdx` around lines 141 - 143, Replace the absolute, extensionful links for the three entries ("[Message Format]", "[Off-Chain Overview]", "[Implementation Checklist]") with version-local, extensionless links so they don't 404 in versioned builds: remove the leading /docs/ and the .mdx extension and keep the fragment anchor (`#off-chain-rpc`) on the Implementation Checklist entry so the link becomes a relative/version-local path without the .mdx suffix.versioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdx-588-591 (1)
588-591:⚠️ Potential issue | 🟠 MajorKeep “Further Reading” links inside the 0.5.x docs version.
Absolute
/docs/...links can send readers to current docs instead of the frozen version.Version-safe link fix
-- [App Sessions Core Concepts](/docs/learn/core-concepts/app-sessions) — Understanding app sessions -- [App Session Methods](/docs/protocol/app-layer/off-chain/app-sessions) — Complete API reference -- [Client-Side App Session Signing Guide](/docs/guides/client-side-app-session-signing) — Signing implementation details -- [Session Keys](/docs/learn/core-concepts/session-keys) — Managing session keys +- [App Sessions Core Concepts](../learn/core-concepts/app-sessions) — Understanding app sessions +- [App Session Methods](../protocol/app-layer/off-chain/app-sessions) — Complete API reference +- [Client-Side App Session Signing Guide](./client-side-app-session-signing) — Signing implementation details +- [Session Keys](../learn/core-concepts/session-keys) — Managing session keys🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdx` around lines 588 - 591, The four absolute links (targets like "/docs/learn/core-concepts/app-sessions", "/docs/protocol/app-layer/off-chain/app-sessions", "/docs/guides/client-side-app-session-signing", "/docs/learn/core-concepts/session-keys") should be made version-safe so they stay in the 0.5.x docs; update each link target to point to the frozen 0.5.x path (e.g. replace the leading "/docs/..." with the 0.5.x versioned path equivalent) so the "Further Reading" links inside the multi-party-app-sessions.mdx file resolve to the versioned docs rather than the current docs.versioned_docs/version-0.5.x/learn/getting-started/key-terms.mdx-335-339 (1)
335-339:⚠️ Potential issue | 🟠 MajorUse version-safe internal links (avoid absolute
/docs/...+.mdx).These links can route readers out of 0.5.x and may break due to
.mdxsuffixes.Link fix
-- **[State Channels vs L1/L2](../core-concepts/state-channels-vs-l1-l2.mdx)** — Deep comparison with other scaling solutions -- **[App Sessions](../core-concepts/app-sessions.mdx)** — Multi-party application patterns -- **[Session Keys](../core-concepts/session-keys.mdx)** — Authentication and security +- **[State Channels vs L1/L2](../core-concepts/state-channels-vs-l1-l2)** — Deep comparison with other scaling solutions +- **[App Sessions](../core-concepts/app-sessions)** — Multi-party application patterns +- **[Session Keys](../core-concepts/session-keys)** — Authentication and security -For complete definitions, see the **[Glossary](/docs/protocol/glossary.mdx)**. +For complete definitions, see the **[Glossary](../../protocol/glossary)**.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/getting-started/key-terms.mdx` around lines 335 - 339, Replace the absolute, .mdx-suffixed glossary link with a version-safe relative link: change the "**[Glossary](/docs/protocol/glossary.mdx)**" entry to a relative/internal link without the .mdx suffix (for example "**[Glossary](../protocol/glossary)**") so it stays within the 0.5.x tree and avoids routing out of the version; keep other "../core-concepts/..." links as-is.docs/learn/protocol-flows/escrow-withdrawal.mdx-67-72 (1)
67-72:⚠️ Potential issue | 🟠 MajorUse one execution-transition name throughout.
The transition table defines
escrow_withdraw, but Phase 6 switches toescrow_withdrawalT. For protocol docs, that identifier needs to stay canonical or implementers won’t know which transition name is actually valid.Also applies to: 289-297
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/learn/protocol-flows/escrow-withdrawal.mdx` around lines 67 - 72, The doc uses two different transition identifiers—`escrow_withdraw` in the Transition Types table and `escrow_withdrawalT` in Phase 6—so pick the canonical name (preferably `escrow_withdraw`) and make it consistent across the file (including the Transition Types table and Phase 6 text); update any occurrence of `escrow_withdrawalT` to the chosen canonical symbol (or vice versa if you prefer) and ensure any explanatory text references the exact same transition identifier.versioned_docs/version-0.5.x/learn/getting-started/prerequisites.mdx-328-350 (1)
328-350:⚠️ Potential issue | 🟠 MajorDon’t make the frozen 0.5.x guide depend on live
get_config.This archived page tells
/0.5.xreaders to fetch supported chains and contract addresses from a real-time clearnode response. As the server config changes, this page will silently drift away from the version it is supposed to preserve. Snapshot the 0.5.x values here, or move the dynamic discovery guidance to the 1.x docs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/getting-started/prerequisites.mdx` around lines 328 - 350, This archived 0.5.x doc should not depend on live get_config responses; replace the dynamic WebSocket example (ws, ws.onopen, ws.onmessage and the use of response.res[2].chains / response.res[2].contracts) with a static snapshot of the supported chains and contract addresses valid for 0.5.x (or remove the live example and add a note pointing readers to the 1.x docs for dynamic discovery); update the text to show the snapshot values inline and delete or move the WebSocket get_config example to the 1.x docs to avoid breaking the frozen doc state.docs/learn/protocol-flows/home-channel-creation.mdx-68-75 (1)
68-75:⚠️ Potential issue | 🟠 MajorUse the same channel-definition field name throughout.
The channel-definition table introduces
challengeDuration, but the creation step later switches tochallenge. For protocol docs this needs to be exact, otherwise readers will build the wrong payload shape.Also applies to: 145-151
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/learn/protocol-flows/home-channel-creation.mdx` around lines 68 - 75, The docs use two different field names for the same channel-definition property—`challengeDuration` in the channel-definition table and `challenge` later in the channel creation example—causing inconsistent payload shapes; pick one canonical name (prefer `challengeDuration` to match the table) and update every occurrence in the creation step and the later example (the block currently showing `challenge`) to use `challengeDuration` so the table and examples are identical.docusaurus.config.ts-70-79 (1)
70-79:⚠️ Potential issue | 🟠 MajorMake the footer docs links version-aware.
With
0.5.xnow mounted at/docs/0.5.x, the hardcoded footer routes below still point at/docs/..., so archived readers will jump back into 1.x when they use the footer. Please switch those items to doc links or prepend the active version path.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docusaurus.config.ts` around lines 70 - 79, The footer currently contains hardcoded "/docs/..." links that break for the mounted '0.5.x' version; update the themeConfig.footer.links entries so they are version-aware by either converting them to Docusaurus doc links (use type: 'doc' with the correct docId) or prefixing the href with the active version path at runtime; locate the versions block (current and '0.5.x') and the footer definition (themeConfig.footer.links) and change each footer docs link to use doc link entries or construct the URL using the active version path rather than hardcoding "/docs/...".versioned_docs/version-0.5.x/protocol/architecture.mdx-13-15 (1)
13-15:⚠️ Potential issue | 🟠 MajorThis archived 0.5.x page still includes v1-only architecture.
The page opens with the Decentralized Layer/App Layer split and then points readers to the “v1.x” release. That conflicts with the goal of freezing 0.5.x after stripping decentralized-layer material, so the archived architecture is no longer historically accurate.
Also applies to: 54-59
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/architecture.mdx` around lines 13 - 15, The archived v0.5.x page still presents a v1-only two-layer architecture; update the intro and any references to "Decentralized Layer" and "App Layer (VirtualApp)" (including the "Two-Layer Architecture" heading and the opening paragraph that mentions both layers) to reflect the frozen v0.5.x scope by either removing the decentralized-layer content and rephrasing the intro to describe only the App Layer/state-channel behavior, or clearly mark the two-layer description as part of v1.x (archival note) so readers aren’t misled; ensure every mention of "Decentralized Layer", "App Layer (VirtualApp)" and the "Two-Layer Architecture" section is edited consistently.versioned_docs/version-0.5.x/build/quick-start/index.md-69-129 (1)
69-129:⚠️ Potential issue | 🟠 MajorClarify the target runtime or provide browser setup instructions.
The tutorial lists "Node.js 16+" as a prerequisite and instructs readers to create
app.jsusing npm, but the JavaScript code blocks use browser-only globals (WebSocketwithout import,window.ethereum). The code will fail in Node.js without additional setup (importing thewspackage, polyfillingwindow). Either narrow the scope to browser-only or add explicit Node.js setup guidance with appropriate imports.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/build/quick-start/index.md` around lines 69 - 129, The doc mixes browser-only APIs with a Node.js prerequisite: update the Quick Start so the runtime is explicit and the examples match it; either mark Step 2/Step 3 as "Browser only" and state that app.js expects a browser (references: WebSocket global, window.ethereum, setupMessageSigner, personal_sign), or add a Node.js variant showing required setup (importing a WebSocket client package and polyfilling or mocking window.ethereum and personal_sign) and adjust the example text to reference which file/example is for browser vs Node; ensure the code block captions and surrounding text clearly state which runtime each snippet targets.versioned_docs/version-0.5.x/tutorials/index.md-9-13 (1)
9-13:⚠️ Potential issue | 🟠 MajorRemove the “coming soon” placeholder from the frozen 0.5.x docs.
This version is supposed to be archived, so this page now promises future content that will never land for 0.5.x. Either drop the Tutorials section from the 0.5.x snapshot or rewrite this as an archive note instead of a WIP page.
Proposed wording
-:::info Work in Progress -This section is currently under development. Step-by-step tutorials and comprehensive guides will be available soon. -::: - -Coming soon: Interactive tutorials covering various development scenarios and use cases. +:::info Archived version +No step-by-step tutorials were published for version 0.5.x. +For actively maintained tutorials and guides, use the current 1.x documentation. +:::🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/tutorials/index.md` around lines 9 - 13, Remove the "Work in Progress" admonition and the "Coming soon" placeholder from the frozen 0.5.x tutorials page and replace them with an archival note that this section is intentionally frozen and will not receive new tutorials; specifically update the ":::info Work in Progress" block and the "Coming soon: Interactive tutorials..." line in versioned_docs/version-0.5.x/tutorials/index.md to either delete the Tutorials section entirely or change the content to a clear archive message (e.g., "This section is archived for v0.5.x and no further content will be added.") so the snapshot no longer promises future content.versioned_docs/version-0.5.x/protocol/app-layer/on-chain/channel-lifecycle.mdx-413-414 (1)
413-414:⚠️ Potential issue | 🟠 MajorFix malformed table row in transition summary.
Line 413 concatenates two rows (
VOID→INITIALandVOID→ACTIVE) into one malformed row, which can render incorrectly.Suggested fix
-| VOID | INITIAL | `create()` | Creator signature, sufficient balance, INITIALIZE intent || VOID | ACTIVE | `create()` with all sigs | All participants' signatures, sufficient balances | +| VOID | INITIAL | `create()` | Creator signature, sufficient balance, INITIALIZE intent | +| VOID | ACTIVE | `create()` with all sigs | All participants' signatures, sufficient balances |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/on-chain/channel-lifecycle.mdx` around lines 413 - 414, The table row combining the VOID→INITIAL and VOID→ACTIVE transitions is malformed; split the concatenated row into two separate rows so one row reads "VOID | INITIAL | `create()` | Creator signature, sufficient balance, INITIALIZE intent" and the next reads "VOID | ACTIVE | `create()` with all sigs | All participants' signatures, sufficient balances", ensuring the existing "INITIAL | ACTIVE | `join()` | All participants joined and funded" row remains unchanged; locate the transition summary table entries referencing VOID, INITIAL, ACTIVE and the `create()`/`join()` cells and separate them into distinct table lines.versioned_docs/version-0.5.x/protocol/protocol-reference.mdx-305-311 (1)
305-311:⚠️ Potential issue | 🟠 MajorAlign the ERC-20 requirement statement with native-token handling docs.
Line 310 says all assets must be ERC-20, but the on-chain data-structures page (Line 72) also documents zero-address native currency usage. This should be reconciled to avoid contradictory guidance.
Suggested fix
-**Usage**: All assets must be ERC-20 compliant tokens. The <Tooltip content={tooltipDefinitions.custodyContract}>Custody Contract</Tooltip> uses `transferFrom` and `transfer` methods. +**Usage**: Assets are typically ERC-20 tokens; some deployments may also support native currency via the zero address. The <Tooltip content={tooltipDefinitions.custodyContract}>Custody Contract</Tooltip> uses token transfer methods where applicable.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/protocol-reference.mdx` around lines 305 - 311, The ERC-20 statement is too absolute and conflicts with the on-chain data-structures doc that permits the zero-address native currency; update the "EIP-20 (ERC-20): Token Standard" section to state that assets SHOULD be ERC-20 tokens but the protocol also supports native currency represented by the zero-address, and clarify that the <Tooltip content={tooltipDefinitions.custodyContract}>Custody Contract</Tooltip> will use `transferFrom`/`transfer` for ERC-20 tokens while native currency transfers are handled via the zero-address mechanism described on the on-chain data-structures page.versioned_docs/version-0.5.x/learn/core-concepts/session-keys.mdx-175-177 (1)
175-177:⚠️ Potential issue | 🟠 MajorUse version-safe relative links in 0.5.x docs instead of hard-coded
/docs/...paths.Lines 176-177 can route users to the current docs version instead of frozen 0.5.x content.
Suggested fix
-- **[Managing Session Keys](../advanced/managing-session-keys.mdx)** — Create, list, and revoke session keys with full API examples -- **[Authentication Flow](/docs/protocol/app-layer/off-chain/authentication.mdx)** — Full 3-step authentication protocol -- **[Communication Flows](/docs/protocol/communication-flows.mdx#authentication-flow)** — Sequence diagrams for auth +- **[Managing Session Keys](../advanced/managing-session-keys)** — Create, list, and revoke session keys with full API examples +- **[Authentication Flow](../../protocol/app-layer/off-chain/authentication)** — Full 3-step authentication protocol +- **[Communication Flows](../../protocol/communication-flows#authentication-flow)** — Sequence diagrams for auth🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/learn/core-concepts/session-keys.mdx` around lines 175 - 177, Replace the hard-coded absolute docs links in the list entries for "Authentication Flow" and "Communication Flows" with version-safe relative links used across the 0.5.x docs; specifically update the link targets for the link texts "Authentication Flow" and "Communication Flows" in session-keys.mdx to point to the relative paths within the versioned docs (matching the pattern used by the other entries like "../advanced/managing-session-keys.mdx") so users are routed to the current 0.5.x pages instead of the frozen /docs/ paths.docs/build/sdk/typescript/getting-started.mdx-84-96 (1)
84-96:⚠️ Potential issue | 🟠 MajorAdd
withHandshakeTimeoutto the import statement on line 84.The code snippet uses
withHandshakeTimeout(10000)on line 95, but it is not imported on line 84. The example will fail when copied as-is.Fix
-import { Client, createSigners, withBlockchainRPC } from '@yellow-org/sdk'; +import { Client, createSigners, withBlockchainRPC, withHandshakeTimeout } from '@yellow-org/sdk';🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/sdk/typescript/getting-started.mdx` around lines 84 - 96, The example fails because withHandshakeTimeout is used but not imported; update the import statement that currently imports Client, createSigners, withBlockchainRPC from '@yellow-org/sdk' to also include withHandshakeTimeout so the snippet can call withHandshakeTimeout(10000) successfully (ensure the updated import includes withHandshakeTimeout alongside Client, createSigners, withBlockchainRPC).versioned_docs/version-0.5.x/protocol/communication-flows.mdx-247-250 (1)
247-250:⚠️ Potential issue | 🟠 MajorPack the same field name you return.
This section creates the initial state with
state_data: "0x"and then immediately tells clients to hashdata. That inconsistency changes the signed payload and will break signature verification for anyone copying the example.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/communication-flows.mdx` around lines 247 - 250, The docs create the initial State with the field named state_data but then show packing/hashing of `data`, causing a mismatch in the signed payload; update the example so the same field name is used in both places (either change the State field from `state_data: "0x"` to `data: "0x"` or change the packing step to hash `state_data`), ensuring `channelId`, `intent`, `version`, the chosen data field, and `allocations` are consistently referenced when describing the packed state and signature with the participant key.docs/build/sdk/typescript/examples.mdx-223-229 (1)
223-229:⚠️ Potential issue | 🟠 MajorDon't hardcode mainnet
chainIdin the wallet signer.
connectWithWallet()creates the SDK client for Sepolia, butWalletTransactionSigner.sign()always signs typed data withchainId: 1. Those signatures won't verify on Sepolia, so this example breaks as soon as it's copied to a non-mainnet network.Also applies to: 247-252
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/sdk/typescript/examples.mdx` around lines 223 - 229, The example hardcodes chainId: 1 inside WalletTransactionSigner.sign which causes signatures to be invalid on Sepolia; update sign to use the actual network chain id (e.g., read from the SDK/client or the wallet connector like this.wc.chainId or pass a chainId from connectWithWallet) instead of the literal 1, and apply the same fix to the similar block at lines 247-252 so typed-data signing uses the runtime chainId rather than mainnet.versioned_docs/version-0.5.x/protocol/app-layer/off-chain/overview.mdx-31-34 (1)
31-34:⚠️ Potential issue | 🟠 MajorRemove the
amountparameter from thecreate_channeloverview example.This example advertises
create_channelwith anamount, but the dedicated method doc in this PR says channels are created with zero balance and funded later viaresize_channel. Leaving the old parameter here makes the overview document a different API than the one readers should actually call.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/overview.mdx` around lines 31 - 34, The overview example for the Compact format shows a create_channel call including an "amount" param, but channels are created with zero balance and funded later via resize_channel; update the example by removing the "amount" field from the create_channel params so the example becomes [requestId, "create_channel", {"chain_id": 137, "token": "0x..."}, timestamp] to match the create_channel and resize_channel semantics.docs/learn/protocol-flows/app-session-deposit.mdx-224-233 (1)
224-233:⚠️ Potential issue | 🟠 MajorThe completion step promises a transaction hash for an off-chain flow.
Everything in Phases 1-5 is described as off-chain validation and persistence, but this section returns “success and tx hash”. That implies an on-chain submission that never happens in the preceding steps and will confuse SDK users about when a blockchain transaction exists.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/learn/protocol-flows/app-session-deposit.mdx` around lines 224 - 233, The docs incorrectly promise a transaction hash in the completion step for an entirely off-chain flow; update the "What Gets Returned" and the sequence (references: "AppSessionUpdate", "Node signature", "Success and tx hash") to either remove "tx hash" or explicitly state that a tx hash is only returned if an on-chain submission occurs and add a new step describing that on-chain submission when applicable; ensure the text and sequence diagram consistently reflect that Phases 1–5 are off-chain and only include a tx hash when an explicit on-chain broadcast step is performed.versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx-154-156 (1)
154-156:⚠️ Potential issue | 🟠 MajorUse one
Statefield name in the signing instructions.The response tables define
state_data, but these packing examples switch tostate.data. If an integrator follows the latter, they'll hash a different payload than the one returned by the RPC response and signature verification will fail.Also applies to: 193-198, 415-423
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx` around lines 154 - 156, The signing instructions use inconsistent field names: the response tables use state_data but the packing examples use state.data (e.g., in the `packedState`/`abi.encode(channelId, state.intent, state.version, state.data, state.allocations)` lines), which will produce a different hash; update all packing examples (instances around `packedState` at the shown locations and the ones at 193-198, 415-423) to use the exact response field name `state_data` (or change the response tables to match if intended) so that `abi.encode` consistently references `state_data` together with `channelId`, `state.intent`, `state.version`, and `state.allocations` for signature verification.docs/build/sdk/typescript/examples.mdx-276-283 (1)
276-283:⚠️ Potential issue | 🟠 MajorRetry approval only for explicit allowance failures.
This branch also matches generic
"insufficient"errors, so the sample will callapproveToken()after unrelated failures like insufficient balance or gas. That makes the recovery path misleading and can hide the real problem.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/build/sdk/typescript/examples.mdx` around lines 276 - 283, The error handling around client.checkpoint is too broad because it retries approval on any error containing "insufficient"; narrow the retry condition to only detect allowance-related failures (e.g., check for "allowance" or the exact phrase "insufficient allowance" / an allowance-specific error code) before calling client.approveToken(chainId, asset, MAX_APPROVE) and re-invoking client.checkpoint(asset); update the conditional that inspects error?.message (variable msg) to match only explicit allowance-related messages or codes to avoid retrying on unrelated failures like low balance or gas.versioned_docs/version-0.5.x/protocol/communication-flows.mdx-164-170 (1)
164-170:⚠️ Potential issue | 🟠 MajorThe authentication summary points the wallet signature at the wrong method.
This says the main wallet signs once during
auth_request, but the flow above correctly shows the main-wallet EIP-712 signature being sent withauth_verify. That mismatch will send readers to the wrong step when implementing login.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/communication-flows.mdx` around lines 164 - 170, The "Session Security" bullet incorrectly states the main wallet signs once during auth_request; update the text to match the flow where the main-wallet EIP-712 signature is produced in auth_verify. Specifically, edit the bullet that currently reads "Main wallet only signs once (`auth_request`)" to reference `auth_verify` (or reword to "Main wallet only signs once (during auth_verify)") so it aligns with the auth_request/auth_verify flow and the rest of the diagram that uses the session key.versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx-76-78 (1)
76-78:⚠️ Potential issue | 🟠 MajorStandardize the documented challenge-period default.
Line 77 says new channels default to
3600seconds, but the example on Lines 107-108 uses86400, and the cooperative-vs-challenge table later describes the waiting period as24+ hours. Readers won't know which timeout to expect or validate against.Also applies to: 97-108, 333-338
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx` around lines 76 - 78, The doc has inconsistent default challenge-period values: update the "Initial Channel State" section and every occurrence (including the example using resize_channel and the cooperative-vs-challenge table) to use a single canonical default (choose either 3600 or 86400) and make the text explicit (e.g., "challenge period defaults to X seconds (Y hours)"). Ensure you change the example at lines ~107-108 and the cooperative-vs-challenge table entries so all references to the default timeout match the chosen value.versioned_docs/version-0.5.x/protocol/app-layer/off-chain/authentication.mdx-153-156 (1)
153-156:⚠️ Potential issue | 🟠 MajorThe challenge is described as session-key-signed, but
auth_verifyrequires the main wallet.These sections say the client signs the challenge with the session key to prove ownership, but the
auth_verifysection later requires an EIP-712 signature from the main wallet. An integrator following this flow will send the wrong signature type and fail authentication.Also applies to: 199-223
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/authentication.mdx` around lines 153 - 156, The docs currently state that `challenge_message` is signed by the session key but `auth_verify` expects an EIP-712 signature from the main wallet; update the documentation so the two steps match: either (A) change the `challenge_message` description and example to state that the challenge must be signed with the main wallet using EIP-712 (referencing `auth_verify` and EIP-712 signature format) or (B) change the `auth_verify` section to accept and verify session-key signatures (and document the verification algorithm and signature format). Ensure you update all related mentions (including the other affected block around the later section) so `challenge_message`, `auth_create`/`auth_verify` descriptions, and examples consistently specify the signer (session key vs main wallet) and the signature scheme (EIP-712 or raw session-key signature).versioned_docs/version-0.5.x/protocol/app-layer/off-chain/overview.mdx-234-242 (1)
234-242:⚠️ Potential issue | 🟠 MajorAvoid absolute
/docs/...links from frozen 0.5.x pages.This hard-link jumps out of the versioned docs tree and can land
0.5.xreaders on current terminology/content. Use a version-relative link so the frozen docs stay self-consistent.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/overview.mdx` around lines 234 - 242, The link "[Terminology](/docs/protocol/terminology)" is an absolute /docs/... URL that escapes the frozen 0.5.x docs; update it to a version-relative link that points to the 0.5.x terminology page instead (replace the absolute path with the relative path from this file to the frozen terminology page, e.g. "../../terminology" or the equivalent version-relative URL used in other 0.5.x pages) so the overview.mdx stays self-consistent.versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx-591-594 (1)
591-594:⚠️ Potential issue | 🟠 MajorKeep the 0.5.x docs version-local.
This absolute
/docs/...link sends readers out of the frozen0.5.xdocs set and into the current docs tree. That mixes versions and defeats the version freeze this PR is setting up.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@versioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdx` around lines 591 - 594, The absolute link "/docs/protocol/app-layer/on-chain/overview" breaks the frozen 0.5.x docs by pointing to the current docs tree; update the list entry so it uses a version-local relative link (e.g., change the target to "../on-chain/overview" or another relative path that points to the on-chain overview within the same versioned tree) so the reference stays inside the 0.5.x docs; update the text where the absolute link appears (the list item referencing On-Chain Protocol) to use the relative path.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6e2d7c74-c116-498d-b803-5905c2978211
⛔ Files ignored due to path filters (2)
package-lock.jsonis excluded by!**/package-lock.jsonstatic/img/protocol-petal-diagram.pngis excluded by!**/*.png
📒 Files selected for processing (89)
docs/build/sdk/_category_.jsondocs/build/sdk/go/_category_.jsondocs/build/sdk/go/api-reference.mdxdocs/build/sdk/go/getting-started.mdxdocs/build/sdk/index.mddocs/build/sdk/typescript-compat/_category_.jsondocs/build/sdk/typescript-compat/migration-offchain.mdxdocs/build/sdk/typescript-compat/migration-onchain.mdxdocs/build/sdk/typescript-compat/migration-overview.mdxdocs/build/sdk/typescript-compat/overview.mdxdocs/build/sdk/typescript/_category_.jsondocs/build/sdk/typescript/api-reference.mdxdocs/build/sdk/typescript/configuration.mdxdocs/build/sdk/typescript/examples.mdxdocs/build/sdk/typescript/getting-started.mdxdocs/learn/core-concepts/yellow-token.mdxdocs/learn/index.mdxdocs/learn/protocol-flows/_category_.jsondocs/learn/protocol-flows/app-session-deposit.mdxdocs/learn/protocol-flows/architecture.mdxdocs/learn/protocol-flows/escrow-deposit.mdxdocs/learn/protocol-flows/escrow-withdrawal.mdxdocs/learn/protocol-flows/home-channel-creation.mdxdocs/learn/protocol-flows/home-channel-deposit.mdxdocs/learn/protocol-flows/home-channel-withdraw-on-create.mdxdocs/learn/protocol-flows/home-channel-withdrawal.mdxdocs/learn/protocol-flows/transfer-flow.mdxdocusaurus.config.tsi18n/en/docusaurus-plugin-content-docs/current.jsonpackage.jsonsidebars.tsversioned_docs/version-0.5.x/api-reference/_category_.jsonversioned_docs/version-0.5.x/api-reference/app-sessions.mdversioned_docs/version-0.5.x/api-reference/index.mdversioned_docs/version-0.5.x/build/_category_.jsonversioned_docs/version-0.5.x/build/quick-start/index.mdversioned_docs/version-0.5.x/guides/index.mdversioned_docs/version-0.5.x/guides/migration-guide.mdversioned_docs/version-0.5.x/guides/multi-party-app-sessions.mdxversioned_docs/version-0.5.x/learn/_category_.jsonversioned_docs/version-0.5.x/learn/advanced/_category_.jsonversioned_docs/version-0.5.x/learn/advanced/managing-session-keys.mdxversioned_docs/version-0.5.x/learn/core-concepts/_category_.jsonversioned_docs/version-0.5.x/learn/core-concepts/app-sessions.mdxversioned_docs/version-0.5.x/learn/core-concepts/challenge-response.mdxversioned_docs/version-0.5.x/learn/core-concepts/message-envelope.mdxversioned_docs/version-0.5.x/learn/core-concepts/session-keys.mdxversioned_docs/version-0.5.x/learn/core-concepts/state-channels-vs-l1-l2.mdxversioned_docs/version-0.5.x/learn/getting-started/_category_.jsonversioned_docs/version-0.5.x/learn/getting-started/key-terms.mdxversioned_docs/version-0.5.x/learn/getting-started/prerequisites.mdxversioned_docs/version-0.5.x/learn/getting-started/quickstart.mdxversioned_docs/version-0.5.x/learn/index.mdxversioned_docs/version-0.5.x/learn/introduction/_category_.jsonversioned_docs/version-0.5.x/learn/introduction/architecture-at-a-glance.mdxversioned_docs/version-0.5.x/learn/introduction/supported-chains.mdxversioned_docs/version-0.5.x/learn/introduction/what-yellow-solves.mdxversioned_docs/version-0.5.x/manuals/_category_.jsonversioned_docs/version-0.5.x/manuals/index.mdversioned_docs/version-0.5.x/manuals/request-asset-support.mdversioned_docs/version-0.5.x/manuals/request-blockchain-support.mdversioned_docs/version-0.5.x/manuals/running-clearnode-locally.mdversioned_docs/version-0.5.x/protocol/_category_.jsonversioned_docs/version-0.5.x/protocol/app-layer/_category_.jsonversioned_docs/version-0.5.x/protocol/app-layer/off-chain/_category_.jsonversioned_docs/version-0.5.x/protocol/app-layer/off-chain/app-sessions.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/authentication.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/channel-methods.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/message-format.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/overview.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/queries.mdxversioned_docs/version-0.5.x/protocol/app-layer/off-chain/transfers.mdxversioned_docs/version-0.5.x/protocol/app-layer/on-chain/_category_.jsonversioned_docs/version-0.5.x/protocol/app-layer/on-chain/channel-lifecycle.mdxversioned_docs/version-0.5.x/protocol/app-layer/on-chain/data-structures.mdxversioned_docs/version-0.5.x/protocol/app-layer/on-chain/overview.mdxversioned_docs/version-0.5.x/protocol/app-layer/on-chain/security.mdxversioned_docs/version-0.5.x/protocol/app-layer/on-chain/signature-formats.mdxversioned_docs/version-0.5.x/protocol/architecture.mdxversioned_docs/version-0.5.x/protocol/communication-flows.mdxversioned_docs/version-0.5.x/protocol/glossary.mdxversioned_docs/version-0.5.x/protocol/implementation-checklist.mdxversioned_docs/version-0.5.x/protocol/introduction.mdxversioned_docs/version-0.5.x/protocol/protocol-reference.mdxversioned_docs/version-0.5.x/protocol/terminology.mdxversioned_docs/version-0.5.x/tutorials/_category_.jsonversioned_docs/version-0.5.x/tutorials/index.mdversioned_sidebars/version-0.5.x-sidebars.jsonversions.json
- Fix running-clearnode-locally.md clone instructions in both v1.x and 0.5.x: use layer-3/nitrolite repo with cd nitrolite/clearnode - Add bottom margin to version badge (.theme-doc-version-badge) Made-with: Cursor
3 participants
Summary
Sets up the v1.x documentation version alongside the frozen 0.5.x version, adds comprehensive SDK documentation, and integrates v1 protocol flow documentation from Notion.
What's done
Version infrastructure:
versioned_docs/version-0.5.x/with version dropdowncontractsSidebarfrom 0.5.x versionSDK documentation (15 new pages under Build > SDK):
@yellow-org/sdk(TypeScript): getting-started, api-reference, configuration, examples@yellow-org/sdk-compat(TypeScript compat): overview, migration-overview, migration-onchain, migration-offchain.d.tstypes and real example apps (example-app, cosign-demo)Protocol flows (9 new pages under Learn > Protocol Flows):
Other:
learnSidebarwith Protocol Flows category and Yellow TokenWhat still needs updating (from 0.5.x, tracked separately)
The following Learn section pages were copied from 0.5.x and still contain stale v0.5.x terminology, API surfaces, and code examples that need updating to v1:
Heavy rewrites needed:
learn/getting-started/quickstart.mdx— uses@erc7824/nitrolite,VirtualAppClient, old create-sign-send-parse patternlearn/getting-started/prerequisites.mdx— old package names, oldget_configformatlearn/getting-started/key-terms.mdx— "VirtualApp 0.5.0", old state/channel structures, Custody/Adjudicatorlearn/core-concepts/message-envelope.mdx— flat RPC method names instead of v1 namespaced (channels.v1.*)learn/advanced/managing-session-keys.mdx— old auth flow, old method namesModerate updates needed:
learn/introduction/what-yellow-solves.mdx— "VirtualApp" naming, old fund flow (Deposit→Resize→Withdraw)learn/introduction/architecture-at-a-glance.mdx— old channel lifecycle, Custody/Adjudicatorlearn/core-concepts/app-sessions.mdx—NitroRPC/0.4protocol version, old method nameslearn/core-concepts/session-keys.mdx— old method names, old deprecation noteslearn/core-concepts/challenge-response.mdx— Custody/Adjudicator → ChannelHubMinor updates needed:
learn/introduction/supported-chains.mdx—yellow-tsimport, old client constructorlearn/core-concepts/state-channels-vs-l1-l2.mdx— verify internal linksKey v0.5.x → v1 changes these pages need
@layer-3/nitrolite@yellow-org/sdkget_channelschannels.v1.get_channelsClient.create()+ direct methodsTest plan
npm run buildsucceeds with only pre-existing broken anchorsSummary by CodeRabbit
Documentation
Chores