Skip to content

YNU-864: Native TS SDK pages polish + terminology #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ihsraham wants to merge 1 commit into
base: docs/reorg-for-v1
Choose a base branch
from
Open

YNU-864: Native TS SDK pages polish + terminology #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/nitrolite/build/sdk/go/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: API Reference
description: Complete API reference for the Clearnode Go SDK
description: Complete API reference for the Nitronode Go SDK
sidebar_position: 2
---

Expand Down Expand Up @@ -92,7 +92,7 @@ batchID, err := client.RebalanceAppSessions(ctx, signedUpdates)

---

## Session Keys — App Sessions
## Session Keys: App Sessions

```go
state := app.AppSessionKeyStateV1{
Expand All @@ -112,7 +112,7 @@ states, err := client.GetLastAppKeyStates(ctx, userAddress, nil)

---

## Session Keys — Channels
## Session Keys: Channels

```go
state := core.ChannelSessionKeyStateV1{
Expand Down
32 changes: 18 additions & 14 deletions docs/nitrolite/build/sdk/go/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: Getting Started
description: Install and set up the Clearnode Go SDK
description: Install and set up the Nitronode Go SDK
sidebar_position: 1
---

# Getting Started with the Go SDK

Go SDK for Clearnode payment channels providing both high-level and low-level operations in a unified client. It has full feature parity with the TypeScript SDK.
Go SDK for Nitronode payment channels providing both high-level and low-level operations in a unified client.

## Requirements

- Go 1.21+
- Running Clearnode instance
- Go 1.25.7 or later
- Running Nitronode instance
- Blockchain RPC endpoint (for `Checkpoint` settlement)

## Installation
Expand All @@ -22,6 +22,10 @@ go get github.com/layer-3/nitrolite/sdk/go

## Quick Start

:::info Sandbox URL - coming soon
Use your Nitronode WebSocket URL in `sdk.NewClient()`. The public sandbox URL is intentionally shown as `<sandbox-url-coming-soon>` until the canonical host is pinned.
:::

```go
package main

Expand All @@ -42,7 +46,7 @@ func main() {

// 2. Create unified client
client, _ := sdk.NewClient(
"wss://clearnode.example.com/ws",
"<sandbox-url-coming-soon>",
stateSigner,
txSigner,
sdk.WithBlockchainRPC(80002, "https://polygon-amoy.alchemy.com/v2/KEY"),
Expand Down Expand Up @@ -120,11 +124,11 @@ txHash, _ := client.Checkpoint(ctx, "usdc")

### Channel Lifecycle

1. **Void** — No channel exists
2. **Create** — `Deposit()` creates channel on-chain via `Checkpoint()`
3. **Open** — Channel active; can deposit, withdraw, transfer
4. **Challenged** — Dispute initiated
5. **Closed** — Channel finalized
1. **Void**: No channel exists
2. **Create**: `Deposit()` creates channel on-chain via `Checkpoint()`
3. **Open**: Channel active; can deposit, withdraw, transfer
4. **Challenged**: Dispute initiated
5. **Closed**: Channel finalized

## Configuration Options

Expand All @@ -150,7 +154,7 @@ if err != nil {
```

Common errors:
- `"home blockchain not set for asset"` — Missing `SetHomeBlockchain`
- `"blockchain RPC not configured for chain"` — Missing `WithBlockchainRPC`
- `"no channel exists for asset"` — `Checkpoint` without a co-signed state
- `"insufficient balance"` — Not enough funds in channel/wallet
- `"home blockchain not set for asset"`: Missing `SetHomeBlockchain`
- `"blockchain RPC not configured for chain"`: Missing `WithBlockchainRPC`
- `"no channel exists for asset"`: `Checkpoint` without a co-signed state
- `"insufficient balance"`: Not enough funds in channel/wallet
23 changes: 13 additions & 10 deletions docs/nitrolite/build/sdk/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,30 @@ sidebar_position: 1

Yellow Network provides official SDKs for building applications on top of Nitrolite payment channels. All SDKs share the same two-step architecture: **build and co-sign states off-chain**, then **settle on-chain when needed**.

## Available SDKs
## Choose your SDK

| Package | Language | Description |
|---------|----------|-------------|
| [`@yellow-org/sdk`](./typescript/getting-started) | TypeScript | Main SDK with full API coverage |
| [`@yellow-org/sdk-compat`](./typescript-compat/overview) | TypeScript | Compatibility layer for migrating from v0.5.3 |
| [`clearnode-go-sdk`](./go/getting-started) | Go | Go SDK with full feature parity |
| Builder type | Package | Import | Notes |
|---|---|---|---|
| New TypeScript app | [`@yellow-org/sdk@1.2.1`](./typescript/getting-started) | `import { Client, createSigners } from '@yellow-org/sdk'` | Native v1 SDK; uses `Decimal` amounts. |
| Migrating from 0.5.3 (TS) | [`@yellow-org/sdk-compat@1.2.1`](./typescript-compat/overview) | `import { NitroliteClient } from '@yellow-org/sdk-compat'` | Minimal-diff bridge for `@erc7824/nitrolite@0.5.3`; see the compat codemod workflow. |
| Go integration | [`github.com/layer-3/nitrolite/sdk/go`](./go/getting-started) | `import "github.com/layer-3/nitrolite/sdk/go"` | Root Go module; no separate Go module for the SDK package. |
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Notes cell describes a package-structure implementation detail ("Root Go module; no separate Go module for the SDK package.") rather than a builder-facing usage characteristic. All other rows' notes describe usage semantics (amount type, compat workflow). Replace with something builder-relevant, e.g. "Standard Go package; go get github.com/layer-3/nitrolite/sdk/go."

| Agentic IDE / AI agents | `@yellow-org/sdk-mcp@1.2.1` | `npx -y @yellow-org/sdk-mcp` | MCP server with binary `yellow-sdk-mcp`; coming soon on npm. |
| 0.5.3 codemod | `@yellow-org/nitrolite-codemod@1.0.0` | `npx -y @yellow-org/nitrolite-codemod` | One-time migration tool; use the source workflow until the npm package publishes. |
| Smart contracts | `contracts/src/ChannelHub.sol` | See the deployment repository | v1 ChannelHub entrypoint for settlement. |
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this can be removed as Smart contracts are not an SDK.


## Architecture

All SDKs follow a unified design:

- **State Operations** (off-chain): `deposit()`, `withdraw()`, `transfer()`, `closeHomeChannel()`, `acknowledge()` — build and co-sign channel states without touching the blockchain.
- **Blockchain Settlement**: `checkpoint()` — the single entry point for all on-chain transactions. Routes to the correct contract method based on transition type and channel status.
- **State Operations** (off-chain): `deposit()`, `withdraw()`, `transfer()`, `closeHomeChannel()`, `acknowledge()`. Build and co-sign channel states without touching the blockchain.
- **Blockchain Settlement**: `checkpoint()`. The single entry point for all on-chain transactions. Routes to the correct contract method based on transition type and channel status.
- **Low-Level Operations**: Direct RPC access for app sessions, session keys, queries, and custom flows.

```mermaid
sequenceDiagram
participant App
participant SDK
participant Node as Clearnode
participant Node as Nitronode
participant Chain as Blockchain

App->>SDK: deposit(chain, asset, amount)
Expand All @@ -46,4 +49,4 @@ sequenceDiagram

- **New TypeScript projects**: Use [`@yellow-org/sdk`](./typescript/getting-started) directly.
- **Migrating from v0.5.3**: Use [`@yellow-org/sdk-compat`](./typescript-compat/overview) to minimise code changes, then migrate to the main SDK at your own pace.
- **Go projects**: Use the [Go SDK](./go/getting-started) — it has full feature parity with the TypeScript SDK.
- **Go projects**: Use the [Go SDK](./go/getting-started) for backend services and CLI tooling.
61 changes: 38 additions & 23 deletions docs/nitrolite/build/sdk/migration-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,28 @@ import TabItem from '@theme/TabItem';

# Migration Guide

If you are coming from an earlier version of VirtualApp, you will need to account for the following breaking changes.
If you are coming from an earlier version of VirtualApp, first choose the migration surface:
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update here and ensure we don't have "VirtualApp" term throughout docs - it should be Nitrolite.

Suggested change
If you are coming from an earlier version of VirtualApp, first choose the migration surface:
If you are coming from an earlier version of the Nitrolite protocol, first choose the migration surface:


- If you're using `@yellow-org/sdk-compat`, use this page for legacy protocol semantics and the [compat overview](./typescript-compat/overview) for the codemod workflow.
- If you're going straight to `@yellow-org/sdk`, use this page as a semantics checklist, then implement new code with the native [TypeScript SDK guide](./typescript/getting-started).

The `@yellow-org/nitrolite-codemod` package is planned for npm. Until it publishes, the [compat overview codemod workflow](./typescript-compat/overview) shows how to clone the source repo, build the CLI, scan your app, and apply the migration transforms. It rewrites package imports, updates dependencies, and leaves `TODO [codemod]` markers where a native v1 decision is required.

## What semantics changed

Amount units are the most important migration boundary:

- If you're using `@yellow-org/sdk-compat`, channel transfers use raw asset-unit strings, such as `'5000000'` for 5 USDC with 6 decimals. See the amount-units table in the [compat overview](./typescript-compat/overview).
- If you're updating app-session allocations, keep human-decimal strings in the allocation payloads because app state is signed and shared by participants.
- If you're going straight to `@yellow-org/sdk`, use `Decimal` values for native v1 calls such as `deposit()`, `withdraw()`, `transfer()`, and app-session allocation amounts.

## 0.5.x Breaking changes

If you're using `@yellow-org/sdk-compat`, treat the snippets in this section as legacy-shape examples to compare with your current app. If you're going straight to `@yellow-org/sdk`, use the native SDK pages for replacement code.

The 0.5.x release includes fundamental protocol changes affecting session keys, channel operations, state signatures, and channel resize rules. The main objective of these changes is to enhance security, and provide better experience for developers and users by ability to limit allowances for specific applications.

**Not ready to migrate?** Unfortunately, at this time Yellow Network does not provide ClearNodes running the previous version of the protocol, so you will need to migrate to the latest version to continue using the Network.
**Not ready to migrate?** Unfortunately, at this time Yellow Network does not provide Nitronode instances running the previous version of the protocol, so you will need to migrate to the latest version to continue using the Network.

### Protocol Changes

Expand All @@ -26,15 +41,15 @@ These protocol-level changes affect all implementations and integrations with th

Session keys now have enhanced properties that define their access levels and capabilities:

- **Application field**: Determines the scope of session key permissions. Setting this to an application name (e.g., "My Trading App") grants application-scoped access with enforced allowances. Setting it to "clearnode" grants root access equivalent to the wallet itself.
- **Application field**: Determines the scope of session key permissions. Setting this to an application name (e.g., "My Trading App") grants application-scoped access with enforced allowances. Legacy root-access examples may use a broker-specific root marker because that is what older protocol versions expected.

- **Allowances field**: Defines spending limits for application-scoped session keys. These limits are tracked cumulatively across all operations and are enforced by the protocol.

- **Expires_at field**: Uses a bigint timestamp (seconds since epoch). Once expired, session keys are permanently frozen and cannot be reactivated. This is particularly critical for root access keys (application set to "clearnode") - if they expire, you lose the ability to perform channel operations.
- **Expires_at field**: Uses a bigint timestamp (seconds since epoch). Once expired, session keys are permanently frozen and cannot be reactivated. This is particularly critical for legacy root access keys: if they expire, you lose the ability to perform channel operations.

#### Channel Creation: Separate Create and Fund Steps

Clearnode no longer supports creating channels with an initial deposit. All channels must be created with zero balance and funded separately through a resize operation. This two-step process ensures cleaner state management and prevents edge cases in channel initialization.
Nitronode no longer supports creating channels with an initial deposit. All channels must be created with zero balance and funded separately through a resize operation. This two-step process ensures cleaner state management and prevents edge cases in channel initialization.

#### State Signatures: Wallet vs Session Key Signing

Expand Down Expand Up @@ -96,13 +111,13 @@ Implementing the new session key protocol changes:
```

</TabItem>
<TabItem value="root" label="Root Access (Clearnode)">
<TabItem value="root" label="Root Access (legacy)">

```typescript
const authRequest = {
address: '0x...',
session_key: '0x...',
application: 'clearnode', // Special value for root access
application: '<legacy-root-application>', // Legacy special value for root access
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The substitution replaces 'clearnode' with a placeholder without explanation. Developers auditing existing apps won't know whether their current value matches. Add an inline comment: // The legacy root-access value was 'clearnode'; check your broker docs if you used a custom value.

allowances: [], // Not enforced for root access
scope: 'app.create',
expires_at: BigInt(Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60) // Long expiration recommended
Expand All @@ -113,7 +128,7 @@ Implementing the new session key protocol changes:
</Tabs>

**Important considerations:**
- Root access keys (application: "clearnode") cannot perform channel operations after expiration
- Root access keys that use a legacy root-application marker cannot perform channel operations after expiration
- Plan expiration times based on your operational needs
- Application-scoped keys track cumulative spending against allowances

Expand Down Expand Up @@ -167,7 +182,7 @@ await client.resizeChannel({

#### Resize correctly

Channel resizing must be negotiated with the ClearNode through WebSocket. Use `resize_amount` and `allocate_amount` with correct sign convention (`resize_amount = -allocate_amount`) and help users with non-zero channel balances migrate by resizing to zero or reopening channels.
Channel resizing must be negotiated with Nitronode through WebSocket. Use `resize_amount` and `allocate_amount` with correct sign convention (`resize_amount = -allocate_amount`) and help users with non-zero channel balances migrate by resizing to zero or reopening channels.

Channel resize can be requested as follows:

Expand All @@ -179,7 +194,7 @@ const resizeMessage = await createResizeChannelMessage(messageSigner, {
funds_destination: walletAddress,
});

const resizeResponse = {}; // send the message and wait for Clearnode's response
const resizeResponse = {}; // send the message and wait for Nitronode's response

const { params: resizeResponseParams } = parseResizeChannelResponse(resizeResponse);
const resizeParams = {
Expand Down Expand Up @@ -272,9 +287,9 @@ const types = {
};
```

### ClearNode API
### Nitronode RPC

You should read this section only if you are using the ClearNode API directly.
You should read this section only if you are using the Nitronode RPC API directly.

#### Update Authentication

Expand All @@ -301,14 +316,14 @@ Use the new session key parameters with proper `application`, `allowances`, and
```

</TabItem>
<TabItem value="root" label="Root Auth (Clearnode)">
<TabItem value="root" label="Root Auth (legacy)">

```json
{
"req": [1, "auth_request", {
"address": "0x1234567890abcdef...",
"session_key": "0x9876543210fedcba...",
"application": "clearnode",
"application": "<legacy-root-application>",
"allowances": [],
"scope": "app.create",
"expires_at": 1750659456789
Expand Down Expand Up @@ -398,9 +413,9 @@ Response:

## 0.3.x Breaking changes

The 0.3.x release includes breaking changes to the SDK architecture, smart contract interfaces, and Clearnode API enhancements listed below.
The 0.3.x release includes breaking changes to the SDK architecture, smart contract interfaces, and Nitronode RPC enhancements listed below.
Comment on lines 414 to +416
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should NOT have 0.3.0 breaking changes at all for the v1 protocol version. The latest v0.5 migration guide is enough.


**Not ready to migrate?** Unfortunately, at this time Yellow Network does not provide ClearNodes running the previous version of the protocol, so you will need to migrate to the latest version to continue using the Network.
**Not ready to migrate?** Unfortunately, at this time Yellow Network does not provide Nitronode instances running the previous version of the protocol, so you will need to migrate to the latest version to continue using the Network.

### VirtualApp SDK

Expand Down Expand Up @@ -445,7 +460,7 @@ const stateSigner = new SessionKeyStateSigner('0x...' as Hex);

The `CreateChannelParams` interface has been fully restructured for better clarity.

You should use the new [`CreateChannel` ClearNode API endpoint](#added-create_channel-method) to get the response, that fully resembles the channel creation parameters.
You should use the new [`CreateChannel` Nitronode RPC endpoint](#added-create_channel-method) to get the response, that fully resembles the channel creation parameters.

```typescript
// remove-start
Expand Down Expand Up @@ -590,7 +605,7 @@ const sig: Signature = '0x...';

#### Added: Pagination Types and Parameters

To support pagination in ClearNode API requests, new types and parameters have been added.
To support pagination in Nitronode RPC requests, new types and parameters have been added.

For now, only `GetLedgerTransactions` request has been updated to include pagination.

Expand All @@ -605,15 +620,15 @@ export interface PaginationFilters {
}
```

### Clearnode API
### Nitronode RPC

You should read this section only if you are using the ClearNode API directly, or if you are using the VirtualApp SDK with custom ClearNode API requests.
You should read this section only if you are using the Nitronode RPC API directly, or if you are using the VirtualApp SDK with custom Nitronode RPC requests.

#### Actions: Structured Request Parameters

ClearNode API requests have migrated from array-based parameters to structured object parameters for improved type safety and API clarity.
Nitronode RPC requests have migrated from array-based parameters to structured object parameters for improved type safety and API clarity.

Update all your ClearNode API requests to use object-based parameters instead of arrays.
Update all your Nitronode RPC requests to use object-based parameters instead of arrays.

```json
{
Expand Down Expand Up @@ -952,4 +967,4 @@ The contracts automatically detect and verify the appropriate signature format:
- **EIP-1271**: Smart contract wallet signatures
- **EIP-6492**: Signatures for undeployed contracts

No changes are needed in your contract calls - the signature verification is handled automatically by the contract.
No changes are needed in your contract calls - the signature verification is handled automatically by the contract.
Loading
Loading