nitrolite

README

Nitrolite: State Channel Framework

Nitrolite is a lightweight, efficient state channel framework for Ethereum and other EVM-compatible blockchains, enabling off-chain interactions while maintaining on-chain security guarantees.

Overview

Nitrolite is a complete state channel infrastructure consisting of several main components:

1. Smart Contracts: On-chain infrastructure for state channel management (ChannelHub, ChannelEngine).
2. Clearnode: A broker providing ledger services and off-chain state management.
3. Go SDK: Comprehensive Go library for building backend and CLI applications.
4. TypeScript SDK: Client-side library for building web and mobile applications.
5. Cerebro (CLI): Interactive command-line interface for managing channels and assets.

Key Benefits

• Instant Finality: Transactions settle immediately between parties off-chain.
• Reduced Gas Costs: Most interactions happen off-chain, with minimal on-chain footprint.
• High Throughput: Support for thousands of transactions per second.
• Security Guarantees: Same security as on-chain, backed by cryptographic proofs and challenge periods.
• Chain Agnostic: Works with any EVM-compatible blockchain.

Project Structure

This repository contains:

• /contracts: Solidity smart contracts for the state channel framework.
• /clearnode: Implementation of the Clearnode service.
• /sdk/go: Official Go SDK.
• /sdk/ts: Official TypeScript SDK.
• /cerebro: Clearnode CLI tool.
• /pkg: Shared Go packages (core state machine, signing, etc.).
• /docs: Protocol specifications and architectural documentation.

Protocol

Nitrolite implements a state channel protocol that enables secure off-chain communication with minimal on-chain operations. The protocol includes:

• Channel Creation: A funding protocol where participants lock assets in the ChannelHub.
• Off-Chain Updates: A mechanism for exchanging and signing versioned state updates off-chain.
• Channel Closure: Multiple resolution paths including cooperative close and unilateral challenge-response.
• Checkpointing: The ability to record valid states on-chain without closing the channel.
• App Sessions: Support for multi-participant application sessions with arbitrary logic.
• Session Keys: Delegated signing authority for automated or restricted operations.

See the protocol description for complete details.

Smart Contracts

The Nitrolite contract system (built with Foundry) provides:

• ChannelHub: The central entry point for all channel operations.
• ChannelEngine: Logic for state verification and transition validation.
• Escrow Engines: Specialized logic for cross-chain deposits and withdrawals.
• SigValidators: Pluggable signature validation modules (e.g., Session Keys).

Deployments

For the most up-to-date contract addresses on all supported networks, see the contract deployments directory.

See the contract README for detailed contract documentation.

Clearnode

Clearnode is a message broker and state manager that enables efficient off-chain payment channels.

Features

• Multi-Chain Support: Connect to multiple EVM blockchains (Polygon, Celo, Base, etc.).
• Off-Chain Payments: High-throughput transfers with near-zero latency.
• App Sessions: Manage complex multi-party application states.
• Flexible Storage: Support for SQLite (embedded) and PostgreSQL.
• Quorum-Based Signatures: Weight-based quorum requirements for state updates.

See the Clearnode Documentation for more details.

SDKs

Go SDK

The official Go SDK for building performant backend integrations or CLI tools.

go get github.com/layer-3/nitrolite/sdk/go

See SDK Go README.

TypeScript SDK

The official TypeScript SDK for web-based applications.

npm install @layer-3/nitrolite

See SDK TS README.

Cerebro (CLI)

Interactive CLI for interacting with Clearnode.

# From the root directory
go build -o nitrolite-cli ./cerebro
./nitrolite-cli wss://node.example.com/ws

See Cerebro README.

Quick Start with Docker Compose

Get started quickly with the local development environment:

# Start the environment
docker-compose up -d

# This will:
# 1. Start a local Anvil blockchain on port 8545
# 2. Deploy core Nitrolite contracts
# 3. Seed test tokens and configuration
# 4. Start the Clearnode service.

Development

# Run contract tests
cd contracts && forge test

# Run Go tests (requires GOCACHE redirection if restricted)
export GOCACHE=/tmp/gocache && go test ./...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.