YNU-354: Protocol Docs #69
Conversation
- Added Protocol section in the docs - Added Intro and Architecture pages - Added On-chain section and contents
docs/protocol/off-chain/queries.mdx
Outdated
| | `application` | string | Application name for this session | `"clearnode"` | — | | ||
| | `allowances` | array\<Allowance\> | Spending limits and usage | — | See [Allowance](#allowance-structure) below | | ||
| | `scope` | string | Permission scope | — | Future feature, not fully enforced yet | | ||
| | `expire` | string (timestamp) | Session expiration time | — | — | |
There was a problem hiding this comment.
This is a bit outdated. Now expires_at is used - please check current docs/API.md
There was a problem hiding this comment.
| :::success Cryptographic Security | ||
| State validity is enforced through ECDSA signatures on the secp256k1 curve, the same cryptographic foundation as Ethereum itself. | ||
| ::: | ||
|
|
There was a problem hiding this comment.
Would be good to mention why using EIP-712 sigs is more superior than 191 in terms of security and user experience (as this is one of the minor but important features that differentiate our protocol)
There was a problem hiding this comment.
@dimast-x
I am adding this new section, is it fine?
There was a problem hiding this comment.
There was a problem hiding this comment.
Great work! Just one minor suggestion - no need to say this loudly with the green highlight about this being a differentiating feature XD Yes, it is differentiating, but its not the main feature that we need to highlight this much. Maybe try to shorten it - one small sentence should be enough
There was a problem hiding this comment.
|
@ihsraham Some change broke the sidebar UI, now the arrows are shown on both sides of the title (It must be only on the left). It was good before |
nksazonov
left a comment
nksazonov
left a comment
There was a problem hiding this comment.
Generally LGTM!
Some comments are still left to address, but nothing critical.
GREAT WORK!
src/constants/tooltipDefinitions.ts
Outdated
| assetSymbol: "A lowercase string identifier for a supported asset.", | ||
| sessionThreshold: | ||
| "Minimum total weight of signatures required to approve app session state updates.", | ||
| creatorRole: | ||
| "Most often a light client willing to fund a ledger account with a clearnode (the Broker).", | ||
| stateIntent: | ||
| "An enum defining the purpose of a state: INITIALIZE (0), OPERATE (1), RESIZE (2), FINALIZE (3).", | ||
| creatorParticipant: | ||
| "The participant at index 0 in a channel who initiates channel creation.", | ||
| appSessionId: | ||
| "A unique identifier for an app session, formatted as a 0x-prefixed hex string (32 bytes).", | ||
| packedState: | ||
| "A specific encoding of a channelId, state.intent, state.version, state.data, state.allocations, used for signing and signature verification.", |
There was a problem hiding this comment.
Let's move these definitions closer to others, that are relevant, so that they form groups. I.e., move "packedState" to right after "channel state", "appSessionId" to right after "appSession" etc.
There was a problem hiding this comment.
| appChannel: | ||
| "Off-chain channels built on top of payment channels, intended to be used by app developers to enable application-specific interactions and transactions without touching the blockchain.", |
There was a problem hiding this comment.
Maybe we should rename this to "appSession" and avoid using "channels" in the "off-chain" definition, so that the difference between on-chain state channels is bigger? @dimast-x @philanton , WDYT?
There was a problem hiding this comment.
Did not address it, we can have this as a part of an enhancement story if decide upon to be done
docs/protocol/architecture.mdx
Outdated
| 4. If a newer valid state is submitted during the challenge period, it replaces the current state | ||
| 5. After the challenge period expires, any participant calls `close()` to finalize with the latest submitted state |
There was a problem hiding this comment.
Let's clarify what happens if a newer state is submitted during challenge period
| 4. If a newer valid state is submitted during the challenge period, it replaces the current state | |
| 5. After the challenge period expires, any participant calls `close()` to finalize with the latest submitted state | |
| 4. If participants decides to cooperate again, they may produce a newer valid state, and any of them can submit it via `checkpoint()`, thus stopping the challenge period and moving the channel from DISPUTE back to ACTIVE status | |
| 5. If not, after the challenge period expires, any participant calls `close()` to finalize with the latest submitted state |
There was a problem hiding this comment.
|
|
||
| ### Usage | ||
|
|
||
| Transfer funds from the authenticated user's <Tooltip content={tooltipDefinitions.unifiedBalance}>unified balance</Tooltip> to another user's <Tooltip content={tooltipDefinitions.unifiedBalance}>unified balance</Tooltip> within the Yellow Network. This is a purely off-chain operation executed as a database transaction on <Tooltip content={tooltipDefinitions.clearnode}>the clearnode</Tooltip>, resulting in instant settlement. The transfer updates internal ledger entries using double-entry bookkeeping principles and creates a transaction record for both parties. The security guarantee comes from the underlying on-chain channels that back the <Tooltip content={tooltipDefinitions.unifiedBalance}>unified balance</Tooltip>. |
There was a problem hiding this comment.
Replace "This is a purely off-chain operation executed as a database transaction on the clearnode, resulting in instant settlement.'
with "This is a purely off-chain operation executed as a database transaction on the clearnode, resulting in instant settlement."
There was a problem hiding this comment.
Changed it to: Transfer funds from the authenticated user's unified balance to another user's unified balance within the Yellow Network. This is a purely off-chain operation, which results in instant settlement. The transfer updates internal ledger entries using double-entry bookkeeping principles and creates a transaction record for both parties. The security guarantee comes from the underlying on-chain channels that back the unified balance.
There was a problem hiding this comment.
|
|
||
| ### When to Use | ||
|
|
||
| When sending funds to another Yellow Network user. Common use cases include peer-to-peer payments, merchant payments, tipping, and rapid fund redistribution between users. |
There was a problem hiding this comment.
Remove "rapid fund redistribution between users", its a feature of app sessions, not transfers
There was a problem hiding this comment.
| - Recipient must be identified by valid <Tooltip content={tooltipDefinitions.participant}>wallet address</Tooltip> or user tag | ||
|
|
||
| :::info Recipient Requirements | ||
| The recipient does not need to have an existing balance or account on the clearnode. Transfers can be sent to any valid wallet address, and the recipient's account will be created automatically if it doesn't exist. |
There was a problem hiding this comment.
created automatically on the first login.
There was a problem hiding this comment.
| Clearnode->>Bob: tr (transfer) notification | ||
| Clearnode->>Bob: bu (balance update) notification | ||
| Note over Bob: 5. Balance Updated |
There was a problem hiding this comment.
Client A also receives tr (transfer) notification.
also move "Clearnode->>Alice: {ledger_transactions}" to be the last step, and instead of ledger_transactions, simply say that this is "response"
There was a problem hiding this comment.
|
|
||
| #### 4. Sends Notifications | ||
|
|
||
| - **Sender** receives response with transaction details |
There was a problem hiding this comment.
move "Sender receives response with transaction details" into section 5. Response
There was a problem hiding this comment.
| B[Create App Session<br/>Alice locks 100 USDC] | ||
| C[Alice's Unified Balance<br/>Total: 200 USDC<br/>Available: 100 USDC<br/>Locked: 100 USDC] | ||
There was a problem hiding this comment.
We dont have Locked acccount.
There is User's Unified Account and an App Session Account. In this example, the funds are transferred from user's Unified Account to the App Session Account
There was a problem hiding this comment.
| Locked: 100 USDC (in app session 0x98765...) | ||
| ``` | ||
|
|
||
| :::warning Locked Funds |
There was a problem hiding this comment.
Remove this warning completely as funds can be withdrawn without closing an app session
There was a problem hiding this comment.
| Alice's Unified Balance: | ||
| Total: 200 USDC | ||
| Available: 100 USDC | ||
| Locked: 100 USDC (in app session 0x98765...) |
There was a problem hiding this comment.
remove Locked terminology from here and other parts. The funds are no longer on the unified balance account, they are no locked on unified balance, they are on a separate app session account. please check it in all places where you mention that funds are locked in the unified balance
There was a problem hiding this comment.
| --- | ||
|
|
||
| ## Error Cases | ||
|
|
There was a problem hiding this comment.
Lots of these errors do not follow the real errors. Every error can be checked by copying it and searching for it in the Clearnode codebase. Please remove the errors that don't exist, and you can create a user story to address errors properly in the documentation so that we don't forget
There was a problem hiding this comment.
YNU-354: Protocol Documentation (Parts 1, 2 & 3)
Part 1 – Delivered 8 Nov 2025
Scope (Part 1)
New Protocol section rooted at
docs/protocol/, covering:introduction,terminology,architecture, and theon-chainsuite (overview,data-structures,channel-lifecycle,security).Sidebar (
protocolSidebar) now reflects this structure automatically:Introduction → Terminology → Architecture → On-Chain Protocol (Overview → Data Structures → Channel Lifecycle → Security).Navbar updated with a
Protocolbutton (left-aligned) linking todocs/protocol/introduction.Presentation Enhancements
Custom tooltip system (
@tippyjs/react,Tooltip.tsx) exposing Terminology definitions on hover across all Part 1 pages.Contextual highlight boxes (info, tip, caution, warning, success, note) used where required.
Mermaid diagrams created for architectural, lifecycle, and flow visuals.
Part 2 – Delivered 12 Nov 2025
Scope (Part 2)
Complete
off-chainprotocol documentation suite covering all RPC methods and communication patterns.Seven comprehensive modules added under
docs/protocol/off-chain/:overview– Off-chain layer architecture and WebSocket communicationmessage-format– JSON-RPC 2.0 structure, request/response patterns, error codesauthentication– Three-step session key flow (auth_request,auth_challenge,auth_verify)channel-methods– Lifecycle operations (create_channel,close_channel,resize_channel)transfers– Off-chain transfer mechanics between unified balancesapp-sessions– Virtual ledger channels (app.create,app.submit,app.close) with intent systemqueries– Ten query methods (get_config,get_assets,get_channels,get_app_sessions,get_balance,get_ledger_entries,get_ledger_transactions,get_user_tag,get_session_keys,ping)Sidebar structure expanded:
Introduction → Terminology → Architecture → On-Chain Protocol → Off-Chain Protocol (Overview → Message Format → Authentication → Channel Methods → Transfers → App Sessions → Queries).Parameter Documentation Transformation
Deeply nested structures refactored using separate sub-tables (Stripe/GitHub/AWS pattern):
AppDefinitionstructure with Quick Reference anchorsChannelandStatestructures with cross-referencesAppSessionInfowith 13 fields cleanly separatedSessionKeyInfowithAllowancesub-structureBrokerSignaturesfor atomic operationsEnhanced scannability:
Presentation Enhancements (Part 2)
Part 3 – Delivered 14 Nov 2025
Scope (Part 3)
communication-flows– End-to-end sequence diagrams showing how on-chain and off-chain layers interact for major operations (channel creation, transfers, app sessions, cooperative closure, disputes)protocol-reference– Quick reference guide with all critical protocol constants, magic numbers, state intents, participant indices, error codes, hash computations, and signature requirements in one placeglossary– A-Z terminology reference with detailed definitions for all protocol concepts (75+ terms)implementation-checklist– Comprehensive checklist for building compliant Nitrolite implementations covering identifier computation, signature handling, blockchain integration, off-chain RPC, state management, security, and testingCross-Layer Communication Flows
Protocol Reference
Implementation Support
Glossary provides standalone definitions with cross-references, useful for:
Implementation Checklist organized by concern:
Reviews
Anton's Review Integration
Statestructure to includeintentandversionfieldsstateHashcomputation to include all required fieldschallengetocheckpoint()CLIENT_IDX,SERVER_IDX,PART_NUM)Protocol Specification Approach
Final Documentation Structure
Total: 18 comprehensive documentation pages covering the complete Nitrolite protocol