From 62c63a53401e41bafa1ea350db8d6f3361d4a428 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 7 May 2026 22:27:20 +0530 Subject: [PATCH 1/2] YNU-864: API Reference rebuild from api.yaml --- .../api-reference/app-sessions-v1.md | 167 +++++++++++ docs/nitrolite/api-reference/app-sessions.md | 154 ---------- docs/nitrolite/api-reference/apps-v1.md | 54 ++++ docs/nitrolite/api-reference/channels-v1.md | 175 ++++++++++++ docs/nitrolite/api-reference/errors.md | 37 +++ docs/nitrolite/api-reference/index.md | 270 ++---------------- docs/nitrolite/api-reference/node-v1.md | 62 ++++ .../api-reference/session-keys-v1.md | 19 ++ docs/nitrolite/api-reference/types.md | 260 +++++++++++++++++ docs/nitrolite/api-reference/user-v1.md | 76 +++++ 10 files changed, 873 insertions(+), 401 deletions(-) create mode 100644 docs/nitrolite/api-reference/app-sessions-v1.md delete mode 100644 docs/nitrolite/api-reference/app-sessions.md create mode 100644 docs/nitrolite/api-reference/apps-v1.md create mode 100644 docs/nitrolite/api-reference/channels-v1.md create mode 100644 docs/nitrolite/api-reference/errors.md create mode 100644 docs/nitrolite/api-reference/node-v1.md create mode 100644 docs/nitrolite/api-reference/session-keys-v1.md create mode 100644 docs/nitrolite/api-reference/types.md create mode 100644 docs/nitrolite/api-reference/user-v1.md diff --git a/docs/nitrolite/api-reference/app-sessions-v1.md b/docs/nitrolite/api-reference/app-sessions-v1.md new file mode 100644 index 0000000..b1ae7fb --- /dev/null +++ b/docs/nitrolite/api-reference/app-sessions-v1.md @@ -0,0 +1,167 @@ +--- +title: app_sessions.v1 +description: Nitrolite v1 app-session RPC methods sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 4 +--- + +# app_sessions.v1 + +App-session methods create sessions, submit signed app-state updates, deposit into sessions, rebalance sessions, and manage app-session session keys. Send requests with the compact envelope described in [Interaction Model](../protocol/interaction-model): `[1, requestId, method, payload, timestamp]`. + +:::important Register the app first +`create_app_session` requires the application to exist in the app registry. If you receive `application_not_registered`, register it with [`apps.v1.submit_app_version`](./apps-v1#submit_app_version), then retry session creation. +::: + +## submit_deposit_state + +Submit an application session deposit state update. +SDK wrapper: `Client.submitAppSessionDeposit(appStateUpdate, quorumSigs, asset, depositAmount)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_state_update` | [`app_state_update`](./types#app_state_update) | required | Application session state update. | +| `quorum_sigs` | `array` | required | App-session state update signatures. | +| `user_state` | [`state`](./types#state) | required | User state associated with the update. | + +| Response field | Type | Description | +| --- | --- | --- | +| `signature` | `string` | Node signature for the deposit state. | +Errors: `invalid_app_state`, `quorum_not_met`, `channel_not_found`. See [Errors](./errors). + +```json +[1, 2001, "app_sessions.v1.submit_deposit_state", { "app_state_update": { "app_session_id": "0xSession", "intent": "deposit", "version": "2", "allocations": [], "session_data": "{}" }, "quorum_sigs": ["0xSig"], "user_state": { "id": "0xState", "asset": "usdc" } }, 1741344819012] +``` + +## submit_app_state + +Submit an application session state update. +SDK wrapper: `Client.submitAppState(appStateUpdate, quorumSigs)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_state_update` | [`app_state_update`](./types#app_state_update) | required | Application session state update. | +| `quorum_sigs` | `array` | required | App-session state update signatures required for quorum. | +Response: empty payload. +Errors: `invalid_app_state`, `quorum_not_met`, `ongoing_transition`. See [Errors](./errors). + +```json +[1, 2002, "app_sessions.v1.submit_app_state", { "app_state_update": { "app_session_id": "0xSession", "intent": "operate", "version": "3", "allocations": [], "session_data": "{\"move\":\"e4\"}" }, "quorum_sigs": ["0xSigA", "0xSigB"] }, 1741344819012] +``` + +## rebalance_app_sessions + +Rebalance multiple application sessions atomically. +SDK wrapper: `Client.rebalanceAppSessions(signedUpdates)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `signed_updates` | `array` | required | Signed app-state updates; each update must have intent `rebalance`. | + +| Response field | Type | Description | +| --- | --- | --- | +| `batch_id` | `string` | Unique identifier of the executed rebalance operation. | +Errors: none declared in `docs/api.yaml`. + +```json +[1, 2003, "app_sessions.v1.rebalance_app_sessions", { "signed_updates": [{ "app_state_update": { "app_session_id": "0xSession", "intent": "rebalance", "version": "4", "allocations": [], "session_data": "{}" }, "quorum_sigs": ["0xSig"] }] }, 1741344819012] +``` + +## get_app_definition + +Retrieve the application definition for a specific app session. +SDK wrapper: `Client.getAppDefinition(appSessionId)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_session_id` | `string` | required | Application session ID. | + +| Response field | Type | Description | +| --- | --- | --- | +| `definition` | [`app_definition`](./types#app_definition) | Application definition. | +Errors: `app_session_not_found`. See [Errors](./errors). + +```json +[1, 2004, "app_sessions.v1.get_app_definition", { "app_session_id": "0xSession" }, 1741344819012] +``` + +## get_app_sessions + +List all application sessions for a participant with optional filtering. +SDK wrapper: `Client.getAppSessions({ appSessionId, wallet, status, page, pageSize })`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_session_id` | `string` | optional | Filter by application session ID. | +| `participant` | `string` | optional | Filter by participant wallet address. | +| `status` | `string` | optional | Filter by `open` or `closed`. | +| `pagination` | [`pagination_params`](./types#pagination_params) | optional | Pagination parameters. | + +| Response field | Type | Description | +| --- | --- | --- | +| `app_sessions` | `array` | List of application sessions. | +| `metadata` | [`pagination_metadata`](./types#pagination_metadata) | Pagination information. | +Errors: `invalid_parameters`. See [Errors](./errors). + +```json +[1, 2005, "app_sessions.v1.get_app_sessions", { "participant": "0xUser", "status": "open", "pagination": { "offset": 0, "limit": 20 } }, 1741344819012] +``` + +## create_app_session + +Create a new application session between participants. +SDK wrapper: `Client.createAppSession(definition, sessionData, quorumSigs, { ownerSig })`. + +Before calling this method, register the application with [`apps.v1.submit_app_version`](./apps-v1#submit_app_version). The `application_not_registered` error means the app registry does not know the `definition.application_id`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `definition` | [`app_definition`](./types#app_definition) | required | Application definition including participants and quorum. | +| `session_data` | `string` | required | JSON stringified session data. | +| `quorum_sigs` | `array` | required | Participant signatures for app-session creation. | +| `owner_sig` | `string` | optional | Owner signature, required when creation approval is required. | + +| Response field | Type | Description | +| --- | --- | --- | +| `app_session_id` | `string` | Created application session ID. | +| `version` | `string` | Initial session version. | +| `status` | `string` | Session status, normally `open`. | +Errors: `invalid_definition`, `application_not_registered`, `owner_sig_required`, `invalid_owner_signature`, `insufficient_balance`. See [Errors](./errors). + +```json +[1, 2006, "app_sessions.v1.create_app_session", { "definition": { "application_id": "demo-app", "participants": [{ "wallet_address": "0xUser", "signature_weight": 1 }], "quorum": 1, "nonce": "1" }, "session_data": "{}", "quorum_sigs": ["0xSig"] }, 1741344819012] +``` + +## submit_session_key_state + +Submit the app-session key state for registration and updates. +SDK wrapper: `Client.submitSessionKeyState(state)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `state` | [`app_session_key_state`](./types#app_session_key_state) | required | Session key metadata and delegation information. | +Response: empty payload. +Errors: `invalid_session_key_state`. See [Errors](./errors). + +```json +[1, 2007, "app_sessions.v1.submit_session_key_state", { "state": { "user_address": "0xUser", "session_key": "0xKey", "version": "1", "application_id": ["demo-app"], "app_session_id": ["0xSession"], "expires_at": "1770000000", "user_sig": "0xSig" } }, 1741344819012] +``` + +## get_last_key_states + +Retrieve latest app-session key states for a user, optionally filtered by session key. +SDK wrapper: `Client.getLastKeyStates(userAddress, sessionKey?)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | +| `session_key` | `string` | optional | Optional session key filter. | + +| Response field | Type | Description | +| --- | --- | --- | +| `states` | `array` | Active app-session key states for the user. | +Errors: `account_not_found`. See [Errors](./errors). + +```json +[1, 2008, "app_sessions.v1.get_last_key_states", { "wallet": "0xUser", "session_key": "0xKey" }, 1741344819012] +``` diff --git a/docs/nitrolite/api-reference/app-sessions.md b/docs/nitrolite/api-reference/app-sessions.md deleted file mode 100644 index 60dad55..0000000 --- a/docs/nitrolite/api-reference/app-sessions.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -sidebar_position: 3 -title: App Sessions -description: API reference for virtual application session management -keywords: [app session, create, submit, close, virtual application, api] -displayed_sidebar: apiSidebar ---- - -# App Sessions - -API methods for managing virtual application sessions. - -## create_app_session - -Creates a virtual application session between participants. - -**Request:** -```json -{ - "req": [1, "create_app_session", { - "definition": { - "protocol": "NitroRPC/0.2" | "NitroRPC/0.4", - "participants": Address[], - "weights": number[], - "quorum": number, - "challenge": number, - "nonce": number - }, - "allocations": AppAllocation[], - "session_data": string // Optional - }, timestamp], - "sig": Hex[] -} -``` - -**Response:** -```json -{ - "res": [1, "create_app_session", { - "app_session_id": Hex, - "version": string, - "status": "open" - }, timestamp], - "sig": [Hex] -} -``` - -## submit_app_state - -Updates session state and redistributes funds. - -### NitroRPC/0.2 - -**Request:** -```json -{ - "req": [1, "submit_app_state", { - "app_session_id": Hex, - "allocations": AppAllocation[], - "session_data": string // Optional - }, timestamp], - "sig": Hex[] -} -``` - -### NitroRPC/0.4 - -**Request:** -```json -{ - "req": [1, "submit_app_state", { - "app_session_id": Hex, - "intent": "operate" | "deposit" | "withdraw", - "version": number, - "allocations": AppAllocation[], - "session_data": string // Optional - }, timestamp], - "sig": Hex[] -} -``` - -**Response:** -```json -{ - "res": [1, "submit_app_state", { - "app_session_id": Hex, - "version": string, - "status": "open" - }, timestamp], - "sig": [Hex] -} -``` - -## close_app_session - -Closes session and finalizes fund distribution. - -**Request:** -```json -{ - "req": [1, "close_app_session", { - "app_session_id": Hex, - "allocations": AppAllocation[], - "session_data": string // Optional - }, timestamp], - "sig": Hex[] -} -``` - -**Response:** -```json -{ - "res": [1, "close_app_session", { - "app_session_id": Hex, - "version": string, - "status": "closed" - }, timestamp], - "sig": [Hex] -} -``` - -## Types - -### AppAllocation -```typescript -interface AppAllocation { - participant: Address; - asset: string; - amount: string; -} -``` - -### AppDefinition -```typescript -interface AppDefinition { - protocol: "NitroRPC/0.2" | "NitroRPC/0.4"; - participants: Address[]; - weights: number[]; - quorum: number; - challenge: number; - nonce: number; -} -``` - -## Intent Types (NitroRPC/0.4) - -- `operate`: Redistribute existing session funds -- `deposit`: Add funds from participants' unified balances -- `withdraw`: Remove funds to participants' unified balances - -## Session Status - -- `open`: Session is active and accepting state updates -- `closed`: Session is finalized, no further updates allowed \ No newline at end of file diff --git a/docs/nitrolite/api-reference/apps-v1.md b/docs/nitrolite/api-reference/apps-v1.md new file mode 100644 index 0000000..da10f64 --- /dev/null +++ b/docs/nitrolite/api-reference/apps-v1.md @@ -0,0 +1,54 @@ +--- +title: apps.v1 +description: Nitrolite v1 app registry RPC methods sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 5 +--- + +# apps.v1 + +App registry methods list registered applications and register new application versions. Send requests with the compact envelope described in [Interaction Model](../protocol/interaction-model): `[1, requestId, method, payload, timestamp]`. + +## get_apps + +Retrieve registered applications with optional filtering by app ID and owner wallet. + +SDK wrapper: `Client.getApps({ appId, ownerWallet, page, pageSize })`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_id` | `string` | optional | Filter by application ID. | +| `owner_wallet` | `string` | optional | Filter by owner wallet address. | +| `pagination` | [`pagination_params`](./types#pagination_params) | optional | Pagination parameters. | + +| Response field | Type | Description | +| --- | --- | --- | +| `apps` | `array` | Registered applications. | +| `metadata` | [`pagination_metadata`](./types#pagination_metadata) | Pagination information. | + +Errors: `invalid_parameters`. See [Errors](./errors). + +```json +[1, 3001, "apps.v1.get_apps", { "owner_wallet": "0xOwner", "pagination": { "offset": 0, "limit": 20 } }, 1741344819012] +``` + +## submit_app_version + +Register a new application in the app registry. Currently only version `1` creation is supported, and the owner must sign the packed app data. + +SDK wrapper: `Client.registerApp(appID, metadata, creationApprovalNotRequired)`. + +This is the registration prerequisite for [`app_sessions.v1.create_app_session`](./app-sessions-v1#create_app_session). If app-session creation returns `application_not_registered`, submit the app version first and then retry session creation. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app` | [`app`](./types#app) | required | Application definition including ID, owner wallet, metadata, version, and creation approval flag. | +| `owner_sig` | `string` | required | Owner EIP-191 signature over the packed application data. | + +Response: empty payload. + +Errors: `invalid_app_id`, `invalid_version`, `invalid_signature`, `app_already_exists`. See [Errors](./errors). + +```json +[1, 3002, "apps.v1.submit_app_version", { "app": { "id": "demo-app", "owner_wallet": "0xOwner", "metadata": "0xMetadata", "version": "1", "creation_approval_not_required": true }, "owner_sig": "0xSig" }, 1741344819012] +``` diff --git a/docs/nitrolite/api-reference/channels-v1.md b/docs/nitrolite/api-reference/channels-v1.md new file mode 100644 index 0000000..b3f11b1 --- /dev/null +++ b/docs/nitrolite/api-reference/channels-v1.md @@ -0,0 +1,175 @@ +--- +title: channels.v1 +description: Nitrolite v1 channel RPC methods sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 3 +--- + +# channels.v1 + +Channel methods query home and escrow channels, fetch signed state, submit state transitions, and manage channel session keys. Send requests with the compact envelope described in [Interaction Model](../protocol/interaction-model): `[1, requestId, method, payload, timestamp]`. + +## get_home_channel + +Retrieve current on-chain home channel information. +SDK wrapper: `Client.getHomeChannel(wallet, asset)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | +| `asset` | `string` | required | Asset symbol. | + +| Response field | Type | Description | +| --- | --- | --- | +| `channel` | [`channel`](./types#channel) | On-chain channel information. | +Errors: `channel_not_found`. See [Errors](./errors). + +```json +[1, 1001, "channels.v1.get_home_channel", { "wallet": "0xUser", "asset": "usdc" }, 1741344819012] +``` + +## get_escrow_channel + +Retrieve current on-chain escrow channel information. +SDK wrapper: `Client.getEscrowChannel(escrowChannelId)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `escrow_channel_id` | `string` | required | Escrow channel ID. | + +| Response field | Type | Description | +| --- | --- | --- | +| `channel` | [`channel`](./types#channel) | On-chain channel information. | +Errors: `channel_not_found`. See [Errors](./errors). + +```json +[1, 1002, "channels.v1.get_escrow_channel", { "escrow_channel_id": "0xEscrowChannel" }, 1741344819012] +``` + +## get_channels + +Retrieve all channels for a user with optional filtering. +SDK wrapper: `Client.getChannels(wallet, { asset, status, pagination })`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | +| `asset` | `string` | optional | Filter by asset. | +| `status` | `string` | optional | Filter by status. | +| `pagination` | [`pagination_params`](./types#pagination_params) | optional | Pagination parameters. | + +| Response field | Type | Description | +| --- | --- | --- | +| `channels` | `array` | List of channels. | +| `metadata` | [`pagination_metadata`](./types#pagination_metadata) | Pagination information. | +Errors: `invalid_parameters`. See [Errors](./errors). + +```json +[1, 1003, "channels.v1.get_channels", { "wallet": "0xUser", "asset": "usdc", "status": "open" }, 1741344819012] +``` + +## get_latest_state + +Retrieve the current state of the user stored on the Node. +SDK wrapper: `Client.getLatestState(wallet, asset, onlySigned)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | +| `asset` | `string` | required | Asset symbol. | +| `only_signed` | `boolean` | required | When true, returns only the latest signed state. | + +| Response field | Type | Description | +| --- | --- | --- | +| `state` | [`state`](./types#state) | Current state of the user. | +Errors: `channel_not_found`. See [Errors](./errors). + +```json +[1, 1004, "channels.v1.get_latest_state", { "wallet": "0xUser", "asset": "usdc", "only_signed": true }, 1741344819012] +``` + +## request_creation + +Request the creation of a channel from Node. +SDK wrapper: internal path used by `Client.deposit(...)` when the home channel does not exist. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `state` | [`state`](./types#state) | required | Initial state to submit. | +| `channel_definition` | [`channel_definition`](./types#channel_definition) | required | Definition of the channel to create. | + +| Response field | Type | Description | +| --- | --- | --- | +| `signature` | `string` | Node signature for the state. | +Errors: `invalid_channel_definition`, `invalid_state`, `channel_already_exists`. See [Errors](./errors). + +```json +[1, 1005, "channels.v1.request_creation", { "state": { "id": "0xState", "asset": "usdc" }, "channel_definition": { "nonce": "1", "challenge": 86400 } }, 1741344819012] +``` + +## submit_state + +Submit a cross-chain channel state. +SDK wrapper: internal path used by `Client.deposit(...)`, `Client.transfer(...)`, `Client.checkpoint(...)`, and other channel-state transitions. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `state` | [`state`](./types#state) | required | Signed state to submit. | + +| Response field | Type | Description | +| --- | --- | --- | +| `signature` | `string` | Node signature for the state. | +Errors: `invalid_transition`, `ongoing_transition`, `channel_not_found`, `denied_until_checkpoint`. See [Errors](./errors). + +```json +[1, 1006, "channels.v1.submit_state", { "state": { "id": "0xState", "transition": { "type": "transfer_send", "tx_id": "tx-1", "account_id": "0xReceiver", "amount": "1.0" } } }, 1741344819012] +``` + +## submit_session_key_state + +Submit the channel session key state for registration and updates. +SDK wrapper: `Client.submitChannelSessionKeyState(state)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `state` | [`channel_session_key_state`](./types#channel_session_key_state) | required | Session key metadata and delegation information. | +Response: empty payload. +Errors: `invalid_session_key_state`. See [Errors](./errors). + +```json +[1, 1007, "channels.v1.submit_session_key_state", { "state": { "user_address": "0xUser", "session_key": "0xKey", "version": "1", "assets": ["usdc"], "expires_at": "1770000000", "user_sig": "0xSig" } }, 1741344819012] +``` + +## get_last_key_states + +Retrieve latest channel session key states for a user, optionally filtered by session key. +SDK wrapper: `Client.getLastChannelKeyStates(userAddress, sessionKey?)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `user_address` | `string` | required | User wallet address. | +| `session_key` | `string` | optional | Optional session key filter. | + +| Response field | Type | Description | +| --- | --- | --- | +| `states` | `array` | Active channel session key states for the user. | +Errors: `account_not_found`. See [Errors](./errors). + +```json +[1, 1008, "channels.v1.get_last_key_states", { "user_address": "0xUser", "session_key": "0xKey" }, 1741344819012] +``` + +## Events + +### home_channel_created + +`docs/api.yaml` declares `home_channel_created` with `channel` and `initial_state` payload fields. + +:::note Future protocol revision +The [Interaction Model](../protocol/interaction-model#message-types) currently marks asynchronous event notifications as reserved for a future protocol revision. Treat `home_channel_created` as documented schema, not a stable event subscription guarantee. +::: + +| Payload field | Type | Description | +| --- | --- | --- | +| `channel` | [`channel`](./types#channel) | Created home channel information. | +| `initial_state` | [`state`](./types#state) | Initial state of the home channel. | diff --git a/docs/nitrolite/api-reference/errors.md b/docs/nitrolite/api-reference/errors.md new file mode 100644 index 0000000..0e632e1 --- /dev/null +++ b/docs/nitrolite/api-reference/errors.md @@ -0,0 +1,37 @@ +--- +title: Errors +description: Aggregated Nitrolite v1 RPC error messages sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 9 +--- + +# Errors + +RPC failures are returned as error response messages in the envelope described by [Interaction Model](../protocol/interaction-model#error-handling). Surface the message safely to users, log the method and request ID, and guide the user to the next recoverable action where one exists. + +| Error message | Returned by | User-facing handling | +| --- | --- | --- | +| `account_not_found` | `channels.v1.get_last_key_states`, `app_sessions.v1.get_last_key_states`, `user.v1.get_balances` | Ask the user to reconnect or verify the wallet address. | +| `app_already_exists` | `apps.v1.submit_app_version` | Treat registration as complete if the app metadata matches; otherwise choose a new app ID. | +| `app_session_not_found` | `app_sessions.v1.get_app_definition` | Refresh the session list before retrying. | +| `application_not_registered` | `app_sessions.v1.create_app_session` | Register the app with [`apps.v1.submit_app_version`](./apps-v1#submit_app_version), then retry. | +| `channel_already_exists` | `channels.v1.request_creation` | Fetch the existing channel and continue from its latest state. | +| `channel_not_found` | `channels.v1.get_home_channel`, `channels.v1.get_escrow_channel`, `channels.v1.get_latest_state`, `channels.v1.submit_state`, `app_sessions.v1.submit_deposit_state` | Create or fund the required channel, or refresh local channel IDs. | +| `denied_until_checkpoint` | `channels.v1.submit_state` | Run the checkpoint flow before submitting another state. | +| `insufficient_balance` | `app_sessions.v1.create_app_session` | Ask the user to deposit or reduce allocations. | +| `invalid_app_id` | `apps.v1.submit_app_version` | Fix the application ID format. | +| `invalid_app_state` | `app_sessions.v1.submit_deposit_state`, `app_sessions.v1.submit_app_state` | Rebuild the app-state update from the latest session version. | +| `invalid_channel_definition` | `channels.v1.request_creation` | Recompute the channel definition from SDK helpers. | +| `invalid_definition` | `app_sessions.v1.create_app_session` | Validate participants, quorum, nonce, and application ID. | +| `invalid_owner_signature` | `app_sessions.v1.create_app_session` | Re-sign creation approval with the registered owner wallet. | +| `invalid_parameters` | `channels.v1.get_channels`, `app_sessions.v1.get_app_sessions`, `apps.v1.get_apps` | Fix filters and pagination parameters. | +| `invalid_session_key_state` | `channels.v1.submit_session_key_state`, `app_sessions.v1.submit_session_key_state` | Rebuild the session key state and verify expiration, scope, and user signature. | +| `invalid_signature` | `apps.v1.submit_app_version` | Re-sign packed app data with the owner wallet. | +| `invalid_state` | `channels.v1.request_creation` | Rebuild and sign the state from canonical SDK state helpers. | +| `invalid_transition` | `channels.v1.submit_state` | Recompute the next state from the latest node-signed state. | +| `invalid_version` | `apps.v1.submit_app_version` | Submit version `1`; other versions are not supported yet. | +| `ongoing_transition` | `channels.v1.submit_state`, `app_sessions.v1.submit_app_state` | Poll latest state or app session until the pending transition settles. | +| `owner_sig_required` | `app_sessions.v1.create_app_session` | Include `owner_sig` because the registered app requires owner approval. | +| `quorum_not_met` | `app_sessions.v1.submit_deposit_state`, `app_sessions.v1.submit_app_state` | Collect enough participant signatures to satisfy quorum. | +| `retrieval_failed` | `user.v1.get_action_allowances` | Retry after reconnecting; log the failure for operators. | +| `wallet_required` | `user.v1.get_action_allowances` | Request a connected wallet address before calling the method. | diff --git a/docs/nitrolite/api-reference/index.md b/docs/nitrolite/api-reference/index.md index caeb7ac..da422c8 100644 --- a/docs/nitrolite/api-reference/index.md +++ b/docs/nitrolite/api-reference/index.md @@ -1,263 +1,39 @@ --- -sidebar_position: 9 title: API Reference -description: Complete Yellow SDK method documentation with examples and type definitions -keywords: [api reference, methods, types, virtualapp client, documentation] +description: Canonical Nitrolite v1 RPC reference sourced from docs/api.yaml displayed_sidebar: apiSidebar +sidebar_position: 1 --- # API Reference -Complete reference for all Yellow SDK methods, types, and utilities. +This is the canonical Nitrolite v1 RPC surface, sourced from `docs/api.yaml` in the Nitrolite repository. Method names are grouped by namespace and version, for example `channels.v1.submit_state`. -## VirtualAppRPC Functions +RPC messages use the compact wire envelope described in [Interaction Model](../protocol/interaction-model): `[type, requestId, method, payload, timestamp]`. A request uses type `1`, a successful response uses type `2`, an event uses type `3`, and an error response uses type `4`. -### Message Creation - -#### `createAppSessionMessage(signer: MessageSigner, sessions: AppSession[]): Promise` - -Creates a signed application session message. - -**Parameters:** -```typescript -type MessageSigner = (payload: any) => Promise; - -interface AppSession { - definition: AppDefinition; - allocations: AppAllocation[]; -} - -interface AppDefinition { - protocol: string; - participants: Address[]; - weights: number[]; - quorum: number; - challenge: number; - nonce: number; -} - -interface AppAllocation { - participant: Address; - asset: string; - amount: string; -} +```json +[1, 1001, "channels.v1.get_home_channel", { "wallet": "0x...", "asset": "usdc" }, 1741344819012] ``` -#### `createStateUpdateMessage(signer: MessageSigner, update: StateUpdate): Promise` - -Creates a signed state update message. - -#### `parseRPCResponse(data: string): RPCMessage` - -Parses ClearNode response messages. - -**Returns:** -```typescript -interface RPCMessage { - id?: number; - method?: string; - params?: any; - result?: any; - error?: RPCError; -} -``` - -### Utilities - -#### `computeChannelId(channel: Channel): ChannelId` +:::info Looking for the 0.5.3 helper API? +If your app still imports legacy 0.5.3 message helpers, start with the [TypeScript compat SDK](../build/sdk/typescript-compat/overview). This section documents the v1 RPC methods, not the legacy helper surface. +::: -Calculates deterministic channel identifier. - -#### `computeStateHash(state: State, channelId: ChannelId): Hash` - -Calculates state hash for signatures. - -#### `validateSignature(state: State, signature: Hex, signer: Address): Promise` - -Verifies state signature. - -## Type Definitions - -### Core Types - -```typescript -type Address = `0x${string}`; -type Hash = `0x${string}`; -type Hex = `0x${string}`; -type ChannelId = Hash; - -interface Channel { - participants: Address[]; - adjudicator: Address; - challenge: bigint; - nonce: bigint; -} - -interface State { - intent: StateIntent; - version: bigint; - data: Hex; - allocations: Allocation[]; - sigs: Hex[]; -} - -interface Allocation { - destination: Address; - token: Address; - amount: bigint; -} - -enum StateIntent { - OPERATE = 0, - INITIALIZE = 1, - RESIZE = 2, - FINALIZE = 3 -} - -enum ChannelStatus { - VOID = 0, - INITIAL = 1, - ACTIVE = 2, - DISPUTE = 3, - FINAL = 4 -} -``` +## Groups -### Connection Configuration +| Group | Page | Purpose | +| --- | --- | --- | +| `channels.v1` | [Channels](./channels-v1) | Channel queries, state submission, channel session keys, and channel events. | +| `app_sessions.v1` | [App Sessions](./app-sessions-v1) | App-session creation, updates, deposits, rebalancing, and app-session keys. | +| `apps.v1` | [Apps](./apps-v1) | App registry lookup and application registration. | +| `user.v1` | [User](./user-v1) | Balances, transaction history, and action allowances. | +| `node.v1` | [Node](./node-v1) | Connectivity, node configuration, and supported assets. | +| `session_keys.v1` | [Session Keys](./session-keys-v1) | Reserved group; methods are not defined in `api.yaml` yet. | +| Types | [Types](./types) | Field tables for all shared request and response types. | +| Errors | [Errors](./errors) | Aggregated error messages and suggested user-facing handling. | -```typescript -interface ClearNodeConfig { - endpoint: string; // WebSocket endpoint - apiKey?: string; // Optional authentication - timeout: number; // Connection timeout - retryAttempts: number; // Reconnection attempts -} +## SDK and MCP Lookup -const config = { - endpoint: 'wss://clearnet-sandbox.yellow.com/ws', // or wss://clearnet.yellow.com/ws for production - timeout: 30000, - retryAttempts: 3 -}; -``` - -### RPC Types - -```typescript -interface RPCRequest { - id: number; - method: string; - params: any[]; - timestamp?: number; -} - -interface RPCResponse { - id: number; - result?: any; - error?: RPCError; - timestamp: number; -} - -interface RPCError { - code: number; - message: string; - data?: any; -} -``` - -## Error Types - -### Client Errors - -```typescript -class YellowSDKError extends Error { - constructor(message: string, public code: string, public context?: any) { - super(message); - this.name = 'YellowSDKError'; - } -} - -class NetworkError extends YellowSDKError { - constructor(message: string, context?: any) { - super(message, 'NETWORK_ERROR', context); - } -} - -class ContractError extends YellowSDKError { - constructor(message: string, context?: any) { - super(message, 'CONTRACT_ERROR', context); - } -} - -class ValidationError extends YellowSDKError { - constructor(message: string, context?: any) { - super(message, 'VALIDATION_ERROR', context); - } -} -``` - -### Error Handling - -```javascript -try { - const sessionMessage = await createAppSessionMessage(messageSigner, sessionData); - ws.send(sessionMessage); -} catch (error) { - if (error instanceof NetworkError) { - // Handle network connectivity issues - await this.reconnectToClearNode(); - } else if (error instanceof ValidationError) { - // Handle input validation errors - console.error('Invalid session parameters:', error.context); - } else if (error instanceof SigningError) { - // Handle wallet signing errors - console.error('Message signing failed:', error.message); - } else { - // Handle unexpected errors - console.error('Unexpected error:', error); - } -} -``` - -## Constants - -### Network Endpoints - -```typescript -const CLEARNODE_ENDPOINTS = { - PRODUCTION: 'wss://clearnet.yellow.com/ws', - SANDBOX: 'wss://clearnet-sandbox.yellow.com/ws', - LOCAL: 'ws://localhost:8080/ws' -}; - -const PROTOCOLS = { - PAYMENT: 'payment-app-v1', - GAMING: 'gaming-app-v1', - ESCROW: 'escrow-app-v1', - TOURNAMENT: 'tournament-v1', - SUBSCRIPTION: 'subscription-v1' -}; -``` - -### Message Types - -```typescript -const MESSAGE_TYPES = { - SESSION_CREATE: 'session_create', - SESSION_MESSAGE: 'session_message', - PAYMENT: 'payment', - STATE_UPDATE: 'state_update', - PARTICIPANT_JOIN: 'participant_join', - SESSION_CLOSE: 'session_close', - ERROR: 'error' -}; - -const SESSION_STATUS = { - PENDING: 'pending', - ACTIVE: 'active', - CLOSING: 'closing', - CLOSED: 'closed', - ERROR: 'error' -}; -``` +Most builders should call the TypeScript or Go SDK instead of hand-building envelopes. Each group page links the RPC method back to the high-level SDK method where one exists. -This API reference provides everything you need to integrate VirtualAppRPC into your applications with confidence and precision. \ No newline at end of file +If you use the Yellow SDK MCP server, ask `lookup_rpc_method` for the full method by name, for example `channels.v1.submit_state`. The MCP package documents the same `docs/api.yaml` surface and is intended for agentic API browsing. diff --git a/docs/nitrolite/api-reference/node-v1.md b/docs/nitrolite/api-reference/node-v1.md new file mode 100644 index 0000000..69246c4 --- /dev/null +++ b/docs/nitrolite/api-reference/node-v1.md @@ -0,0 +1,62 @@ +--- +title: node.v1 +description: Nitrolite v1 node RPC methods sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 7 +--- + +# node.v1 + +Node methods check connectivity and read the node configuration and supported assets. Send requests with the compact envelope described in [Interaction Model](../protocol/interaction-model): `[1, requestId, method, payload, timestamp]`. + +## ping + +Simple connectivity check. + +SDK wrapper: `Client.ping()`. + +Request: empty payload. Response: empty payload. Errors: none declared in `docs/api.yaml`. + +```json +[1, 5001, "node.v1.ping", {}, 1741344819012] +``` + +## get_config + +Retrieve broker configuration and supported networks. + +SDK wrapper: `Client.getConfig()`. + +Request: empty payload. + +| Response field | Type | Description | +| --- | --- | --- | +| `node_address` | `string` | Node wallet address. | +| `node_version` | `string` | Node software version. | +| `blockchains` | `array` | Supported networks. | + +Errors: none declared in `docs/api.yaml`. + +```json +[1, 5002, "node.v1.get_config", {}, 1741344819012] +``` + +## get_assets + +Retrieve all supported assets with optional blockchain filter. + +SDK wrapper: `Client.getAssets(blockchainId?)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `blockchain_id` | `string` | optional | Filter by blockchain network ID. | + +| Response field | Type | Description | +| --- | --- | --- | +| `assets` | `array` | Supported assets, filtered by blockchain if provided. | + +Errors: none declared in `docs/api.yaml`. + +```json +[1, 5003, "node.v1.get_assets", { "blockchain_id": "11155111" }, 1741344819012] +``` diff --git a/docs/nitrolite/api-reference/session-keys-v1.md b/docs/nitrolite/api-reference/session-keys-v1.md new file mode 100644 index 0000000..1e4f974 --- /dev/null +++ b/docs/nitrolite/api-reference/session-keys-v1.md @@ -0,0 +1,19 @@ +--- +title: session_keys.v1 +description: Reserved Nitrolite v1 session key RPC group +displayed_sidebar: apiSidebar +sidebar_position: 8 +--- + +# session_keys.v1 + +Group reserved; methods are not yet defined in `docs/api.yaml`. + +Session key operations currently live under the channel and app-session groups: + +| Existing method | Purpose | +| --- | --- | +| [`channels.v1.submit_session_key_state`](./channels-v1#submit_session_key_state) | Register or update a channel session key state. | +| [`channels.v1.get_last_key_states`](./channels-v1#get_last_key_states) | Read latest channel session key states. | +| [`app_sessions.v1.submit_session_key_state`](./app-sessions-v1#submit_session_key_state) | Register or update an app-session key state. | +| [`app_sessions.v1.get_last_key_states`](./app-sessions-v1#get_last_key_states) | Read latest app-session key states. | diff --git a/docs/nitrolite/api-reference/types.md b/docs/nitrolite/api-reference/types.md new file mode 100644 index 0000000..06aff56 --- /dev/null +++ b/docs/nitrolite/api-reference/types.md @@ -0,0 +1,260 @@ +--- +title: Types +description: Shared Nitrolite v1 RPC types sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 2 +--- + +# Types + +These field tables mirror the `types:` section of `docs/api.yaml`. Optional fields are marked in the presence column. + +## channel + +Represents an on-chain channel. + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `channel_id` | `string` | required | Unique identifier for the channel. | +| `user_wallet` | `string` | required | User wallet address. | +| `type` | `string` | required | Type of the channel: `home` or `escrow`. | +| `blockchain_id` | `string` | required | Unique identifier for the blockchain. | +| `token_address` | `string` | required | Address of the token used in the channel. | +| `challenge_duration` | `integer` | required | Challenge period for the channel in seconds. | +| `challenge_expires_at` | `string` | optional | Challenge expiration timestamp in Unix seconds. | +| `nonce` | `string` | required | Nonce for the channel. | +| `status` | `string` | required | Current status: `void`, `open`, `challenged`, or `closed`. | +| `state_version` | `string` | required | On-chain state version of the channel. | + +## transition_type + +Type of state transition. Values: `transfer_receive`, `transfer_send`, `release`, `commit`, `home_deposit`, `home_withdrawal`, `mutual_lock`, `escrow_deposit`, `escrow_lock`, `escrow_withdraw`, `migrate`, `finalize`. + +## transition + +Represents a state transition. + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `type` | `transition_type` | required | Type of state transition. | +| `tx_id` | `string` | required | Transaction ID associated with the transition. | +| `account_id` | `string` | required | Account identifier, varying by transition type. | +| `amount` | `string` | required | Amount involved in the transition. | + +## state + +Represents the current state of the user stored on Node. + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `id` | `string` | required | Deterministic ID hash of the state. | +| `transition` | `transition` | required | State transition that led to this state. | +| `asset` | `string` | required | Asset type of the state. | +| `user_wallet` | `string` | required | User wallet address. | +| `epoch` | `string` | required | User epoch index. | +| `version` | `string` | required | Version of the state. | +| `home_channel_id` | `string` | optional | Identifier for the home channel. | +| `escrow_channel_id` | `string` | optional | Identifier for the escrow channel. | +| `home_ledger` | `ledger` | required | User and node balances for the home channel. | +| `escrow_ledger` | `ledger` | optional | User and node balances for the escrow channel. | +| `user_sig` | `string` | optional | User signature for the state. | +| `node_sig` | `string` | optional | Node signature for the state. | + +## ledger + +Represents ledger balances. + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `token_address` | `string` | required | Address of the token used in this channel. | +| `blockchain_id` | `string` | required | Unique identifier for the blockchain. | +| `user_balance` | `string` | required | User balance in the channel. | +| `user_net_flow` | `string` | required | User net flow in the channel. | +| `node_balance` | `string` | required | Node balance in the channel. | +| `node_net_flow` | `string` | required | Node net flow in the channel. | + +## channel_definition + +Configuration for creating a channel. + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `nonce` | `string` | required | Unique number to prevent replay attacks. | +| `challenge` | `integer` | required | Challenge period for the channel in seconds. | + +## app_participant + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet_address` | `string` | required | Participant wallet address. | +| `signature_weight` | `integer` | required | Signature weight for the participant. | + +## app_definition + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `application_id` | `string` | required | Application identifier from an app registry. | +| `participants` | `array` | required | List of participants in the app session. | +| `quorum` | `integer` | required | Quorum required for the app session. | +| `nonce` | `string` | required | Unique number to prevent replay attacks. | + +## app_allocation + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `participant` | `string` | required | Participant wallet address. | +| `asset` | `string` | required | Asset symbol. | +| `amount` | `string` | required | Amount allocated to the participant. | + +## app_state_update + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_session_id` | `string` | required | Unique application session identifier. | +| `intent` | `string` | required | Update intent: `operate`, `deposit`, `withdraw`, `close`, or `rebalance`. | +| `version` | `string` | required | Version of the app state. | +| `allocations` | `array` | required | Allocations in the app state. | +| `session_data` | `string` | required | JSON stringified session data. | + +## signed_app_state_update + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_state_update` | `app_state_update` | required | Application session state update. | +| `quorum_sigs` | `array` | required | Signature quorum for the application session. | + +## token + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `name` | `string` | required | Token name. | +| `symbol` | `string` | required | Token symbol. | +| `address` | `string` | required | Token contract address. | +| `blockchain_id` | `string` | required | Blockchain network ID. | +| `decimals` | `integer` | required | Number of decimal places. | + +## asset + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `name` | `string` | required | Asset name. | +| `symbol` | `string` | required | Asset symbol. | +| `decimals` | `integer` | required | Asset decimal places. | +| `suggested_blockchain_id` | `string` | required | Suggested blockchain network ID for this asset. | +| `tokens` | `array` | required | Supported tokens for the asset. | + +## blockchain_info + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `name` | `string` | required | Blockchain name. | +| `blockchain_id` | `string` | required | Blockchain network ID. | +| `contract_address` | `string` | required | Main contract address on this blockchain. | + +## balance_entry + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `asset` | `string` | required | Asset symbol. | +| `amount` | `string` | required | Balance amount. | +| `enforced` | `string` | required | On-chain enforced balance. | + +## transaction_type + +Type of transaction. Values: `transfer`, `release`, `commit`, `home_deposit`, `home_withdrawal`, `mutual_lock`, `escrow_deposit`, `escrow_lock`, `escrow_withdraw`, `migrate`, `rebalance`, `finalize`. + +## transaction + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `id` | `string` | required | Unique transaction reference. | +| `asset` | `string` | required | Asset symbol. | +| `tx_type` | `transaction_type` | required | Transaction type. | +| `from_account` | `string` | required | Account that sent the funds. | +| `to_account` | `string` | required | Account that received the funds. | +| `sender_new_state_id` | `string` | optional | ID of the sender's new channel state. | +| `receiver_new_state_id` | `string` | optional | ID of the receiver's new channel state. | +| `amount` | `string` | required | Transaction amount. | +| `created_at` | `string` | required | Creation timestamp. | + +## app_session_info + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `app_session_id` | `string` | required | Unique application session identifier. | +| `status` | `string` | required | Session status: `open` or `closed`. | +| `app_definition` | `app_definition` | required | Application definition for this session. | +| `session_data` | `string` | optional | JSON stringified session data. | +| `version` | `string` | required | Current version of the session state. | +| `allocations` | `array` | required | Allocations in the app state. | + +## channel_session_key_state + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `user_address` | `string` | required | User wallet address. | +| `session_key` | `string` | required | Session key address for delegation. | +| `version` | `string` | required | Session key format version. | +| `assets` | `array` | required | Assets associated with this session key. | +| `expires_at` | `string` | required | Unix timestamp in seconds when the key expires. | +| `user_sig` | `string` | required | User signature authorizing the registration or update. | + +## app_session_key_state + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `user_address` | `string` | required | User wallet address. | +| `session_key` | `string` | required | Session key address for delegation. | +| `version` | `string` | required | Session key format version. | +| `application_id` | `array` | required | Application IDs associated with this session key. | +| `app_session_id` | `array` | required | App-session IDs associated with this session key. | +| `expires_at` | `string` | required | Unix timestamp in seconds when the key expires. | +| `user_sig` | `string` | required | User signature authorizing the registration or update. | + +## app + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `id` | `string` | required | Application identifier. | +| `owner_wallet` | `string` | required | Owner wallet address. | +| `metadata` | `string` | required | Application metadata bytes32 hash. | +| `version` | `string` | required | Current application version. | +| `creation_approval_not_required` | `boolean` | required | Whether app sessions can be created without owner approval. | + +## app_info + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `id` | `string` | required | Application identifier. | +| `owner_wallet` | `string` | required | Owner wallet address. | +| `metadata` | `string` | required | Application metadata bytes32 hash. | +| `version` | `string` | required | Current application version. | +| `creation_approval_not_required` | `boolean` | required | Whether app sessions can be created without owner approval. | +| `created_at` | `string` | required | Creation timestamp in Unix seconds. | +| `updated_at` | `string` | required | Last update timestamp in Unix seconds. | + +## action_allowance + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `gated_action` | `string` | required | Gated action: `transfer`, `app_session_deposit`, `app_session_operation`, or `app_session_withdrawal`. | +| `time_window` | `string` | required | Time window for the allowance, for example `24h0m0s`. | +| `allowance` | `string` | required | Total allowance within the window. | +| `used` | `string` | required | Amount already used within the window. | + +## pagination_params + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `offset` | `integer` | optional | Number of items to skip. | +| `limit` | `integer` | optional | Number of items to return. | +| `sort` | `string` | optional | Sort order: `asc` or `desc`. | + +## pagination_metadata + +| Field | Type | Presence | Description | +| --- | --- | --- | --- | +| `page` | `integer` | required | Current page number. | +| `per_page` | `integer` | required | Number of items per page. | +| `total_count` | `integer` | required | Total number of items. | +| `page_count` | `integer` | required | Total number of pages. | diff --git a/docs/nitrolite/api-reference/user-v1.md b/docs/nitrolite/api-reference/user-v1.md new file mode 100644 index 0000000..f346301 --- /dev/null +++ b/docs/nitrolite/api-reference/user-v1.md @@ -0,0 +1,76 @@ +--- +title: user.v1 +description: Nitrolite v1 user RPC methods sourced from docs/api.yaml +displayed_sidebar: apiSidebar +sidebar_position: 6 +--- + +# user.v1 + +User methods read balances, transaction history, and action allowances. Send requests with the compact envelope described in [Interaction Model](../protocol/interaction-model): `[1, requestId, method, payload, timestamp]`. + +## get_balances + +Retrieve the balances of the user in YN. + +SDK wrapper: `Client.getBalances(wallet)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | + +| Response field | Type | Description | +| --- | --- | --- | +| `balances` | `array` | List of asset balances. | + +Errors: `account_not_found`. See [Errors](./errors). + +```json +[1, 4001, "user.v1.get_balances", { "wallet": "0xUser" }, 1741344819012] +``` + +## get_transactions + +Retrieve ledger transaction history with optional filtering. + +SDK wrapper: `Client.getTransactions(wallet, options)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | +| `asset` | `string` | optional | Filter by asset symbol. | +| `tx_type` | [`transaction_type`](./types#transaction_type) | optional | Filter by transaction type. | +| `pagination` | [`pagination_params`](./types#pagination_params) | optional | Pagination parameters. | +| `from_time` | `integer` | optional | Start timestamp filter. | +| `to_time` | `integer` | optional | End timestamp filter. | + +| Response field | Type | Description | +| --- | --- | --- | +| `transactions` | `array` | Ledger transactions. | +| `metadata` | [`pagination_metadata`](./types#pagination_metadata) | Pagination information. | + +Errors: none declared in `docs/api.yaml`. + +```json +[1, 4002, "user.v1.get_transactions", { "wallet": "0xUser", "asset": "usdc", "pagination": { "offset": 0, "limit": 20 } }, 1741344819012] +``` + +## get_action_allowances + +Retrieve action allowances for a user based on their staking level. + +SDK wrapper: `Client.getActionAllowances(wallet)`. + +| Request field | Type | Presence | Description | +| --- | --- | --- | --- | +| `wallet` | `string` | required | User wallet address. | + +| Response field | Type | Description | +| --- | --- | --- | +| `allowances` | `array` | Action allowances. | + +Errors: `wallet_required`, `retrieval_failed`. See [Errors](./errors). + +```json +[1, 4003, "user.v1.get_action_allowances", { "wallet": "0xUser" }, 1741344819012] +``` From 7db6dd8831f66139b8ccd85e1c045710c8f0cc47 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 8 May 2026 09:15:48 +0530 Subject: [PATCH 2/2] YNU-864: Clarify API Reference orientation --- docs/nitrolite/api-reference/index.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/nitrolite/api-reference/index.md b/docs/nitrolite/api-reference/index.md index da422c8..68f81d1 100644 --- a/docs/nitrolite/api-reference/index.md +++ b/docs/nitrolite/api-reference/index.md @@ -7,6 +7,8 @@ sidebar_position: 1 # API Reference +The **Protocol** tab describes the semantic model: envelope structure, channel lifecycle, state-and-ledger model, enforcement guarantees, and other conceptual pieces. **API Reference** catalogs the concrete RPC methods that bind that model to the wire. Most app builders never read this tab directly: the TypeScript and Go SDKs build the envelopes, sign requests, and surface every method below as a typed function call. Reach for hand-rolled RPC only when you are integrating from a language without an official SDK, building a thin proxy or wire debugger, or generating code against `docs/api.yaml`. + This is the canonical Nitrolite v1 RPC surface, sourced from `docs/api.yaml` in the Nitrolite repository. Method names are grouped by namespace and version, for example `channels.v1.submit_state`. RPC messages use the compact wire envelope described in [Interaction Model](../protocol/interaction-model): `[type, requestId, method, payload, timestamp]`. A request uses type `1`, a successful response uses type `2`, an event uses type `3`, and an error response uses type `4`. @@ -19,6 +21,16 @@ RPC messages use the compact wire envelope described in [Interaction Model](../p If your app still imports legacy 0.5.3 message helpers, start with the [TypeScript compat SDK](../build/sdk/typescript-compat/overview). This section documents the v1 RPC methods, not the legacy helper surface. ::: +## Use the SDKs first + +The official SDKs are the recommended way to call every method documented here: + +- **TypeScript:** [`@yellow-org/sdk`](../build/sdk/typescript/getting-started) for new apps, or [`@yellow-org/sdk-compat`](../build/sdk/typescript-compat/overview) for migrations from `@erc7824/nitrolite@0.5.3`. You get IDE autocomplete, parameter checking, discriminated-union response types, and correct amount-unit handling out of the box. +- **Go:** [`github.com/layer-3/nitrolite/sdk/go`](../build/sdk/go/getting-started) for backends and CLI tooling, with typed structs for every request and response. +- **MCP server (`@yellow-org/sdk-mcp`, coming soon):** ask `lookup_rpc_method` for a method by name, for example `channels.v1.submit_state`, and `lookup_method` to find the matching SDK call. The MCP indexes the same `docs/api.yaml` surface and is intended for agentic browsing inside coding tools. + +The SDKs handle the `[type, requestId, method, payload, timestamp]` envelope, signing, response correlation, event streams, auth/session-key plumbing, and amount-unit conversions. Reach for the catalogue below when you genuinely need to inspect or generate against the wire surface. + ## Groups | Group | Page | Purpose | @@ -31,9 +43,3 @@ If your app still imports legacy 0.5.3 message helpers, start with the [TypeScri | `session_keys.v1` | [Session Keys](./session-keys-v1) | Reserved group; methods are not defined in `api.yaml` yet. | | Types | [Types](./types) | Field tables for all shared request and response types. | | Errors | [Errors](./errors) | Aggregated error messages and suggested user-facing handling. | - -## SDK and MCP Lookup - -Most builders should call the TypeScript or Go SDK instead of hand-building envelopes. Each group page links the RPC method back to the high-level SDK method where one exists. - -If you use the Yellow SDK MCP server, ask `lookup_rpc_method` for the full method by name, for example `channels.v1.submit_state`. The MCP package documents the same `docs/api.yaml` surface and is intended for agentic API browsing.