Release v1.2.0

This release introduces the App Registry, Gated Actions with staking-based allowances, Security Token Locking contracts integration, new observability metrics, Cerebro tool and example apps improvements, and several smart contract fixes for unhappy-path scenarios.

---

Changelog

Features

• App Registry — Register apps with owner signature, per-app approval settings, app versioning, and listing with pagination (#597)
• Gated Actions — Action gateway enforcing per-action 24h allowances that scale with staked tokens and app count; CLI commands to view allowances and manage registry (#601)
• Security Token Locking Integration — Lock, relock, unlock, withdraw, approve, and balance queries across chains; new CLI commands for security token management; per-chain locking contract config in Go/TS SDKs (#606)
• Cerebro Tool — Updated Cerebro tool includes improved wallet configuration, new methods and fixes a bug on start without a configured wallet.
• New Metrics — Lifespan metrics storage, total-value-locked metric, active-user/app-session metrics with day/week/month windows; new indexes for faster aggregation (#605)
• Basic Rate Limits — Introduce basic rate limiting for Clearnode to prevent DoS attacks (#600)
• DeployChannelHub Script — Forge script for deploying ChannelHub contracts (3988714)
• Updated TS SDK Example App — Includes demo of the new features and UI improvements.
• Updated App Session Lifecycle Scripts (Go & TS) — Integration scripts demonstrating end-to-end app session lifecycle via Go & TS SDKs.
• Updated Compat SDK — Compat SDK is now reconciled with @yellow-org/sdk v1.2.0. No breaking changes: drop-in upgrade from 1.1.x. README and docs website updated with method cheat sheets and usage examples.

Bug Fixes

• ChannelHub unhappy paths — Fix home-chain unhappy-path flows and add comprehensive tests (#599)
• Compat SDK — OngoingStateTransitionError export + classifyError detection, Blockchain list caching, amount validation on locking methods

Infrastructure & Docs

• Rename erc7824 org to layer-3 and remove legacy erc7824 docs (#603)
• Clearnet V1 Sandbox Deployment (#608)
• SDK Documentation Updates: Expanded Go SDK and TypeScript SDK READMEs with additional examples, API documentation, and usage patterns.
• Dependencies: Bump go-ethereum 1.17.0 → 1.17.1, opentelemetry-go 1.40.0 → 1.41.0, @yellow-org/sdk >=1.2.0.

Clearnet V1 Sandbox Deployment

The new Clearnet V1 Sandbox deployment is available at wss://clearnode-sandbox.yellow.org/v1/ws.

• Cerebro, Go/TS SDKs, and sdk/ts/examples/example-app can be used to start developing with the new sandbox testing environment.

Breaking Changes

• Applications are now required to be registered on a Node to operate (#597)

Migration Guide

• Starting with this release, all apps must be registered on a Node to operate.
• To ease migration, there is a default app registered on Clearnode with limited action allowances shared among developers. To use it, specify application_id as default in the app session creation request.
• Developers are strongly advised to register their own apps on a Clearnode for full control over action allowances. App registration happens only once and requires locking security tokens in a locking contract. Based on the amount locked by an app owner, each application receives a daily operations allowance. An app can be registered via the Cerebro tool, sdk/ts/examples/example-app, or via RegisterApp SDK method. See sdk/ts/examples/app-sessions and sdk/go/examples/app-sessions for examples.
• To lock security tokens, you can use the Go or TypeScript SDK EscrowSecurityTokens method, the Cerebro tool, or sdk/ts/examples/example-app. Make sure to call ApproveSecurityToken first.
• At the time of this release, the Yellow token on ETH Sepolia Testnet can be used as a security token. Use the Faucet to obtain test tokens. With the public release of the Yellow Token on Ethereum Mainnet, it will be required to lock Yellow Tokens on the mainnet contract.

Release v1.1.1

This patch release migrates the TypeScript SDKs from the @erc7824 npm scope to the @yellow-org organization, establishing a unified package identity under the Yellow brand.

Changelog

TypeScript SDK

• Package Rename: The TypeScript SDK has been renamed from @erc7824/nitrolite to @yellow-org/sdk. All functionality remains identical - this is purely a namespace migration.
• Compatibility Package Rename: The compatibility layer has been renamed from @erc7824/nitrolite-compat to @yellow-org/sdk-compat.
• Updated Dependencies: Internal references and peer dependencies updated to reflect the new package names.

Migration Guide

For projects using the previous package names, update your dependencies:

- "@erc7824/nitrolite": "^1.1.0"
+ "@yellow-org/sdk": "^1.1.1"

- "@erc7824/nitrolite-compat": "^1.1.0"
+ "@yellow-org/sdk-compat": "^1.1.1"

Update your imports:

- import { NitroliteClient } from '@erc7824/nitrolite';
+ import { NitroliteClient } from '@yellow-org/sdk';

- import { NitroliteClient } from '@erc7824/nitrolite-compat';
+ import { NitroliteClient } from '@yellow-org/sdk-compat';

No API changes are required - only the package names have changed.

Release v1.1.0

This release builds on the V1 foundation with production-ready TypeScript SDKs: @yellow-org/sdk (sdk/ts) with full feature parity alongside the Go SDK, and @yellow-org/sdk-compat (sdk/ts-compat) - a compatibility layer wrapping the v1 SDK behind the v0.5.3 API surface, reducing migration effort from hundreds of lines to ~15 lines for applications built on v0.x.x. Additional enhancements include native token support, operational tooling improvements, and smart contract resilience.

Changelog

Smart Contracts

• Native Token Support: Extended ChannelHub and Utils contracts to handle native tokens (ETH) alongside ERC-20 tokens, enabling deposits and withdrawals in native currency.
• Reclaim Logic for Failed Transfers: Outbound transfer failures no longer revert the transaction. Failed amounts are recorded as reclaimable balances and can be claimed to alternative destinations. Transfers now run with an explicit gas limit to mitigate gas-depletion attacks.
• Gas and Size Optimizations: Improved internal handling of channel challenge logic for cleaner, more consistent state reads while reducing contract size and gas consumption.

Clearnode

• Prometheus Metrics: Comprehensive metrics exporter providing visibility into RPC operations, channel states, app sessions, and system health. Metrics are exposed via a configurable endpoint for Prometheus scraping.
• GCP KMS Signer: Added Google Cloud Platform Key Management Service signing backend with DER-to-Ethereum signature conversion. Supports signer_type configuration ("key" or "gcp-kms") with Helm chart integration for service account credentials.
• Stress-Testing Tool: New clearnode/stress package providing load testing capabilities for Clearnode deployments. Includes configurable concurrency, app session lifecycle testing, transfer stress tests, and detailed performance reporting. Helm chart includes stress test pod templates.
• Dynamic Limits Validation: Configurable validation limits for app session operations, allowing operators to tune request size constraints based on deployment requirements.
• Native WebSocket Ping: Switched to server-driven ping/pong with configurable PingTimeout, improving connection liveness detection and resilience.
• channels.v1.get_channels Endpoint: New RPC method to list all channels (open, closed, challenged) for a wallet, with status/asset filtering and pagination support.

Go SDK

• Native Token Operations: Added DepositNative() and WithdrawNative() methods to the channel interface for native token (ETH) deposits and withdrawals.
• WebSocket Improvements: Updated connection handling with server-driven ping/pong and configurable PingTimeout replacing the previous PingInterval.

TypeScript SDK

• Compatibility Package (@yellow-org/sdk-compat): New compatibility layer wrapping the v1 TypeScript SDK behind the v0.5.3 API surface, reducing migration effort from ~400 lines to ~15 lines for existing applications.
• Native Token Support: Extended EVMBlockchainClient with native token deposit and withdrawal capabilities, mirroring Go SDK functionality.
• Example App Overhaul: Replaced react-demo with improved example-app featuring a comprehensive WalletDashboard component with better UX for channel and app session management.
• Connection Improvements: Removed client-side periodic pings in favor of server-driven keepalive mechanism.

Cerebro

• Native Token Commands: Extended CLI commands to support native token operations alongside ERC-20 tokens.
• Cosmetic Fixes: Various UI/UX improvements to the interactive REPL.

Documentation

• SDK Documentation Updates: Expanded Go SDK and TypeScript SDK READMEs with additional examples, API documentation, and usage patterns.
• Security Documentation: Updated protocol and security docs to describe transfer resilience, reclaim patterns, and gas mitigation strategies.

Dependencies

• Bumped go-ethereum from 1.16.8 to 1.17.0
• Bumped google.golang.org/api from 0.265.0 to 0.269.0
• Bumped viem from 2.38.6 to 2.44.4
• Various npm dependency updates for security and compatibility

Release v1.0.0

This release marks the V1 milestone for Nitrolite, introducing a completely redesigned protocol architecture that drastically enhances security, stability, manageability, and modularity across all system components.

Changelog

Documentation

• Added comprehensive V1 Clearnode Specifications including architecture design, data models, RPC message format, and communication flows for deposits, withdrawals, transfers, and channel lifecycle operations.
• Added Security Properties documentation with formal invariants covering channel identity, state validity, liquidity accounting, challenge mechanisms, and cross-chain safety guarantees.
• Added Signature Validators documentation describing the pluggable validation system, validator registry, and security considerations.

Smart Contracts

• Introduced ChannelHub with a unified engine approach, replacing fragmented contract logic with a single, auditable entry point for all channel operations.
• Implemented pluggable signature validation system via ISignatureValidator interface, enabling flexible authorization schemes (ECDSA, session keys, multi-sig) without protocol modifications.
• Added per-node validator registry with approved validators bitmask, preventing signature forgery while maintaining cross-chain compatibility.
• Implemented cross-chain escrow infrastructure with deposit and withdrawal engines, enabling secure multi-chain state transitions.
• Added challenge mechanism with formal invariants ensuring latest-state dominance and deterministic enforcement.
• Introduced version monotonicity and channel uniqueness guarantees embedded in the protocol design.

Project Structure

The project now has six main directions:

• contracts/ - Solidity smart contracts built with Foundry, including ChannelHub, escrow engines, and signature validators (see Smart Contracts section above).

• pkg/ - Core Go packages providing foundational protocol primitives:

  • pkg/core - State management, transitions, channel signing, and type definitions
  • pkg/rpc - NitroRPC V1 messaging, WebSocket client/server, and connection handling
  • pkg/app - App session types and session key management
  • pkg/sign - Cryptographic signing utilities (EthereumMsgSigner, EthereumRawSigner)

• sdk/go/ - Comprehensive Go SDK (see Go SDK section below)

• sdk/ts/ - TypeScript SDK providing feature parity with Go SDK, still a work in progress (see TypeScript SDK section below)

• clearnode/ - Clearnode node implementation (see Clearnode section below)

• cerebro/ - Cerebro REPL, now a first-class project component providing an interactive CLI for Clearnode operations, wallet management, and session key handling.

Clearnode

• Stateless Architecture: Clearnode is now fully stateless, storing no session data in memory. All state is persisted to the database, enabling horizontal scaling - adding more instances is purely a matter of infrastructure.
• Signature-Based Authorization: Removed traditional session-based authentication. Every write request must now include cryptographic signature(s) that authorize the operation, providing stronger security guarantees and eliminating session management complexity.
• Versioned Endpoint Groups: API methods are now organized into versioned groups (e.g., app_sessions.v1.submit_session_key_state). This design enables introducing new endpoint versions without breaking existing integrations - clients can migrate at their own pace.
• Store Adapters: Provides flexible data persistence with support for multiple backends.

Go SDK

The Go SDK (sdk/go/) is essentially a new addition - previously only an RPC client existed. V1 introduces a comprehensive SDK with:

• Unified Client API: Single client providing both high-level operations (Deposit, Withdraw, Transfer, CloseHomeChannel, Acknowledge) and low-level RPC access.
• Two-Step State Pattern: Build and co-sign states off-chain, then settle on-chain via Checkpoint() - the single entry point for all blockchain transactions.
• App Session Management: Full support for creating, depositing, operating, rebalancing, and closing app sessions.
• Session Keys: Build, sign, submit, and query session key states with scoped permissions.
• Channel Lifecycle: Complete support for channel creation, checkpointing, challenges, and closure.

See the full Go SDK documentation.

TypeScript SDK

The TypeScript SDK (sdk/ts/) provides feature parity with the Go SDK:

• High-Level Operations: deposit(), withdraw(), transfer(), closeHomeChannel() with automatic state management.
• Signer Implementations: EthereumMsgSigner for channel states, EthereumRawSigner for blockchain transactions.
• Full Low-Level Access: All RPC methods available on the same client instance.

Note: The TypeScript SDK is still a work in progress. While core functionality is complete, additional features and improvements will follow in upcoming releases.

See the full TypeScript SDK documentation.

v0.5.0

This release introduces enhanced security features, improved app session management, and critical infrastructure updates for the Clearnode API and Nitrolite SDK.

Changelog

Documentation

• Added the v0.5.0 Migration Guide.
• Added a huge and incredibly fruitful Protocol section, providing detailed specifications for the current protocol version.
• Added instructions on how to request a blockchain and an asset support.
• As always, the up-to-date Clearnode API documentation can be found in the API docs of the ClearNode.

Nitrolite SDK

• Added a support for new revoke_session_key and get_session_keys endpoints
• Modified the Authorization structure
• Added a conditional mechanism to choose channel state signer based on the channel participant.
• Fixed EIP712 signature types to properly support float amounts, ensuring accurate transaction processing.
• Upgraded viem dependency through multiple security patches (from 2.37.6 to 2.38.5) for improved security and stability.

Clearnode

• Added app session keys with allowances and expiration functionality for granular access control.
• Implemented session keys revocation mechanism, allowing users to invalidate compromised or unused session keys.
• Enhanced authentication flow to avoid creating duplicate session keys when one already exists.
• Wallet address is now used as channel and app-session participant to improve consistency
• Added non-replayable transfer mechanism to prevent transaction replay attacks.
• Enabled zero deposit channel creation for improved user onboarding.
• Introduced restrictions on off-chain operations for users with non-zero channels to improve security.
• Added escrow mechanism for channel resize operations.
• Streamlined blockchain and asset configuration for easier management.
• Fixed asset validation to properly skip empty assets in app allocations.
• Extended Cerebro CLI functionality for better administrative capabilities.

v0.4.0

This release introduces the NitroRPC/0.4 protocol version with enhanced app session management, expanded network support, and improved infrastructure components for the Clearnode API.

Changelog

Nitrolite SDK

• Introduced NitroRPC/0.4 protocol version for improved communication between clients and servers.
• Added support for app session deposits and withdrawals, enabling more flexible fund management within active sessions.
• Implemented app protocol enforcement to ensure consistent behavior across different client implementations.
• Upgraded critical dependencies including viem (2.24.1 → 2.37.6) and zod (3.25.67 → 3.25.76) for improved security and performance.
• Updated SDK version to 0.4.0 to reflect the major protocol enhancements.

Clearnode

• Implemented app protocol enforcement: developers can no longer use the protocol field inside app sessions as custom values. Only two protocol versions are now supported: NitroRPC/0.2 (maintains the same app sessions functionality as before) and NitroRPC/0.4 (introduces new functionality).
• Introduced NitroRPC/0.4 protocol version with support for app session deposits and withdrawals, enabling dynamic fund management during active sessions. When using this protocol version, two new required fields must be specified: version and intent.
• Enabled Flow and XRPL EVM network support on production, expanding the platform's blockchain compatibility.
• Exported RPC node, client, and dialer implementations in a public package for external integrations.
• Introduced comprehensive infrastructure improvements:
  • Chain-agnostic signing package for multi-blockchain support
  • Dedicated logging package for better debugging and monitoring
  • RPC protocol package for standardized communication
  • User action log store for audit trails and analytics
• Patched a security vulnerability when it was possible to challenge the channel with an older state. Clearnode now listens to such events and checkpoints with a newer valid state.
• Added docker-compose configuration for simplified local development setup.
• Upgraded to Go 1.25 and updated multiple dependencies for improved performance and security.

The v0.4.0 API documentation can be found in the API docs of the ClearNode.

v0.3.0

This release focuses on streamlining channel creation, improving API consistency, and adding support for modern signature standards.

Changelog

Nitrolite SDK

• Replaced an optional NitroliteClient stateWalletClient field with a required StateSigner interface to handle state signing operations (via signState(channelId, state)).
• Added WalletStateSigner (using viem's WalletClient) and SessionStateSigner (using raw private key account) classes to provide convenient implementations of the StateSigner interface.
• Updated CreateChannel(...) method parameters to support the improved channel creation flow.
• Standardized the request types in all Clearnode API methods, so that now params is an object instead of an array. This improves type safety and clarity.
• Standardized CreateChannel, CloseChannel, and ResizeChannel method response types.
• Changed the Signature type from {r, s, v} struct to Hex.
• Added pagination types and parameters for requests to ClearNode pagination-supporting endpoints.

Clearnode API

• Added create_channel method to facilitate the improved, single-transaction channel opening flow. The response includes the Channel and State structs, alongside with the serverSignature for the initial state.
• Standardized the request structure in all Clearnode API methods, so that now params is an object instead of an array. This improves type safety and clarity.
• Standardized create_channel, close_channel, and resize_channel method responses.
• Added metadata struct to the get_channels, get_app_sessions, get_ledger_entries, and get_ledger_transactions method responses to provide additional pagination information: current page, number of items per page, total pages, and total items.

The v0.3.0 API documentation can be found in the API docs of the ClearNode.

Smart Contract

• Channels can now become operational immediately after the create(...) method call if all participant signatures are provided. In such case, the funds of all participants other than thee sender ("creator") are transferred from the respective address specified in participants array.
• Changed the Signature type from {r, s, v} struct to bytes.
• Added EIP712AdjudicatorBase to support EIP-712 typed structured data signatures in Adjudicator contracts.
• Added support for EIP-191, EIP-712, EIP-1271, and EIP-6492 signatures.